EgoBlur Demo

This repository contains a demo of EgoBlur models with visualizations.

Overview

EgoBlur is an open-source AI model from Meta designed to preserve privacy by detecting and blurring faces and license plates in images and videos. We provide Gen1 models for data captured with Aria Gen1 devices and Gen2 models for data captured with Aria Gen2 devices.

Important: Use the model generation that matches your data. If your data was captured with an Aria Gen1 device, use the Gen1 models and the egoblur-gen1 CLI. If your data was captured with an Aria Gen2 device, use the Gen2 models and the egoblur-gen2 CLI.

Gen1:

egoblur-gen1 command line tool — Python tool for PNG, JPEG, or MP4 files
EgoBlur VRS Utilities — C++ tool for Aria Gen1 VRS files
- See the EgoBlur VRS Utilities README for details.
See EgoBlur Gen1 wiki for Gen1 models' details.

Gen2 - ✨new✨:

egoblur-gen2 command line tool — Python tool for PNG, JPEG, or MP4 files
EgoBlur VRS Utilities — Users currently need to convert VRS files into video or image files to use the model. Please refer to the VRS to MP4 Converter for instructions on converting VRS to MP4. A future version of EgoBlur will support operating directly on VRS files.
See EgoBlur Gen2 wiki for Gen2 models' details.

Installation

Supported environments

Gen1 and Gen2 python command line tool:

Python version: 3.10-3.12
Platform: Fedora 43, Ubuntu 20.04, Ubuntu 22.04, Ubuntu 24.04, MacOS-14, MacOS-15
CUDA toolkit (optional): 12.8

Gen1 C++ VRS Utilities:

Ubuntu 22.04
libtorch 2.1
CUDA toolkit 12.1

Installation from PyPI

(Optional) Create and activate a fresh virtual environment:

mkdir -p ~/venvs
python3 -m venv ~/venvs/egoblur
source ~/venvs/egoblur/bin/activate
pip install --upgrade pip

Install EgoBlur directly from PyPI:
```
pip install egoblur
```

Download the repo:

git clone https://github.com/facebookresearch/EgoBlur.git

Getting Started

First, download the zipped models from the links provided. You can then pass these models as inputs to the CLI.

| Model | Download link | | ------------------ | ------------------------------------------------------------- | | ego_blur_face_gen1 | ego_blur_website | | ego_blur_lp_gen1 | ego_blur_website | | ego_blur_face_gen2 | ego_blur_website | | ego_blur_lp_gen2 | ego_blur_website |

CLI options

The CLI arguments are mostly identical between egoblur-gen1 and egoblur-gen2, with two differences:

Gen2 adds optional --camera_name for camera-specific defaults.
Gen2 preserves the input video FPS; Gen1 retains --output_video_fps for manually setting the output FPS.

A brief description of CLI args:

--camera_name (Gen2 only) use this argument to specify the camera type for automatic threshold selection. Valid options are: slam-front-left, slam-front-right, slam-side-left, slam-side-right, camera-rgb. See the stream id to camera label in project aria wiki. When specified, camera-specific default thresholds will be used for both face and license plate detection (see Camera-Specific Thresholds section below). This is optional.

--lp_model_path use this argument to provide the absolute EgoBlur license plate model file path. file path. You MUST provide either --face_model_path or --lp_model_path or both. If none is provided code will throw a ValueError.

--face_model_score_threshold use this argument to provide face model score threshold to filter out low confidence face detections. The values must be between 0.0 and 1.0. If not provided and --camera_name is specified (Gen2 only), camera-specific defaults are used. Otherwise set to default threshold for camera rgb.

--lp_model_path use this argument to provide absolute EgoBlur license plate file path. You MUST provide either --face_model_path or --lp_model_path or both. If none is provided code will throw a ValueError.

--lp_model_score_threshold use this argument to provide license plate model score threshold to filter out low confidence license plate detections. The values must be between 0.0 and 1.0. If not provided and --camera_name is specified (Gen2 only), camera-specific defaults are used. Otherwise set to default threshold for camera rgb.

--nms_iou_threshold use this argument to provide the NMS IoU threshold to filter out low confidence overlapping boxes. The values must be between 0.0 and 1.0, if not provided this defaults to 0.3.

--scale_factor_detections use this argument to scale detections by the given factor to allow blurring more area. The values can only be positive real numbers, e.g., 0.9 (values < 1) would mean scaling DOWN the predicted blurred region by 10%, whereas 1.1 (values > 1) would mean scaling UP the predicted blurred region by 10%.

--input_image_path use this argument to provide the absolute path for the given image image on which we want to make detections and perform blurring. You MUST provide either --input_image_path or --input_video_path or both. If none is provided code will throw a ValueError.

--output_image_path use this argument to provide the absolute path where we want to store the blurred image. to store the blurred image. You MUST provide --output_image_path with --input_image_path otherwise code will throw ValueError.

--input_video_path use this argument to provide the absolute path for the given video video on which we want to make detections and perform blurring. You MUST provide either --input_image_path or --input_video_path or both. If none is provided code will throw a ValueError.

--output_video_path use this argument to provide the absolute path where we want to store the blurred video. to store the blurred video. You MUST provide --output_video_path with --input_video_path otherwise code will throw ValueError.

Video FPS handling: the Gen2 script preserves the input video's FPS when writing the blurred output. If the input FPS metadata is missing or invalid, the script raises a ValueError; provide a video file with a valid, fixed FPS.

--output_video_fps (Gen1 only) use this argument to provide the FPS for the output video. The values must be positive integers; if not provided this defaults to 30.

CLI command examples

Download this repository to access the built-in demo assets. The samples are organized per generation:

Gen2 assets live under ${EGOBLUR_REPO}/gen2/demo_assets/
Gen1 assets live under ${EGOBLUR_REPO}/gen1/demo_assets/

Update the snippets below with absolute paths that match your system, for example:

export EGOBLUR_REPO=/absolute/path/to/ego_blur
export EGOBLUR_MODELS=/home/${USER}/ego_blur_assets

Extract the downloaded model files into ${EGOBLUR_MODELS} (for example, ${EGOBLUR_MODELS}/ego_blur_face_gen2.jit). After installing the package, run:

egoblur-gen2 --help

Face blurring (image)

egoblur-gen2 \
  --camera_name camera-rgb \
  --face_model_path ${EGOBLUR_MODELS}/ego_blur_face_gen2.jit \
  --input_image_path ${EGOBLUR_REPO}/gen2/demo_assets/test_face_image.png \
  --output_image_path ${EGOBLUR_REPO}/gen2/demo_assets/output/test_face_image_output.png

Face blurring (video)

egoblur-gen2 \
  --camera_name camera-rgb \
  --face_model_path ${EGOBLUR_MODELS}/ego_blur_face_gen2.jit \
  --input_video_path ${EGOBLUR_REPO}/gen2/demo_assets/test_face_video.mp4 \
  --output_video_path ${EGOBLUR_REPO}/gen2/demo_assets/output/test_face_video_output.mp4

License plate blurring (image)

egoblur-gen2 \
  --camera_name camera-rgb \
  --lp_model_path ${EGOBLUR_MODELS}/ego_blur_lp_gen2.jit \
  --input_image_path ${EGOBLUR_REPO}/gen2/demo_assets/test_lp_image.png \
  --output_image_path ${EGOBLUR_REPO}/gen2/demo_assets/output/test_lp_image_output.png

License plate blurring (video)

egoblur-gen2 \
  --camera_name camera-rgb \
  --lp_model_path ${EGOBLUR_MODELS}/ego_blur_lp_gen2.jit \
  --input_video_path ${EGOBLUR_REPO}/gen2/demo_assets/test_lp_video.mp4 \
  --output_video_path ${EGOBLUR_REPO}/gen2/demo_assets/output/test_lp_video_output.mp4

Note: Some license plates in output video frames may remain not blurred due to low detection confidence. This is expected, you can adjust the --lp_model_score_threshold to add low confidence detections.

Combined face + license plate (image + video)

egoblur-gen2 \
  --camera_name camera-rgb \
  --face_model_path ${EGOBLUR_MODELS}/ego_blur_face_gen2.jit \
  --lp_model_path ${EGOBLUR_MODELS}/ego_blur_lp_gen2.jit \
  --input_image_path ${EGOBLUR_REPO}/gen2/demo_assets/test_lp_image.png \
  --output_image_path ${EGOBLUR_REPO}/gen2/demo_assets/output/test_lp_image_output.png \
  --input_video_path ${EGOBLUR_REPO}/gen2/demo_assets/test_face_video.mp4 \
  --output_video_path ${EGOBLUR_REPO}/gen2/demo_assets/output/test_face_video_output.mp4

Gen1 demo assets

Gen1 sample media lives in ${EGOBLUR_REPO}/gen1/demo_assets/. Sample usage:

egoblur-gen1 \
  --face_model_path ${EGOBLUR_MODELS}/ego_blur_face_gen1.jit \
  --lp_model_path ${EGOBLUR_MODELS}/ego_blur_lp_gen1.jit \
  --input_image_path ${EGOBLUR_REPO

EgoBlur

Install / Use

README