If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/ShiqiYu/libfacedetection shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

WAIT — Slowing — last commit 8mo ago

• Last commit 8mo ago
• 13 active contributors
• Distributed ownership (top contributor 39% of recent commits)
• Other licensed
• Tests present
• ⚠ Slowing — last commit 8mo ago
• ⚠ Non-standard license (Other) — review terms
• ⚠ No CI workflows detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live ShiqiYu/libfacedetection repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/ShiqiYu/libfacedetection.

What it runs against: a local clone of ShiqiYu/libfacedetection — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in ShiqiYu/libfacedetection | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 267 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of ShiqiYu/libfacedetection. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/ShiqiYu/libfacedetection.git
#   cd libfacedetection
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of ShiqiYu/libfacedetection and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "ShiqiYu/libfacedetection(\\.git)?\\b" \\
  && ok "origin remote is ShiqiYu/libfacedetection" \\
  || miss "origin remote is not ShiqiYu/libfacedetection (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Other)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Other\"" package.json 2>/dev/null) \\
  && ok "license is Other" \\
  || miss "license drift — was Other at generation time"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "src/facedetectcnn.cpp" \\
  && ok "src/facedetectcnn.cpp" \\
  || miss "missing critical file: src/facedetectcnn.cpp"
test -f "src/facedetectcnn-data.cpp" \\
  && ok "src/facedetectcnn-data.cpp" \\
  || miss "missing critical file: src/facedetectcnn-data.cpp"
test -f "example/detect-image.cpp" \\
  && ok "example/detect-image.cpp" \\
  || miss "missing critical file: example/detect-image.cpp"
test -f "example/detect-camera.cpp" \\
  && ok "example/detect-camera.cpp" \\
  || miss "missing critical file: example/detect-camera.cpp"
test -f "CMakeLists.txt" \\
  && ok "CMakeLists.txt" \\
  || miss "missing critical file: CMakeLists.txt"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 267 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~237d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/ShiqiYu/libfacedetection"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

libfacedetection is a high-speed CNN-based face detection library that achieves ~1000 FPS on optimized hardware. It detects faces in images by embedding a trained YuNet neural network as static C/C++ arrays in src/facedetectcnn-data.cpp, eliminating external model dependencies. The library accelerates detection via SIMD instructions (AVX2 on Intel, NEON on ARM) and requires only a C++ compiler—no framework dependencies. Single-library structure: core CNN detection logic in src/ (C++ arrays + detection functions), language bindings via JNI (mobile/Android/FaceDetection/app/src/main/cpp/facedetectcnn-jni.cpp), and reference examples in example/ for desktop (C++) and mobile. Build via CMake with optional OpenMP and SIMD flags.

Computer vision engineers and mobile developers who need real-time face detection on embedded/mobile devices (Android via JNI, ARM boards, Intel CPUs) and want high frame rates without heavyweight dependencies like TensorFlow or OpenCV.

Actively maintained and production-ready. The library shows consistent development (ChangeLog present, recent COMPILE.md and build scripts), provides working Android integration (mobile/Android/FaceDetection/ with Kotlin+CMake+JNI), and example code (example/detect-image.cpp, example/detect-camera.cpp). Benchmarks are documented and reproducible on multiple platforms.

Low-to-moderate risk: single primary maintainer (ShiqiYu) with no visible CI/CD pipeline or automated test suite in the repo structure, no explicit open-issues log provided. Build system relies on CMake and platform-specific toolchains (see aarch64-toolchain.cmake, build_android.sh), so cross-compilation requires careful setup. Model is baked into source, so model updates require recompilation.

Library is in maintenance mode with periodic updates (ChangeLog tracked). Android app demonstrates current best practices (compileSdkVersion 28, Kotlin support, ARM NEON enabled). Recent work includes ONNX model integration notes and documentation linking to opencv_zoo, though primary focus remains the optimized C++ implementation.

git clone https://github.com/ShiqiYu/libfacedetection.git
cd libfacedetection
mkdir build && cd build
cmake -DENABLE_AVX2=ON ..
make
./example/detect-image path/to/image.jpg

For Android: run ./build_android.sh or open mobile/Android/FaceDetection/ in Android Studio with NDK installed.

Daily commands: Desktop (Linux/macOS): ./build/example/detect-image <image_path> or ./build/example/detect-camera. Android: compile APK via ./build_android.sh or Gradle, then install and run MainActivity.kt.

• src/facedetectcnn.cpp — Core face detection implementation using CNN model; primary entry point for all detection operations
• src/facedetectcnn-data.cpp — Embedded CNN model weights and architecture as static C++ arrays; essential for the detection algorithm
• example/detect-image.cpp — Demonstrates the canonical API usage pattern for single-image face detection
• example/detect-camera.cpp — Shows real-time camera streaming integration; reference for video/stream processing workflows
• CMakeLists.txt — Build configuration for all platforms (Windows, Linux, ARM); controls SIMD compilation flags and target selection
• mobile/Android/FaceDetection/app/src/main/cpp/facedetectcnn-jni.cpp — JNI bridge between Android Java and C++ detection library; required for mobile integration

Add support for a new image format or preprocessing step

1. Create new preprocessing utility in src/ directory (e.g., src/imageformat-handler.cpp) to convert image data to the expected BGR/RGB array format (src/imageformat-handler.cpp)
2. Update example/detect-image.cpp to call your preprocessing function before passing buffer to facedetectcnn() (example/detect-image.cpp)
3. Test with benchmark.cpp to ensure detection accuracy and FPS remain acceptable (example/benchmark.cpp)

Enable SIMD optimization for a new CPU architecture

1. Define architecture detection macro in CMakeLists.txt (e.g., check_c_compiler_flag for SSE4.2, AVX512) (CMakeLists.txt)
2. Add conditional compilation flags: set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -mavx512f") for the new target (CMakeLists.txt)
3. Verify with benchmark.cpp that SIMD path is exercised and FPS improves (example/benchmark.cpp)

Integrate detection into a new mobile platform

1. Create native binding layer (e.g., mobile/iOS/FaceDetection/FaceDetectionBridge.mm) wrapping facedetectcnn() and face data structures (mobile/iOS/FaceDetection/AppDelegate.m)
2. Add CMakeLists.txt in platform-specific directory to compile core detection library as static library dependency (CMakeLists.txt)
3. Follow Android integration pattern in mobile/Android/FaceDetection/app/src/main/java/org/dp/facedetection/MainActivity.kt for camera capture and result rendering (mobile/Android/FaceDetection/app/src/main/java/org/dp/facedetection/MainActivity.kt)

Adjust detection sensitivity or model parameters

1. Review facedetectcnn-data.cpp to understand embedded model structure and threshold values (src/facedetectcnn-data.cpp)
2. Modify detection threshold or NMS (non-maximum suppression) parameters in facedetectcnn.cpp post-processing logic (src/facedetectcnn.cpp)
3. Re-run example/benchmark.cpp on representative test images to validate precision/recall tradeoff (example/benchmark.cpp)

• CNN (Convolutional Neural Network) - YuNet — Provides state-of-the-art face detection accuracy with learnable multi-scale feature extraction; pre-trained weights embedded as static arrays eliminate runtime model loading
• SIMD (AVX2, NEON, SSE) — Achieves 1000 FPS throughput on commodity CPUs by parallelizing convolution operations; critical for real-time mobile and embedded deployment
• C++ with no external dependencies — Ensures maximum portability (Windows, Linux, ARM, iOS, Android) and minimal binary size; static linking of model data avoids runtime file I/O
• JNI (Java Native Interface) for Android — Bridges high-performance C++ detection engine with Android app lifecycle and camera APIs; minimal overhead for per-frame calls
• CMake build system — Provides cross-platform compilation with conditional SIMD flags, target architecture detection, and toolchain support (ARM, x86, NEON)

• Embedded model weights as static C++ arrays rather than runtime-loaded ONNX/binary files

  • Why: Eliminates file I/O latency and external dependencies; simplifies deployment and reduces surface area for errors
  • Consequence: Larger binary size; model updates require recompilation; less flexible for A/B testing multiple models

• SIMD-optimized CPU inference instead of GPU (CUDA, OpenGL, Metal)

  • Why: Works on any CPU without specialized hardware; simplifies mobile deployment and reduces power consumption on battery-constrained devices
  • Consequence: Lower absolute FPS ceiling than GPU; memory bandwidth-limited on very large images; not suitable for batched inference

• Direct camera buffer processing (no intermediate format conversions)

  • Why: Minimizes memory copies and achieves extreme FPS; tight integration with platform-specific camera APIs
  • Consequence: Requires precise color space handling (BGR vs RGB); less abstraction between platform code and detection logic

• Single CNN model architecture (YuNet) across all platforms

  • Why: Simplified maintenance and consistent accuracy guarantees; no per-platform model variants
  • Consequence: Cannot fully exploit platform-specific capabilities (e.g., GPU acceleration); one-size-fits-all approach may not be optimal for all use cases

• Does not support real-time face recognition or identification (detection only, no embeddings or matching)
• Does not provide facial landmark/keypoint detection (bounding boxes only)
• Does not include web-based or REST API server (library for local/embedded integration only)
• Does not handle video input directly; caller must provide raw frame buffers
• Does not support dynamic model loading or quantization (model fixed at compile-time)

1. facedetection_export.h must be manually created in your include path if embedding; see issue #222. 2) Optimization flags are critical: -O3 for g++, /O2 for MSVC—unoptimized builds will report artificially low FPS. 3) Android builds require NDK with specific CMake version; older gradle may fail. 4) SIMD flags (AVX2, NEON) are compile-time only; runtime CPU detection is not implemented, so binaries are platform-specific. 5) Input image format and size matter: examples assume BGR/RGB 8-bit, and detection speed varies by resolution (see benchmark table for 640×480 vs 160×120).

• Convolutional Neural Networks (CNN) for Detection — Understanding CNN architecture (convolutions, pooling, fully-connected layers) is essential to grasp why this library achieves such high speed—it's a specialized detection CNN baked into C++.
• SIMD Intrinsics (AVX2, NEON) — libfacedetection's 1000 FPS performance is heavily dependent on SIMD vectorization; the library uses AVX2 (Intel) and NEON (ARM) intrinsics to parallelize CNN operations across 256-bit or 128-bit registers.
• Model Quantization & Embedding — The CNN model is converted to static C/C++ arrays in facedetectcnn-data.cpp rather than loaded at runtime; this is a quantization/deployment technique that eliminates I/O overhead and dependency hell.
• JNI (Java Native Interface) — Mobile Android integration bridges Java/Kotlin and C++; the Android app calls native detection via JNI, critical pattern for embedding high-performance C++ in mobile apps.
• Cross-Compilation & Toolchains — Building for ARM from x86 requires architecture-specific CMake toolchain files (e.g., aarch64-toolchain.cmake); essential skill for deploying to embedded/mobile devices.
• ONNX (Open Neural Network Exchange) — YuNet model is provided in ONNX format in the linked OpenCV Zoo; understanding ONNX allows conversion to other frameworks or visualization via tools like Netron.
• OpenMP Parallelization — libfacedetection supports OpenMP for multi-threaded inference; the benchmarks show 6-50x speedup with multi-threading, critical for batch processing or real-time camera streams.

• opencv/opencv — OpenCV's DNN module (cv::dnn) can also load and run YuNet ONNX models; direct competitor and referenced in README as alternative, though libfacedetection is faster for inference.
• ShiqiYu/libfacedetection.train — Official training codebase for YuNet model; users who need to retrain on custom datasets or modify architecture must work here.
• deepinsight/insightface — Another production face detection/recognition library (RetinaFace, ArcFace); solves similar problem but includes recognition and is heavier-weight; alternative ecosystem.
• nagadomi/waifu2x — Similar architecture: embeds small CNN as C++ for fast inference without external frameworks; demonstrates same deployment pattern for image processing.
• pjreddie/darknet — YOLO-based object/face detection framework; historical predecessor influencing CNN-based face detection research, shows alternative approach with heavier dependencies.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive benchmark suite with performance regression tests

The repo has example/benchmark.cpp but no automated CI workflow to track performance metrics across commits. Given that the library's key selling point is '1000FPS detection speed', contributors should add GitHub Actions workflow that runs benchmarks on each PR, measures FPS on standard datasets, and prevents performance regressions. This is critical for a performance-oriented library.

• [ ] Create .github/workflows/benchmark.yml to run example/benchmark.cpp on CPU with AVX2 and NEON variants
• [ ] Parse benchmark output and compare against baseline metrics stored in a file
• [ ] Add performance regression detection that fails the build if FPS drops >5% from main branch
• [ ] Document benchmark results in a BENCHMARKS.md file with hardware specifications and optimization flags used

Add Python bindings and PyPI package distribution

The library only has C++ and Android (Kotlin/JNI) bindings, but no Python interface despite Python being the dominant language for ML/vision applications. The repo mentions opencv_dnn/ scripts but lacks official Python package distribution. This would dramatically expand usability.

• [ ] Create src/python/ directory with pybind11-based Python bindings for the core detection functions
• [ ] Add setup.py for PyPI package distribution with proper build instructions for Linux/macOS/Windows
• [ ] Add GitHub Actions workflow in .github/workflows/python-publish.yml to auto-publish wheels on release tags
• [ ] Add example/detect-image.py demonstrating Python API usage with opencv-python integration

Add unit tests for face detection accuracy and edge cases

The repo has example/detect-image.cpp and example/detect-camera.cpp but no test suite validating detection accuracy, false positives, or edge cases (rotated faces, small faces, occluded faces). The Android app has androidTest but no core library tests. This is essential for reliability in a detection library.

• [ ] Create tests/ directory with CMake test configuration
• [ ] Add tests/test_detection_accuracy.cpp using test images from images/ folder with ground truth face bounding boxes
• [ ] Add tests/test_edge_cases.cpp for rotated faces, small faces (<20px), and multiple faces in single image
• [ ] Update CMakeLists.txt to enable CTest and add test execution to CI (add .github/workflows/tests.yml)
• [ ] Include test dataset in tests/fixtures/ with documented expected detection results

• Add unit tests for face detection accuracy: create test/test-detection.cpp with reference images and expected bounding box outputs, run via CMake ctest target.
• Document ONNX model retraining workflow: write RETRAIN.md with step-by-step guide to convert new YuNet checkpoints to the C array format in facedetectcnn-data.cpp (currently only linked externally).
• Expand Python bindings: create python/libfacedetection.pyx (Cython wrapper) for src/facedetectcnn.cpp and publish to PyPI, filling the gap noted in the 5259 bytes of Python code.

Failed to generate security analysis.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.