moqros 0.2.0

Stream ROS 2 sensor_msgs/Image topics over Media over QUIC
Documentation
//! ROS-independent raw image representation.

use std::fmt;
use std::str::FromStr;
use std::time::Duration;

use bytes::Bytes;

use crate::Error;

/// Pixel layouts understood by moqros.
///
/// The names mirror the `encoding` strings of `sensor_msgs/Image`
/// (see `sensor_msgs/image_encodings.hpp`).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum PixelFormat {
	/// `rgb8`: 3 bytes per pixel, R G B.
	Rgb8,
	/// `bgr8`: 3 bytes per pixel, B G R.
	Bgr8,
	/// `rgba8`: 4 bytes per pixel, R G B A.
	Rgba8,
	/// `bgra8`: 4 bytes per pixel, B G R A.
	Bgra8,
	/// `mono8`: 1 byte per pixel, luma only.
	Mono8,
	/// `yuv422`: packed 4:2:2, byte order U Y0 V Y1 (a.k.a. UYVY).
	Uyvy,
	/// `yuv422_yuy2`: packed 4:2:2, byte order Y0 U Y1 V (a.k.a. YUYV).
	Yuyv,
}

impl PixelFormat {
	/// The `sensor_msgs/Image` encoding string.
	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",
		}
	}

	/// Average number of bytes used by one pixel in a row.
	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())
	}
}

/// An uncompressed image, equivalent to the payload of a `sensor_msgs/Image`.
#[derive(Clone, PartialEq, Eq)]
pub struct Image {
	pub width: u32,
	pub height: u32,
	pub format: PixelFormat,
	/// Length of one row in bytes, including any padding.
	pub step: u32,
	pub data: Bytes,
	/// Capture time; for ROS images this is `header.stamp` since the epoch.
	pub timestamp: Duration,
}

impl Image {
	/// Create a tightly packed image, validating the buffer length.
	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)
	}

	/// Create an image whose rows are `step` bytes apart, validating the buffer length.
	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)
	}

	/// Check that `step` and `data` are large enough for the declared geometry.
	pub 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(())
	}

	/// Borrow row `y` without trailing padding.
	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_rechecks_public_fields() {
		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}");
	}
}