Classify Movement Events (Intelligence)

Summary

Identifies turn events, acceleration events, and speed from an input point track dataset.

Illustration

Classify Movement Events tool illustration

Usage

  • For the tool to run, the Input Features parameter value must be in a projected coordinate system and it must be time enabled.

    The tool will identify the following events:

    • Right or left turn
    • Right or left U-turn
    • Acceleration
    • Deceleration
    • Start
    • Stop
    • Speed in miles per hour
    • Speed in kilometers per hour
    • From bearing
    • To bearing

    Additionally, the distance difference and time difference between the current point and the previous point in the track will be calculated.

    Optionally, a region of interest point will be located.

  • Turns are annotated based on the direction of travel. Turns can be categorized as follows:

    • Right turn
    • Left turn
    • Right U-turn
    • Left U-Turn
    • Stopped
    • Traveling

    Turns are calculated using the Curvature and Number Of Points parameters. Each point is evaluated based on the bearing from the previous point in the track to the current point and from the current point to the next point in the track. If the value exceeds the value specified for the Curvature parameter, it is considered a turn; otherwise, it is considered to be traveling. For tracks representing large objects such as aircraft or ships, it is recommended that you increase the Number Of Points parameter value to account for the longer amount of time to conduct a turn.

    Bearing calculations
    Bearing is calculated from the previous point to the current point and from the current point to the next point, and the difference is used to determine turn events.

  • The default values for the Curvature and Number Of Points parameters are optimized for typical automobile tracks assuming an approximate one-second sampling rate. For vehicles that move faster than automobiles or data that is sampled in an interval that is not once per second, you may need to change the Curvature or Number Of Points parameter value. For example, for a personal GPS device that samples once every five seconds, increase the Number Of Points value. For data that represents aircraft that is sampled once every second, adjust the Curvature parameter value down to 10 or lower to account for the greater amount of time and space that is required for an aircraft to make a turn.

    Difference in turning radius between smaller objects and larger objects
    Smaller objects such as people and cars require less distance to turn than larger objects such as aircraft and ships.

  • Speed is calculated using the distance between points divided by the amount of time needed to travel that distance. Stops are identified when a vehicle has a velocity of zero. Starts are determined from when points accelerate from a stopped position.

    The acc_event field is calculated using the difference of the current point in the track and the previous point in the track and between the current point and the next point in the track. Specific acceleration events include the following:

    • Start of acceleration event—The point where the track begins to speed up. The current point is proceeded by a point of equal speed and followed by a point with a higher speed.

    • Start of deceleration event—The point where the track begins to slow down. The current point is proceeded by a point of equal speed and followed by a point with a lower speed.

    • Acceleration—The point track has increasing speed between the previous point and current point. This must come after the start of acceleration and before the end of an acceleration event.

      Acceleration and deceleration events calculation
      Acceleration and deceleration events are calculated using the average speed between points.

    • Deceleration—The point track has decreasing speed between the previous point and the current point. This must come after the start of a deceleration event and before the end of a deceleration event.

    • End of acceleration event—The point where an acceleration event stops. The current point has a higher speed than the previous point, but the following point is of the same or lower speed. This is typically followed by either a traveling or a deceleration event.

    • End of deceleration event—The point where a deceleration event stops. The current point has a lower speed than the previous point, but the following point is of the same or higher speed. This is typically followed by a stopped or an acceleration event.

    • Stopped—The point track is not moving. The speed must be equal to 0 mph or 0 kph.

    • Traveling—The point track is moving at a speed that does not fall into any of the previous categories.

  • The output feature class will contain the following fields:

    • track_id—The unique identifier associating the point to a track. This field is derived from the ID Field parameter.
    • time—The time associated with the point track feature. This field is derived from the time field specified in the layer properties.
    • source_OID—The Object ID of the feature derived from the Input Features parameter.
    • POINT_X—The x-coordinate associated with the current feature.
    • POINT_Y—The y-coordinate associated with the current feature.
    • distance_diff—The distance between the previous feature in the track and the current feature. The distance is calculated in the units of the input's coordinate system.
    • time_diff—The difference in seconds between the previous feature in the track and the current feature.
    • speed—The speed in the linear units of the input coordinate system per second.
    • speed_mph—The speed in miles per hour of the track from the previous feature in the track to the current feature.
    • speed_kph—The speed in kilometers per hour of the track from the previous feature in the track to current feature.
    • acc_event—Acceleration events. Specific acceleration events include the following
      • Start of acceleration event
      • Start of deceleration event
      • Acceleration
      • Deceleration
      • End of acceleration event
      • End of deceleration event
      • Stopped
      • Traveling
    • turn_event—A turn event. Specific turn events include the following:
      • Left turn
      • Right turn
      • Left U-turn
      • Right U-turn
      • Stopped
      • Traveling
    • from_bearing—The bearing from the previous point in the track to the current point.
    • to_bearing—The bearing from the current point in the track to the next point.

    If the Regions Of Interest parameter value has an associated feature class, a roi_id field will be populated. This field will include the region of interest that the point intersects.

    If the Create Turn Event Identifiers parameter is checked, the output attribute table will include a turn_event_id field that contains the unique identifier created for each unique turn event. If a turn event has multiple features associated with it, each feature will share the same turn_event_id value.

  • The from_bearing and to_bearing fields are included and are primarily intended to help understand directionality of travel and help with applying symbology to orient correctly with the direction of travel. The key difference between these fields is that the from_bearing field represents a back angle from the current point to the previous point of the track.

  • If the Exclude Non-Turn Events parameter is checked, the tool removes any features in the turn_event field that have the Traveling value. This can reduce the size of the output feature class and can improve performance. This is recommended when you want to identify where and how often an intersection is used or where a particular track conducted a turn event for use in forensic analysis.

  • If the Turn Events Feature Representation parameter is set to Turn midpoint, all turn event features that share the same turn_event_id value will be aggregated to the feature's mean center. This is a reductive process that will remove all of the associated features and leave a single feature at the calculated mean center of the turn event. Due to the destructive nature of this parameter, it is best used with the Exclude Non-Turn Events parameter checked.

Parameters

LabelExplanationData Type
Input Features

A time-enabled point feature layer with a field annotating the track with which each point is associated. The geometry, object identifier, track name, and time will be transferred to the output feature class. The input must be in a projected coordinate system.

Feature Layer
ID Field

A field from the input features that will be used to obtain the unique identifiers per point track. The field will be copied to the output feature class.

Field
Output Feature Class

The output feature class that will contain the calculated movement events.

Feature Class
Curvature
(Optional)

The minimum value that is necessary for an event to be classified as a turn event. After the curvature is calculated, any calculated curvature greater than this value will cause the turn_event field to be populated with the relevant turn event, while values less than this will cause the turn_event field to be classified as traveling.

Turns are calculated using the Curvature and Number Of Points parameters. Each point is evaluated based on the bearing from the previous point in the track to the current point and from the current point to the next point in the track. If the value exceeds the value specified for the Curvature parameter, it is considered a turn. Otherwise, it is considered to be traveling. For tracks representing large objects, it is recommended that you increase the Number Of Points value to account for the longer amount of time to conduct a turn.

Double
Number Of Points
(Optional)

The number of points that will be evaluated before and after a given point when calculating the bearing difference. When using data with a high sampling rate (subsecond), you may need to increase the Number Of Points parameter value to account for the decreased movement that is possible in that brief time period. A value of 1 is suitable for automobiles and pedestrians assuming a one-second sampling on the input data. Larger values are necessary for aircraft and ships; use a value of 5 for these.

Long
Regions Of Interest
(Optional)

The regions of interest. This input feature layer must be a polygon feature class. If a value is provided, a roi field will be added to the Output Feature Class parameter.

Feature Layer
Regions Of Interest ID Field
(Optional)

A field from the Regions Of Interest parameter that contains the unique identifiers for each region of interest.

Field
Create Turn Event Identifiers
(Optional)

Specifies whether turn event identifiers will be created for the output feature class.

  • Checked—Unique turn event identifiers will be created.
  • Unchecked—Unique turn event identifiers will not be created. This is the default.

Boolean
Exclude Non-Turn Events
(Optional)

Specifies whether features with a turn_event field value of Traveling will be excluded.

  • Checked—Features with a turn_event field value of Traveling will be excluded.
  • Unchecked—Features with a turn_event field value of Traveling will not be excluded; all features will be returned. This is the default.

Boolean
Turn Events Feature Representation
(Optional)

Specifies how the output turn events will be represented.

  • All featuresAll points associated with the turn event will be returned. This is the default.
  • Turn midpointThe mean center of the turn event will be returned.
String

arcpy.intelligence.ClassifyMovementEvents(in_features, id_field, out_featureclass, {curvature}, {number_of_points}, {regions_of_interest}, {roi_id_field}, {include_turn_ids}, {exclude_non_turn_events}, {turn_events_representation})
NameExplanationData Type
in_features

A time-enabled point feature layer with a field annotating the track with which each point is associated. The geometry, object identifier, track name, and time will be transferred to the output feature class. The input must be in a projected coordinate system.

Feature Layer
id_field

A field from the input features that will be used to obtain the unique identifiers per point track. The field will be copied to the output feature class.

Field
out_featureclass

The output feature class that will contain the calculated movement events.

Feature Class
curvature
(Optional)

The minimum value that is necessary for an event to be classified as a turn event. After the curvature is calculated, any calculated curvature greater than this value will cause the turn_event field to be populated with the relevant turn event, while values less than this will cause the turn_event field to be classified as traveling.

Turns are calculated using the curvature and number_of_points parameters. Each point is evaluated based on the bearing from the previous point in the track to the current point and from the current point to the next point in the track. If the value exceeds the value specified for the curvature parameter, it is considered a turn. Otherwise, it is considered to be traveling. For tracks representing large objects, it is recommended that you increase the number_of_points value to account for the longer amount of time to conduct a turn.

Double
number_of_points
(Optional)

The number of points that will be evaluated before and after a given point when calculating the bearing difference. When using data with a high sampling rate (subsecond), you may need to increase the number_of_points parameter value to account for the decreased movement that is possible in that brief time period. A value of 1 is suitable for automobiles and pedestrians assuming a one-second sampling on the input data. Larger values are necessary for aircraft and ships; use a value of 5 for these.

Long
regions_of_interest
(Optional)

The regions of interest. This input feature layer must be a polygon feature class. If a value is provided, a roi field will be added to the out_featureclass parameter.

Feature Layer
roi_id_field
(Optional)

A field from the regions_of_interest parameter that contains the unique identifiers for each region of interest.

Field
include_turn_ids
(Optional)

Specifies whether turn event identifiers will be created for the output feature class.

  • INCLUDE_TURN_IDSUnique turn event identifiers will be created.
  • NO_TURN_IDSUnique turn event identifiers will not be created. This is the default.
Boolean
exclude_non_turn_events
(Optional)

Specifies whether to filter features with a turn_event field value of Traveling.

  • ONLY_TURN_EVENTSFeatures with a turn_event field value of Traveling will be excluded.
  • ALL_FEATURESFeatures with a turn_event field value of Traveling will not be excluded; all features will be returned. This is the default.
Boolean
turn_events_representation
(Optional)

Specifies how the output turn events will be represented.

String

Code sample

ClassifyMovementEvents example (stand-alone script)

The following stand-alone Python script demonstrates how to use the ClassifyMovementEvents function.

# Name: ClassifyMovementEvents.py
# Description: Identify movement events in a point track dataset. 

# Import system modules 
import arcpy 

arcpy.env.workspace = "C:/data/Tracks.gdb"

# Set local variables 
source_features = "Known_Tracks"
output_movement_events = "MovementEvents"
id_field = "device_id"
regions_of_interest = "Named_Areas_Of_Interest"
roi_name = "counties"

# Run tool
arcpy.intelligence.ClassifyMovementEvents(source_features,
                                          output_point_features,
                                          id_field,
                                          regions_of_interest,
                                          roi_name)

Licensing information

  • Basic: No
  • Standard: No
  • Advanced: Yes

Related topics