kornia-rs

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-icp = "0.1"
kornia-linalg = "0.1"
kornia-3d = "0.1"
kornia-apriltag = "0.1"
kornia-vlm = "0.1"
kornia-nn = "0.1"
kornia-pnp = "0.1"
kornia-lie = "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)

Encoding and Decoding

Encode or decode image streams using the turbojpeg backend:

import kornia_rs as K

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

# encode the image with jpeg
image_encoder = K.ImageEncoder()
image_encoder.set_quality(95)  # set the encoding quality

# get the encoded stream
img_encoded: list[int] = image_encoder.encode(img)

# decode back the image
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)

🧑‍💻 Development

Prerequisites

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

Setting Up Your Development Environment

• Install Rust using rustup:

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

• Install uv to manage Python dependencies:

  curl -LsSf https://astral.sh/uv/install.sh | sh
  

• Install just command runner for managing development tasks:

  cargo install just
  

• Clone the repository to your local directory:

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

Available Commands

You can check all available development commands by running just in the root directory of the project:

$ just
Available recipes:
    check-environment                 # Check if the required binaries for the project are installed
    clean                             # Clean up caches and build artifacts
    clippy                            # Run clippy with all features
    clippy-default                    # Run clippy with default features
    fmt                               # Run autoformatting and linting
    py-build py_version='3.9'         # Create virtual environment, and build kornia-py
    py-build-release py_version='3.9' # Create virtual environment, and build kornia-py for release
    py-install py_version='3.9'       # Create virtual environment, and install dev requirements
    py-test                           # Test the kornia-py code with pytest
    test name=''                      # Test the code or a specific test

🐳 Development Container

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

Using the Dev Container:

• Install the Remote - Containers extension in Visual Studio Code
• Open the project folder in VS Code
• Press F1 and select Remote-Containers: Reopen in Container
• 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:

just test

To run specific tests:

just test image

To run clippy linting:

just clippy

🐍 Python Development

Build Python wheels using maturin:

just py-build

Run Python tests:

just 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

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},
}