Skip to content

README.md

Latest commit

 

History

History
171 lines (139 loc) · 8.86 KB

README.md

File metadata and controls

171 lines (139 loc) · 8.86 KB
Raw

yscv documentation

Pick your starting point.

Just landed here?

You want to... Read first
Run something right now (5 min) QUICKSTART.md
Walk through the framework end-to-end getting-started.md
Find recipes for a specific task cookbook.md
Try the worked examples ../examples/README.md
Something is broken troubleshooting.md

By topic

Getting started

  • QUICKSTART.md — three 5-minute paths: image processing, training, edge deployment. Pick one, copy code, you're running.
  • getting-started.md — full progressive tutorial through every layer of the framework. Start here for a proper walkthrough.
  • cookbook.md — 1400-line recipe collection. Self-contained code for every common task with copy-paste commands.

Pipeline framework (TOML-driven runtime)

  • pipeline-config.md — full TOML schema reference: [camera], [output], [encoder], [[tasks]], [realtime]. Validation order, accelerator-by-feature table.
  • edge-deployment.md — Rockchip / NPU deep dive: DMA-BUF zero-copy V4L2→NPU, on-chip SRAM, MPP zero-copy from hardware decoder, dynamic-shape matmul for LLMs, custom OpenCL ops with Rust callbacks.

Inference

  • onnx-inference.md — ONNX runtime: CPU (122 ops), Apple MPSGraph, wgpu (cross-platform GPU). Triple- buffered submit/wait API for sustained throughput.
  • onnx-cpu-kernels.md — CPU hot-path map for ONNX Conv/MatMul: fused kernels, asm vs intrinsics coverage, Orange Pi tracker numbers, and A/B env toggles.
  • microarch-dispatch.md — north-star vision (drop-in ORT-CPU replacement, one crate, runtime auto-detect) and the per-microarchitecture kernel dispatch architecture: the Cpu/Microarch identity layer, capability-first selection table, per-core kernel files, and the zero-regression phased roadmap.
  • mpsgraph-guide.md — standalone guide for the Apple Silicon MPSGraph path: when to use, full API reference, sync vs pipelined, multi-input models, fallback, troubleshooting. One-stop shop for yscv's fastest backend on macOS.
  • gpu-backend-guide.md — standalone guide for the wgpu cross-platform GPU path (Vulkan / Metal / DX12 / GL): platform selection, compiled f16 plans, multi-GPU, WGPU_BACKEND env var, troubleshooting. The one to read on Linux/Windows.
  • feature-flags.md — canonical reference for every Cargo feature flag across the workspace: what it does, setup per platform, combination recipes.
  • ../crates/yscv-pipeline/README.md — multi-accelerator dispatcher, recovery, hot-reload, watchdog.
  • ../crates/yscv-onnx/README.md — ONNX-specific layer documentation.
  • ../crates/yscv-kernels/README.md — CPU SIMD + GPU kernels, RKNN backend with full SDK 2.4.3a0 coverage.

Video

  • video-pipeline.md — H.264 / HEVC / AV1 software decode (faster than ffmpeg), hardware decode (VideoToolbox / VAAPI / NVDEC / MediaFoundation), MP4 / MKV container parsing, audio metadata.

Training

  • training-optimizers.md — 8 optimizers (SGD → LARS), Lookahead meta-optimizer, 11 LR schedulers, 17 loss functions, gradient clipping, the high-level Trainer API.
  • training-augmentation.md — data augmentation pipeline: 12+ transforms, MixUp/CutMix, sampling, reproducibility (deterministic via seed).
  • dataset-adapters.md — supported dataset formats: training (JSONL, CSV, ImageManifest, ImageFolder), evaluation (COCO, OpenImages, YOLO, VOC, KITTI, WIDER FACE, MOT Challenge).

Architecture & references

  • architecture.md — crate dependency layers, yscv-cpu host identity, SIMD dispatch model (AVX-512/AVX2/AVX/SSE/NEON + scalar fallback), threading strategy, memory patterns, source-file map.
  • ecosystem-capability-matrix.md — canonical map of every capability area, status, and gap relative to a Python CV/DL stack.
  • performance-benchmarks.md — measured CPU tracker + single-op tables vs onnxruntime / NumPy / PyTorch (x86 Zen 4 + Orange Pi A53), with methodology and reproduction commands; Apple-Silicon / Metal / video sections retained as provisional.
  • api-stability.md — versioning policy, per-crate stability tiers, release checklist, publish order.

Operations

  • troubleshooting.md — common build / runtime / performance errors with concrete fixes per platform.

Per-crate READMEs

Crate What it does
yscv Umbrella — re-exports prelude + per-crate APIs.
yscv-cpu Cached host CPU identity and runtime feature detection shared by dispatch.
yscv-tensor N-dim tensor with 115 ops, f32/f16/bf16, SIMD-aligned storage.
yscv-kernels CPU + GPU compute backends, 315 SIMD functions, RKNN bindings.
yscv-autograd Reverse-mode autodiff, 61 backward op variants.
yscv-optim Optimizers + LR schedulers + Lookahead.
yscv-model 39 layer types, Trainer, model zoo (17 architectures), LoRA, EMA.
yscv-imgproc 160 image-processing ops (blur, edges, morphology, features, color).
yscv-video H.264/HEVC/AV1 codecs, hardware decode, MP4/MKV, V4L2 camera, audio.
yscv-detect YOLOv8/v11 pipeline, NMS, heatmap decoding.
yscv-track DeepSORT, ByteTrack, Kalman filter, Hungarian assignment.
yscv-recognize Cosine matching, VP-Tree ANN indexing, enroll/match.
yscv-eval Classification / detection / tracking / regression / image-quality metrics.
yscv-onnx 122 op ONNX CPU runtime, INT4/INT8 quantization, LLM generation, MPSGraph GPU.
yscv-pipeline TOML-driven multi-accelerator dispatch, RT wiring, recovery.
yscv-cli Inference + evaluation CLI: camera diagnostics, dataset eval, pipeline runner.

By role

"I'm building a CV product, want a single binary"

  1. QUICKSTART §1 — get running in 3 minutes.
  2. cookbook.md §image processing — find the ops you need.
  3. yscv-imgproc README — the full op catalogue.

"I'm training a model"

  1. QUICKSTART §2 — first training loop.
  2. getting-started.md §step 4 — full Trainer walkthrough.
  3. training-optimizers.md + training-augmentation.md + dataset-adapters.md — when you need control.

"I'm deploying on a Rockchip / drone / FPV board"

  1. QUICKSTART §3 — minimal TOML + 5-line main.rs.
  2. edge-deployment.md — every NPU feature (DMA-BUF, SRAM, MPP, custom ops).
  3. pipeline-config.md — TOML schema reference.
  4. yscv-pipeline README — runtime entry point.
  5. troubleshooting.md — when librknnrt.so isn't found, when SCHED_FIFO needs CAP_SYS_NICE, etc.

"I'm evaluating yscv for production"

  1. README.md (top-level) — what is yscv, what's the pitch.
  2. performance-benchmarks.md — how fast on what hardware vs whom.
  3. ecosystem-capability-matrix.md — capability gaps vs Python stack.
  4. architecture.md — design philosophy + crate layering.
  5. api-stability.md — versioning + breaking-change policy.

"I want to contribute"

  1. architecture.md — understand the layers first.
  2. ecosystem-capability-matrix.md — find what's missing.
  3. api-stability.md — what's safe to change vs needs RFC.
  4. Open an issue or PR. We respond fast.