FME Feature Functions

Aborts the translation and outputs a specified message.

This function is the equivalent of the Terminator transformer.

Syntax

@Abort(<message>)

Arguments

<message>

The message string to output when the translation aborts.

Calculates the area of a polygonal feature. The function correctly handles both polygonal features and polygonal features with holes. For point and linear features, 0 is returned.

Syntax

@Area([[(SLOPED_AREAS|VOLUME),]<multiplier>])

Arguments

<multiplier>

By default, the area returned is in coordinate units squared. The multiplier, if specified, can be used to convert to other units. For example, (@Area()*10.764) could be used to calculate the area of a feature in a coordinate system with meters as the units, to a result in square feet. The default is 1.

Range: Real Number

SLOPED_AREAS

Calculates the area of the planar polygon or face with respect to the plane.

VOLUME

Calculates the volume of the solid (not the area).

Returns the coordinate system of features.

Syntax

@CoordSys()

Generates unique numbers and assigns them to feature attributes during a translation. Because it outputs the final counts in each of the domains to the log file, this function can also be used to count features that matched the correlation lines. In this case, the log file records the total number of times the function was invoked, even though its result was not stored in any attribute.

Syntax

@Count([<domain>[,<startVal>[,<modulo>]]][,NO_LOG])

Arguments

<domain>

A counter name. Each time @Count is invoked, it returns and increments the count associated with the domain name. This allows many different counters to be used during a single translation. For example, unique line numbers starting at 0 can be assigned to all lines by invoking @Count(lineCounter). During the same run, unique polygon numbers starting at 0 can be assigned to all polygons by using @Count(polygonCounter). If this parameter is not specified, the default domain is assumed.

Range: Any String

<startVal>

The starting value of the counter. The counter is incremented from the start value. This is useful for applications where ranges of values have meanings in the problem domain.

Range: Any Integer

<modulo>

The modulo value of the counter. The counter returns a value between zero and <modulo> - 1. This is useful when using counters as lookup values with the @Lookup function.

Range: Any Integer

NO_LOG

Prevents FME from logging this domain.

Configuration

The @Count function accepts the following configuration line:

Count MAX_TO_LOG <number>

If this configuration line is not present, a maximum of 50 count domains are logged by default.

<number>

Integer >= -1

Sets the maximum number of count domains that are logged. If -1 is specified, all count domains are logged.

Returns the dimension of the feature as either 2 or 3. If no parameters are specified, the dimensions of the feature are returned. If 2 or 3 is specified as a parameter, the function forces the feature to that dimension and returns the new dimension of the feature.

Syntax

@Dimension([(<dimension>)])

Arguments

<dimension>

The dimension to which the feature will be forced.

Range: (2|3)

Uses Tcl to evaluate a mathematical expression and returns the result.

Syntax

@Evaluate(<expression>)

Returns the number of parts of a geometry. For multis and aggregates, it is the number of parts; for paths, the number of segments, for donuts, the number of shells (outer and inner); otherwise, it is one.

Syntax

@GeometryPartCount([<count_aggregates_parts>])

Arguments

<count_aggregates_parts>

If TRUE, aggregates' parts also have their parts counted. If FALSE, only aggregates' parts are counted. If not specified, FALSE is assumed.

Returns the geometry type of the feature as a string.

Syntax

@GeometryType()

Calculates the length of features. For polygonal features, the length is equal to the sum of its perimeter and the perimeter of any holes within it.

Syntax

@Length([<dimension>[, <multiplier>]])

@Length(TO_POINT, <dimension>, <point x>, <point y> [, <point z>])

@Length(ALL_LENGTHS[, <dimension>[, <multiplier>]])

@Length(ALL_LENGTHS_AS_MEASURES, <dimension>, <multiplier>

[, <measure name>])

Arguments

<dimension>

Specifies whether the 3rd dimension is used in the length calculation. The default is 2, meaning only the x and y coordinates are used in the calculation. If 3 is specified and the feature has only 2 dimensions, no error is flagged and the length will be calculated on the 2 available dimensions.

If the first argument is TO_POINT, this argument is required.

Range: 2|3

<multiplier>

By default, the length returned is in ground units. The multiplier, if specified, can be used to convert to other units. The default is 1.

Range: Real Number

TO_POINT

If the first argument is TO_POINT, the function calculates the length of a feature up to the vertex specified by <point x>, <point y> [, <point z>]. The value returned is the length of the line up until the closest spot on the feature to the point that was passed in. For example, if there is a line that goes from (0,0) to (0,100) and passes in a point (50,50), the closest spot on the line would be (0,50), and the value returned would be the length from (0,0) to (0,50), which is 50. Depending on the <dimension> argument, either a 2D or 3D length is calculated.

<point x>

The x coordinate for the vertex up to which the length is to be calculated. Used if the first argument is TO_POINT.

Range: Real Number

<point y>

The y coordinate for the vertex up to which the length is to be calculated. Used if the first argument is TO_POINT.

Range: Real Number

<point x>

The z coordinate for the vertex up to which the length is to be calculated. Used if the first argument is TO_POINT.

Range: Real Number

ALL_LENGTHS

If the first argument is ALL_LENGTHS, the function returns a comma-separated list of values, in which each value is the distance from the start of the feature up to that vertex in the feature.

For example, a feature has 4 points: A,B,C and D.

AB, BC and CD are the distance between two consecutive vertices:

If AB = 1, BC = 2, and CD = 3, the value returned by the function is 0,1,3,6.

ALL_LENGTHS_AS_MEASURES

If the first argument is ALL_LENGTHS_AS_MEASURES, the function calculates values as with the ALL_LENGTHS option, but does not output them. Instead, they are applied as measures on the input features. The name of the new measure can be given by the <measure name> parameter.

<measure name>

Specifies the name of the measure to set. If left blank or omitted, the default measure is set.

Range: String

Examples

This example calculates the length of a feature's two dimensions. The feature is in a coordinate system with meters as units. To obtain a result in feet, a multiplier (3.2808) is applied:

@Length(2,3.2808)

This example calculates the length of a feature up to the (0,5) vertex (which is a two-dimensional vertex):

@Length(TO_POINT,2,0,5)

This example returns a list of lengths for all of a feature's two-dimensional vertices:

@Length(ALL_LENGTHS,2)

Assuming input of a two-dimensional line feature, this example adds measure values to each segment of the line, with a measure name of "measure_name".

@Length(ALL_LENGTHS_AS_MEASURES,2,0,measure_name)

Returns the number of coordinates that define the feature’s geometry.

Syntax

@NumCoords([FLATTEN_AGGREGATE])

Arguments

FLATTEN_AGGREGATE

In the case of multi-part or aggregate features, this flag ensures that the actual number of coordinates are returned for the aggregate feature, instead of the actual storage used for the feature. (An aggregate feature may use more storage space than the actual coordinates of the feature.)

The number of coordinates returned with FLATTEN_AGGREGATE excludes any internal FME meta information.

Creates and returns a new Universally Unique Identifier (UUID) for the feature.

Syntax

@UUID()

Returns the value of the specified input attribute attr.

Syntax

@Value(STRING attr)

This function may be used as either a feature function or an attribute value function. When used as a feature function, @XValue stores the specified value as the x coordinate of the feature.

When used as an attribute value function, @XValue returns the value of the first x coordinate of the feature. This value is then stored in the attribute.

@XValue() should generally be used in conjunction with @YValue(). If @XValue() is used on its own, it is possible to create a feature with a different number of X and Y values.

Syntax

@XValue([(<x-value>|<list attribute>)][, Reset])

Arguments

<x-value>

The value of the x coordinate stored in the feature. When used as a feature function, this parameter must be specified. When used as an attribute value function, this parameter is not specified.

Range: Real Number

<list attribute>

The name of a list attribute that contains coordinates to be stored in the feature. All the values in the list are supplied as coordinates to the feature; each coordinate is supplied in the same way as a single value.

Range: attribute name containing {} exactly once.

, Reset

Specifies that the coordinates of the feature are cleared before the x value is added. If not specified, then the x value is added to the current feature's geometry, either extending a line if the feature was linear or creating a Point-In-Polygon feature out of a polygonal feature.

This function may be used as either a feature function or an attribute value function. When used as a feature function, @YValue stores the specified value as the y coordinate of the feature.

When used as an attribute value function, @YValue returns the value of the first y coordinate of the feature. This value is then stored in the attribute.

@YValue() should generally be used in conjunction with @XValue(). If @YValue() is used on its own, it is possible to create a feature with a different number of X and Y values.

Syntax

@YValue([(<y-value>|<list attribute>)])

Arguments

<y-value>

The value of the y coordinate stored in the feature. When used as a feature function, this parameter must be specified. When used as an attribute value function, this parameter is not specified.

Range: Real Number

<list attribute>

The name of a list attribute that contains coordinates to be stored in the feature. All the values in the list are supplied as coordinates to the feature; each coordinate is supplied in the same way as a single value.

Range: attribute name containing {} exactly once.

This function may be used as either a feature function or an attribute value function. When used as a feature function, @ZValue stores the specified value as the z coordinate of the feature. If the feature contains multiple coordinates, then all coordinates are set to the specified z-value.

When used as an attribute value function, @ZValue returns the value of the first z coordinate of the feature. This value is then stored in the attribute.

@ZValue() should generally be used in conjunction with @XValue and @YValue(). If @ZValue() is used on its own, it is possible to create a feature with a different number of X, Y and Z values.

Syntax

@ZValue([(<z-value>|<list attribute>)])

Arguments

<z-value>

The value of the z coordinate stored in the feature. When used as a feature function, this parameter must be specified. When used as an attribute value function, this parameter is not specified.

Range: Real Number

<list attribute>

The name of a list attribute that contains coordinates to be stored in the feature. All the values in the list are supplied as successive coordinates to the feature.

Range: attribute name containing {} exactly once.