Understanding the Filter/NFilter Feature for Identity-Based Face Extraction in FaceSwap

The filter and nfilter options in FaceSwap enable identity-based face extraction by comparing facial embeddings against reference images, allowing you to include only specific identities (filter) or exclude unwanted faces (nfilter) during the extraction process.

The deepfakes/faceswap repository provides advanced tools for face manipulation, including sophisticated identity-based filtering mechanisms. The filter and nfilter features allow users to control which faces are extracted from video or image sequences by leveraging pre-computed facial identity embeddings. This capability is essential when working with footage containing multiple subjects, ensuring only target identities are processed while filtering out background individuals or unwanted faces.

What Are Filter and NFilter in FaceSwap?

The filter (positive filter) and nfilter (negative filter) options work as identity-based gatekeepers during the face extraction pipeline:

• Filter (-f/--filter): Provide reference images containing faces you want to keep. The extractor will only retain faces whose identity embeddings match these references within a specified threshold.
• NFilter (-n/--nfilter): Provide reference images containing faces you want to exclude. The extractor will reject any faces matching these identities, even if they might otherwise pass other criteria.

Both mechanisms rely on the same facial recognition models used during normal extraction, computing 512-dimensional identity embeddings for comparison.

How Identity-Based Filtering Works Internally

Command-Line Interface Configuration

The CLI arguments are defined in [lib/cli/args_extract_convert.py](https://github.com/deepfakes/faceswap/blob/master/lib/cli/args_extract_convert.py), where the -f/--filter and -n/--nfilter options are registered as file path arguments. These accept one or more image files that serve as identity references.

Extraction Pipeline Integration

In [scripts/extract.py](https://github.com/deepfakes/faceswap/blob/master/scripts/extract.py), the IdentityExtractor class handles the filter logic:

• Validation: The _validate_inputs method (around lines 184-205) ensures that provided filter files exist, are valid images, and contain detectable faces.
• Embedding computation: For each filter/nfilter image, the extractor detects the face and computes its identity embedding, storing these in _filter_embeddings and _nfilter_embeddings lists.
• Flagging: The _has_filter_or_nfilter property tracks whether any filtering is active, allowing the pipeline to skip unnecessary comparison operations when filters aren't specified.

Recognition and Embedding Comparison

The core filtering logic resides in [plugins/extract/recognition/_base.py](https://github.com/deepfakes/faceswap/blob/master/plugins/extract/recognition/_base.py):

• Registration: The add_filters(filters, nfilters, threshold) method receives the embedding matrices and similarity threshold, storing them as instance attributes.
• Enable flags: The recogniser sets self._filter_enabled and self._nfilter_enabled to True when respective embeddings are provided.
• Distance checking: During face processing, the _check_face method (referenced around the filter_type handling logic) computes the Euclidean distance between the current face's embedding and all filter/nfilter embeddings.
• Decision logic:
  • If _nfilter_enabled is True and the distance to any nfilter embedding is below the threshold, the face is rejected immediately.
  • If _filter_enabled is True, the face is only accepted if its distance to at least one filter embedding is below the threshold.
  • When both are disabled, all detected faces proceed normally.

Practical Usage Examples

Basic CLI Usage

Extract faces from a video while keeping only identities matching target_person.jpg and excluding anyone resembling unwanted_person.jpg:

python scripts/extract.py \
    -i /path/to/input_video.mp4 \
    -o /path/to/extracted_faces \
    -f /path/to/target_person.jpg \
    -n /path/to/unwanted_person.jpg \
    -t 0.6

The -t parameter sets the similarity threshold (0.0 = identical, 1.0 = completely different). Lower values require stricter matches.

Programmatic Implementation

Integrate identity filtering into a custom Python workflow:

from scripts.extract import IdentityExtractor

# Initialize extractor with filter references

extractor = IdentityExtractor(
    filter_files=["/path/to/actor_ref_1.jpg", "/path/to/actor_ref_2.jpg"],
    nfilter_files=["/path/to/crowd_ref.jpg"],
    threshold=0.6,
)

# Process media

extractor.run(
    input_path="/videos/movie_scene.mp4",
    output_path="/output/extracted_actor",
)

Advanced Filter Management

For plugin developers extending the recognition system:

from plugins.extract.recognition._base import _BaseRecognizer
import numpy as np

# Assume filters and nfilters are pre-computed embedding arrays

# Shape: (num_reference_faces, 512)

filter_embeddings = np.array([...])  
nfilter_embeddings = np.array([...])

recognizer = _BaseRecognizer()
recognizer.add_filters(
    filters=filter_embeddings,
    nfilters=nfilter_embeddings,
    threshold=0.6
)

# During extraction loop

face_embedding = get_face_embedding()  # Your extraction logic

if recognizer.should_keep(face_embedding):
    process_face()

Summary

• The filter (-f) option retains only faces matching provided reference identities, while nfilter (-n) excludes faces matching unwanted identities.
• Both features operate by computing 512-dimensional facial embeddings and comparing Euclidean distances against a user-defined threshold.
• The implementation spans [lib/cli/args_extract_convert.py](https://github.com/deepfakes/faceswap/blob/master/lib/cli/args_extract_convert.py) for CLI parsing, [scripts/extract.py](https://github.com/deepfakes/faceswap/blob/master/scripts/extract.py) for pipeline orchestration, and [plugins/extract/recognition/_base.py](https://github.com/deepfakes/faceswap/blob/master/plugins/extract/recognition/_base.py) for the core distance-based filtering logic.
• Identity-based extraction is essential for isolating specific subjects in crowded scenes or removing unwanted individuals from training datasets.

Frequently Asked Questions

What is the difference between filter and nfilter in FaceSwap?

The filter option acts as a positive selector, ensuring only faces that match your reference images are extracted. The nfilter option acts as a negative selector, automatically rejecting any faces that resemble your excluded reference images. You can use either option independently or combine them to precisely control which identities enter your extraction pipeline.

How does FaceSwap calculate similarity for identity filtering?

FaceSwap uses a deep learning-based face recognition model to generate 512-dimensional embedding vectors for each face. During filtering, it calculates the Euclidean distance between the embedding of a detected face and the embeddings of your filter/nfilter reference images. If the distance falls below the threshold specified by the -t parameter (default typically around 0.6), the faces are considered a match.

Can I use multiple filter images for identity-based extraction?

Yes, you can provide multiple reference images for both filter and nfilter options. The extractor computes embeddings for all provided reference faces and checks the detected face against the entire set. If a detected face matches any one of the filter references (or nfilter references), the corresponding action (keep or reject) is triggered. This is particularly useful when the target person appears with different expressions, angles, or lighting conditions.

What happens if a face matches both filter and nfilter criteria?

The nfilter (negative filter) takes precedence over the filter. If a detected face's embedding is within the threshold distance of any nfilter reference, it is immediately rejected regardless of whether it also matches a filter reference. This safety mechanism ensures that explicitly excluded identities never enter your dataset, even in edge cases where a person might resemble both a target and an excluded individual.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}