Package: bbo-acm
ACM (Anatomically-constrained model)A framework for videography based pose tracking of rodents.
By Arne Monsees. [In review]InstallationInstall AnacondaClonehttps://github.com/bbo-lab/ACM.gitStart Anaconda Prompt (Windows) / terminal (linux) and navigate into repository directoryCreate conda environmentconda env create -f https://raw.githubusercontent.com/bbo-lab/ACM/main/environment.ymlonce repo is public)Install usingpip install .TestingDownloadexample dataset.Start Anaconda Prompt (Windows) / terminal (linux)Activate conda environmentconda activate bbo_acm.View 2D labels by runningpython -m ACM --viewer [Path of "table_1_20210511" folder from step 1.]Runpython -m ACM [Path of "table_1_20210511" folder from step 1.](expected to take around 20 minutes on modern 8-core CPU, tested with an AMD Vega iGPU and a Geforce GTX 1080 Ti)View 3D tracked pose by runningpython -m ACM --viewer [Path of "table_1_20210511" folder from step 1.]Setting up your own dataset configOverviewInputA dataset input config consists of a folder with the following files:configuration.py: Configuration file that determines settings and input and out paths.model.npy: Defines the underlying skeleton graph of the animal.multicalibration.npy: Intrinsic and extrinsic camera parameters obtained from calibrating the camera setup.origin_coord.npy: Coordinate system of the final result, relative to the coordinate system of the camera calibration.labels_dlc_n_m.npy: Automatically detected labels on the videography data.labels_manual.npz: Manual labels on the videography data. The labels are required for training a neural network for automated detection of surface markers as well as for learning the animal's antaomy via calibration.py.OutputA dataset output consists of a folder with the following files:pose.npy: A dictionary containing the inferred 3D joint and marker locations as well as the resulting projected marker locations in the 2D images.save_dict.npy: A dictionary containing the model parameters learned with the EM algorithm (i.e. the initial state and covariance matrix as well as the transition and measurement covariance matrix). Additionally, it also contains the smoothed latent variables and covariance matrices for every time point of the reconstructed sequence, which were generated using the learned model parameters.Further, the following intermediate files are generated by calibration and initialization:x_calib.npy: A flattened vector containing the latent variables encoding the learned bone lengths, surface marker locations and poses for all time points of the calibration data set, used to learn the animal's anatomy. For the subsequent pipeline only the first few entries of the flattened vector, corresponding to the bone lengths and surface marker locations, are relevant.x_ini.npy: A flattened vector containing the latent variables encoding the learned bone lengths, surface marker locations and poses for the first time point of the sequence, which should be reconstructed.By default, results are saved into theresultssubfolder of the datset configuration.File structure of input and output filesThe structure of the inputs is documented inINPUTS.md. The structure of the outputs is documented inOUTPUTS.md.FAQ