kornia-image 0.1.14

Image types and traits for generating and manipulating images
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85

# Kornia: kornia-image

[![Crates.io](https://img.shields.io/crates/v/kornia-image.svg)](https://crates.io/crates/kornia-image)
[![Documentation](https://docs.rs/kornia-image/badge.svg)](https://docs.rs/kornia-image)
[![License](https://img.shields.io/crates/l/kornia-image.svg)](https://github.com/kornia/kornia/blob/main/LICENSE)

> **Image types and traits for computer vision in Rust.**

## 🚀 Overview

`kornia-image` provides a strongly-typed image representation for computer vision applications. It is built on top of `kornia-tensor` and offers a flexible memory layout that supports various pixel formats and data types. The library is designed to be zero-copy where possible and allows for easy integration with other libraries in the ecosystem.

## 🔑 Key Features

* **Strongly-typed Image Struct:** The `Image<T, C, A>` struct ensures compile-time safety for pixel types (`T`) and channel counts (`C`).
* **Flexible Memory Management:** Uses the `ImageAllocator` trait to support different memory backends (e.g., CPU, potentially GPU).
* **Rich Operations:** built-in support for casting, scaling, channel splitting/merging, and pixel access.
* **Arrow Integration:** Optional support for converting images to Arrow format for data processing pipelines.
* **Color Space Safety:** Includes typed wrappers for color spaces (e.g., `Rgb8`, `Gray8`) to prevent mixing up image formats.

## 📦 Installation

Add the following to your `Cargo.toml`:

```toml
[dependencies]
kornia-image = "0.1.0"
```

## 🛠️ Usage

Here is a simple example showing how to create and manipulate an image:

```rust
use kornia_image::{Image, ImageSize, allocator::CpuAllocator};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Create a dummy RGB image (3 channels) with u8 data
    let image_size = ImageSize { width: 10, height: 20 };
    let data = vec![0u8; 10 * 20 * 3];
    let image = Image::<u8, 3, _>::new(image_size, data, CpuAllocator)?;

    println!("Image size: {:?}", image.size());
    println!("Channels: {}", image.num_channels());

    // 2. Cast to f32 and scale values to [0, 1]
    let image_f32 = image.cast_and_scale::<f32>(1.0 / 255.0)?;

    // 3. Access specific pixel (slow, for convenience)
    let pixel_val = image_f32.get_pixel(5, 5, 0)?;
    println!("Pixel at (5,5) ch 0: {}", pixel_val);

    // 4. Split into individual channels
    let channels = image_f32.split_channels()?;
    println!("Split into {} single-channel images", channels.len());

    Ok(())
}
```

## 🧩 Modules

*   **`image`**: Core `Image` struct, `ImageSize`, `ImageLayout`, and `PixelFormat`.
*   **`allocator`**: Memory management utilities and the `ImageAllocator` trait.
*   **`error`**: Error types for the image module.
*   **`ops`**: Basic image operations.
*   **`color_spaces`**: Typed wrappers for common color spaces.
*   **`arrow`**: (Optional, feature: `arrow`) Utilities for Apache Arrow integration.

## 💡 Related Examples

You can find comprehensive examples in the `examples` folder of the repository:

*   [`image_api`](../../examples/image_api): Demonstration of the basic image API.
*   [`color_spaces`](../../examples/color_spaces): Working with different color spaces.
*   [`foxglove`](../../examples/foxglove): Using image types for visualization.
*   [`ros-z-nodes`](../../examples/ros-z-nodes): Using images in a ROS 2 context.

## 🤝 Contributing

Contributions are welcome! This crate is part of the Kornia workspace. Please refer to the main repository for contribution guidelines.

## 📄 License

This crate is licensed under the Apache-2.0 License.