ZQCNN: C Inference Framework with Face and Vision Examples

ZQCNN's C Inference Scope and Intended Users

ZQCNN addresses the need to run trained neural-network models in C-oriented software without adopting a larger application framework around the inference code. The README identifies Windows, Linux, and ARM Linux as supported targets. The repository layout is centered on `ZQCNN/`, with a separate `ZQ_GEMM/` implementation, sample programs, conversion utilities, and model files. This makes the project relevant to engineers integrating face detection or recognition into an existing native codebase, especially when model loading, tensor layout, and convolution execution need direct inspection.

The examples cover several concrete areas rather than one narrow model family. MTCNN is used for face and head detection. SSD examples handle object detection. `SampleVideoFaceDetection_Interface.cpp` contains a video-mode face pipeline with 106-point landmarks and a head-pose gaze model. `SampleOCR` demonstrates text recognition, but the README explicitly says that it does not include text detection and expects an already cropped image. ZQlibFaceID and related samples indicate additional face identity functionality.

ZQCNN is not presented as a general training platform. The training section points to separate repositories for SSD, gender and age estimation, MTCNN, and MTCNN head detection. That division matters when judging adoption. A team that needs an end-to-end training workflow must treat those companion projects and model exports as separate dependencies. ZQCNN is best evaluated as the inference and conversion side of a native deployment stack.

Inside ZQCNN's Model, Tensor, and GEMM Path

The repository contains conversion-related directories such as `TensorFlow_to_ZQCNN`, `onnx_to_ZQCNN`, `ZQCNN_to_MNN`, and `manualExportCaffe`. This indicates that model conversion is part of the intended workflow, but the README does not give one universal input format or a complete conversion command for every source framework. Supported examples include a PyTorch SSD workflow and models converted from TensorFlow, while the presence of an MNN export directory shows that model interchange is treated as a separate concern.

At the core, the README documents MTCNN and SSD model artifacts using `.zqparams` files together with `.nchwbin` files. The `nchw` naming indicates that the binary representation is organized around the NCHW layout, which is common in native C and C++ inference implementations. The documentation does not specify tensor allocation details, layer dispatch order, or a public C API in the excerpt, so those parts should be checked in the headers and sample source before integration.

The numerical backend is more explicit. ZQCNN can use its built-in ZQ_GEMM implementation, an external BLAS implementation, or an ARM-specific combined backend. The project documentation says that the internal implementation has no `cblas_*` calls and can run without an MKL runtime. On ARM, `openblas_zq_gemm` is intended to choose between OpenBLAS and ZQ_GEMM for convolution work. A documented fix changed compile-time macro handling so command-line definitions can take precedence, and CMake now consumes a computed `ZQCNN_BLAS_BACKEND` value. This is a meaningful architectural feature, but it also makes the build configuration part of the API surface.

CMake Build and First Native Example

The current README, updated for October 2026, states that CMake is the unified build entry and that Visual Studio project files are no longer retained. On Windows with Visual Studio 2022, configure and build the x64 configuration with:

cmake -S . -B build_x64 -G"Visual Studio 17 2022" -A x64
cmake --build build_x64 --config Release -j8
cd cmake-out-win32-x64/release/Release

The first command configures the project, the second builds the Release configuration, and the final command changes to the executable directory described by the README. That directory is said to contain links for `data/` and `model/` along with third-party DLLs, allowing supported examples to run there.

On Linux, the documented sequence is:

mkdir -p build && cd build && cmake .. && make -j8

After a successful build, run an example from its output directory. The README says that `imshow` and `waitKey` calls in the samples have been commented out, so the examples should not block on an OpenCV display window as written. The repository includes MTCNN and SSD weights, but SphereFace, ArcFace, PersonPose, NSFW, and TextBoxes examples require additional weights from the Model Zoo. Some examples also require extra image data.

The first practical use should therefore be a supported sample whose required assets are already present. For other examples, download the exact model files and any additional images before invoking the corresponding executable. The README does not document a single universal executable name, so it should not be invented.

ARM, BLAS, and Platform Configuration Boundaries

ZQCNN's backend options are not interchangeable across architectures. The README identifies `openblas_zq_gemm` as meaningful only on ARM because its dispatch path exists under `__ARM_NEON`. Passing that value on x86 is documented as a configure-time error rather than a silently ignored setting. This is a useful guard, although it means backend names must be selected with the target CPU in mind.

The bundled OpenBLAS files are identified as ARM 32-bit libraries under `3rdparty/lib/`. An x86-64 build that requests `-DBLAS_TYPE=openblas` therefore needs a matching OpenBLAS library supplied separately. Without it, CMake should report the architecture mismatch. That behavior is clearer than proceeding with an incompatible library, but it adds deployment preparation to the build process.

The README also distinguishes the default path from MKL. ZQCNN does not require MKL by default, and the internal `ZQ_GEMM` path is available when MKL is absent. If MKL is desired, `ZQ_CNN_CompileConfig.h` contains `ZQ_CNN_USE_MKL_GEMM`. For the combined ARM path, the documentation describes compile-time macros such as `ZQ_CNN_USE_ZQ_GEMM` and `ZQ_CNN_USE_BLAS_GEMM`. Exact values and their interaction with CMake should be confirmed from `ZQCNN/ZQ_CNN_CompileConfig.h` and the sample CMake files before shipping a custom configuration.

The repository also includes `tools/check_blas_config.py`, which the README describes as a configuration gate covering eight macro arrangements. This indicates that backend selection is treated as a regression-sensitive build decision rather than a cosmetic compiler option.

Model Assets and Conversion Boundaries

The bundled model directory is not a complete model catalog for every sample. The README specifically identifies MTCNN and SSD weights as included, while examples for SphereFace, ArcFace, PersonPose, NSFW, and TextBoxes need files obtained through the Model Zoo. Some model references are distributed through external download links, and the README lists extraction codes for certain archives. This makes asset management a practical part of deployment rather than an optional afterthought.

The OCR example illustrates the boundary between recognition and detection. Its input must already be cropped because the project does not currently provide text detection. A team looking for an end-to-end OCR pipeline would therefore need another component. Similarly, the MTCNN head detector is described as trained on the Hollywood Heads dataset, with the README evaluating the result modestly. The existence of the demo does not imply that it is appropriate for every camera, demographic, or accuracy target.

Model conversion support is distributed across separate tools and companion training repositories. The README does not establish a single command that converts every ONNX, TensorFlow, PyTorch, MXNet, or Caffe model into a ZQCNN artifact. It also does not provide compatibility guarantees for every layer, operator, quantization format, or model version. An adoption decision should therefore be based on the exact model conversion path and the headers used by the target sample, not on the broad list of conversion directories.

The repository includes a model conversion path to MNN, but that is an export utility rather than evidence that ZQCNN itself accepts MNN models at inference time. Keeping that distinction clear prevents a directory-level misunderstanding during integration planning.

Maintenance, Licensing, and Upgrade Cost

ZQCNN is not archived, and its last push was on 2026-10-07. The repository has no GitHub releases, so there is no release version or packaged upgrade trail documented in the repository metadata. That does not mean the project is inactive, but it does mean adopters should not assume that tagged releases provide a migration path. The README's October 2026 build notes document recent changes to CMake and BLAS configuration, yet the history also contains entries dating back to 2019, 2020, and 2022.

An upgrade can therefore affect more than application code. Maintainers may need to review CMake generator settings, output directories, compile-time macros, model file names, and backend selection. The README says the old Visual Studio solution and project files are no longer retained, which is a direct migration constraint for Windows developers. It also documents fixes to BLAS macro propagation and CMake backend matching. Those changes are relevant when reproducing an existing build.

The repository is licensed under MIT. That permits broad use under the license terms, but it does not answer questions about the licenses of separately downloaded model files, external datasets, MKL, OpenBLAS, or other third-party components. Those assets should be reviewed independently before redistribution. The license also does not make the included demonstration models equivalent to application-specific training data or guarantee suitability for a particular deployment.

When ZQCNN Is the Right Tool

ZQCNN is a reasonable candidate for a native C integration when the team needs face detection, MTCNN pipelines, SSD inference, landmark processing, or a custom model format and wants to inspect the implementation rather than depend on a black-box runtime. It is especially relevant when ARM deployment or comparison between ZQ_GEMM and OpenBLAS matters, because the repository exposes that decision explicitly.

It is the wrong choice when the requirement is a fully managed training and deployment platform, a complete text-recognition pipeline, or a model ecosystem with documented compatibility guarantees across common formats. The absence of GitHub releases, the external model assets, the architecture-sensitive OpenBLAS handling, and the lack of a universal conversion command all increase integration work.

A concrete alternative is a higher-level framework with a broader model registry and packaged runtime. The trade-off is direct native control versus ecosystem coverage. ZQCNN exposes low-level C-oriented inference and custom GEMM choices; a higher-level runtime may reduce conversion and compatibility work while adding a more substantial dependency. The alternative should be selected based on whether ZQCNN's model format and backend control solve a requirement that a general framework cannot meet.

Editorial conclusion

Adopt ZQCNN when you need a C or C++ inference layer and want direct control over its model format, layers, or GEMM backend. Do not choose it merely because a demo exists, since many demos need separately downloaded weights or data, and OpenBLAS support differs by CPU architecture. Verify first that the target platform is supported, that the required model files are available, and that the selected `ZQCNN_BLAS_BACKEND` produces the intended build configuration.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. zuoqing1988/ZQCNN on GitHub