Struct DynamicFrame

pub struct DynamicFrame<'a> { /* private fields */ }

An image whose pixel format is determined at runtime.

This type is used to represent images where the pixel format is not known at compile time, allowing for flexibility in handling various image formats.

It can be created from raw image data and provides methods to access the image dimensions, pixel format, and raw data. It also supports conversion to static pixel formats and encoding to various formats.

Type Parameters

• 'a - Lifetime of the borrowed data. If you want to own the data, use DynamicFrameOwned.

Notes

• This type is not Sync or Send because it contains a borrowed buffer. If you need to share it across threads, use DynamicFrameOwned instead.
• The pixel format is represented by the PixFmt enum, which allows for various pixel formats like Mono8, RGB8, etc.
• The buffer must be large enough to hold the image data for the specified dimensions and pixel format.

Examples

// Create a frame from raw data
let data = vec![0u8; 1920 * 1080];
let frame = DynamicFrame::from_buf(1920, 1080, 1920, data, PixFmt::Mono8).unwrap();

// Check the pixel format
assert_eq!(frame.pixel_format(), PixFmt::Mono8);

// Get dimensions
println!("Size: {}x{}", frame.width(), frame.height());

Implementations

impl<'a> DynamicFrame<'a>

pub fn copy_to_owned(&self) -> DynamicFrameOwned

Return a new DynamicFrameOwned by copying data.

pub fn from_static_ref<FMT: PixelFormat>( frame: &'a dyn ImageStride<FMT>, ) -> Self

Return a new DynamicFrame from a reference to a statically typed frame. This does not copy the input data.

pub fn from_buf( w: u32, h: u32, stride: usize, buf: Vec<u8>, pixfmt: PixFmt, ) -> Option<Self>

Creates a new DynamicFrame from raw image data.

This function moves the provided buffer into the new frame without copying. The buffer size must be appropriate for the given dimensions and pixel format.

Parameters

• w - Image width in pixels
• h - Image height in pixels
• s - Row stride in bytes (must be >= width * bytes_per_pixel)
• buf - Raw image data buffer
• pixfmt - Pixel format of the image data

Returns

• Some(DynamicFrame) if the buffer is valid for the given parameters
• None if the buffer is too small.

Examples

let data = vec![128u8; 640 * 480]; // Gray image data
let frame = DynamicFrame::from_buf(640, 480, 640, data, PixFmt::Mono8);
assert!(frame.is_some());

pub fn width(&self) -> u32

Returns the width of the image in pixels.

Examples

let data = vec![0u8; 1500];
let frame = DynamicFrame::from_buf(50, 10, 150, data, PixFmt::RGB8).unwrap();
assert_eq!(frame.width(), 50);

pub fn height(&self) -> u32

Returns the height of the image in pixels.

Examples

let data = vec![0u8; 2000];
let frame = DynamicFrame::from_buf(40, 50, 40, data, PixFmt::Mono8).unwrap();
assert_eq!(frame.height(), 50);

pub fn copy_from<FMT: PixelFormat>(frame: &'a dyn ImageStride<FMT>) -> Self

Creates a new DynamicFrame from an existing frame using borrowed data.

This function copies the image data from the source frame and creates a new DynamicFrame. The original frame remains unchanged.

Type Parameters

• FMT - The pixel format type of the source frame

Parameters

• frame - Reference to the source frame implementing ImageStride

Examples

let source = OImage::<Mono8>::new(100, 100, 100, vec![0u8; 10000]).unwrap();
let dynamic_frame = DynamicFrame::copy_from(&source);
assert_eq!(dynamic_frame.width(), 100);

pub fn into_pixel_format<FMT>(&self) -> Result<CowImage<'_, FMT>, Error>

where FMT: PixelFormat,

Available on crate feature convert-image only.

Converts the image to the specified pixel format, returning a CowImage that may borrow or own the data.

If the requested pixel format matches the current format, this method returns a borrowed view of the data without copying. Otherwise, the data is converted and a new owned image is returned.

Type Parameters

• FMT - The target pixel format type

Returns

• Ok(CowImage<FMT>) - Either a borrowed view or owned converted image
• Err(convert_image::Error) - If conversion fails

Examples

let data = vec![64u8; 2000];
let frame = DynamicFrame::from_buf(20, 10, 200, data, PixFmt::Mono8).unwrap();

// No conversion needed - returns borrowed view
let cow_image = frame.into_pixel_format::<Mono8>().unwrap();

pub fn as_static<FMT: PixelFormat>(&'a self) -> Option<ImageRef<'a, FMT>>

Return a borrowed view of the image data as a static pixel format.

This method allows you to treat the dynamic frame as a specific pixel format without copying the data, as long as the pixel format matches.

Type Parameters

• FMT - The target pixel format type

Returns

• Some(ImageRef<FMT>) if the pixel format matches
• None if the pixel format does not match

Examples

// Create a dynamic frame with Mono8 pixel format.
let data = vec![128u8; 1000];
let frame = DynamicFrame::from_buf(100, 10, 100, data, PixFmt::Mono8).unwrap();

// Convert to a static Mono8 view
let static_view: Option<ImageRef<Mono8>> = frame.as_static();
assert!(static_view.is_some());
assert_eq!(static_view.unwrap().width(), 100);

pub fn into_pixel_format_dest<FMT>( &self, dest: &mut dyn HasRowChunksExactMut<FMT>, ) -> Result<(), Error>

where FMT: PixelFormat,

Available on crate feature convert-image only.

Converts the image data into a mutable destination buffer of the specified pixel format.

This method will convert the data in-place, modifying the destination buffer to match the pixel format of the source image.

Parameters

• dest - A mutable reference to the destination buffer implementing machine_vision_formats::iter::HasRowChunksExactMut for the target pixel format.

Returns

• Ok(()) if the conversion was successful
• Err(convert_image::Error) if the conversion fails

Examples

// Create a dynamic frame with RGB8 pixel format.
let data = vec![255u8; 3000]; // RGB8 data for 100x10 image
let frame = DynamicFrame::from_buf(100, 10, 300, data, PixFmt::RGB8).unwrap();

// Create a destination buffer for Mono8 format
let mut dest = OImage::<Mono8>::zeros(100, 10, 100).unwrap();

// Convert the frame into the destination buffer
frame.into_pixel_format_dest(&mut dest).unwrap();
assert_eq!(dest.width(), 100);
assert_eq!(dest.height(), 10);
assert_eq!(dest.stride(), 100);

pub fn to_encoded_buffer(&self, opts: EncoderOptions) -> Result<Vec<u8>, Error>

Available on crate feature convert-image only.

Converts the image to a byte buffer encoded in the specified format.

This method encodes the image data into a format suitable for storage or transmission. The encoding options can be specified using convert_image::EncoderOptions.

Parameters

• opts - Encoding options for the output format

Returns

• Ok(Vec<u8>) - The encoded image data as a byte vector
• Err(convert_image::Error) - If the encoding fails

Examples

let data = vec![255u8; 3000]; // RGB8 data for 100x10 image
let frame = DynamicFrame::from_buf(100, 10, 300, data, PixFmt::RGB8).unwrap();

// Encode the frame to PNG bytes
let encoded_buffer = frame.to_encoded_buffer(convert_image::EncoderOptions::Png).unwrap();
assert!(!encoded_buffer.is_empty());

pub fn pixel_format(&self) -> PixFmt

Returns the pixel format of this image.

Examples

let data = vec![0u8; 300];
let frame = DynamicFrame::from_buf(10, 10, 30, data, PixFmt::RGB8).unwrap();
assert_eq!(frame.pixel_format(), PixFmt::RGB8);

pub fn force_pixel_format(self, pixfmt: PixFmt) -> Option<DynamicFrame<'a>>

Forces the image data to be interpreted as a different pixel format without converting the data.

Use this method with caution - the resulting image may not be valid if the buffer size is incompatible with the new pixel format requirements.

Parameters

• pixfmt - The new pixel format to interpret the data as

Returns

• Some(DynamicFrame) if the buffer size is compatible with the new format
• None if the buffer is too small for the new format

Examples

// Create a Mono8 image
let data = vec![128u8; 1000];
let frame = DynamicFrame::from_buf(100, 10, 100, data, PixFmt::Mono8).unwrap();

// Force it to be interpreted as a different format (if buffer size allows)
let forced_frame = frame.force_pixel_format(PixFmt::Mono8);
assert!(forced_frame.is_some());

pub fn roi( &'a self, left: u32, top: u32, width: u32, height: u32, ) -> Option<DynamicFrame<'a>>

Returns a new DynamicFrame representing a region of interest (ROI) within the image.

The ROI is defined by the specified left, top, width, and height parameters. If the specified ROI is out of bounds or the buffer is too small, this method returns None.

Parameters

• left - The left coordinate of the ROI in pixels
• top - The top coordinate of the ROI in pixels
• width - The width of the ROI in pixels
• height - The height of the ROI in pixels

Returns

• Some(DynamicFrame) if the ROI is valid and the buffer is large enough
• None if the ROI is out of bounds or the buffer is too small

Trait Implementations

impl Debug for DynamicFrame<'_>

fn fmt(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Formats the value using the given formatter.

impl Stride for DynamicFrame<'_>

fn stride(&self) -> usize

Returns the stride (bytes per row) of the image.

The stride represents the number of bytes from the start of one row to the start of the next row. This may be larger than the minimum required by the pixel format due to alignment requirements.

Examples

let data = vec![0u8; 1000];
let frame = DynamicFrame::from_buf(10, 10, 100, data, PixFmt::Mono8).unwrap();
assert_eq!(frame.stride(), 100);