Usage

To run the box software, make sure the hardware is assembled and the training is complete. First you'll run the box with only power to the Raspberry Pi and not the lock servo--this will allow you to test the face recognition without locking yourself out of the box. Apply power to just the Raspberry Pi (and not the servo), then connect to the Pi in a terminal session, navigate to the folder with the software, and execute the following command:

sudo python box.py

You should see the box software load and the message 'Loading training data...' appear. It should take a few minutes for the training data to load and the following message to appear:

Running box...
Press button to lock (if unlocked), or unlock if the correct face is detected.
Press Ctrl-C to quit.

The box will lock itself (however because no power is applied to the servo, the lock latch should not move) and be ready to try unlocking with face recognition. Aim the box camera at your face, like you did when training the face recognition model, and press the button on the box. You should see a message that the button was pressed, and after a moment if the face is recognized you will see a message like:

Predicted POSITIVE face with confidence 1321.35253959 (lower is more confident). Recognized face!

If the face is not recognized you will see a message like:

Predicted NEGATIVE face with confidence 3987.76625152 (lower is more confident). Did not recognize face!

If a single face couldn't be detected (because none is visible, or there are multiple faces detected) an error message will be displayed like with the training script.

When a face is found, you'll notice the prediction message includes how the face was recognized (i.e. matching either the positive or negative training data), and the confidence of the recognition. The confidence is a value like 1321.35 or 3987.77 above and represents the distance of the captured face from the predicted face--a lower distance value means the captured face is more similar to the predicted face.

To unlock the box, a captured face must be a positive prediction with a confidence value below the POSITIVE_THRESHOLD configuration value. By default the POSITIVE_THRESHOLD is 2000, so the positive prediction with confidence 1321.35 was considered a match and would have unlocked the box.

When the box is in an unlocked state, press the button to lock the box again. You do not need to have a face recognized to lock the box.

Play with unlocking and locking the box to see what prediction and confidence you get from your trained face recognition model. Ideally you want images of the positively trained face to be predicted as positive images with a low number for the confidence value. The eigenfaces recognition algorithm is sensitive to the lighting and orientation of your face, so try to have as similar conditions as when the positive training images were captured (or consider re-training your model to include more varied images).

You can see examples of how my training data predicted faces below (remember you can look at the capture.pgm image in the software directory after pressing the button to attempt a face recognition):

This image unlocked my box because it was a match for the positive training images, and had a confidence of 1321.35 which was below the threshold of 2000.
This image of a face from a magazine did not unlock my box because it was a match for the negative training data, with a confidence of 3987.77.
This image unfortunately did not unlock my box. Although it was predicted as a positive match, the confidence was 2269.04 which was slightly higher than the positive match threshold.

If you get a lot of false negative predictions like this, it's a sign you need better training data or should adjust the POSITIVE_THRESHOLD configuration value up.
This image matched the positive training data, but the confidence value of 4407.85 was too far above the threshold to unlock the box.

If you get a lot of false positive responses like this it's also a sign that you need better training data. Remember face recognition is far from perfect--there's always a chance someone who looks like the positively trained images will match close enough to unlock the box!
Based on how the face recognition responds, you might consider training it again or adjust the POSITIVE_THRESHOLD configuration to a higher/lower value.

When you're happy with how the recognition is working, apply power to the servo and try locking and unlocking the box for real. Congratulations on building the face recognition treasure box!

If for some reason your box is locked and will not recognize a face to unlock itself, you can manually set the servo position to an unlocked value by following the steps in the servo configuration. If you don't have access to the Raspberry Pi terminal or the servo isn't moving, unfortunately you'll need to disassemble your box (this is why it's a good idea to use a box with hinges on the outside!).
This guide was first published on Jan 24, 2014. It was last updated on Jan 24, 2014. This page (Usage) was last updated on May 04, 2015.