Metadata-Version: 2.4
Name: kornia_rs
Version: 0.1.14
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: GPU
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Free Threading :: 3 - Stable
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Classifier: Programming Language :: Rust
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Dist: pytest ; extra == 'dev'
Requires-Dist: pytest-run-parallel ; extra == 'dev'
Requires-Dist: numpy ; extra == 'dev'
Requires-Dist: torch ; extra == 'dev'
Provides-Extra: dev
License-File: LICENSE
Summary: Low level implementations for computer vision in Rust
Keywords: augmentation,camera,computer vision,deep-learning,image-processing,machine-learning,opencv-alternative,pytorch,rust,tensor,video-processing
Home-Page: http://kornia.org
Author-email: Edgar Riba <edgar@kornia.org>
Maintainer-email: Edgar Riba <edgar@kornia.org>
Requires-Python: >=3.8
Description-Content-Type: text/markdown; charset=UTF-8; variant=GFM
Project-URL: documentation, https://kornia.readthedocs.io
Project-URL: homepage, http://www.kornia.org
Project-URL: repository, https://github.com/kornia/kornia-rs

# kornia-rs: low level computer vision library in Rust

English | [简体中文](README.zh-CN.md)

![Crates.io Version](https://img.shields.io/crates/v/kornia)
[![PyPI version](https://badge.fury.io/py/kornia-rs.svg)](https://badge.fury.io/py/kornia-rs)
[![PyPI Downloads](https://img.shields.io/pypi/dm/kornia-rs?label=PyPI%20downloads&logo=python&color=blue)](https://pypi.org/project/kornia-rs/)
[![Crates.io Downloads](https://img.shields.io/crates/d/kornia?label=Crate%20downloads&logo=rust&color=orange)](https://crates.io/crates/kornia)
[![Documentation](https://img.shields.io/badge/docs.rs-kornia-orange)](https://docs.rs/kornia)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](LICENSE)
[![Discord](https://img.shields.io/badge/Discord-5865F2?logo=discord&logoColor=white)](https://discord.gg/HfnywwpBnD)

The `kornia` crate is a low level library for Computer Vision written in [Rust](https://www.rust-lang.org/) 🦀

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](#getting-started)
- [Features](#features)
- [Installation](#️-installation)
- [Examples](#examples-image-processing)
- [Python Usage](#python-usage)
- [Development](#-development)
- [Contributing](#-contributing)
- [Citation](#citation)

## Getting Started

### Quick Example

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

```rust
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(())
}
```

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

Goodbyte!
```

## Features

- 🦀 The library is primarily written in [Rust](https://www.rust-lang.org/).
- 🚀 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](https://github.com/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`:

```toml
[dependencies]
kornia = "0.1"
```

Alternatively, you can use each sub-crate separately:

```toml
[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

```bash
pip install kornia-rs
```

A subset of the full rust API is exposed. See the [kornia documentation](https://kornia.readthedocs.io/en/stable/) 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)

```bash
sudo apt-get install clang
```

#### turbojpeg

```bash
sudo apt-get install nasm
```

#### gstreamer

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

**Note:** Check the [gstreamer installation guide](https://docs.rs/gstreamer/latest/gstreamer/#installation) 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`](https://github.com/rerun-io/rerun) recording stream for visualization.

For more examples and use cases, check out the [`examples`](https://github.com/kornia/kornia-rs/tree/main/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...

```rust
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(())
}
```

![Screenshot from 2024-03-09 14-31-41](https://github.com/kornia/kornia-rs/assets/5157099/afdc11e6-eb36-4fcc-a6a1-e2240318958d)

## Python Usage

### Reading Images

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

```python
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:

```python
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):

```python
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:

```python
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:

```python
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

1. **Install Rust** using rustup:
   ```bash
   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   ```

2. **Install [`pixi`](https://pixi.sh)** for package and environment management:
   ```bash
   curl -fsSL https://pixi.sh/install.sh | bash
   ```

3. **Clone the repository** to your local directory:
   ```bash
   git clone https://github.com/kornia/kornia-rs.git
   ```

4. **Install dependencies** using pixi:
   ```bash
   pixi install
   ```

### Available Commands

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

```bash
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:

```bash
pixi run rust-test
```

To run tests for a specific package:

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

To run clippy linting:

```bash
pixi run rust-clippy
```

### 🐍 Python Development

Build Python wheels using `maturin`:

```bash
pixi run py-build
```

Run Python tests:

```bash
pixi run py-test
```

## 💜 Contributing

We welcome contributions! Please read [CONTRIBUTING.md](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](AI_POLICY.md) 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](AI_POLICY.md) for complete details.

### Community

This is a child project of [Kornia](https://github.com/kornia/kornia).

- 💬 Join our community on [Discord](https://discord.gg/HfnywwpBnD)
- 💖 Support the project on [OpenCollective](https://opencollective.com/kornia)
- 📖 Read the full [documentation](https://kornia.readthedocs.io/en/stable/)
- 🦀 Browse the [Rust API docs](https://docs.rs/kornia)

## Citation

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

```bibtex
@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},
}
```