Skip to content


Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

Downloads Downloads GitHub stars GitHub forks PyPI version Documentation Status GitHub open issues

Facemap lilmouse

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 facemap for headless version or pip install facemap[gui] for using GUI.

  • For using tracker and svd processing, follow the instructions below:

  1. git clone
  2. Change directory to facemap folder containing environment.yml file
  3. conda env create -f environment.yml
  4. conda activate facemap
  5. python -m facemap This 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:

  1. Download the environment.yml file from the repository
  2. Open an anaconda prompt / command prompt with conda for python 3 in the path
  3. Run conda env create -f environment.yml
  4. To activate this new environment, run conda activate facemap
  5. You should see (facemap) on the left side of the terminal line. Now run python -m facemap and you're all set.

Pose tracking


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).

view1 view2

GUI Instructions

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.

CLI Instructions

For more examples, please see tutorial notebooks.

📣 User contributions 📹 📷

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] or stringerc[at] Please let us know of any issues using the software by sending us an email or opening an issue on GitHub.

SVD processing

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:


Data acquisition info


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.


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.

HOW TO GUI (Python)

(video with old install instructions)

face gif

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.

gui screenshot


matlab/python GUI for unsupervised video analysis of rodent behavior (capable of processing multiple camera views)








No releases published


No packages published

Contributors 4