How kornia/kornia-rs works
Project type and purpose
• This is an open-source, multi-crate Rust library for low-level computer vision (kornia-rs) with optional Python bindings (kornia-py).
• It provides primitives for image I/O, image/tensor operators, geometry (2D/3D), and integrates into ML/data-science workflows.
File structure
• Top-level “crates” directory contains dozens of sub-crates:
• Core data structures (“kornia-tensor”, “kornia-tensor-ops”)
• Image I/O (“kornia-io”)
• Image processing (“kornia-image”, “kornia-imgproc”)
• Geometric operators (“kornia-linalg”, “kornia-lie”, “kornia-pnp”, “kornia-april tag”, “kornia-icp”, “kornia-3d”)
• High-level models (“kornia-vlm”)
• Re-export crate (“kornia”) that ties everything together
• Python bindings in “kornia-py” leveraging PyO3/Maturin.
• “examples/” shows end-user applications (Rust binaries) using the crates.
• CI/CD under “.github/workflows” + Dockerfiles + “justfile” scripts.
• Devcontainer configuration for VS Code.
README for architecture clues
• Rust-centric library with optional Python layer.
• Build matrix: Rust crates → artifacts → Python wheels (maturin) → pip package.
• System dependencies: libjpeg-turbo, gstreamer, v4l (optional).
• Examples invoke either Rust binaries (cargo run) or Python API.
a. Main components
• Rust Workspace
– Sub-crate groups:
· Core: tensor, tensor-ops
· I/O: kornia-io
· Processing: kornia-image, kornia-imgproc
· Geometry/3D: linalg, lie, pnp, apriltag, icp, 3d, vlm
· Top-level re-export: kornia
• Python Layer
– kornia-py (built via maturin)
• Client Applications
– Rust examples (cargo bins)
– Python scripts/notebooks
• CI/CD & Tooling
– GitHub workflows (lint, test, release)
– Dockerfiles (devel containers)
– justfile (local task runner)
• External Services/Dependencies
– System libs: libjpeg-turbo, gstreamer, v4l
– Cargo/crates.io, PyPI
b. Relationships & data flows
1. Cargo workspace builds all sub-crates.
→ crates may depend on lower-level crates (e.g., imgproc → image → tensor-ops → tensor).
→ “kornia” crate re-exports APIs.
2. Python binding process
Cargo build + PyO3 → shared library (.so/.pyd)
maturin packages into Python wheel → publishes to PyPI
3. Examples
• Rust examples link against kornia workspace via Cargo.
• Python examples import kornia_rs from PyPI/locally built wheel.
4. CI/CD pipelines
• GitHub Actions orchestrate Rust tests, Python tests, packaging, and Docker image builds.
c. Architectural patterns & design principles
• Monorepo with Cargo workspace pattern for modular sub-crates.
• Clear separation of concerns: core data, IO, image processing, geometry.
• Layered architecture: low-level tensor ops → higher-level vision ops → bindings.
• Polyglot packaging: Rust library + Python wrapper.
• CI/CD as code: GitHub workflows + Docker + just tasks.
d. Key technologies/frameworks
• Rust/Cargo workspace
• PyO3/Maturin for Python bindings
• GitHub Actions for CI/CD
• Docker/Devcontainer for reproducible environments
• just (task runner)