AppearanceSetter

This input port is optional. If this input port is not used, only the values specified in the parameters of this transformer will be used.

Appearance style features coming in through this port will be applied to the front and/or back sides of geometries. The format of this feature should be precisely what exits the AppearanceExtractor or AppearanceStyler transformers.

It may have many optional attributes which express the color and/or texture parameters of the appearance. It must also have either a Raster geometry (which is understood to be the Raster texture to use) or a null geometry. The Style parameters in this transformer, if used, will override any values on these input features.

Features that contain some geometry on which an appearance may be set.

Using this input port is optional.

All features that enter this port are held back until this transformer has completed all its processing, and are then output through the Holder port at the very end. These features will not be directly modified in any way by this transformer, but may have been indirectly changed. Please read the documentation for the Replace Existing Definitions’ value for the ‘Appearance Storage’ option for details on how this may occur.

The reason these Holder ports are useful is that in some situations, it is important to control the timing of features passing through the workspace. By holding back some features, you are ensuring that this transformer has a chance to complete its processing before allowing some other features to continue further along the workspace.

Example

There are 100 features passing through the workspace, and they all contain some surfaces that refer to a “red brick” Appearance. Their natural flow would be directly out to a writer. However, in a separate section of the workspace, an AppearanceSetter exists, and it uses the Replace Existing Definitions option on the Appearance Storage parameter. It replaces the definition of the “red brick” Appearance with “brown brick”, obviously using a different color.

In this situation, if there is no explicit control over the order of features, the first 50 features could be inadvertently sent to the writer, followed by the AppearanceSetter processing, followed by the last 50 features being sent to the writer. Here, the output would contain 50 “red brick” features and 50 “brown brick” features. You would not be able to control the arbitrary ordering of features flowing through the workspace.

If, however, all 100 features are routed through the Holder port, it is guaranteed that the AppearanceSetter will do its processing before any of the 100 features are sent to the writer. In this case, the output would contain 100 “brown brick” features. This is probably the desired outcome: change the definition of one Appearance, make sure that definition is reflected throughout the entire dataset (without having to locate each reference to that modified appearance), and have the guarantee that all features reflect that change regardless of the order of the flow of input features.

All input Geometry features are output whether or not anything was changed.

All features that came in through the Holder input port will be output through this port. See the Holder input port for more details on correct usage of these ports.

Only appearance style features with null or raster geometry types are accepted. All other appearance style features are rejected.

If the Join parameters (described below) are not used, then only the first Appearance style input per group is used. All other extra Appearance styles are rejected and output through this port.

Rejected features will have an fme_rejection_code attribute with one of the following values: EXTRA_APPEARANCE_FEATURE, INVALID_APPEARANCE_GEOMETRY_TYPE, INVALID_GEOMETRY_GEOMETRY_TYPE.

Note that only the first appearance styles will be used in each "Group By" group.

Note: How parallel processing works with FME: see About Parallel Processing for detailed information.

This parameter determines whether or not the transformer should perform the work across parallel processes. If it is enabled, a process will be launched for each group specified by the Group By parameter.

Parallel Processing Levels

For example, on a quad-core machine, minimal parallelism will result in two simultaneous FME processes. Extreme parallelism on an 8-core machine would result in 16 simultaneous processes.

You can experiment with this feature and view the information in the Windows Task Manager and the Workbench Log window.

No: This is the default behavior. Processing will only occur in this transformer once all input is present.

By Group: This transformer will process input groups in order. Changes of the value of the Group By parameter on the input stream will trigger batch processing on the currently accumulating group. This will improve overall speed if groups are large/complex, but could cause undesired behavior if input groups are not truly ordered. Specifically, on a two input-port transformer, "in order" means that an entire group must reach both ports before the next group reaches either port, for the transformer to work as expected. This may take careful consideration in a workspace, and should not be confused with both port's input streams being ordered individually, but not synchronously.

Considerations for Using Input is Ordered By

Using Ordered input can provide performance gains in some scenarios, however, it is not always preferable, or even possible. Consider the following when using it, with both one- and two-input transformers.

Single Datasets/Feature Types: Are generally the optimal candidates for Ordered processing. If you know that the dataset is correctly ordered by the Group By attribute, using Input is Ordered By can improve performance, depending on the size and complexity of the data.

If the input is coming from a database, using ORDER BY in a SQL statement to have the database pre-order the data can be an extremely effective way to improve performance. Consider using a Database Readers with a SQL statement, or the SQLCreator transformer.

Multiple Datasets/Feature Types: Since all features matching a Group By value need to arrive before any features (of any feature type or dataset) belonging to the next group, using Ordering with multiple feature types is more complicated than processing a single feature type.

Multiple feature types and features from multiple datasets will not generally naturally occur in the correct order.

One approach is to send all features through a Sorter, sorting on the expected Group By attribute. The Sorter is a feature-holding transformer, collecting all input features, performing the sort, and then releasing them all. They can then be sent through an appropriate filter (TestFilter, AttributeFilter, GeometryFilter, or others), which are not feature-holding, and will release the features one at a time to the transformer using Input is Ordered By, now in the expected order.

The processing overhead of sorting and filtering may negate the performance gains you will get from using Input is Ordered By. In this case, using Group By without using Input is Ordered By may be the equivalent and simpler approach.

In all cases when using Input is Ordered By, if you are not sure that the incoming features are properly ordered, they should be sorted (if a single feature type), or sorted and then filtered (for more than one feature or geometry type).

As with many scenarios, testing different approaches in your workspace with your data is the only definitive way to identify performance gains.

Use this parameter if you want to isolate only a portion of the geometry passed in to the transformer. If no criteria are specified, the action will apply to the entire geometry at all levels.

Selection can be based on structural location, geometry name, type, appearance information, traits, trait storage types, or definition reference. The syntax used is a restricted set of XQuery, where the return clause is fixed.

The basic Geometry XQuery dialog allows you to construct simple selection queries by automatically writing the necessary query based on specified test clauses. Clicking the Switch to Advanced button opens the Advanced Editor, which allows you to type a query free-form, for more expressive queries.

Note: Once you switch to Advanced mode, you will have to clear all parameters before you can return to Basic mode.

A hierarchical geometry is represented as nodes of type geometry, with attributes containing information about traits, type, and name for each geometry.

You can specify which side of the geometry on which the appearance should be set.

Front Side: The texture will be applied to the front side of the geometry part only.

Back Side: The texture will be applied to the front side of the geometry part only.

Front and Back Sides: The texture will be applied to both sides of the geometry part.

Both of these parameters must be used together, or neither is used.

If you are not using these parameters, this transformer expects only one Appearance style feature (per Group) and it is used for all selected geometry parts.

If these join parameters are specified, all of the Appearance style features (per Group) are kept as possible matches for each individual selected geometry part. In each case, the value of the Trait specified on the geometry part is matched to the value of the Attribute specified on the Appearance style features. (If there is more than one match, an arbitrary Appearance style feature is chosen. If there is no match, no processing is done for that geometry part.) The matched Appearance style is then used for the processing of that geometry part.

Note: Note that a missing Trait on the geometry part, or a missing Attribute on the Appearance style features are equivalent to blank traits or attributes. Traits with blank values will match to Attributes with blank values. This will, for example, allow you to intentionally send in a “default” Appearance style feature without the join attribute, and use it for any geometry parts that may not have the trait present. This is useful if not all geometry parts are expected to have the join trait.

When you pass in Appearance style features, this transformer will be creating Appearance definitions. However, there are two ways these new appearances may be stored and used:

• Create New Definitions: This is the simplest approach. With this option, a new Appearance Definition is created and stored in the internal FMELibrary. This new definition is referenced by the selected geometry parts; references to previous definitions are dropped, leaving those definitions unchanged in the internal FMELibrary.
• Replace Existing Definitions: This approach is powerful and may change many things in the dataset very efficiently. With this option, a new Appearance Definition is not created, but instead, the link to every Appearance Definition which is referenced by the selected Geometry Parts is followed, and each of those definitions is overwritten within the internal FMELibrary.

This is reflected in two ways: First, all chosen geometry parts reflect the new Appearance style properties, even though they do not change how they reference Appearances. Second, a more subtle effect is that all geometry parts, on all active features (even those features not passing through this factory) that refer to the overwritten Appearance definitions will immediately see the new values as well.

This transformer can, therefore, modify the effective nature of some features that never pass through it. Please see the documentation for the HOLDER input and HOLDER output ports for more details on management of these effects.

A name that will help you remember what the appearance is for, such as "castle wall" or "house roof". Note that it does not have to be unique.

Attribute name string: fme_appearance_style_name

The most instinctive meaning of the color of an object, the essential color that is revealed under pure white light. It is perceived as the color of the object rather than a reflection of the light.

Attribute name string: fme_appearance_style_diffuse_color

The color that the object reflects when illuminated by color from the surrounding medium rather than direct light.

Attribute name string: fme_appearance_style_ambient_color

The color of the light reflected from the object through specular reflection (the type of reflection that is characteristic of light reflected from a shiny surface).

Attribute name string: fme_appearance_style_specular_color

Color of the light that the object is emitting itself.

Attribute name string: fme_appearance_style_emissive_color

A value from 0.0 to 1.0 that specifies the shine of specular reflection, with 0.0 being completely dull and 1.0 extremely shiny.

Attribute name string: fme_appearance_style_shininess

Specifies the transparency level of the appearance, with 0.0 being completely transparent and 1.0 completely opaque.

Attribute name string: fme_appearance_style_alpha

Used to specify the origin of texture coordinate system. It is only used in conjunction with scaling and rotation.

Attribute name string: fme_texture_style_center_u

Used to specify the origin of texture coordinate system. It is only used in conjunction with scaling and rotation.

Attribute name string: fme_texture_style_center_v

Specifies the counter-clockwise rotation angle of the texture in degrees around the texture center (from a line parallel to the u-axis, passing through the texture center).

Attribute name string: fme_texture_style_rotation_angle

Used to specify the amount of shear along the u texture coordinate system axis, relative to the center.

Attribute name string: fme_texture_style_u_shearing_factor

Used to specify the amount of shear along the v texture coordinate system axis, relative to the center.

Attribute name string: fme_texture_style_v_shearing_factor

Used to specify the amount that the texture should be scaled along the u-axis.

Attribute name string: fme_texture_style_u_scaling_factor

Used to specify the amount that the texture should be scaled along the v-axis.

Attribute name string: fme_texture_style_v_scaling_factor

Used to specify the offset applied to the texture after all the other transformations are done.

Attribute name string: fme_texture_style_u_offset

Used to specify the offset applied to the texture after all the other transformations are done.

Attribute name string: fme_texture_style_v_offset

Only affects the area outside the 0 to 1 U and V range. Note that not all texture wrapping styles are supported by all output formats, in which case the texture wrapping style will be defaulted to a supported style individual writer.

None: means no texture wrapping style is given and behavior outside the 0 to 1 range is unspecified.

Repeat in U and V: will tile the texture in both directions.

Clamp in U and V: clamps both U and V to the 0 to 1 range and a constant boundary color will fill values outside this range.

Clamp in U and Repeat in V: clamps U to the 0 to 1 range and tiles in the V direction.

Repeat in U and Clamp in V: clamps V to the 0 to 1 range and tiles in the U direction.

Mirror: will mirror the texture in the U and V direction.

Border Fill: will use a constant border color to fill values outside the U, V 0 to 1 range.

Attribute name string: fme_texture_style_wrap

This parameter is used only with the Border Fill wrapping style, and is only supported by certain formats. It specifies the color to "bleed" into the space surrounding the texture raster.

Attribute name string: fme_texture_style_border_color

When an appearance with a raster texture is set, each part of the Geometry that is affected will also require texture coordinates. When this parameter is No, new texture coordinates are always calculated for each part of the geometry that is affected by the appearance which is being set. When this parameter is Yes, new texture coordinates are only calculated on the affected parts of the geometry where they do not already exist. Existing texture coordinates are left unchanged.

This parameter specifies how the texture defined in an appearance style will be mapped onto the surface. This is only applicable to textures which have raster images.

• Surface Normal: The textures are projected onto the surfaces along their normals. For composite surfaces and meshes, each of the child parts will be treated separately, since the parts can have different normals.
• From Top View: The textures are projected onto the surfaces along a single normal – one that is perpendicular to the x-y plane. In this mode, a composite surface is considered as one single geometry when the texture coordinates are applied.

You can specify how the texture is shifted in the u direction with this parameter.

You can specify how the texture is shifted in the v direction with this parameter.

Texture u Repeat Factor can be used to specify the number of times the texture is repeated in rows.

Texture v Repeat Factor can be used to specify the number of times the texture is repeated in columns.