edgefirst_codec/
traits.rs

1// SPDX-FileCopyrightText: Copyright 2026 Au-Zone Technologies
2// SPDX-License-Identifier: Apache-2.0
3
4//! [`ImageLoad`] extension trait for loading images into pre-allocated tensors.
5
6use crate::decoder::ImageDecoder;
7use crate::error::CodecError;
8use crate::options::ImageInfo;
9use crate::pixel::ImagePixel;
10use edgefirst_tensor::{Tensor, TensorDyn};
11use std::io::{BufReader, Read};
12use std::path::Path;
13
14/// Extension trait for loading images into pre-allocated tensors.
15///
16/// Import this trait to add `load_image`, `load_image_read`, and
17/// `load_image_file` methods to [`Tensor<T>`] and [`TensorDyn`].
18///
19/// The decoder configures the tensor's dimensions and pixel format to the
20/// decoded native format (JPEG → `Nv12`/`Grey`, PNG → `Rgb`/`Rgba`/`Grey`).
21/// Allocate the tensor at the maximum expected image size; smaller images
22/// reconfigure it within the same allocation.
23///
24/// # Example
25///
26/// ```rust,no_run
27/// use edgefirst_codec::{ImageDecoder, ImageLoad};
28/// use edgefirst_tensor::{Tensor, TensorTrait, TensorMemory, PixelFormat};
29///
30/// let mut tensor = Tensor::<u8>::image(1920, 1080, PixelFormat::Nv12, Some(TensorMemory::Mem))
31///     .expect("alloc");
32/// let mut decoder = ImageDecoder::new();
33///
34/// let jpeg = std::fs::read("image.jpg").unwrap();
35/// let info = tensor.load_image(&mut decoder, &jpeg).unwrap();
36/// println!("Decoded {}×{} {:?}", info.width, info.height, info.format);
37///
38/// let info = tensor.load_image_file(&mut decoder, "image.jpg").unwrap();
39/// ```
40pub trait ImageLoad {
41    /// Decode image bytes (`&[u8]`) into this tensor, configuring its
42    /// dimensions and format to the decoded native format.
43    ///
44    /// The image format (JPEG or PNG) is detected from magic bytes.
45    ///
46    /// # Errors
47    ///
48    /// Returns [`CodecError::InsufficientCapacity`] if the decoded image is
49    /// larger than the tensor's allocation.
50    fn load_image(&mut self, decoder: &mut ImageDecoder, data: &[u8]) -> crate::Result<ImageInfo>;
51
52    /// Decode image data from a [`Read`] source into this tensor.
53    fn load_image_read<R: Read>(
54        &mut self,
55        decoder: &mut ImageDecoder,
56        reader: R,
57    ) -> crate::Result<ImageInfo>;
58
59    /// Decode an image file into this tensor.
60    fn load_image_file(
61        &mut self,
62        decoder: &mut ImageDecoder,
63        path: impl AsRef<Path>,
64    ) -> crate::Result<ImageInfo>;
65}
66
67impl<T: ImagePixel> ImageLoad for Tensor<T> {
68    fn load_image(&mut self, decoder: &mut ImageDecoder, data: &[u8]) -> crate::Result<ImageInfo> {
69        decoder.decode_into(data, self)
70    }
71
72    fn load_image_read<R: Read>(
73        &mut self,
74        decoder: &mut ImageDecoder,
75        reader: R,
76    ) -> crate::Result<ImageInfo> {
77        decoder.decode_from_reader(reader, self)
78    }
79
80    fn load_image_file(
81        &mut self,
82        decoder: &mut ImageDecoder,
83        path: impl AsRef<Path>,
84    ) -> crate::Result<ImageInfo> {
85        let file = std::fs::File::open(path.as_ref()).map_err(CodecError::Io)?;
86        self.load_image_read(decoder, BufReader::new(file))
87    }
88}
89
90impl ImageLoad for TensorDyn {
91    fn load_image(&mut self, decoder: &mut ImageDecoder, data: &[u8]) -> crate::Result<ImageInfo> {
92        decoder.decode_into_dyn(data, self)
93    }
94
95    fn load_image_read<R: Read>(
96        &mut self,
97        decoder: &mut ImageDecoder,
98        reader: R,
99    ) -> crate::Result<ImageInfo> {
100        decoder.decode_from_reader_dyn(reader, self)
101    }
102
103    fn load_image_file(
104        &mut self,
105        decoder: &mut ImageDecoder,
106        path: impl AsRef<Path>,
107    ) -> crate::Result<ImageInfo> {
108        let file = std::fs::File::open(path.as_ref()).map_err(CodecError::Io)?;
109        self.load_image_read(decoder, BufReader::new(file))
110    }
111}
edgefirst_codec/traits.rs

edgefirst_codec/
traits.rs
