Image FastFormat DataType

[Hennzau]

First FastFormat DataType

This PR adds the first FastFormat DataType, the Image DataType, and the project structure.

Representation

An Image is represented by a struct with two Enum Variant with the corresponding data and encoding

pub enum DataContainer {
    U8Data(Vec<u8>),
}

pub enum Encoding {
    RGB8,
    BGR8,
    GRAY8,
}

pub struct Image {
    pub data: DataContainer,

    pub width: u32,
    pub height: u32,

    pub encoding: Encoding,

    pub name: Option<String>,
}

Usage

You can then create an Image from flat data:

use fastformat::image::Image;

let pixels = vec![0; 27]; // 3x3 image with 3 bytes per pixel
let image = Image::new_bgr8(pixels, 3, 3, Some("example")).unwrap();

Features

• You can convert RGB8 <-> BGR8 in place

use fastformat::image::Image;

let pixels = vec![0; 27]; // 3x3 image with 3 bytes per pixel
let bgr8_image = Image::new_bgr8(pixels, 3, 3, Some("example")).unwrap();
let rgb8_image = bgr8_image.to_rgb8().unwrap();

• You can convert Image <-> NDArray with ZeroCopy

use crate::image::Image;

let pixels = vec![0; 27]; // 3x3 image with 3 bytes per pixel
let bgr8_image = Image::new_bgr8(pixels, 3, 3, Some("example")).unwrap();
let bgr8_ndarray = bgr8_image.bgr8_to_ndarray().unwrap();
let bgr8_image = Image::bgr8_from_ndarray(bgr8_ndarray, None);

• You can convert Image <-> Arrow with ZeroCopy

/*
- **Image** as a **UnionArray**,
    - Field "pixels': UintXArray (e.g [0, 255, 0, 255, 0, 255, ...])
    - Field "width": Uint32Array (e.g [1280])
    - Field "height": Uint32Array (e.g [720])
    - Field "encoding": StringArray (e.g ["RGB8"])
    - Field "name" (Optional): StringArray (e.g,["image.front_camera"] or [None])
*/

use crate::image::Image;

let pixels = vec![0; 27]; // 3x3 image with 3 bytes per pixel
let bgr8_image = Image::new_bgr8(pixels, 3, 3, Some("example")).unwrap();
let arrow_image = bgr8_image.to_arrow().unwrap();
let bgr8_image = Image::from_arrow(arrow_image).unwrap();

RoadMap to finish this PR

• separate the image.rs file into submodules for each datatype so everyone can simply add a module like rgba16.rs to add its owm Implementation for the Image Enum

image.rs/
├── bgr8.rs
├── rgb8.rs
├── gray8rs
└── rgba16.rs

• add tests inside each image submodule directly

[haixuanTao]

Looks really good overall!

I left some comments as well as I would recommend checking the clippy warnings that you can see here: https://github.com/dora-rs/fastformat/pull/1/files

I think you can merge it after the couple of comments.

Looks very very solid!

[phil-opp]

Thanks for the PR, looks good to me too!

Two nits:

• You can convert RGB8 <-> BGR8 with ZeroCopy

  I think the term "in place" fits better here than "zero copy", given that the data is processed and changed. "In place" makes it clear that no additional allocations are created. When I see "zero copy", I think that the original data is left untouched without any processing (just the interpretation changes) and that the operation has negligible cost (i.e. O(1)).

• Rust's API guidelines recommend naming conversion methods that take self by value into_*. This way, it is clear that the original data is no longer available after using the method. Methods named to_* should only take &self (with the exception of Copy types).
  This PR introduces some methods named to_* that take self by value. For example, to_arrow or to_bgr8. It would be better to rename these to into_arrow/into_bgr8/etc.

[Hennzau]

Thanks for the PR, looks good to me too!

Two nits:

• You can convert RGB8 <-> BGR8 with ZeroCopy

  I think the term "in place" fits better here than "zero copy", given that the data is processed and changed. "In place" makes it clear that no additional allocations are created. When I see "zero copy", I think that the original data is left untouched without any processing (just the interpretation changes) and that the operation has negligible cost (i.e. O(1)).

• Rust's API guidelines recommend naming conversion methods that take self by value into_*. This way, it is clear that the original data is no longer available after using the method. Methods named to_* should only take &self (with the exception of Copy types).

  This PR introduces some methods named to_* that take self by value. For example, to_arrow or to_bgr8. It would be better to rename these to into_arrow/into_bgr8/etc.

Hi! Thanks for your review!

I will make sure to change those to_ for into_ in the next PR! 😄