Particle Track (Spatial Analyst Tools)

Summary

Calculates the path of a particle through a velocity field, returning an ASCII file of particle tracking data and, optionally, a feature class of track information.

Learn more about how Particle Track works

Usage

The input direction and magnitude rasters should be from the same run of the Darcy Flow tool.

The path file generated by this tool is an ASCII text file containing information about position, local velocity direction and magnitude, and cumulative length and time of travel along the path. This file is used for input by Porous Puff. The format of this file is as follows:

time         x            y            length       flow dir     flow mag
0.000000000  0.000000000  482.8400000  0.000000000  90.00000000  0.04418909563
113.1648712  4.999804443  482.7957786  5.000000000  91.01366126  0.04418332249
226.2741353  9.998043277  482.6630814  10.00000000  92.02765240  0.04420504404
339.3574334  14.99315255  482.4419855  15.00000000  93.04094157  0.04421519432
452.3447720  19.98356700  482.1325285  20.00000000  94.05521317  0.04425274599
565.2657591  24.96772671  481.7348453  25.00000000  95.06807622  0.04427874865
678.0514031  29.94406931  481.2490323  30.00000000  96.08254679  0.04433188322
790.7309576  34.91104149  480.6752838  35.00000000  97.09488082  0.04437362239

No particular system of units is specified by Particle Track. It is important that all data be in a consistent set of units, using the same unit for time (seconds, days, years) and length (feet, meters).
The source location must be within the boundary of the input rasters and cannot be in an area of NoData.
The track file will end if the track reaches outside the study area and has not met the specified maximum tracking time.
If the particle being tracked has reached the edge of the study area at the indicated time and the predictor point is outside the study area, the track file will end.
If the particle being tracked migrates into a depression at the indicated time, the track file will end. A depression can be created by a discharge well or other sink.
The two outputs from this tool are:
1. A particle track ASCII file using the name specified as output particle track file
2. An optional polyline feature class
See Analysis environments and Spatial Analyst for additional details on the geoprocessing environments that apply to this tool.

Label	Explanation	Data type
Input direction raster	An input raster where each cell value represents the direction of the seepage velocity vector (average linear velocity) at the center of the cell. Directions are expressed in compass coordinates, in degrees clockwise from north. This can be created by the Darcy Flow tool. Direction values must be floating point.	Raster Layer
Input magnitude raster	An input raster where each cell value represents the magnitude of the seepage velocity vector (average linear velocity) at the center of the cell. Units are length/time. This can be created by the Darcy Flow tool.	Raster Layer
Source point	The location of the source point from which to begin the particle tracking. This is entered as numbers identifying the x,y coordinates of the position in map units.	Point
Output particle track file	The output ASCII text file that contains the particle tracking data.	File
Step length (Optional)	The step length to be used for calculating the particle track. The default is one-half the cell size. Units are length.	Double
Tracking time (Optional)	Maximum elapsed time for particle tracking. The algorithm will follow the track until either this time is met or the particle migrates off the raster or into a depression. The default value is infinity. Units are time.	Double
Output track polyline features (Optional)	The optional output line feature class containing the particle track. This feature class contains a series of arcs with attributes for position, local velocity direction and magnitude, and cumulative length and time of travel along the path.	Feature Class

ParticleTrack(in_direction_raster, in_magnitude_raster, source_point, out_track_file, {step_length}, {tracking_time}, {out_track_polyline_features})

Name	Explanation	Data type
in_direction_raster	An input raster where each cell value represents the direction of the seepage velocity vector (average linear velocity) at the center of the cell. Directions are expressed in compass coordinates, in degrees clockwise from north. This can be created by the Darcy Flow tool. Direction values must be floating point.	Raster Layer
in_magnitude_raster	An input raster where each cell value represents the magnitude of the seepage velocity vector (average linear velocity) at the center of the cell. Units are length/time. This can be created by the Darcy Flow tool.	Raster Layer
source_point	A Python `Point` class object denotes the location of the source point, in map units, from which to begin the particle tracking. The form of the object is: point(x,y)	Point
out_track_file	The output ASCII text file that contains the particle tracking data.	File
step_length (Optional)	The step length to be used for calculating the particle track. The default is one-half the cell size. Units are length.	Double
tracking_time (Optional)	Maximum elapsed time for particle tracking. The algorithm will follow the track until either this time is met or the particle migrates off the raster or into a depression. The default value is infinity. Units are time.	Double
out_track_polyline_features (Optional)	The optional output line feature class containing the particle track. This feature class contains a series of arcs with attributes for position, local velocity direction and magnitude, and cumulative length and time of travel along the path.	Feature Class

Code sample

ParticleTrack example 1 (Python window)

This example executes the tool on the required inputs and outputs an ASCII file of particle tracking data and a shapefile featureclass of the particle track.

import arcpy
from arcpy import env
from arcpy.sa import *
env.workspace = "C:/sapyexamples/data"
ParticleTrack("gwdir", "gwmag", arcpy.Point(-200,-200),
              "C:/sapyexamples/output/trackfile.txt",10, 100000,
              "C:/sapyexamples/output/trackpolyline.shp")

ParticleTrack example 2 (stand-alone script)

This example executes the tool on the required inputs and outputs an ASCII file of particle tracking data and a shapefile featureclass of the particle track.

# Name: ParticleTrack_Ex_02.py
# Description: Calculates the path of a particle through a velocity field.
# Requirements: Spatial Analyst extension

# Import system modules
import arcpy
from arcpy import env
from arcpy.sa import *

# Set environment settings
env.workspace = "C:/sapyexamples/data"

# Set local variables
inDirectionRaster = "gwdir"
inMagnitudeRaster = "gwmag"
sourcePoint = arcpy.Point(-200, -200)
outTrackFile = "C:/sapyexamples/output/trackfile.txt"
stepLength = 10
trackingTime = 10000000
outTrackPolylineFeatures = "C:/sapyexamples/output/trackpolyline.shp"

# Run ParticleTrack
ParticleTrack(inDirectionRaster, inMagnitudeRaster, sourcePoint, outTrackFile,
              stepLength, trackingTime, outTrackPolylineFeatures)

Environments

Auto Commit, Cell Size, Cell Size Projection Method, Current Workspace, Default Output Z Value, Extent, Geographic Transformations, M Resolution, M Tolerance, Output CONFIG Keyword, Output Coordinate System, Output has M values, Output has Z values, Output M Domain, Output XY Domain, Output Z Domain, Scratch Workspace, XY Resolution, XY Tolerance, Z Resolution, Z Tolerance

Licensing information