Tracking Movies (DL algorithms)

There are multiple ways to track movies using GPUs:

1. 'Track' button in the GUI to track movies in the project.

This method lets you track the movies loaded into the project (using any GPU backend). The frames to be tracked are specified by the drop down menu below the 'Track' button. The 'current' tracker will be used. The 'current' is based on which Track > Tracking algorithm is selected. The predictions created by tracking in the GUI will be displayed as 'predictions', and can be exported to trk files using File > Import/Export > Export Predictions to Trk File (Current Movie) or Track > Export current tracking results > current movie or all movies.

2. Track>Track Multiple Videos menu option.

This option brings up a GUI for tracking multiple movies. The movies-to-be-tracked can be entered manually, or use the Load button to provide a JSON file specifying these movies. An example of this JSON file can be found in the /examples directory.

Note: This option, and option 3 below, currently apply only to Deep Learning trackers (and not CPR tracking).

3. With the GUI open, use command line to track any movie.

This method allows you to track movies that internal or external to your APT project (using any GPU backend).

First, start APT using lObj = StartAPT;, open your project, and then select the trained tracker (non-CPR) that you want to use for tracking.

Then you will run lObj.tracker.track({'movies to track'},'trkfiles',{'trkfilenames for movies'}) from the MATLAB command line.

Always required variables:

lObj.tracker.track({'/path/to/movie.avi'},'trkfiles',{'/path/to/out.trk'}) - tracks the movie specified in the initial cell array {'/path/to/movie.avi'} and outputs the predictions to the file specified by 'trkfiles',{trkfilename for movie'}.

If tracking multiple movies, use cell arrays to list all variables. For example: lObj.tracker.track({'/path/to/movie1.avi';'/path/to/movie2.avi'},'trkfiles',{'/path/to/outputmovie1.trk';'/path/to/outputmovie2.trk'}). Note that the order of all variables must correspond to the order of the movies in the initial cell array.

Additional variables:

'trxfiles',{'/path/to/bodytrackingmovie1.mat';'/path/to/bodytrackingmovie2.mat'} - must be set for projects with body tracking.

'cropRois', {[mov1xlo,mov1xhi,mov1ylo,mov1yhi]; [mov2xlo,mov2xhi,mov2ylo,mov2yhi]} - must be set for projects with cropping.

Optional variables:

'f0',firstframe2track,'f1',lastframe2track - set a range of frames f0:f1 to track for each movie. If not specified, all frames will be tracked.

'f0',[firstframe2track movie1,firstframe2track movie2],'f1',[lastframe2track movie1,lastframe2track movie2] - For clusters or multi-GPU workstations. An array can be specified with one element per movie to be tracked.

'targets',[array of Tgt Ids] - set which targets to track in each movie for projects with body tracking. If not specified, all targets will be tracked.

'targets',{[array of Tgt Ids to track in movie1]; [array of Tgt Ids to track in movie2]} - For clusters or multi-GPU workstations. A cell array can be specified with one element per movie to be tracked.

Examples:

1. Track frames 1000:1499 for two movies.

lObj.tracker.track({'/path/to/movie1.avi';'/path/to/movie2.avi'},'trkfiles',{'/path/to/outputmovie1.trk';'/path/to/outputmovie2.trk'},'f0',1000,'f1',1499)

2. Track two movies of a group of animals with body tracking. For movie1, track targets 2 and 4 for 500 frames from 1000:1499, and for movie2, track targets 1, 3, and 5 for 1500 from frames 2500:3999. Currently for cluster or Multi-GPU workstations only.

lObj.tracker.track({'/path/to/movie1.avi';'/path/to/movie2.avi'},'trkfiles',{'/path/to/outputmovie1.trk';'/path/to/outputmovie2.trk'},'trxfiles',{'/path/to/bodytrackingmovie1.mat';'/path/to/bodytrackingmovie2.mat'},'f0',[1000,2500],'f1',[1499,3999],'targets',{[2,4];[1,3,5]})

3. Track three movies with 860 (w) x 300 (h) crops

lObj.tracker.track({'/path/to/movie1.avi';'/path/to/movie2.avi';'/path/to/movie3.avi'},'trkfiles',{'/path/to/outputmovie1.trk';'/path/to/outputmovie2.trk';'/path/to/outputmovie3.trk'},'cropRois', {[10,870,15,315]; [22,882,7,307];[41,901,32,332]})

Note - you can figure out the default trk file name for a project & tracker using:

tmp = lObj.movieFilesAllFull(1);

temp = defaultTrkFileName(lObj,tmp{:});

[~,a,b] = fileparts(temp);

trkname = [a,b];