Pyfacer

Common errors

• ModuleNotFoundError: No module named 'facer'

  cause The core `facer` library, which `pyfacer` depends on internally, has not been installed.
  fix Install the `facer` package: `pip install facer` (or `pip install pyfacer facer`)

• RuntimeError: CUDA error: out of memory

  cause Attempting to run models on a GPU with insufficient VRAM, or incorrect device setup.
  fix Try running on CPU by explicitly setting `device='cpu'` during `FacerAPI` initialization (e.g., `api = FacerAPI(device='cpu')`). Consider reducing input image resolution if possible.

• FileNotFoundError: No such file or directory: '...' (model path related)

  cause The `facer` library (underlying `pyfacer`) could not find or download required models. This might be due to network issues, disk permissions, or a corrupted model cache.
  fix Check your internet connection. Verify write permissions in your user's cache directory (typically `~/.cache/facer`). If issues persist, try clearing the `facer` model cache and retrying model loading.

Warnings

• breaking The `pyfacer` library is currently marked 'under development' (version 0.0.5), indicating its API surface is subject to frequent and undocumented breaking changes.
  Fix: Pin 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.
• gotcha The `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.
  Fix: Always install both packages: `pip install pyfacer facer`.
• gotcha Models 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`.
  Fix: Ensure 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.

Install

• pip install pyfacer facer Install pyfacer and its core dependency

Imports

• FacerAPI

  from pyfacer.facer_api import FacerAPI

Quickstart

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.")