Struct Image

Source

pub struct Image<T, const C: usize>(pub Tensor<T, 3, CpuAllocator>);

Expand description

Represents an image with pixel data.

The image is represented as a 3D Tensor with shape (H, W, C), where H is the height of the image,

Tuple Fields§

§0: Tensor<T, 3, CpuAllocator>

Implementations§

Source §

impl<T, const C: usize> Image<T, C>

Source

pub fn new(size: ImageSize, data: Vec<T>) -> Result<Image<T, C>, ImageError>
where T: Clone,

Create a new image from pixel data.

§Arguments

size - The size of the image in pixels.
data - The pixel data of the image.

§Returns

A new image with the given pixel data.

§Errors

If the length of the pixel data does not match the image size, an error is returned.

§Examples

use kornia_image::{Image, ImageSize};

let image = Image::<u8, 3>::new(
   ImageSize {
      width: 10,
     height: 20,
 },
vec![0u8; 10 * 20 * 3],
).unwrap();

assert_eq!(image.size().width, 10);
assert_eq!(image.size().height, 20);
assert_eq!(image.num_channels(), 3);

Source

pub fn from_size_val(size: ImageSize, val: T) -> Result<Image<T, C>, ImageError>
where T: Clone + Default,

Create a new image with the given size and default pixel data.

§Arguments

size - The size of the image in pixels.
val - The default value of the pixel data.

§Returns

A new image with the given size and default pixel data.

§Errors

If the length of the pixel data does not match the image size, an error is returned.

§Examples

use kornia_image::{Image, ImageSize};

let image = Image::<u8, 3>::from_size_val(
  ImageSize {
    width: 10,
   height: 20,
}, 0u8).unwrap();

assert_eq!(image.size().width, 10);
assert_eq!(image.size().height, 20);
assert_eq!(image.num_channels(), 3);

Source

pub unsafe fn from_raw_parts( size: ImageSize, data: *const T, len: usize, ) -> Result<Image<T, C>, ImageError>
where T: Clone,

Create a new image from raw parts.

§Arguments

size - The size of the image in pixels.
data - A pointer to the pixel data.
len - The length of the pixel data.

§Returns

A new image created from the given size and pixel data.

§Safety

The pointer must be non-null and the length must be valid.

Source

pub fn from_size_slice( size: ImageSize, data: &[T], ) -> Result<Image<T, C>, ImageError>
where T: Clone,

Create a new image from a slice of pixel data.

§Arguments

size - The size of the image in pixels.
data - A slice containing the pixel data.

§Returns

A new image created from the given size and pixel data.

§Errors

Returns an error if the length of the data slice doesn’t match the image dimensions, or if there’s an issue creating the tensor or image.

Source

pub fn map(&self, f: impl Fn(&T) -> U) -> Result<Image<U, C>, ImageError>
where U: Clone,

Map the pixel data of the image to a different type.

§Arguments

f - A function that takes a pixel value and returns a new pixel value.

§Returns

A new image with the pixel data mapped to the new type.

Source

pub fn cast(&self) -> Result<Image<U, C>, ImageError>
where U: NumCast + Clone + Copy, T: NumCast + Clone + Copy,

Cast the pixel data of the image to a different type.

§Returns

A new image with the pixel data cast to the given type.

Source

pub fn channel(&self, channel: usize) -> Result<Image<T, 1>, ImageError>
where T: Clone,

Get a channel of the image.

§Arguments

channel - The channel to get.

§Returns

A new image with the given channel.

§Errors

If the channel index is out of bounds, an error is returned.

Source

pub fn split_channels(&self) -> Result<Vec<Image<T, 1>>, ImageError>
where T: Clone + Copy,

Split the image into its channels.

§Returns

A vector of images, each containing one channel of the original image.

§Examples

use kornia_image::{Image, ImageSize};

let image = Image::<f32, 2>::from_size_val(
  ImageSize {
   width: 10,
  height: 20,
},
0.0f32).unwrap();

let channels = image.split_channels().unwrap();
assert_eq!(channels.len(), 2);

Source

pub fn size(&self) -> ImageSize

Get the size of the image in pixels.

Source

pub fn cols(&self) -> usize

Get the number of columns of the image.

Source

pub fn rows(&self) -> usize

Get the number of rows of the image.

Source

pub fn width(&self) -> usize

Get the width of the image in pixels.

Source

pub fn height(&self) -> usize

Get the height of the image in pixels.

Source

pub fn num_channels(&self) -> usize

Get the number of channels in the image.

Source

pub fn cast_and_scale(self, scale: U) -> Result<Image<U, C>, ImageError>
where U: NumCast + Mul<Output = U> + Clone + Copy, T: NumCast + Clone + Copy,

Cast the pixel data to a different type and scale it.

§Arguments

scale - The scale to multiply the pixel data with.

§Returns

A new image with the pixel data cast to the new type and scaled.

§Errors

If the pixel data cannot be cast to the new type, an error is returned.

§Examples

use kornia_image::{Image, ImageSize};

let data = vec![0u8, 0, 255, 0, 0, 255];

let image_u8 = Image::<u8, 3>::new(
ImageSize {
  height: 2,
  width: 1,
},
data,
).unwrap();

let image_f32 = image_u8.cast_and_scale::<f32>(1. / 255.0).unwrap();

assert_eq!(image_f32.get([1, 0, 2]), Some(&1.0f32));

Source

pub fn scale_and_cast(&self, scale: T) -> Result<Image<U, C>, ImageError>
where U: NumCast + Clone + Copy, T: NumCast + Mul<Output = T> + Clone + Copy,

Cast the pixel data to a different type and scale it.

§Arguments

scale - The scale to multiply the pixel data with.

§Returns

A new image with the pixel data cast to the new type and scaled.

Source

pub fn get_pixel(&self, x: usize, y: usize, ch: usize) -> Result<&T, ImageError>

Get the pixel data of the image.

NOTE: this is method is for convenience and not optimized for performance. We recommend using iterators over the data slice.

§Arguments

x - The x-coordinate of the pixel.
y - The y-coordinate of the pixel.
ch - The channel index of the pixel.

§Returns

The pixel value at the given coordinates.

Source

pub fn set_pixel( &mut self, x: usize, y: usize, ch: usize, val: T, ) -> Result<(), ImageError>

Set the pixel value at the given coordinates.

NOTE: this is method is for convenience and not optimized for performance. We recommend creating a mutable slice and operating on it directly.

§Arguments

x - The x-coordinate of the pixel.
y - The y-coordinate of the pixel.
ch - The channel index of the pixel.
val - The value to set the pixel to.

§Returns

The pixel value at the given coordinates.

Methods from Deref<Target = Tensor<T, 3, CpuAllocator>>§

Source

pub fn as_slice(&self) -> &[T]

Get the data of the tensor as a slice.

§Returns

A slice containing the data of the tensor.

Source

pub fn as_slice_mut(&mut self) -> &mut [T]

Get the data of the tensor as a mutable slice.

§Returns

A mutable slice containing the data of the tensor.

Source

pub fn as_ptr(&self) -> *const T

Get the data of the tensor as a pointer.

§Returns

A pointer to the data of the tensor.

Source

pub fn as_mut_ptr(&mut self) -> *mut T

Get the data of the tensor as a mutable pointer.

§Returns

A mutable pointer to the data of the tensor.

Source

pub fn numel(&self) -> usize

Returns the number of elements in the tensor.

§Returns

The number of elements in the tensor.

Source

pub fn get_iter_offset(&self, index: [usize; N]) -> Option<usize>

Get the offset of the element at the given index.

§Arguments

index - The list of indices to get the element from.

§Returns

The offset of the element at the given index.

Source

pub fn get_iter_offset_unchecked(&self, index: [usize; N]) -> usize

Get the offset of the element at the given index without checking dim sizes.

§Arguments

index - The list of indices to get the element from.

§Returns

The offset of the element at the given index.

Source

pub fn get_index_unchecked(&self, offset: usize) -> [usize; N]

Get the index of the element at the given offset without checking dim sizes. The reverse of Self::get_iter_offset_unchecked.

§Arguments

offset - The offset of the element at the given index.

§Returns

The array of indices to get the element from.

Source

pub fn get_index(&self, offset: usize) -> Result<[usize; N], TensorError>

Get the index of the element at the given offset. The reverse of Self::get_iter_offset.

§Arguments

offset - The offset of the element at the given index.

§Returns

The array of indices to get the element from.

§Errors

If the offset is out of bounds (>= numel), an error is returned.

Source

pub fn get_unchecked(&self, index: [usize; N]) -> &T

Get the element at the given index without checking if the index is out of bounds.

§Arguments

index - The list of indices to get the element from.

§Returns

A reference to the element at the given index.

§Example

use kornia_tensor::{Tensor, CpuAllocator};

let data: Vec<u8> = vec![1, 2, 3, 4];

let t = Tensor::<u8, 2, CpuAllocator>::from_shape_vec([2, 2], data, CpuAllocator).unwrap();
assert_eq!(*t.get_unchecked([0, 0]), 1);
assert_eq!(*t.get_unchecked([0, 1]), 2);
assert_eq!(*t.get_unchecked([1, 0]), 3);
assert_eq!(*t.get_unchecked([1, 1]), 4);

Source

pub fn get(&self, index: [usize; N]) -> Option<&T>

Get the element at the given index, checking if the index is out of bounds.

§Arguments

index - The list of indices to get the element from.

§Returns

A reference to the element at the given index.

§Errors

If the index is out of bounds, an error is returned.

§Example

use kornia_tensor::{Tensor, CpuAllocator};

let data: Vec<u8> = vec![1, 2, 3, 4];

let t = Tensor::<u8, 2, CpuAllocator>::from_shape_vec([2, 2], data, CpuAllocator).unwrap();

assert_eq!(t.get([0, 0]), Some(&1));
assert_eq!(t.get([0, 1]), Some(&2));
assert_eq!(t.get([1, 0]), Some(&3));
assert_eq!(t.get([1, 1]), Some(&4));

assert!(t.get([2, 0]).is_none());

Source

pub fn reshape<const M: usize>( &self, shape: [usize; M], ) -> Result<TensorView<'_, T, M, A>, TensorError>

Reshape the tensor to a new shape.

§Arguments

shape - The new shape of the tensor.

§Returns

A new TensorView instance.

§Errors

If the number of elements in the new shape does not match the number of elements in the tensor, an error is returned.

§Example

use kornia_tensor::{Tensor, CpuAllocator};

let data: Vec<u8> = vec![1, 2, 3, 4];

let t = Tensor::<u8, 1, CpuAllocator>::from_shape_vec([4], data, CpuAllocator).unwrap();
let t2 = t.reshape([2, 2]).unwrap();
assert_eq!(t2.shape, [2, 2]);
assert_eq!(t2.as_slice(), vec![1, 2, 3, 4]);
assert_eq!(t2.strides, [2, 1]);
assert_eq!(t2.numel(), 4);

Source

pub fn permute_axes(&self, axes: [usize; N]) -> TensorView<'_, T, N, A>

Permute the dimensions of the tensor.

The permutation is given as an array of indices, where the value at each index is the new index of the dimension. The data is not moved, only the order of the dimensions is changed.

§Arguments

axes - The new order of the dimensions.

§Returns

A view of the tensor with the dimensions permuted.

Source

pub fn view(&self) -> TensorView<'_, T, N, A>

Return a view of the tensor.

The view is a reference to the tensor storage with a different shape and strides.

§Returns

A TensorView instance.

Source

pub fn map<U, F>(&self, f: F) -> Tensor<U, N, A>
where F: Fn(&T) -> U,

Apply a function to each element of the tensor.

§Arguments

f - The function to apply to each element.

§Returns

A new Tensor instance.

§Example

use kornia_tensor::{Tensor, CpuAllocator};

let data: Vec<u8> = vec![1, 2, 3, 4];
let t = Tensor::<u8, 1, CpuAllocator>::from_shape_vec([4], data, CpuAllocator).unwrap();

let t2 = t.map(|x| *x + 1);
assert_eq!(t2.as_slice(), vec![2, 3, 4, 5]);

Source

pub fn cast(&self) -> Tensor<U, N, CpuAllocator>
where U: From<T>, T: Clone,

Cast the tensor to a new type.

§Returns

A new Tensor instance.

§Example

use kornia_tensor::{Tensor, CpuAllocator};

let data: Vec<u8> = vec![1, 2, 3, 4];
let t = Tensor::<u8, 1, CpuAllocator>::from_shape_vec([4], data, CpuAllocator).unwrap();

let t2 = t.cast::<f32>();
assert_eq!(t2.as_slice(), vec![1.0, 2.0, 3.0, 4.0]);

Source

pub fn element_wise_op<F>( &self, other: &Tensor<T, N, CpuAllocator>, op: F, ) -> Result<Tensor<T, N, CpuAllocator>, TensorError>
where F: Fn(&T, &T) -> T,

Perform an element-wise operation on two tensors.

§Arguments

other - The other tensor to perform the operation with.
op - The operation to perform.

§Returns

A new Tensor instance.

§Example

use kornia_tensor::{Tensor, CpuAllocator};

let data1: Vec<u8> = vec![1, 2, 3, 4];
let t1 = Tensor::<u8, 1, CpuAllocator>::from_shape_vec([4], data1, CpuAllocator).unwrap();

let data2: Vec<u8> = vec![1, 2, 3, 4];
let t2 = Tensor::<u8, 1, CpuAllocator>::from_shape_vec([4], data2, CpuAllocator).unwrap();

let t3 = t1.element_wise_op(&t2, |a, b| *a + *b).unwrap();
assert_eq!(t3.as_slice(), vec![2, 4, 6, 8]);

let t4 = t1.element_wise_op(&t2, |a, b| *a - *b).unwrap();
assert_eq!(t4.as_slice(), vec![0, 0, 0, 0]);

let t5 = t1.element_wise_op(&t2, |a, b| *a * *b).unwrap();
assert_eq!(t5.as_slice(), vec![1, 4, 9, 16]);

let t6 = t1.element_wise_op(&t2, |a, b| *a / *b).unwrap();
assert_eq!(t6.as_slice(), vec![1, 1, 1, 1]);

Trait Implementations§

Source §

impl<T, const C: usize> Clone for Image<T, C>
where T: Clone,

Source §

fn clone(&self) -> Image<T, C>

Returns a duplicate of the value. Read more

1.0.0 · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more

Source §

impl<T, const C: usize> Deref for Image<T, C>

helper to deference the inner tensor

Source §

type Target = Tensor<T, 3, CpuAllocator>

The resulting type after dereferencing.

Source §

fn deref(&self) -> &<Image<T, C> as Deref>::Target

Dereferences the value.

Source §

impl<T, const C: usize> DerefMut for Image<T, C>

helper to deference the inner tensor

Source §

fn deref_mut(&mut self) -> &mut <Image<T, C> as Deref>::Target

Mutably dereferences the value.

Source §

impl<T> TryFrom<Tensor<T, 2, CpuAllocator>> for Image<T, 1>
where T: Clone,

helper to convert an single channel tensor to a kornia image with try into

Source §

type Error = ImageError

The type returned in the event of a conversion error.

Source §

fn try_from( value: Tensor<T, 2, CpuAllocator>, ) -> Result<Image<T, 1>, <Image<T, 1> as TryFrom<Tensor<T, 2, CpuAllocator>>>::Error>

Performs the conversion.

Source §

impl<T, const C: usize> TryFrom<Tensor<T, 3, CpuAllocator>> for Image<T, C>

helper to convert an multi channel tensor to a kornia image with try into

Source §

type Error = ImageError

The type returned in the event of a conversion error.

Source §

fn try_from( value: Tensor<T, 3, CpuAllocator>, ) -> Result<Image<T, C>, <Image<T, C> as TryFrom<Tensor<T, 3, CpuAllocator>>>::Error>

Performs the conversion.

Source §

impl<T, const C: usize> TryInto<Tensor<T, 3, CpuAllocator>> for Image<T, C>

Source §

type Error = ImageError

The type returned in the event of a conversion error.

Source §

fn try_into( self, ) -> Result<Tensor<T, 3, CpuAllocator>, <Image<T, C> as TryInto<Tensor<T, 3, CpuAllocator>>>::Error>

Performs the conversion.

Auto Trait Implementations§

§

impl<T, const C: usize> UnwindSafe for Image<T, C>
where T: RefUnwindSafe,

Blanket Implementations§

Source §

impl<T> Any for T
where T: 'static + ?Sized,

Source §

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more

Source §

impl<T> Az for T

Source §

fn az<Dst>(self) -> Dst
where T: Cast<Dst>,

Casts the value.

Source §

impl<T> Borrow<T> for T
where T: ?Sized,

Source §

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more

Source §

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source §

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more

Source §

impl<Src, Dst> CastFrom<Src> for Dst
where Src: Cast<Dst>,

Source §

fn cast_from(src: Src) -> Dst

Casts the value.

Source §

impl<T> CheckedAs for T

Source §

fn checked_as<Dst>(self) -> Option<Dst>
where T: CheckedCast<Dst>,

Casts the value.

Source §

impl<Src, Dst> CheckedCastFrom<Src> for Dst
where Src: CheckedCast<Dst>,

Source §

fn checked_cast_from(src: Src) -> Option<Dst>

Casts the value.

Source §

impl<T> CloneToUninit for T
where T: Clone,

Source §

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)

Performs copy-assignment from self to dest. Read more

Source §

impl<T> From<T> for T

Source §

fn from(t: T) -> T

Returns the argument unchanged.

Source §

impl<T, U> Into for T
where U: From<T>,

Source §

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source §

impl<T> IntoEither for T

Source §

fn into_either(self, into_left: bool) -> Either<Self, Self>

Converts self into a Left variant of Either<Self, Self> if into_left is true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more

Source §

fn into_either_with<F>(self, into_left: F) -> Either<Self, Self>
where F: FnOnce(&Self) -> bool,

Converts self into a Left variant of Either<Self, Self> if into_left(&self) returns true. Converts self into a Right variant of Either<Self, Self> otherwise. Read more

Source §