# kornia/kornia-rs architecture

> Architecture diagram of the GitHub repository kornia/kornia-rs, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-28). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/kornia/kornia-rs
- Repository: https://github.com/kornia/kornia-rs

## Overview

##### 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)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Rust Workspace
    subgraph "Rust Workspace"
        direction TB
        subgraph "Core Data Structures"
            direction TB
            Tensor["kornia-tensor"]:::rust
            TensorOps["kornia-tensor-ops"]:::rust
        end
        subgraph "Image I/O & Processing"
            direction TB
            IO["kornia-io"]:::rust
            ImgBasic["kornia-image"]:::rust
            ImgProc["kornia-imgproc"]:::rust
        end
        subgraph "Geometry / 3D"
            direction TB
            Linalg["kornia-linalg"]:::rust
            Lie["kornia-lie"]:::rust
            PnP["kornia-pnp"]:::rust
            AprilTag["kornia-apriltag"]:::rust
            ICP["kornia-icp"]:::rust
            ThreeD["kornia-3d"]:::rust
            VLM["kornia-vlm"]:::rust
        end
        Kornia["kornia (re-export)"]:::rust
    end

    %% Python Layer
    PyBinding["kornia-py"]:::python

    %% Client Applications
    subgraph "Client Applications"
        direction TB
        RustExamples["Rust Examples"]:::client
        PythonClients["Python Scripts/Notebooks"]:::client
    end

    %% CI/CD & Tooling
    subgraph "CI/CD & Tooling"
        direction TB
        Workflows["GitHub Workflows"]:::cicd
        Docker["Dockerfiles"]:::cicd
        Just["justfile"]:::cicd
        DevContainer[".devcontainer"]:::cicd
    end

    %% External Dependencies
    subgraph "External Dependencies"
        direction TB
        LibJPEG["libjpeg-turbo"]:::external
        GStreamer["gstreamer"]:::external
        V4L["v4l"]:::external
        CargoIO["crates.io"]:::external
        PyPI["PyPI"]:::external
    end

    %% Relationships
    Tensor --> TensorOps
    TensorOps --> ImgBasic
    ImgBasic --> ImgProc
    TensorOps --> Linalg
    TensorOps --> Lie
    TensorOps --> PnP
    TensorOps --> AprilTag
    TensorOps --> ICP
    TensorOps --> ThreeD
    Linalg --> VLM
    Lie --> VLM
    PnP --> VLM
    AprilTag --> VLM
    ICP --> VLM
    ThreeD --> VLM
    Tensor --> Kornia
    TensorOps --> Kornia
    IO --> Kornia
    ImgBasic --> Kornia
    ImgProc --> Kornia
    Linalg --> Kornia
    Lie --> Kornia
    PnP --> Kornia
    AprilTag --> Kornia
    ICP --> Kornia
    ThreeD --> Kornia
    VLM --> Kornia

    Kornia --> PyBinding
    PyBinding --> PyPI
    CargoIO --> Kornia
    CargoIO --> Tensor
    CargoIO --> VLM

    RustExamples --> Kornia
    PythonClients --> PyBinding

    Workflows --> Tensor
    Workflows --> PyBinding
    Workflows --> RustExamples
    Workflows --> PythonClients
    Docker --> Workflows
    Just --> Workflows
    DevContainer --> Workflows

    IO --> LibJPEG
    IO --> GStreamer
    IO --> V4L

    %% Click Events
    click Tensor "https://github.com/kornia/kornia-rs/blob/main/crates/kornia-tensor/src/lib.rs"
    click TensorOps "https://github.com/kornia/kornia-rs/blob/main/crates/kornia-tensor-ops/src/lib.rs"
    click IO "https://github.com/kornia/kornia-rs/blob/main/crates/kornia-io/src/lib.rs"
    click ImgBasic "https://github.com/kornia/kornia-rs/blob/main/crates/kornia-image/src/lib.rs"
    click ImgProc "https://github.com/kornia/kornia-rs/blob/main/crates/kornia-imgproc/src/lib.rs"
    click Linalg "https://github.com/kornia/kornia-rs/blob/main/crates/kornia-linalg/src/lib.rs"
    click Lie "https://github.com/kornia/kornia-rs/blob/main/crates/kornia-lie/src/lib.rs"
    click PnP "https://github.com/kornia/kornia-rs/blob/main/crates/kornia-pnp/src/lib.rs"
    click AprilTag "https://github.com/kornia/kornia-rs/blob/main/crates/kornia-apriltag/src/lib.rs"
    click ICP "https://github.com/kornia/kornia-rs/blob/main/crates/kornia-icp/src/lib.rs"
    click ThreeD "https://github.com/kornia/kornia-rs/blob/main/crates/kornia-3d/src/lib.rs"
    click VLM "https://github.com/kornia/kornia-rs/blob/main/crates/kornia-vlm/src/lib.rs"
    click Kornia "https://github.com/kornia/kornia-rs/blob/main/crates/kornia/src/lib.rs"
    click PyBinding "https://github.com/kornia/kornia-rs/blob/main/kornia-py/src/lib.rs"
    click RustExamples "https://github.com/kornia/kornia-rs/tree/main/examples/"
    click Workflows "https://github.com/kornia/kornia-rs/tree/main/.github/workflows/"
    click Docker "https://github.com/kornia/kornia-rs/blob/main/devel-*.Dockerfile"
    click Just "https://github.com/kornia/kornia-rs/tree/main/justfile"
    click DevContainer "https://github.com/kornia/kornia-rs/blob/main/.devcontainer/devcontainer.json"

    %% Styles
    classDef rust fill:#D0E6FF,stroke:#0366D6,stroke-width:1px
    classDef python fill:#DFFFD0,stroke:#228B22,stroke-width:1px
    classDef client fill:#E0F7FF,stroke:#17A2B8,stroke-width:1px
    classDef cicd fill:#F0F0F0,stroke:#888888,stroke-width:1px
    classDef external fill:#FFE6CC,stroke:#CC6600,stroke-width:1px
```
