Skip to content

CPR Tracking on a Local Cluster

Jump to bottom
Allen Lee edited this page Aug 15, 2020 · 6 revisions

This page was originally written for users tracking with CPR on the Janelia Cluster, but it can apply to anyone who would like to run with CPR on a local Linux cluster resource.

<APT>/matlab/APTCluster.m is a MATLAB function that has been compiled into binaries located at ~leea30/aptbuild. (See below for compilation instructions.) This function performs training/tracking operations on/with an existing APT project, depending on the input arguments. The python script <APT>/matlab/APTCluster.py starts cluster jobs that call the compiled APTCluster binaries.

APTCluster.py must be run from Linux servers and your project, as well as any movies to be tracked, must be accessible over the network filesystem.

IMPORTANT: If you have never opened/used your project using the Labeler on Linux, your movie paths may not work. To resolve this, first make sure you can open/train/track with your project on Linux. If you have been using a non-Unix platform, you will probably need to add macros to your moviepaths; see Path Macros. See also #8.

For help and usage examples, see

./APTCluster.py --help
  • The --nslots specification should be selected empirically based on your project. Use --multithreaded to select a multithreaded build. The CPR algorithm can be a memory hog, especially for full retrains; it can also multithread significantly when running in multithreaded mode, eg using up to 10 cores while tracking one dataset. You must investigate and set your --nslots specification on a case-by-case basis.
  • The --movbatchfile specification expects a textfile with the following format. Linux line-endings are expected.
    • For projects without trx, one full movie path per line.
    • For projects with trx, a two column csv (comma delimited) with one (moviefile,trxfile) pair on each line. The movie comes first.

APTCluster Compilation Instructions

The APT repo includes a function that calls mcc to build APTCluster.m with the MATLAB Compiler.

  • In <APT>/Manifest.txt, add a row with a build path specification: build,/path/to/builddir. Compiled binaries will be placed in this directory. Subsequently, this directory can be specified with the --binrootdir argument to APTCluster.py.
  • Start MATLAB and cd to the APT root directory (eg returned by APT.Root)
  • run APT.buildAPTCluster()

Prototype Installation Instructions for non-JRC Users

  1. Build/compile APTCluster using the steps above.
  2. Your cluster will either need an installation of MATLAB R20xxx that includes MATLAB Compiler, OR
  3. You will need to download and install the MATLAB runtime libraries for R20xxx at https://www.mathworks.com/products/compiler/matlab-runtime.html

Only one of steps 2 and 3 need to be done. At JRC step 2 applies, as all recent MATLAB versions are installed in a standard location.

You can test the APTCluster binaries on your cluster by running them directly in Linux (shown here with R2019b):

# Hello-world test
# The second argument is the installation location of MATLAB R2019b; you can replace this with an installation of the MATLAB runtime libraries if you use step 3.
/path/to/builddir/20200312/APTCluster/run_APTCluster_multithreaded.sh /usr/local/MATLAB/R2019b/ hello 

# This retrains a project (for CPR) with whatever settings are saved in the project.
/path/to/builddir/20200312/APTCluster/run_APTCluster_multithreaded.sh /usr/local/MATLAB/R2019b/ /path/to/APTproject.lbl retrain

# Track 100 frames
/path/to/builddir/20200312/APTCluster/run_APTCluster_multithreaded.sh /usr/local/MATLAB/R2019b/ /path/to/APTproject.lbl track /path/to/movie.avi startFrame 1 endFrame 100
Clone this wiki locally