Validator#

Warning

This tool may be overwhelming for beginner users, there’s no need to use it to get decent trajectories.

Idtracker.ai’s validator is a graphical application to check, modify and validate a successful tracking session. It loads the list_of_blobs and the session.json from the session folder so setting data_policy = 'trajectories' would make the validator unable to load the session.

To start the app, run the next command:

idtrackerai_validate path/to/session_folder

to open the desired session, or just

idtrackerai_validate

to open a blank validator and manually opening a session by pressing Ctrl+O.

../_images/validator_dark.png — idtracker.ai’s validator application (in *dark* mode)#

../_images/validator_light.png — 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 close 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 minor impact tools

Blob’s extra info

Displayer of selected blob’s main attributes

App actions#

Here you’ll find the application options. None has an effect on the data being validated and most of them have an associated keyboard shortcut.

About: contains a link to this webpage and an update checker.
View: access to quit the app, change the font size and toggle the dark theme.
Video Player
- Enable Color: toggles color/grayscale in the video player.
- Limit framerate: limits the frame rate to the framerate of the original video (default is True in the validator).
- Reduce memory usage: a cache is implemented in the video player to speed up the access to previously displayed frames. The size of this cache is limited to the last 128 frames. Enable this options to reduce this to the last 16 frames and reduce RAM usage.
Session
- Open session: open a session by browsing the desired session folder.
- Reset session…: reset all user made corrections in a specified time range or in the entire session.
- Save session: save the current session as well as generating the corresponding validated trajectories file.
Draw: toggle different blob’s attributes to draw in the video player. Regions of interest can also be drawn when present. Search identity can be triggered from here.

List of errors#

Contains all errors in the current session classified into four types:

No id A blob’s centroid could not be identified or has an invalid identity.
Miss id (Missing identity) The animal with identity Id couldn’t be located (NaN gap).
Jump The speed of the animal with identity Id is suspiciously large.
Dupl (Duplicated) There are more than one centroid with the same identity.

Jump type errors are triggered when an animal moves faster than the mean value (of all speed values in the session) plus \(x\) times the standard deviation. This threshold \(x\) can be modified by the user in the “Jumps threshold” slider.

Clicking an error will make video player focus on it and, if the clicked error is of type Miss id or Jump, the Interpolator will activate. As some Jumps errors are not real errors, already user interpolated jumps (even if they still are over the threshold) will no longer appear as errors. User can reset the list of user accepted jumps by clicking “Reset”.

Interpolator#

The interpolator can correct trajectories and close NaN gaps by using polynomial interpolations. It activates clicking an error of type Miss id or Jump in the List of errors and also double clicking a centroid on the Video player and then selecting “Interpolate here”.

When activated, the interpolator will focus on a single animal identity and will take some input data from the current animal trajectory (drawn as red dots in the video player) and will propose the position for the missing centroids inside the interpolation range (drawn as white dots).

User can modify the interpolation parameters (“Interpolation order” and “Input size”). Also, user can manually adjust the trajectories by:

Removing the centroids (move through the video with A and D to select the centroid you want to remove and press R to remove it).
Establishing the current centroid position right-clicking in the video player (only when inside the interpolation range).
Fixing wrong identifications by double-clicking on an existing centroid and assigning a new identity.

Click “Apply” to accept the interpolation proposal and click another errors to continue validating.

Video player#

The video frames will be live displayed here as well as the blobs information (contours, labels…). Double clicking on one centroid will display the a window with some tools to modify its properties. User can change the identity of the centroid (and propagate this change up to the next crossing, it expands on the entire fragment) and also the Interpolator can be called from here.

Extra tools#

The next tools have no effect on the trajectories nor on any other aspect of the session. Their information will be included in the Trajectory files for user to use it as desired.

Groups#

Create identity groups by clicking “Add”, writing the group name, and clicking on every identity in the video player to toggle it. When done, uncheck the “Edit” button to finish editing the group.

Labels#

Set a label (a name) for every identity in your session.

Setup points#

Create sets of “Setup points” by clicking “Add”, writing the desired name and clicking on the video player to set the desired positions of the points (left click to add a point and right click to erase it). This could be used to mark the corners/center of your experimental arena, some obstacle, or the position of a rule to calibrate distances.

Length Calibration#

By clicking “Add”, define two points in the video and the real distance between them to calibrate the tracking. This will populate the length_unit property in the trajectory files to convert pixel units to the one states by the user.

Mark blobs#

Point out blobs based on different properties. Designed for debugging and helping to understand the tracking process. Marked blobs will appear in red.

Blob’s extra info#

When clicking a centroid on the video player, this tool will display its main attributes (mostly for debugging purposes). The selected identity will be traced through the video displaying information of any blob which contains the selected identity.

Validator shortcuts#

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)