Finds the Candidate features closest to each Base feature and merges their attributes onto the Base feature according to the Accumulation Mode parameter. Or, if Input is set to Candidates Only, performs the same operation using each Candidate as a Base feature, considering all other Candidates, but not itself.
Input Ports
If a feature is routed to both the Base and the Candidate input ports, then features will be compared to themselves as they are both a Base and Candidate.
If Input is set to Candidates Only, there will be no Base port. All Candidates will be compared with all other Candidates, but will not be compared to themselves.
Output Ports
Matched
If a Candidate feature is found, then all the attributes from the closest Candidate feature are added to the Base feature and the Base feature is output via the Matched port. In addition, several other attributes are added to the Base feature just prior to it being output via the Matched port:
| Attributes | Description |
|---|---|
| _distance | The distance from the Base to the matching Candidate |
| _angle | The angle between the closest interpolated Base point and the closest interpolated Candidate point. |
| _closest_base_x, _closest_base_y | The coordinates of the closest interpolated point on the Base feature relative to the Candidate feature. |
| _closest_candidate_x, _closest_candidate_y | The coordinates of the closest interpolated point on the Candidate feature relative to the Base feature. |
| _candidate_angle | The angle from (_closest_candidate_x, _closest_candidate_y) to the next vertex within the Candidate feature. If (_closest_candidate_x, _closest_candidate_y) equals the last vertex of the Candidate feature, then candidate_angle will be the angle from the previous vertex of the Candidate feature to (_closest_candidate_x, _closest_candidate_y). |
| _candidate_label_angle | The _candidate_angle adjusted so that if it is used as a text rotation, the text will run from left to right. This angle is guaranteed to be greater than or equal to 270 and less than 360, or greater than or equal to 0 and less than or equal to 90. |
UnmatchedBase
If there are no Candidate features found to be within the maximum distance, then the Base feature will be output unchanged via the UnmatchedBase port.
UnmatchedCandidate
Candidate features not within the Maximum Distance to any Base feature are output via the UnmatchedCandidate port. Also, if no Close Candidate List Name is specified, then any features within the Maximum Distance, but not closest, will be output from the UnmatchedCandidate port. This is because they are not used in any way; their attributes are not merged onto the base at all.
<Rejected>
Invalid features are output via the <Rejected> port. Base and candidate features with null geometry will be rejected. Features with invalid geometries may also be rejected. Rejected features will be tagged with a reason for the rejection, using the fme_rejection_code attribute.
Parameters
Transformer
Group By
The default behavior is to use the entire set of input features as the group. This option allows you to select attributes that define which groups to form. Each set of features that have the same value for all of these attributes will be processed as an independent group.
Input
If Input is set to Bases and Candidates, then the transformer will have a Base port as well as a Candidate port, and the transformer will look for the Candidate feature that lies closest to each Base feature. If Input is set to Candidates Only, then the transformer will have only a Candidate port and no Base port. Each Candidate will then also act as a Base.
Parallel Processing Level
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.
Input is Ordered by Group
Yes: This transformer will process input groups in order. Changes on 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.
No: This is the default behavior. Processing will only occur in this transformer once all input is present.
Parameters
Number of Neighbors to Find
The maximum number of candidate features that will be included in the list specified by the Close Candidate List Name parameter. The closest candidate features will be included in the list.
A value must be specified for at least one of the Number of Neighbors to Find and Maximum Distance parameters.
Maximum Distance
The maximum distance is measured in the units of coordinates of the input features.
The list specified in the Close Candidate List Name contains all of the candidate features that were within the maximum distance of the base.
A value must be specified for at least one of the Number of Neighbors to Find and Maximum Distance parameters.
Note: To get the distance from a given Base to all Candidate features, use a very large number for this parameter and specify a Close Candidate List Name.
Insert Vertex On Base Feature
If Insert Vertex On Base Feature is Yes, then (_closest_base_x, _closest_base_y) will be inserted onto the Base feature if the insertion is well-defined. For example, if a Candidate polygon is contained inside a Base polygon, insertion will not take place.
If Insert Vertex On Base Feature is Yes, the _closest_base_x, _closest_base_y vertex will be inserted onto to the Base feature as well as added as an attribute. This option only applies to Lines, Polygons, Paths, Arcs, Ellipses, and Donuts.
Candidates First
If set to Yes, then all Candidate features must be input before any Base features. If a Candidate feature is input after a Base feature and this option is set to Yes, the Candidate feature will be ignored in all calculations.
Close Candidate List Name
If specified, a list will be built on the Matched output, consisting of all the attributes from the Candidate features that were within maximum distance of the Base feature.
Note: Attribute lists are not accessible from the output schema in Workbench unless they are first processed using a transformer that operates on them, such as ListExploder or ListConcatenator. All attribute list transformers are displayed in the Contents pane of the Transformer Help under Lists. Alternatively, AttributeExposer can be used.
Treat Polygons As
- Lines: A polygon, donut, or ellipse will be treated as a line (that is, its boundary line) for backwards compatibility.
- Areas: A polygon, donut, or ellipse will be treated as an area, and any geometry that overlaps with the area will be of 0 distance away from that area.
Attribute Accumulation
If attributes on the base and candidate feature share the same name, but are not geometry attributes that start with fme_, then they are deemed conflicted.
Accumulation Mode
Merge Candidate: The base feature will retain all of its own un-conflicted attributes, and will additionally acquire any un-conflicted attributes that the candidate feature has. This mode will handle conflicted attributes based on the Conflict Resolution parameter.
Prefix Candidate: The base feature will retain all of its own attributes. In addition, the base will acquire attributes reflecting the candidate feature’s attributes, with the name prefixed with the Prefix parameter.
Only Use Candidate: The base feature will have all of its attributes removed, except geometry attributes that start with fme_. Then, all of the attributes from one (arbitrary) candidate feature will be placed onto the base.
Conflict Resolution
Use Base: If a conflict occurs, the base values will be maintained.
Use Candidate: If a conflict occurs, the values of the candidate will be transferred onto the base.
Prefix
To prevent a Candidate attribute from being ignored because the Base attribute already exists, you can optionally specify a prefix that will be applied to each Candidate attribute when it is added to the Base. This parameter is only enabled when the Accumulation Mode is Prefix Candidate.
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.
Transformer Categories
Example
All angles are measured in degrees counterclockwise from horizontal. Where angles are not well-defined (for example, when a Candidate polygon is contained inside a Base polygon), they are set to 0.
Usage Notes
This transformer works with 2D geometries only; if an input geometry is 3D, its z-coordinate will be ignored.
This transformer has full support for points, lines, arcs, ellipses, polygons, and donuts, and has limited support for other types of geometry. Polygons, ellipses and donuts may be processed as lines or areas, depending on user selection.
FME Licensing Level
FME Professional edition and above
Technical History
Associated FME function or factory: ProximityFactory
Search FME Knowledge Center
Search for samples and information about this transformer on the FME Knowledge Center.
Tags Keywords: MBR "minimum bounding rectangle" neighbourfinder