Pose tracking of mouse face from different camera views (python only) and svd processing of videos (python and MATLAB). Includes GUI and CLI for easy use.
-
For latest released version (from PyPI) including svd processing only, run
pip install facemapfor headless version orpip install facemap[gui]for using GUI. -
For using tracker and svd processing, follow the instructions below:
git clone https://github.com/MouseLand/facemap.git- Change directory to facemap folder containing environment.yml file
conda env create -f environment.ymlconda activate facemappython -m facemapThis will install the latest development version on github.
To upgrade Facemap (PyPI package), within the environment run: pip install facemap --upgrade
Facemap installation is recommended using the environment.yml:
- Download the
environment.ymlfile from the repository - Open an anaconda prompt / command prompt with
condafor python 3 in the path - Run
conda env create -f environment.yml - To activate this new environment, run
conda activate facemap - You should see
(facemap)on the left side of the terminal line. Now runpython -m facemapand you're all set.
The latest python version is integrated with Facemap network for tracking 14 distinct keypoints on mouse face and an additional point for tracking paw. The keypoints can be tracked from different camera views (some examples shown below).
For pose tracking, load video and check keypoints then click process button. A dialog box will appear for selecting a bounding box for the face. The keypoints will be tracked in the selected bounding box. Please ensure that the bouding box is focused on the face where all the keypoints shown above will be visible. See example frames here.
Use the file menu to set path of output folder. The processed keypoints file will be saved in the output folder with an extension of .h5 and corresponding metadata file with extension .pkl.
For more examples, please see tutorial notebooks.
Facemap's goal is to provide a simple way to generate keypoints for rodent face tracking. However, we need a large dataset of images from different camera views to reduce any errors on new mice videos. Hence, we would like to get your help to further expand our dataset. You can contribute by sending us a video or few frames of your mouse on following email address(es): syedaa[at]janelia.hhmi.org or stringerc[at]janelia.hhmi.org. Please let us know of any issues using the software by sending us an email or opening an issue on GitHub.
Works for grayscale and RGB movies. Can process multi-camera videos. Some example movies to test the GUI on are located here. You can save the output from both the python and matlab versions as a matlab file with a checkbox in the GUI (if you'd like to use the python version - it has a better GUI).
Supported movie files:
'.mj2','.mp4','.mkv','.avi','.mpeg','.mpg','.asf'
IR ILLUMINATION:
For recording in darkness we use IR illumination at 850nm, which works well with 2p imaging at 970nm and even 920nm. Depending on your needs, you might want to choose a different wavelength, which changes all the filters below as well. 950nm works just as well, and probably so does 750nm, which still outside of the visible range for rodents.
If you want to focus the illumination on the mouse eye or face, you will need a different, more expensive system. Here is an example, courtesy of Michael Krumin from the Carandini lab: driver, power supply, LED, lens, and lens tube, and another lens tube.
CAMERAS:
We use ptgrey cameras. The software we use for simultaneous acquisition from multiple cameras is BIAS software. A basic lens that works for zoomed out views here. To see the pupil well you might need a better zoom lens 10x here.
For 2p imaging, you'll need a tighter filter around 850nm so you don't see the laser shining through the mouse's eye/head, for example this. Depending on your lenses you'll need to figure out the right adapter(s) for such a filter. For our 10x lens above, you might need all of these: adapter1, adapter2, adapter3, adapter4.
(video with old install instructions)
Run the following command in a terminal
python -m facemap
Default starting folder is set to wherever you run python -m FaceMap
To start the GUI, run the command MovieGUI in this folder. The following window should appear. After you click an ROI button and draw an area, you have to double-click inside the drawn box to confirm it. To compute the SVD across multiple simultaneously acquired videos you need to use the "multivideo SVD" options to draw ROI's on each video one at a time.
