Files
craft-libs/crates/raster-codecs/src/lib.rs
T
Dylan M. Taylor 5c0b0a3632 Deduplicate raster codecs via shared image implementations (successor to #1198) (#1331)
* Share small raster format implementations

(cherry picked from commit 7aedc1de73)

* Preserve raster facade encode contracts

(cherry picked from commit 2db7c82705)

* Allow alpha in IFF compatibility encoder

(cherry picked from commit 80b55dee5a)

* Test shared raster facade contracts and refresh lockfile
2026-11-14 20:46:22 -05:00

269 lines
11 KiB
Rust

//! Small raster image formats, one module each, decoding untrusted bytes into one flat
//! [`Image`] and (where the format is written) encoding it back.
//!
//! | Module | Format | Read | Write |
//! |---|---|---|---|
//! | [`dds`] | DirectDraw Surface: uncompressed masks, BC1-BC3 (DXT1/3/5), the DX10 header | yes | yes |
//! | [`dicom`] | DICOM Part 10, uncompressed native pixel data | yes | no |
//! | [`fits`] | FITS primary and image-extension HDUs | yes | yes |
//! | [`iff`] | IFF ILBM (palette or 24-bit planes, masks) and PBM | yes | yes (24-plane ILBM) |
//! | [`pcx`] | ZSoft PCX, palettes and 24-bit RGB | yes | no |
//! | [`pnm`] | Netpbm PBM/PGM/PPM (plain and raw), PAM, PFM | yes | yes |
//! | [`xpm`] | X PixMap, XPM3 and XPM2 | yes | no |
//!
//! Every decoder takes [`Limits`] and checks the declared size against them before it
//! allocates. Nothing here panics on malformed input. Encoders take an image already in a
//! layout and sample type the format stores and refuse any other: choosing and converting is
//! the caller's business.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
mod bridge;
/// Common bounded decoding and PNG/JPEG encoding for common image formats.
pub mod common;
pub mod dds;
pub mod dicom;
pub mod fits;
pub mod iff;
pub mod pcx;
pub mod pnm;
pub mod xpm;
/// What went wrong. `format` is the format's short name (`"DDS"`, `"FITS"`, ...).
#[derive(Debug, thiserror::Error)]
pub enum CodecError {
#[error("{format}: {reason}")]
Unsupported { format: &'static str, reason: String },
#[error("{format}: malformed data: {message}")]
Malformed { format: &'static str, message: String },
#[error("limit exceeded: {0}")]
LimitExceeded(String),
#[error("{format}: encode failed: {message}")]
Encode { format: &'static str, message: String },
#[error("invalid image: {0}")]
InvalidImage(String),
}
impl CodecError {
pub(crate) fn malformed(format: &'static str, e: impl std::fmt::Display) -> Self {
CodecError::Malformed { format, message: e.to_string() }
}
pub(crate) fn encode(format: &'static str, e: impl std::fmt::Display) -> Self {
CodecError::Encode { format, message: e.to_string() }
}
pub(crate) fn unsupported(format: &'static str, reason: impl Into<String>) -> Self {
CodecError::Unsupported { format, reason: reason.into() }
}
}
/// Channel layout of an [`Image`]. Alpha, when present, is the last channel and is straight
/// (not premultiplied).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum ChannelLayout {
Gray,
GrayA,
Rgb,
Rgba,
/// Ink amounts, `0 = no ink`, `max = full ink`.
Cmyk,
CmykA,
}
impl ChannelLayout {
/// Total number of channels including alpha.
pub const fn channels(self) -> usize {
match self {
ChannelLayout::Gray => 1,
ChannelLayout::GrayA => 2,
ChannelLayout::Rgb => 3,
ChannelLayout::Rgba | ChannelLayout::Cmyk => 4,
ChannelLayout::CmykA => 5,
}
}
}
/// Storage type of one sample.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum SampleType {
U8,
U16,
F32,
}
impl SampleType {
pub const fn bytes(self) -> usize {
match self {
SampleType::U8 => 1,
SampleType::U16 => 2,
SampleType::F32 => 4,
}
}
}
/// What a decoder noticed about a file it nevertheless decoded.
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum DecodeWarning {
/// The file holds more images (planes, pages) than the one returned; `total` when known.
MorePages { total: Option<u32> },
}
/// A flat raster image: samples interleaved (`RGBARGBA...`), row-major, top to bottom, in
/// native endianness. Integer samples are unsigned and span `0..=max`; float samples are
/// nominally `0..=1` and may exceed it.
#[derive(Debug, Clone, PartialEq)]
pub struct Image {
width: u32,
height: u32,
layout: ChannelLayout,
sample: SampleType,
data: Vec<u8>,
/// Resolution in pixels per inch (x, y), when the file states one.
pub dpi: Option<(f32, f32)>,
/// Key/value text the file carries (FITS header cards).
pub text: Vec<(String, String)>,
/// Empty for a complete, single image and for images built in memory. Encoders ignore it.
pub warnings: Vec<DecodeWarning>,
}
impl Image {
/// Wraps raw interleaved, native-endian bytes; the length must match the size exactly.
pub fn from_raw(width: u32, height: u32, layout: ChannelLayout, sample: SampleType, data: Vec<u8>) -> Result<Self, CodecError> {
let expected = (width as usize)
.checked_mul(height as usize)
.and_then(|n| n.checked_mul(layout.channels()))
.and_then(|n| n.checked_mul(sample.bytes()))
.ok_or_else(|| CodecError::InvalidImage("image size overflows usize".into()))?;
if data.len() != expected {
return Err(CodecError::InvalidImage(format!(
"buffer has {} bytes, expected {expected} for {width}x{height} {layout:?} {sample:?}",
data.len()
)));
}
Ok(Image { width, height, layout, sample, data, dpi: None, text: Vec::new(), warnings: Vec::new() })
}
pub fn from_u8(width: u32, height: u32, layout: ChannelLayout, data: Vec<u8>) -> Result<Self, CodecError> {
Self::from_raw(width, height, layout, SampleType::U8, data)
}
pub fn from_u16(width: u32, height: u32, layout: ChannelLayout, data: &[u16]) -> Result<Self, CodecError> {
Self::from_raw(width, height, layout, SampleType::U16, data.iter().flat_map(|v| v.to_ne_bytes()).collect())
}
pub fn from_f32(width: u32, height: u32, layout: ChannelLayout, data: &[f32]) -> Result<Self, CodecError> {
Self::from_raw(width, height, layout, SampleType::F32, data.iter().flat_map(|v| v.to_ne_bytes()).collect())
}
pub fn width(&self) -> u32 {
self.width
}
pub fn height(&self) -> u32 {
self.height
}
pub fn dimensions(&self) -> (u32, u32) {
(self.width, self.height)
}
pub fn layout(&self) -> ChannelLayout {
self.layout
}
pub fn sample_type(&self) -> SampleType {
self.sample
}
/// Raw interleaved native-endian bytes.
pub fn data(&self) -> &[u8] {
&self.data
}
pub fn into_data(self) -> Vec<u8> {
self.data
}
/// The samples as `u16` (only when the sample type is `U16`).
pub fn to_u16_samples(&self) -> Option<Vec<u16>> {
(self.sample == SampleType::U16).then(|| self.data.as_chunks::<2>().0.iter().map(|c| u16::from_ne_bytes(*c)).collect())
}
/// The samples as `f32` (only when the sample type is `F32`).
pub fn to_f32_samples(&self) -> Option<Vec<f32>> {
(self.sample == SampleType::F32).then(|| self.data.as_chunks::<4>().0.iter().map(|c| f32::from_ne_bytes(*c)).collect())
}
}
/// Bounds on what a decoder will produce.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Limits {
pub max_width: u32,
pub max_height: u32,
/// Maximum `width * height`.
pub max_pixels: u64,
/// Maximum bytes for the decoded pixel buffer. Not a cap on total memory.
pub max_alloc: u64,
}
impl Default for Limits {
/// 2^18 pixels a side, 2^30 pixels, and 8 GiB of pixels on 64-bit targets (1 GiB on 32-bit).
fn default() -> Self {
let max_alloc = if cfg!(target_pointer_width = "64") { 8 << 30 } else { 1 << 30 };
Limits { max_width: 1 << 18, max_height: 1 << 18, max_pixels: 1 << 30, max_alloc }
}
}
impl Limits {
/// Effectively unlimited (still bounded by `usize` overflow checks).
pub fn none() -> Self {
Limits { max_width: u32::MAX, max_height: u32::MAX, max_pixels: u64::MAX, max_alloc: u64::MAX }
}
/// Validates declared dimensions for an output buffer of the given layout and sample type.
pub fn check(&self, width: u32, height: u32, layout: ChannelLayout, sample: SampleType) -> Result<(), CodecError> {
let layout = match layout {
ChannelLayout::Gray => craft_image_codecs::ChannelLayout::Gray,
ChannelLayout::GrayA => craft_image_codecs::ChannelLayout::GrayA,
ChannelLayout::Rgb => craft_image_codecs::ChannelLayout::Rgb,
ChannelLayout::Rgba => craft_image_codecs::ChannelLayout::Rgba,
ChannelLayout::Cmyk => craft_image_codecs::ChannelLayout::Cmyk,
ChannelLayout::CmykA => craft_image_codecs::ChannelLayout::CmykA,
};
let sample = match sample {
SampleType::U8 => craft_image_codecs::SampleType::U8,
SampleType::U16 => craft_image_codecs::SampleType::U16,
SampleType::F32 => craft_image_codecs::SampleType::F32,
};
craft_image_codecs::Limits::new(self.max_width, self.max_height, self.max_pixels, self.max_alloc)
.check(width, height, layout, sample)
.map_err(crate::bridge::from_shared_error)
}
/// Decompression-bomb guard for formats that compress: refuses a file too small to hold
/// `declared_bytes` of stored image data when the compression never beats `max_ratio`:1.
/// Called before the output buffer is allocated. 1 MiB of slack leaves tiny images alone.
pub fn check_plausible(declared_bytes: u64, file_len: usize, max_ratio: u64) -> Result<(), CodecError> {
craft_image_codecs::Limits::check_plausible(declared_bytes, file_len, max_ratio).map_err(crate::bridge::from_shared_error)
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn limits_refuse_each_bound() {
let l = Limits { max_width: 10, max_height: 10, max_pixels: 50, max_alloc: 100 };
let check = |w, h| l.check(w, h, ChannelLayout::Rgb, SampleType::U8);
assert!(check(5, 5).is_ok());
assert!(matches!(check(0, 5), Err(CodecError::InvalidImage(_))));
assert!(matches!(check(11, 1), Err(CodecError::LimitExceeded(_))), "width");
assert!(matches!(check(1, 11), Err(CodecError::LimitExceeded(_))), "height");
assert!(matches!(check(10, 6), Err(CodecError::LimitExceeded(_))), "pixels");
assert!(matches!(check(7, 5), Err(CodecError::LimitExceeded(_))), "bytes");
assert!(matches!(Limits::check_plausible((1 << 20) + 129, 1, 128), Err(CodecError::LimitExceeded(_))));
assert!(Limits::check_plausible((1 << 20) + 128, 1, 128).is_ok());
}
#[test]
fn image_buffer_must_match_its_size() {
assert!(Image::from_u8(2, 2, ChannelLayout::Rgb, vec![0; 12]).is_ok());
assert!(matches!(Image::from_u8(2, 2, ChannelLayout::Rgb, vec![0; 11]), Err(CodecError::InvalidImage(_))));
assert_eq!(Image::from_u16(1, 1, ChannelLayout::Gray, &[513]).ok().and_then(|i| i.to_u16_samples()), Some(vec![513]));
}
}