Validator#

Warning

This tool may be overwhelming for beginners; it is not necessary for obtaining 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. Setting data_policy = 'trajectories' would make the validator unable to load the session, see Tool availability for different data policies.

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 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#

Application options are listed here. 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 option to reduce the cache 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 are displayed here along with blob information (contours, labels, trails…). Double-clicking a centroid opens a window with tools to modify its properties: the identity can be changed (the change propagates forward through the fragment up to the next crossing) and the Interpolator can be called from here.

Extra tools#

These tools do not alter the tracked positions or identities. Their outputs are saved alongside the trajectories in the Trajectory files for downstream use.

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.

Show Metadata#

Mark Metadata visibility

Checking the Show Metadata adds the tab Mark Metadata into the Extra tools. This tool allows to point out blobs based on different properties.

When active, it displays the main attributes of the corresponding blob and fragment of the selected centroid in the video player (mostly for debugging purposes). The selected identity will be traced through the video to always display the information in 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