# Input and Output Routines¶

The main entry points for using the module are the trajectories() function (or its counterpart :funciter_trajectories) for reading the data for a scene; and either save_trajectories() or save_particles_table() for saving scene data in, respectively, an obsolete format based on a directory of NPZ files, or in the newer, recommended, HDF5 format.

The trajectory reader, unless otherwise noted, will try to infer the format from the file name (see infer_format()).

The rest of the content of this module is composed of readers and writers for the various formats. They are documented here alongside the main entry points, so that users may access them directly if needed.

flowtracks.io.infer_format(fname)[source]

Try to guess the format of a particles data file by its name.

Arguments

• fname: the file name from which to guess the format.

Returns

A string marking the format. Currently one of ‘acc’, ‘mat’, ‘xuap’, ‘npz’, ‘hdf’ or ‘ptvis’.

flowtracks.io.iter_trajectories_ptvis(fname, first=None, last=None, frate=1.0, xuap=False, traj_min_len=None)[source]

Extract all trajectories in a directory of ptv_is/xuap files, as generated by programs in the 3d-ptv/pyptv family.

Arguments

• fname: a template file name representing all ptv_is/xuap files in the directory, with exactly one ‘%d’ representing the frame number. If no ‘%d’ is found, the input is assumed to be in the Ron Shnapp format- single file of concatenated ptv_is files, each stripped of the particle count line (first line) and separated from the next by an empty line.
• first, last: inclusive range of frames to read, rel. filename numbering.
• frate: frame rate, used for calculating velocities by backward derivative.
• xuap: The format is extended with colums for velocity and acceleration.
• traj_min_len: do not include trajectories shorter than this many frames.

Yields

each of the trajectories in the ptv_is data in order, as a Trajectory instance with velocity and acceleration.

flowtracks.io.load_trajectories(res_dir, first=None, last=None)[source]

Load a series of trajectories and associated data from a directory containing npz trajectory files, as created by save_trajectories().

Arguments

• res_dir: path to the directory holding the trajectory files.

Returns

• trajects: a list of Trajectory objects created from the files is res_dir
• per_traject_adds: a dictionary of named added date. Each value is a dictionary keyed by trajid.
flowtracks.io.read_frame_data(conf_fname)[source]

Read a configuration file in INI format, which specifies the locations where particle positions and velocities should be read from, and directly stores some scalar frame values, like particle densidy etc.

Arguments

• conf_fname: name of the config file

Returns

• particle: a Particle object holding particle properties.
• frate: the frame rate at which the scene was shot.
• frame, next_frame: Frame objects holding the tracers and particles data for the time points indicated in config, and the one immediately following it.
flowtracks.io.save_particles_table(filename, trajects, trim=None)[source]

Save trajectory data as a table of particles, with added columns for time (frame number) and trajid - the last one may be indexed. Note that no extra (per-trajectory or meta) data is allowed here, unlike the npz save format.

Arguments

• filename: name of output PyTables HDF5 file to create. The ‘h5’ extension is recommended so that infer_format() knows what to do with it.
• trajects: a list of Trajectory objects to save.
• trim: if None, remove this many time points from each end of each trajectory before saving.
flowtracks.io.save_trajectories(output_dir, trajects, per_traject_adds, **kwds)[source]

Save for each trajectory the data for this trajectory, as well as additional data attached to each trajectory, such as trajectory reconstructions. Creates in the output directory one npz file per trajectory, containing the arrays of the trajectory as well as the added arrays.

Arguments

• output_dir: name of the directory where output should be placed. Will be created if it does not exist.
• trajects: a list of Trajectory objects.
• per_traject_adds: a dictionary, whose keys are the array names to use when saving, and vaslues are trajid-keyed dictionaries with the actual arrays to save for each trajectory.
• kwds: free arrays to save in the output dir
flowtracks.io.trajectories(fname, first, last, frate, fmt=None, traj_min_len=None, iter_allowed=False)[source]

Extract all trajectories in a given target location. The location format is interpreted based on the format of the data files, in the respective trajectories_* functions.

Trajectories of one frame are filtered out.

Arguments

• fname: a template file name, as needed by the appropriate suboridinate function.
• first, last: inclusive range of frames to read, rel. filename numbering.
• frate: frame rate under which the film was shot - needed for ptvis trajectories.
• traj_min_len: on some formats, (currently ptv_is and xuap) it is possible to filter trajectories with less frames than this, saving memory.
• iter_allowed: may return an iterator instead of a list.

Returns

a list (or iterator) of Trajectory objects.

flowtracks.io.trajectories_acc(fname, first=None, last=None)[source]

Extract all trajectories in a directory of trajAcc files.

Arguments

• fname: a template file name representing all trajAcc files in the directory, with exactly one ‘%d’ representing the frame number.
• first, last: inclusive range of frames to read, rel. filename numbering.

Returns

• trajects: a list of Trajectory objects, one for each trajectory contained in the mat file.
flowtracks.io.trajectories_mat(fname)[source]

Extracts all trajectories from a Matlab file. the file is formated as a list of trajectory record arrays, containing attributes ‘xf’, ‘yf’, ‘zf’ for position, ‘uf’, ‘vf’, ‘wf’ for velocity, and ‘axf’, ‘ayf’, ‘azf’ for acceleration.

Arguments

• fname: path to the Matlab file.

Returns

• trajects: a list of Trajectory objects, one for each trajectory contained in the mat file.
flowtracks.io.trajectories_ptvis(fname, first=None, last=None, frate=1.0, xuap=False, traj_min_len=None)[source]

Extract all trajectories in a directory of ptv_is files, as generated by programs in the 3d-ptv/pyptv family. supports xuap files as well.

Arguments

• fname: a template file name representing all ptv_is/xuap files in the directory, with exactly one ‘%d’ representing the frame number. If no ‘%d’ is found, the input is assumed to be in the Ron format - single file of concatenated ptv_is files, each stripped of the particle count line (first line) and separated from the next by an empty line.
• first, last: inclusive range of frames to read, rel. filename numbering.
• frate: frame rate, used for calculating velocities by backward derivative.
• xuap: The format is extended with colums for velocity and acceleration.
• traj_min_len: do not include trajectories shorter than this many frames.

Returns

each of the trajectories in the ptv_is/xuap data in order, as a Trajectory instance with velocity and acceleration.

flowtracks.io.trajectories_table(fname, first=None, last=None)[source]

Reads trajectories from a PyTables HDF5 file, as saved by save_particles_table().

Arguments

• fname: path to file to read.
• first, last: inclusive range of frames to read.

Returns

• trajects: a list of Trajectory objects, each trimmed to the frame range.