Important: Current state of framework is WIP. It's ready to use for small inputs and special models. Also crates like tensors/kernels etc are self-sufficient. If you found any issues, please report them. You can connect with me via Telegram on my GitHub page or open an issue on GitHub. Stable version will be released soon. Milestone is 0.2.0.

yscv

A complete computer vision and deep learning framework in pure Rust. One cargo add yscv gives you image processing (160 ops, faster than OpenCV), neural network training (39 layer types, 8 optimizers), ONNX inference (122 operators, INT4/INT8 quantization), LLM generation (KV-cache, RoPE, GQA), real-time detection + tracking + recognition, H.264/HEVC/AV1 video decoding, hardware decode (VideoToolbox/VAAPI/NVDEC/MediaFoundation), and GPU compute via Vulkan/Metal/DX12 — all in a single statically-linked binary with zero Python or C++ dependencies.

Project focus. YSCV is built for CPU inference on edge devices — Raspberry Pi, Rockchip / Allwinner SBCs, drone boards, factory PCs, anything ARM Cortex-A or low-power x86. The north star is a drop-in replacement for ONNX Runtime's CPU execution provider: load an ONNX model, call run, and a single crate auto-detects the best path for the host — no execution-provider wiring, no backend selection, no build-time target pinning. Hot paths are hand-tuned SIMD (NEON / AVX / SSE / scalar) with rayon multi-thread fork-join, selected at runtime by detected ISA, and — increasingly — by detected microarchitecture (see docs/microarch-dispatch.md for the vision and the dispatch roadmap). On a public Siamese tracker we are within ~7% of ORT-CPU single-thread on x86 and faster than ORT on ARM SBCs and Apple M1; the CPU benchmarks (x86 / ARM / Apple M1) and the M1 GPU path (MPSGraph vs CoreML) are freshly measured on current hardware (the YOLO / video Metal sections are still pending re-measurement) — see docs/performance-benchmarks.md. Other backends — wgpu cross-platform GPU, Apple MPSGraph, Rockchip RKNN NPU, optional BLAS — exist as opt-in features and keep getting wider, but they're not the headline target. PRs are welcome; see CONTRIBUTING.md.

Agent-friendly documentation. YSCV is structured so that an AI coding agent can wire it into a downstream project end-to-end without prior context: every crate has a focused README.md describing its surface, docs/cookbook.md has recipes per task, docs/feature-flags.md is exhaustive on Cargo features and runtime env knobs, AGENTS.md has the workflow + style rules verbatim, and per-op profile labels (YSCV_RUNNER_PROFILE=path dumps fused-path JSON) make hot-path issues self-diagnosing. The benefit is downstream: agents can build working code on top of yscv quickly, not the other way around. Responsibility for any PR — including patches drafted by an agent — rests with the human author submitting it.

First time here? → QUICKSTART (5 minutes to a running program) · Tutorial (full walkthrough) · Cookbook (recipes by task) · Feature flags (what to enable for your target) · Edge / Rockchip (NPU deployment) · Examples (worked code) · Troubleshooting (when things break) · Docs hub (everything else)

We built this because deploying ML in production shouldn't require Docker containers with PyTorch, CUDA drivers, and a prayer. YSCV compiles to one binary that runs on a Raspberry Pi, a cloud VM, or a factory floor computer. Every hot path has hand-tuned SIMD for ARM and x86 — 315 #[target_feature]-gated functions selected by runtime CPU detection, so one binary picks the best path for the host it lands on.

Quick Start

[dependencies]
yscv = "0.1.10"

Load an image, process it, save the result — three lines:

```rust,ignore use yscv::prelude::*;

let img = imread("photo.jpg")?; let gray = rgb_to_grayscale(&img)?; imwrite("gray.png", &gray)?;

## What can you build with this?

**The short answer: anything you'd normally need Python + OpenCV + PyTorch for.**

YSCV covers the full pipeline — from reading pixels off a camera to training a neural network to deploying an optimized model. Here are some real examples:

**Video surveillance and security.** Hook up a camera, detect people, track them across frames, recognize faces. The tracking and face-matching stages cost tens of microseconds per frame on a single CPU core; the detector/tracker model inference is the real budget (a public Siamese tracker runs ~8.6 ms / 116 FPS single-thread on a Zen 4 core — see [benchmarks](docs/performance-benchmarks.md)). No GPU needed — deploy on any ARM or x86 device as a static binary.

**Factory quality control.** Train a defect detection model on your laptop, export to ONNX, quantize to INT8, deploy on cheap edge hardware on the production line. The whole thing runs without internet, without Python, without Docker.

**Retail and traffic analytics.** Count people, track movement paths, measure dwell time. One machine can handle dozens of camera streams because the processing is that fast.

**Medical imaging.** Process X-rays and DICOM images at scale: resize, normalize, detect edges, extract features. Memory-safe by construction — no segfaults on malformed input, ever.

**Robotics and drones.** Cross-compile to ARM, get a 5MB binary with feature detection (ORB, SIFT), optical flow, stereo matching, and homography estimation. No Python runtime on your drone.

**Training on the edge.** Fine-tune a pretrained ResNet or ViT directly on device with Adam optimizer, learning rate scheduling, and gradient clipping. You don't always need a GPU cluster.

## Training a model

Build a CNN, train it, done:

```rust,ignore
use yscv::prelude::*;

let mut graph = Graph::new();
let mut model = SequentialModel::new(&graph);
model.add_conv2d_zero(3, 16, 3, 3, 1, 1, true)?;
model.add_relu();
model.add_flatten();
model.add_linear_zero(&mut graph, 16 * 30 * 30, 10)?;

let config = TrainerConfig {
    optimizer: OptimizerKind::Adam { lr: 0.001 },
    loss: LossKind::CrossEntropy,
    epochs: 50,
    batch_size: 32,
    validation_split: Some(0.2),
};

let result = Trainer::new(config).fit(&mut model, &mut graph, &inputs, &targets)?;
println!("Final loss: {:.4}", result.final_loss);

17 pretrained architectures available out of the box — ResNet, VGG, MobileNet, EfficientNet, ViT, DeiT. Weights download automatically:

```rust,ignore let hub = ModelHub::new(); // caches in ~/.yscv/models/ let weights = hub.load_weights("resnet50")?;

## Object detection

YOLOv8 detection with tracking and recognition:

```rust,ignore
use yscv::detect::{detect_yolov8_from_rgb, yolov8_coco_config, non_max_suppression};

let img = imread("scene.jpg")?;
let detections = detect_yolov8_from_rgb(&img, &model, &yolov8_coco_config())?;
let filtered = non_max_suppression(&detections, 0.5);

The detect → track → recognize pipeline's tracking and matching stages cost tens of microseconds per frame on a single CPU core (the model inference is the real budget). DeepSORT and ByteTrack are built in. VP-tree ANN for recognition.

Performance

YSCV is profiled and tuned on real edge hardware — the hot paths (Conv, MatMul, depthwise, pointwise, the fused streaming kernels) are hand-written SIMD with runtime dispatch, benchmarked per thread count against ONNX Runtime / XNNPACK on the target board, and against NumPy / PyTorch / OpenCV / ffmpeg for the standalone ops. The kernel work is mapped in docs/onnx-cpu-kernels.md (per-op hot-path map, asm-vs-intrinsics coverage, A/B env toggles); the direction for broadening per-hardware performance is in docs/microarch-dispatch.md.

Benchmarks (current CPU suite). The CPU sections of docs/performance-benchmarks.md are freshly measured on fixed hardware with pinned competitor versions and a regenerable script. On a public Siamese tracker, AMD Ryzen 5 7500F (Zen 4): 8.63 ms / 1T (116 FPS), 2.52 ms / 6T (396 FPS) — roughly 7% behind ONNX Runtime 1.24.4 single-thread, with ORT scaling better across cores (the gap widens to ~1.45× at 6T). On the Orange Pi Zero 3 (Cortex-A53) — the actual deployment target — the picture inverts: yscv is 1.5–1.6× faster than ORT on the same tracker (321 ms vs 496 ms / 1T). On the Apple M1, yscv is 1.9× / 4.3× faster than ORT-CPU at 1 / 4 threads (15.4 / 5.46 ms), and its MPSGraph GPU path runs the tracker at 1.26 ms sync (792 FPS, 1.3× over ORT CoreML) up to 2688 FPS pipelined. On single ops yscv is at parity with NumPy/PyTorch on memory-bound elementwise and faster on transcendentals and activations; it beats ORT-CPU across the board (on the A53, up to ~11× on activations like sigmoid/gelu). See docs/performance-benchmarks.md for the tables, methodology, and exact reproduction commands. The older YOLO / Metal / video numbers in that doc were measured on different hardware and dates and are marked pending re-measurement — treat those as provisional.

1,861 default tests / 1,897 with all features, across 19 crates.

What's inside

The framework is split into 19 crates, each doing one thing well:

Building

cargo build --workspace --release
cargo test --workspace --release      # 1,861 tests (default)
cargo run --example train_cnn         # train a CNN on synthetic data
cargo run --example train_linear      # linear regression
cargo run --example image_processing  # image pipeline demo
cargo run --example yolo_detect -- model.onnx photo.jpg  # YOLOv8/v11 detection
cargo run --example yolo_finetune     # fine-tune a detection head

GPU / Metal (Apple Silicon)

# wgpu backend (Vulkan / Metal / DX12 — cross-platform)
cargo run --release --example bench_yolo --features gpu

# Metal-native backend (macOS only)
cargo run --release --example bench_mpsgraph --features metal-backend  # MPSGraph + per-op comparison
cargo run --release --example bench_metal_yolo --features metal-backend
cargo run --release --example bench_mps_gemm  --features metal-backend

# Both features can be combined
cargo test --workspace --features metal-backend
cargo clippy --workspace --features metal-backend

The gpu feature uses wgpu and works on any platform with Vulkan, Metal, or DX12. The metal-backend feature talks to Metal directly via metal-rs and provides two backends: MPSGraph (whole-model graph compilation, the fastest of yscv's own backends on Apple Silicon — ~4.8 ms YOLOv8n (measured on Apple M1, pending re-measurement); also exposes a triple-buffered submit_mpsgraph_plan / wait_mpsgraph_plan pipelined API that overlaps CPU marshaling with GPU compute for higher throughput on sustained inference, multi-input models supported) and Metal per-op (individual op dispatch with Winograd + MPS GEMM, fallback for unsupported models). On macOS, metal-backend is what you want.

System dependencies

YSCV builds with zero requir