retinaface-xs

RetinaFace training checkpoints

Raw training/compression-sweep checkpoints from this project's private training pipeline, plus the deploy-ready exports built from them. Layout is checkpoints/<arch>/pytorch/<arch>_cN.zip (a plain PyTorch state_dict, one per compression-sweep cluster count, _float32 for the uncompressed baseline) and, once exported, checkpoints/<arch>/{onnx,tflite,tfjs,coreml}/<arch>_cN.zip (the corresponding ONNX / TFLite / TF.js / CoreML artifacts). Every pytorch/ zip contains exactly one file, always named checkpoint.pth.

Loading a checkpoint

import zipfile, torch

with zipfile.ZipFile("path/to/checkpoint.zip") as zf:
    with zf.open("checkpoint.pth") as f:
        state_dict = torch.load(f, map_location="cpu", weights_only=True)

Every backbone's pytorch checkpoints -- resnet50 included -- are linked from the checkpoint column of its table below.

ONNX exports (checkpoints/<arch>/onnx/<arch>_cN.zip, plus _float32.zip), TFJS exports (checkpoints/<arch>/tfjs/, plus _float32.zip) and TFLite exports (checkpoints/<arch>/tflite/, plus _float32.zip) exist for every backbone's best-mean-AP level, 256- and 2-cluster levels and selected (bold) level; float32 ONNX/TFLite/TFJS exist for every backbone, resnet50 included. CoreML exports (checkpoints/<arch>/coreml/<arch>_cN.zip) cover the same levels as ONNX, float32 included. Every backbone, resnet50 included, has all 14 PyTorch sweep points (2-8, 12, 16, 32, 64, 128, 256, float32).

Export verification

Every published ONNX, TFLite, TFJS and CoreML file has been checked against the PyTorch checkpoint it was exported from on the full 3226-image WIDER FACE val set (inference/export_check.py --format onnx|tflite|tfjs|coreml), on the same fixed 640x640 letterbox preprocessing. Each artifact was downloaded fresh from this repo, its sha256 compared with the checksum this repo reports for it, and then evaluated. Each cell below is the converted file's mean AP (%) and, in parentheses, its difference from the PyTorch reference run in the same script. The bold row for each backbone is its selected level, matching the bold row in that backbone's metrics table below.

ONNX and TFJS match PyTorch to within 0.07% everywhere they were checked and CoreML to within 0.00%. TFLite is the exception: it loses accuracy at low cluster counts (e.g. resnet18 at 2 clusters, -1.38%; at 5 clusters, -0.92%) -- prefer ONNX or TFJS when that matters. PyTorch differs by ~0.02% between CPU and CUDA, so differences below that are noise. AP here is the fixed-size-wrapper AP, so it is only comparable across the columns above, not to the variable-size AP in the per-backbone metrics tables further down.

Sizes and compression of the ONNX exports ("raw" = uncompressed model.onnx on disk; "zip" = the downloadable .zip; "compression ratio" = that backbone's float32 ONNX size divided by this row's size, computed separately for raw and zip -- raw shrinks only modestly since palettization mainly shrinks index redundancy that gzip exploits, not the graph's own tensor layout, while zip captures the real deployable-size win). The float32 rows are the uncompressed reference every other row is measured against; resnet50 and mobilenetv1_0.50 c12 raw sizes are listed only where measured:

Per-file checksums (sha256 exactly as this repo reports them) and full Easy/Medium/Hard/mean AP:

<details> <summary>resnet50 PyTorch checkpoints (14 files)</summary>

Real full-val AP through the fixed-size wrapper on CUDA; every zip's sha256 was compared with the checksum this repo reports (all 14 identical).

</details> <details> <summary>ONNX files (35), converted vs. PyTorch</summary> </details> <details> <summary>TFLite files (35), converted vs. PyTorch</summary> </details> <details> <summary>TFJS files (35), converted vs. PyTorch</summary> </details> <details> <summary>CoreML file checksums (35), converted vs. PyTorch</summary>

AP is PyTorch / CoreML, run on the exact file bytes with the sha256 shown (identical to the checksum this repo reports).

</details>

To check a file yourself: download it, sha256sum it and compare with the value above, then run inference/export_check.py --format <fmt> --network <backbone> --hf-repo azemel/retinaface-xs --hf-level <level> (ONNX needs --onnx-provider CPU|CUDA, CoreML needs --compute-units and macOS).

CoreML verification

Every exported CoreML file has been verified against its PyTorch source on the full 3226-image WIDER FACE val set (inference/export_check.py --format coreml, the same fixed 640x640 letterboxed input as the ONNX check above; inference/validate_coreml.sh re-checks the published files straight from this repo). PyTorch vs. CoreML mean AP is identical (0.00%) at all 35 exported levels below on CPU_AND_GPU (the GPU, "MPS" on Apple Silicon), and also on CPU_ONLY for the 27 rows marked GPU + CPU. The CoreML input is a native RGB ImageType; the exported graph permutes it to the BGR order the checkpoints were trained on.

GPU caveat, and why the 128/256-cluster CoreML files are large: on the CoreML GPU path a per-channel-palettized dense spatial (3x3) conv is wrong when its index table is 2-, 4- or 8-bit wide (CPU is exact at every width). So those layers never get such a table: they get a 1-, 3- or 6-bit table (the cluster count rounded up to a supported width), and stay float32 above 64 clusters. The 128- and 256-cluster CoreML packages are therefore close to uncompressed; lower levels compress as expected. 1x1 and depthwise convs are unaffected.

Sizes are in MB (1 MB = 10^6 bytes), measured from the published files: the zip as stored on HF, and the unpacked model.mlpackage inside it.

² Added later (float32 of every backbone, and mobilenetv1_0.50 at 12 clusters): verified on the GPU unit on the full val set; CPU_ONLY has not been run for these yet.

¹ Rebuilt for the GPU fix above: the published file was verified on the GPU on the full val set; its CPU result was measured on the previous build of the same weights (palettization is lossless, so the CPU output is unchanged).

CoreML sizes and compression

Sizes of the published CoreML exports ("raw" = the unpacked model.mlpackage on disk, all files inside the zip; "zip" = the downloadable .zip; 1 MB = 10^6 bytes). "Compression ratio" = that backbone's float32 CoreML size divided by this row's size, computed separately for raw and zip. The float32 rows are the uncompressed reference every other row is measured against. These are measured file sizes, unlike the "est. size" column in the metrics tables below, which is a theoretical weight-only estimate.

CoreML: AP vs. measured size

This graph is based on the CoreML conversion, not on the PyTorch checkpoints: every point is one published CoreML model (checkpoints/<arch>/coreml/<arch>_<level>.zip, exported with inference/export_coreml.py, coremltools 9.0). The AP is measured on that converted model itself -- its own easy / medium / hard AP from the macOS validation above (Apple GPU, fixed 640x640 letterbox, full val set) -- and the x-axis is the measured size of the published .zip from the size table above, not an estimate. Easy, medium and hard are never averaged; all three panels share the same axes, both logarithmic. The ringed dot is the selected level and the diamond is the float32 baseline. Also in assets/: the log-x version, the same plots against the unpacked package size (coreml_ap_vs_size_raw_loglog_*), dark variants of each, and the underlying data as coreml_ap_vs_size.csv.

Accuracy vs. size

This graph is based on the PyTorch checkpoints (the training pipeline's evaluation and its estimated weight size, as in the tables below), not on any converted format. The three WIDER FACE metrics -- easy (7,211 faces), medium (13,319) and hard (31,958) -- each against the estimated weight size in MB, in their own panel; both axes logarithmic and all three panels on the same x and y axes. One line per backbone; each dot is a compression level (2-256 clusters); the ringed dot is the selected level and the diamond is the float32 baseline. Like the tables below, this is the variable-size AP, not the fixed-size verification AP above.

<!-- METRICS TABLE START -->

mobilenetv1

mobilenetv1_0.25

mobilenetv1_0.50

mobilenetv2

resnet18

resnet34

resnet50

<!-- METRICS TABLE END -->