FME Transformers: 2024.2
FME Transformers: 2024.2
AppearanceSetter
Sets appearance style(s) onto the front and/or back sides of geometries. All Surfaces and most geometry types which are, or can contain, surfaces may have appearances set directly on them.
You may also, at the same time, generate the texture coordinates of the surfaces that are affected. Texture coordinates are only required where Raster textures are used.
The appearance is only directly set on the geometry parts which are specified through the Geometry XQuery selection. However, because appearances may be inherited further down a geometry hierarchy, setting an appearance directly at one level may also have a visible effect further down a geometry hierarchy. Texture coordinates are therefore calculated, if necessary, on every geometry part that is affected by the setting of this appearance.
This transformer accepts appearance values in two ways: input appearance style feature and transformer parameter values. If a value is specified in both places, the parameter value will be the only one used. For example, if an input appearance style feature has the appearance name wall, and the appearance name is also set in the transformer parameter as brick wall, then the appearance that is set on the feature will have the name brick wall.
There are also two fundamental modes in which this transformer is used:
- One mode may send in many Appearance style features and specify, through the two join parameters, which Appearance to apply to each selected geometry part.
- In the other mode, where no join is specified, a single input Appearance style feature is expected and it is used for all selected geometry parts.
Coordinate Space Terminology
In order to reduce confusion between the real coordinate space of the surface and the texture coordinate space, this transformer uses "u" and "v" instead of "x" and "y" when referencing the latter. Note that this is also reflected in the parameter names.
For more information on appearance support in FME, see Appearances.
Configuration
Input Ports
Appearance
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.
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.
Geometry
Features that contain some geometry on which an appearance may be set.
Holder
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.
Output Ports
Output
All input Geometry features are output whether or not anything was changed.
Holder
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.
Unmatched
Features that were not queried.
<Rejected>
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.
Parameters
Group Processing
Group By |
Note that only the first appearance styles will be used in each "Group By" group. |
||||
Complete Groups |
Select the point in processing at which groups are processed:
Considerations for Using Group By
There are two typical reasons for using When Group Changes (Advanced) . The first is incoming data that is intended to be processed in groups (and is already so ordered). In this case, the structure dictates Group By usage - not performance considerations. The second possible reason is potential performance gains. Performance gains are most likely when the data is already sorted (or read using a SQL ORDER BY statement) since less work is required of FME. If the data needs ordering, it can be sorted in the workspace (though the added processing overhead may negate any gains). Sorting becomes more difficult according to the number of data streams. Multiple streams of data could be almost impossible to sort into the correct order, 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. In this case, using Group By with When All Features Received may be the equivalent and simpler approach. Note Multiple feature types and features from multiple datasets will not generally naturally occur in the correct order.
As with many scenarios, testing different approaches in your workspace with your data is the only definitive way to identify performance gains. |
Geometry Part Selection
Geometry XQuery |
Use this parameter to isolate only a portion of the input geometry. 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. |
||||||
Set Appearance On |
Select the sides to set the appearance on:
|
||||||
Appearance Join Attribute and Geometry Join Trait |
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.
|
||||||
Appearance Storage |
When you pass in Appearance style features, this transformer will be creating Appearance definitions. There are two ways these new appearances may be stored and used:
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. |
Color
Specifying Colors
Colors may be entered directly or chosen from the color picker via the ellipsis button.
Syntax
Colors can be specified by RGB values or hex codes. RGB values may be either 24-bit or decimal (0 - 1). If the value type is unclear, as in (1,1,1), the 24-bit interpretation is used. Hex codes are accepted with or without a hash sign (#).
|
24-bit RGB |
Decimal RGB |
Hex code |
---|---|---|---|
|
0,0,0 |
0,0,0 |
#000000 |
|
255,0,0 |
1,0,0 |
#FF0000 |
|
202,173,232 |
0.79,0.68,0.91 |
#CAADE8 |
255,255,255 |
Not Available |
#FFFFFF |
Appearance Name |
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 |
Diffuse Color |
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 |
Ambient 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 |
Specular 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 |
Emissive Color |
Color of the light that the object is emitting itself. Attribute name string: fme_appearance_style_emissive_color |
Shininess |
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 |
Alpha |
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 |
Texture
Texture 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_u |
Texture Center v |
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 |
Texture Rotation Angle |
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 |
Texture u Shearing Factor |
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 |
Texture v 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 |
Texture u Scaling 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 |
Texture v 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 |
Texture u Offset |
Used to specify the offset applied to the texture after all the other transformations are done. Attribute name string: fme_texture_style_u_offset |
Texture v 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 |
Texture Wrap Style |
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 |
Texture Border Color |
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 |
Texture Coordinate Generation
Use Existing Texture Coordinates |
When an appearance with a raster texture is set, each part of the Geometry that is affected will also require texture coordinates.
|
||||||||||
Texture Mapping Type |
Specify how the texture defined in an appearance style is mapped onto the surface. This is only applicable to textures which have raster images.
|
||||||||||
u Origin Offset |
Specify how the texture is shifted in the u direction. |
||||||||||
v Origin Offset |
Specify how the texture is shifted in the v direction. |
||||||||||
Texture u Repeat Factor |
Specify the number of times the texture is repeated in rows. |
||||||||||
Texture v Repeat Factor |
Specify the number of times the texture is repeated in columns. |
Editing Transformer Parameters
Transformer parameters can be set by directly entering values, using expressions, or referencing other elements in the workspace such as attribute values or user parameters. Various editors and context menus are available to assist. To see what is available, click beside the applicable parameter.
How to Set Parameter Values
Defining Values
There are several ways to define a value for use in a Transformer. The simplest is to simply type in a value or string, which can include functions of various types such as attribute references, math and string functions, and workspace parameters.
Using the Text Editor
The Text Editor provides a convenient way to construct text strings (including regular expressions) from various data sources, such as attributes, parameters, and constants, where the result is used directly inside a parameter.
Using the Arithmetic Editor
The Arithmetic Editor provides a convenient way to construct math expressions from various data sources, such as attributes, parameters, and feature functions, where the result is used directly inside a parameter.
Conditional Values
Set values depending on one or more test conditions that either pass or fail.
Parameter Condition Definition Dialog
Content
Expressions and strings can include a number of functions, characters, parameters, and more.
When setting values - whether entered directly in a parameter or constructed using one of the editors - strings and expressions containing String, Math, Date/Time or FME Feature Functions will have those functions evaluated. Therefore, the names of these functions (in the form @<function_name>) should not be used as literal string values.
Content Types
These functions manipulate and format strings. | |
Special Characters |
A set of control characters is available in the Text Editor. |
Math functions are available in both editors. | |
Date/Time Functions | Date and time functions are available in the Text Editor. |
These operators are available in the Arithmetic Editor. | |
These return primarily feature-specific values. | |
FME and workspace-specific parameters may be used. | |
Creating and Modifying User Parameters | Create your own editable parameters. |
Dialog Options - Tables
Table Tools
Transformers with table-style parameters have additional tools for populating and manipulating values.
Row Reordering
|
Enabled once you have clicked on a row item. Choices include:
|
Cut, Copy, and Paste
|
Enabled once you have clicked on a row item. Choices include:
Cut, copy, and paste may be used within a transformer, or between transformers. |
Filter
|
Start typing a string, and the matrix will only display rows matching those characters. Searches all columns. This only affects the display of attributes within the transformer - it does not alter which attributes are output. |
Import
|
Import populates the table with a set of new attributes read from a dataset. Specific application varies between transformers. |
Reset/Refresh
|
Generally resets the table to its initial state, and may provide additional options to remove invalid entries. Behavior varies between transformers. |
Note: Not all tools are available in all transformers.
For more information, see Transformer Parameter Menu Options.
FME Community
The FME Community has a wealth of FME knowledge with over 20,000 active members worldwide. Get help with FME, share knowledge, and connect with users globally.
Search for all results about the AppearanceSetter on the FME Community.