Calculate Distance

The Calculate Distance tool 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 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 set to either 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.
      Note:

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

    • Near planar calculates Euclidean distance. This is 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.
    • Dynamic geofencing is in beta for most configurations. The only currently released configuration is for Join Features. Configurations using beta capabilities 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 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 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 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.

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 DistanceToFeature field. 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 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.