{"id":49296329,"url":"https://github.com/facex-engine/facex","last_synced_at":"2026-05-01T09:00:43.922Z","repository":{"id":353778944,"uuid":"1220866899","full_name":"facex-engine/facex","owner":"facex-engine","description":"Face verification in the browser. 74 KB WebAssembly. No server, no cloud, no dependencies. Also runs native at 3ms on CPU.","archived":false,"fork":false,"pushed_at":"2026-04-29T23:52:09.000Z","size":7906,"stargazers_count":1,"open_issues_count":1,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-04-30T08:21:57.962Z","etag":null,"topics":["avx-512","avx2","biometrics","c99","computer-vision","cpu-inference","deep-learning","edge-ai","embedded-ai","face-embedding","face-recognition","face-verification","low-latency","onnx-runtime","production-ready","simd","zero-dependencies"],"latest_commit_sha":null,"homepage":"https://facex-engine.github.io/facex/","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/facex-engine.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-04-25T12:49:25.000Z","updated_at":"2026-04-30T00:14:34.000Z","dependencies_parsed_at":"2026-04-28T06:00:34.462Z","dependency_job_id":null,"html_url":"https://github.com/facex-engine/facex","commit_stats":null,"previous_names":["facex-engine/facex"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/facex-engine/facex","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facex-engine%2Ffacex","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facex-engine%2Ffacex/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facex-engine%2Ffacex/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facex-engine%2Ffacex/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/facex-engine","download_url":"https://codeload.github.com/facex-engine/facex/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/facex-engine%2Ffacex/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":32490815,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-04-30T13:12:12.517Z","status":"online","status_checked_at":"2026-05-01T02:00:05.856Z","response_time":64,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["avx-512","avx2","biometrics","c99","computer-vision","cpu-inference","deep-learning","edge-ai","embedded-ai","face-embedding","face-recognition","face-verification","low-latency","onnx-runtime","production-ready","simd","zero-dependencies"],"created_at":"2026-04-26T04:00:23.818Z","updated_at":"2026-05-01T09:00:43.873Z","avatar_url":"https://github.com/facex-engine.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003cimg src=\"docs/logo.jpg\" alt=\"FaceX\" width=\"480\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\u003cem\u003eFast face embedding library. 3 ms inference, 7 MB binary, zero dependencies.\u003c/em\u003e\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n\n[![Language: C99](https://img.shields.io/badge/language-C99-blue.svg)](https://en.wikipedia.org/wiki/C99)\n[![License: Apache 2.0](https://img.shields.io/badge/license-Apache_2.0-blue.svg)](LICENSE)\n[![Platform: x86-64](https://img.shields.io/badge/platform-x86__64-lightgrey.svg)](#limitations)\n[![AVX2 / AVX-512](https://img.shields.io/badge/SIMD-AVX2_%2F_AVX--512-blueviolet.svg)](#architecture)\n[![LFW](https://img.shields.io/badge/LFW-99.73%25-success.svg)](#benchmarks)\n[![Latency](https://img.shields.io/badge/latency-3.0_ms%2Fface-brightgreen.svg)](#benchmarks)\n[![Binary](https://img.shields.io/badge/binary-148_KB-informational.svg)](#footprint)\n[![Deps](https://img.shields.io/badge/dependencies-zero-green.svg)](#architecture)\n\n\u003c/p\u003e\n\n**A 148 KB face embedding library that runs EdgeFace-XS at 3.0 ms/face\non a consumer i5 -- faster than ONNX Runtime on the same model and CPU.**\n\nNo Python. No GPU. No ONNX Runtime. One header, one static library.\n\n```c\n#include \"facex.h\"\n\nFaceX* fx = facex_init(\"edgeface_xs_fp32.bin\", NULL);\nfloat emb[512];\nfacex_embed(fx, rgb_112x112, emb);\n```\n\n---\n\n## Why this exists\n\nFace embedding is the core of every face recognition system -- turning\na face photo into a 512-dimensional vector. The standard way to run it\non CPU is ONNX Runtime (28 MB DLL + Python). That's fine for servers,\nbut too heavy for edge devices, kiosks, embedded systems, and anyone\nwho values simplicity.\n\nFaceX is a single C99 file with handwritten AVX2/AVX-512 SIMD kernels\nthat **beats ONNX Runtime by 23%** with zero dependencies. Six months\nof optimization: per-op profiling, custom GEMM microkernels, INT8\nquantization, cache-tuned memory layout, thread pool -- every\nmillisecond fought for.\n\n### Target users\n\n- **Edge AI / embedded** -- kiosks, turnstiles, access control where\n  you have a $40 CPU and no GPU.\n- **Server-side at scale** -- 3 ms/face means 300+ faces/sec on a\n  single core.\n- **Privacy-first deployments** -- runs fully offline, no cloud,\n  no telemetry.\n- **Developers** -- `#include \"facex.h\"`, link, done. No package\n  managers, no version conflicts.\n\n---\n\n## Benchmarks\n\nMeasured on Intel i5-11500 (6 cores, AVX-512 + VNNI):\n\n### Speed\n\n![Speed comparison](docs/speed_comparison.svg)\n\n| Engine | Median | Min | vs FaceX |\n|--------|-------:|----:|:--------:|\n| **FaceX** | **3.0 ms** | **2.87 ms** | -- |\n| ONNX Runtime 1.23 | 3.9 ms | 3.18 ms | 1.30x slower |\n| InsightFace (R34) | 17 ms | -- | 5.7x slower |\n| FaceNet (PyTorch) | 30 ms | -- | 10x slower |\n| dlib | 50+ ms | -- | 17x slower |\n\n### Accuracy\n\n| Benchmark | Score |\n|-----------|------:|\n| **LFW verification** | **99.73%** |\n| Model parameters | 1.77M |\n| Embedding dim | 512 |\n\n### Footprint\n\n![Footprint comparison](docs/footprint.svg)\n\n| Metric | FaceX | ONNX Runtime |\n|--------|------:|-------------:|\n| Library size | **148 KB** | 28 MB |\n| Total deploy | **7 MB** | 157 MB |\n| Dependencies | **none** | Python + onnxruntime |\n| Cold start | **~100 ms** | ~350 ms |\n\n---\n\n## Quick start\n\n### C\n\n```c\n#include \"facex.h\"\n\nint main() {\n    // Load engine (one-time, ~100ms)\n    FaceX* fx = facex_init(\"edgeface_xs_fp32.bin\", NULL);\n\n    // Compute embedding (3ms per call)\n    float face[112 * 112 * 3];  // RGB, HWC, [-1, 1]\n    float embedding[512];\n    facex_embed(fx, face, embedding);\n\n    // Compare two faces\n    float sim = facex_similarity(emb_a, emb_b);\n    // sim \u003e 0.3 → same person\n\n    facex_free(fx);\n}\n```\n\n```bash\ngcc -O3 -march=native -Iinclude -o myapp myapp.c -L. -lfacex -lm -lpthread\n```\n\n### Go\n\n```go\nimport \"github.com/facex-engine/facex/go/facex\"\n\nff, _ := facex.New(facex.Config{\n    Exe:     \"./facex-cli\",\n    Weights: \"./edgeface_xs_fp32.bin\",\n})\ndefer ff.Close()\n\nembedding, _ := ff.Embed(rgbImage)\nsim := facex.CosSim(embA, embB)\n```\n\n### CLI (any language via stdin/stdout)\n\n```bash\n# Pipe mode: reads 112x112x3 float32 HWC, writes 512 float32\n./facex-cli weights.bin --server \u003c faces.raw \u003e embeddings.raw\n```\n\n### Browser (WebAssembly)\n\n```html\n\u003cscript src=\"facex.js\"\u003e\u003c/script\u003e\n\u003cscript\u003e\nconst Module = await FaceXModule();\nconst fx = Module.cwrap('facex_init', 'number', ['string', 'string'])('/weights.bin', null);\n// 7ms per face, runs entirely in browser, no server needed\n\u003c/script\u003e\n```\n\n48 KB WASM module. Face recognition with zero server infrastructure.\nSee [`wasm/`](wasm/) for the full browser demo with live camera.\n\n---\n\n## Build\n\n```bash\nmake            # builds libfacex.a + facex-cli\nmake example    # builds and runs example\nmake encrypt    # builds weight encryption tool\n```\n\nRequirements: GCC with AVX2 support. Nothing else.\n\n### Cross-compile for Linux (from WSL)\n\n```bash\ngcc -O3 -march=x86-64-v3 -mavx2 -mfma -static \\\n    -DFACEX_LIB -o libfacex.a src/*.c -lm -lpthread\n```\n\n---\n\n## API\n\n```c\n// Initialize engine. Returns NULL on error.\n// license_key: NULL for plain weights, or key string for AES-256 encrypted.\nFaceX* facex_init(const char* weights_path, const char* license_key);\n\n// Compute 512-dim face embedding from 112x112 RGB image.\n// rgb_hwc: float32 array [112][112][3], values in [-1, 1].\n// embedding: output buffer, 512 floats (L2-normalized).\nint facex_embed(FaceX* fx, const float* rgb_hwc, float embedding[512]);\n\n// Cosine similarity between two embeddings. Range [-1, 1].\nfloat facex_similarity(const float emb1[512], const float emb2[512]);\n\n// Free engine resources.\nvoid facex_free(FaceX* fx);\n\n// Version string.\nconst char* facex_version(void);\n```\n\n---\n\n## Architecture\n\n```\nInput: 112x112 RGB float32\n    ↓\n  Stem: Conv 3→32, stride 4\n    ↓\n  Stage 0: 3× ConvNeXt blocks (C=32)\n    ↓\n  Stage 1: 2× ConvNeXt + XCA attention (C=64)\n    ↓\n  Stage 2: 8× ConvNeXt + XCA attention (C=100)\n    ↓\n  Stage 3: 2× ConvNeXt + XCA attention (C=192)\n    ↓\n  Global Average Pool → LayerNorm → FC → L2 Norm\n    ↓\nOutput: 512-dim embedding\n```\n\n**Engine internals:**\n\n- Pure C99 + SIMD intrinsics (AVX2, FMA, AVX-512, VNNI)\n- INT8 quantized GEMM with `vpmaddubsw` (AVX2) / `vpdpbusd` (VNNI)\n- FP32 packed column-panel MatMul (NR=8 AVX2, NR=16 AVX-512)\n- Custom thread pool with work-stealing (WaitOnAddress / futex)\n- Exact GELU via polynomial `erf` approximation (A\u0026S 7.1.26)\n- Pre-packed weights at load time for cache-optimal access\n- Optional AES-256-CTR weight encryption with hardware binding\n\n---\n\n## Weight encryption\n\nFor commercial deployment with IP protection:\n\n```bash\n# Encrypt weights (binds to target machine hardware)\n./facex-encrypt encrypt weights.bin weights.enc \"LICENSE-KEY\"\n\n# Load encrypted weights\nFaceX* fx = facex_init(\"weights.enc\", \"LICENSE-KEY\");\n```\n\nWrong key or different machine → load fails. Original weights never\ntouch disk in plaintext on the target machine.\n\n---\n\n## Integration paths\n\n| Language | Method | Latency |\n|----------|--------|:-------:|\n| **C / C++** | `libfacex.a` + `facex.h` | 3 ms (native) |\n| **Browser** | `facex.wasm` (48 KB) | 7 ms (WASM SIMD) |\n| **Go** | `go/facex` subprocess | ~4 ms |\n| **Python** | subprocess / ctypes | ~4 ms |\n| **Any** | `facex-cli --server` stdin/stdout | ~4 ms |\n\n---\n\n## Limitations\n\n- **x86-64 only.** AVX2 required, AVX-512 optional. ARM NEON port\n  planned for Q3 2026.\n- **Embedding only.** Face detection and alignment are separate steps.\n- **Single model.** EdgeFace-XS (1.77M params). Other models need\n  weight conversion.\n\n---\n\n## Model\n\nUses [EdgeFace-XS](https://arxiv.org/abs/2307.01838) by George et al.:\n\n- 1.77M parameters (smallest in its accuracy class)\n- 99.73% LFW, competitive with models 100x larger\n- Originally CC BY-NC-SA 4.0 license\n\n---\n\n## Repo layout\n\n```\ninclude/\n  facex.h               — public API (5 functions)\n  weight_crypto.h       — encryption API\nsrc/\n  facex.c               — API implementation\n  edgeface_engine.c     — forward pass (all stages + ops)\n  transformer_ops.c     — SIMD kernels (LN, GELU, MatMul, Conv)\n  gemm_int8_4x8c8.c    — INT8 GEMM microkernel (AVX2 + VNNI)\n  threadpool.c/h        — lock-free thread pool\n  weight_crypto.c       — AES-256-CTR encryption\ngo/facex/               — Go binding (subprocess protocol)\nexamples/\n  example.c             — minimal usage example\ndocs/                   — SVG benchmarks, logo\n```\n\n---\n\n## FAQ\n\n**Q: Is it really faster than ONNX Runtime?**\nA: Yes. Measured on the same CPU, same model, same input. FaceX median\n3.0 ms vs ONNX Runtime median 3.9 ms. The gap comes from handwritten\nSIMD kernels that avoid framework overhead.\n\n**Q: What accuracy vs ArcFace-R100?**\nA: EdgeFace-XS gets 99.73% LFW vs ArcFace-R100's 99.80%. The 0.07%\ngap buys you 10x speed and 60x smaller model.\n\n**Q: Can I use this commercially?**\nA: The engine code is Apache 2.0 -- fully commercial. The bundled model\nweights are CC BY-NC-SA 4.0 (non-commercial). For commercial use, train\nyour own weights or contact for licensing.\n\n**Q: Does it do face detection?**\nA: No. FaceX is the embedding step only. Pair it with any face detector\n(RetinaFace, SCRFD, YuNet, etc.) for a complete pipeline.\n\n---\n\n## Citation\n\n```bibtex\n@software{facex2026,\n  author  = {Atinov, Baurzhan},\n  title   = {FaceX: Fast CPU Face Embedding Library},\n  year    = {2026},\n  url     = {https://github.com/facex-engine/facex}\n}\n```\n\n---\n\n## License\n\nCode: [Apache License 2.0](LICENSE) -- free for commercial use.\nModel weights: [CC BY-NC-SA 4.0](https://creativecommons.org/licenses/by-nc-sa/4.0/)\n(follows upstream EdgeFace license). Train your own weights for\nunrestricted commercial use.\n\nFor commercial licensing: [bauratynov@gmail.com](mailto:bauratynov@gmail.com)\n\n---\n\n\u003cp align=\"center\"\u003e\n  Created by \u003cstrong\u003eBaurzhan Atinov\u003c/strong\u003e (Kazakhstan)\u003cbr\u003e\n  \u003ca href=\"https://github.com/bauratynov\"\u003eGitHub\u003c/a\u003e\n\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacex-engine%2Ffacex","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffacex-engine%2Ffacex","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffacex-engine%2Ffacex/lists"}