Calculate Distance

Calculate Distance tool icon The Calculate Distance tool can calculate the distance from a target 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

  • 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 around 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 if any are in dangerous proximity to one another.

Usage notes

  • For every target feature, distance will be calculated to all features in the join layer within the provided search radius. The number of features within the search radius will affect performance.
  • The spatial search method can be either Near geodesic or Near planar.
    • Near geodesic will calculate 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:
      • Your input features are dispersed (cover multiple UTM zones, large regions, or the entire globe).
      • The spatial reference (map projection) of your input features distorts distances to preserve other properties such as area.
      Note:

      Near geodesic is only supported when both the target and near (join) features are point features.

    • Near planar will calculate Euclidean distance. This is distance in a two-dimensional Cartesian plane, where 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 done 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 purged 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 at the close of the join time window, whichever comes first.
    • Dynamic geofencing is currently in beta and should not be used in production workflows.
  • 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

ParameterDescriptionData Type

Target Layer

The features which 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 and calculate the distance between them.

Features

Spatial Relationship

Defines the method by which to create the search radius for finding nearest features.

Spatial operators include Near geodesic and 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:

Near geodesic is only supported when both the target and near (join) 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 geofences). If the last known observation for a join feature is older than the time window specified, it will be purged and will not be included in the analysis. If the join feed has a field marked as END_TIME, this parameter is optional.

Note:

Dynamic geofencing is currently in beta and should not be used in production workflows.

String

Output layer

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

Field NameDescriptionField Type

DistanceToFeature

The distance from the feature to the nearest feature in the Join Layer in the units defined in the Output distance units parameter.

Float64

Considerations and limitations

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