CoordinateExtractor
Typical Uses
- Extracting coordinate values into attributes for manipulation or use elsewhere.
How does it work?
The CoordinateExtractor receives any type of geometry, and retrieves either one specified coordinate or all coordinates, adding them to the feature as attributes.
If Specify Coordinate is used, retrieving only one coordinate, the coordinate is identified by its Coordinate Index, which may be either entered as an integer or specified with an attribute value, expression, user parameter, or conditional value. A coordinate index always starts at zero (0). 0 indicates the first vertex (or only vertex of a point geometry), and a negative index can be used to indicate position relative to the last vertex where -1 is the last coordinate, -2 is the second-to-last, and so on. If the index number is invalid, the feature will be rejected.
If All Coordinates is used, retrieving coordinates for all vertices, the values will be added to a list attribute which may be further manipulated with list-based transformers. A list is returned even when the incoming feature possesses just a single vertex.
A Default Z Value may be optionally provided, and is applied where no z coordinate value exists.This too can be provided by an attribute, expression, user parameter, or conditional value.
If the input feature is a raster or point cloud, All Coordinates will return its extents, and Specify Coordinate will return the requested vertex on the bounding box (0, 1, 2, 3, 4). If the input feature is multi-part or aggregate, each part’s coordinates are indexed sequentially.
Examples
In this example, we have a geodatabase containing address points. Note that the point features have 23 attributes, and are in a UTM coordinate system. We want to extract the coordinates of each point into attributes for use elsewhere.
The address points are routed into a CoordinateExtractor.
In the parameters dialog, Mode is set to Specify Coordinate. The Coordinate Index default is zero (0), the first one, which is correct. Default names are also provided for the X, Y, and Z output attributes.
Note that although Mode > All Coordinates would also return just one set of coordinates per point, and wouldn’t require setting a Coordinate Index number, they would be added as a list attribute, potentially requiring additional transformers to work with.
The output features have two added attributes - _x and _y - for a new total of 25 attributes. Note that the coordinate values are in meters due to the UTM coordinate system.
The Z Attribute was not added, as the data is 2D and we did not provide a Default Z Value.
In this example, we have a set of park polygons, and want to retrieve all of the coordinates for them. Note that the input features have 28 attributes.
The features are routed into a CoordinateExtractor.
In the parameters dialog, Mode is set to All Coordinates. A default name is provided for the Coordinates List Name - _indices.
The output features have an added list attribute named _indices containing coordinates for each vertex of the polygon.
Note that each coordinate has an x and y value only. Z was not added as the data is 2D and we did not provide a Default Z Value.
In this example, we want to retrieve the coordinates of the first and last points of these transit lines. Note that the original features have nine attributes.
The features are routed through two CoordinateExtractors, one to extract the first point and one to extract the last.
In the parameters dialog of the first CoordinateExtractor, Mode is set to Specify Coordinate and Coordinate Index is set to zero (0), indicating the first vertex.
The X and Y Attribute names are edited to start_x and start_y.
Similarly, in the parameters dialog of the second CoordinateExtractor, Coordinate Index is set to -1, indicating the last vertex. X and Y Attribute are set as end_x and end_y.
The output features have added attributes containing the requested coordinate values.
Usage Notes
- Extracted coordinates may be reprojected into another coordinate system using the AttributeReprojector.
- All vertices can be retrieved as a delimited attribute (instead of a list) using the CoordinateConcatenator.
- The first coordinate index is 0 and the last coordinate index is -1. In a polygon feature, or a line feature that closes on itself, these two vertices should return the same coordinate values.
- To retrieve the center point of a feature, use the CenterPointExtractor or CenterPointReplacer.
Configuration
Input Ports
This transformer accepts any feature.
Output Ports
Features with extracted coordinates stored in either attributes or list attributes as specified in the parameters.
Features where either an invalid Coordinate Index or invalidDefault Z Value has been provided will be routed to the <Rejected> port.
Rejected features will have an fme_rejection_code attribute with one of the following values:
INVALID_PARAMETER_DEFAULT_Z
INVALID_PARAMETER_INDEX
Rejected Feature Handling: can be set to either terminate the translation or continue running when it encounters a rejected feature. This setting is available both as a default FME option and as a workspace parameter.
Parameters
Mode |
Select a coordinate extraction mode. Choices include:
|
Default Z Value |
Optionally provide a z value to be applied to 2D geometries. If blank, no z attributes will be created where they do not already exist. |
Coordinates List Name
|
If Mode is All Coordinates, provide a name for the list attribute to be added and store all coordinate values. The default name is _indices. |
Coordinate Index |
If Mode is Specify Coordinate, specify the index position of the desired coordinate as an integer. Attribute values and expressions are supported. Index numbering starts at zero (0), indicating the first vertex. Negative index positions indicate position relative to the last vertex, where -1 is the last, -2 is second-to-last, and so on. |
Output Attribute Names
X |
Name the attribute to contain the x coordinate. |
Y |
Name the attribute to contain the y coordinate. |
Z |
Name the attribute to contain the z coordinate. |
Editing Transformer Parameters
Using a set of menu options, transformer parameters can be assigned by referencing other elements in the workspace. More advanced functions, such as an advanced editor and an arithmetic editor, are also available in some transformers. To access a menu of these options, click beside the applicable parameter. For more information, see Transformer Parameter Menu Options.
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. There are a number of tools and shortcuts that can assist in constructing values, generally available from the drop-down context menu adjacent to the value field.
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.
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
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.
Reference
Processing Behavior |
|
Feature Holding |
No |
Dependencies | None |
Aliases | CoordinateFetcher |
History |
FME Community
The FME Community is the place for demos, how-tos, articles, FAQs, and more. Get answers to your questions, learn from other users, and suggest, vote, and comment on new features.
Search for all results about the CoordinateExtractor on the FME Community.
Examples may contain information licensed under the Open Government Licence – Vancouver and/or the Open Government Licence – Canada.