Help

Particle Track

Available with Spatial Analyst license.

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.

Syntax

ParticleTrack (in_direction_raster, in_magnitude_raster, source_point, out_track_file, {step_length}, {tracking_time}, {out_track_polyline_features})
ParameterExplanationData 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

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
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"

# Check out the ArcGIS Spatial Analyst extension license
arcpy.CheckOutExtension("Spatial")

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

Environments

Licensing Information

  • ArcGIS for Desktop Basic: Requires Spatial Analyst
  • ArcGIS for Desktop Standard: Requires Spatial Analyst
  • ArcGIS for Desktop Advanced: Requires Spatial Analyst

Related Topics

Feedback on this topic?