| 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 |
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 for 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 determines how search distances are 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 is 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 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 selected (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.gapro.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})| 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 |
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 a .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.MakeFeatureLayer_management(inputLyrx, "Snowplows Layer")
# ApplySymbologyFromLayer sets the time using the .lyrx file definition
arcpy.ApplySymbologyFromLayer_management(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")Licensing information
- Basic: No
- Standard: No
- Advanced: Yes