# How face_encodings Generates 128-Dimensional Embeddings Internally

> Discover how face_encodings creates 128-dimensional face embeddings by detecting landmarks aligning faces and using Dlib's ResNet neural network for facial recognition.

- Repository: [Adam Geitgey/face_recognition](https://github.com/ageitgey/face_recognition)
- Tags: internals
- Published: 2026-03-06

---

**The `face_encodings` function generates 128-dimensional vectors by detecting facial landmarks, aligning the face, and processing it through Dlib's pre-trained ResNet-based neural network that outputs a fixed-length embedding vector.**

The `face_recognition` library by ageitgey provides a high-level Python API for face detection and recognition, with `face_encodings` serving as the critical bridge between raw pixel data and machine-readable identity representations. Understanding how face_encodings generates 128-dimensional embeddings internally requires examining its dependency on Dlib's underlying C++ implementation and the specific neural architecture defined in the pre-trained model files.

## The Three-Step Embedding Generation Pipeline

The implementation in [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/main/face_recognition/api.py) orchestrates a precise sequence of computer vision operations to transform an image region into a numerical signature.

### Step 1: Facial Landmark Detection via `_raw_face_landmarks`

First, the function invokes `_raw_face_landmarks` (defined at lines 54-66 in [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/main/face_recognition/api.py)) to identify key facial structures. This step loads either the 68-point model (`pose_predictor_68_point`) or the 5-point model (`pose_predictor_5_point`) depending on the `model` parameter. These shape predictors analyze the face rectangle to output landmark coordinates used for geometric alignment and as structured input to the encoder.

### Step 2: Neural Feature Extraction with `compute_face_descriptor`

The landmark sets are passed to `face_encoder.compute_face_descriptor`, where `face_encoder` represents an instance of `dlib.face_recognition_model_v1` instantiated at lines 28-30 of [`api.py`](https://github.com/ageitgey/face_recognition/blob/main/api.py). This encoder wraps the ResNet-based model stored in `dlib_face_recognition_resnet_model_v1.dat` (bundled in the `face_recognition_models` package). According to the source code, the actual computation occurs inside the `face_encodings` function where Dlib executes a forward pass through the neural network to extract high-level facial features.

### Step 3: Outputting the 128-Dimensional Vector

Finally, `compute_face_descriptor` returns a NumPy array containing exactly 128 floating-point values. The `face_encodings` implementation (lines 203-215 in [`api.py`](https://github.com/ageitgey/face_recognition/blob/main/api.py)) collects these vectors into a list, yielding one 128-dimensional embedding per detected face. Each vector represents a point on a hypersphere where Euclidean distance directly correlates with facial identity similarity.

## The ResNet Architecture and 128-Dimensional Design

The fixed dimensionality stems from the underlying model architecture, specifically a ResNet-34-like network trained with FaceNet-style triplet loss. As implemented in the ageitgey/face_recognition library, this training paradigm maps faces onto a 128-dimensional hypersphere, ensuring that embeddings of the same person cluster tightly while different identities remain separated by measurable distances. The model weights reside in the binary file `dlib_face_recognition_resnet_model_v1.dat`, which the library downloads automatically via the `face_recognition_models` dependency specified in [`setup.py`](https://github.com/ageitgey/face_recognition/blob/main/setup.py).

## Practical Code Examples

Detect and encode faces from an image file:

```python
import face_recognition

image = face_recognition.load_image_file("examples/obama.jpg")
locations = face_recognition.face_locations(image, model="hog")
encodings = face_recognition.face_encodings(image, known_face_locations=locations)

print(f"Found {len(encodings)} face(s).")
print(f"First embedding (first 5 values): {encodings[0][:5]}")

```

Use the faster 5-point landmark model for reduced computation:

```python
encodings = face_recognition.face_encodings(
    image,
    known_face_locations=locations,
    model="small",   # Uses 5-point predictor instead of 68-point

    num_jitters=2    # Applies jittering for robustness

)

```

Calculate similarity between two faces using Euclidean distance:

```python
dist = face_recognition.face_distance([encodings[0]], encodings[1])[0]
print(f"Distance between faces: {dist:.3f}")

```

## Summary

- **`face_encodings`** acts as a Python wrapper around Dlib's C++ face recognition pipeline, located in [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/main/face_recognition/api.py).
- The function relies on **68-point or 5-point facial landmarks** detected by `_raw_face_landmarks` to geometrically normalize input faces.
- **Dlib's `face_recognition_model_v1`** processes aligned faces through a ResNet-34 architecture, outputting embeddings via `compute_face_descriptor`.
- The **128-dimensional constraint** derives from FaceNet-style training, optimizing the hypersphere embedding space for identity comparison tasks.
- Pre-trained weights are automatically managed through the **`face_recognition_models`** package dependency.

## Frequently Asked Questions

### What neural network architecture powers the face_encodings function?

The function utilizes a ResNet-34-like convolutional neural network wrapped by Dlib's `face_recognition_model_v1` class. This architecture processes aligned facial regions through residual connections to produce the final embedding vector. The specific weights are stored in `dlib_face_recognition_resnet_model_v1.dat` and loaded at module initialization in [`face_recognition/api.py`](https://github.com/ageitgey/face_recognition/blob/main/face_recognition/api.py).

### Why does face_encodings output exactly 128 dimensions?

The 128-dimensional output reflects the FaceNet embedding strategy employed during training, which maps facial features onto a unit hypersphere in 128-D space. This dimensionality strikes a balance between descriptive power and computational efficiency. The fixed size allows Euclidean distance calculations to effectively measure facial similarity while maintaining compact storage requirements.

### What is the difference between the "large" and "small" model parameters?

The "large" model (default) employs a 68-point facial landmark predictor (`shape_predictor_68_face_landmarks.dat`) for precise alignment, while the "small" model uses a 5-point predictor for faster processing with slightly reduced accuracy. Both landmark sets ultimately feed into the same 128-dimensional ResNet encoder. However, the 5-point version sacrifices some geometric precision for inference speed.

### Where does the pre-trained model data originate?

The binary model files, including `dlib_face_recognition_resnet_model_v1.dat` and the shape predictors, are distributed through the separate `face_recognition_models` Python package. This dependency is declared in the main library's [`setup.py`](https://github.com/ageitgey/face_recognition/blob/main/setup.py), ensuring automatic download and installation when users install `face_recognition` via pip.