{"id":8481,"library":"pyfacer","title":"Pyfacer","description":"Pyfacer is a Python API that wraps the core 'facer' library, providing a high-level interface for face-related tasks such as detection, parsing, recognition, and alignment. It is part of the broader FacePerceiver ecosystem. Currently at version 0.0.5, it is explicitly marked as 'under development', indicating an early-stage project with potential for rapid changes. Its release cadence is infrequent.","status":"active","version":"0.0.5","language":"en","source_language":"en","source_url":"https://github.com/FacePerceiver/facer-api","tags":["face detection","face recognition","computer vision","face parsing","deep learning"],"install":[{"cmd":"pip install pyfacer facer","lang":"bash","label":"Install pyfacer and its core dependency"}],"dependencies":[{"reason":"Deep learning framework for model execution.","package":"torch"},{"reason":"Computer vision utilities for PyTorch.","package":"torchvision"},{"reason":"PyTorch Image Models, used for various backbones.","package":"timm"},{"reason":"Flexible tensor operations.","package":"einops"},{"reason":"Computer vision utility library.","package":"opencv-python"},{"reason":"The core library that pyfacer wraps for model loading and execution. This is a critical implicit dependency that must be installed separately.","package":"facer","optional":false}],"imports":[{"symbol":"FacerAPI","correct":"from pyfacer.facer_api import FacerAPI"}],"quickstart":{"code":"import torch\nimport numpy as np\nfrom PIL import Image\nfrom pyfacer.facer_api import FacerAPI\n\n# Create a dummy image (e.g., a black image with a white square)\n# The underlying 'facer' library expects a torch.Tensor, typically (1, 3, H, W) float, normalized 0-1.\ndummy_img_np = np.zeros((256, 256, 3), dtype=np.uint8)\ndummy_img_np[100:150, 100:150] = [255, 255, 255] # Add a white square\n\n# Convert NumPy array to PIL Image, then to PyTorch Tensor.\nimage_pil = Image.fromarray(dummy_img_np)\nimage_tensor = torch.from_numpy(np.array(image_pil)).float() / 255.0 # HWC, float 0-1\nimage_tensor = image_tensor.permute(2, 0, 1).unsqueeze(0) # CHW -> NCHW\n\ntry:\n    # Determine device\n    device = \"cuda\" if torch.cuda.is_available() else \"cpu\"\n    print(f\"Initializing FacerAPI on {device}...\")\n\n    # Instantiate the FacerAPI. This will internally load models via the 'facer' library.\n    # It might take a while on first run to download models.\n    api = FacerAPI(device=device)\n\n    print(\"Detecting faces...\")\n    # Perform a face detection. `detect_faces` returns a list of facer.Face objects or similar.\n    detected_faces = api.detect_faces(image_tensor)\n\n    print(f\"Number of detected 'faces': {len(detected_faces) if detected_faces else 0}\")\n    if detected_faces:\n        # Assuming `facer.Face` objects have `boxes` attribute, as in the core `facer` library.\n        print(f\"First 'face' (or object) bounding box: {detected_faces[0].boxes}\")\n\nexcept Exception as e:\n    print(f\"An error occurred during pyfacer quickstart: {e}\")\n    print(\"\\nTroubleshooting:\")\n    print(\"1. Ensure 'facer' library is also installed: `pip install facer`\")\n    print(\"2. Models are downloaded by 'facer' on first use; this might require internet access.\")\n    print(\"3. Check for CUDA errors if using GPU.\")\n","lang":"python","description":"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."},"warnings":[{"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.","message":"The `pyfacer` library is currently marked 'under development' (version 0.0.5), indicating its API surface is subject to frequent and undocumented breaking changes.","severity":"breaking","affected_versions":"All 0.x versions"},{"fix":"Always install both packages: `pip install pyfacer facer`.","message":"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.","severity":"gotcha","affected_versions":"All versions"},{"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.","message":"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`.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Install the `facer` package: `pip install facer` (or `pip install pyfacer facer`)","cause":"The core `facer` library, which `pyfacer` depends on internally, has not been installed.","error":"ModuleNotFoundError: No module named 'facer'"},{"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.","cause":"Attempting to run models on a GPU with insufficient VRAM, or incorrect device setup.","error":"RuntimeError: CUDA error: out of memory"},{"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.","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.","error":"FileNotFoundError: No such file or directory: '...' (model path related)"}]}