Scene and Dual Scene Manipulation

A module for manipulating PTV analyses saved as HDF5 files in the flowtracks format. Allows reading the data by iterating over frames or over trajectories.

Main design goals:

1. Keep as little as possible in memory.
2. Minimize separate file accesses by allowing reading by frames instead of only by trajectories as in the old code.

class flowtracks.scene.DualScene(tracers_path, particles_path, frate, particle, frame_range=None)

Holds a scene orresponding to the dual-PTV systems, which shoot separate but coordinated streams for the tracers data and inertial particles data.

Arguments

• tracers_path, particles_path: respectively the path to the tracers and particles HDF files.
• frate: frame rate at which the scene was shot, [1/s].
• particle: a Particle object describing the inertial particles’ diameter and density.
• frame_range: a uniform frame range to set to both of them. The default is None, meaning to use all frames (assuming equal-length data streams)

get_particles()

Returns the Scene that manages inertial particles’ data.

get_particles_path()

Returns the path to the HDF file holding inertial particle data

get_range()

Returns the frame renge set for the dual scene.

iter_frames(frame_range=-1)

Iterates over a scene represented by two HDF files (one for inertial particles, one for tracers), and returns a Frame object whose two attributes (.tracers, .particles) hold a corresponding ParticleSnapshot object.

Arguments

• frame_range: tuple (first, last) sets the frame range of both scenes to an identical frame range. Argument format as in Scene.set_frame_range(). Default is (-1) meaning to skip this. Then the object’s initialization range is used, so initialize to a coordinated range if you use the default.

Yields

the Frame object for each frame in turn.

iter_segments(frame_range=-1)

Like iter_frames, but returns two consecutive frames, both having the same trajids set (in other words, both contain only particles from the first frame whose trajectory continues to the next frame).

Arguments

• frame_range: tuple (first, last) sets the frame range of both scenes to an identical frame range. Argument format as in Scene.set_frame_range(). Default is (-1) meaning to skip this. Then the object’s initialization range is used, so initialize to a coordinated range if you use the default.

Yields

two Frame objects, representing the consecutive selective frames.

class flowtracks.scene.Scene(file_name, frame_range=None)

This class is the programmer’s interface to an HDF files containing particle trajectory data. It manages access by frames or trajectories, as well as by segments.

Arguments

• file_name: path to the HDF file hilding the data.
• frame_range: use only frames in this range for iterating the data. the default is None, meaning to use all present frams.

iter_frames()

Iterator over frames. Generates a ParticleSnapshot object for each frame, in the file, ordered by frame number, and yields it.

iter_segments()

Iterates over frames, taking out only the particles whose trajectory continues in the next frame.

Yields

• frame: a ParticleSnapshot object representing the current frame with the particles that have continuing trajectories.
• next_frame: same object, for the same particles in the next frame (the time attribute is obviously +1 from frame).

iter_trajectories()

Iterator over trajectories. Generates a Trajectory object for each trajectory in the file (in no particular order, but the same order every time on the same PyTables version) and yields it.

keys()

Return all the possible trajectory properties that may be queried as a data series (i.e. not the scalar property trajid), as a list of strings.

set_frame_range(frame_range)

Prepare a query part that limits the frame numbers is needed.

Arguments

• frame_range: a tuple (first, last) frame number, with the usual pythonic convention that first <= i < last. Any element may be None, in which case no limit is generated for it, and for no limits at all, passing none instead of a tuple is acceptable.

shapes()

Return the number of components per item of each key in the order returned by keys().

flowtracks.scene.read_dual_scene(conf_fname)

Read dual-scene parameters, such as unchanging particle properties and frame range. Values are stored in an INI-format file.

Arguments

• conf_fname: name of the config file

Returns

a DualScene object initialized with the configuration values found.