use std::fmt;
use std::str::FromStr;
use std::time::Duration;
use bytes::Bytes;
use crate::Error;
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[non_exhaustive]
pub enum PixelFormat {
Rgb8,
Bgr8,
Rgba8,
Bgra8,
Mono8,
Uyvy,
Yuyv,
}
impl PixelFormat {
pub const fn as_ros_encoding(self) -> &'static str {
match self {
Self::Rgb8 => "rgb8",
Self::Bgr8 => "bgr8",
Self::Rgba8 => "rgba8",
Self::Bgra8 => "bgra8",
Self::Mono8 => "mono8",
Self::Uyvy => "yuv422",
Self::Yuyv => "yuv422_yuy2",
}
}
pub const fn bytes_per_pixel(self) -> usize {
match self {
Self::Rgb8 | Self::Bgr8 => 3,
Self::Rgba8 | Self::Bgra8 => 4,
Self::Mono8 => 1,
Self::Uyvy | Self::Yuyv => 2,
}
}
}
impl FromStr for PixelFormat {
type Err = Error;
fn from_str(s: &str) -> Result<Self, Self::Err> {
Ok(match s {
"rgb8" | "8UC3" => Self::Rgb8,
"bgr8" => Self::Bgr8,
"rgba8" | "8UC4" => Self::Rgba8,
"bgra8" => Self::Bgra8,
"mono8" | "8UC1" => Self::Mono8,
"yuv422" | "uyvy" => Self::Uyvy,
"yuv422_yuy2" | "yuyv" => Self::Yuyv,
other => return Err(Error::UnsupportedEncoding(other.to_string())),
})
}
}
impl fmt::Display for PixelFormat {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(self.as_ros_encoding())
}
}
#[derive(Clone, PartialEq, Eq)]
pub struct Image {
pub(crate) width: u32,
pub(crate) height: u32,
pub(crate) format: PixelFormat,
pub(crate) step: u32,
pub(crate) data: Bytes,
pub(crate) timestamp: Duration,
}
impl Image {
#[expect(clippy::cast_possible_truncation, reason = "at most 4 bytes per pixel")]
pub fn new(
width: u32,
height: u32,
format: PixelFormat,
data: impl Into<Bytes>,
timestamp: Duration,
) -> Result<Self, Error> {
let step = width
.checked_mul(format.bytes_per_pixel() as u32)
.ok_or_else(|| Error::InvalidImage(format!("{width}px wide {format} rows overflow u32")))?;
Self::with_step(width, height, format, step, data, timestamp)
}
pub fn with_step(
width: u32,
height: u32,
format: PixelFormat,
step: u32,
data: impl Into<Bytes>,
timestamp: Duration,
) -> Result<Self, Error> {
let image = Self {
width,
height,
format,
step,
data: data.into(),
timestamp,
};
image.validate()?;
Ok(image)
}
pub fn width(&self) -> u32 {
self.width
}
pub fn height(&self) -> u32 {
self.height
}
pub fn format(&self) -> PixelFormat {
self.format
}
pub fn step(&self) -> u32 {
self.step
}
pub fn data(&self) -> &Bytes {
&self.data
}
pub fn into_data(self) -> Bytes {
self.data
}
pub fn timestamp(&self) -> Duration {
self.timestamp
}
pub fn with_timestamp(mut self, timestamp: Duration) -> Self {
self.timestamp = timestamp;
self
}
pub(crate) fn validate(&self) -> Result<(), Error> {
let row = (self.width as usize).checked_mul(self.format.bytes_per_pixel());
let step = self.step as usize;
let needed = step.checked_mul(self.height as usize);
let (Some(row), Some(needed)) = (row, needed) else {
return Err(Error::InvalidImage(format!(
"{}x{} {} with step {step} overflows usize",
self.width, self.height, self.format
)));
};
if step < row || self.data.len() < needed {
return Err(Error::InvalidImage(format!(
"{}x{} {} needs step >= {row} and {needed} bytes, got step {step} and {} bytes",
self.width,
self.height,
self.format,
self.data.len()
)));
}
Ok(())
}
pub(crate) fn row(&self, y: usize) -> &[u8] {
let start = y * self.step as usize;
&self.data[start..start + self.width as usize * self.format.bytes_per_pixel()]
}
}
impl fmt::Debug for Image {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.debug_struct("Image")
.field("width", &self.width)
.field("height", &self.height)
.field("format", &self.format)
.field("step", &self.step)
.field("data", &format_args!("{} bytes", self.data.len()))
.field("timestamp", &self.timestamp)
.finish()
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parses_ros_encodings() {
for format in [
PixelFormat::Rgb8,
PixelFormat::Bgr8,
PixelFormat::Rgba8,
PixelFormat::Bgra8,
PixelFormat::Mono8,
PixelFormat::Uyvy,
PixelFormat::Yuyv,
] {
assert_eq!(format.as_ros_encoding().parse::<PixelFormat>().unwrap(), format);
}
assert!("32FC1".parse::<PixelFormat>().is_err());
}
#[test]
fn rejects_short_buffers() {
assert!(Image::new(4, 4, PixelFormat::Rgb8, vec![0u8; 47], Duration::ZERO).is_err());
assert!(Image::new(4, 4, PixelFormat::Rgb8, vec![0u8; 48], Duration::ZERO).is_ok());
assert!(Image::with_step(4, 4, PixelFormat::Rgb8, 11, vec![0u8; 64], Duration::ZERO).is_err());
}
#[test]
fn rejects_widths_whose_rows_overflow() {
let image = Image::new(u32::MAX / 2, 1, PixelFormat::Rgba8, vec![0u8; 4], Duration::ZERO);
assert!(matches!(image, Err(Error::InvalidImage(_))));
}
#[test]
fn parses_encoding_aliases() {
for (encoding, format) in [
("8UC1", PixelFormat::Mono8),
("8UC3", PixelFormat::Rgb8),
("8UC4", PixelFormat::Rgba8),
("uyvy", PixelFormat::Uyvy),
("yuyv", PixelFormat::Yuyv),
] {
assert_eq!(encoding.parse::<PixelFormat>().unwrap(), format, "{encoding}");
}
assert!(matches!("RGB8".parse::<PixelFormat>(), Err(Error::UnsupportedEncoding(e)) if e == "RGB8"));
}
#[test]
fn displays_ros_encoding() {
assert_eq!(PixelFormat::Uyvy.to_string(), "yuv422");
assert_eq!(PixelFormat::Yuyv.to_string(), "yuv422_yuy2");
}
#[test]
fn new_packs_rows_tightly() {
for (format, step) in [
(PixelFormat::Mono8, 5),
(PixelFormat::Yuyv, 10),
(PixelFormat::Bgr8, 15),
(PixelFormat::Rgba8, 20),
] {
let image = Image::new(5, 2, format, vec![0u8; step * 2], Duration::ZERO).unwrap();
assert_eq!(image.step as usize, step, "{format}");
}
}
#[test]
fn accepts_longer_buffers_and_padded_rows() {
assert!(Image::new(2, 2, PixelFormat::Mono8, vec![0u8; 5], Duration::ZERO).is_ok());
let image = Image::with_step(2, 2, PixelFormat::Rgb8, 8, (0..16).collect::<Vec<u8>>(), Duration::ZERO).unwrap();
assert_eq!(image.row(0), &[0, 1, 2, 3, 4, 5]);
assert_eq!(image.row(1), &[8, 9, 10, 11, 12, 13]);
}
#[test]
fn validate_checks_the_geometry() {
let mut image = Image::new(4, 4, PixelFormat::Rgb8, vec![0u8; 48], Duration::ZERO).unwrap();
image.height = 5;
assert!(matches!(image.validate(), Err(Error::InvalidImage(_))));
image.height = 4;
image.step = 11;
assert!(image.validate().is_err());
}
#[test]
fn debug_omits_pixel_data() {
let image = Image::new(2, 2, PixelFormat::Mono8, vec![7u8; 4], Duration::from_millis(5)).unwrap();
let debug = format!("{image:?}");
assert!(debug.contains("4 bytes"), "{debug}");
assert!(!debug.contains("[7"), "{debug}");
}
}