tomas-gajarsky/facetorch

What it solves

Building face analysis pipelines often means wrestling with model source code, dependencies, and reproducibility. Facetorch solves this by curating open-source face analysis models, packaging them into a portable torch.export format (.pt2), and offering a unified Python toolkit so you can run detection and analysis without needing model source code at inference time.

How it works

Facetorch centers on a FaceAnalyzer class that orchestrates several pluggable components: a reader that handles images from local paths, tensors, NumPy arrays, PIL images, or bytes; a detector (a neural network wrapper) that finds faces; a unifier that normalizes face sizes and pixel ranges; a set of predictors (neural network wrappers for tasks like embedding, verification, expression, etc.); and utilizers (e.g. drawing bounding boxes). Configuration is managed via Hydra/OmegaConf, letting you select CPU or GPU profiles and override settings. Models are serialized with torch.export, so inference doesn't require the original code. The library's default behavior is deterministic: by default it coerces inputs and only fetches a remote image if you explicitly configure a bounded URLReader. Models are loaded lazily on first use and cached, and the library supports dynamic batching for faces detected within a single image.

Who it's for

Developers and researchers who need a flexible, reproducible way to run face detection and analysis (e.g., verifying identity, reading facial expressions) in Python, especially those who want to avoid managing model internals directly. It requires Python 3.11–3.12 and PyTorch 2.6–2.13, with Linux x86-64 as the official platform (Windows/macOS/ARM are experimental).

Highlights

• Portable models in .pt2 format — no model source code needed at inference; supports dynamic batch and torch.compile
• Governed extensibility: custom components must pass validation, including an immutable manifest, provenance, and model-rights review
• Deterministic input pipeline: accepts local paths, tensors, NumPy arrays, PIL images, or bytes; remote input only via an explicit, bounded URLReader
• Reproducible environments through uv, conda-lock, and Docker; cache directories can be controlled via environment variables
• Lazy loading and caching of detector/predictor models; batch size for faces is capped by built-in predictors at 64