kornia-rs 0.1.15rc4

Low level implementations for computer vision in Rust

kornia-rs: low level computer vision library in Rust

English | 简体中文

The kornia crate is a low level library for Computer Vision written in Rust 🦀

Use the library to perform image I/O, visualization and other low level operations in your machine learning and data-science projects in a thread-safe and efficient way.

📚 Table of Contents

• Getting Started
• Features
• Installation
• Examples
• Python Usage
• Development
• Contributing
• Citation

Getting Started

Quick Example

The following example demonstrates how to read and display image information:

use kornia::image::Image;
use kornia::io::functional as F;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // read the image
    let image: Image<u8, 3> = F::read_image_any_rgb8("tests/data/dog.jpeg")?;

    println!("Hello, world! 🦀");
    println!("Loaded Image size: {:?}", image.size());
    println!("\nGoodbyte!");

    Ok(())
}

Hello, world! 🦀
Loaded Image size: ImageSize { width: 258, height: 195 }

Goodbyte!

Features

• 🦀 The library is primarily written in Rust.
• 🚀 Multi-threaded and efficient image I/O, image processing and advanced computer vision operators.
• 🔢 Efficient Tensor and Image API for deep learning and scientific computing.
• 🐍 Python bindings are created with PyO3/Maturin.
• 📦 We package with support for Linux [amd64/arm64], macOS and Windows.
• Supported Python versions are 3.7/3.8/3.9/3.10/3.11/3.12/3.13, including the free-threaded build.

Supported image formats

• Read images from AVIF, BMP, DDS, Farbeld, GIF, HDR, ICO, JPEG (libjpeg-turbo), OpenEXR, PNG, PNM, TGA, TIFF, WebP.

Image processing

• Convert images to grayscale, resize, crop, rotate, flip, pad, normalize, denormalize, and other image processing operations.

Video processing

• Capture video frames from a camera and video writers.

🛠️ Installation

🦀 Rust

Add the following to your Cargo.toml:

[dependencies]
kornia = "0.1"

Alternatively, you can use each sub-crate separately:

[dependencies]
kornia-tensor = "0.1"
kornia-tensor-ops = "0.1"
kornia-io = "0.1"
kornia-image = "0.1"
kornia-imgproc = "0.1"
kornia-3d = "0.1"
kornia-apriltag = "0.1"
kornia-vlm = "0.1"
kornia-bow = "0.1"
kornia-algebra = "0.1"

🐍 Python

pip install kornia-rs

A subset of the full rust API is exposed. See the kornia documentation for more detail about the API for python functions and objects exposed by the kornia-rs Python module.

The kornia-rs library is thread-safe for use under the free-threaded Python build.

System Dependencies (Optional)

Depending on the features you want to use, you might need to install the following dependencies in your system:

v4l (Video4Linux camera support)

sudo apt-get install clang

turbojpeg

sudo apt-get install nasm

gstreamer

sudo apt-get install libgstreamer1.0-dev libgstreamer-plugins-base1.0-dev

Note: Check the gstreamer installation guide for more details.

Examples: Image Processing

The following example shows how to read an image, convert it to grayscale and resize it. The image is then logged to a rerun recording stream for visualization.

For more examples and use cases, check out the examples directory, which includes:

• Image processing operations (resize, rotate, normalize, filters)
• Video capture and processing
• AprilTag detection
• Feature detection (FAST)
• Visual language models (VLM) integration
• And more...

use kornia::{image::{Image, ImageSize}, imgproc};
use kornia::io::functional as F;

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // read the image
    let image: Image<u8, 3> = F::read_image_any_rgb8("tests/data/dog.jpeg")?;
    let image_viz = image.clone();

    let image_f32: Image<f32, 3> = image.cast_and_scale::<f32>(1.0 / 255.0)?;

    // convert the image to grayscale
    let mut gray = Image::<f32, 1>::from_size_val(image_f32.size(), 0.0)?;
    imgproc::color::gray_from_rgb(&image_f32, &mut gray)?;

    // resize the image
    let new_size = ImageSize {
        width: 128,
        height: 128,
    };

    let mut gray_resized = Image::<f32, 1>::from_size_val(new_size, 0.0)?;
    imgproc::resize::resize_native(
        &gray, &mut gray_resized,
        imgproc::interpolation::InterpolationMode::Bilinear,
    )?;

    println!("gray_resize: {:?}", gray_resized.size());

    // create a Rerun recording stream
    let rec = rerun::RecordingStreamBuilder::new("Kornia App").spawn()?;

    rec.log(
        "image",
        &rerun::Image::from_elements(
            image_viz.as_slice(),
            image_viz.size().into(),
            rerun::ColorModel::RGB,
        ),
    )?;

    rec.log(
        "gray",
        &rerun::Image::from_elements(gray.as_slice(), gray.size().into(), rerun::ColorModel::L),
    )?;

    rec.log(
        "gray_resize",
        &rerun::Image::from_elements(
            gray_resized.as_slice(),
            gray_resized.size().into(),
            rerun::ColorModel::L,
        ),
    )?;

    Ok(())
}

Python Usage

Reading Images

Load an image, which is converted directly to a numpy array to ease the integration with other libraries.

import kornia_rs as K
import numpy as np
import torch

# load an image with using libjpeg-turbo
img: np.ndarray = K.read_image_jpeg("dog.jpeg")

# alternatively, load other formats
# img: np.ndarray = K.read_image_any("dog.png")

assert img.shape == (195, 258, 3)

# convert to dlpack to import to torch
img_t = torch.from_dlpack(img)
assert img_t.shape == (195, 258, 3)

Writing Images

Write an image to disk:

import kornia_rs as K
import numpy as np

# load an image with using libjpeg-turbo
img: np.ndarray = K.read_image_jpeg("dog.jpeg")

# write the image to disk
K.write_image_jpeg("dog_copy.jpeg", img)

Image — PIL-style class with uint8 + uint16 support

kornia_rs.image.Image mirrors PIL's fromarray / save / load / decode and natively holds uint16 for depth maps and scientific imagery (lossless via PNG-16):

import io
import numpy as np
from kornia_rs.image import Image

# Bit depth is auto-detected from the numpy dtype.
rgb   = np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)
depth = np.full((480, 640), 1500, dtype=np.uint16)            # mm

rgb_img   = Image.fromarray(rgb)
depth_img = Image.fromarray(depth)

# In-memory encode for transit (Zenoh / MCAP / gRPC).
png16_bytes = depth_img.encode("png")    # lossless on uint16

# Save to disk (format from extension), or to any file-like (PIL parity).
rgb_img.save("dog.png")
buf = io.BytesIO(); rgb_img.save(buf, format="jpeg")

# Decode auto-detects bit depth from the file header.
back = Image.decode(png16_bytes, mode="L")
assert back.dtype == np.uint16

Encoding and Decoding (legacy, jpeg-only)

The original ImageEncoder/ImageDecoder pair is still available for JPEG-only workflows that want the explicit turbojpeg backend object:

import kornia_rs as K

img = K.read_image_jpeg("dog.jpeg")

image_encoder = K.ImageEncoder()
image_encoder.set_quality(95)
img_encoded: list[int] = image_encoder.encode(img)

image_decoder = K.ImageDecoder()
decoded_img: np.ndarray = image_decoder.decode(bytes(img_encoded))

Image Resizing

Resize an image using the kornia-rs backend with SIMD acceleration:

import kornia_rs as K

# load image with kornia-rs
img = K.read_image_jpeg("dog.jpeg")

# resize the image
resized_img = K.resize(img, (128, 128), interpolation="bilinear")

assert resized_img.shape == (128, 128, 3)

GPU / CUDA

The kornia_rs.cuda module runs image ops on an NVIDIA GPU. The published wheels are GPU-capable but load CUDA lazily, so the same wheel runs on CPU when no GPU is present and activates CUDA when it is.

Runtime requirements for the GPU path: an NVIDIA driver (libcuda) and nvrtc (from the CUDA toolkit — kernels are JIT-compiled), matching your architecture (x86_64 / aarch64 / Jetson). Without them the GPU calls are unavailable; CPU ops keep working.

import numpy as np
import kornia_rs as K

# Guard: falls back to CPU when no CUDA runtime is available.
if K.cuda.is_available():
    rgb = np.ascontiguousarray(
        np.random.randint(0, 255, (480, 640, 3), dtype=np.uint8)
    )

    cu_img = K.cuda.upload(rgb)              # host -> GPU  (CudaImage)
    cu_gray = K.cuda.gray_from_rgb(cu_img)   # runs on the GPU
    gray = np.asarray(cu_gray.download())    # GPU -> host  (H, W, 1) uint8

    assert gray.shape == (480, 640, 1)

Available on the GPU: color conversions (gray_from_rgb, bgr_from_rgb, hsv_from_rgb, lab_from_rgb, ycbcr_from_rgb, rgb_from_bayer, rgba_from_rgb, …), apply_colormap, a fused CudaPreprocessor, and zero-copy DLPack import (K.cuda.from_dlpack) for handing tensors to/from PyTorch without a host copy.

🧑‍💻 Development

Prerequisites

Before you begin, ensure you have rust and python3 installed on your system.

Setting Up Your Development Environment

1. Install Rust using rustup:

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

2. Install pixi for package and environment management:

   curl -fsSL https://pixi.sh/install.sh | bash
   

3. Clone the repository to your local directory:

   git clone https://github.com/kornia/kornia-rs.git
   

4. Install dependencies using pixi:

   pixi install
   

Available Commands

You can check all available development commands via pixi task list:

pixi run rust-check        # Check Rust compilation (all targets)
pixi run rust-clippy       # Run clippy (all targets, warnings as errors)
pixi run rust-fmt          # Format Rust code
pixi run rust-fmt-check    # Check Rust formatting
pixi run rust-lint         # Run all Rust lints (fmt + clippy + check)
pixi run rust-test         # Run Rust tests
pixi run rust-test-release # Run Rust tests (release mode)
pixi run rust-clean        # Clean Rust build artifacts
pixi run py-build          # Build kornia-py for development
pixi run py-build-release  # Build kornia-py for release
pixi run py-test           # Run pytest
pixi run cpp-build         # Build C++ library (debug)
pixi run cpp-test          # Build and run C++ tests

🐳 Development Container

This project includes a development container configuration for a consistent development environment across different machines.

Using the Dev Container:

1. Install the Remote - Containers extension in Visual Studio Code
2. Open the project folder in VS Code
3. Press F1 and select Remote-Containers: Reopen in Container
4. VS Code will build and open the project in the containerized environment

The devcontainer includes all necessary dependencies and tools for building and testing kornia-rs.

🦀 Rust Development

Compile the project and run all tests:

pixi run rust-test

To run tests for a specific package:

pixi run rust-test-package <package-name>

To run clippy linting:

pixi run rust-clippy

🐍 Python Development

Build Python wheels using maturin:

pixi run py-build

Run Python tests:

pixi run py-test

💜 Contributing

We welcome contributions! Please read CONTRIBUTING.md for:

• Coding standards and style guidelines
• Development workflow
• How to run local checks before submitting PRs

AI Policy

Kornia-rs accepts AI-assisted code but strictly rejects AI-generated contributions where the submitter acts as a proxy. All contributors must be the Sole Responsible Author for every line of code. Please review our AI Policy before submitting pull requests. Key requirements include:

• Proof of Verification: PRs must include local test logs proving execution (e.g., pixi run rust-test or cargo test)
• Pre-Discussion: All PRs must be discussed in Discord or via a GitHub issue before implementation
• Library References: Implementations must be based on existing library references (Rust crates, OpenCV, etc.)
• Use Existing Utilities: Use existing kornia-rs utilities instead of reinventing the wheel
• Error Handling: Use Result<T, E> for error handling (avoid unwrap()/expect() in library code)
• Explain It: You must be able to explain any code you submit

Automated AI reviewers (e.g., @copilot) will check PRs against these policies. See AI_POLICY.md for complete details.

Community

This is a child project of Kornia.

• 💬 Join our community on Discord
• 💖 Support the project on OpenCollective
• 📖 Read the full documentation
• 🦀 Browse the Rust API docs

Citation

If you use kornia-rs in your research, please cite:

@misc{2505.12425,
Author = {Edgar Riba and Jian Shi and Aditya Kumar and Andrew Shen and Gary Bradski},
Title = {Kornia-rs: A Low-Level 3D Computer Vision Library In Rust},
Year = {2025},
Eprint = {arXiv:2505.12425},
}