Adds and documents a Highway-based optimized C++ implementation. Adds a new pure Rust crate, libfacedetection_rs, with a safe Rust API, static model data, scalar fallback, and runtime AVX2 acceleration.

[Wwupup]

Summary

This PR adds two major performance and language-extension tracks for libfacedetection:

1. Adds and documents a Highway-based optimized C++ implementation.
2. Adds a new pure Rust crate, libfacedetection_rs, with a safe Rust API, static model data, scalar fallback, and runtime AVX2 acceleration.

Changes

Highway optimized implementation

• Added an independent Highway implementation under highway/ while keeping the original C++ implementation untouched.

• Added Highway build integration through CMake, including support for:

  • find_package(hwy 1.3.0 CONFIG)
  • explicit hwy_DIR
  • FDT_HW_HIGHWAY_ROOT
  • scalar, SSE/default, AVX2 pure Highway, AVX2 hybrid, and AVX512 build modes

• Added the public Highway API entry point:

  int* results = facedetect_hw_cnn(result_buffer, bgr_image_data, width, height, step);

• Added optimized Highway kernels for pointwise, depthwise, maxpool, image/network flow, and postprocess flow.

• Added x86 hybrid AVX2 path using Highway packed pointwise plus guarded AVX2/FMA intrinsics for selected depthwise/maxpool kernels.

• Added benchmark and detection examples:

  • example/detect-image-highway.cpp
  • example/benchmark-highway.cpp
  • highway/benchmark/hw_resolution_benchmark.cpp

• Documented recommended external multi-threading model: one caller-owned result buffer per thread.

Performance documentation

• Added detailed Highway performance report and status docs:
  • highway/docs/hw-performance-report.md
  • highway/docs/hw-status.md
  • highway/docs/hw-cross-platform-execution-plan.md
• Updated root README.md and COMPILE.md with Highway build instructions, usage examples, backend descriptions, and benchmark tables.
• Documented measured Highway performance against the original scalar/AVX2 implementation across multiple input resolutions.

Rust crate

• Added a new pure Rust package under rust/ named libfacedetection_rs.

• Added safe public Rust API:

  • Detector
  • Detection
  • Face
  • DetectError
  • ResultBuffer

• Added high-level image API through the image crate:

  use libfacedetection_rs::{image, Detector};
  
  let image = image::open("face.jpg")?;
  let mut detector = Detector::new();
  let detection = detector.detect(&image)?;

• Added low-level RGB/BGR entry points for callers that already own decoded image buffers.

• Added compatibility result-buffer support matching the legacy libfacedetection layout.

• Added generated static Rust model data in rust/src/generated/model_data.rs, making the crate self-contained for publishing.

• Added full Rust detection pipeline:

  • image input conversion
  • model/filter loading
  • scalar kernels
  • x86 AVX2 kernels
  • network forward path
  • decode/postprocess/NMS
  • structured face output

• Added runtime AVX2 dispatch on x86/x86_64 with scalar fallback for other supported Rust targets.

• Added Rust benchmark helpers and development benchmark harnesses.

• Added Rust crate docs, changelog, license, diagrams, migration plan, publish-preparation plan, and optimization report.

Performance Notes

• Highway AVX2 hybrid shows significant speedups over the original AVX2 implementation in the documented resolution benchmark.
• The Rust AVX2 implementation is also benchmarked against the original C++ AVX2 path and shows improved throughput in the included benchmark tables.
• Benchmark notes, CPU/toolchain details, and reproduction commands are documented in README.md, COMPILE.md, and the Highway/Rust performance reports.

Test / Validation Notes

• Added unit-testable Rust modules for input validation, model loading, kernels, result buffers, and detector behavior.
• Added Highway test and benchmark targets through CMake.
• Added benchmark commands and reproduction notes for both Highway and Rust paths.

Files Added / Updated

• Added Highway docs, benchmarks, examples, and optimized kernels.
• Added root build/usage documentation for Highway and Rust.
• Added the complete rust/ crate including source, examples, docs, generated model data, and benchmark tooling.

[pszemus]

Great job! I noticed a several-fold speedup for my operations after enabling hybrid mode (HWY+AVX-2) compared to the original AVX-2.

When is the CMake install target scheduled to be added?

Edit: I've made a naive attempt in PR #384