Install & Compatibility
Where this runs
tested against v? · pip install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
build_error
glibcpy 3.10–3.920 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
FacerAPI
✓ from pyfacer.facer_api import FacerAPI
This quickstart demonstrates how to initialize the `FacerAPI` and perform a basic face detection on a dummy image. It highlights the internal dependency on the `facer` package and potential model download times.
import torch
import numpy as np
from PIL import Image
from pyfacer.facer_api import FacerAPI
# Create a dummy image (e.g., a black image with a white square)
# The underlying 'facer' library expects a torch.Tensor, typically (1, 3, H, W) float, normalized 0-1.
dummy_img_np = np.zeros((256, 256, 3), dtype=np.uint8)
dummy_img_np[100:150, 100:150] = [255, 255, 255] # Add a white square
# Convert NumPy array to PIL Image, then to PyTorch Tensor.
image_pil = Image.fromarray(dummy_img_np)
image_tensor = torch.from_numpy(np.array(image_pil)).float() / 255.0 # HWC, float 0-1
image_tensor = image_tensor.permute(2, 0, 1).unsqueeze(0) # CHW -> NCHW
try:
# Determine device
device = "cuda" if torch.cuda.is_available() else "cpu"
print(f"Initializing FacerAPI on {device}...")
# Instantiate the FacerAPI. This will internally load models via the 'facer' library.
# It might take a while on first run to download models.
api = FacerAPI(device=device)
print("Detecting faces...")
# Perform a face detection. `detect_faces` returns a list of facer.Face objects or similar.
detected_faces = api.detect_faces(image_tensor)
print(f"Number of detected 'faces': {len(detected_faces) if detected_faces else 0}")
if detected_faces:
# Assuming `facer.Face` objects have `boxes` attribute, as in the core `facer` library.
print(f"First 'face' (or object) bounding box: {detected_faces[0].boxes}")
except Exception as e:
print(f"An error occurred during pyfacer quickstart: {e}")
print("\nTroubleshooting:")
print("1. Ensure 'facer' library is also installed: `pip install facer`")
print("2. Models are downloaded by 'facer' on first use; this might require internet access.")
print("3. Check for CUDA errors if using GPU.")
Debug
Known issues
breakingThe `pyfacer` library is currently marked 'under development' (version 0.0.5), indicating its API surface is subject to frequent and undocumented breaking changes.fixPin exact versions of `pyfacer` and its dependencies. Refer directly to the source code (`pyfacer/facer_api.py`) for the most current API details, as documentation may be sparse.
affects: All 0.x versions
gotchaThe `pyfacer` library acts as an API wrapper around the separate `facer` PyPI package. `facer` must also be installed (`pip install facer`) for `pyfacer` to function, as it handles core functionalities like model loading and execution.fixAlways install both packages: `pip install pyfacer facer`.
affects: All versions
gotchaModels required by `pyfacer` are managed by its underlying `facer` dependency. These models are downloaded on the first use, which requires an active internet connection and may result in a significant delay during the first initialization of `FacerAPI`.fixEnsure internet connectivity during initial model loading. Be prepared for a download time. Check the `facer` library's documentation for any advanced model management or pre-downloading options.
affects: All versions
Upgrade
Version history
0.0.5latest on PyPI · released Jan 17, 2025
Audit
Dependencies
torchrequiredDeep learning framework for model execution.
torchvisionrequiredComputer vision utilities for PyTorch.
timmrequiredPyTorch Image Models, used for various backbones.
einopsrequiredFlexible tensor operations.
opencv-pythonrequiredComputer vision utility library.
facerrequiredThe core library that pyfacer wraps for model loading and execution. This is a critical implicit dependency that must be installed separately.