Snap Tracks (GeoAnalytics)

Summary

Snaps input track points to lines. The time-enabled point data must include features that represent an instant in time. Traversable lines with fields indicating the from and to nodes are required for analysis.

Illustration

Time-enabled track points that have been matched to lines are shown.

Usage

• The following table lists terminology used in the Snap Tracks tool:

  Term	Description
  Track	A sequence of features that are time-enabled with time type instant. Features are determined to be in sequence by using a track identifier field and their order in time. For example, a city can have a fleet of snow plow trucks that record their location every 30 seconds. The vehicle ID can represent the distinct tracks.
  Observation	A point in a track.
  Node	Nodes are the end vertices of line features used to indicate the direction of the line. The start of the line is the from node and the end of the line is the to node.
  Direction	The direction of a line. Direction refers to how a line can be travelled between the from node and the to node.
  Connectivity	Connectivity describes how lines are connected to represent a traversable network. Lines are connected based on their from node and to node values. Lines that cannot be reached by a point, based on connectivity, will not be considered a match.
  Traversable	Lines are traversable if they are connected by common nodes. For example, if the from node of line A is the same as the to node of line B, they are traversable.

• The tool requires the following parameter input layers:

  • Input Point Layer—The input point layer must be time-enabled observations that represent an instant in time. Track observations that do not have a valid time stamp will be excluded from analysis.
  • Input Line Layer—The input line layer must contain fields with the following connectivity information and must be specified in the Connectivity Field Matching parameter:
    • Unique ID—The unique identifier for the line
    • From node—The node that the travel along a line is moving away from
    • To node—The node that the travel along a line is moving to

Note:

Licensed StreetMap Premium geodatabase feature layers are not supported as input for ArcGIS Pro 3.0.

• The spatial reference of the Input Point Layer parameter value must be the same as the spatial reference of the Input Line Layer parameter value. If the datasets have different spatial references, use the Output Coordinate System environment to specify the spatial reference to use in analysis, or project the datasets prior to analysis.

• You can specify one or more fields to identify tracks. Tracks are represented by the unique combination of one or more track fields. For example, if the fields flightID and Destination are used as track identifiers, the features ID007, Solden and ID007, Tokyo would be in two separate tracks, since they have different Destination field values.

• Tracks must have more than one observation to be used in analysis. Tracks with only one observation will not be matched.

• Point to line matches are made with the following considerations:

  • The observation is within the search distance from a line. This is the minimum requirement. Observations will not be matched if they do not meet the search distance condition.
  • The observation can traverse the lines based on their connectivity.
  • The observation is travelling in a direction supported by the line. This is an optional condition that will be made if you specify values for the Direction Value Matching parameter. Results that meet this optional condition will be more accurate.

• Use the Search Distance parameter to specify the maximum distance allowed between an observation and a line. For example, if you know the accuracy of the GPS points is approximately 100 meters, specify 100 meters for the search distance.

• The Distance Method parameter specifies how search distances will be calculated. There are two distance methods available:

  • Geodesic—If the spatial reference can be continuously panned across the antimeridian, tracks will cross the antimeridian when appropriate. If the spatial reference cannot be continuously panned, tracks will be limited to the coordinate system extent and may not wrap. This is the default.
  • Planar—Tracks will not cross the antimeridian. Use this option if the input data uses a projected coordinate system.

• To include additional line attributes in the output results, specify the field names using the Line Fields to Include parameter. These fields will not be used for analytical purposes and are included for your own use. You cannot include geometry fields in the output result.

• Use the Direction Value Matching parameter to define the supported directions for each line feature. For example, a line layer has a field named direction with values T (backward), F (forward), B (both), and "" (none). Direction matching is optional but recommended for accurate results. If no direction matching is specified, the line is assumed to be bidirectional.

• The tool returns points snapped to the nearest location along the line it matched. The line features are not returned. The unique identifier of the line dataset will be available for matched results. The unique identifier field is specified using the Connectivity Field Matching parameter. You can identify the matched-to lines by referencing this field.

• In addition to the fields from the input point layer and any line fields specified, the following fields will be added to the output:

  Field name	Description
  MatchStatus	Indicates whether the observation was matched to a line. Values are M for matched features and U for unmatched features.
  OrigX	The x-coordinate of the input observation. Coordinates are stored in the units of the output spatial reference.
  OrigY	The y-coordinate of the input observation. Coordinates are stored in the units of the output spatial reference.
  MatchX	The x-coordinate of the matched result on the line. Coordinates are stored in the units of the output spatial reference.
  MatchY	The y-coordinate of the matched result on the line. Coordinates are stored in the units of the output spatial reference.
  MatchDist	The distance between the origin location and the matched location for an observation. Distances are calculated based on the distance method specified (geodesic or planar). Values are recorded in meters.
  INSTANT_DATETIME	The time stamp of the observation.

  If the Output Mode parameter value specified is All Features, both matched and unmatched points will be returned. For unmatched points, output result fields will be appended with null values for numeric fields and empty strings for string fields. The fields that will be appended with null values are line fields specified using the Line Fields To Include parameter,MatchX field, MatchY field, and MatchDist field.

• You can split tracks in the following ways:

  • Time Split—Based on a time between inputs. Applying a time split breaks up any track when input data is farther apart than the specified time. For example, if you have five features with the same track identifier and the times of [01:00, 02:00, 03:30, 06:00, 06:30] and set a time split of 2 hours, any features that are measured more than 2 hours apart will be split. In this example, the result would be a track with [01:00, 02:00, 03:30] and [06:00, 06:30], because the difference between 03:30 and 6:00 is greater than 2 hours.
  • Time Boundary Split—Based on defined time intervals. Applying a time boundary split segments tracks at a defined interval. For example, if you set the time boundary to 1 day, starting at 9:00 a.m. on January 1, 1990, each track will be truncated at 9:00 a.m. every day. This split accelerates computing time, as it creates smaller tracks for analysis. If splitting by a recurring time boundary makes sense for your analysis, it is recommended for big data processing.
  • Distance Split—Based on a distance between inputs. Applying a distance split breaks up any track when input data is farther apart than the specified distance. For example, if you set a distance split of 5 kilometers, sequential features greater than 5 kilometers apart will be part of a different track.
  • Split Expression—Based on an Arcade expression. Applying a split expression splits tracks based on values, geometry or time values. For example, you can split tracks when a field value is more than double the previous value in a track. To do this, using an example field named WindSpeed, you can use the following expression: var speed = TrackFieldWindow("WindSpeed", -1, 1); 2* speed[0] < speed[1]. Tracks will split when the previous value (speed[0]) is less than two times the current value.

• You can improve performance of the Snap Tracks tool by doing one or more of the following:

  • Use a smaller value for the Search Distance parameter so less point and line pairs are considered in the match process. It is recommended that you use a value of less than 75 meters.
  • Split the tracks using the Time Split, Time Boundary Split, Distance Split, or Split Expression parameters. Using the Time Boundary Split parameter will allow the biggest performance gains.
  • Use the Direction Value Matching parameter so lines will only be matched with points traveling in a direction supported by the line.
  • Use a selection of tracks of interest instead of the full track dataset.
  • Specify fewer fields for the Line Fields To Include parameter.
  • Set the Extent environment so that only data of interest is analyzed.
  • Use the planar distance method instead of geodesic.
  • Use data that is local to where the analysis is being run.

• Similar analysis can also be completed using the following:

  • Reconstruct time-enabled track points into lines using the Reconstruct Tracks tool.
  • Snap points, multipoints, lines, or polygons to other features using the Snap tool. This tool modifies the input data.

• This geoprocessing tool is powered by ArcGIS GeoAnalytics Server. Analysis is completed on your GeoAnalytics Server, and results are stored in your content in ArcGIS Enterprise.

• When running GeoAnalytics Server tools, the analysis is completed on the GeoAnalytics Server. For optimal performance, make data available to the GeoAnalytics Server through feature layers hosted on your ArcGIS Enterprise portal or through big data file shares. Data that is not local to your GeoAnalytics Server will be moved to your GeoAnalytics Server before analysis begins. This means that it will take longer to run a tool, and in some cases, moving the data from ArcGIS Pro to your GeoAnalytics Server may fail. The threshold for failure depends on your network speeds, as well as the size and complexity of the data. It is recommended that you always share your data or create a big data file share.

  Learn more about sharing data to your portal

  Learn more about creating a big data file share through Server Manager

Parameters

Dialog

Label	Explanation	Data Type
Input Point Layer	The points that will be matched to lines. The input must be a time-enabled point layer that represents an instant in time and must contain at least one field that identifies unique tracks.	Feature Set
Input Line Layer	The lines to which points will be matched. The input must contain fields with values indicating the from and to nodes of the line.	Feature Set
Output Name	The name of the output feature service.	String
Track Fields	One or more fields that will be used to identify unique tracks.	Field
Search Distance	The maximum distance allowed between a point and any line to be considered a match. It is recommended that you use values less than or equal to 75 meters. Larger distances will result in a longer process time and less accurate results.	Linear Unit
Connectivity Field Matching	The line layer fields that will be used to define the connectivity of the input line features. Unique ID—The line layer field that contains the unique ID value for each line feature From Node—The line layer field that contains the from node values To Node—The line layer field that contains the to node values	Value Table
Line Fields To Include (Optional)	One or more fields from the input line layer that will be included in the output result.	Field
Distance Method (Optional)	Specifies the method that will be used to calculate distances between points and lines. Geodesic— Geodesic distances will be calculated. This is the default. Planar—Planar distances will be calculated.	String
Direction Value Matching (Optional)	The line layer field and attribute values that will be used to define the direction of the input line features. For example, a line layer has a field named direction with values T (backward), F (forward), B (both), and "" (none). If no value is specified, the line is assumed to be bidirectional. Direction Field—The field from the line layer that describes the direction of travel. Forward Value—The value from the Direction Field that indicates the supported direction of travel is forward along a line. Backward Value—The value from the Direction Field that indicates the supported direction of travel is backward along a line. Both Value—The value from the Direction Field that indicates both forward and backward directions of travel are supported along a line. None Value—The value from the Direction Field that indicates there are no supported directions of travel along a line.	Value Table
Output Mode (Optional)	Specifies whether all input features or only the input features that were matched to a line feature will be returned. All Features—All input point features will be returned regardless of whether they were matched to a line feature. This is the default. Matched Features—Only input point features that were matched to a line feature will be returned.	String
Data Store (Optional)	Specifies the ArcGIS Data Store where the output will be saved. The default is Spatiotemporal big data store. All results stored in a spatiotemporal big data store will be stored in WGS84. Results stored in a relational data store will maintain their coordinate system. Spatiotemporal big data store—Output will be stored in a spatiotemporal big data store. This is the default. Relational data store—Output will be stored in a relational data store.	String
Time Split (Optional)	Features that are farther apart in time than the time-split duration will be split into separate tracks.	Time Unit
Distance Split (Optional)	Features that are farther apart in distance than the distance split value will be split into separate tracks. This parameter is only available with ArcGIS Enterprise 10.6 and later.	Linear Unit
Time Boundary Split (Optional)	A time span to split the input data into for analysis. A time boundary allows you to analyze values within a defined time span. For example, if you use a time boundary of 1 day, starting on January 1, 1980, tracks will be split at the beginning of every day. This parameter is only available with ArcGIS Enterprise 10.7 and later.	Time Unit
Time Boundary Reference (Optional)	The reference time used to split the input data into for analysis. Time boundaries will be created for the entire span of the data, and the reference time does not need to occur at the start. If no reference time is specified, January 1, 1970, is used. This parameter is only available with ArcGIS Enterprise 10.7 and later.	Date

Derived Output

Label	Explanation	Data Type
Output Feature Class	The output points.	Feature Set

Python

arcpy.geoanalytics.SnapTracks(input_points, input_lines, output_name, track_fields, search_distance, connectivity_field_matching, {line_fields_to_include}, {distance_method}, {direction_value_matching}, {output_mode}, {data_store}, {time_split}, {distance_split}, {time_boundary_split}, {time_boundary_reference})

Name	Explanation	Data Type
input_points	The points that will be matched to lines. The input must be a time-enabled point layer that represents an instant in time and must contain at least one field that identifies unique tracks.	Feature Set
input_lines	The lines to which points will be matched. The input must contain fields with values indicating the from and to nodes of the line.	Feature Set
output_name	The name of the output feature service.	String
track_fields [track_fields,...]	One or more fields that will be used to identify unique tracks.	Field
search_distance	The maximum distance allowed between a point and any line to be considered a match. It is recommended that you use values less than or equal to 75 meters. Larger distances will result in a longer process time and less accurate results.	Linear Unit
connectivity_field_matching [connectivity_field_matching,...]	The line layer fields that will be used to define the connectivity of the input line features. Unique ID—The line layer field that contains the unique ID value for each line feature From Node—The line layer field that contains the from node values To Node—The line layer field that contains the to node values	Value Table
line_fields_to_include [line_fields_to_include,...] (Optional)	One or more fields from the input line layer that will be included in the output result.	Field
distance_method (Optional)	Specifies the method that will be used to calculate distances between points and lines. GEODESIC—Geodesic distances will be calculated. PLANAR—Planar distances will be calculated.	String
direction_value_matching [direction_value_matching,...] (Optional)	The line layer field and attribute values that will be used to define the direction of the input line features. For example, a line layer has a field named direction with values T (backward), F (forward), B (both), and "" (none). If no value is specified, the line is assumed to be bidirectional. Direction Field—The field from the line layer that describes the direction of travel. Forward Value—The value from the Direction Field that indicates the supported direction of travel is forward along a line. Backward Value—The value from the Direction Field that indicates the supported direction of travel is backward along a line. Both Value—The value from the Direction Field that indicates both forward and backward directions of travel are supported along a line. None Value—The value from the Direction Field that indicates there are no supported directions of travel along a line.	Value Table
output_mode (Optional)	Specifies whether all input features or only the input features that were matched to a line feature will be returned. ALL_FEATURES—All input point features will be returned regardless of whether they were matched to a line feature. This is the default. MATCHED_FEATURES—Only input point features that were matched to a line feature will be returned.	String
data_store (Optional)	Specifies the ArcGIS Data Store where the output will be saved. The default is SPATIOTEMPORAL_DATA_STORE. All results stored in a spatiotemporal big data store will be stored in WGS84. Results stored in a relational data store will maintain their coordinate system. SPATIOTEMPORAL_DATA_STORE—Output will be stored in a spatiotemporal big data store. This is the default. RELATIONAL_DATA_STORE—Output will be stored in a relational data store.	String
time_split (Optional)	Features that are farther apart in time than the time-split duration will be split into separate tracks.	Time Unit
distance_split (Optional)	Features that are farther apart in distance than the distance split value will be split into separate tracks. This parameter is only available with ArcGIS Enterprise 10.6 and later.	Linear Unit
time_boundary_split (Optional)	A time span to split the input data into for analysis. A time boundary allows you to analyze values within a defined time span. For example, if you use a time boundary of 1 day, starting on January 1, 1980, tracks will be split at the beginning of every day. This parameter is only available with ArcGIS Enterprise 10.7 and later.	Time Unit
time_boundary_reference (Optional)	The reference time used to split the input data into for analysis. Time boundaries will be created for the entire span of the data, and the reference time does not need to occur at the start. If no reference time is specified, January 1, 1970, is used. This parameter is only available with ArcGIS Enterprise 10.7 and later.	Date

Derived Output

Name	Explanation	Data Type
output	The output points.	Feature Set

Code sample

SnapTracks example 1 (stand-alone script)

The following Python window script demonstrates how to use the SnapTracks function.

# Name: SnapTracks.py
# Description: Snap delivery vehicle GPS crumbs to a street dataset.

# Requirements: ArcGIS GeoAnalytics Server

# Import system modules
import arcpy

# Set local variables
tracksLayer = "https://sampleserver.arcgisonline.com/arcgis/rest/services/DeliveryTrucks/MapServer/0"
lineLayer = "https://sampleserver.arcgisonline.com/arcgis/rest/services/CityStreets/MapServer/0"
trackIdentifier = "vehicle_id"
out = "trucks_snapped_to_streets"
searchDistance = "30 Feet"
connectivityFieldMatching = "unique_ID from_node to_node"
directionValueMatching = "dir_travel F T B #"

# Run Snap Tracks
arcpy.geoanalytics.SnapTracks(tracksLayer, lineLayer, out, trackIdentifier, 
                       searchDistance, connectivityFieldMatching, None,
                       "GEODESIC", directionValueMatching, "MATCHED_FEATURES", 
                       "SPATIOTEMPORAL_DATA_STORE")

Environments

Output Coordinate System, Extent, Current Workspace

Special cases

Output Coordinate System

The coordinate system that will be used for analysis. Analysis will be completed in the input coordinate system unless specified by this parameter. For GeoAnalytics Tools, final results will be stored in the spatiotemporal data store in WGS84.

Licensing information

• Basic: Requires ArcGIS GeoAnalytics Server
• Standard: Requires ArcGIS GeoAnalytics Server
• Advanced: Requires ArcGIS GeoAnalytics Server