Lesson 8: Teaching BonicBot to Remember Faces

This lesson also uses two built-in Python modules, pickle and pathlib.Path, along with sys, subprocess, and importlib (all part of the standard library, so no separate install is needed for those).

If you already installed opencv-python, tf-keras, and deepface in an earlier lesson, you don’t need to reinstall anything for this lesson — just make sure numpy is present too (it usually is, as a dependency of the others).

If pip install fails, try pip3 install ... instead, or use a virtual environment:

python3 -m venv bonicbot-env
source bonicbot-env/bin/activate   # On Windows: bonicbot-env\Scripts\activate
pip install opencv-python==4.10.0.84 tf-keras deepface numpy

1. Build your face gallery first. This lesson doesn’t connect to BonicBot at all — it’s an offline batch script — so there’s no robot IP address to configure. Instead, make sure the face_gallery/ folder (as described above) exists in the same directory as your script, with one subfolder per person containing their face images.
2. Save the code below into a file, e.g. lesson8_face_embeddings.py, in the same directory as your face_gallery/ folder.
3. Double-check your images. Each face should be reasonably clear and well-lit — the script will skip and report any image it can’t detect a face in, rather than crashing.
4. Run the script:

   python lesson8_face_embeddings.py

5. Watch the terminal output. You should see a line for every image processed (✅ success or ❌ failure), followed by a summary once all folders have been scanned.
6. No window will open and there’s no q key to press — the script runs to completion on its own and exits automatically once face_database.pkl has been written.

This lesson doesn’t require a physical BonicBot, a robot connection, or the ROS 2 simulation at all — it’s a standalone Python script that only reads images from your face_gallery/ folder and writes face_database.pkl to disk.

You can complete this lesson entirely on your own computer using photos of yourself, friends, or family members. The embeddings generated here will be used by BonicBot’s camera in the next lesson, where the simulation or a real robot does become relevant.

• Imports — sys, subprocess, and importlib support the automatic fallback-detector installation logic; Path from pathlib handles folder/file traversal over face_gallery/; pickle serializes the final embedding database to disk; numpy (as np) handles vector math; cv2 is checked for CascadeClassifier support; DeepFace from deepface generates the actual face embeddings.
• ensure_detector_backend() — Checks whether the installed cv2 build has hasattr(cv2, "CascadeClassifier"); if so, it immediately returns "opencv" as the detector backend. If not, it loops through a list of fallback backends (mediapipe, mtcnn, retinaface), attempting to import each one first and installing it via pip (using subprocess.check_call) if the import fails. For each backend, it runs a quick sanity check by calling DeepFace.represent() on a blank black image (np.zeros((100, 100, 3), np.uint8)) with enforce_detection=False — if that call succeeds without raising, the backend is considered usable and is returned. If none of the backends work, the function calls sys.exit(...) with an error message.
• build_face_database(dataset_dir="face_gallery", output_pickle="face_database.pkl") — The main function that does the actual work:
  • Calls ensure_detector_backend() once at the start to decide which detector to use for every image.
  • Initializes empty identities and embeddings lists, plus ok/fail counters for the summary.
  • Iterates over every subfolder inside dataset_dir using Path(dataset_dir).iterdir(), skipping anything that isn’t a directory (if not person_folder.is_dir(): continue) — this is what lets each person’s folder name double as their identity label.
  • For each person folder, builds a list of image paths by globbing multiple extensions (*.jpg, *.jpeg, *.png, and their uppercase variants) so it works across differently-cased file extensions.
  • For each image, calls DeepFace.represent(str(img_path), model_name="ArcFace", detector_backend=backend, align=True)[0]["embedding"] to get the raw embedding vector, wraps it in np.array(vec), and normalizes it by dividing by its own np.linalg.norm(vec) (guarding against division by zero) — this ensures every stored embedding has unit length, which matters for the cosine similarity comparison used in the next lesson.
  • On success, appends the person’s folder name to identities and the normalized vector to embeddings, increments ok, and prints a ✅ line. On failure (e.g. no face detected in that image), increments fail and prints a ❌ line with the exception message instead of stopping the whole run.
  • After all folders are processed, if identities is empty (no faces were successfully embedded at all), it prints a warning and returns early without writing a file.
  • Otherwise, it opens output_pickle in binary write mode and uses pickle.dump({"identities": identities, "embeddings": embeddings}, f) to save both lists together as a single dictionary, then prints a final summary line showing how many images were indexed versus skipped.
• if __name__ == "__main__": build_face_database() — Standard Python entry point guard; running the file directly (rather than importing it as a module) triggers the whole embedding-extraction process using the default face_gallery input folder and face_database.pkl output filename.

🚀 Starting batch embedding extraction...

✅ Processed: Alice (image1.jpg)
✅ Processed: Alice (image2.jpg)
✅ Processed: Bob (image1.jpg)
✅ Processed: Charlie (image1.jpg)

🎉 Parsing Complete!
💾 Database saved to 'face_database.pkl'
📊 Summary: 12 faces successfully indexed, 0 failed/skipped.

After the program finishes, a new file named

face_database.pkl

will be created.

This file contains the face embeddings for every person in your dataset and will be used in the next lesson for face recognition.

A computer cannot understand a face the way humans do.

Instead, a deep learning model first converts the face into a list of numbers called an embedding.

Alice

↓

[0.14, -0.27, 0.81, ...]

This list of numbers captures the important features of the face while ignoring unnecessary details such as the background.

In this lesson, the ArcFace model generates one embedding for every face image.

The program then:

1. Reads every person’s folder.
2. Finds all the face images.
3. Uses ArcFace to generate an embedding for each image.
4. Normalizes the embedding so every vector has the same length.
5. Stores all embeddings together in a file called face_database.pkl.

In the next lesson, BonicBot will generate an embedding for a newly detected face and compare it with the embeddings stored in this database.

The closest match will tell BonicBot who it is looking at.

Create another folder inside face_gallery.

For example:

face_gallery/
└── David/
    ├── image1.jpg
    ├── image2.jpg
    ├── image3.jpg

Run the program again to rebuild the database.