| Label | Explanation | Data Type |
Input Layer
| The time-enabled point features on which motion statistics will be calculated. | Feature Layer |
Output Feature Class
|
The output feature class or layer containing the points with new fields for each motion statistic that was calculated. | Feature Class |
Track Fields
|
One or more fields that will be used to identify distinct entities. | Field |
Track History Window (Optional) |
The number of observations (including the current observation) that will be used for summary statistics. The default value is 3, which means that the summary statistics will be calculated at each point in a track using the current observation and the previous two observations. This parameter does not affect instantaneous statistics or idle classification. | Long |
Motion Statistics
(Optional) | Specifies the group containing the statistics that will be calculated and written to the result. If no value is specified, all statistics from all groups will be calculated.
| String |
Distance Method
(Optional) | Specifies the distance measurement method that will be used when calculating motion statistics.
| String |
Idle Distance Tolerance
(Optional) | The maximum distance that two sequential points in a track can be apart and still be considered idle. This parameter is used with the Idle Time Tolerance parameter to determine whether an entity is idling. The Idle Distance Tolerance parameter is required if the Idle statistic group is specified for the Motion Statistics parameter or if statistics in all the groups will be calculated. | Linear Unit |
Idle Time Tolerance
(Optional) | The minimum duration that two sequential points in a track must be near each other to be considered idle. This parameter is used with the Idle Distance Tolerance parameter to determine whether an entity is idling. The Idle Time Tolerance parameter is required if the Idle statistic group is specified for the Motion Statistics parameter or if statistics in all the groups will be calculated. | Time 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. | Date |
Distance Unit
(Optional) | Specifies the unit of measure that will be used for distance values in the output feature class.
| String |
Duration Unit
(Optional) | Specifies the unit of measure that will be used for duration values in the output feature class.
| String |
Speed Unit
(Optional) | Specifies the unit of measure that will be used for speed values in the output feature class.
| String |
Acceleration Unit
(Optional) | Specifies the unit of measure that will be used for acceleration values in the output feature class.
| String |
Elevation Unit
(Optional) | Specifies the unit of measure that will be used for elevation values in the output feature class.
| String |
Summary
Calculates motion statistics for points in a time-enabled feature class.
Illustration
Usage
The result of Calculate Motion Statistics is a copy of the input points with a new field for each calculated statistic.
You can specify one or more fields to identify unique entities, also known as tracks. Tracks are represented by the unique combination of one or more track fields. For example, if the flightID and Destination fields are used as track identifiers, the ID007, Solden, ID007, and Tokoyo features would be in two separate tracks, since they have different Destination field values.
By default, all supported statistics will be calculated for each input point if possible. Alternatively, you can choose one or more groups of statistics to calculate using the Motion Statistics parameter.
The following statistics fields will be calculated for the Distance group:
- Distance—Distance traveled from the previous observation to the current.
- TotDistance—Sum of distances traveled between observations in the track history window.
- MinDistance—Minimum of distances traveled between observations in the track history window.
- MaxDistance—Maximum of distances traveled between observations in the track history window.
- AvgDistance—Average of distances traveled between observations in the track history window.
The following statistics fields will be calculated for the Speed group:
- Speed—Speed of travel from the previous observation to the current.
- MinSpeed—Minimum speed between observations in the track history window.
- MaxSpeed—Maximum speed between observations in the track history window.
- AvgSpeed—Sum of distances between observations in the track history window divided by the sum of durations between observations in the track history window.
The following statistics fields will be calculated for the Acceleration group:
- Acceleration—Difference between the current speed and previous speed divided by the current duration.
- MinAcceleration—Minimum acceleration calculated in the track history window.
- MaxAcceleration—Maximum acceleration calculated in the track history window.
- AvgAcceleration—Difference between the current and first speeds in the track history window divided by the sum of durations between observations in the track history window.
The following statistics fields will be calculated for the Duration group:
- Duration—Elapsed time since the previous observation.
- TotDuration—Sum of durations in the track history window.
- MinDuration—Minimum duration in the track history window.
- MaxDuration—Maximum duration in the track history window.
- AvgDuration—Sum of durations in the track history window divided by the number of durations calculated in the track history window.
The following statistics fields will be calculated for the Elevation group:
- Elevation—Current elevation of the observation.
- ElevChange—Difference between the current elevation and the previous elevation.
- TotElevChange—Sum of elevation changes between points in the track history window. This can be a negative value.
- MinElevation—Minimum elevation in the track history window.
- MaxElevation—Maximum elevation in the track history window.
- AvgElevation—Sum of elevations in the track history window divided by the number of observations in the track history window.
The following statistics fields will be calculated for the Slope group:
- Slope—Ratio of elevation change to distance between the current and previous observations.
- MinSlope—Minimum slope in the track history window.
- MaxSlope—Maximum slope in the track history window.
- AvgSlope—Sum of slopes in the track history window divided by the number of slopes calculated in the track history window.
The following statistics fields will be calculated for the Idle group:
- Idling—True if the distance between the current observation and the previous is less than the Idle Distance Tolerance parameter value, and the duration between the current observation and the previous is greater than the Idle Time Tolerance parameter value. False if one or both of these conditions are not met.
- TotIdleTime—Sum of durations in the track history window that meet idling criteria.
- PctIdleTime—Percentage of time for which idling was detected.
The following statistics field will be calculated for the Bearing group:
- Bearing—Angle of travel from the previous observation to the current observation.
Statistics starting with Min, Max, Avg, or Tot will be calculated using the current observation and a number of previous observations defined by the Track History Window parameter. Other statistics are always calculated using only the current and previous observation and do not consider the Track History Window values. For example, if you set a Track History Window value of 5 and request the Speed statistic group, the current observation and the previous 4 observations will be used to calculate the MinSpeed, MaxSpeed, and AvgSpeed fields at each observation, while the Speed field will be calculated using only the current and previous observations at each point. The Track History Window parameter value must be greater than 1. The default is 3.
The diagram below shows a track with six point features. The statistics are calculated based on each feature's elevation, distance, and time.
The following table summarizes the statistics calculations for the diagram above. All calculations are evaluated at point 5 and the track history window is 3. An observation is considered idling if it has moved less than 32 meters in 1 minute.
Statistic Formula Example Distance
35 m
Total Distance
80 + 30 + 35 = 145 m
Speed
Distance / Duration
35 / 60 = 0.58 m/s
Average Speed
Total Distance / Total Duration
145 / 180 m/s
Acceleration
(0.58 – 0.5) / 60 = 0.001 m/s2
Average Acceleration
(Speed (last) – Speed (first)) / (Total Duration)
(0.58 – 1.33) / 60 = -0.01 m/s2
Duration
60 s
Total Duration
60 + 60 + 60 = 180 s
Elevation
5 m
Elevation Change
5 – 4 = 1 m
Total Elevation Change
5 – 0 = 5 m
Slope
Elevation Change / Distance
1 / 35
Average Slope
Total Elevation Change / Total Distance
5 / 145
Idling
False
Total Idle Time
60 s
Percentage Idle Time
1 / 3
Bearing
0
If there are fewer observations in a track's history than the Track History Window parameter value, statistics starting with Min, Max, Avg, or Tot will be calculated using all observations in the track history.
Statistics will not be calculated for the first feature in each track. Statistics in the Acceleration group will not be calculated for the first two features in each track.
The result values will be in the units specified by the Distance Unit, Duration Unit, Speed Unit, Acceleration Unit, and Elevation Unit parameters.
When calculating statistics on large tracks, you can use the Time Boundary Split parameter to split the large tracks into smaller tracks to improve performance.
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.
You can improve the performance of the Calculate Motion Statistics tool by doing any or all of the following:
- Set the extent environment so you only analyze data of interest.
- Decrease the Track History Window parameter value.
- Use the Time Boundary Split parameter to break up large tracks at a defined time interval.
- Use data that is local to where the analysis is being run.
Parameters
arcpy.geoanalytics.CalculateMotionStatistics(input_layer, out_feature_class, track_fields, {track_history_window}, {motion_statistics}, {distance_method}, {idle_dist_tolerance}, {idle_time_tolerance}, {time_boundary_split}, {time_boundary_reference}, {distance_unit}, {duration_unit}, {speed_unit}, {acceleration_unit}, {elevation_unit})| Name | Explanation | Data Type |
input_layer | The time-enabled point features on which motion statistics will be calculated. | Feature Layer |
out_feature_class |
The output feature class or layer containing the points with new fields for each motion statistic that was calculated. | Feature Class |
track_fields [track_fields,...] |
One or more fields that will be used to identify distinct entities. | Field |
track_history_window (Optional) |
The number of observations (including the current observation) that will be used for summary statistics. The default value is 3, which means that the summary statistics will be calculated at each point in a track using the current observation and the previous two observations. This parameter does not affect instantaneous statistics or idle classification. | Long |
motion_statistics [motion_statistics,...] (Optional) | Specifies the group containing the statistics that will be calculated and written to the result. If no value is specified, all statistics from all groups will be calculated.
| String |
distance_method (Optional) | Specifies the distance measurement method that will be used when calculating motion statistics.
| String |
idle_dist_tolerance (Optional) | The maximum distance that two sequential points in a track can be apart and still be considered idle. This parameter is used with the idle_time_tolerance parameter to determine whether an entity is idling. The idle_dist_tolerance parameter is required if the IDLE statistic group is specified for the motion_statistics parameter or if statistics in all the groups will be calculated. | Linear Unit |
idle_time_tolerance (Optional) | The minimum duration that two sequential points in a track must be near each other to be considered idle. This parameter is used with the idle_dist_tolerance parameter to determine whether an entity is idling. The idle_time_tolerance parameter is required if the IDLE statistic group is specified for the motion_statistics parameter or if statistics in all the groups will be calculated. | Time 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. | Date |
distance_unit (Optional) | Specifies the unit of measure that will be used for distance values in the output feature class.
| String |
duration_unit (Optional) | Specifies the unit of measure that will be used for duration values in the output feature class.
| String |
speed_unit (Optional) | Specifies the unit of measure that will be used for speed values in the output feature class.
| String |
acceleration_unit (Optional) | Specifies the unit of measure that will be used for acceleration values in the output feature class.
| String |
elevation_unit (Optional) | Specifies the unit of measure that will be used for elevation values in the output feature class.
| String |
Code sample
The following stand-alone script demonstrates how to use the CalculateMotionStatistics function.
# Name: CalculateMotionStatistics.py
# Description: Calculate speed, acceleration, and bearing for hurricane tracks.
# Import system modules
import arcpy
arcpy.env.workspace = "C:/data/Weather.gdb"
# 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\Hurricanes.lyrx'
# MakeFeatureLayer converts the .lyrx to features
hurricanesInputLayer = arcpy.management.MakeFeatureLayer(inputLyrx, "Hurricanes_layer")
# ApplySymbologyFromLayer sets the time using the .lyrx file definition
arcpy.management.ApplySymbologyFromLayer(hurricanesInputLayer, inputLyrx)
# Set local variables
trackField = "name"
out = "Hurricanes_MotionStats"
# Run Calculate Motion Statistics
arcpy.gapro.CalculateMotionStatistics(hurricanesInputLayer, out, trackField, 5,
["SPEED", "ACCELERATION", "BEARING"],
"GEODESIC")