Validator

Optional tool

The validator has many features and may feel overwhelming at first. You do not need it to get good trajectories.

The validator is a graphical app to review, correct and annotate the results of a tracking session. Open a session with:

idtrackerai_validate path/to/session_folder

or run idtrackerai_validate without arguments and open a session with Ctrl+O.

The validator needs the preprocessing folder of the session. Sessions tracked with data_policy = 'trajectories' cannot be opened (see Data policies).

Click any area of the diagram below the screenshot to jump to its description.

idtracker.ai’s validator application (in dark mode)

idtracker.ai’s validator application (in light mode)

App actions

Actions related to the application and its operation

List of errors

An error analyzer and explorer

Interpolator

The interpolation tool to fill NaN gaps

Video player

The interactive video player displaying the current video frame with all extra information on top

Extra tools

A collection of three added tools for extra functionality

Show Metadata

Main attributes of the blob and fragment of the selected centroid

App actions

The menu bar holds the application options. None of them change the session data, and most have a keyboard shortcut.

• About: link to this documentation and an update checker.

• View: quit the app, change the font size and toggle the dark theme.

• Video Player

  • Enable Color: show the video in color or in grayscale.

  • Limit framerate: play the video no faster than its original frame rate (on by default).

  • Reduce memory usage: the player keeps the last 128 frames in memory to show them again quickly. Enable this option to keep only 16 frames and use less RAM.

• Session

  • Open session: browse for a session folder and open it.

  • Reset session…: undo all your corrections, in a range of frames or in the whole session.

  • Save session: save your corrections and write the corrected trajectory files.

• Draw: choose which blob properties are drawn on the video player, and draw the regions of interest. You can also start Search identity from here.

List of errors

Lists the possible errors in the session, of four types:

• No id: a blob has no identity, or an invalid one.

• Miss id (missing identity): the animal Id could not be located (a NaN gap).

• Jump: the animal Id moves suspiciously fast.

• Dupl (duplicated): two or more blobs have the same identity.

A Jump is reported when an animal moves faster than the mean speed of the session plus \(x\) standard deviations. Set \(x\) with the Jumps threshold slider.

Click an error to show it in the video player. For Miss id and Jump errors, this also opens the Interpolator.

Some jumps are real fast movements, not errors. Once you interpolate a jump, it is considered accepted and no longer listed, even if it is still above the threshold. Click Reset to clear the list of accepted jumps.

Interpolator

The interpolator fills NaN gaps and corrects trajectories with a polynomial interpolation. Open it by:

• clicking a Miss id or Jump error in the List of errors, or

• double-clicking a centroid in the Video player and selecting Interpolate here.

The interpolator works on one animal at a time. It takes some positions of that animal before and after the gap as input (red dots in the video player) and proposes positions for the missing frames (white dots). Adjust the proposal with the Interpolation order and Input size parameters.

You can also edit the trajectory by hand:

• Remove a centroid: move to its frame with A and D and press R.

• Set a position: right-click on the video player (only inside the interpolation range).

• Fix an identity: double-click a centroid and assign a new identity.

Click Apply to accept the result, then click the next error to continue.

Video player

Shows the current frame with the blob information on top (contours, labels, trails…). Double-click a centroid to open a window where you can:

• change its identity (the change applies forward, up to the next crossing), or

• open the Interpolator.

Extra tools

These tools add information to the session without changing any position or identity. Their results are saved in the Trajectory files, so you can use them in your analysis.

Groups

Group identities, for example by sex or by treatment. Click Add, type the group name, and click every animal of the group in the video player. Uncheck Edit when you are done.

Labels

Give a name to each identity.

Setup points

Mark reference points of your setup, such as the corners or the center of the arena, an obstacle, or the ends of a ruler. Click Add, type a name, and click on the video player to place the points (left click adds a point, right click removes one).

Length calibration

Convert pixels to real units. Click Add, mark two points on the video, and type the real distance between them. This sets length_unit in the trajectory files.

Show Metadata

Mark Metadata

Checking Show Metadata also adds the Mark Metadata tab to the Extra tools, which highlights blobs based on their properties.

Shows the main properties of the blob and the fragment of the selected centroid. This is mostly useful for debugging. The selected identity is followed through the video, so the information always refers to the current frame.

Validator shortcuts

Shortcut Key	Action
Q	Quit the app
Ctrl + O	Open session
Ctrl + S	Save trajectories
Alt + L	Toggle labels drawing
Alt + C	Toggle contours drawing
Alt + P	Toggle centroids drawing
Alt + B	Toggle bounding boxes drawing
Alt + T	Toggle trails drawing
Alt + R	Toggle ROIs drawing
Ctrl + F	Search identity
Space	Play/pause video player
1 - 9	Change the video playback speed
Ctrl + L	Toggle playback framerate limit
Right / D	Move video playback forward
Left / A	Move video playback backward
U	Update list of errors
Ctrl + A	Apply interpolation (when interpolating)
Esc	Abort interpolation (when interpolating)
R	Remove current centroid (when interpolating)
Ctrl + +	Increase font size
Ctrl + -	Decrease font size