Package: id-manual-tools
id manual toolsid_manual_tools is a set of tools to use after a video has been tracked with idTracker.ai. They work on Python and are capable of visually correcting trajectories of animals, concatenate trajectory files and render awesome videos like the one above.Table of ContentsInstallSteps to track a video with idTracker.ai1 Download the episodes from Google Drive2 Prepare the videos3 Input parameters3.1 local_settings.py3.2 segmentation parameters4 Running idTracker.ai from terminal4.1 Commands to run idTracker.ai from terminal4.2 idTracker.ai logger5 id_manual_tools5.1id_manual_tools_get_nans5.2id_manual_tools_set_corners5.3id_manual_tools_correct_traj5.4id_manual_tools_concatenate_traj5.5id_manual_tools_plot_trajContactInstallIn theidTracker.aienvironment:pip install id-manual-toolsSteps to track a video with idTracker.ai1 Download the episodes from Google DriveWhen downloading more than one file (or folder) of some GB each from Google Drive, Google tries to compress it but it can't, a bunch of files are then downloaded separately in the folder and you need to organize them.These files should be saved at the external drive. Each one is around 4GB and you don't want to run out of space in the OS drive.Once done, the files contain some extra numbers in their names (the videoGX010128.MP4is downloaded asGX010128-012.MP4, for example). You can rename each file individually or use the bash commandrename -v 's/-[0-9]{3}././' *.MP4to rename all of them at once2 Prepare the videosYou don't want to track every 5 minutes episode individually and join them afterwards. The episodes (from the same experiment) must be concatenated usingffmpeg.The larger the number of fishes in the experiment, the sorter the videos have to be so that idtracker.ai can track them. For up to 8 fishes, 30 minutes of 50fps videos (~90k frames) are ok for our computer. But try to track 30 minutes of 39 fish and your RAM will die (at least with our RAM with 64GB).To concatenate all videos ended with0154in the current directory and write the output in the home directory you can runffmpeg -safe 0 -f concat -i <(find . -type f -name '*0154.MP4' -printf "file '$PWD/%p'\n" | sort) -c copy /home/jordi/0154.MP4If you don't want to concatenate all of the videos and you want to specify the files you have to write an orderedfilelike (for example)file './GX010154.MP4'
file './GX020154.MP4'
file './GX030154.MP4'and then runffmpeg -safe 0 -f concat -i file -c copy /home/jordi/0102030154.MP4I use this name encoding, the lasts 4 digits are the video name and the firsts pairs are the episodes. So010203040187.MP4are episodes 01 02 03 and 04 of video 01870187.MP4are all episodes of the video 01873 Input parametersidTracker.ai has 3 levels of parameters with increasing priority.constants.pyfile in the idtrackerai internal directory (you don't want to modify those parameters).local_settings.pyfile in the current working directory.Segmentation parameters from the idtrackerai GUI that wi will send to idtracker as.jsonfile.3.1 local_settings.pyFind complete infothe official idtracker website.Here, you want to define the next parameters:NUMBER_OF_JOBS_FOR_SEGMENTATION = 20Currently, idtrackerai consume so much RAM in the segmentation process so you want to set the number of jobs somewhere around 20 (although our computer has 36 cores)IDENTIFICATION_IMAGE_SIZE = 55If you want to match identities after the tracking process, you have to fix the image size. In out videos 55 is a good valueDATA_POLICY = 'idmatcher.ai'This will remove useless data in the session directory when the tracking ends (this will free you from GBs of trash data)3.2 segmentation parametersThe segmentation parameters will be unique for every video. To get them you have to run the commandidtrackeraito enter the idtrackerai GUI.Hereyou will find extended info of that.These are the steps to obtain a good segmentation .json file from the GUI:Open a video file by clickingOpen.If a window appears asking if you want to track multiple videos at once, say NO. I don't recommend tracking various videos, at least by now.Define a ROI (Region of Interest) with aPolygon.Subtract background. This may take a while and the GUI will freeze until the background is computedDefine the number of animalsClick to the Blob information and pressing Alt+space put itAlways on top.Modify the upper intensity threshold (the lower must be at 0) to obtain a minimum blob area of around 400 px and no noise blobs.Modify the lower area threshold to around 300 px (so that all fish appear as blobs but you limit some accidental small noise blob)Name you session with the same name as the video fileSave the .json with the same name as the video fileClose the GUISide notes:If you are working with 30 min videos, it's useful to use the GUI with one of the 5 min episodes so that the background computation takes less time. If you do that remember torename the video pathto the full 30 min video andmodify therange(of frames to track) to something like $[0, 9999999999]$ in the .json.If you want to create the .json files for very similar videos (videos of the same day and characteristics). You can create the first one and copy-paste it changing the session name and the video path.4 Running idTracker.ai from terminal4.1 Commands to run idTracker.ai from terminalThe command to run idtrackerai in the terminal isidtrackerai terminal_mode --load file.json --exec track_videoThis will print output in the terminal and will be shut down when you exit the terminal.If you want to run idtracker.ai not worrying about accidental shut downs, thennohup idtrackerai terminal_mode --load file.json --exec track_video > file.log 2>&1 &will print the output to a file and will keep running when you exit the terminalA mini bash script for various videos to track could be#!/bin/bashdeclare-afiles=("0102030405060146""0708091011120146""0147""0148""0149")forfilein"${files[@]}"doidtrackeraiterminal_mode--load$file.json--exectrack_video>$file.log2>&1doneAnd run it likenohup ./script.sh &Keep track of the output file to check the status of the program4.2 idTracker.ai loggerEven if you run idtracker actively on the terminal (so that the log is printed in screen) or on background (the log is written in a .log file), you have to check some important aspects.The firsts lines of the log will indicate the parameters received by the software, check they are correct.Look for the lineINFO     --> check_segmentation. After this line will appear the frames that contain more blobs than animal (if there is any). You don't want to have frames like that. For a 30 min 50 fps video you could accept < 20 error frames. But always think abut adjusting the segmentation parameters to avoid those frames.idTracker.ai has 3 tracking protocols depending of the needs of each video. If you video enters on protocol 3 (look for the lineINFO     --------------------> Protocol 2 failed -> Start protocol 3), kill the process. Protocol 3 is eternal, it is time itself. Try to readjust the segmentation parameters and pray to god this doesn't happen again.The last lines of a successful log will beINFO     Estimated accuracy: 0.????andINFO     Success. A useful tracking should have an accuracy > 0.99.5 id_manual_toolsWhen tracked, you may use theid_manual_toolsprojectFor now, id_manual_tools has 5 tools:5.1id_manual_tools_get_nans5.2id_manual_tools_set_corners5.3id_manual_tools_correct_traj5.4id_manual_tools_concatenate_traj5.5id_manual_tools_plot_trajAll of them are wrapped with Python's ArgParser and can be ran with-hflag to print some basic information about input/output.5.1id_manual_tools_get_nansThe first tool checks for nans in the trajectory file. The raw trajectories from idTracker.ai use to have some NaNs (less than 1% of the total data). It reads the file and print a .csv list of NaNs5.2id_manual_tools_set_cornersThis tool opens the video to set thesetting_points. A list of coordinates that we use to indicate the position of the tank corners.5.3id_manual_tools_correct_trajThat's the main tool here. The trajectory corrector will useid_manual_tools_get_nansto look fort NaNs and will display a full matplotlib GUI to correct them using cubic interpolations. Additionally, the user will be asked to write the corners of the tank usingid_manual_tools_set_cornersto crop the video and speed up the GUI.This tool can also be used to correct suspicious high velocities (jumps) using a gaussian threshold.id_manual_tools_correct_trajectories -s session_0146/ -video 0146.MP4 -fps 50 -n 10 -jumps_check_sigma 65.4id_manual_tools_concatenate_trajIf your video has been tracked in chunks. You can concatenate them with this tool but first of all you have to match them. This can be done withidmatcher.Since this repo is a bit out-of-date, in the computer there is a the idmatcher directory and, if you havesession_Asession_Bsession_C, you can use it likepython idmatcher/main.py -sA session_A -sB session_B
python idmatcher/main.py -sA session_A -sB session_CAn additional folder will appear inside each session folder. Then you will be able to concatenate them.5.5id_manual_tools_plot_trajThis is used to make composed videos (the original video with the trajectories overlapped)ContactGitHub actions are recommended (issues, PR,...). Also, author's email isjordi.torrentsm@gmail.com