.traj Trajectory File Format

Each <xxx> is a four-byte, 32-bit value (integer int32 or IEEE floating-point float32) unless otherwise specified. The <fmtchar> byte at the beginning determines whether that's in big-endian or little-endian format. Codes for fmtchar are

• 'l' (0x6c) little-endian
• 'b' (0x62) big-endian
• 'a' (0x61) ASCII text

In the binary formats, most quantities are 32-bit; all of those are aligned to 4-byte boundaries. The format is also designed to be the streaming message format for a networked trajectory-calculating server; some of the fields aren't useful in a disk file format, and their values can be ignored.

The .traj file begins with:

• <fmtchar> (1 byte) is the message format -- here, 'l' (0x6c) little-endian binary
• 'T' (1 byte) is the message type -- 'T' (0x54) is "Trajectory"
• <pad> (2 bytes) (ignored)
• <reqno> (4-byte int32) is an arbitrary value for caller's convenience
• <groupval> (int32) and ...
• <groupmask> (int32) are two integers that determine the set of points selected for advection (in the disk file format, they'll be zeros, and can be ignored)
• <startdatatime> (float32) is the simulation timestep at which the trajectories begin, e.g. 6700.
• <duration> (float32) is the maximum integration time.
  Some trajectories may end sooner.
• <velrate> (float32) is a multiplier for fluid velocities:
  d<position>/dt = flow_velocity * <velrate>
• <datarate> (float32) is a multiplier that relates trajectory-time to simulation time.
  

  datarate=1	velrate=1	advects normally
  datarate=-1	velrate=1	follows particles backwards in time
  datarate=0		looks at just the single timestep at <startdatatime>

• <sampledt> (float32) gives the trajectory-time ("ttime") interval for sampling particles, i.e., each particle's position will be sampled at ttime=0, ttime=sampledt, ttime=2*sampledt, etc.
• <reportIOformat> (int32)
  format of this message -- same value as <fmtchar> above, but in a 32-bit field for historical reasons.
• <reportstyle> (int32)
  currently just 'T' (0x00000054) in a 32-bit integer field. Might allow something else someday, e.g. specifying points sorted primarily by time rather than by trajectory.
• <reportinterval> (int32)
  How often (in multiples of sampledt) for a streaming server to return incrementally computed trajectories. This value isn't useful for the disk file format.

Following this come two sets of headers describing attributes. In these, each <type> is a four-byte int32 which may be either

• 'i' (0x00000069) (where the corresponding attribute is a 32-bit integer) or
• 'f' (0x00000066) (where the attribute is a 32-bit float)

• 32-bit integer length of what follows (including all trailing \0's)
• \0-terminated string, with enough extra \0's to be a multiple of 4 bytes

Given this, here's the first header:

Per-trajectory attribute header

<ntrajattrs> (int32)

number of per-trajectory attributes.

<trajattrtype0> (int32)

type ('i' or 'f') of first per-traj attribute

<trajattrname0> (string preceded by int32 length)

name of first per-traj attr

<trajattrtype1> (int32)

type ('i' or 'f') of second per-traj attribute

<trajattrname1> (string preceded by int32 length)

name of second per-traj attr

...

"id"

(type int32) particle id number; next will be

"group"

(type int32) particle group number; then comes

"ttime0"

(type float32) trajectory-time at start of this trajectory

Per-sample attribute header

There be none of these, or there might be several, e.g. "u", "v", "w", "temp", "salt" for wind velocities, temperature, and salinity, sampled at each point.

<nsampleattrs> (int32)

number of per-sample attributes

<sampattrtype0> (int32)

datatype ('i' or 'f') of first per-sample attribute

<sampattrname0> (string preceded by int32 length)

name of first per-sample attr

...

Trajectory Body

• <ntrajectories> (int32)

<nsamples> (int32)

number of samples in this trajectory

<per-trajectory-attributes>

series of <ntrajattrs> trajectory attribute values, a total of ntrajattrs*4 bytes long, of the types given in the "per-trajectory attributes" header.

<sequence of nsamples records>

each record (3+nsampleattrs)*4 bytes long:
X Y Z sampleattr0 sampleattr1 sampleattr2 ...
The X Y Z coordinates are all of type float32; other attributes have the datatypes specified in the per-sample attribute header.

In case it matters, along each trajectory, the simulation time "datatime" is related to the sample number (counting from 0) as:

datatime = startdatatime + (ttime0 + samplenumber * sampledt) * datarate

See also the .pb file format description.