Kornia-rs

0.1.10 · active · verified Fri Apr 10

Kornia-rs is a low-level computer vision library primarily written in Rust, offering high-performance image I/O, processing, and 3D operations through Python bindings. It leverages Rust's memory safety and speed for demanding computer vision tasks, integrating efficiently into machine learning and data science workflows via zero-copy data transfer with frameworks like NumPy and PyTorch. The library is actively developed by the Kornia organization and is currently at version 0.1.10.

Warnings

breaking As a library in active development and in early versions (0.1.x), expect potential breaking changes between minor versions. API signatures, especially for core functionalities like `warp_affine` or tensor allocators, have undergone refactoring in past releases.
Fix: Always consult the latest GitHub README and release notes when upgrading, and adapt your code to new API signatures. Pin your minor version to ensure stability within a project (e.g., `kornia-rs==0.1.*`).
gotcha Certain features, such as optimized JPEG decoding (via `turbojpeg`) or video processing (via `gstreamer`), may require additional system-level dependencies (e.g., `nasm`, `libgstreamer1.0-dev`). These are not automatically installed with `pip install kornia-rs`.
Fix: Check the `kornia-rs` GitHub documentation for a full list of optional system dependencies relevant to the features you intend to use and install them manually if needed.
gotcha Kornia-rs is a Rust-first library with Python bindings. Only a subset of the full Rust API is exposed to Python. Not all functionalities available in the Rust crate are directly accessible from Python.
Fix: Refer to the `kornia` (PyTorch) documentation or `kornia-rs` specific documentation for the exact Python-exposed functions and objects. Avoid assuming direct parity with the Rust API.
gotcha The `kornia_rs.Tensor` objects use DLPack for zero-copy data transfer to NumPy and PyTorch tensors. While highly efficient, this means direct modifications to the underlying `kornia_rs.Tensor` after conversion might affect the derived NumPy/PyTorch tensors, and vice versa.
Fix: Be mindful of shared memory when performing operations on tensors converted via DLPack. If independent copies are needed, explicitly clone the tensor after conversion (e.g., `np_array = np.from_dlpack(image_tensor).copy()`).

Install

pip install kornia-rs Install via pip

Imports

kornia_rs
```
import kornia_rs as K
```
While direct imports are possible, aliasing 'kornia_rs' as 'K' is a common convention demonstrated in official examples, allowing for a consistent API access pattern.

Quickstart

This quickstart demonstrates how to read an image using `kornia-rs`, convert the resulting `kornia_rs.Tensor` to a NumPy array via DLPack for seamless integration with Python data science tools, perform a basic image processing operation like resizing, and then convert the result back to a NumPy array. This highlights the library's high-performance I/O and interoperability.

import kornia_rs as K
import numpy as np
import os

# For demonstration, create a dummy image file if it doesn't exist
# In a real scenario, replace 'dummy.jpeg' with your image path.
if not os.path.exists('dummy.jpeg'):
    try:
        from PIL import Image
        img = Image.new('RGB', (256, 256), color = 'red')
        img.save('dummy.jpeg')
        print("Created 'dummy.jpeg' for quickstart.")
    except ImportError:
        print("Pillow not installed. Skipping dummy image creation.")
        print("Please create a 'dummy.jpeg' file or adjust the quickstart path.")
        exit() # Or handle gracefully without exiting

# 1. Read an image into a kornia_rs.Tensor
# This uses the image-rs backend by default (or turbojpeg if enabled/available).
image_tensor = K.read_image_jpeg('dummy.jpeg')
print(f"Original image tensor shape: {image_tensor.shape}")

# 2. Convert the kornia_rs.Tensor to a NumPy array (zero-copy via DLPack)
np_image = np.from_dlpack(image_tensor)
print(f"NumPy array shape: {np_image.shape}, dtype: {np_image.dtype}")

# 3. Perform a basic image operation, e.g., resize
# The resize function expects a kornia_rs.Tensor and returns one.
resized_tensor = K.resize(image_tensor, (128, 128), interpolation="bilinear")
print(f"Resized image tensor shape: {resized_tensor.shape}")

# Convert resized tensor back to NumPy for further processing or visualization
np_resized_image = np.from_dlpack(resized_tensor)
print(f"Resized NumPy array shape: {np_resized_image.shape}, dtype: {np_resized_image.dtype}")

# Clean up dummy image if created
if os.path.exists('dummy.jpeg') and 'Created' in locals():
    os.remove('dummy.jpeg')
    print("Removed 'dummy.jpeg'.")

view raw JSON →