dynsight.track.track_xyz

dynsight.track.track_xyz(input_xyz, output_xyz, search_range, memory=1, adaptive_stop=0.95, adaptive_step=0.5)[source]

Track particles from an .xyz file and write a new file with IDs.

The input .xyz is assumed to contain only raw 3D coordinates (without atom labels/identity), and each frame begins with a line indicating the number of objects, followed by a comment line, then a list of positions. Each frame in the input file must follow this structure:

<number of objects>
comment line
<x> <y> <z>
<x> <y> <z>
...
<x> <y> <z>

or:

<number of objects>
comment line
<name> <x> <y> <z>
<name> <x> <y> <z>
...
<name> <x> <y> <z>

The output file will have the same structure, but each line will start with the tracked particle ID.

Parameters:

  • input_xyz (Path) – Path to the input .xyz file containing positions only.

  • output_xyz (Path) – Path where the output .xyz file with particle IDs will be saved.

  • search_range (float) – The maximum allowable displacement of objects between frames for them to be considered the same particle. Units depend on the coordinate system used in the input file. If the file comes from vision, then the unit is pixels. We do not provide a default parameter here, because fine tuning is required to get good behaviour. We recommend starting with a value around 2-3 times the diameter of the particles. But if you are unsure, start with a value of 10. Additionally, test on a small trajectory to start with.

  • memory (int) – The maximum number of frames during which an object can vanish, then re-appear nearby, and be considered the same particle.

  • adaptive_stop (None | float) – If not None, when encountering a region with too many candidate links (subnet), retry by progressively reducing search_range until the subnet is solvable. If search_range becomes less or equal than the adaptive_stop, give up and raise a SubnetOversizeException.

  • adaptive_step (None | float) – Factor by which the search_range is multiplied to reduce it during adaptive search. Effective only if adaptive_stop is not None.

Return type:

Trj