Creating and Using Geometry Instances

Introduction

A geometry definition is a shared geometry that can have several geometry instances in the same or different features. A geometry instance consists of a geometry definition reference, a placement location, and a 3D affine matrix. Geometry definitions may contain any type of geometry, including instances of other geometry definitions.

Geometry instances are useful for complex geometries where many copies of the same object are required. For instance, in a visualization of a city, many copies of the same park bench may be used in different locations.

If a single geometry definition is used, with many geometry instances, the overall file size, processing required, and effort to display the geometry is greatly reduced than if many copies of the same geometry are used. This is especially true if the geometry instance is very large or detailed.

With a single geometry definition, it is also possible to easily modify only the geometry definition, and subsequently, update all instances of that definition without needing to modify every instance. For example, if a user wishes to change the park bench from red to blue, a modification can be made to the geometry definition only, and it will subsequently be reflected in all geometry instances.

Examples

Example 1: Replace Points with Models

In the following example, using makeinstances.fmw, we will replace a set of lamp post location points with an instance of an actual model of a lamp post. The model was obtained from the Sketchup 3D Warehouse.

Preparing the Data

Reading in pole point FME Feature Store data and a Sketchup Model of a lamp post

From the location points, we need to extract the coordinate system (with the CoordinateSystemExtractor) and the location (with the CoordinateExtractor). The pole locations have an attribute containing the pole rotation.

The 3D warehouse model is not centered at 0,0,0, nor is it facing the right way, so we center and align it with the Offsetter and Rotator, then convert the units to meters with the Scaler.

Creating the Instances

Merging the two datasets together using shared_id and setting the geometry to shared Pole

In FME, the geometry instances are stored within the shared item library. We add geometries to the shared item library with the SharedItemAdder transformer.

SharedItemAdder parameters

The SharedItemAdder can be used to add appearances or geometries to the Shared Item library, so we set the Item to Add to Geometry Definition. We are adding a new definition, so we set the Insert Mode to Add New Item. The shared item ID assigned to the new instance will be added to the attribute _shared_item_id.

In order to replace the points with the instances, we need to provide them with the newly shared item ID. We can do this using a FeatureMerger with the Join on values set to 1, instead of feature attributes. This will merge the shared item id on all the points, even though they have no common attributes with the instance.

FeatureMerger Parameters, set the Requestor to 1 and the Supplier to 1

Now that the points all have shared item IDs, we can use a SharedItemIDSetter to actually set their geometry to an instance of that shared item.

SharedItemIDSetter Parameters, set the Shared Item ID Attribute to _shared_item_id

Item Type should be set to Geometry Definition. We are setting the instance on simple points, so the Geometry Part Selection can be left as is, but if you have a more complex source geometry, you can use Geometry XQueries to determine which part of the geometry should be replaced with the instance.

Set Retrieve Shared Item ID to From Attribute, then set Share Item ID Attribute to _shared_item_id.

Rotate the lamp post, ensure the coordinate system is correct, then write out to Sketchup.

The SharedItemIDSetter will place the model at the same location as the point, but we still need to apply the streetlight rotation with a Rotator. In the Rotator settings, use the _x and _y attributes created by the CoordinateExtractor to set the X Origin and Y Origin for the rotation.

Finally, we will apply the point coordinate system we extracted earlier to the new instance geometries, before writing out to Sketchup.

Result

Results viewed in Sketchup where a lamp post represents a single lamp post point

Sketchup supports instanced geometry as shared components, so you can create a relatively small file that contains hundreds of streetlights.

Example 2: Update the Model by ID

In this example, using updateinstance2.fmw, we want to replace the wooden street lights with some snazzier ones (also from the Sketchup 3D Warehouse). We will do this by updating the model in the shared item library, instead of changing each pole instance.

Updating the Item ID

Workflow for updateinstance2.fmw, updating an existing model with new street light styles

From the input Sketchup file, we will extract the shared item id of the original pole, and merge this onto the scaled and aligned new light pole model.

SharedItemIDExtractor Parameters, extract the Shared Item ID as Attribute

We will set the Item Type to Geometry Definition, and extract the shared item ID to an attribute. Since there may be more than one instance in the feature geometry, the shared item IDs will be stored in a list attribute: _shared_item_id{}. This list will be merged onto the new model by the FeatureMerger.

This time we will use the SharedItemAdder in the update mode.

SharedItemAdder Parameters, set the Insert Mode to Replace Existing Item and the Shared Item ID to Replace to _shared_item_id{0}

Set Item to Add to Geometry Definition and Insert Mode to Replace Existing Item. The ID to replace will be set to the first element of the _shared_item_id{} list. This works OK in our example since the model only contains a single instance definition. If you have several shared items in your data, you can use a Geometry XQuery in the ShareItemIdExtractor to extract only the id of the shared item you want to update.

FME works on the input data sequentially, so to make sure that the source features are not written to the output before the Shared Item is updated, we will use the FeatureMerger output rather than a copy of the source feature to write to the output. The Supplier features will be output through the ports Referenced, Unreferenced, or DuplicateSupplier, depending on the number of source features. We will route all these output ports to the Sketchup writer.

Result

Results in Sketchup of the updated lamp styles.

We now have updated streetlights, in the same locations and alignments as the original.