Skip to content
No description, website, or topics provided.
Python JavaScript
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib final v1 release Jan 26, 2018
training_data/negative First Version Jan 10, 2018
translations First Version Jan 10, 2018
.gitignore ignore Jan 15, 2018
LICENSE remove algorithm alternatives Jan 15, 2018
MMM-Facial-Recognition-OCV3.js final v1 release Jan 26, 2018 correction doc Feb 13, 2018
node_helper.js First Version Jan 10, 2018
package.json common config Jan 15, 2018 cleaning files Jan 25, 2018 final v1 release Jan 26, 2018 cleaning files Jan 25, 2018


This module is a facial recognition module (detection + recognition) for MagicMirror². This module is mainly inspired by the one developped by paviro : MMM-Facial-Recognition. [TOC]


This module uses the OpenCV library and is only compatible with the v3 (only tested with the version 3.3 and the rest of the description is based on this version. Some adaptions will probably be needed to support other version). It has been adapted to :

  • Be able to support the v3.3.0 OpenCV version (the paviro one did not)
  • Merge the 2 projects MMM-Facial-Recognition (MagicMirror module) and MMM-Facial-Recognition-Tools (tools to capture and train the model) into one project
  • Mutualize some code and move some of into Classes
  • Explain the way to build and install OpenCV 3.3.0 (required, the version is not available into a repository)
  • Remove the Fisher and Eigen Algorithm that did not work well for Raspberry. Only LBPH Algorithm is usable.

Get this module with the command line :

cd ~/MagicMirror/modules/
git clone

Prepare the module

This section explain the way to prepare the module, by installing the dependencies and train the model.

Building OpenCV

This is the most time consuming part, because the OpenCV library need to be build by the raspberry (it may take 2 hours). This section is a mix of 2 great articles found[^first][^second].

Configuring the Raspberry

First, install and update all the elements before compiling :

sudo apt-get update
sudo apt-get upgrade
sudo rpi-update
sudo reboot
sudo apt-get install build-essential git cmake pkg-config
sudo apt-get install libjpeg-dev libtiff5-dev libjasper-dev libpng12-dev
sudo apt-get install libavcodec-dev libavformat-dev libswscale-dev libv4l-dev
sudo apt-get install libxvidcore-dev libx264-dev
sudo apt-get install libgtk2.0-dev
sudo apt-get install libatlas-base-dev gfortran
cd ~
git clone
cd opencv
git checkout 3.3.0
cd ~
git clone
cd opencv_contrib
git checkout 3.3.0

Build OpenCV

This section may take long ... First get pip cross version :


Two Python alternatives to build OpenCV : v2.7 or v3.0

If using Python v2.7 :

sudo apt-get install python2.7-dev
sudo python

If using Python v3.0 :

sudo apt-get install python3-dev
sudo python3

Before you start the compile process, you should increase your swap space size. This enables OpenCV to compile with all four cores of the Raspberry PI without the compile hanging due to memory problems. Open your /etc/dphys-swapfile and then edit the CONF_SWAPSIZE variable:

# set size to absolute value, leaving empty (default) then uses computed value
# you most likely don't want this, unless you have an special disk situation

To activate the new swap space, restart the swap service:

sudo /etc/init.d/dphys-swapfile stop
sudo /etc/init.d/dphys-swapfile start

It is possible to burn out the Raspberry Pi microSD card because flash memory has a limited number of writes until the card won’t work. It is highly recommended that you change this setting back to the default when you are done compiling and testing the install.

And then, build OpenCV :

pip install numpy
cd ~/opencv
mkdir build
cd build
    -D CMAKE_INSTALL_PREFIX=/usr/local \
    -D OPENCV_EXTRA_MODULES_PATH=~/opencv_contrib/modules \
make -j4
sudo make install
sudo ldconfig

After a long time, OpenCV is built and installed

Install the dependencies

Go back to the MMM-Facial-Recognition-OCV3 modules directory :

cd ~/MagicMirror/modules/MMM-Facial-Recognition-OCV3

Install the need dependencies by running the command :

npm install

If you will run the different tools with Python 2.7, install the cross-compatible features with :

pip install future

Capture and Train the model

Capturing training images

  1. Run python
  2. Decide whether you want to capture images from your picam or convert existing .jpg images.
  3. Enter the name of the person you are about to capture. Images will be stored in a folder named after the captured person in training_data/.
  4. Follow screen instructions.

Training model

  1. Make sure you have captured all your images.
  2. Run python The script will automatically scan the directory training_data/ for your images.
  3. Wait. You will end up with a training.xml file in the current directory.
  4. Copy down the ['name1', 'name2','name3'] part because you will later need it for setting up your mirror's face recognition and to test your face recognition model.

Test your trained model

  1. Make sure your training.xml from running is in this directory
  2. Specify your user labels in the environment with
export FACE_USERS=name1,name2,name3
  1. Run python to test your trained model.

Setup the module

To setup the module in MagicMirror², add the following script int the config.js file in the config/ MagicMirror² directory (Modify the script regarding the Algorithm, file location, ...).

    module: 'MMM-Facial-Recognition-OCV3',
    config: {
        // Threshold for the confidence of a recognized face before it's considered a
        // positive match.  Confidence values below this threshold will be considered
        // a positive match because the lower the confidence value, or distance, the
        // more confident the algorithm is that the face was correctly detected.
        threshold: 80,
        // force the use of a usb webcam on raspberry pi (on other platforms this is always true automatically)
        useUSBCam: false,
        // Path to your training xml
        trainingFile: '/home/pi/MagicMirror/modules/MMM-Facial-Recognition-OCV3/training.xml',
        // recognition intervall in seconds (smaller number = faster but CPU intens!)
        interval: 2,
        // Logout delay after last recognition so that a user does not get instantly logged out if he turns away from the mirror for a few seconds
        logoutDelay: 15,
        // Array with usernames (copy and paste from training script)
        users: [],
        //Module set used for strangers and if no user is detected
        defaultClass: "default",
        //Set of modules which should be shown for every user
        everyoneClass: "everyone",
        // Boolean to toggle welcomeMessage
        welcomeMessage: true

In order for this module to do anything useful you have to assign custom classes to your modules. The class default (if you don't change it) is shown if no user is detected or a stranger. The class everyone (if you don't change it) is shown for all users. To specify modules for a certain user, use their name as classname.

    module: 'example_module',
    position: 'top_left',
    //Set your classes here seperated by a space.
    //Shown for all users
    classes: 'default everyone'
    module: 'example_module2',
    position: 'top_left',
    //Only shown for name1
    classes: 'name1'


You can’t perform that action at this time.