Calculate Distance

Available in real-time and big data analytics.

The Calculate Distance tool can calculate the distance from a target point feature to the nearest feature in the same feed or in another feed or dataset. Candidate nearest features can be limited based on an attribute relationship between the target and near features.

Examples

The following are example uses of the Calculate Distance tool:

• An emergency operations manager is monitoring field crew locations in real time. Each time a worker's location is updated, a real-time analytic calculates the distance from the worker's current position to their assigned base of operations.
• Calculate the distance from an incoming feed of emergency events to a different feed of emergency response vehicles moving in the same vicinity to determine the closest responder to the event.
• Calculate the distance from the features in a shipping vessel feed to other features in the same feed to determine whether any are in dangerous proximity to one another.

Usage notes

Keep the following in mind when working with the Calculate Distance tool:

• For every target feature, the distance will be calculated to the nearest feature in the join layer within the provided search radius. The number of features in the search radius will affect performance.
• If the Keep outside distance features parameter is set to No, the output will contain only those target features for which a join feature is found within the search radius and satisfies the attribute relationship, if specified. If set to Yes, the output will contain all target features. If there is not a join feature found for a target feature in the specified search radius, the DistanceToFeature output value will be null.

• The Spatial Relationship parameter can be set to Near geodesic or Near planar.
  • Near geodesic calculates geodesic distance. This accounts for the actual shape of the earth (an ellipsoid, or more properly, a geoid). Distances are calculated between two points on a curved surface (the geoid) as opposed to two points on a flat surface (the Cartesian plane). Always consider calculating geodesic distance in the following circumstances:
    • The input features are dispersed (cover multiple coordinated universal time (UTM) zones, large regions, or the entire globe).
    • The spatial reference (map projection) of the input features distorts distances to preserve other properties such as area.
  • Near planar calculates Euclidean distance. This is the distance in a two-dimensional Cartesian plane in which straight-line or Euclidean distances are calculated between two points on a flat surface (the Cartesian plane). This is useful when analyzing distances between features that are concentrated in a relatively small area, such as one UTM zone.
  • If a feed is connected to the join port, distance calculations will be performed dynamically based on the changing features in both the target and join feeds.
  • In dynamic geofencing, the Join Time Window parameter must be set. If the join feed does not have a field tagged as END_TIME and the last known observation for a join feature is older than this window, it will be removed from the tool's memory and will not be included in the analysis. If the join feed has a field tagged as END_TIME, the feature will age out of the geofence store according to the value in the field tagged as END_TIME or when the join time window is closed, whichever comes first.
  • Adding a join feed to a tool must be done in the model view. Analytics with tools using join feeds cannot be viewed or edited in the workflow view.
• An attribute relationship can be specified to measure distance from a target feature to the nearest feature in another dataset with a matching attribute value.
• One or more fields can be specified from the near (join) feature to join with the target feature.

Parameters

The following are the parameters for the Calculate Distance tool:

Parameter	Description	Data type
Target Layer	The features that the Calculate Distance tool will process.	Features
Join Layer	The layer in which to identify the nearest feature for each feature in the Target Layer parameter and calculate the distance between them.	Features
Spatial Relationship	The method used to create the search radius for finding nearest features. Spatial operators include Near geodesic or Near planar. Note: If Near planar is selected, the target features and nearest features must both be projected. The Project tool can be used to project the input points prior to running the Calculate Distance tool. Note: The Near geodesic spatial search method is only supported when both the target and near (join) features are point features. Note: The Near geodesic and Near planar spatial search methods are only supported when the target features are point features	String
Spatial Search Radius	The distance within which to identify the nearest feature. Features outside this distance will not be considered.	Linear Unit
Attribute Relationship (optional)	Limits the candidate nearest features based on a relationship between the target and near (join) features. Specify which attribute field from the target layer matches an attribute field from the near (join) layer.	String
Output Distance Units	The output distance units for the distance calculation.	String
Join Fields (optional)	A set of fields from the near (join) features to join to the target features.	String
Join Time Window	The time window for the join feed (dynamic geofencing). If the last known observation for a join feature is older than the time window specified, it will be removed and will not be included in the analysis. If the join feed has a field marked as END_TIME, this parameter is optional.	String
Keep outside distance features	Specifies whether to output all target features or only those for which a join feature was found within the search radius and satisfies the attribute relationship, if specified.	Boolean

Output layer

The output layer will be appended with the new DistanceToFeature field. Additionally, any fields specified in the Join Fields parameter will also be appended to the output layer.

Field name	Description	Field type
DistanceToFeature	The distance from the feature to the nearest feature in Join Layer in the units defined in the Output distance units parameter.	Float64

Considerations and limitations

There are several considerations and limitations to keep in mind when using the Calculate Distance tool:

• The Near geodesic spatial search method is only supported as the spatial relationship when both the target and near (join) features are point features.
• The Near geodesic and Near planar spatial search methods are only supported when the target features are point features.