The PARTICLE_TRACE procedure traces the path of a massless particle through a vector field, given a set of starting points (or seed points).

Particles are tracked by treating the vector field as a velocity field and integrating. Each particle is tracked from the seed point until the path leaves the input volume or a maximum number of iterations is reached. The vertices generated along the paths are returned packed into a single array along with a polyline connectivity array. The polyline connectivity array organizes the vertices into separate paths (one per seed). Each path has an orientation. The initial orientation may be set using the SEED_NORMAL keyword. As a path is tracked, the change in the normal is also computed and may be returned to the user as the optional Normals argument.

Path output can be passed directly to an IDLgrPolyline object or passed to the STREAMLINE procedure for generation of ribbons. Control over aspects of the integration (e.g. method or stepsize) is also provided.


The following procedure calculates the path of three particles through a vector field representing wind and plots it against a background displaying the vector field itself.

PRO ex_particle_trace2
  ; Restore u, v, x, and y variables containing wind data
  RESTORE, FILEPATH('globalwinds.dat', $
  ; Build a data array from the wind data.
  data = FLTARR(2, 128, 64)
  data[0, *, *] = u
  data[1, *, *] = v
  ; Define starting points for the streamlines
  seeds = [[32, 32], [64, 32], [96, 32]]
  ; Calculate the vertext and connectivity data for the
  ; streamline paths
  PARTICLE_TRACE, data, seeds, verts, conn, MAX_ITERATIONS=30
  ; Plot the underlying vector field
  VELOVECT, u, v, x, y, COLOR='AAAAAA'x
  ; Overplot the streamlines
  i = 0
  sz = SIZE(verts, /STRUCTURE)
  WHILE (i LT sz.dimensions[1]) DO BEGIN
     nverts = conn[i]
  ; OLD METHOD: Uses 'x' and 'y' as lookup tables, losing the fractional
  ;                part of the result, ending up only using data grid points.
  PLOTS, x[verts[0, conn[i+1:i+nverts]]], $
     y[verts[1, conn[i+1:i+nverts]]], $
     COLOR='0000FF'x, THICK=2
  ; NEW METHOD: Find 'index' locations of desired points, then scale them
  ;                correctly to exact degrees. Plotting both to show improvement.
  xIndices = verts[0, conn[i+1:i+nverts]]
  yIndices = verts[1, conn[i+1:i+nverts]]
  xDeg = (xIndices / 128) * 360 - 180
  yDeg = (yIndices /  64) * 180 -  90
  PLOTS, xDeg, yDeg, COLOR='0000FF'x, THICK=2
  i += nverts + 1


PARTICLE_TRACE, Data, Seeds, Verts, Conn [, Normals] [, MAX_ITERATIONS=value] [, ANISOTROPY=array] [, INTEGRATION={0 | 1}] [, SEED_NORMAL=vector] [, TOLERANCE=value] [, MAX_STEPSIZE=value] [, /UNIFORM]



A three- or four-dimensional array that defines the vector field. Data can be of dimensions [2, dx, dy] for a two-dimensional vector field or [3, dx, dy, dz] for a three-dimensional vector field, where:

  • Data[0,*,*] or Data[0,*,*,*] contains the X components of the two- or three-dimensional vector field (commonly referred to as U).
  • Data[1,*,*] or Data[1,*,*,*] contains the Y components of the two- or three-dimensional vector field (commonly referred to as V).
  • Data[2,*,*,*] contains the Z components of the three-dimensional vector field (commonly referred to as W).


An array of two- or three-element vectors ([2, n] or [3, n]) specifying the indices of the n points in the Data array at which the tracing operation is to begin. The result will be n output paths.


A named variable that will contain the output path vertices as a [2, n] or [3, n] array of floating-point values.


A named variable that will contain the output path connectivity array in IDLgrPolyline POLYLINES keyword format. There is one set of line segments in this array for each input seed point.


A named variable that will contain the output normal estimate at each output vertex ([3, n] array of floats).



Set this input keyword to a two- or three- element array describing the distance between grid points in each dimension. The default value is [1.0, 1.0, 1.0] for three-dimensional data and [1.0, 1.0] for two-dimensional data.


Set this keyword to one of the following values to select the integration method:

  • 0 = 2nd order Runge-Kutta (the default)
  • 1 = 4th order Runge-Kutta


Set this keyword to a three-element vector which selects the initial normal for the paths. The default value is [0.0, 0.0, 1.0]. This keyword is ignored for 2-D data.


This keyword is used with adaptive step-size control in the 4th order Runge-Kutta integration scheme. It is ignored if the UNIFORM keyword is set or the 2nd order Runge-Kutta scheme is selected.


This keyword specifies the maximum number of line segments to return for each path. The default value is 200.


This keyword specifies the maximum path step size. The default value is 1.0.


If this keyword is set, the step size will be set to a fixed value, set via the MAX_STEPSIZE keyword. If this keyword is not specified, and TOLERANCE is either unspecified or inapplicable, then the step size is computed based on the velocity at the current point on the path according to the formula:

      stepsize = MIN(MaxStepSize, MaxStepSize/MAX(ABS(U), ABS(V), ABS(W)))

where (U,V,W) is the local velocity vector.

Version History