| 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 Feature Class
| The feature class that will contain the matched points. | Feature Class |
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.
| 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.
| 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.
| 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.
| 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. | 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, and set the time boundary reference to January 1, 1980, tracks will be split at the beginning of every day. | 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. | Date |
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
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
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.
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.
In addition to the fields from the Input Point Layer parameter value and any line fields specified using the Line Fields To Include parameter, the following fields will be included in 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.
DATE
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.
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 Spark. Analysis is completed on your desktop machine using multiple cores in parallel. See Considerations for GeoAnalytics Desktop tools to learn more about running analysis.
When running GeoAnalytics Desktop tools, the analysis is completed on your desktop machine. For optimal performance, data should be available on your desktop. If you are using a hosted feature layer, it is recommended that you use ArcGIS GeoAnalytics Server. If your data isn't local, it will take longer to run a tool. To use your ArcGIS GeoAnalytics Server to perform analysis, see GeoAnalytics Tools.
Note:
Licensed StreetMap Premium geodatabase feature layers are not supported as input for ArcGIS Pro 3.0.
Parameters
arcpy.geoanalytics.SnapTracks(input_points, input_lines, out_feature_class, track_fields, search_distance, connectivity_field_matching, {line_fields_to_include}, {distance_method}, {direction_value_matching}, {output_mode}, {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 |
out_feature_class | The feature class that will contain the matched points. | Feature Class |
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.
| 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.
| 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.
| 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.
| 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. | 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, and set the time boundary reference to January 1, 1980, tracks will be split at the beginning of every day. | 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. | Date |
Code sample
The following stand-alone script demonstrates how to use the SnapTracks function.
# Name: SnapTracks.py
# Description: Snap snowplow fleet tracks to roads to uncover areas that
# may need more resources for snow removal efforts
# Import system modules
import arcpy
# Enable time on the input features using an .lyrx file.
# To create the .lyrx file, add your layer to a map, open the layer properties
# and enable time. Then right-click the layer and select Share As Layer File.
inputLyrx = r'C:\data\Snowplow.lyrx'
# MakeFeatureLayer converts the .lyrx to features
snowplowsLayer = arcpy.management.MakeFeatureLayer(inputLyrx, "Snowplows Layer")
# ApplySymbologyFromLayer sets the time using the .lyrx file definition
arcpy.management.ApplySymbologyFromLayer(snowplowsLayer, inputLyrx)
# Set local variables
lineLayer = "c:/mydata/Roads.gdb/CityStreets"
trackIdentifier = "vehicle_id"
out = "c:/mydata/OutputDatasets.gdb/Snowplows_snapped_to_streets"
searchDistance = "10 Meters"
connectivityFieldMatching = "unique_ID from_node to_node"
directionValueMatching = "dir_travel F T B #"
# Run Snap Tracks
arcpy.gapro.SnapTracks(snowplowsLayer, lineLayer, out, trackIdentifier,
searchDistance, connectivityFieldMatching, None,
"GEODESIC", directionValueMatching, "MATCHED_FEATURES")