Merge remote-tracking branch 'origin/main' into fix/avif-exif-hlg

This commit is contained in:
Dylan M. Taylor committed 2026-11-15 02:03:26 +00:00
commit 543786812c
44 files changed
+2597 -4562

No files matched your search

Generated
+35 -1
View File
@@ -222,6 +222,16 @@ version = "1.0.104"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "330a5ed07fa54e4702c9d6c4174f74427fc0ef6e214bbd677ae50a5099946470"
[[package]]
name = "aotuv_lancer_vorbis_sys"
version = "0.1.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "5bc4fd1a61860d2f1198b60bedd30910eaffa978f1ee6214dfb24ac70d589225"
dependencies = [
"cc",
"ogg_next_sys",
]
[[package]]
name = "arbitrary"
version = "1.5.0"
@@ -1349,6 +1359,7 @@ dependencies = [
"serde_json",
"symphonia",
"thiserror 2.0.21",
"vorbis_rs",
]
[[package]]
@@ -2419,7 +2430,6 @@ dependencies = [
"base64 0.23.1",
"craft-image-codecs",
"image",
"rayon",
"thiserror 2.0.21",
]
@@ -2721,6 +2731,7 @@ version = "0.1.0"
dependencies = [
"craft-media",
"craft-media-testkit",
"rav1e",
"rayon",
"thiserror 2.0.21",
]
@@ -6610,6 +6621,15 @@ dependencies = [
"phf 0.11.3",
]
[[package]]
name = "ogg_next_sys"
version = "0.1.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "ed2d7a48e247c2bb07e633aefb65a38648ea58c7eedd4e4408a5861721ab049b"
dependencies = [
"cc",
]
[[package]]
name = "once_cell"
version = "1.21.4"
@@ -10371,6 +10391,20 @@ version = "0.9.5"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
[[package]]
name = "vorbis_rs"
version = "0.5.6"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "49c5da94d280f7a27e8c937e9b73df2da3e23a2583f48471fd8fb4c72f9c1933"
dependencies = [
"aotuv_lancer_vorbis_sys",
"errno",
"getrandom 0.4.3",
"ogg_next_sys",
"thiserror 2.0.21",
"tinyvec",
]
[[package]]
name = "wait-timeout"
version = "0.2.1"
+6 -1
View File
@@ -24,13 +24,15 @@ decode-native = ["aac-decode", "alac-decode", "opus-decode", "ac3-decode", "mpa-
symphonia = ["decode-native", "dep:symphonia"]
# Every encoder: the lossless file writers and the AAC, ALAC, AC-3/E-AC-3, MP3 and Opus encoders.
# All but Opus are also file formats of `encode` and `FileEncoder`.
encode = ["lossless-encode", "aac-encode", "alac-encode", "ac3-encode", "eac3-encode", "mp3-encode", "opus-encode"]
encode = ["lossless-encode", "aac-encode", "alac-encode", "ac3-encode", "eac3-encode", "mp3-encode", "opus-encode", "vorbis-encode"]
# Encode WAV/BWF/RF64, AIFF/AIFF-C and FLAC files.
lossless-encode = ["pcm-encode", "flac-encode"]
# Encode WAV/BWF/RF64 and AIFF/AIFF-C files.
pcm-encode = []
# Encode FLAC files.
flac-encode = ["craft-media/bitstream"]
# Encode Ogg Vorbis files (desktop only: builds the reference libvorbis from its C sources).
vorbis-encode = ["dep:vorbis_rs"]
# Codec modules on their own, for packet-level use.
aac-decode = ["craft-media/bitstream"]
# The AAC encoder (`aac::Encoder`), and AAC in M4A through `encode` and `FileEncoder`.
@@ -65,6 +67,9 @@ rayon = { workspace = true, optional = true }
# symphonia keeps its AAC decoder for AAC in CAF, a container craft-media does not read.
symphonia = { version = "0.6.1", optional = true, default-features = false, features = ["mp3", "flac", "vorbis", "ogg", "wav", "pcm", "aiff", "isomp4", "aac", "alac", "adpcm", "caf", "mkv"] }
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
vorbis_rs = { version = "0.5", optional = true }
[dev-dependencies]
craft-media-testkit = { workspace = true }
proptest = { workspace = true }
+34 -10
View File
@@ -62,9 +62,12 @@ mod wav;
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
feature = "eac3-encode",
feature = "vorbis-encode"
))]
mod write;
#[cfg(feature = "vorbis-encode")]
pub use write::{OGG_BITRATES, encode_ogg};
/// The FLAC packet encoder (RFC 9639), for a caller that muxes FLAC itself (into MP4, Matroska or
/// its own `.flac` writer): planar integer samples in, frames out, and the STREAMINFO to patch in
@@ -107,8 +110,6 @@ pub use read::{
pub use read::{RawPcm, aiff_pcm, wav_pcm};
#[cfg(any(feature = "aac-decode", feature = "alac-decode", feature = "opus-decode", feature = "ac3-decode", feature = "mpa-decode"))]
pub use track::{LOOKAHEAD_PACKETS, TrackDecoder};
#[cfg(feature = "pcm-encode")]
pub use write::wav_float_header;
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
@@ -118,7 +119,20 @@ pub use write::wav_float_header;
feature = "ac3-encode",
feature = "eac3-encode"
))]
pub use write::{ENCODE_EXTENSIONS, FileEncoder, encode, encode_format_for};
pub use write::FileEncoder;
#[cfg(feature = "pcm-encode")]
pub use write::wav_float_header;
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode",
feature = "vorbis-encode"
))]
pub use write::{ENCODE_EXTENSIONS, encode, encode_format_for};
#[cfg(feature = "pcm-encode")]
pub use write::{pcm_aiff_file, pcm_aiff_header, pcm_wav_file, pcm_wav_header};
@@ -256,6 +270,8 @@ pub enum EncodeFormat {
Ac3,
/// An E-AC-3 stream: up to 7.1 at 32, 44.1 or 48 kHz.
Eac3,
/// Ogg Vorbis, whole-buffer encoding only.
Ogg,
}
impl EncodeFormat {
@@ -270,6 +286,7 @@ impl EncodeFormat {
EncodeFormat::Mp3,
EncodeFormat::Ac3,
EncodeFormat::Eac3,
EncodeFormat::Ogg,
];
/// The extension a new file of this format gets, lower case and without the dot: `"wav"`,
@@ -284,6 +301,7 @@ impl EncodeFormat {
EncodeFormat::Mp3 => "mp3",
EncodeFormat::Ac3 => "ac3",
EncodeFormat::Eac3 => "eac3",
EncodeFormat::Ogg => "ogg",
}
}
@@ -297,6 +315,7 @@ impl EncodeFormat {
EncodeFormat::Mp3 => "audio/mpeg",
EncodeFormat::Ac3 => "audio/ac3",
EncodeFormat::Eac3 => "audio/eac3",
EncodeFormat::Ogg => "audio/ogg",
}
}
@@ -309,6 +328,7 @@ impl EncodeFormat {
EncodeFormat::Aac | EncodeFormat::Alac => Container::Mp4,
EncodeFormat::Mp3 => Container::MpegAudio,
EncodeFormat::Ac3 | EncodeFormat::Eac3 => Container::Ac3,
EncodeFormat::Ogg => Container::Ogg,
}
}
@@ -322,6 +342,7 @@ impl EncodeFormat {
EncodeFormat::Mp3 => CodecId::Mp3,
EncodeFormat::Ac3 => CodecId::Ac3,
EncodeFormat::Eac3 => CodecId::Eac3,
EncodeFormat::Ogg => CodecId::Vorbis,
}
}
@@ -335,10 +356,11 @@ impl EncodeFormat {
EncodeFormat::Mp3 => "mp3-encode",
EncodeFormat::Ac3 => "ac3-encode",
EncodeFormat::Eac3 => "eac3-encode",
EncodeFormat::Ogg => "vorbis-encode",
}
}
/// Whether [`encode`] and [`FileEncoder`] write this format in this build (its
/// Whether [`encode`] writes this format in this build (its
/// [`feature`](Self::feature) is on): what to filter [`EncodeFormat::ALL`] by for a menu.
pub fn is_built(self) -> bool {
match self {
@@ -349,6 +371,7 @@ impl EncodeFormat {
EncodeFormat::Mp3 => cfg!(feature = "mp3-encode"),
EncodeFormat::Ac3 => cfg!(feature = "ac3-encode"),
EncodeFormat::Eac3 => cfg!(feature = "eac3-encode"),
EncodeFormat::Ogg => cfg!(all(feature = "vorbis-encode", not(target_arch = "wasm32"))),
}
}
@@ -359,7 +382,7 @@ impl EncodeFormat {
EncodeFormat::Aac => Some(&[7350, 8000, 11_025, 12_000, 16_000, 22_050, 24_000, 32_000, 44_100, 48_000, 64_000, 88_200, 96_000]),
EncodeFormat::Mp3 => Some(&[16_000, 22_050, 24_000, 32_000, 44_100, 48_000]),
EncodeFormat::Ac3 | EncodeFormat::Eac3 => Some(&[32_000, 44_100, 48_000]),
EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac | EncodeFormat::Alac => None,
EncodeFormat::Wav | EncodeFormat::Aiff | EncodeFormat::Flac | EncodeFormat::Alac | EncodeFormat::Ogg => None,
}
}
@@ -371,7 +394,7 @@ impl EncodeFormat {
EncodeFormat::Wav | EncodeFormat::Aiff => 32_767,
EncodeFormat::Flac | EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Eac3 => 8,
EncodeFormat::Ac3 => 6,
EncodeFormat::Mp3 => 2,
EncodeFormat::Mp3 | EncodeFormat::Ogg => 2,
}
}
@@ -385,7 +408,7 @@ impl EncodeFormat {
EncodeFormat::Aac => &[&[0x4], &[0x3], &[0x7], &[0x107], &[0x607], &[0x60F], &[0x70F], &[0xFF]],
// Apple's layout tags for 1–8 channels, surrounds as back speakers.
EncodeFormat::Alac => &[&[0x4], &[0x3], &[0x7], &[0x107], &[0x37], &[0x3F], &[0x13F], &[0xFF]],
EncodeFormat::Mp3 => &[&[0x4], &[0x3]],
EncodeFormat::Mp3 | EncodeFormat::Ogg => &[&[0x4], &[0x3]],
// The coding modes 1/0 to 3/2 with and without an LFE, by channel count.
EncodeFormat::Ac3 => &[&[0x4], &[0x3, 0xC], &[0x7, 0x103, 0xB], &[0x107, 0x603, 0xF, 0x10B], &[0x607, 0x10F, 0x60B], &[0x60F]],
// The same, and 7.1 with backs and sides.
@@ -436,7 +459,7 @@ impl EncodeFormat {
/// Whether the format loses audio: AAC, MP3, AC-3 and E-AC-3. These take
/// [`EncodeOptions::rate_control`] and ignore the bit depth and dither.
pub fn is_lossy(self) -> bool {
matches!(self, EncodeFormat::Aac | EncodeFormat::Mp3 | EncodeFormat::Ac3 | EncodeFormat::Eac3)
matches!(self, EncodeFormat::Aac | EncodeFormat::Mp3 | EncodeFormat::Ac3 | EncodeFormat::Eac3 | EncodeFormat::Ogg)
}
}
@@ -449,7 +472,8 @@ pub enum RateControl {
/// set of rates (MP3, AC-3) uses the highest one not above it; a rate outside what the
/// stream can carry is moved to the nearest one inside. AAC is written at 6 kbit/s or a
/// quarter of the sample rate per channel at least: from about half of that down its encoder
/// codes silence.
/// codes silence. Vorbis treats this as a VBR target (64–500 kbit/s), falling back to
/// a quality preset when that target is unsupported; it does not promise a constant bitrate.
Bitrate(u32),
/// A constant quality from 0.0 (smallest) to 1.0 (best), at whatever bit rate each frame
/// needs. AAC only; values outside the range are clamped, and NaN is an error.
+108 -5
View File
@@ -9,6 +9,10 @@ mod coded;
#[cfg(feature = "flac-encode")]
pub(crate) mod flac;
mod pcm;
#[cfg(feature = "vorbis-encode")]
mod vorbis;
#[cfg(feature = "vorbis-encode")]
pub use vorbis::{OGG_BITRATES, encode as encode_ogg};
#[cfg(feature = "pcm-encode")]
mod raw;
#[cfg(feature = "pcm-encode")]
@@ -17,6 +21,15 @@ mod wav;
use crate::{AudioBuffer, AudioError, ChannelLayout, EncodeFormat, EncodeOptions, Result};
#[cfg(feature = "pcm-encode")]
pub use raw::{pcm_aiff_file, pcm_aiff_header, pcm_wav_file, pcm_wav_header};
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
))]
use std::io::{Seek, Write};
/// Encode `buf` as the file `opts.format` names. Integer depths clamp samples to [-1, 1]; float
@@ -51,6 +64,18 @@ pub fn encode(buf: &AudioBuffer, opts: &EncodeOptions) -> Result<Vec<u8>> {
EncodeFormat::Flac => flac::encode(buf, opts.bit_depth, opts.dither, mask),
#[cfg(any(feature = "aac-encode", feature = "alac-encode", feature = "mp3-encode", feature = "ac3-encode", feature = "eac3-encode"))]
EncodeFormat::Aac | EncodeFormat::Alac | EncodeFormat::Mp3 | EncodeFormat::Ac3 | EncodeFormat::Eac3 => coded::encode(buf, opts),
#[cfg(feature = "vorbis-encode")]
EncodeFormat::Ogg => {
if opts.layout.is_some_and(|layout| !EncodeFormat::Ogg.supports_layout(&layout)) {
return Err(AudioError::Unsupported("Vorbis requires a mono or stereo speaker layout".into()));
}
let kbps = match opts.rate_control {
None => 192,
Some(crate::RateControl::Bitrate(bps)) => bps / 1000,
Some(crate::RateControl::Quality(_)) => return Err(AudioError::Unsupported("Ogg export takes a target bitrate".into())),
};
vorbis::encode(buf, kbps)
}
#[allow(unreachable_patterns)]
f => Err(AudioError::Unsupported(format!("writing {f:?}"))),
}
@@ -62,8 +87,8 @@ fn check_built(format: EncodeFormat) -> Result<()> {
}
/// Every extension [`ENCODE_EXTENSIONS`] can list, and how many of them the features built give.
const fn extensions() -> ([&'static str; 12], usize) {
let mut all = [""; 12];
const fn extensions() -> ([&'static str; 13], usize) {
let mut all = [""; 13];
let mut n = 0;
macro_rules! add {
($built:expr, $($extension:literal),+) => {
@@ -81,10 +106,11 @@ const fn extensions() -> ([&'static str; 12], usize) {
add!(cfg!(feature = "mp3-encode"), "mp3");
add!(cfg!(feature = "ac3-encode"), "ac3");
add!(cfg!(feature = "eac3-encode"), "eac3", "ec3");
add!(cfg!(all(feature = "vorbis-encode", not(target_arch = "wasm32"))), "ogg");
(all, n)
}
const EXTENSIONS: ([&str; 12], usize) = extensions();
const EXTENSIONS: ([&str; 13], usize) = extensions();
/// The file extensions of the formats [`encode`] can write (those whose features are on).
pub const ENCODE_EXTENSIONS: &[&str] = EXTENSIONS.0.split_at(EXTENSIONS.1).0;
@@ -99,7 +125,7 @@ pub const ENCODE_EXTENSIONS: &[&str] = EXTENSIONS.0.split_at(EXTENSIONS.1).0;
/// use craft_audio::{EncodeFormat, encode_format_for};
///
/// assert_eq!(encode_format_for(".AIFF"), Some(EncodeFormat::Aiff));
/// assert_eq!(encode_format_for("ogg"), None);
/// assert_eq!(encode_format_for("unknown"), None);
/// # }
/// ```
pub fn encode_format_for(name: &str) -> Option<EncodeFormat> {
@@ -122,6 +148,8 @@ pub fn encode_format_for(name: &str) -> Option<EncodeFormat> {
"ac3" => Some(EncodeFormat::Ac3),
#[cfg(feature = "eac3-encode")]
"eac3" | "ec3" => Some(EncodeFormat::Eac3),
#[cfg(all(feature = "vorbis-encode", not(target_arch = "wasm32")))]
"ogg" => Some(EncodeFormat::Ogg),
_ => None,
}
}
@@ -138,6 +166,15 @@ fn wav_mask(layout: &ChannelLayout, channels: usize) -> Result<u32> {
/// The error a stream encoder returns for every call after one of its writes has failed: the
/// sink may already hold a prefix of the failed block, so the encoder's counters can no longer
/// describe the bytes on the sink, and later writes or `finish` must not claim success.
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
))]
fn failed_write_error() -> AudioError {
AudioError::Encode("the stream encoder already failed on an earlier write; its output is incomplete".into())
}
@@ -163,12 +200,30 @@ fn failed_write_error() -> AudioError {
/// assert_eq!(&flac[..4], b"fLaC");
/// # }
/// ```
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
))]
pub struct FileEncoder<W: Write + Seek> {
writer: Writer<W>,
format: EncodeFormat,
channels: usize,
}
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
))]
impl<W: Write + Seek> std::fmt::Debug for FileEncoder<W> {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("FileEncoder").field("format", &self.format).finish_non_exhaustive()
@@ -177,6 +232,15 @@ impl<W: Write + Seek> std::fmt::Debug for FileEncoder<W> {
// The writers differ in size with the features built; the coded one is boxed for its encoder.
#[allow(clippy::large_enum_variant)]
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
))]
enum Writer<W: Write + Seek> {
#[cfg(feature = "pcm-encode")]
Wav(wav::Writer<W>),
@@ -188,6 +252,15 @@ enum Writer<W: Write + Seek> {
Coded(Box<coded::Writer<W>>),
}
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
))]
impl<W: Write + Seek> FileEncoder<W> {
/// Starts a file of `channels` channels at `sample_rate` at the current position of `out`.
/// `opts.layout`, when set, must have `channels` channels.
@@ -317,9 +390,39 @@ impl EncodeOptions {
/// The constant bit rate such a file would be written at ([`FileEncoder::bitrate`]), or the
/// error [`EncodeOptions::check`] returns.
pub fn bitrate(&self, sample_rate: u32, channels: u16) -> Result<Option<u32>> {
#[cfg(feature = "vorbis-encode")]
if self.format == EncodeFormat::Ogg {
// Vorbis is whole-buffer only and VBR has no constant output bitrate.
encode(&AudioBuffer::new(sample_rate, channels, 0), self)?;
return Ok(None);
}
// The encoder a file would get, on a sink that is thrown away: what it accepts and the
// rate it settles on are then the writer's by construction.
Ok(FileEncoder::new(std::io::Cursor::new(Vec::new()), self, sample_rate, channels)?.bitrate())
#[cfg(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
))]
{
Ok(FileEncoder::new(std::io::Cursor::new(Vec::new()), self, sample_rate, channels)?.bitrate())
}
#[cfg(not(any(
feature = "pcm-encode",
feature = "flac-encode",
feature = "aac-encode",
feature = "alac-encode",
feature = "mp3-encode",
feature = "ac3-encode",
feature = "eac3-encode"
)))]
{
let _ = (sample_rate, channels);
Err(AudioError::Unsupported("streaming encoders are not built".into()))
}
}
}
+130
View File
@@ -0,0 +1,130 @@
//! Ogg Vorbis encoding (RFC 5334): the reference libvorbis encoder, built from its C sources by
//! `vorbis_rs`. Stereo or mono, variable bitrate at the requested kbit/s (64–500), with a
//! fallback to a quality preset when the bitrate is not supported for the rate and channel count.
use crate::{AudioBuffer, AudioError, Result};
/// The bitrates an Ogg Vorbis export is asked for, in kbit/s.
pub const OGG_BITRATES: (u32, u32) = (64, 500);
/// The block size the encoder processes at a time: small enough that memory stays bounded
/// regardless of file length.
#[cfg(not(target_arch = "wasm32"))]
const BLOCK: usize = 4096;
#[cfg(not(target_arch = "wasm32"))]
fn encode_error(e: vorbis_rs::VorbisError) -> AudioError {
AudioError::Encode(e.to_string())
}
/// Encode `buf` as an Ogg Vorbis stream at about `kbps` (variable, as Vorbis is): stereo, or mono
/// for a mono buffer. A bitrate the encoder has no setup for at that rate and channel count falls
/// back to a quality that suits it. `Err` says why there is nothing.
#[cfg(not(target_arch = "wasm32"))]
pub fn encode(buf: &AudioBuffer, kbps: u32) -> Result<Vec<u8>> {
use std::num::{NonZeroU8, NonZeroU32};
let channels = buf.channels.len();
if !(1..=2).contains(&channels) {
return Err(AudioError::Unsupported("Ogg Vorbis export requires mono or stereo audio".into()));
}
if buf.channels.iter().any(|c| c.len() != buf.frames() || c.iter().any(|s| !s.is_finite())) {
return Err(AudioError::Encode("Vorbis samples must be finite and channels equally long".into()));
}
let (Some(rate), Some(count)) = (NonZeroU32::new(buf.sample_rate), NonZeroU8::new(channels as u8)) else {
return Err(AudioError::Encode("there is no audio to encode".into()));
};
let target = NonZeroU32::new(kbps.clamp(OGG_BITRATES.0, OGG_BITRATES.1) * 1000).unwrap_or(NonZeroU32::MIN);
let encode = |strategy: vorbis_rs::VorbisBitrateManagementStrategy| -> Result<Vec<u8>> {
let mut encoder = vorbis_rs::VorbisEncoderBuilder::new_with_serial(rate, count, Vec::new(), 0x4C43_5246)
.bitrate_management_strategy(strategy)
.build()
.map_err(encode_error)?;
let frames = buf.frames();
let mut at = 0usize;
while at < frames {
let end = (at + BLOCK).min(frames);
let block: Vec<&[f32]> = buf.channels.iter().take(channels).map(|side| side.get(at..end).unwrap_or_default()).collect();
encoder.encode_audio_block(&block).map_err(encode_error)?;
at = end;
}
encoder.finish().map_err(encode_error)
};
// Convert Rust unwinds to an error. This does not catch native crashes or aborts.
let attempt = |strategy| {
std::panic::catch_unwind(std::panic::AssertUnwindSafe(|| encode(strategy)))
.unwrap_or_else(|_| Err(AudioError::Encode("the Vorbis encoder failed".into())))
};
match attempt(vorbis_rs::VorbisBitrateManagementStrategy::Vbr { target_bitrate: target }) {
Ok(bytes) => Ok(bytes),
Err(_) => attempt(vorbis_rs::VorbisBitrateManagementStrategy::QualityVbr { target_quality: 0.6 })
.map_err(|e| AudioError::Encode(format!("the Vorbis encoder refused the audio: {e}"))),
}
}
/// Ogg Vorbis encoding is unavailable on WASM; returns an unsupported-format error.
#[cfg(target_arch = "wasm32")]
pub fn encode(_buf: &AudioBuffer, _kbps: u32) -> Result<Vec<u8>> {
Err(AudioError::Unsupported("Ogg Vorbis files are exported by the desktop app".into()))
}
#[cfg(all(test, not(target_arch = "wasm32")))]
mod tests {
#![allow(clippy::unwrap_used)]
use super::*;
#[test]
fn rejects_unsupported_or_malformed_channels_without_dropping_audio() {
for channels in [0, 3, 6] {
assert!(matches!(encode(&AudioBuffer::new(48_000, channels, 16), 192), Err(AudioError::Unsupported(_))));
}
let ragged = AudioBuffer { sample_rate: 48_000, channels: vec![vec![0.0; 16], vec![0.0; 15]] };
assert!(encode(&ragged, 192).is_err());
assert!(encode(&AudioBuffer::new(0, 1, 16), 192).is_err());
let invalid = AudioBuffer { sample_rate: 48_000, channels: vec![vec![f32::NAN]] };
assert!(encode(&invalid, 192).is_err());
}
#[test]
fn generic_and_direct_encoders_write_mono_and_stereo_ogg() {
for channels in [1, 2] {
let audio = AudioBuffer::new(48_000, channels, 512);
let opts = crate::EncodeOptions::new(crate::EncodeFormat::Ogg);
assert!(opts.check(48_000, channels).is_ok());
assert_eq!(opts.bitrate(48_000, channels).unwrap(), None);
let direct = encode(&audio, 192).unwrap();
let generic = crate::encode(&audio, &opts).unwrap();
assert!(direct.starts_with(b"OggS"));
assert_eq!(direct, generic);
#[cfg(feature = "decode")]
{
let (info, decoded) = crate::decode(&generic, Some("ogg")).unwrap();
assert_eq!(info.channels, channels);
assert_eq!(decoded.num_channels(), channels);
assert_eq!(decoded.frames(), audio.frames());
}
}
}
#[cfg(feature = "decode")]
#[test]
fn distinct_signals_survive_full_and_partial_blocks() {
for frames in [4096, 4097, 8193] {
let channels: Vec<Vec<f32>> = [440.0f32, 880.0]
.into_iter()
.map(|hz| (0..frames).map(|i| (std::f32::consts::TAU * hz * i as f32 / 48_000.0).sin() * 0.4).collect())
.collect();
let audio = AudioBuffer { sample_rate: 48_000, channels };
let bytes = encode(&audio, 192).unwrap();
let (_, decoded) = crate::decode(&bytes, Some("ogg")).unwrap();
assert_eq!(decoded.frames(), frames);
assert_eq!(decoded.channels.len(), 2);
for (expected, actual) in audio.channels.iter().zip(&decoded.channels) {
let mse = expected.iter().zip(actual).map(|(a, b)| (a - b).powi(2)).sum::<f32>() / frames as f32;
// Vorbis is lossy; this tolerates codec error but rejects silence or swapped channels.
assert!(mse.sqrt() < 0.08, "{frames} frames: RMS error {}", mse.sqrt());
}
}
}
}
@@ -77,6 +77,6 @@ fn every_encode_format_has_an_extension_it_is_written_and_read_under() {
assert!(format.mime_type().starts_with("audio/"), "{format:?}");
}
let extensions: Vec<_> = EncodeFormat::ALL.iter().map(|f| f.extension()).collect();
assert_eq!(extensions, ["wav", "aif", "flac", "m4a", "m4a", "mp3", "ac3", "eac3"]);
assert_eq!(extensions, ["wav", "aif", "flac", "m4a", "m4a", "mp3", "ac3", "eac3", "ogg"]);
assert_eq!(EncodeFormat::Aiff.mime_type(), "audio/aiff");
}
+9 -1
View File
@@ -14,7 +14,15 @@ fn only_formats_the_encoder_writes_are_named() {
for name in craft_audio::ENCODE_EXTENSIONS {
assert!(encode_format_for(name).is_some(), "{name}");
}
for other in ["ogg", "opus", "aac", "mp4", "xyz", ""] {
for other in ["opus", "aac", "mp4", "xyz", ""] {
assert_eq!(encode_format_for(other), None, "{other}");
}
}
#[test]
fn ogg_names_follow_the_native_feature() {
let built = cfg!(all(feature = "vorbis-encode", not(target_arch = "wasm32")));
assert_eq!(EncodeFormat::Ogg.is_built(), built);
assert_eq!(encode_format_for("ogg"), built.then_some(EncodeFormat::Ogg));
assert_eq!(craft_audio::ENCODE_EXTENSIONS.contains(&"ogg"), built);
}
+23 -3
View File
@@ -397,12 +397,15 @@ fn the_formats_are_named() {
for name in ENCODE_EXTENSIONS {
assert!(encode_format_for(name).is_some(), "{name}");
}
assert_eq!(ENCODE_EXTENSIONS.len(), 12);
assert_eq!(ENCODE_EXTENSIONS.len(), 13);
for format in CODED {
assert!(EncodeFormat::ALL.contains(&format) && format.is_built());
}
let features: Vec<_> = EncodeFormat::ALL.iter().map(|f| f.feature()).collect();
assert_eq!(features, ["pcm-encode", "pcm-encode", "flac-encode", "alac-encode", "aac-encode", "mp3-encode", "ac3-encode", "eac3-encode"]);
assert_eq!(
features,
["pcm-encode", "pcm-encode", "flac-encode", "alac-encode", "aac-encode", "mp3-encode", "ac3-encode", "eac3-encode", "vorbis-encode"]
);
}
/// ffmpeg's decode of `file` as interleaved `f32`, split into `channels` channels.
@@ -495,6 +498,10 @@ fn the_format_queries_agree_with_the_writer() {
let layouts = masks.iter().map(|&mask| ChannelLayout::from_mask(mask)).chain((1..=9).map(ChannelLayout::unordered));
for layout in layouts {
for &format in EncodeFormat::ALL {
// Vorbis is whole-buffer-only; its direct/generic API and options are tested separately.
if format == EncodeFormat::Ogg {
continue;
}
// 24 bits is a depth every format has.
let opts = EncodeOptions::new(format).with_layout(layout);
for &sample_rate in &rates {
@@ -520,7 +527,7 @@ fn the_format_queries_agree_with_the_writer() {
// The most channels is the most: one more is refused, by the layouts of a format that has
// a fixed set and by the writer of one that has not.
let most: Vec<u16> = EncodeFormat::ALL.iter().map(|f| f.max_channels()).collect();
assert_eq!(most, [32_767, 32_767, 8, 8, 8, 2, 6, 8]);
assert_eq!(most, [32_767, 32_767, 8, 8, 8, 2, 6, 8, 2]);
for &format in EncodeFormat::ALL {
let most = format.max_channels();
match format.fixed_layouts(most) {
@@ -569,3 +576,16 @@ fn the_bit_rate_used_can_be_asked_for() {
assert_eq!(encode(&buf, &opts).unwrap().len() as u32, 43 * 1152 / 8 * opts.bitrate(48_000, 2).unwrap().unwrap() / 48_000);
assert!(is_unsupported(EncodeOptions::new(EncodeFormat::Mp3).bitrate(48_000, 6)));
}
#[test]
fn vorbis_is_whole_buffer_only_and_validates_layouts() {
let opts = EncodeOptions::new(EncodeFormat::Ogg).with_layout(ChannelLayout::STEREO);
assert!(opts.check(48_000, 2).is_ok());
assert_eq!(opts.bitrate(48_000, 2).unwrap(), None);
assert!(FileEncoder::new(Cursor::new(Vec::new()), &opts, 48_000, 2).is_err());
let buf = craft_audio::AudioBuffer::new(48_000, 2, 512);
assert!(craft_audio::encode(&buf, &opts).unwrap().starts_with(b"OggS"));
let wrong = opts.with_layout(ChannelLayout::from_mask(0xC));
assert!(wrong.check(48_000, 2).is_err());
assert!(craft_audio::encode(&buf, &wrong).is_err());
}
+22 -13
View File
@@ -1,5 +1,5 @@
//! ZSoft PCX (Paintbrush) reader: strictly bounded scanline RLE, 16/256-colour
//! palettes and 8-bit three-plane RGB. Read-only: modern saves should use PNG.
//! palettes, 8-bit RGB and four-plane RGBA. Read-only: modern saves should use PNG.
use crate::SampleType;
use crate::error::CodecError;
@@ -19,7 +19,7 @@ fn le16(b: &[u8], i: usize) -> u16 {
/// PCX lacks a strong magic number. Require plausible complete header fields before
/// identifying it, rather than classifying every file starting with 0x0a as PCX.
pub(crate) fn looks_like_pcx(b: &[u8]) -> bool {
if b.len() < HEADER || b[0] != 0x0a || !matches!(b[1], 0 | 2 | 3 | 5) || b[2] != 1 {
if b.len() < HEADER || b[0] != 0x0a || !matches!(b[1], 0 | 2..=5) || b[2] != 1 {
return false;
}
let bits = b[3];
@@ -31,7 +31,12 @@ pub(crate) fn looks_like_pcx(b: &[u8]) -> bool {
}
let width = u32::from(x1 - x0) + 1;
let min_stride = (width * u32::from(bits)).div_ceil(8);
stride >= min_stride && stride > 0 && (bits != 8 || matches!(planes, 1 | 3)) && (bits == 8 || u32::from(bits) * u32::from(planes) <= 4)
stride >= min_stride && stride > 0 && (bits != 8 || matches!(planes, 1 | 3 | 4)) && (bits == 8 || u32::from(bits) * u32::from(planes) <= 4)
}
/// The dimensions declared by a plausible PCX header, without decoding its pixels.
pub(crate) fn dimensions(b: &[u8]) -> Option<(u32, u32)> {
looks_like_pcx(b).then(|| (u32::from(le16(b, 8) - le16(b, 4)) + 1, u32::from(le16(b, 10) - le16(b, 6)) + 1))
}
/// Read one compressed scanline, including all planes. RLE packets never cross a scanline.
@@ -61,11 +66,12 @@ pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result<Image, CodecError> {
if !looks_like_pcx(b) {
return Err(bad("invalid PCX header or unsupported pixel layout"));
}
let (w, h) = (u32::from(le16(b, 8) - le16(b, 4)) + 1, u32::from(le16(b, 10) - le16(b, 6)) + 1);
limits.check(w, h, ChannelLayout::Rgb, SampleType::U8)?;
let (w, h) = dimensions(b).ok_or_else(|| bad("invalid PCX header or unsupported pixel layout"))?;
let layout = if b[3] == 8 && b[65] == 4 { ChannelLayout::Rgba } else { ChannelLayout::Rgb };
limits.check(w, h, layout, SampleType::U8)?;
let (bits, planes, stride) = (usize::from(b[3]), usize::from(b[65]), usize::from(le16(b, 66)));
let row_len = stride.checked_mul(planes).ok_or_else(|| bad("row size overflow"))?;
let total = (w as usize).checked_mul(h as usize).and_then(|n| n.checked_mul(3)).ok_or_else(|| bad("pixel size overflow"))?;
let total = (w as usize).checked_mul(h as usize).and_then(|n| n.checked_mul(layout.channels())).ok_or_else(|| bad("pixel size overflow"))?;
// The last 769 bytes are the optional VGA palette for 8-bit indexed images.
let vga = bits == 8 && planes == 1 && b.len() >= HEADER + 769 && b[b.len() - 769] == 0x0c;
if bits == 8 && planes == 1 && !vga && le16(b, 68) != 2 {
@@ -102,8 +108,10 @@ pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result<Image, CodecError> {
for y in 0..h as usize {
read_row(&b[..image_end], &mut p, &mut row)?;
for x in 0..width {
let rgb = if bits == 8 && planes == 3 {
[row[x], row[stride + x], row[2 * stride + x]]
let rgba = if bits == 8 && planes == 4 {
[row[x], row[stride + x], row[2 * stride + x], row[3 * stride + x]]
} else if bits == 8 && planes == 3 {
[row[x], row[stride + x], row[2 * stride + x], 255]
} else {
let index = if bits == 8 {
usize::from(row[x])
@@ -118,19 +126,20 @@ pub(crate) fn decode(b: &[u8], limits: &Limits) -> Result<Image, CodecError> {
};
if vga {
let o = image_end + 1 + index * 3;
[b[o], b[o + 1], b[o + 2]]
[b[o], b[o + 1], b[o + 2], 255]
} else if bits == 8 {
let g = index as u8;
[g, g, g] // palette-info 2: gray scale
[g, g, g, 255] // palette-info 2: gray scale
} else {
let o = 16 + index * 3;
[b[o], b[o + 1], b[o + 2]]
[b[o], b[o + 1], b[o + 2], 255]
}
};
pixels[(y * width + x) * 3..(y * width + x + 1) * 3].copy_from_slice(&rgb);
let start = (y * width + x) * layout.channels();
pixels[start..start + layout.channels()].copy_from_slice(&rgba[..layout.channels()]);
}
}
let mut image = Image::from_u8(w, h, ChannelLayout::Rgb, pixels)?;
let mut image = Image::from_u8(w, h, layout, pixels)?;
let (xdpi, ydpi) = (le16(b, 12), le16(b, 14));
if xdpi > 0 && ydpi > 0 {
image.meta.dpi = Some((f32::from(xdpi), f32::from(ydpi)));
+11 -1
View File
@@ -96,7 +96,7 @@ fn channel(hex: &str) -> Option<u8> {
Some(((v * 255 + max / 2) / max) as u8)
}
fn named(name: &str) -> Option<[u8; 3]> {
pub(crate) fn named(name: &str) -> Option<[u8; 3]> {
let s = name.to_ascii_lowercase().replace([' ', '-', '_'], "");
// XPM imports X11 names, whose RGB values differ from CSS for names
// such as gray, maroon and purple. Keep these exact rather than guessing.
@@ -114,6 +114,16 @@ fn named(name: &str) -> Option<[u8; 3]> {
})
}
/// Exact, normalized X11 lookup for consumers that need table membership rather
/// than XPM's additional aliases and normalization rules.
pub(crate) fn exact_x11_name(name: &str) -> Option<[u8; 3]> {
if name.is_empty() || name.len() > 64 || !name.bytes().all(|byte| byte.is_ascii_lowercase() || byte.is_ascii_digit()) {
return None;
}
let index = x11_colors::X11_COLORS.binary_search_by_key(&name, |(entry, _)| *entry).ok()?;
Some(x11_colors::X11_COLORS.get(index)?.1)
}
fn color(name: &str) -> Option<[u8; 4]> {
if name.eq_ignore_ascii_case("none") {
return Some([0, 0, 0, 0]);
+11
View File
@@ -237,6 +237,17 @@ pub fn jpeg_info(bytes: &[u8]) -> Option<JpegInfo> {
jpeg::info(bytes)
}
/// PCX's dimensions are available from its fixed-size header without decoding the RLE rows.
pub fn pcx_dimensions(bytes: &[u8]) -> Option<(u32, u32)> {
codecs::pcx::dimensions(bytes)
}
/// The X11 color-name lookup used by XPM files, expressed as normalized sRGB.
pub fn xpm_named_color_rgb(name: &str) -> Option<[f32; 3]> {
let rgb = codecs::xpm::exact_x11_name(name)?;
Some(rgb.map(|channel| f32::from(channel) / 255.0))
}
/// The colour table of a GIF's first frame (its Local Color Table, else the Global one) and the
/// entry its Graphic Control Extension makes transparent, read without decoding pixels.
pub fn gif_palette(bytes: &[u8]) -> Option<(Vec<[u8; 3]>, Option<u8>)> {
+5 -1
View File
@@ -32,6 +32,10 @@ impl Default for Limits {
}
impl Limits {
/// Construct explicit bounds for a caller-owned format adapter.
pub const fn new(max_width: u32, max_height: u32, max_pixels: u64, max_alloc: u64) -> Self {
Limits { max_width, max_height, max_pixels, max_alloc }
}
/// For a decoder that writes a band of rows at a time into the document's tiles instead of
/// one buffer (TIFF, #8169): the largest document size, 300,000 px a side, on 64-bit
/// targets, with `max_alloc` bounding each group of bands. 32-bit targets keep the
@@ -85,7 +89,7 @@ impl Limits {
/// never beats `max_ratio`:1. Called before the output buffer is allocated, so a
/// header-only hostile file cannot make the decoder reserve gigabytes. A fixed 1 MiB of
/// slack keeps tiny images and headers with large metadata unaffected.
pub(crate) fn check_plausible(declared_bytes: u64, file_len: usize, max_ratio: u64) -> Result<(), CodecError> {
pub fn check_plausible(declared_bytes: u64, file_len: usize, max_ratio: u64) -> Result<(), CodecError> {
let capacity = (file_len as u64).saturating_mul(max_ratio).saturating_add(1 << 20);
if declared_bytes > capacity {
return Err(CodecError::LimitExceeded(format!("a {file_len} byte file cannot hold {declared_bytes} bytes of image data")));
-4
View File
@@ -15,7 +15,3 @@ base64 = "0.23"
craft-image-codecs = { workspace = true }
thiserror = { workspace = true }
image = { version = "0.25", default-features = false }
# The DDS encoder compresses rows of blocks in parallel on native; wasm stays single-threaded.
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
rayon = { workspace = true }
+6 -10
View File
@@ -1,12 +1,9 @@
# craft-raster-codecs
Small raster image formats for the Craft apps, from PhotoCraft's `photocraft-codecs`: one module
per format, one implementation of each. Decoders take untrusted bytes and `Limits`, check the
declared size before allocating, and never panic. No `unsafe`; it builds for
`wasm32-unknown-unknown`. The `common` RGBA image facade delegates PNG/JPEG/BMP/GIF/TIFF/WebP
decoding and PNG/JPEG encoding to [`craft-image-codecs`](../image-codecs/README.md), the shared
depth- and metadata-preserving codec implementation. Other dependencies are `thiserror`, and
`rayon` on native targets (the DDS encoder compresses rows of blocks in parallel).
Compatibility facade for the small raster-format modules in older Craft app versions. The
format readers and writers are implemented once in [`craft-image-codecs`](../image-codecs/README.md);
these modules forward calls and adapt the older `Image` and `Limits` types. The `common` RGBA
image facade also delegates to that crate.
```toml
craft-raster-codecs = { git = "https://github.com/storytold/craft-libs", rev = "<commit>" }
@@ -37,9 +34,8 @@ assert_eq!(image.data(), &[0, 255]);
let bytes = pnm::encode(&image)?;
```
Each module has a `looks_like_*` (or `is_dicom`) sniffer for the format's signature. `dds` and
`fits` also have `has_additional_images`, which says without decoding whether a file holds
more than the one image `decode` returns (cube faces, array slices, further HDUs).
The module sniffers and the `dds`/`fits` additional-image queries forward to shared detection and
metadata inspection in `craft-image-codecs`.
`xpm::x11_color_rgb` also looks up exact normalized X11 names as RGB channels in `0..=1`.
It accepts only 1–64 lowercase ASCII letters or digits, without normalization, XPM-only aliases,
+79
View File
@@ -0,0 +1,79 @@
//! Compatibility between this crate's small-format facade and the canonical image codec model.
use crate::{ChannelLayout, CodecError, DecodeWarning, Image, Limits, SampleType};
use craft_image_codecs::{DecodeOptions, Format, Metadata};
pub(crate) fn format(format: Format, bytes: &[u8], limits: &Limits) -> Result<Image, CodecError> {
let shared_limits = craft_image_codecs::Limits::new(limits.max_width, limits.max_height, limits.max_pixels, limits.max_alloc);
let options = DecodeOptions { limits: shared_limits, ..DecodeOptions::default() };
let image = craft_image_codecs::decode_as_with(format, bytes, &options).map_err(from_shared_error)?;
from_shared_image(image)
}
pub(crate) fn shared_image(image: &Image) -> Result<craft_image_codecs::Image, CodecError> {
let layout = match image.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 image.sample_type() {
SampleType::U8 => craft_image_codecs::SampleType::U8,
SampleType::U16 => craft_image_codecs::SampleType::U16,
SampleType::F32 => craft_image_codecs::SampleType::F32,
};
let meta = Metadata { dpi: image.dpi, text: image.text.clone(), ..Metadata::default() };
craft_image_codecs::Image::from_raw(image.width(), image.height(), layout, sample, image.data().to_vec())
.map(|image| image.with_meta(meta))
.map_err(from_shared_error)
}
fn from_shared_image(image: craft_image_codecs::Image) -> Result<Image, CodecError> {
let layout = match image.layout() {
craft_image_codecs::ChannelLayout::Gray => ChannelLayout::Gray,
craft_image_codecs::ChannelLayout::GrayA => ChannelLayout::GrayA,
craft_image_codecs::ChannelLayout::Rgb => ChannelLayout::Rgb,
craft_image_codecs::ChannelLayout::Rgba => ChannelLayout::Rgba,
craft_image_codecs::ChannelLayout::Cmyk => ChannelLayout::Cmyk,
craft_image_codecs::ChannelLayout::CmykA => ChannelLayout::CmykA,
_ => return Err(CodecError::InvalidImage(format!("unsupported small-codec layout {:?}", image.layout()))),
};
let sample = match image.sample_type() {
craft_image_codecs::SampleType::U8 => SampleType::U8,
craft_image_codecs::SampleType::U16 => SampleType::U16,
craft_image_codecs::SampleType::F32 => SampleType::F32,
_ => return Err(CodecError::InvalidImage(format!("unsupported small-codec sample type {:?}", image.sample_type()))),
};
let mut out = Image::from_raw(image.width(), image.height(), layout, sample, image.data().to_vec())?;
out.dpi = image.meta.dpi;
out.text = image.meta.text;
out.warnings = image
.warnings
.into_iter()
.filter_map(|warning| match warning {
craft_image_codecs::DecodeWarning::MorePages { total } | craft_image_codecs::DecodeWarning::MoreParts { total } => {
Some(DecodeWarning::MorePages { total })
}
_ => None,
})
.collect();
Ok(out)
}
pub(crate) fn from_shared_error(error: craft_image_codecs::CodecError) -> CodecError {
match error {
craft_image_codecs::CodecError::UnknownFormat => CodecError::unsupported("image", "unrecognized image format"),
craft_image_codecs::CodecError::Unsupported { format, reason } => CodecError::unsupported(format.name(), reason),
craft_image_codecs::CodecError::Malformed { format, message } => CodecError::malformed(format.name(), message),
craft_image_codecs::CodecError::LimitExceeded(message) => CodecError::LimitExceeded(message),
craft_image_codecs::CodecError::Encode { format, message } => CodecError::Encode { format: format.name(), message },
craft_image_codecs::CodecError::InvalidImage(message) => CodecError::InvalidImage(message),
}
}
pub(crate) fn encode(image: &Image, format: Format, options: &craft_image_codecs::EncodeOptions) -> Result<Vec<u8>, CodecError> {
let image = shared_image(image)?;
craft_image_codecs::encode(&image, format, options).map_err(from_shared_error)
}
+40 -581
View File
@@ -1,616 +1,75 @@
//! DirectDraw Surface (DDS) textures, after Microsoft's public DDS documentation ("DDS",
//! "DDS_HEADER", "DDS_PIXELFORMAT", "DDS_HEADER_DXT10").
//!
//! Reading: the top mip level of a 2D texture, either uncompressed (8 to 32 bits per pixel
//! described by channel masks, RGB or luminance) or block-compressed BC1/BC2/BC3
//! (DXT1/DXT3/DXT5), with or without the DX10 header. Cubemaps, texture arrays and volume
//! textures are refused rather than flattened to one face or slice.
//!
//! Writing: a 2D texture, uncompressed (BGRA or BGRX, luminance with or without alpha) or
//! BC1/BC2/BC3, optionally with its full mip chain. The legacy header describes all of these,
//! so no DX10 header is written; formats only DXGI can name (BC4–BC7, sRGB) aren't written.
//! DDS compatibility facade; implementation and BC block codecs live in craft-image-codecs.
use crate::{CodecError, Image, Limits, SampleType, bridge};
use craft_image_codecs::Format;
use std::borrow::Cow;
use crate::dds_bc::{self, Block, Mask};
use crate::{ChannelLayout, CodecError, Image, Limits, SampleType};
/// `DDS ` plus the 124-byte DDS_HEADER.
const HEADER: usize = 128;
/// DDS_HEADER_DXT10, present when the FourCC is `DX10`.
const DX10_HEADER: usize = 20;
const DDSD_DEPTH: u32 = 0x80_0000;
const DDPF_ALPHAPIXELS: u32 = 0x1;
const DDPF_FOURCC: u32 = 0x4;
const DDPF_RGB: u32 = 0x40;
const DDPF_LUMINANCE: u32 = 0x2_0000;
const DDSCAPS2_CUBEMAP: u32 = 0x200;
const DDSCAPS2_CUBEMAP_FACES: u32 = 0xfc00;
const DDSCAPS2_VOLUME: u32 = 0x20_0000;
const DIMENSION_TEXTURE2D: u32 = 3;
const MISC_TEXTURECUBE: u32 = 0x4;
fn bad(reason: impl std::fmt::Display) -> CodecError {
CodecError::malformed("DDS", reason)
pub fn looks_like_dds(bytes: &[u8]) -> bool {
craft_image_codecs::detect(bytes) == Some(Format::Dds)
}
fn unsupported(reason: impl Into<String>) -> CodecError {
CodecError::unsupported("DDS", reason)
}
fn le32(b: &[u8], at: usize) -> Result<u32, CodecError> {
let bytes = b.get(at..at + 4).and_then(|s| <[u8; 4]>::try_from(s).ok()).ok_or_else(|| bad("truncated header"))?;
Ok(u32::from_le_bytes(bytes))
}
/// The `DDS ` magic.
pub fn looks_like_dds(b: &[u8]) -> bool {
b.starts_with(b"DDS ")
}
/// Header-declared extra subresources cannot survive a single-image rewrite, even without presence flags.
pub fn has_additional_images(bytes: &[u8]) -> Result<bool, CodecError> {
let depth = le32(bytes, 24)?;
let mips = le32(bytes, 28)?;
let faces = (le32(bytes, 112)? & DDSCAPS2_CUBEMAP_FACES).count_ones();
let dx10 = le32(bytes, 80)? & DDPF_FOURCC != 0 && bytes.get(84..88) == Some(b"DX10");
let (cube, array) = if dx10 { (le32(bytes, 136)? & MISC_TEXTURECUBE != 0, le32(bytes, 140)?) } else { (false, 0) };
Ok(depth > 1 || mips > 1 || faces > 1 || cube || array > 1)
craft_image_codecs::has_unretained_source_data(bytes).map_err(bridge::from_shared_error)
}
pub fn decode(bytes: &[u8], limits: &Limits) -> Result<Image, CodecError> {
bridge::format(Format::Dds, bytes, limits)
}
/// A FourCC as text when it is printable, else as the number legacy writers store there.
fn fourcc_name(fourcc: u32) -> String {
let bytes = fourcc.to_le_bytes();
if bytes.iter().all(|c| c.is_ascii_graphic() || *c == b' ') { bytes.iter().map(|&c| char::from(c)).collect() } else { fourcc.to_string() }
}
/// One channel of an uncompressed pixel: where it sits and its largest value.
#[derive(Clone, Copy)]
struct Field {
shift: u32,
max: u32,
}
impl Field {
/// `None` for an empty mask; an error for one with gaps or wider than the pixel.
fn new(mask: u32, bits: u32) -> Result<Option<Field>, CodecError> {
if mask == 0 {
return Ok(None);
}
let shift = mask.trailing_zeros();
let max = mask >> shift;
if max & max.wrapping_add(1) != 0 || (bits < 32 && mask >> bits != 0) {
return Err(bad(format!("channel mask {mask:#x} is not a contiguous field of a {bits}-bit pixel")));
}
Ok(Some(Field { shift, max }))
}
fn get(self, pixel: u32) -> u8 {
let v = u64::from((pixel >> self.shift) & self.max);
let max = u64::from(self.max);
((v * 255 + max / 2) / max) as u8
}
}
enum Encoding {
/// Uncompressed: bytes per pixel, then red (or luminance), green, blue and alpha.
Masks {
bytes: usize,
gray: bool,
fields: [Option<Field>; 4],
},
Bc1,
Bc2,
Bc3,
}
impl Encoding {
fn masks(bits: u32, masks: [u32; 4], gray: bool) -> Result<Encoding, CodecError> {
if !matches!(bits, 8 | 16 | 24 | 32) {
return Err(bad(format!("{bits} bits per pixel is not 8, 16, 24 or 32")));
}
let mut fields = [None; 4];
for (field, mask) in fields.iter_mut().zip(masks) {
*field = Field::new(mask, bits)?;
}
let colour = if gray { fields[0].is_some() } else { fields[..3].iter().any(Option::is_some) };
if !colour {
return Err(bad("the pixel format has no colour channel masks"));
}
Ok(Encoding::Masks { bytes: bits as usize / 8, gray, fields })
}
fn layout(&self) -> ChannelLayout {
match self {
Encoding::Masks { gray: true, fields, .. } if fields[3].is_some() => ChannelLayout::GrayA,
Encoding::Masks { gray: true, .. } => ChannelLayout::Gray,
Encoding::Masks { fields, .. } if fields[3].is_none() => ChannelLayout::Rgb,
_ => ChannelLayout::Rgba,
}
}
/// Stored row stride and byte size of the top mip level (block rows for BC).
fn level_layout(&self, width: u32, height: u32, pitch: Option<u32>) -> Result<(usize, usize), CodecError> {
let overflow = || bad("pixel data size overflow");
let (w, h) = (usize::try_from(width).map_err(|_| overflow())?, usize::try_from(height).map_err(|_| overflow())?);
let (row_bytes, rows) = match self {
Encoding::Masks { bytes, .. } => {
let packed = w.checked_mul(*bytes).ok_or_else(overflow)?;
let row_bytes = match pitch {
Some(pitch) => usize::try_from(pitch).map_err(|_| overflow())?,
None => packed,
};
if row_bytes < packed {
return Err(bad(format!("row pitch {row_bytes} is smaller than the {packed}-byte pixel row")));
}
(row_bytes, h)
}
Encoding::Bc1 | Encoding::Bc2 | Encoding::Bc3 => {
let block = if matches!(self, Encoding::Bc1) { 8 } else { 16 };
(w.div_ceil(4).checked_mul(block).ok_or_else(overflow)?, h.div_ceil(4))
}
};
let size = row_bytes.checked_mul(rows).ok_or_else(overflow)?;
Ok((row_bytes, size))
}
}
/// The legacy pixel format: a FourCC, or channel masks.
fn legacy_encoding(b: &[u8]) -> Result<Encoding, CodecError> {
let (flags, fourcc, bits) = (le32(b, 80)?, le32(b, 84)?, le32(b, 88)?);
let alpha = if flags & DDPF_ALPHAPIXELS != 0 { le32(b, 104)? } else { 0 };
if flags & DDPF_FOURCC != 0 {
return match &fourcc.to_le_bytes() {
b"DXT1" => Ok(Encoding::Bc1),
b"DXT3" => Ok(Encoding::Bc2),
b"DXT5" => Ok(Encoding::Bc3),
b"DXT2" | b"DXT4" => Err(unsupported("premultiplied-alpha DXT2/DXT4 textures are not supported")),
_ => Err(unsupported(format!("compression `{}` is not supported (DXT1, DXT3 and DXT5 are)", fourcc_name(fourcc)))),
};
}
if flags & DDPF_RGB != 0 {
return Encoding::masks(bits, [le32(b, 92)?, le32(b, 96)?, le32(b, 100)?, alpha], false);
}
if flags & DDPF_LUMINANCE != 0 {
return Encoding::masks(bits, [le32(b, 92)?, 0, 0, alpha], true);
}
Err(unsupported(format!("pixel format flags {flags:#x} are not RGB, luminance or a supported compression")))
}
/// The DX10 header's DXGI format, refusing anything but a single 2D texture.
fn dx10_encoding(b: &[u8]) -> Result<Encoding, CodecError> {
let (dxgi, dimension, misc, array) = (le32(b, HEADER)?, le32(b, HEADER + 4)?, le32(b, HEADER + 8)?, le32(b, HEADER + 12)?);
if misc & MISC_TEXTURECUBE != 0 {
return Err(unsupported("cubemaps are not supported"));
}
if dimension != DIMENSION_TEXTURE2D {
return Err(unsupported(format!("only 2D textures are supported (resource dimension {dimension})")));
}
if array > 1 {
return Err(unsupported(format!("texture arrays are not supported ({array} textures)")));
}
const RGBA: [u32; 4] = [0xff, 0xff00, 0xff_0000, 0xff00_0000];
const BGRA: [u32; 4] = [0xff_0000, 0xff00, 0xff, 0xff00_0000];
const BGRX: [u32; 4] = [0xff_0000, 0xff00, 0xff, 0];
match dxgi {
27..=29 => Encoding::masks(32, RGBA, false),
87 | 90 | 91 => Encoding::masks(32, BGRA, false),
88 | 92 | 93 => Encoding::masks(32, BGRX, false),
70..=72 => Ok(Encoding::Bc1),
73..=75 => Ok(Encoding::Bc2),
76..=78 => Ok(Encoding::Bc3),
_ => Err(unsupported(format!("DXGI format {dxgi} is not supported (BC1, BC2, BC3 and 8-bit RGBA or BGRA are)"))),
}
}
pub fn decode(b: &[u8], limits: &Limits) -> Result<Image, CodecError> {
if !b.starts_with(b"DDS ") {
return Err(bad("missing the `DDS ` signature"));
}
if le32(b, 4)? != 124 {
return Err(bad("header size is not 124"));
}
let (flags, height, width, depth, caps2) = (le32(b, 8)?, le32(b, 12)?, le32(b, 16)?, le32(b, 24)?, le32(b, 112)?);
if caps2 & DDSCAPS2_CUBEMAP != 0 {
return Err(unsupported("cubemaps are not supported"));
}
if caps2 & DDSCAPS2_VOLUME != 0 || (flags & DDSD_DEPTH != 0 && depth > 1) {
return Err(unsupported("volume textures are not supported"));
}
let dx10 = le32(b, 80)? & DDPF_FOURCC != 0 && &le32(b, 84)?.to_le_bytes() == b"DX10";
let (encoding, start) = if dx10 { (dx10_encoding(b)?, HEADER + DX10_HEADER) } else { (legacy_encoding(b)?, HEADER) };
let layout = encoding.layout();
limits.check(width, height, layout, SampleType::U8)?;
// The same header field is a total level size for BC, but a row stride when DDSD_PITCH is set.
let pitch = if flags & DDSD_PITCH != 0 { Some(le32(b, 20)?) } else { None };
let (row_pitch, size) = encoding.level_layout(width, height, pitch)?;
let data = b.get(start..).and_then(|d| d.get(..size)).ok_or_else(|| bad(format!("truncated pixel data: {size} bytes needed")))?;
let (w, h) = (width as usize, height as usize);
let channels = layout.channels();
let row_size = w.checked_mul(channels).ok_or_else(|| bad("pixel size overflow"))?;
let total = row_size.checked_mul(h).ok_or_else(|| bad("pixel size overflow"))?;
let mut pixels = vec![0u8; total];
match encoding {
Encoding::Masks { bytes, gray, fields } => {
for (src_row, dst_row) in data.chunks_exact(row_pitch).zip(pixels.chunks_exact_mut(row_size)) {
// Stop at the output width, leaving any stored row padding unread.
for (src, dst) in src_row.chunks_exact(bytes).zip(dst_row.chunks_exact_mut(channels)) {
let pixel = src.iter().rev().fold(0u32, |v, &byte| v << 8 | u32::from(byte));
let channel = |i: usize| fields[i].map_or(0, |f| f.get(pixel));
let values = if gray { [channel(0), channel(3), 0, 0] } else { [channel(0), channel(1), channel(2), channel(3)] };
dst.copy_from_slice(&values[..channels]);
}
}
}
Encoding::Bc1 | Encoding::Bc2 | Encoding::Bc3 => {
let block_size = if matches!(encoding, Encoding::Bc1) { 8 } else { 16 };
let blocks_x = w.div_ceil(4);
for (i, block) in data.chunks_exact(block_size).enumerate() {
let texels = match encoding {
Encoding::Bc1 => bc1(block, true),
Encoding::Bc2 => with_alpha(bc1(block.get(8..).unwrap_or_default(), false), bc2_alpha(block)),
_ => with_alpha(bc1(block.get(8..).unwrap_or_default(), false), bc3_alpha(block)),
};
let (bx, by) = ((i % blocks_x) * 4, (i / blocks_x) * 4);
for (t, texel) in texels.iter().enumerate() {
let (x, y) = (bx + t % 4, by + t / 4);
if x < w && y < h {
let at = (y * w + x) * 4;
if let Some(dst) = pixels.get_mut(at..at + 4) {
dst.copy_from_slice(texel);
}
}
}
}
}
}
Image::from_u8(width, height, layout, pixels)
}
/// A BC1 colour block. BC2 and BC3 colour blocks always have four colours; only BC1's
/// `c0 <= c1` order selects three colours and transparent black.
fn bc1(block: &[u8], one_bit_alpha: bool) -> [[u8; 4]; 16] {
let byte = |i: usize| block.get(i).copied().unwrap_or(0);
let (c0, c1) = (u16::from_le_bytes([byte(0), byte(1)]), u16::from_le_bytes([byte(2), byte(3)]));
let palette = dds_bc::colour_palette(c0, c1, c0 > c1 || !one_bit_alpha);
let indices = u32::from_le_bytes([byte(4), byte(5), byte(6), byte(7)]);
std::array::from_fn(|t| palette[(indices >> (2 * t)) as usize & 3])
}
/// BC2: four explicit bits of alpha per texel.
fn bc2_alpha(block: &[u8]) -> [u8; 16] {
let bits = u64::from_le_bytes(std::array::from_fn(|i| block.get(i).copied().unwrap_or(0)));
std::array::from_fn(|t| ((bits >> (4 * t)) & 0xf) as u8 * 17)
}
/// BC3: two alpha endpoints and a 3-bit index per texel into eight values, or into six plus
/// 0 and 255 when `a0 <= a1`.
fn bc3_alpha(block: &[u8]) -> [u8; 16] {
let byte = |i: usize| block.get(i).copied().unwrap_or(0);
let palette = dds_bc::alpha_palette(byte(0), byte(1));
let bits = u64::from_le_bytes([byte(2), byte(3), byte(4), byte(5), byte(6), byte(7), 0, 0]);
std::array::from_fn(|t| palette[((bits >> (3 * t)) & 7) as usize])
}
fn with_alpha(mut texels: [[u8; 4]; 16], alpha: [u8; 16]) -> [[u8; 4]; 16] {
for (texel, a) in texels.iter_mut().zip(alpha) {
texel[3] = a;
}
texels
}
const DDSD_CAPS: u32 = 0x1;
const DDSD_HEIGHT: u32 = 0x2;
const DDSD_WIDTH: u32 = 0x4;
const DDSD_PITCH: u32 = 0x8;
const DDSD_PIXELFORMAT: u32 = 0x1000;
const DDSD_MIPMAPCOUNT: u32 = 0x2_0000;
const DDSD_LINEARSIZE: u32 = 0x8_0000;
const DDSCAPS_COMPLEX: u32 = 0x8;
const DDSCAPS_TEXTURE: u32 = 0x1000;
const DDSCAPS_MIPMAP: u32 = 0x40_0000;
fn encode_err(reason: impl std::fmt::Display) -> CodecError {
CodecError::encode("DDS", reason)
}
/// How a written texture stores its pixels.
#[derive(Clone, Copy, PartialEq, Eq)]
enum Store {
/// 8-bit luminance.
Luminance,
/// 8-bit luminance, then 8-bit alpha.
LuminanceAlpha,
/// Blue, green, red and an unused byte (written as 255, so a reader that takes it for
/// alpha still sees an opaque texture).
Bgrx,
Bgra,
Bc1,
Bc2,
Bc3,
}
impl Store {
/// The storage for an image of `layout`.
fn new(compression: DdsCompression, layout: ChannelLayout) -> Result<Store, CodecError> {
Ok(match (compression, layout) {
(DdsCompression::None, ChannelLayout::Gray) => Store::Luminance,
(DdsCompression::None, ChannelLayout::GrayA) => Store::LuminanceAlpha,
(DdsCompression::None, ChannelLayout::Rgb) => Store::Bgrx,
(DdsCompression::None, ChannelLayout::Rgba) => Store::Bgra,
(DdsCompression::Bc1, ChannelLayout::Rgba) => Store::Bc1,
(DdsCompression::Bc2, ChannelLayout::Rgba) => Store::Bc2,
(DdsCompression::Bc3, ChannelLayout::Rgba) => Store::Bc3,
(_, layout) => return Err(encode_err(format!("{layout:?} pixels can't be written as `{}`", compression.name()))),
})
}
/// Bytes per pixel, or per 4×4 block for a block compression.
fn unit(self) -> usize {
match self {
Store::Luminance => 1,
Store::LuminanceAlpha => 2,
Store::Bgrx | Store::Bgra => 4,
Store::Bc1 => 8,
Store::Bc2 | Store::Bc3 => 16,
}
}
fn is_block(self) -> bool {
matches!(self, Store::Bc1 | Store::Bc2 | Store::Bc3)
}
/// Bytes of one row of pixels (or of 4×4 blocks) of a level `width` wide.
fn row_bytes(self, width: usize) -> Option<usize> {
if self.is_block() { width.div_ceil(4).checked_mul(self.unit()) } else { width.checked_mul(self.unit()) }
}
fn level_bytes(self, width: usize, height: usize) -> Option<usize> {
let rows = if self.is_block() { height.div_ceil(4) } else { height };
self.row_bytes(width)?.checked_mul(rows)
}
/// DDS_PIXELFORMAT: flags, FourCC, bits per pixel and the red, green, blue and alpha masks.
fn pixel_format(self) -> (u32, [u8; 4], u32, [u32; 4]) {
match self {
Store::Luminance => (DDPF_LUMINANCE, [0; 4], 8, [0xff, 0, 0, 0]),
Store::LuminanceAlpha => (DDPF_LUMINANCE | DDPF_ALPHAPIXELS, [0; 4], 16, [0xff, 0, 0, 0xff00]),
Store::Bgrx => (DDPF_RGB, [0; 4], 32, [0xff_0000, 0xff00, 0xff, 0]),
Store::Bgra => (DDPF_RGB | DDPF_ALPHAPIXELS, [0; 4], 32, [0xff_0000, 0xff00, 0xff, 0xff00_0000]),
Store::Bc1 => (DDPF_FOURCC, *b"DXT1", 0, [0; 4]),
Store::Bc2 => (DDPF_FOURCC, *b"DXT3", 0, [0; 4]),
Store::Bc3 => (DDPF_FOURCC, *b"DXT5", 0, [0; 4]),
}
}
}
/// Levels in a full mip chain: the larger side halves down to 1.
fn mip_levels(width: u32, height: u32) -> u32 {
32 - width.max(height).max(1).leading_zeros()
}
fn half((w, h): (usize, usize)) -> (usize, usize) {
((w / 2).max(1), (h / 2).max(1))
}
/// How a DDS texture stores its pixels.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum DdsCompression {
/// Uncompressed, 8 bits per channel: BGRA (BGRX without alpha), or luminance with or
/// without alpha for grayscale. Lossless.
#[default]
None,
/// BC1 (DXT1): 4 bits per pixel. Alpha is on or off: texels under half opacity become
/// transparent black.
Bc1,
/// BC2 (DXT3): 8 bits per pixel, with 4 bits of explicit alpha per texel.
Bc2,
/// BC3 (DXT5): 8 bits per pixel, with smooth interpolated alpha.
Bc3,
}
impl DdsCompression {
pub const ALL: [DdsCompression; 4] = [DdsCompression::None, DdsCompression::Bc1, DdsCompression::Bc2, DdsCompression::Bc3];
/// The name scripts and the CLI use: `none`, `bc1`, `bc2` or `bc3`.
pub const ALL: [Self; 4] = [Self::None, Self::Bc1, Self::Bc2, Self::Bc3];
pub fn name(self) -> &'static str {
match self {
DdsCompression::None => "none",
DdsCompression::Bc1 => "bc1",
DdsCompression::Bc2 => "bc2",
DdsCompression::Bc3 => "bc3",
Self::None => "none",
Self::Bc1 => "bc1",
Self::Bc2 => "bc2",
Self::Bc3 => "bc3",
}
}
/// [`Self::name`] back to a compression, also taking the DXT names (`dxt1`, `dxt3`,
/// `dxt5`), in any case. Anything else is `None`.
pub fn from_name(name: &str) -> Option<Self> {
match name.to_ascii_lowercase().as_str() {
"none" => Some(DdsCompression::None),
"bc1" | "dxt1" => Some(DdsCompression::Bc1),
"bc2" | "dxt3" => Some(DdsCompression::Bc2),
"bc3" | "dxt5" => Some(DdsCompression::Bc3),
"none" => Some(Self::None),
"bc1" | "dxt1" => Some(Self::Bc1),
"bc2" | "dxt3" => Some(Self::Bc2),
"bc3" | "dxt5" => Some(Self::Bc3),
_ => None,
}
}
/// A block compression (lossy), not uncompressed pixels.
pub fn is_block(self) -> bool {
self != DdsCompression::None
self != Self::None
}
}
/// What a DDS file is written with.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub struct DdsOptions {
pub compression: DdsCompression,
/// Write the full mip chain down to 1×1, each level a box filter of the one above.
pub mipmaps: bool,
}
/// Writes `img` (8 bits per channel) as a DDS texture. Uncompressed stores gray, gray with
/// alpha, RGB and RGBA; the block compressions take RGBA only.
pub fn encode(img: &Image, opts: DdsOptions) -> Result<Vec<u8>, CodecError> {
if img.sample_type() != SampleType::U8 {
return Err(encode_err("DDS is written at 8 bits per channel"));
pub fn encode(image: &Image, options: DdsOptions) -> Result<Vec<u8>, CodecError> {
if image.sample_type() != SampleType::U8 {
return Err(CodecError::encode("DDS", "DDS is written at 8 bits per channel"));
}
let pixels = img.data();
let store = Store::new(opts.compression, img.layout())?;
let (width, height) = (img.width(), img.height());
let levels = if opts.mipmaps { mip_levels(width, height) } else { 1 };
let top = (width as usize, height as usize);
// Every level's size, checked before anything is allocated.
let mut sizes = Vec::new();
let mut size = top;
for _ in 0..levels {
sizes.push(store.level_bytes(size.0, size.1).ok_or_else(|| encode_err("texture size overflow"))?);
size = half(size);
}
let total = sizes.iter().try_fold(HEADER, |total, &s| total.checked_add(s)).ok_or_else(|| encode_err("texture size overflow"))?;
let header = header(width, height, store, levels, sizes.first().copied().unwrap_or(0))?;
let mut out = crate::alloc_zeroed::<u8>(total)?;
out.get_mut(..HEADER).ok_or_else(|| encode_err("output buffer too small"))?.copy_from_slice(&header);
let channels = img.layout().channels();
let mut level = Cow::Borrowed(pixels);
let (mut size, mut at) = (top, HEADER);
for (i, &bytes) in sizes.iter().enumerate() {
let dst = out.get_mut(at..at + bytes).ok_or_else(|| encode_err("output buffer too small"))?;
write_level(store, &level, size, dst)?;
at += bytes;
if i + 1 < sizes.len() {
let next = half(size);
level = Cow::Owned(downsample(&level, size, next, channels)?);
size = next;
}
}
Ok(out)
}
/// The `DDS ` signature and DDS_HEADER. `top` is the top level's size in bytes.
fn header(width: u32, height: u32, store: Store, levels: u32, top: usize) -> Result<[u8; HEADER], CodecError> {
let mut b = [0u8; HEADER];
let mut put = |at: usize, v: u32| {
if let Some(d) = b.get_mut(at..at + 4) {
d.copy_from_slice(&v.to_le_bytes());
}
// BC storage encodes RGBA blocks. The generic image API can plan a
// conversion from other layouts, but this compatibility facade accepts
// only layouts its former writer stored directly.
let allowed = if options.compression.is_block() {
image.layout() == crate::ChannelLayout::Rgba
} else {
matches!(image.layout(), crate::ChannelLayout::Gray | crate::ChannelLayout::GrayA | crate::ChannelLayout::Rgb | crate::ChannelLayout::Rgba)
};
// Uncompressed: the pitch of one row. Compressed: the whole top level (its "linear size").
let (size_flag, pitch_or_size) = if store.is_block() { (DDSD_LINEARSIZE, Some(top)) } else { (DDSD_PITCH, store.row_bytes(width as usize)) };
let pitch_or_size = pitch_or_size
.and_then(|v| u32::try_from(v).ok())
.ok_or_else(|| encode_err(format!("a {width}x{height} level is too large for a DDS header")))?;
let mipmapped = levels > 1;
put(4, 124);
put(8, DDSD_CAPS | DDSD_HEIGHT | DDSD_WIDTH | DDSD_PIXELFORMAT | size_flag | if mipmapped { DDSD_MIPMAPCOUNT } else { 0 });
put(12, height);
put(16, width);
put(20, pitch_or_size);
put(28, levels);
let (flags, fourcc, bits, masks) = store.pixel_format();
put(76, 32);
put(80, flags);
put(84, u32::from_le_bytes(fourcc));
put(88, bits);
for (i, mask) in masks.into_iter().enumerate() {
put(92 + 4 * i, mask);
if !allowed {
return Err(CodecError::encode("DDS", format!("{:?} pixels can't be written as `{}`", image.layout(), options.compression.name())));
}
put(108, DDSCAPS_TEXTURE | if mipmapped { DDSCAPS_COMPLEX | DDSCAPS_MIPMAP } else { 0 });
b[..4].copy_from_slice(b"DDS ");
Ok(b)
}
/// Runs `f` on each `len`-byte row of `out` with its index, in parallel on native targets.
fn rows(out: &mut [u8], len: usize, f: impl Fn(usize, &mut [u8]) + Send + Sync) {
#[cfg(not(target_arch = "wasm32"))]
{
use rayon::prelude::*;
out.par_chunks_mut(len.max(1)).enumerate().for_each(|(i, row)| f(i, row));
}
#[cfg(target_arch = "wasm32")]
for (i, row) in out.chunks_mut(len.max(1)).enumerate() {
f(i, row);
}
}
/// Writes one level of `width` × `height` pixels (in the image's layout) into `dst`.
fn write_level(store: Store, pixels: &[u8], (width, height): (usize, usize), dst: &mut [u8]) -> Result<(), CodecError> {
let row_bytes = store.row_bytes(width).ok_or_else(|| encode_err("texture size overflow"))?;
match store {
Store::Luminance | Store::LuminanceAlpha => {
// The image's gray (and alpha) samples, in the same order.
let src = pixels.get(..dst.len()).ok_or_else(|| encode_err("the level is smaller than its size"))?;
dst.copy_from_slice(src);
}
Store::Bgrx | Store::Bgra => {
let channels = if store == Store::Bgra { 4 } else { 3 };
rows(dst, row_bytes, |y, row| {
let src = pixels.get(y * width * channels..).unwrap_or_default();
for (d, s) in row.as_chunks_mut::<4>().0.iter_mut().zip(src.chunks_exact(channels)) {
let byte = |i: usize| s.get(i).copied().unwrap_or(255);
*d = [byte(2), byte(1), byte(0), byte(3)];
}
});
}
Store::Bc1 | Store::Bc2 | Store::Bc3 => {
let (texels, _) = pixels.as_chunks::<4>();
rows(dst, row_bytes, |by, row| {
for (bx, d) in row.chunks_exact_mut(store.unit()).enumerate() {
let (block, inside) = gather(texels, (width, height), bx, by);
let encoded: &[u8] = match store {
Store::Bc1 => &dds_bc::encode_bc1(&block, inside),
Store::Bc2 => &dds_bc::encode_bc2(&block, inside),
_ => &dds_bc::encode_bc3(&block, inside),
};
for (d, s) in d.iter_mut().zip(encoded) {
*d = *s;
}
}
});
}
}
Ok(())
}
/// Block (`bx`, `by`)'s texels, and which of them lie inside the image.
fn gather(texels: &[[u8; 4]], (width, height): (usize, usize), bx: usize, by: usize) -> (Block, Mask) {
let mut block = [[0u8; 4]; 16];
let mut inside: Mask = 0;
for (t, texel) in block.iter_mut().enumerate() {
let (x, y) = (bx * 4 + t % 4, by * 4 + t / 4);
if x < width
&& y < height
&& let Some(p) = texels.get(y * width + x)
{
*texel = *p;
inside |= 1 << t;
}
}
(block, inside)
}
/// The next mip level: each pixel the average of the 2×2 pixels it covers, or of 2×3, 3×2 or
/// 3×3 along the last column and row of an odd-sized level, so no pixel is dropped.
fn downsample(src: &[u8], (w, h): (usize, usize), (nw, nh): (usize, usize), channels: usize) -> Result<Vec<u8>, CodecError> {
let len = nw.checked_mul(nh).and_then(|n| n.checked_mul(channels)).ok_or_else(|| encode_err("mip level size overflow"))?;
let mut dst = crate::alloc_zeroed::<u8>(len)?;
let span = |i: usize, n: usize, size: usize| 2 * i..=if i + 1 == n { size.saturating_sub(1) } else { 2 * i + 1 };
rows(&mut dst, nw * channels, |y, row| {
let ys = span(y, nh, h);
for (x, px) in row.chunks_exact_mut(channels.max(1)).enumerate() {
let xs = span(x, nw, w);
for (c, v) in px.iter_mut().enumerate() {
let (mut sum, mut n) = (0u32, 0u32);
for sy in ys.clone() {
for sx in xs.clone() {
if let Some(&s) = src.get((sy * w + sx) * channels + c) {
sum += u32::from(s);
n += 1;
}
}
}
*v = ((sum + n / 2) / n.max(1)) as u8;
}
}
});
Ok(dst)
let compression = match options.compression {
DdsCompression::None => craft_image_codecs::DdsCompression::None,
DdsCompression::Bc1 => craft_image_codecs::DdsCompression::Bc1,
DdsCompression::Bc2 => craft_image_codecs::DdsCompression::Bc2,
DdsCompression::Bc3 => craft_image_codecs::DdsCompression::Bc3,
};
let opts =
craft_image_codecs::EncodeOptions { dds: craft_image_codecs::DdsOptions { compression, mipmaps: options.mipmaps }, ..Default::default() };
bridge::encode(image, Format::Dds, &opts)
}
-369
View File
@@ -1,369 +0,0 @@
//! BC1, BC2 and BC3 (DXT1, DXT3, DXT5) blocks, after Microsoft's public block compression
//! documentation ("Block Compression (Direct3D 10)" and "Texture Block Compression in Direct3D
//! 11"): the palettes the DDS reader decodes with, and the block encoder the DDS writer uses.
//!
//! The encoder fits a block's colours with two RGB565 endpoints along their principal axis,
//! refines them by least squares, and scores every candidate against the exact palette the
//! reader rebuilds, so the indices it picks are the best ones for what a decoder shows.
/// The 16 texels of a 4×4 block, row by row, as RGBA.
pub(crate) type Block = [[u8; 4]; 16];
/// Bit `t` set for each texel `t` of a block that counts: edge blocks of a texture whose size is
/// not a multiple of four have texels outside the image.
pub(crate) type Mask = u16;
pub(crate) fn rgb565(c: u16) -> [u8; 3] {
let scale = |v: u16, max: u16| ((u32::from(v) * 255 + u32::from(max) / 2) / u32::from(max)) as u8;
[scale(c >> 11, 31), scale((c >> 5) & 63, 63), scale(c & 31, 31)]
}
/// The colours a colour block's indices select. Four-colour mode (BC1 with `c0 > c1`, and every
/// BC2 and BC3 block) adds two colours at thirds; three-colour mode adds the midpoint and
/// transparent black.
pub(crate) fn colour_palette(c0: u16, c1: u16, four: bool) -> [[u8; 4]; 4] {
let (a, b) = (rgb565(c0), rgb565(c1));
let mix = |wa: u32, wb: u32| {
let d = wa + wb;
let at = |i: usize| ((wa * u32::from(a[i]) + wb * u32::from(b[i]) + d / 2) / d) as u8;
[at(0), at(1), at(2), 255]
};
if four {
[[a[0], a[1], a[2], 255], [b[0], b[1], b[2], 255], mix(2, 1), mix(1, 2)]
} else {
[[a[0], a[1], a[2], 255], [b[0], b[1], b[2], 255], mix(1, 1), [0; 4]]
}
}
/// A BC3 alpha block's eight values: six interpolated at sevenths when `a0 > a1`, else four
/// interpolated at fifths followed by 0 and 255.
pub(crate) fn alpha_palette(a0: u8, a1: u8) -> [u8; 8] {
let (a0, a1) = (u32::from(a0), u32::from(a1));
let mut palette = [a0, a1, 0, 0, 0, 0, 0, 255];
if a0 > a1 {
for (k, v) in palette.iter_mut().enumerate().skip(2) {
let k = k as u32;
*v = ((8 - k) * a0 + (k - 1) * a1 + 3) / 7;
}
} else {
for (k, v) in palette.iter_mut().enumerate().take(6).skip(2) {
let k = k as u32;
*v = ((6 - k) * a0 + (k - 1) * a1 + 2) / 5;
}
}
palette.map(|v| v as u8)
}
/// A BC1 block. Texels under half opacity become BC1's transparent black, which needs the
/// three-colour mode; an opaque block takes whichever mode fits its colours better.
pub(crate) fn encode_bc1(block: &Block, inside: Mask) -> [u8; 8] {
let transparent = select(block, inside, |t| t[3] < 128);
colour_block(block, inside & !transparent, transparent, true)
}
/// A BC2 block: four bits of alpha per texel, then a four-colour block.
pub(crate) fn encode_bc2(block: &Block, inside: Mask) -> [u8; 16] {
let bits = block.iter().enumerate().fold(0u64, |bits, (t, texel)| bits | ((u64::from(texel[3]) * 15 + 127) / 255) << (4 * t));
join(bits.to_le_bytes(), colour_block(block, inside, 0, false))
}
/// A BC3 block: an interpolated alpha block, then a four-colour block.
pub(crate) fn encode_bc3(block: &Block, inside: Mask) -> [u8; 16] {
join(alpha_block(block, inside), colour_block(block, inside, 0, false))
}
fn join(a: [u8; 8], b: [u8; 8]) -> [u8; 16] {
std::array::from_fn(|i| if i < 8 { a.get(i) } else { b.get(i - 8) }.copied().unwrap_or(0))
}
/// The texels of `inside` for which `f` holds.
fn select(block: &Block, inside: Mask, f: impl Fn(&[u8; 4]) -> bool) -> Mask {
block.iter().enumerate().filter(|(t, texel)| inside >> t & 1 != 0 && f(texel)).fold(0, |m, (t, _)| m | 1 << t)
}
fn rgb_of(texel: &[u8; 4]) -> [f32; 3] {
[f32::from(texel[0]), f32::from(texel[1]), f32::from(texel[2])]
}
/// RGB565 of a colour, rounding each channel to the nearest level.
fn to565(c: [f32; 3]) -> u16 {
let q = |v: f32, max: f32| (v.clamp(0.0, 255.0) * max / 255.0).round() as u16;
q(c[0], 31.0) << 11 | q(c[1], 63.0) << 5 | q(c[2], 31.0)
}
fn distance(a: &[u8; 4], b: &[u8; 4]) -> u32 {
(0..3).map(|i| u32::from(a[i].abs_diff(b[i])).pow(2)).sum()
}
/// A colour block (endpoints, then 2-bit indices) for the `opaque` texels' colours, with the
/// `transparent` ones on BC1's transparent index. `bc1` allows the three-colour mode; BC2 and
/// BC3 always decode four colours.
fn colour_block(block: &Block, opaque: Mask, transparent: Mask, bc1: bool) -> [u8; 8] {
let colours: Vec<[f32; 3]> = block.iter().enumerate().filter(|(t, _)| opaque >> t & 1 != 0).map(|(_, texel)| rgb_of(texel)).collect();
if colours.is_empty() {
// Nothing visible: every texel on the transparent index (or index 0 of black).
let indices = if transparent != 0 { u32::MAX } else { 0 };
return pack(0, 0, indices);
}
let (lo, hi) = principal_endpoints(&colours);
let mut candidates = vec![(to565(lo), to565(hi))];
let modes: &[bool] = if transparent != 0 {
&[false]
} else if bc1 {
&[true, false]
} else {
&[true]
};
let mut best: Option<(u32, [u8; 8])> = None;
// Each refinement starts from the best block so far: its indices give the least-squares
// endpoints, which become one more candidate.
for round in 0..3 {
for &(e0, e1) in &candidates {
for &four in modes {
let (bytes, error) = fit(block, opaque, transparent, e0, e1, four);
if best.is_none_or(|(e, _)| error < e) {
best = Some((error, bytes));
}
}
}
let Some((error, bytes)) = best else { break };
if error == 0 || round == 2 {
break;
}
candidates = least_squares(block, opaque, &bytes).into_iter().collect();
if candidates.is_empty() {
break;
}
}
best.map_or([0; 8], |(_, bytes)| bytes)
}
/// Orders endpoints `e0`, `e1` for the mode (`c0 > c1` for four colours, `c0 <= c1` for three)
/// and picks each texel's nearest palette colour. Returns the block and its squared error.
fn fit(block: &Block, opaque: Mask, transparent: Mask, e0: u16, e1: u16, four: bool) -> ([u8; 8], u32) {
let (c0, c1) = if four == (e0 >= e1) { (e0, e1) } else { (e1, e0) };
// Equal endpoints can't be in four-colour order; the palette is then one colour either way.
let palette = colour_palette(c0, c1, four && c0 > c1);
let choices = if four && c0 > c1 { 4 } else { 3 };
let mut indices = 0u32;
let mut error = 0u32;
for (t, texel) in block.iter().enumerate() {
let index = if transparent >> t & 1 != 0 {
3
} else if opaque >> t & 1 != 0 {
let (i, d) = palette.iter().take(choices).enumerate().map(|(i, p)| (i, distance(texel, p))).min_by_key(|&(_, d)| d).unwrap_or((0, 0));
error += d;
i as u32
} else {
0
};
indices |= index << (2 * t);
}
(pack(c0, c1, indices), error)
}
fn pack(c0: u16, c1: u16, indices: u32) -> [u8; 8] {
let (c0, c1, i) = (c0.to_le_bytes(), c1.to_le_bytes(), indices.to_le_bytes());
[c0[0], c0[1], c1[0], c1[1], i[0], i[1], i[2], i[3]]
}
/// The ends of the colours' spread along their principal axis (the covariance's dominant
/// eigenvector, by power iteration), clamped to the RGB cube.
fn principal_endpoints(colours: &[[f32; 3]]) -> ([f32; 3], [f32; 3]) {
let n = colours.len().max(1) as f32;
let mean = [0, 1, 2].map(|i| colours.iter().map(|c| c[i]).sum::<f32>() / n);
let mut cov = [[0f32; 3]; 3];
for c in colours {
let d = [c[0] - mean[0], c[1] - mean[1], c[2] - mean[2]];
for (i, row) in cov.iter_mut().enumerate() {
for (j, v) in row.iter_mut().enumerate() {
*v += d[i] * d[j];
}
}
}
let times = |a: [f32; 3]| [0, 1, 2].map(|i| cov[i][0] * a[0] + cov[i][1] * a[1] + cov[i][2] * a[2]);
let iterate = |start: usize| {
let mut axis = [0f32; 3];
axis[start] = 1.0;
for _ in 0..8 {
let next = times(axis);
let len = next.iter().map(|v| v * v).sum::<f32>().sqrt();
if !len.is_normal() {
break;
}
axis = next.map(|v| v / len);
}
axis
};
// From each channel's axis, keeping the one the colours spread along most: a channel that
// varies on its own is already an eigenvector, so a single start there would never leave it
// even when the others vary more together.
let spread = |a: [f32; 3]| times(a).iter().zip(a).map(|(x, y)| x * y).sum::<f32>();
let axis = [0, 1, 2].map(iterate).into_iter().max_by(|&a, &b| spread(a).total_cmp(&spread(b))).unwrap_or([1.0, 0.0, 0.0]);
let along = |c: &[f32; 3]| (c[0] - mean[0]) * axis[0] + (c[1] - mean[1]) * axis[1] + (c[2] - mean[2]) * axis[2];
let (lo, hi) = colours.iter().map(along).fold((f32::MAX, f32::MIN), |(lo, hi), t| (lo.min(t), hi.max(t)));
let at = |t: f32| [0, 1, 2].map(|i| (mean[i] + t * axis[i]).clamp(0.0, 255.0));
if lo > hi { (mean, mean) } else { (at(lo), at(hi)) }
}
/// The endpoints that minimise the squared error for the indices `bytes` already chose: each
/// texel's index fixes its weights between the endpoints, giving 2×2 normal equations per
/// channel. `None` when the indices don't constrain both endpoints.
fn least_squares(block: &Block, opaque: Mask, bytes: &[u8; 8]) -> Option<(u16, u16)> {
let (c0, c1) = (u16::from_le_bytes([bytes[0], bytes[1]]), u16::from_le_bytes([bytes[2], bytes[3]]));
let indices = u32::from_le_bytes([bytes[4], bytes[5], bytes[6], bytes[7]]);
let four = c0 > c1;
// How much of c0 each index holds.
let weight = |i: u32| match (four, i) {
(_, 0) => Some(1.0f32),
(_, 1) => Some(0.0),
(true, 2) => Some(2.0 / 3.0),
(true, _) => Some(1.0 / 3.0),
(false, 2) => Some(0.5),
(false, _) => None,
};
let (mut aa, mut ab, mut bb) = (0f32, 0f32, 0f32);
let (mut ax, mut bx) = ([0f32; 3], [0f32; 3]);
for (t, texel) in block.iter().enumerate() {
if opaque >> t & 1 == 0 {
continue;
}
let Some(a) = weight(indices >> (2 * t) & 3) else { continue };
let b = 1.0 - a;
let c = rgb_of(texel);
aa += a * a;
ab += a * b;
bb += b * b;
for ((x0, x1), v) in ax.iter_mut().zip(bx.iter_mut()).zip(c) {
*x0 += a * v;
*x1 += b * v;
}
}
let det = aa * bb - ab * ab;
if det.abs() < 1e-3 {
return None;
}
let e0 = [0, 1, 2].map(|i| (ax[i] * bb - bx[i] * ab) / det);
let e1 = [0, 1, 2].map(|i| (bx[i] * aa - ax[i] * ab) / det);
Some((to565(e0), to565(e1)))
}
/// A BC3 alpha block: whichever of the two modes (eight values between the extremes, or six
/// between the extremes other than 0 and 255, plus exact 0 and 255) fits better.
fn alpha_block(block: &Block, inside: Mask) -> [u8; 8] {
let alphas = || block.iter().enumerate().filter(move |(t, _)| inside >> t & 1 != 0).map(|(_, texel)| texel[3]);
let range =
|values: &mut dyn Iterator<Item = u8>| values.fold(None, |r: Option<(u8, u8)>, a| Some(r.map_or((a, a), |(lo, hi)| (lo.min(a), hi.max(a)))));
let (lo, hi) = range(&mut alphas()).unwrap_or((0, 0));
// Eight values need a0 > a1; equal ends fall to the six-value mode, which starts with a0 too.
let eight = alpha_fit(block, inside, hi, lo);
let (mid_lo, mid_hi) = range(&mut alphas().filter(|a| !matches!(a, 0 | 255))).unwrap_or((0, 0));
let six = alpha_fit(block, inside, mid_lo, mid_hi);
if six.1 < eight.1 { six.0 } else { eight.0 }
}
fn alpha_fit(block: &Block, inside: Mask, a0: u8, a1: u8) -> ([u8; 8], u32) {
let palette = alpha_palette(a0, a1);
let mut bits = 0u64;
let mut error = 0u32;
for (t, texel) in block.iter().enumerate() {
if inside >> t & 1 == 0 {
continue;
}
let (i, d) = palette.iter().enumerate().map(|(i, &p)| (i, u32::from(p.abs_diff(texel[3])).pow(2))).min_by_key(|&(_, d)| d).unwrap_or((0, 0));
error += d;
bits |= (i as u64) << (3 * t);
}
let b = bits.to_le_bytes();
([a0, a1, b[0], b[1], b[2], b[3], b[4], b[5]], error)
}
#[cfg(test)]
mod tests {
use super::*;
fn decode_colour(bytes: &[u8; 8], bc1: bool) -> Block {
let (c0, c1) = (u16::from_le_bytes([bytes[0], bytes[1]]), u16::from_le_bytes([bytes[2], bytes[3]]));
let palette = colour_palette(c0, c1, c0 > c1 || !bc1);
let indices = u32::from_le_bytes([bytes[4], bytes[5], bytes[6], bytes[7]]);
std::array::from_fn(|t| palette[(indices >> (2 * t)) as usize & 3])
}
#[test]
fn solid_blocks_land_on_the_nearest_565_colour() {
for colour in [[0, 0, 0, 255], [255, 255, 255, 255], [12, 200, 77, 255]] {
let block = [colour; 16];
let out = decode_colour(&encode_bc1(&block, u16::MAX), true);
for texel in out {
assert!(texel.iter().zip(colour).all(|(a, b)| a.abs_diff(b) <= 4), "{texel:?} for {colour:?}");
}
}
}
#[test]
fn two_colour_blocks_are_exact_when_the_colours_are_565() {
let (a, b) = ([255, 0, 0, 255], [0, 0, 255, 255]);
let block: Block = std::array::from_fn(|t| if t % 3 == 0 { a } else { b });
for bc1 in [true, false] {
let bytes = if bc1 { encode_bc1(&block, u16::MAX) } else { colour_block(&block, u16::MAX, 0, false) };
assert_eq!(decode_colour(&bytes, bc1), block);
}
}
#[test]
fn bc1_punches_through_texels_under_half_alpha() {
let block: Block = std::array::from_fn(|t| if t < 8 { [200, 100, 50, 255] } else { [9, 9, 9, 127] });
let bytes = encode_bc1(&block, u16::MAX);
let (c0, c1) = (u16::from_le_bytes([bytes[0], bytes[1]]), u16::from_le_bytes([bytes[2], bytes[3]]));
assert!(c0 <= c1, "three-colour mode");
let out = decode_colour(&bytes, true);
assert!(out[..8].iter().all(|t| t[3] == 255) && out[8..].iter().all(|t| *t == [0; 4]), "{out:?}");
}
#[test]
fn four_colour_blocks_keep_c0_above_c1() {
// A ramp needs all four colours; BC2 and BC3 blocks must not rely on the order, but
// older decoders read c0 <= c1 as three colours, so the encoder never writes that.
let block: Block = std::array::from_fn(|t| [(t * 16) as u8, 0, 0, 255]);
let bytes = colour_block(&block, u16::MAX, 0, false);
assert!(u16::from_le_bytes([bytes[0], bytes[1]]) > u16::from_le_bytes([bytes[2], bytes[3]]));
}
#[test]
fn alpha_blocks_pick_the_mode_that_keeps_0_and_255() {
// 0, 255 and a cluster in between: the six-value mode stores 0 and 255 exactly.
let block: Block = std::array::from_fn(|t| [0, 0, 0, [0, 255, 100, 110][t % 4]]);
let bytes = alpha_block(&block, u16::MAX);
assert!(bytes[0] <= bytes[1], "six-value mode");
let palette = alpha_palette(bytes[0], bytes[1]);
let bits = u64::from_le_bytes([bytes[2], bytes[3], bytes[4], bytes[5], bytes[6], bytes[7], 0, 0]);
for (t, texel) in block.iter().enumerate() {
let got = palette[(bits >> (3 * t)) as usize & 7];
assert!(got.abs_diff(texel[3]) <= 2, "texel {t}: {got} for {}", texel[3]);
}
}
#[test]
fn the_principal_axis_is_found_when_one_channel_varies_on_its_own() {
// Red alternates on its own (variance 64); green and blue alternate together (variance 49
// each, 98 along their shared axis), uncorrelated with red. Starting on red alone would
// keep red's axis and flatten green and blue; the block must do better than its bounding box.
let block: Block = std::array::from_fn(|t| {
let gb = if (t / 2) % 2 == 0 { 121 } else { 135 };
[if t % 2 == 0 { 120 } else { 136 }, gb, gb, 255]
});
let error = |bytes: &[u8; 8]| decode_colour(bytes, false).iter().zip(&block).map(|(a, b)| distance(a, b)).sum::<u32>();
let (_, bounding_box) = fit(&block, u16::MAX, 0, to565([120.0, 121.0, 121.0]), to565([136.0, 135.0, 135.0]), true);
let ours = error(&colour_block(&block, u16::MAX, 0, false));
assert!(ours < bounding_box, "{ours} vs the bounding box's {bounding_box}");
}
#[test]
fn texels_outside_the_image_are_ignored() {
// Only the top-left texel is inside: its colour alone decides the endpoints.
let mut block: Block = [[0, 255, 0, 255]; 16];
block[0] = [255, 0, 255, 255];
let out = decode_colour(&encode_bc1(&block, 1), true);
assert_eq!(out[0], [255, 0, 255, 255]);
}
}
+7 -523
View File
@@ -1,526 +1,10 @@
//! DICOM (medical imaging) reader, uncompressed transfer syntaxes only.
//!
//! Supports what a viewer needs from a single-frame image: MONOCHROME1/2 (gray) and RGB or
//! YBR_FULL, 8- and 16-bit samples, interleaved or planar, both byte orders and explicit or
//! implicit VR. Undefined-length sequences outside the pixel data are skipped (clinical files
//! contain them); compressed transfer syntaxes, encapsulated pixel data and other photometric
//! interpretations are refused with a clear error. Read-only in this crate.
//! DICOM compatibility facade; implementation and detection live in craft-image-codecs.
use crate::{CodecError, Image, Limits, bridge};
use craft_image_codecs::Format;
use std::collections::HashMap;
use crate::{ChannelLayout, CodecError, Image, Limits, SampleType};
const F: &str = "DICOM";
const PREAMBLE: usize = 132; // 128 zero bytes + "DICM"
const UNDEFINED: u32 = 0xFFFF_FFFF;
fn bad(msg: impl std::fmt::Display) -> CodecError {
CodecError::malformed(F, msg)
pub fn is_dicom(bytes: &[u8]) -> bool {
craft_image_codecs::detect(bytes) == Some(Format::Dicom)
}
/// A DICOM file begins with a 128-byte preamble and the `DICM` magic.
pub fn is_dicom(b: &[u8]) -> bool {
b.get(128..132) == Some(b"DICM")
}
#[derive(Clone, Copy)]
struct Endian {
big: bool,
}
/// The transfer syntax: byte order and whether value representations are explicit.
#[derive(Clone, Copy)]
struct Syntax {
endian: Endian,
explicit: bool,
}
/// The value representations whose length field is 2 reserved bytes + `u32` in explicit VR.
fn long_vr(vr: &[u8]) -> bool {
matches!(vr, b"OB" | b"OW" | b"OF" | b"SQ" | b"UT" | b"UN" | b"OD" | b"OL" | b"OV" | b"UC" | b"UR")
}
/// A cursor over the byte stream.
struct Cur<'a> {
b: &'a [u8],
pos: usize,
big: bool,
}
impl<'a> Cur<'a> {
fn take(&mut self, n: usize) -> Option<&'a [u8]> {
let s = self.b.get(self.pos..self.pos.checked_add(n)?)?;
self.pos += n;
Some(s)
}
fn u16(&mut self) -> Option<u16> {
let c = self.take(2)?;
Some(if self.big { u16::from_be_bytes([c[0], c[1]]) } else { u16::from_le_bytes([c[0], c[1]]) })
}
fn u32(&mut self) -> Option<u32> {
let c = self.take(4)?;
Some(if self.big { u32::from_be_bytes([c[0], c[1], c[2], c[3]]) } else { u32::from_le_bytes([c[0], c[1], c[2], c[3]]) })
}
/// Skip `len` bytes, refusing to run past the buffer.
fn skip(&mut self, len: usize) -> Result<(), CodecError> {
self.pos = self.pos.checked_add(len).filter(|p| *p <= self.b.len()).ok_or_else(|| bad("a value runs past the end of the file"))?;
Ok(())
}
}
/// Read one element's tag and value length, leaving the cursor at the value. Item and delimiter
/// tags (group `FFFE`) carry a `u32` length with no VR even under explicit VR.
fn read_header(c: &mut Cur, syn: &Syntax) -> Result<(u16, u16, [u8; 2], u32), CodecError> {
let group = c.u16().ok_or_else(|| bad("truncated element tag"))?;
let elem = c.u16().ok_or_else(|| bad("truncated element tag"))?;
let (vr, len) = if group == 0xFFFE {
([0, 0], c.u32().ok_or_else(|| bad("truncated item length"))?)
} else if syn.explicit {
let vr = c.take(2).ok_or_else(|| bad("truncated VR"))?;
let v = [vr[0], vr[1]];
let len = if long_vr(&v) {
c.take(2).ok_or_else(|| bad("truncated VR"))?; // reserved
c.u32().ok_or_else(|| bad("truncated length"))?
} else {
u32::from(c.u16().ok_or_else(|| bad("truncated length"))?)
};
(v, len)
} else {
([0, 0], c.u32().ok_or_else(|| bad("truncated length"))?)
};
Ok((group, elem, vr, len))
}
/// Skip an undefined-length sequence, ending just after its `FFFE,E0DD` delimiter. Nesting is
/// tracked through undefined-length items and nested sequences; everything else is skipped by
/// its length. Returns the position after the delimiter.
fn skip_undefined(c: &mut Cur, syn: &Syntax) -> Result<(), CodecError> {
let mut depth = 1u32;
while depth > 0 {
let (group, elem, _, len) = read_header(c, syn)?;
// Item (E00D) and sequence (E0DD) delimiters close one undefined length; they carry no
// content of their own.
if group == 0xFFFE && matches!(elem, 0xE00D | 0xE0DD) {
depth -= 1;
continue;
}
if len == UNDEFINED {
depth += 1;
} else {
c.skip(len as usize)?;
}
}
Ok(())
}
/// Walk the elements from `start`, calling `f` with each `(group, element, value)`. An
/// undefined-length sequence outside the pixel data is skipped; encapsulated (undefined-length)
/// pixel data is refused. Returns the number of bytes walked.
fn elements(b: &[u8], start: usize, syn: &Syntax, mut f: impl FnMut(u16, u16, &Elem) -> Result<(), CodecError>) -> Result<usize, CodecError> {
let mut c = Cur { b, pos: start, big: syn.endian.big };
loop {
if c.pos >= b.len() {
return Ok(c.pos - start);
}
let (group, elem, vr, len) = read_header(&mut c, syn)?;
if len == UNDEFINED {
if (group, elem) == (0x7FE0, 0x0010) {
return Err(CodecError::unsupported(F, "encapsulated (compressed) pixel data"));
}
skip_undefined(&mut c, syn)?;
continue;
}
let len = len as usize;
let start = c.pos;
if b.len() < start.saturating_add(len) {
return Err(bad("an element value runs past the end of the file"));
}
f(group, elem, &Elem { vr, start, len })?;
c.pos = start + len;
}
}
/// A parsed element: its VR and the byte range of its value.
struct Elem {
vr: [u8; 2],
start: usize,
len: usize,
}
fn u16_val(b: &[u8], e: &Elem, big: bool) -> Option<u16> {
let c = b.get(e.start..e.start.checked_add(2)?)?;
Some(if big { u16::from_be_bytes([c[0], c[1]]) } else { u16::from_le_bytes([c[0], c[1]]) })
}
/// The transfer syntax (byte order and explicit/implicit VR) and the data-set start. The file
/// meta group is always explicit VR little-endian; the data set follows its `(0002,0010)`
/// TransferSyntaxUID.
fn transfer_syntax(b: &[u8]) -> Result<(Syntax, usize), CodecError> {
let meta = Syntax { endian: Endian { big: false }, explicit: true };
let mut ts: Option<String> = None;
let mut data_start = b.len();
let mut c = Cur { b, pos: PREAMBLE, big: false };
while c.pos + 8 <= b.len() {
let save = c.pos;
let (group, elem, _, len) = read_header(&mut c, &meta)?;
if group != 0x0002 {
// A non-meta group begins the data set.
data_start = save;
break;
}
if len == UNDEFINED {
return Err(CodecError::unsupported(F, "undefined-length meta element"));
}
let start = c.pos;
if b.len() < start.saturating_add(len as usize) {
return Err(bad("a meta element runs past the end of the file"));
}
if elem == 0x0010 {
ts = Some(String::from_utf8_lossy(&b[start..start + len as usize]).trim_end_matches(['\0', ' ']).to_string());
}
c.pos = start + len as usize;
}
let syn = match ts.as_deref() {
Some("1.2.840.10008.1.2") => Syntax { endian: Endian { big: false }, explicit: false },
Some("1.2.840.10008.1.2.1") => Syntax { endian: Endian { big: false }, explicit: true },
Some("1.2.840.10008.1.2.2") => Syntax { endian: Endian { big: true }, explicit: true },
Some(other) => return Err(CodecError::unsupported(F, format!("transfer syntax {other} (only uncompressed is read)"))),
// No meta: the historical default is implicit VR little-endian.
None => Syntax { endian: Endian { big: false }, explicit: false },
};
Ok((syn, data_start))
}
pub fn decode(b: &[u8], limits: &Limits) -> Result<Image, CodecError> {
if !is_dicom(b) {
return Err(bad("not a DICOM file (no DICM magic)"));
}
let (syn, start) = transfer_syntax(b)?;
let mut tags: HashMap<(u16, u16), Elem> = HashMap::new();
elements(b, start, &syn, |g, e, el| {
// Later duplicates must not silently override the first (DICOM forbids duplicates).
tags.entry((g, e)).or_insert_with(|| Elem { vr: el.vr, start: el.start, len: el.len });
Ok(())
})?;
let big = syn.endian.big;
let get_u16 = |tag: (u16, u16)| tags.get(&tag).and_then(|e| u16_val(b, e, big));
let rows = u32::from(get_u16((0x0028, 0x0010)).ok_or_else(|| bad("missing Rows (0028,0010)"))?);
let cols = u32::from(get_u16((0x0028, 0x0011)).ok_or_else(|| bad("missing Columns (0028,0011)"))?);
let samples = u32::from(get_u16((0x0028, 0x0002)).unwrap_or(1));
let bits = get_u16((0x0028, 0x0100)).ok_or_else(|| bad("missing BitsAllocated (0028,0100)"))?;
let bits_stored = get_u16((0x0028, 0x0101)).unwrap_or(bits);
let high_bit = get_u16((0x0028, 0x0102)).unwrap_or(bits_stored.saturating_sub(1));
if u32::from(high_bit) >= u32::from(bits) {
return Err(bad("HighBit is outside the allocated bits"));
}
let signed = get_u16((0x0028, 0x0103)).unwrap_or(0) == 1;
let planar = get_u16((0x0028, 0x0006)).unwrap_or(0);
let photometric = tags
.get(&(0x0028, 0x0004))
.and_then(|e| b.get(e.start..e.start.checked_add(e.len)?))
.map(|v| String::from_utf8_lossy(v).trim_end_matches(['\0', ' ']).to_string())
.ok_or_else(|| bad("missing PhotometricInterpretation (0028,0004)"))?;
let pixel = tags.get(&(0x7FE0, 0x0010)).ok_or_else(|| CodecError::unsupported(F, "no pixel data (7FE0,0010)"))?;
if !matches!(bits, 8 | 16) || !matches!(bits_stored, 1..=16) {
return Err(CodecError::unsupported(F, format!("{bits}-bit allocated / {bits_stored}-bit stored samples")));
}
let mono = matches!(photometric.as_str(), "MONOCHROME1" | "MONOCHROME2");
let rgb = photometric == "RGB";
let ybr = photometric == "YBR_FULL";
if !(mono || rgb || ybr) {
return Err(CodecError::unsupported(F, format!("photometric interpretation {photometric}")));
}
// Mono stores one sample; RGB and YBR_FULL store three. Any other count would index past the
// pixel data, so it is refused rather than misread.
let want_samples = if mono { 1 } else { 3 };
if samples != want_samples {
return Err(CodecError::unsupported(F, format!("{samples} samples per pixel with {photometric}")));
}
if ybr && bits != 8 {
return Err(CodecError::unsupported(F, format!("{bits}-bit {photometric} (8-bit only)")));
}
let layout = if mono { ChannelLayout::Gray } else { ChannelLayout::Rgb };
let out_sample = if bits == 8 { SampleType::U8 } else { SampleType::U16 };
limits.check(cols, rows, layout, out_sample)?;
let pixels = (cols as usize).checked_mul(rows as usize).ok_or_else(|| CodecError::LimitExceeded("image too large".into()))?;
let n = pixels.checked_mul(samples as usize).ok_or_else(|| CodecError::LimitExceeded("image too large".into()))?;
let bytes_per = if bits == 16 { 2usize } else { 1 };
let need = n.checked_mul(bytes_per).ok_or_else(|| CodecError::LimitExceeded("pixel data too large".into()))?;
let data = b
.get(pixel.start..pixel.start.checked_add(need).ok_or_else(|| CodecError::LimitExceeded("pixel data too large".into()))?)
.ok_or_else(|| bad("pixel data is truncated"))?;
let out_channels = layout.channels();
let out_len =
pixels.checked_mul(out_channels).and_then(|k| k.checked_mul(bytes_per)).ok_or_else(|| CodecError::LimitExceeded("image too large".into()))?;
let mut out = Vec::new();
out.try_reserve_exact(out_len).map_err(|_| CodecError::LimitExceeded("cannot allocate the image".into()))?;
// Raw sample of channel `ch` at pixel `p`, honouring the planar configuration.
let sample_at = |p: usize, ch: usize| -> Option<u32> {
let idx = if planar == 1 { ch.checked_mul(pixels)?.checked_add(p)? } else { p.checked_mul(samples as usize)?.checked_add(ch)? };
let off = idx.checked_mul(bytes_per)?;
if bits == 16 {
let c = data.get(off..off.checked_add(2)?)?;
Some(if big { u16::from_be_bytes([c[0], c[1]]) } else { u16::from_le_bytes([c[0], c[1]]) }.into())
} else {
Some(u32::from(*data.get(off)?))
}
};
let stored_max = f64::from((1u32 << bits_stored) - 1);
// Extract the `bits_stored` samples (the least significant one at `high_bit`) and scale to
// [0, 1]; signed values are shifted up by half a range first. `high_bit` is 1-based here.
let shift = (u32::from(high_bit) + 1).saturating_sub(u32::from(bits_stored));
let mask = (1u32 << bits_stored) - 1;
let half = 1u32 << (bits_stored - 1);
let norm = move |raw: u32| -> f64 {
let v = (raw >> shift) & mask;
// Signed: flip the sign bit to map [-2^(b-1), 2^(b-1)-1] onto [0, 2^b-1].
let v = if signed { v ^ half } else { v };
(f64::from(v) / stored_max).clamp(0.0, 1.0)
};
let q = |x: f64| -> u16 { (x * 65535.0).round() as u16 };
let push = |out: &mut Vec<u8>, x: f64| {
if bits == 8 {
out.push((x * 255.0).round() as u8);
} else {
out.extend_from_slice(&q(x).to_ne_bytes());
}
};
for p in 0..pixels {
let s = |ch: usize| sample_at(p, ch).ok_or_else(|| bad("pixel data is shorter than the image"));
if mono {
let x = norm(s(0)?);
push(&mut out, if photometric == "MONOCHROME1" { 1.0 - x } else { x });
} else if rgb {
for ch in 0..3 {
push(&mut out, norm(s(ch)?));
}
} else {
// YBR_FULL (8-bit): BT.601 full-range to RGB.
let y = f64::from(s(0)?);
let cb = f64::from(s(1)?) - 128.0;
let cr = f64::from(s(2)?) - 128.0;
let r = (y + 1.402 * cr).clamp(0.0, 255.0);
let g = (y - 0.344_136 * cb - 0.714_136 * cr).clamp(0.0, 255.0);
let bl = (y + 1.772 * cb).clamp(0.0, 255.0);
for v in [r, g, bl] {
push(&mut out, v / 255.0);
}
}
}
Image::from_raw(cols, rows, layout, out_sample, out)
}
#[cfg(test)]
mod tests {
use super::*;
/// Build the file meta group (explicit VR little-endian), including the given extra
/// `(element, ascii)` pairs before the TransferSyntaxUID.
fn meta(b: &mut Vec<u8>, ts: &str, extra: &[(u16, &str)]) {
let ui = |e: u16, v: &str, b: &mut Vec<u8>| {
let mut s = v.as_bytes().to_vec();
if s.len() % 2 == 1 {
s.push(0);
}
b.extend_from_slice(&0x0002u16.to_le_bytes());
b.extend_from_slice(&e.to_le_bytes());
b.extend_from_slice(b"UI");
b.extend_from_slice(&(s.len() as u16).to_le_bytes());
b.extend_from_slice(&s);
};
for (e, v) in extra {
ui(*e, v, b);
}
ui(0x0010, ts, b);
}
fn us(b: &mut Vec<u8>, g: u16, e: u16, v: u16, explicit: bool) {
b.extend_from_slice(&g.to_le_bytes());
b.extend_from_slice(&e.to_le_bytes());
if explicit {
b.extend_from_slice(b"US");
b.extend_from_slice(&2u16.to_le_bytes());
} else {
b.extend_from_slice(&2u32.to_le_bytes());
}
b.extend_from_slice(&v.to_le_bytes());
}
fn cs(b: &mut Vec<u8>, g: u16, e: u16, v: &str, explicit: bool) {
let mut s = v.as_bytes().to_vec();
if s.len() % 2 == 1 {
s.push(0);
}
b.extend_from_slice(&g.to_le_bytes());
b.extend_from_slice(&e.to_le_bytes());
if explicit {
b.extend_from_slice(b"CS");
b.extend_from_slice(&(s.len() as u16).to_le_bytes());
} else {
b.extend_from_slice(&(s.len() as u32).to_le_bytes());
}
b.extend_from_slice(&s);
}
/// A DICOM with the given transfer syntax UID and data-set encoding.
#[allow(clippy::too_many_arguments)]
fn synth(
ts: &str,
explicit: bool,
big: bool,
planar: u16,
rows: u16,
cols: u16,
samples: u16,
bits: u16,
photometric: &str,
pixels: &[u8],
) -> Vec<u8> {
let mut b = vec![0u8; 128];
b.extend_from_slice(b"DICM");
// One extra meta element before the syntax, so a reader that only looks at the last
// group-0002 element takes the wrong one.
meta(&mut b, ts, &[(0x0002, "1.2.840.10008.5.1.4.1.1.7")]);
let _ = big;
us(&mut b, 0x0028, 0x0010, rows, explicit);
us(&mut b, 0x0028, 0x0011, cols, explicit);
us(&mut b, 0x0028, 0x0002, samples, explicit);
us(&mut b, 0x0028, 0x0006, planar, explicit);
cs(&mut b, 0x0028, 0x0004, photometric, explicit);
us(&mut b, 0x0028, 0x0100, bits, explicit);
us(&mut b, 0x0028, 0x0101, bits, explicit);
us(&mut b, 0x0028, 0x0102, bits - 1, explicit);
us(&mut b, 0x0028, 0x0103, 0, explicit);
b.extend_from_slice(&0x7FE0u16.to_le_bytes());
b.extend_from_slice(&0x0010u16.to_le_bytes());
if explicit {
b.extend_from_slice(b"OB");
b.extend_from_slice(&0u16.to_le_bytes());
}
b.extend_from_slice(&(pixels.len() as u32).to_le_bytes());
b.extend_from_slice(pixels);
b
}
#[test]
fn decodes_8bit_monochrome() {
let b = synth("1.2.840.10008.1.2.1", true, false, 0, 2, 2, 1, 8, "MONOCHROME2", &[0, 51, 102, 255]);
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!((img.width(), img.height(), img.layout(), img.sample_type()), (2, 2, ChannelLayout::Gray, SampleType::U8));
assert_eq!(img.data(), &[0, 51, 102, 255]);
}
#[test]
fn decodes_16bit_monochrome_and_scales() {
let px: Vec<u8> = [0u16, 32768, 65535].iter().flat_map(|v| v.to_le_bytes()).collect();
let b = synth("1.2.840.10008.1.2.1", true, false, 0, 3, 1, 1, 16, "MONOCHROME2", &px);
let img = decode(&b, &Limits::default()).unwrap();
let v = img.to_u16_samples().unwrap();
assert_eq!(v[0], 0);
assert!((i32::from(v[1]) - 32768).abs() <= 1);
assert_eq!(v[2], 65535);
}
#[test]
fn monochrome1_is_inverted() {
let b = synth("1.2.840.10008.1.2.1", true, false, 0, 2, 1, 1, 8, "MONOCHROME1", &[0, 255]);
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!(img.data(), &[255, 0]);
}
#[test]
fn decodes_rgb_interleaved_and_planar() {
// 2 pixels: (10,20,30) and (40,50,60).
let interleaved = synth("1.2.840.10008.1.2.1", true, false, 0, 1, 2, 3, 8, "RGB", &[10, 20, 30, 40, 50, 60]);
let img = decode(&interleaved, &Limits::default()).unwrap();
assert_eq!((img.layout(), img.data()), (ChannelLayout::Rgb, &[10u8, 20, 30, 40, 50, 60][..]));
// Planar 0: R plane, then G, then B.
let planar = synth("1.2.840.10008.1.2.1", true, false, 1, 1, 2, 3, 8, "RGB", &[10, 40, 20, 50, 30, 60]);
let img = decode(&planar, &Limits::default()).unwrap();
assert_eq!(img.data(), &[10, 20, 30, 40, 50, 60]);
}
#[test]
fn decodes_ybr_full_to_rgb() {
// White (Y=128, Cb=Cr=128) stays neutral grey.
let b = synth("1.2.840.10008.1.2.1", true, false, 0, 1, 1, 3, 8, "YBR_FULL", &[128, 128, 128]);
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!(img.layout(), ChannelLayout::Rgb);
let d = img.data();
assert!(d[0].abs_diff(d[1]) <= 1 && d[1].abs_diff(d[2]) <= 1, "{d:?}");
}
#[test]
fn decodes_implicit_vr() {
let b = synth("1.2.840.10008.1.2", false, false, 0, 2, 2, 1, 8, "MONOCHROME2", &[0, 51, 102, 255]);
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!(img.layout(), ChannelLayout::Gray);
assert_eq!(img.data(), &[0, 51, 102, 255]);
}
#[test]
fn skips_an_undefined_length_sequence_outside_the_pixel_data() {
// Insert an undefined-length SQ (0008,2218) with one item, then a defined-length one,
// before the pixel data: the reader must skip both and still decode the image.
let mut b = vec![0u8; 128];
b.extend_from_slice(b"DICM");
meta(&mut b, "1.2.840.10008.1.2.1", &[]);
for (g, e, v) in [
(0x0028, 0x0010, 1u16),
(0x0028, 0x0011, 1),
(0x0028, 0x0002, 1),
(0x0028, 0x0100, 8),
(0x0028, 0x0101, 8),
(0x0028, 0x0102, 7),
(0x0028, 0x0103, 0),
] {
us(&mut b, g, e, v, true);
}
cs(&mut b, 0x0028, 0x0004, "MONOCHROME2", true);
// Undefined-length sequence (0008,2211), one undefined-length item containing a nested
// defined-length sequence, then the delimiters.
b.extend_from_slice(&[0x08, 0x00, 0x11, 0x22, b'S', b'Q', 0x00, 0x00, 0xFF, 0xFF, 0xFF, 0xFF]);
b.extend_from_slice(&[0xFE, 0xFF, 0x00, 0xE0, 0xFF, 0xFF, 0xFF, 0xFF]); // item, undefined
b.extend_from_slice(&[0x08, 0x00, 0x55, 0x22, b'S', b'Q', 0x00, 0x00, 0x04, 0x00, 0x00, 0x00, 1, 2, 3, 4]); // nested, defined
b.extend_from_slice(&[0xFE, 0xFF, 0x0D, 0xE0, 0x00, 0x00, 0x00, 0x00]); // item delimitation
b.extend_from_slice(&[0xFE, 0xFF, 0xDD, 0xE0, 0x00, 0x00, 0x00, 0x00]); // sequence delimitation
// Pixel data (defined length).
b.extend_from_slice(&0x7FE0u16.to_le_bytes());
b.extend_from_slice(&0x0010u16.to_le_bytes());
b.extend_from_slice(b"OB");
b.extend_from_slice(&0u16.to_le_bytes());
b.extend_from_slice(&1u32.to_le_bytes());
b.push(200);
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!(img.data(), &[200]);
}
#[test]
fn truncated_and_bad_is_error_not_panic() {
let b = synth("1.2.840.10008.1.2.1", true, false, 0, 2, 2, 1, 8, "MONOCHROME2", &[0, 1, 2, 3]);
for cut in [0, 4, 128, 132, 140, b.len() - 1] {
assert!(decode(&b[..cut.min(b.len())], &Limits::default()).is_err(), "cut {cut}");
}
assert!(decode(b"not dicom", &Limits::default()).is_err());
}
#[test]
fn high_bit_outside_the_allocated_bits_is_an_error_not_a_panic() {
let mut b = synth("1.2.840.10008.1.2.1", true, false, 0, 1, 1, 1, 8, "MONOCHROME2", &[7]);
let tag = [0x28, 0x00, 0x02, 0x01, b'U', b'S', 0x02, 0x00];
let at = b.windows(tag.len()).position(|w| w == tag).unwrap() + tag.len();
b[at..at + 2].copy_from_slice(&200u16.to_le_bytes());
assert!(decode(&b, &Limits::default()).is_err());
}
#[test]
fn rejects_compressed_transfer_syntax() {
let mut b = synth("1.2.840.10008.1.2.1", true, false, 0, 1, 1, 1, 8, "MONOCHROME2", &[0]);
let uncompressed = b"1.2.840.10008.1.2.1\0";
let compressed = b"1.2.840.10008.1.2.4\0"; // same length, a compressed family
let at = b.windows(uncompressed.len()).position(|w| w == uncompressed).expect("transfer syntax in the fixture");
b[at..at + compressed.len()].copy_from_slice(compressed);
assert!(matches!(decode(&b, &Limits::default()), Err(CodecError::Unsupported { .. })));
}
pub fn decode(bytes: &[u8], limits: &Limits) -> Result<Image, CodecError> {
bridge::format(Format::Dicom, bytes, limits)
}
+11 -849
View File
@@ -1,857 +1,19 @@
//! FITS (Flexible Image Transport System, FITS Standard 4.0), implemented here: the image in the
//! primary HDU, or the first `IMAGE` extension when the primary HDU holds no data.
//!
//! Reading:
//!
//! * `BITPIX` 8, 16, 32, 64, -32 and -64, with `BSCALE`/`BZERO` and integer `BLANK`.
//! * `NAXIS3 = 3` opens as RGB (the planes are R, G, B); any other plane count opens the first
//! plane as gray with [`crate::DecodeWarning::MorePages`].
//! * Rows are stored bottom-to-top, as the standard's convention has it (Siril, DS9, Astropy),
//! unless `ROWORDER = 'TOP-DOWN'`.
//! * Physical values that fit (unsigned 8-bit, or integers in 0..=65535 such as a camera's
//! `BITPIX = 16`, `BZERO = 32768`) are kept exactly as U8/U16. Everything else becomes F32:
//! values up to 2 are taken as already normalised (Siril, PixInsight), larger ones are scaled by
//! 65535 when they fit in it (DeepSkyStacker, most stackers) and by the maximum otherwise. NaN
//! and blank pixels read as 0.
//! * The other header cards are kept as text: `KEY` → value (strings unquoted), `COMMENT` and
//! `HISTORY` by their text, `HIERARCH` keywords by their long name. Long strings continued
//! on `CONTINUE` cards are joined.
//!
//! Writing: gray or RGB, U8 (`BITPIX = 8`), U16 (`BITPIX = 16`, `BZERO = 32768`) or F32
//! (`BITPIX = -32`, 0..1), bottom-to-top with `ROWORDER = 'BOTTOM-UP'`, plus the text cards
//! (strings longer than one card on `CONTINUE` cards).
//! Tile-compressed files (fpack `ZIMAGE` tables) are recognised and refused.
//! FITS compatibility facade; implementation lives in craft-image-codecs.
use crate::{CodecError, Image, Limits, bridge};
use craft_image_codecs::Format;
use std::collections::HashMap;
use crate::{ChannelLayout, CodecError, DecodeWarning, Image, Limits, SampleType};
const F: &str = "FITS";
const BLOCK: usize = 2880;
const CARD: usize = 80;
/// Most HDUs walked looking for an image; FITS files from cameras and stackers hold a handful.
const MAX_HDUS: usize = 1000;
/// Keywords that describe the data layout. They are written from the image, never copied from
/// (or kept as) text metadata: after decoding they no longer describe the pixels.
const STRUCTURAL: &[&str] = &[
"SIMPLE", "BITPIX", "NAXIS", "EXTEND", "BZERO", "BSCALE", "BLANK", "END", "XTENSION", "PCOUNT", "GCOUNT", "ROWORDER", "CHECKSUM", "DATASUM",
"DATAMIN", "DATAMAX", "ZIMAGE",
];
fn err(msg: impl std::fmt::Display) -> CodecError {
CodecError::malformed(F, msg)
pub fn looks_like_fits(bytes: &[u8]) -> bool {
craft_image_codecs::detect(bytes) == Some(Format::Fits)
}
#[derive(Debug, Clone, PartialEq)]
enum Value {
/// A quoted string, unescaped, trailing blanks removed.
Str(String),
/// Anything else (number, logical, complex) as written.
Raw(String),
}
#[derive(Debug, Clone)]
struct Card {
key: String,
/// `None` for commentary cards (`COMMENT`, `HISTORY`, blank keyword).
value: Option<Value>,
/// The text of a commentary card.
text: String,
/// A `HIERARCH` keyword (`key` holds its long name).
hierarch: bool,
}
fn parse_value(field: &str) -> Value {
let t = field.trim_start();
if let Some(rest) = t.strip_prefix('\'') {
let mut s = String::new();
let mut chars = rest.chars().peekable();
while let Some(c) = chars.next() {
if c == '\'' {
if chars.peek() == Some(&'\'') {
chars.next();
s.push('\'');
} else {
break;
}
} else {
s.push(c);
}
}
Value::Str(s.trim_end().to_string())
} else {
Value::Raw(t.split('/').next().unwrap_or("").trim().to_string())
}
}
fn parse_card(raw: &[u8]) -> Card {
// Header bytes are ASCII 32–126 by the standard; anything else is replaced, never trusted.
let s: String = raw.iter().map(|&b| if (32..=126).contains(&b) { b as char } else { '?' }).collect();
let key_field = s.get(..8).unwrap_or(&s).trim_end().to_string();
if key_field == "HIERARCH" {
let rest = s.get(9..).unwrap_or("");
if let Some((k, v)) = rest.split_once('=') {
return Card { key: k.trim().to_string(), value: Some(parse_value(v)), text: String::new(), hierarch: true };
}
}
if s.get(8..10) == Some("= ") {
let v = parse_value(s.get(10..).unwrap_or(""));
return Card { key: key_field, value: Some(v), text: String::new(), hierarch: false };
}
Card { key: key_field, value: None, text: s.get(8..).unwrap_or("").trim_end().to_string(), hierarch: false }
}
struct Header {
cards: Vec<Card>,
/// First-occurrence index of each non-HIERARCH keyword, so `get` is O(1). The card
/// count and the number of looked-up keywords (NAXIS1..NAXISn) are both file-controlled,
/// so a linear scan per lookup lets a crafted header multiply commentary cards by axis
/// count into quadratic work.
index: HashMap<String, usize>,
/// Offset of the data unit.
data_start: usize,
}
impl Header {
fn get(&self, key: &str) -> Option<&Value> {
let c = &self.cards[*self.index.get(key)?];
c.value.as_ref()
}
fn int(&self, key: &str) -> Option<i64> {
match self.get(key)? {
Value::Raw(r) => r.parse::<i64>().ok().or_else(|| self.float(key).filter(|f| f.fract() == 0.0 && f.abs() < 9.0e15).map(|f| f as i64)),
Value::Str(_) => None,
}
}
fn float(&self, key: &str) -> Option<f64> {
match self.get(key)? {
// Fortran-style `D` exponents are allowed in FITS.
Value::Raw(r) => r.replace(['D', 'd'], "E").parse::<f64>().ok().filter(|f| f.is_finite()),
Value::Str(_) => None,
}
}
fn logical(&self, key: &str) -> bool {
matches!(self.get(key), Some(Value::Raw(r)) if r == "T")
}
fn string(&self, key: &str) -> Option<&str> {
match self.get(key)? {
Value::Str(s) => Some(s.trim()),
Value::Raw(_) => None,
}
}
}
fn parse_header(b: &[u8], start: usize) -> Result<Header, CodecError> {
let mut cards = Vec::new();
let mut pos = start;
loop {
let raw = b.get(pos..pos.checked_add(CARD).ok_or_else(|| err("header too long"))?).ok_or_else(|| err("header ends before END"))?;
pos += CARD;
if raw.starts_with(b"END") && raw.get(3..).is_some_and(|r| r.iter().all(|&c| c == b' ')) {
break;
}
let card = parse_card(raw);
// Long strings (FITS 4.0 section 4.2.1.2): a string ending in '&' goes on in the next
// `CONTINUE` record. An orphaned `CONTINUE` stays a card of its own (commentary).
if let Some(Card { value: Some(Value::Str(s)), .. }) = cards.last_mut()
&& s.ends_with('&')
&& card.key == "CONTINUE"
&& card.text.starts_with(" ")
&& let Value::Str(more) = parse_value(&card.text)
{
s.pop();
s.push_str(&more);
continue;
}
cards.push(card);
}
let data_start = pos.div_ceil(BLOCK).checked_mul(BLOCK).ok_or_else(|| err("header too long"))?;
// Index each non-HIERARCH keyword to its first occurrence, matching the previous
// `find(|c| !c.hierarch && c.key == key)` lookup while making `get` O(1).
let mut index = HashMap::with_capacity(cards.len());
for (i, c) in cards.iter().enumerate() {
if !c.hierarch {
index.entry(c.key.clone()).or_insert(i);
}
}
Ok(Header { cards, index, data_start })
}
/// The axis lengths (`NAXIS1`, `NAXIS2`, …).
fn axes(h: &Header) -> Result<Vec<u64>, CodecError> {
let n = h.int("NAXIS").ok_or_else(|| err("missing NAXIS"))?;
if !(0..=999).contains(&n) {
return Err(err(format!("invalid NAXIS {n}")));
}
(1..=n)
.map(|i| h.int(&format!("NAXIS{i}")).and_then(|v| u64::try_from(v).ok()).ok_or_else(|| err(format!("missing or negative NAXIS{i}"))))
.collect()
}
/// Bytes in the data unit (before padding to a block).
fn data_len(h: &Header, bitpix: i64) -> Result<u64, CodecError> {
let ax = axes(h)?;
if ax.is_empty() {
return Ok(0);
}
let pcount = u64::try_from(h.int("PCOUNT").unwrap_or(0)).map_err(|_| err("negative PCOUNT"))?;
let gcount = u64::try_from(h.int("GCOUNT").unwrap_or(1)).map_err(|_| err("negative GCOUNT"))?;
let elems = ax.iter().try_fold(1u64, |a, &n| a.checked_mul(n)).ok_or_else(|| err("data size overflows"))?;
elems
.checked_add(pcount)
.and_then(|v| v.checked_mul(gcount))
.and_then(|v| v.checked_mul(bitpix.unsigned_abs() / 8))
.ok_or_else(|| err("data size overflows"))
}
/// A primary header's first card, `SIMPLE =`.
pub fn looks_like_fits(b: &[u8]) -> bool {
b.starts_with(b"SIMPLE =")
}
/// Inspect every HDU without decoding pixels: one gray plane or three RGB planes are retained,
/// while other cubes, image extensions, tables and other data-bearing HDUs cannot survive a flat save.
/// Incomplete or over-limit walks fail closed rather than treating an unchecked suffix as safe.
pub fn has_additional_images(bytes: &[u8]) -> Result<bool, CodecError> {
let mut start = 0;
let mut image_seen = false;
for index in 0..MAX_HDUS {
let h = parse_header(bytes, start)?;
if index == 0 && h.get("SIMPLE").is_none() {
return Err(err("missing SIMPLE"));
}
let ax = axes(&h)?;
let size = data_len(&h, h.int("BITPIX").unwrap_or(8))?;
let image_hdu = index == 0 || h.string("XTENSION") == Some("IMAGE");
if h.logical("ZIMAGE") {
return Ok(true);
}
if !image_hdu && size > 0 {
return Ok(true);
}
// An image HDU with a zero axis has no data (FITS 4.0, NAXISn) and holds no image, like
// the empty primary: `find_image` skips it too.
if image_hdu && size > 0 && ax.len() >= 2 && ax[..2].iter().all(|n| *n > 0) {
let planes = ax.iter().skip(2).try_fold(1u64, |n, axis| n.checked_mul(*axis)).ok_or_else(|| err("plane count overflows"))?;
let retained = planes == 1 || (ax.get(2) == Some(&3) && planes == 3);
if image_seen || !retained || h.int("GCOUNT").unwrap_or(1) > 1 || h.int("PCOUNT").unwrap_or(0) > 0 {
return Ok(true);
}
image_seen = true;
} else if size > 0 {
return Ok(true);
}
let padded = size.div_ceil(BLOCK as u64).checked_mul(BLOCK as u64).ok_or_else(|| err("data size overflows"))?;
let next = usize::try_from(padded).ok().and_then(|size| h.data_start.checked_add(size)).ok_or_else(|| err("data size overflows"))?;
if next > bytes.len() {
return Err(err("truncated HDU data"));
}
if next == bytes.len() {
return Ok(false);
}
start = next;
}
Err(err("too many HDUs to inspect every source image"))
craft_image_codecs::has_unretained_source_data(bytes).map_err(bridge::from_shared_error)
}
/// Whether an HDU with these axes stores pixels: at least two axes and none of them zero (FITS 4.0,
/// NAXISn: a zero axis means no data follow the header).
fn holds_pixels(ax: &[u64]) -> bool {
ax.len() >= 2 && ax.iter().all(|n| *n > 0)
}
/// Finds the image HDU: the primary one when it holds pixels, else the first `IMAGE` extension
/// that does. Returns its header and the primary header (for its descriptive cards).
fn find_image(b: &[u8]) -> Result<(Header, Option<Header>), CodecError> {
let primary = parse_header(b, 0)?;
if primary.get("SIMPLE").is_none() {
return Err(err("missing SIMPLE"));
}
if holds_pixels(&axes(&primary)?) {
return Ok((primary, None));
}
let mut compressed = false;
let mut cur_start = primary.data_start;
let mut cur_len = data_len(&primary, primary.int("BITPIX").unwrap_or(8))?;
for _ in 0..MAX_HDUS {
let next = usize::try_from(cur_len.div_ceil(BLOCK as u64).saturating_mul(BLOCK as u64))
.ok()
.and_then(|l| cur_start.checked_add(l))
.ok_or_else(|| err("data size overflows"))?;
if next >= b.len() {
break;
}
let h = parse_header(b, next)?;
let kind = h.string("XTENSION").unwrap_or("").to_string();
if kind == "IMAGE" && holds_pixels(&axes(&h)?) {
return Ok((h, Some(primary)));
}
if kind == "BINTABLE" && h.logical("ZIMAGE") {
compressed = true;
}
cur_len = data_len(&h, h.int("BITPIX").unwrap_or(8))?;
cur_start = h.data_start;
}
if compressed {
return Err(CodecError::unsupported(F, "tile-compressed FITS (fpack) is not supported; decompress it with funpack first"));
}
Err(err("the file holds no image"))
}
pub fn decode(bytes: &[u8], limits: &Limits) -> Result<Image, CodecError> {
let (h, primary) = find_image(bytes)?;
let bitpix = h.int("BITPIX").ok_or_else(|| err("missing BITPIX"))?;
if !matches!(bitpix, 8 | 16 | 32 | 64 | -32 | -64) {
return Err(err(format!("invalid BITPIX {bitpix}")));
}
let ax = axes(&h)?;
let (Some(&w), Some(&hgt)) = (ax.first(), ax.get(1)) else { return Err(err("the image has fewer than two axes")) };
let w = u32::try_from(w).map_err(|_| CodecError::LimitExceeded(format!("width {w}")))?;
let hgt = u32::try_from(hgt).map_err(|_| CodecError::LimitExceeded(format!("height {hgt}")))?;
let planes = ax.iter().skip(2).try_fold(1u64, |a, &n| a.checked_mul(n)).ok_or_else(|| err("too many planes"))?;
let (layout, nplanes) = if ax.get(2) == Some(&3) && planes == 3 { (ChannelLayout::Rgb, 3usize) } else { (ChannelLayout::Gray, 1) };
let bscale = h.float("BSCALE").unwrap_or(1.0);
let bzero = h.float("BZERO").unwrap_or(0.0);
let blank = if bitpix > 0 { h.int("BLANK") } else { None };
let integral = bscale == 1.0 && bzero.fract() == 0.0;
let candidate = match bitpix {
8 if integral && bzero == 0.0 => SampleType::U8,
8 | 16 if integral => SampleType::U16,
_ => SampleType::F32,
};
limits.check(w, hgt, layout, candidate)?;
let bps = (bitpix.unsigned_abs() / 8) as usize;
let plane_len = (w as usize).checked_mul(hgt as usize).ok_or_else(|| CodecError::LimitExceeded(format!("{w}x{hgt} does not fit in memory")))?;
let n = plane_len.checked_mul(nplanes).ok_or_else(|| CodecError::LimitExceeded("image does not fit in memory".into()))?;
let need = n.checked_mul(bps).and_then(|l| l.checked_add(h.data_start)).ok_or_else(|| err("data size overflows"))?;
let data = bytes.get(h.data_start..need).ok_or_else(|| err("truncated data"))?;
// Physical value of sample `i` (planar order); `None` for a blank or NaN pixel.
let physical = |i: usize| -> Option<f64> {
let s = data.get(i * bps..(i + 1) * bps)?;
let raw = match bitpix {
8 => s.first().map(|&v| v as i64)?,
16 => i16::from_be_bytes([s[0], s[1]]) as i64,
32 => i32::from_be_bytes([s[0], s[1], s[2], s[3]]) as i64,
64 => i64::from_be_bytes([s[0], s[1], s[2], s[3], s[4], s[5], s[6], s[7]]),
-32 => return Some(f32::from_be_bytes([s[0], s[1], s[2], s[3]]) as f64 * bscale + bzero).filter(|v| v.is_finite()),
_ => return Some(f64::from_be_bytes([s[0], s[1], s[2], s[3], s[4], s[5], s[6], s[7]]) * bscale + bzero).filter(|v| v.is_finite()),
};
if blank == Some(raw) {
return None;
}
Some(raw as f64 * bscale + bzero)
};
let top_down = h.string("ROWORDER").is_some_and(|r| r.eq_ignore_ascii_case("TOP-DOWN"));
let (wu, hu) = (w as usize, hgt as usize);
// Planar, bottom-up (by default) → interleaved, top-down.
let dest = |i: usize| -> usize {
let (p, rem) = (i / plane_len, i % plane_len);
let (y, x) = (rem / wu, rem % wu);
let y = if top_down { y } else { hu - 1 - y };
(y * wu + x) * nplanes + p
};
let mut img = match candidate {
SampleType::U8 => {
let mut out = vec![0u8; n];
for i in 0..n {
out[dest(i)] = physical(i).unwrap_or(0.0) as u8;
}
Image::from_u8(w, hgt, layout, out)?
}
_ => {
let mut out16 = if candidate == SampleType::U16 { Some(vec![0u16; n]) } else { None };
if let Some(out) = out16.as_mut() {
for i in 0..n {
let v = physical(i).unwrap_or(0.0);
if !(0.0..=65535.0).contains(&v) {
// Signed data with negative values: fall back to float.
out16 = None;
break;
}
out[dest(i)] = v as u16;
}
}
match out16 {
Some(out) => Image::from_u16(w, hgt, layout, &out)?,
None => {
let max = (0..n).filter_map(physical).fold(0.0f64, f64::max);
let white = if max <= 2.0 {
1.0
} else if max <= 65535.0 {
65535.0
} else {
max
};
let mut out = vec![0f32; n];
for i in 0..n {
out[dest(i)] = (physical(i).unwrap_or(0.0) / white) as f32;
}
Image::from_f32(w, hgt, layout, &out)?
}
}
}
};
if planes > nplanes as u64 {
img.warnings.push(DecodeWarning::MorePages { total: u32::try_from(planes).ok() });
}
let mut text = Vec::new();
for c in primary.iter().flat_map(|p| p.cards.iter()).chain(h.cards.iter()) {
if !c.hierarch && (STRUCTURAL.contains(&c.key.as_str()) || is_naxis(&c.key)) {
continue;
}
let entry = match &c.value {
Some(Value::Str(s) | Value::Raw(s)) => (c.key.clone(), s.clone()),
None if c.key.is_empty() && c.text.trim().is_empty() => continue,
None => (if c.key.is_empty() { "COMMENT".to_string() } else { c.key.clone() }, c.text.trim().to_string()),
};
text.push(entry);
}
img.text = text;
Ok(img)
bridge::format(Format::Fits, bytes, limits)
}
fn is_naxis(key: &str) -> bool {
key.strip_prefix("NAXIS").is_some_and(|d| d.chars().all(|c| c.is_ascii_digit()))
}
/// A standard keyword: 1–8 characters from `A-Z 0-9 _ -`.
fn standard_key(key: &str) -> bool {
(1..=8).contains(&key.len()) && key.bytes().all(|b| b.is_ascii_uppercase() || b.is_ascii_digit() || b == b'_' || b == b'-')
}
fn ascii(s: &str) -> String {
s.chars().map(|c| if (' '..='~').contains(&c) { c } else { '?' }).collect()
}
/// A FITS literal (number or logical) that can be written unquoted.
fn literal(v: &str) -> bool {
v == "T"
|| v == "F"
|| (v.replace(['D', 'd'], "E").parse::<f64>().is_ok_and(|f| f.is_finite()) && v.bytes().all(|b| b"0123456789+-.EeDd".contains(&b)))
}
fn quoted(v: &str, room: usize) -> String {
let mut s = String::from("'");
for c in ascii(v).chars() {
let add = if c == '\'' { 2 } else { 1 };
// Keep room for the closing quote.
if s.len() + add + 1 > room {
break;
}
s.push(c);
if c == '\'' {
s.push('\'');
}
pub fn encode(image: &Image) -> Result<Vec<u8>, CodecError> {
if !matches!(image.layout(), crate::ChannelLayout::Gray | crate::ChannelLayout::Rgb) {
return Err(CodecError::encode("FITS", format!("FITS cannot store {:?}", image.layout())));
}
// Strings are at least eight characters inside the quotes.
while s.len() < 9 {
s.push(' ');
}
s.push('\'');
s
}
struct Writer {
out: Vec<u8>,
}
impl Writer {
fn card(&mut self, text: &str) {
let mut c: Vec<u8> = ascii(text).into_bytes();
c.truncate(CARD);
c.resize(CARD, b' ');
self.out.extend_from_slice(&c);
}
fn value(&mut self, key: &str, v: &str) {
if literal(v) {
self.card(&format!("{key:<8}= {v:>20}"));
return;
}
// A string too long for one card goes on in `CONTINUE` cards, every piece but the last
// ending in '&' (FITS 4.0 section 4.2.1.2). A doubled quote is never split, and trailing
// blanks (not significant) are dropped so none are kept before an '&'.
let escaped = ascii(v).trim_end().replace('\'', "''");
let mut rest = escaped.as_str();
let mut head = format!("{key:<8}= ");
while rest.len() > CARD - 12 {
let cut = CARD - 13 - rest.get(..CARD - 13).unwrap_or("").bytes().rev().take_while(|&b| b == b'\'').count() % 2;
let (piece, tail) = rest.split_at_checked(cut).unwrap_or((rest, ""));
self.card(&format!("{head}'{piece}&'"));
head = "CONTINUE ".to_string();
rest = tail;
}
self.card(&format!("{head}'{rest:<8}'"));
}
fn commentary(&mut self, key: &str, text: &str) {
let chars: Vec<char> = ascii(text).chars().collect();
if chars.is_empty() {
self.card(key);
}
for chunk in chars.chunks(CARD - 8) {
self.card(&format!("{key:<8}{}", chunk.iter().collect::<String>()));
}
}
fn text(&mut self, key: &str, v: &str) {
let upper = key.to_ascii_uppercase();
if matches!(upper.as_str(), "COMMENT" | "HISTORY") {
self.commentary(&upper, v);
} else if standard_key(key) {
// `CONTINUE` only ever carries a string's continuation, written by `value`.
if !STRUCTURAL.contains(&key) && !is_naxis(key) && key != "CONTINUE" {
self.value(key, v);
}
} else {
// Long or mixed-case names (`Description`, `Software`): the HIERARCH convention,
// when the card fits, else a comment.
let name = ascii(key);
let head = format!("HIERARCH {name} = ");
let fits_key = !name.contains('=') && !name.trim().is_empty();
let body = if literal(v) { v.to_string() } else { quoted(v, CARD.saturating_sub(head.len())) };
if fits_key && head.len() + body.len() <= CARD && (literal(v) || body.ends_with('\'')) && quoted_whole(v, &body) {
self.card(&format!("{head}{body}"));
} else {
self.commentary("COMMENT", &format!("{key} = {v}"));
}
}
}
}
/// `body` holds all of `v` (it was not cut short to fit the card).
fn quoted_whole(v: &str, body: &str) -> bool {
literal(v) || body.trim_matches('\'').trim_end().replace("''", "'") == ascii(v).trim_end()
}
/// Writes `img` (gray or RGB; 8-bit, 16-bit or float) as a single-HDU FITS file, with
/// `img.text` as header cards.
pub fn encode(img: &Image) -> Result<Vec<u8>, CodecError> {
let (w, h) = (img.width(), img.height());
let layout = img.layout();
let nc = match layout {
ChannelLayout::Gray => 1,
ChannelLayout::Rgb => 3,
l => return Err(CodecError::encode(F, format!("FITS cannot store {l:?}"))),
};
let bitpix = match img.sample_type() {
SampleType::U8 => 8,
SampleType::U16 => 16,
SampleType::F32 => -32,
};
let mut wr = Writer { out: Vec::new() };
wr.value("SIMPLE", "T");
wr.value("BITPIX", &bitpix.to_string());
wr.value("NAXIS", if nc == 3 { "3" } else { "2" });
wr.value("NAXIS1", &w.to_string());
wr.value("NAXIS2", &h.to_string());
if nc == 3 {
wr.value("NAXIS3", "3");
}
if bitpix == 16 {
wr.value("BZERO", "32768");
wr.value("BSCALE", "1");
}
wr.value("ROWORDER", "BOTTOM-UP");
for (k, v) in &img.text {
wr.text(k, v);
}
wr.card("END");
let mut out = wr.out;
out.resize(out.len().div_ceil(BLOCK) * BLOCK, b' ');
// Planar, bottom row first.
let (wu, hu) = (w as usize, h as usize);
let idx = |p: usize, y: usize, x: usize| ((hu - 1 - y) * wu + x) * nc + p;
match bitpix {
8 => {
let d = img.data();
for p in 0..nc {
for y in 0..hu {
for x in 0..wu {
out.push(d[idx(p, y, x)]);
}
}
}
}
16 => {
let d = img.to_u16_samples().unwrap_or_default();
for p in 0..nc {
for y in 0..hu {
for x in 0..wu {
out.extend_from_slice(&((d[idx(p, y, x)] as i32 - 32768) as i16).to_be_bytes());
}
}
}
}
_ => {
let d = img.to_f32_samples().unwrap_or_default();
for p in 0..nc {
for y in 0..hu {
for x in 0..wu {
// 0..1 as documented: a value above 2 would make readers (ours too)
// take the data as ADU and scale it by 65535. NaN is written as 0.
let v = d[idx(p, y, x)];
let v = if v.is_nan() { 0.0 } else { v.clamp(0.0, 1.0) };
out.extend_from_slice(&v.to_be_bytes());
}
}
}
}
}
out.resize(out.len().div_ceil(BLOCK) * BLOCK, 0);
Ok(out)
}
#[cfg(test)]
mod tests {
use super::*;
fn header(cards: &[&str]) -> Vec<u8> {
let mut w = Writer { out: Vec::new() };
for c in cards {
w.card(c);
}
w.card("END");
let mut out = w.out;
out.resize(out.len().div_ceil(BLOCK) * BLOCK, b' ');
out
}
#[test]
fn continue_strings_decode() {
let mut b = header(&[
"SIMPLE = T",
"BITPIX = 8",
"NAXIS = 2",
"NAXIS1 = 1",
"NAXIS2 = 1",
"OBJECT = 'aaa&'",
"CONTINUE 'bbb&' / a comment",
"CONTINUE '&'",
"CONTINUE ''",
"OBSERVER= 'R&'",
"COMMENT hi",
"CONTINUE 'orphan'",
]);
b.push(0);
let img = decode(&b, &Limits::default()).unwrap();
let text = [("OBJECT", "aaabbb"), ("OBSERVER", "R&"), ("COMMENT", "hi"), ("CONTINUE", "'orphan'")];
assert_eq!(img.text, text.map(|(k, v)| (k.to_string(), v.to_string())));
}
#[test]
fn continue_strings_round_trip() {
for value in ["a".repeat(100), format!("{}' {}", "a".repeat(65), "b".repeat(100)), "'".repeat(100), "a".repeat(68)] {
let mut img = Image::from_u8(1, 1, ChannelLayout::Gray, vec![0]).unwrap();
img.text = vec![("OBJECT".into(), value.clone()), ("CONTINUE".into(), "orphan".into())];
let b = encode(&img).unwrap();
assert!(!b.chunks(CARD).any(|c| c.starts_with(b"CONTINUE=")));
let decoded = decode(&b, &Limits::default()).unwrap();
assert_eq!(decoded.text, vec![("OBJECT".into(), value)]);
}
}
#[test]
fn camera_u16_with_bzero_reads_exactly_and_bottom_up() {
let mut b = header(&[
"SIMPLE = T",
"BITPIX = 16",
"NAXIS = 2",
"NAXIS1 = 2",
"NAXIS2 = 2",
"BZERO = 32768",
"OBJECT = 'M 31 '",
"EXPTIME = 300.0 / seconds",
]);
for v in [0u16, 1000, 40000, 65535] {
b.extend_from_slice(&((v as i32 - 32768) as i16).to_be_bytes());
}
b.resize(b.len().div_ceil(BLOCK) * BLOCK, 0);
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!(img.sample_type(), SampleType::U16);
// The first stored row is the bottom one.
assert_eq!(img.to_u16_samples().unwrap(), vec![40000, 65535, 0, 1000]);
assert!(img.text.contains(&("OBJECT".into(), "M 31".into())));
assert!(img.text.contains(&("EXPTIME".into(), "300.0".into())));
assert!(!img.text.iter().any(|(k, _)| k == "BZERO" || k == "NAXIS1"));
}
#[test]
fn roworder_top_down_is_honoured() {
let mut b = header(&["SIMPLE = T", "BITPIX = 8", "NAXIS = 2", "NAXIS1 = 1", "NAXIS2 = 2", "ROWORDER= 'TOP-DOWN'"]);
b.extend_from_slice(&[10, 20]);
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!(img.data(), &[10, 20]);
}
#[test]
fn stacked_float_in_adu_is_scaled_by_65535() {
let mut b = header(&["SIMPLE = T", "BITPIX = -32", "NAXIS = 2", "NAXIS1 = 2", "NAXIS2 = 1"]);
for v in [65535.0f32, f32::NAN] {
b.extend_from_slice(&v.to_be_bytes());
}
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!(img.to_f32_samples().unwrap(), vec![1.0, 0.0]);
}
#[test]
fn hdr_float_saves_clamped_and_reopens_as_saved() {
// One value above 2 used to make the reader scale everything by 65535 (all black).
let img = Image::from_f32(2, 1, ChannelLayout::Gray, &[0.5, 3.0]).unwrap();
let bytes = encode(&img).unwrap();
let back = decode(&bytes, &Limits::default()).unwrap().to_f32_samples().unwrap();
assert!((back[0] - 0.5).abs() < 1e-6, "{back:?}");
assert!((back[1] - 1.0).abs() < 1e-6, "{back:?}");
}
#[test]
fn signed_negative_data_falls_back_to_float() {
let mut b = header(&["SIMPLE = T", "BITPIX = 16", "NAXIS = 2", "NAXIS1 = 2", "NAXIS2 = 1"]);
for v in [-100i16, 1000] {
b.extend_from_slice(&v.to_be_bytes());
}
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!(img.sample_type(), SampleType::F32);
}
#[test]
fn image_extension_after_empty_primary() {
let mut b = header(&["SIMPLE = T", "BITPIX = 8", "NAXIS = 0", "EXTEND = T", "TELESCOP= 'Seestar S50'"]);
b.extend(header(&["XTENSION= 'IMAGE '", "BITPIX = 8", "NAXIS = 2", "NAXIS1 = 1", "NAXIS2 = 1", "PCOUNT = 0", "GCOUNT = 1"]));
b.push(42);
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!(img.data(), &[42]);
assert!(img.text.contains(&("TELESCOP".into(), "Seestar S50".into())));
}
/// A zero axis (`NAXIS3 = 0`) means the HDU has no data: it is neither the opened image nor
/// an additional one that a flat save would discard.
#[test]
fn zero_axis_image_hdus_are_empty() {
let empty = |primary: bool| {
let first = if primary { "SIMPLE = T" } else { "XTENSION= 'IMAGE '" };
header(&[first, "BITPIX = 8", "NAXIS = 3", "NAXIS1 = 1", "NAXIS2 = 1", "NAXIS3 = 0", "PCOUNT = 0", "GCOUNT = 1"])
};
let image = || {
let mut b = header(&["XTENSION= 'IMAGE '", "BITPIX = 8", "NAXIS = 2", "NAXIS1 = 1", "NAXIS2 = 1", "PCOUNT = 0", "GCOUNT = 1"]);
b.push(42);
b.resize(b.len().div_ceil(BLOCK) * BLOCK, 0);
b
};
let mut after_empty_primary = empty(true);
after_empty_primary.extend(image());
let mut after_empty_extension = header(&["SIMPLE = T", "BITPIX = 8", "NAXIS = 0", "EXTEND = T"]);
after_empty_extension.extend(empty(false));
after_empty_extension.extend(image());
let mut before_empty_extension = header(&["SIMPLE = T", "BITPIX = 8", "NAXIS = 0", "EXTEND = T"]);
before_empty_extension.extend(image());
before_empty_extension.extend(empty(false));
for b in [&after_empty_primary, &after_empty_extension, &before_empty_extension] {
assert!(!has_additional_images(b).unwrap());
assert_eq!(decode(b, &Limits::default()).unwrap().data(), &[42]);
}
// Only empty HDUs: nothing to open, nothing to lose.
assert!(!has_additional_images(&empty(true)).unwrap());
assert!(decode(&empty(true), &Limits::default()).is_err());
// A second non-empty image is still additional data.
let mut two = after_empty_primary.clone();
two.extend(image());
assert!(has_additional_images(&two).unwrap());
}
#[test]
fn fpack_is_refused_as_unsupported() {
let mut b = header(&["SIMPLE = T", "BITPIX = 8", "NAXIS = 0"]);
b.extend(header(&["XTENSION= 'BINTABLE'", "BITPIX = 8", "NAXIS = 2", "NAXIS1 = 0", "NAXIS2 = 0", "ZIMAGE = T"]));
b.extend(header(&["XTENSION= 'BINTABLE'", "BITPIX = 8", "NAXIS = 1", "NAXIS1 = 0"]));
assert!(matches!(decode(&b, &Limits::default()), Err(CodecError::Unsupported { .. })));
}
/// Hostile headers: absurd or negative axes, bad BITPIX, overflowing sizes, missing END,
/// a long chain of empty HDUs and declared data past the end all error, never panic or
/// allocate the declared size.
#[test]
fn hostile_headers_error_without_panicking() {
let base = ["SIMPLE = T", "BITPIX = 16"];
let cases: &[&[&str]] = &[
&["NAXIS = 2", "NAXIS1 = 4294967296", "NAXIS2 = 1"],
&["NAXIS = 2", "NAXIS1 = -5", "NAXIS2 = 1"],
&["NAXIS = 2", "NAXIS1 = 2000000", "NAXIS2 = 2000000"],
&["NAXIS = 3", "NAXIS1 = 65536", "NAXIS2 = 65536", "NAXIS3 = 9223372036854775807"],
&["NAXIS = 1000"],
&["NAXIS = -1"],
&["NAXIS = 2", "NAXIS1 = 0", "NAXIS2 = 0"],
&["NAXIS = 2", "NAXIS1 = 1.5D300", "NAXIS2 = 1"],
&["NAXIS = 2"],
&["NAXIS = 2", "NAXIS1 = 100", "NAXIS2 = 100"],
];
for extra in cases {
let cards: Vec<&str> = base.iter().chain(extra.iter()).copied().collect();
let b = header(&cards);
assert!(decode(&b, &Limits::default()).is_err(), "{extra:?}");
}
for bitpix in ["0", "7", "-16", "128", "'X'"] {
let card = format!("BITPIX = {bitpix}");
let b = header(&["SIMPLE = T", &card, "NAXIS = 2", "NAXIS1 = 1", "NAXIS2 = 1"]);
assert!(decode(&b, &Limits::default()).is_err(), "BITPIX {bitpix}");
}
// No END card: the header runs off the end of the file.
let mut w = Writer { out: Vec::new() };
for c in ["SIMPLE = T", "BITPIX = 8", "NAXIS = 2"] {
w.card(c);
}
assert!(decode(&w.out, &Limits::default()).is_err());
// An empty primary followed by many empty extensions: bounded walk, then "no image".
let mut b = header(&["SIMPLE = T", "BITPIX = 8", "NAXIS = 0"]);
for _ in 0..(MAX_HDUS + 5) {
b.extend(header(&["XTENSION= 'IMAGE '", "BITPIX = 8", "NAXIS = 0"]));
}
assert!(decode(&b, &Limits::default()).is_err());
// An extension whose declared data size overflows.
let mut b = header(&["SIMPLE = T", "BITPIX = 8", "NAXIS = 0"]);
b.extend(header(&[
"XTENSION= 'BINTABLE'",
"BITPIX = 64",
"NAXIS = 2",
"NAXIS1 = 9223372036854775807",
"NAXIS2 = 4",
"PCOUNT = 0",
"GCOUNT = 1",
]));
assert!(decode(&b, &Limits::default()).is_err());
}
#[test]
fn extra_planes_warn() {
let mut b = header(&["SIMPLE = T", "BITPIX = 8", "NAXIS = 3", "NAXIS1 = 1", "NAXIS2 = 1", "NAXIS3 = 4"]);
b.extend_from_slice(&[1, 2, 3, 4]);
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!(img.layout(), ChannelLayout::Gray);
assert_eq!(img.warnings, vec![DecodeWarning::MorePages { total: Some(4) }]);
}
#[test]
fn strings_with_quotes_and_hierarch_round_trip() {
let mut w = Writer { out: Vec::new() };
w.text("OBSERVER", "O'Brien");
w.text("Software", "craft 1.0");
w.text("HISTORY", "stacked");
let cards: Vec<Card> = w.out.chunks(CARD).map(parse_card).collect();
assert_eq!(cards[0].value, Some(Value::Str("O'Brien".into())));
assert!(cards[1].hierarch && cards[1].key == "Software");
assert_eq!(cards[1].value, Some(Value::Str("craft 1.0".into())));
assert_eq!((cards[2].key.as_str(), cards[2].text.as_str()), ("HISTORY", "stacked"));
}
bridge::encode(image, Format::Fits, &Default::default())
}
+11 -533
View File
@@ -1,538 +1,16 @@
//! Amiga IFF/ILBM reader and writer (EA "Interchange File Format", "InterLeaved BitMap" and the
//! chunky "PBM " variant). Written from the published IFF/ILBM layout: a `FORM` chunk of four-byte
//! chunks (`BMHD` bitmap header, `CMAP` palette, `CAMG` Amiga viewport mode, `BODY` pixel data).
//!
//! Read: 1–8 bitplanes with a palette (or a gray ramp when there is none) with masking 0/1/2, and
//! 24-bitplane "deep" ILBMs (8 planes each of red, green and blue, least significant bit first,
//! no palette) with masking 0/1, both stored (0) and ByteRun1/PackBits (1) compressed. Anything
//! else is a clear `Unsupported`/`Malformed` error, never a panic.
//!
//! Write: a 24-bitplane ILBM, ByteRun1 compressed one plane row at a time, with a mask plane
//! (masking 1) when the image has alpha. The mask plane is one bit per pixel: alpha of 128 or
//! more is opaque.
//! IFF/ILBM compatibility facade; implementation lives in craft-image-codecs.
use crate::{CodecError, Image, Limits, bridge};
use craft_image_codecs::Format;
use crate::{ChannelLayout, CodecError, Image, Limits, SampleType};
const F: &str = "IFF";
fn bad(msg: impl std::fmt::Display) -> CodecError {
CodecError::malformed(F, msg)
pub fn looks_like_iff(bytes: &[u8]) -> bool {
craft_image_codecs::detect(bytes) == Some(Format::Iff)
}
fn unsupported(msg: impl Into<String>) -> CodecError {
CodecError::unsupported(F, msg)
pub fn decode(bytes: &[u8], limits: &Limits) -> Result<Image, CodecError> {
bridge::format(Format::Iff, bytes, limits)
}
fn be32(b: &[u8], at: usize) -> Option<u32> {
let s = b.get(at..at.checked_add(4)?)?.try_into().ok()?;
Some(u32::from_be_bytes(s))
}
fn be16(b: &[u8], at: usize) -> Option<u16> {
let s = b.get(at..at.checked_add(2)?)?.try_into().ok()?;
Some(u16::from_be_bytes(s))
}
/// `FORM` + a bitmap type (`ILBM` interleaved, `PBM ` chunky) at offset 8.
pub fn looks_like_iff(b: &[u8]) -> bool {
b.get(0..4) == Some(b"FORM") && matches!(b.get(8..12), Some(b"ILBM" | b"PBM "))
}
/// Bitplanes of a "deep" ILBM: red, green and blue, 8 each, least significant bit first.
const DEEP_PLANES: u8 = 24;
/// The bitmap header fields decoding needs.
struct Header {
width: u32,
height: u32,
planes: u8,
masking: u8,
compression: u8,
transparent: u16,
/// `PBM ` stores one palette index per byte, padded to even row lengths.
chunky: bool,
}
/// One four-byte chunk's id and byte range.
struct Chunk<'a> {
id: [u8; 4],
data: &'a [u8],
}
/// Walk the `FORM`'s chunks from offset 12 to `end` (the form length), stopping at the first
/// malformed length so a hostile file can't run past the buffer.
fn chunks(b: &[u8]) -> impl Iterator<Item = Chunk<'_>> {
let end = be32(b, 4).map_or(b.len(), |n| (n as usize).saturating_add(8).min(b.len()));
let mut pos = 12usize;
std::iter::from_fn(move || {
if pos + 8 > end {
return None;
}
let id = b.get(pos..pos + 4)?.try_into().ok()?;
let len = be32(b, pos + 4)? as usize;
let start = pos + 8;
let data = b.get(start..start.checked_add(len)?)?;
// Chunks are padded to an even length.
pos = start.checked_add(len)?.checked_add(len & 1)?;
Some(Chunk { id, data })
})
}
fn parse_header(b: &[u8], chunky: bool) -> Result<Header, CodecError> {
let bmhd = chunks(b).find(|c| &c.id == b"BMHD").ok_or_else(|| bad("no BMHD chunk"))?;
let d = bmhd.data;
if d.len() < 20 {
return Err(bad("BMHD chunk is too short"));
pub fn encode(image: &Image) -> Result<Vec<u8>, CodecError> {
if !matches!(image.layout(), crate::ChannelLayout::Rgb | crate::ChannelLayout::Rgba) || image.sample_type() != crate::SampleType::U8 {
return Err(CodecError::encode("IFF", "ILBM writer stores 8-bit RGB pixels with optional alpha"));
}
let width = u32::from(be16(d, 0).ok_or_else(|| bad("BMHD width"))?);
let height = u32::from(be16(d, 2).ok_or_else(|| bad("BMHD height"))?);
let planes = *d.get(8).ok_or_else(|| bad("BMHD planes"))?;
let masking = *d.get(9).ok_or_else(|| bad("BMHD masking"))?;
let compression = *d.get(10).ok_or_else(|| bad("BMHD compression"))?;
if width == 0 || height == 0 {
return Err(bad("zero-sized bitmap"));
}
if !(1..=8).contains(&planes) && planes != DEEP_PLANES {
return Err(unsupported(format!("{planes} bitplanes (1–8 with a palette, or 24)")));
}
if masking > 2 {
return Err(unsupported(format!("masking {masking}")));
}
if planes == DEEP_PLANES && masking == 2 {
return Err(unsupported("a transparent color in a 24-bitplane ILBM"));
}
if compression > 1 {
return Err(unsupported(format!("compression {compression} (only stored and ByteRun1)")));
}
if chunky && (planes != 8 || masking == 1) {
return Err(unsupported("PBM requires 8-bit indices without a mask plane"));
}
let transparent = be16(d, 12).ok_or_else(|| bad("BMHD transparent colour"))?;
Ok(Header { width, height, planes, masking, compression, transparent, chunky })
}
/// ByteRun1 / PackBits decode of one plane row into `out`; returns the bytes consumed. A `0x80`
/// control byte is a no-op, as the layout specifies.
fn unpack_byte_run1(src: &[u8], out: &mut [u8]) -> Result<usize, CodecError> {
let (mut i, mut o) = (0usize, 0usize);
while o < out.len() {
let n = *src.get(i).ok_or_else(|| bad("truncated ByteRun1 data"))? as i8;
i += 1;
if n >= 0 {
let count = n as usize + 1;
let lit = src.get(i..i.checked_add(count).ok_or_else(|| bad("ByteRun1 overflow"))?).ok_or_else(|| bad("truncated ByteRun1 run"))?;
if count > out.len() - o {
return Err(bad("ByteRun1 run crosses the plane row"));
}
out[o..o + count].copy_from_slice(lit);
i += count;
o += count;
} else if n != -128 {
let count = (1 - n as i32) as usize;
let value = *src.get(i).ok_or_else(|| bad("truncated ByteRun1 repeat"))?;
i += 1;
if count > out.len() - o {
return Err(bad("ByteRun1 repeat crosses the plane row"));
}
out[o..o + count].fill(value);
o += count;
}
}
Ok(i)
}
pub fn decode(b: &[u8], limits: &Limits) -> Result<Image, CodecError> {
if !looks_like_iff(b) {
return Err(bad("not an IFF/ILBM file (no FORM ... ILBM)"));
}
let h = parse_header(b, b.get(8..12) == Some(b"PBM "))?;
if let Some(camg) = chunks(b).find(|c| &c.id == b"CAMG") {
let mode = be32(camg.data, 0).ok_or_else(|| bad("short CAMG chunk"))?;
if mode & (0x80 | 0x800) != 0 {
return Err(unsupported("EHB and HAM viewport modes"));
}
}
let layout = if h.masking == 0 { ChannelLayout::Rgb } else { ChannelLayout::Rgba };
limits.check(h.width, h.height, layout, SampleType::U8)?;
// Palette: three bytes per colour; missing entries read as black.
let cmap = chunks(b).find(|c| &c.id == b"CMAP").map(|c| c.data).filter(|p| !p.is_empty());
let colors = 1usize << h.planes;
let palette = |idx: usize| -> [u8; 3] {
if let Some(p) = cmap {
p.get(idx * 3..idx * 3 + 3).map(|c| [c[0], c[1], c[2]]).unwrap_or([0; 3])
} else {
let v = ((idx as u32 * 255) / (colors as u32 - 1).max(1)) as u8;
[v, v, v]
}
};
let body = chunks(b).find(|c| &c.id == b"BODY").map(|c| c.data).ok_or_else(|| bad("no BODY chunk"))?;
let (w, hh) = (h.width as usize, h.height as usize);
// Each plane row is stored as a whole number of 16-bit words.
let plane_row = if h.chunky { w.div_ceil(2) * 2 } else { w.div_ceil(16) * 2 };
// A masking type 1 bitmap carries one extra (mask) plane per row.
let rows_planes: usize = if h.chunky { 1 } else { usize::from(h.planes) + usize::from(h.masking == 1) };
// Decode every stored plane row up front, then recombine.
let total_rows = hh.checked_mul(rows_planes).ok_or_else(|| CodecError::LimitExceeded("bitmap too large".into()))?;
let total_bytes = total_rows.checked_mul(plane_row).ok_or_else(|| CodecError::LimitExceeded("bitmap too large".into()))?;
if total_bytes as u64 > limits.max_alloc {
return Err(CodecError::LimitExceeded("bitmap storage exceeds max_alloc".into()));
}
Limits::check_plausible(total_bytes as u64, body.len(), if h.compression == 0 { 1 } else { 128 })?;
let mut stored = crate::alloc_zeroed::<u8>(total_bytes)?;
let mut cursor = 0usize;
for row in stored.chunks_mut(plane_row.max(1)).take(total_rows) {
match h.compression {
0 => {
let src =
body.get(cursor..cursor.checked_add(plane_row).ok_or_else(|| bad("BODY overflow"))?).ok_or_else(|| bad("truncated BODY data"))?;
let n = row.len().min(src.len());
row[..n].copy_from_slice(&src[..n]);
cursor += plane_row;
}
_ => {
let tail = body.get(cursor..).ok_or_else(|| bad("truncated BODY data"))?;
cursor += unpack_byte_run1(tail, row)?;
}
}
}
let mut out = Vec::new();
out.try_reserve_exact(w.saturating_mul(hh).saturating_mul(layout.channels()))
.map_err(|_| CodecError::LimitExceeded("cannot allocate the image".into()))?;
let planes = usize::from(h.planes);
for y in 0..hh {
for x in 0..w {
let index = if h.chunky {
usize::from(*stored.get(y * plane_row + x).ok_or_else(|| bad("PBM pixel outside BODY"))?)
} else {
(0..planes).filter(|&p| bit_at(&stored, (y * rows_planes + p) * plane_row, x)).fold(0usize, |acc, p| acc | (1 << p))
};
let c = if h.planes == DEEP_PLANES { [index as u8, (index >> 8) as u8, (index >> 16) as u8] } else { palette(index) };
out.extend_from_slice(&c);
if h.masking != 0 {
let opaque =
if h.masking == 1 { bit_at(&stored, (y * rows_planes + planes) * plane_row, x) } else { index != usize::from(h.transparent) };
out.push(if opaque { 255 } else { 0 });
}
}
}
Image::from_u8(h.width, h.height, layout, out)
}
/// The bit for pixel `x` of a stored plane row at `base` (bits run MSB-first).
fn bit_at(stored: &[u8], base: usize, x: usize) -> bool {
stored.get(base + x / 8).is_some_and(|byte| byte & (0x80 >> (x % 8)) != 0)
}
/// ByteRun1 / PackBits encode of one plane row, appended to `out`: three or more equal bytes
/// become a repeat (at most 128), everything else literal runs (at most 128 bytes).
fn pack_byte_run1(row: &[u8], out: &mut Vec<u8>) {
let mut i = 0usize;
while let Some(&value) = row.get(i) {
let repeat = row[i..].iter().take(128).take_while(|&&b| b == value).count();
if repeat >= 3 {
out.push((1 - repeat as i32) as i8 as u8);
out.push(value);
i += repeat;
continue;
}
let start = i;
while i < row.len() && i - start < 128 {
if row.get(i..i + 3).is_some_and(|r| r[0] == r[1] && r[1] == r[2]) {
break;
}
i += 1;
}
out.push((i - start - 1) as u8);
out.extend_from_slice(&row[start..i]);
}
}
fn push_chunk(out: &mut Vec<u8>, id: &[u8; 4], data: &[u8]) -> Result<(), CodecError> {
let len = u32::try_from(data.len()).map_err(|_| CodecError::encode(F, "chunk too large for an IFF file (4 GiB)"))?;
out.extend_from_slice(id);
out.extend_from_slice(&len.to_be_bytes());
out.extend_from_slice(data);
// Chunks are padded to an even length.
if data.len() % 2 == 1 {
out.push(0);
}
Ok(())
}
/// Writes a 24-bitplane `FORM ILBM`: `BMHD` then a ByteRun1-compressed `BODY`, each row stored as
/// the red, green and blue planes (least significant bit first) and, for RGBA, a mask plane.
pub fn encode(img: &Image) -> Result<Vec<u8>, CodecError> {
let enc = |msg: String| CodecError::encode(F, msg);
let masked = match img.layout() {
ChannelLayout::Rgb => false,
ChannelLayout::Rgba => true,
l => return Err(enc(format!("IFF/ILBM cannot store {l:?}"))),
};
if img.sample_type() != SampleType::U8 {
return Err(enc(format!("IFF/ILBM cannot store {:?} samples", img.sample_type())));
}
let (w, h) = (img.width(), img.height());
let (Ok(w16), Ok(h16)) = (u16::try_from(w), u16::try_from(h)) else {
return Err(enc("IFF/ILBM stores at most 65535 × 65535 pixels".into()));
};
let (w, ch) = (w as usize, img.layout().channels());
let data = img.data();
let row_len = w.checked_mul(ch).ok_or_else(|| enc("image too large".into()))?;
if data.len() != row_len.checked_mul(h as usize).ok_or_else(|| enc("image too large".into()))? {
return Err(enc("the image has the wrong number of samples".into()));
}
let planes = usize::from(DEEP_PLANES) + usize::from(masked);
let mut plane_row = vec![0u8; w.div_ceil(16) * 2];
let mut body = Vec::new();
for px in data.chunks_exact(row_len.max(1)) {
for plane in 0..planes {
plane_row.fill(0);
for (x, p) in px.chunks_exact(ch).enumerate() {
let on = if plane == usize::from(DEEP_PLANES) { p[3] >= 128 } else { (p[plane / 8] >> (plane % 8)) & 1 == 1 };
if on {
plane_row[x / 8] |= 0x80 >> (x % 8);
}
}
pack_byte_run1(&plane_row, &mut body);
}
}
let mut bmhd = Vec::with_capacity(20);
bmhd.extend_from_slice(&w16.to_be_bytes());
bmhd.extend_from_slice(&h16.to_be_bytes());
bmhd.extend_from_slice(&[0, 0, 0, 0]); // x/y origin
bmhd.push(DEEP_PLANES);
bmhd.push(u8::from(masked)); // masking: 1 = a mask plane follows the color planes
bmhd.push(1); // ByteRun1
bmhd.push(0); // pad
bmhd.extend_from_slice(&[0, 0]); // transparent color (unused)
bmhd.extend_from_slice(&[1, 1]); // square pixels
bmhd.extend_from_slice(&w16.to_be_bytes()); // page size
bmhd.extend_from_slice(&h16.to_be_bytes());
let mut out = b"FORM".to_vec();
out.extend_from_slice(&[0; 4]); // patched below
out.extend_from_slice(b"ILBM");
push_chunk(&mut out, b"BMHD", &bmhd)?;
push_chunk(&mut out, b"BODY", &body)?;
let form_len = u32::try_from(out.len() - 8).map_err(|_| enc("image too large for an IFF file (4 GiB)".into()))?;
out[4..8].copy_from_slice(&form_len.to_be_bytes());
Ok(out)
}
#[cfg(test)]
mod tests {
use super::*;
/// A `FORM ILBM` with a `BMHD`, `CMAP` and `BODY`. `planes` plane rows per row,
/// `compression` 0 (stored) or 1 (ByteRun1), MSB-first.
fn ilbm(w: u16, h: u16, planes: u8, palette: &[[u8; 3]], compression: u8, body: &[u8]) -> Vec<u8> {
let mut b = b"FORM".to_vec();
b.extend_from_slice(&0u32.to_be_bytes()); // patched below
b.extend_from_slice(b"ILBM");
// BMHD (20 bytes)
b.extend_from_slice(b"BMHD");
b.extend_from_slice(&20u32.to_be_bytes());
b.extend_from_slice(&w.to_be_bytes());
b.extend_from_slice(&h.to_be_bytes());
b.extend_from_slice(&[0, 0, 0, 0]); // x/y origin
b.push(planes);
b.push(0); // masking
b.push(compression);
b.push(0); // pad
b.extend_from_slice(&[0, 0]); // transparent colour
b.extend_from_slice(&[1, 1]); // aspect
b.extend_from_slice(&[0, 0, 0, 0]); // page size
// CMAP
b.extend_from_slice(b"CMAP");
b.extend_from_slice(&((palette.len() * 3) as u32).to_be_bytes());
for c in palette {
b.extend_from_slice(c);
}
if palette.len() % 2 == 1 {
b.push(0);
}
// BODY
b.extend_from_slice(b"BODY");
b.extend_from_slice(&(body.len() as u32).to_be_bytes());
b.extend_from_slice(body);
if body.len() % 2 == 1 {
b.push(0);
}
let size = (b.len() - 8) as u32;
b[4..8].copy_from_slice(&size.to_be_bytes());
b
}
#[test]
fn reads_a_stored_two_plane_bitmap() {
// 2×1, 2 planes: pixel 0 index 0 (plane bits 0,0), pixel 1 index 3 (bits 1,1).
// Plane 0 = 0b0100_0000, plane 1 = 0b0100_0000, each padded to 2 bytes.
let body = [0b0100_0000, 0, 0b0100_0000, 0];
let pal = [[10, 20, 30], [40, 50, 60], [70, 80, 90], [100, 110, 120]];
let b = ilbm(2, 1, 2, &pal, 0, &body);
assert!(looks_like_iff(&b));
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!((img.width(), img.height(), img.layout()), (2, 1, ChannelLayout::Rgb));
assert_eq!(img.data(), &[10, 20, 30, 100, 110, 120]);
}
#[test]
fn reads_byte_run1_compressed_rows() {
// Same image, ByteRun1: literal run of two bytes (0x01) then the two plane bytes each row.
let body = [0x01, 0b0100_0000, 0, 0x01, 0b0100_0000, 0];
let pal = [[1, 2, 3], [4, 5, 6], [7, 8, 9], [250, 251, 252]];
let b = ilbm(2, 1, 2, &pal, 1, &body);
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!(img.data(), &[1, 2, 3, 250, 251, 252]);
}
#[test]
fn no_palette_falls_back_to_a_grey_ramp() {
// 2×1, 1 plane, no CMAP: indices 0 and 1 → black and white.
let body = [0b0100_0000, 0];
let b = ilbm(2, 1, 1, &[], 0, &body);
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!(img.data(), &[0, 0, 0, 255, 255, 255]);
}
#[test]
fn pbm_reads_chunky_indices_with_odd_width_padding() {
let pal = [[10, 20, 30], [40, 50, 60], [70, 80, 90]];
for (compression, body) in [(0, vec![2, 0, 1, 255, 1, 2, 0, 255]), (1, vec![3, 2, 0, 1, 255, 3, 1, 2, 0, 255])] {
let mut b = ilbm(3, 2, 8, &pal, compression, &body);
b[8..12].copy_from_slice(b"PBM ");
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!(img.data(), &[70, 80, 90, 10, 20, 30, 40, 50, 60, 40, 50, 60, 70, 80, 90, 10, 20, 30]);
}
}
#[test]
fn transparency_uses_the_mask_plane_or_transparent_index() {
for masking in [1, 2] {
let mut b = ilbm(2, 1, 1, &[[10, 20, 30], [40, 50, 60]], 0, if masking == 1 { &[0x40, 0, 0x40, 0] } else { &[0x40, 0] });
b[29] = masking;
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!(img.layout(), ChannelLayout::Rgba);
assert_eq!(img.data(), &[10, 20, 30, 0, 40, 50, 60, 255]);
}
let mut b = ilbm(2, 1, 8, &[[10, 20, 30], [40, 50, 60]], 0, &[0, 1]);
b[8..12].copy_from_slice(b"PBM ");
b[29] = 2;
b[32..34].copy_from_slice(&1u16.to_be_bytes());
assert_eq!(decode(&b, &Limits::default()).unwrap().data(), &[10, 20, 30, 255, 40, 50, 60, 0]);
}
#[test]
fn rejects_ham_and_ehb_instead_of_returning_wrong_colours() {
for mode in [0x80u32, 0x800] {
let mut b = ilbm(1, 1, 1, &[], 0, &[0, 0]);
b.extend_from_slice(b"CAMG");
b.extend_from_slice(&4u32.to_be_bytes());
b.extend_from_slice(&mode.to_be_bytes());
let len = (b.len() - 8) as u32;
b[4..8].copy_from_slice(&len.to_be_bytes());
assert!(matches!(decode(&b, &Limits::default()), Err(CodecError::Unsupported { .. })));
}
}
#[test]
fn missing_palette_entries_are_black() {
let b = ilbm(1, 1, 2, &[[10, 20, 30]], 0, &[0x80, 0, 0x80, 0]);
assert_eq!(decode(&b, &Limits::default()).unwrap().data(), &[0, 0, 0]);
}
#[test]
fn reads_a_stored_24_plane_bitmap() {
// 2×1: pixel 0 = (1, 0, 128), pixel 1 = (0, 255, 0). Each plane row is 2 bytes; red bit 0
// has pixel 0 set, green bits 0–7 have pixel 1 set, blue bit 7 has pixel 0 set.
let mut body = Vec::new();
for plane in 0..24 {
let byte = match plane {
0 | 23 => 0x80,
8..=15 => 0x40,
_ => 0,
};
body.extend_from_slice(&[byte, 0]);
}
let b = ilbm(2, 1, 24, &[], 0, &body);
let img = decode(&b, &Limits::default()).unwrap();
assert_eq!((img.width(), img.height(), img.layout()), (2, 1, ChannelLayout::Rgb));
assert_eq!(img.data(), &[1, 0, 128, 0, 255, 0]);
}
#[test]
fn writes_24_plane_byte_run1_that_reads_back_exactly() {
// 37 pixels wide: three plane-row words, the last one partly padding.
let (w, h) = (37u32, 3u32);
let data: Vec<u8> = (0..w * h * 3).map(|i| (i * 7 % 256) as u8).collect();
let img = Image::from_u8(w, h, ChannelLayout::Rgb, data.clone()).unwrap();
let bytes = encode(&img).unwrap();
assert!(looks_like_iff(&bytes));
assert_eq!(be32(&bytes, 4).unwrap() as usize, bytes.len() - 8, "FORM length");
let h = parse_header(&bytes, false).unwrap();
assert_eq!((h.width, h.height, h.planes, h.masking, h.compression), (37, 3, 24, 0, 1));
assert!(chunks(&bytes).all(|c| &c.id != b"CMAP"), "a deep ILBM has no palette");
let back = decode(&bytes, &Limits::default()).unwrap();
assert_eq!(back.layout(), ChannelLayout::Rgb);
assert_eq!(back.data(), &data[..]);
}
#[test]
fn alpha_is_written_as_a_mask_plane() {
let data = [10, 20, 30, 0, 40, 50, 60, 127, 70, 80, 90, 128, 1, 2, 3, 255];
let img = Image::from_u8(4, 1, ChannelLayout::Rgba, data.to_vec()).unwrap();
let bytes = encode(&img).unwrap();
assert_eq!(parse_header(&bytes, false).unwrap().masking, 1);
let back = decode(&bytes, &Limits::default()).unwrap();
assert_eq!(back.layout(), ChannelLayout::Rgba);
assert_eq!(back.data(), &[10, 20, 30, 0, 40, 50, 60, 0, 70, 80, 90, 255, 1, 2, 3, 255]);
}
#[test]
fn byte_run1_round_trips_runs_literals_and_long_rows() {
let mut rows: Vec<Vec<u8>> = vec![vec![], vec![5], vec![5, 5], vec![5, 5, 5], vec![1, 2, 2, 2, 3], vec![9; 300]];
rows.push((0..300).map(|i| (i % 251) as u8).collect());
rows.push([vec![1, 2], vec![7; 129], vec![3]].concat());
for row in rows {
let mut packed = Vec::new();
pack_byte_run1(&row, &mut packed);
let mut back = vec![0; row.len()];
assert_eq!(unpack_byte_run1(&packed, &mut back).unwrap(), packed.len(), "{row:?}");
assert_eq!(back, row);
}
// A long repeat packs into two-byte runs.
let mut packed = Vec::new();
pack_byte_run1(&[0; 256], &mut packed);
assert_eq!(packed, [0x81, 0, 0x81, 0]);
}
#[test]
fn rejects_what_ilbm_cannot_store() {
let gray = Image::from_u8(1, 1, ChannelLayout::Gray, vec![0]).unwrap();
assert!(encode(&gray).is_err());
let wide = Image::from_u8(65536, 1, ChannelLayout::Rgb, vec![0; 65536 * 3]).unwrap();
assert!(encode(&wide).is_err());
// A transparent color index has no meaning without a palette.
let mut b = ilbm(1, 1, 24, &[], 0, &[0; 48]);
b[29] = 2;
assert!(matches!(decode(&b, &Limits::default()), Err(CodecError::Unsupported { .. })));
}
#[test]
fn hostile_input_errors_not_panics() {
// Truncations of a valid file never panic.
let body = [0b0100_0000, 0, 0b0100_0000, 0];
let full = ilbm(2, 1, 2, &[[1, 2, 3], [4, 5, 6], [7, 8, 9], [10, 11, 12]], 0, &body);
for cut in [0, 4, 8, 12, 40, full.len() - 1] {
assert!(decode(&full[..cut.min(full.len())], &Limits::default()).is_err(), "cut {cut}");
}
// Too many planes is unsupported.
let bad = ilbm(1, 1, 9, &[], 0, &[0, 0]);
assert!(matches!(decode(&bad, &Limits::default()), Err(CodecError::Unsupported { .. })));
}
bridge::encode(image, Format::Iff, &Default::default())
}
+19 -34
View File
@@ -18,10 +18,10 @@
#![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;
mod dds_bc;
pub mod dicom;
pub mod fits;
pub mod iff;
@@ -215,47 +215,32 @@ impl Limits {
/// 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> {
if width == 0 || height == 0 {
return Err(CodecError::InvalidImage(format!("zero-sized image {width}x{height}")));
}
if width > self.max_width || height > self.max_height {
return Err(CodecError::LimitExceeded(format!("dimensions {width}x{height} exceed max {}x{}", self.max_width, self.max_height)));
}
let pixels = width as u64 * height as u64;
if pixels > self.max_pixels {
return Err(CodecError::LimitExceeded(format!("{pixels} pixels exceed max {}", self.max_pixels)));
}
let bytes = pixels.saturating_mul((layout.channels() * sample.bytes()) as u64);
if bytes > self.max_alloc {
return Err(CodecError::LimitExceeded(format!("{bytes} bytes exceed max_alloc {}", self.max_alloc)));
}
if usize::try_from(bytes).is_err() {
return Err(CodecError::LimitExceeded(format!("{bytes} bytes do not fit in memory")));
}
Ok(())
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(crate) fn check_plausible(declared_bytes: u64, file_len: usize, max_ratio: u64) -> Result<(), CodecError> {
let capacity = (file_len as u64).saturating_mul(max_ratio).saturating_add(1 << 20);
if declared_bytes > capacity {
return Err(CodecError::LimitExceeded(format!("a {file_len} byte file cannot hold {declared_bytes} bytes of image data")));
}
Ok(())
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)
}
}
/// A zero-filled buffer of `len` elements, allocated fallibly: an allocation failure is
/// [`CodecError::LimitExceeded`] instead of an abort.
pub(crate) fn alloc_zeroed<T: Copy + Default>(len: usize) -> Result<Vec<T>, CodecError> {
let mut v = Vec::new();
v.try_reserve_exact(len).map_err(|_| CodecError::LimitExceeded(format!("cannot allocate {len} elements for the image")))?;
v.resize(len, T::default());
Ok(v)
}
#[cfg(test)]
mod tests {
use super::*;
+9 -140
View File
@@ -1,144 +1,13 @@
//! ZSoft PCX (Paintbrush) reader: strictly bounded scanline RLE, 16/256-colour
//! palettes, 8-bit three-plane RGB and four-plane RGBA. Read-only: modern saves should use PNG.
//! PCX compatibility facade; implementation and header probing live in craft-image-codecs.
use crate::{CodecError, Image, Limits, bridge};
use craft_image_codecs::Format;
use crate::{ChannelLayout, CodecError, Image, Limits, SampleType};
const HEADER: usize = 128;
fn bad(reason: impl std::fmt::Display) -> CodecError {
CodecError::malformed("PCX", reason)
pub fn looks_like_pcx(bytes: &[u8]) -> bool {
craft_image_codecs::detect(bytes) == Some(Format::Pcx)
}
fn le16(b: &[u8], i: usize) -> u16 {
u16::from_le_bytes([b[i], b[i + 1]])
pub fn dimensions(bytes: &[u8]) -> Option<(u32, u32)> {
craft_image_codecs::pcx_dimensions(bytes)
}
/// PCX lacks a strong magic number. Require plausible complete header fields before
/// identifying it, rather than classifying every file starting with 0x0a as PCX.
pub fn looks_like_pcx(b: &[u8]) -> bool {
if b.len() < HEADER || b[0] != 0x0a || !matches!(b[1], 0 | 2..=5) || b[2] != 1 {
return false;
}
let bits = b[3];
let planes = b[65];
let stride = u32::from(le16(b, 66));
let (x0, y0, x1, y1) = (le16(b, 4), le16(b, 6), le16(b, 8), le16(b, 10));
if x1 < x0 || y1 < y0 || !matches!(bits, 1 | 2 | 4 | 8) || !(1..=4).contains(&planes) {
return false;
}
let width = u32::from(x1 - x0) + 1;
let min_stride = (width * u32::from(bits)).div_ceil(8);
stride >= min_stride && stride > 0 && (bits != 8 || matches!(planes, 1 | 3 | 4)) && (bits == 8 || u32::from(bits) * u32::from(planes) <= 4)
}
/// Read one compressed scanline, including all planes. RLE packets never cross a scanline.
fn read_row(b: &[u8], pos: &mut usize, out: &mut [u8]) -> Result<(), CodecError> {
let mut n = 0;
while n < out.len() {
let code = *b.get(*pos).ok_or_else(|| bad("truncated pixel RLE"))?;
*pos += 1;
let (count, value) = if code >= 0xc0 {
let count = usize::from(code & 0x3f);
let value = *b.get(*pos).ok_or_else(|| bad("truncated RLE packet"))?;
*pos += 1;
(count, value)
} else {
(1, code)
};
if count == 0 || count > out.len() - n {
return Err(bad("RLE packet crosses a scanline or has zero length"));
}
out[n..n + count].fill(value);
n += count;
}
Ok(())
}
/// The pixel size a PCX header declares, without decoding; `None` when [`looks_like_pcx`] is false.
pub fn dimensions(b: &[u8]) -> Option<(u32, u32)> {
looks_like_pcx(b).then(|| (u32::from(le16(b, 8) - le16(b, 4)) + 1, u32::from(le16(b, 10) - le16(b, 6)) + 1))
}
/// Decodes to 8-bit RGB, or RGBA for four 8-bit planes (red, green, blue, alpha).
pub fn decode(b: &[u8], limits: &Limits) -> Result<Image, CodecError> {
let (w, h) = dimensions(b).ok_or_else(|| bad("invalid PCX header or unsupported pixel layout"))?;
let (bits, planes, stride) = (usize::from(b[3]), usize::from(b[65]), usize::from(le16(b, 66)));
let layout = if bits == 8 && planes == 4 { ChannelLayout::Rgba } else { ChannelLayout::Rgb };
let ch = layout.channels();
limits.check(w, h, layout, SampleType::U8)?;
let row_len = stride.checked_mul(planes).ok_or_else(|| bad("row size overflow"))?;
let total = (w as usize).checked_mul(h as usize).and_then(|n| n.checked_mul(ch)).ok_or_else(|| bad("pixel size overflow"))?;
// The last 769 bytes are the optional VGA palette for 8-bit indexed images.
let vga = bits == 8 && planes == 1 && b.len() >= HEADER + 769 && b[b.len() - 769] == 0x0c;
if bits == 8 && planes == 1 && !vga && le16(b, 68) != 2 {
return Err(bad("8-bit indexed PCX has no 256-colour palette"));
}
let image_end = if vga { b.len() - 769 } else { b.len() };
// A 63-byte RLE packet takes 2 bytes; a trailing remainder of 1 byte below 0xC0
// can be encoded as a 1-byte literal, while any larger remainder takes at least 2 bytes.
// Because RLE packets may span planes within a scanline (`row_len`), compute the
// minimum encoded bytes across the full scanline (`row_len`) and multiply by `h`.
// Reject inputs that cannot possibly contain all scanlines before allocating
// the decoded image buffer.
let min_packets = (row_len / 63)
.checked_mul(2)
.and_then(|n| {
n.checked_add(match row_len % 63 {
0 => 0,
1 => 1,
_ => 2,
})
})
.ok_or_else(|| bad("compressed row size overflow"))?;
let min_encoded = min_packets.checked_mul(h as usize).ok_or_else(|| bad("compressed image size overflow"))?;
let encoded_len = image_end.saturating_sub(HEADER);
if encoded_len < min_encoded {
return Err(bad("PCX pixel data is too short for the declared image"));
}
let mut row = vec![0u8; row_len];
let mut pixels = Vec::new();
pixels.try_reserve_exact(total).map_err(|_| bad("PCX pixel buffer is too large"))?;
pixels.resize(total, 0);
let mut p = HEADER;
let width = w as usize;
for y in 0..h as usize {
read_row(&b[..image_end], &mut p, &mut row)?;
for x in 0..width {
let at = (y * width + x) * ch;
let rgb = if bits == 8 && planes >= 3 {
if planes == 4 {
pixels[at + 3] = row[3 * stride + x];
}
[row[x], row[stride + x], row[2 * stride + x]]
} else {
let index = if bits == 8 {
usize::from(row[x])
} else {
let bit = x * bits;
let shift = 8 - bits - (bit % 8);
let mask = (1usize << bits) - 1;
(0..planes).fold(0usize, |v, plane| {
let sample = (usize::from(row[plane * stride + bit / 8]) >> shift) & mask;
v | sample << (plane * bits)
})
};
if vga {
let o = image_end + 1 + index * 3;
[b[o], b[o + 1], b[o + 2]]
} else if bits == 8 {
let g = index as u8;
[g, g, g] // palette-info 2: gray scale
} else {
let o = 16 + index * 3;
[b[o], b[o + 1], b[o + 2]]
}
};
pixels[at..at + 3].copy_from_slice(&rgb);
}
}
let mut image = Image::from_u8(w, h, layout, pixels)?;
let (xdpi, ydpi) = (le16(b, 12), le16(b, 14));
if xdpi > 0 && ydpi > 0 {
image.dpi = Some((f32::from(xdpi), f32::from(ydpi)));
}
Ok(image)
pub fn decode(bytes: &[u8], limits: &Limits) -> Result<Image, CodecError> {
bridge::format(Format::Pcx, bytes, limits)
}
+12 -351
View File
@@ -1,357 +1,18 @@
//! Netpbm family, implemented here: P1–P6 (PBM/PGM/PPM, ASCII and binary),
//! P7 (PAM, including the common `CMYK`/`CMYK_ALPHA` tuple types) and PFM
//! (`PF` colour / `Pf` gray float).
//!
//! Writing picks the subtype from the image: float → PFM (gray/RGB), gray
//! → P5, RGB → P6, anything with alpha or CMYK → P7.
//! Netpbm compatibility facade; implementation and bounds live in craft-image-codecs.
use crate::{CodecError, Image, Limits, bridge};
use craft_image_codecs::Format;
use crate::{ChannelLayout, CodecError, Image, Limits, SampleType};
const F: &str = "PNM";
fn err(msg: impl std::fmt::Display) -> CodecError {
CodecError::malformed(F, msg)
pub fn looks_like_pnm(bytes: &[u8]) -> bool {
craft_image_codecs::detect(bytes) == Some(Format::Pnm)
}
struct Reader<'a> {
b: &'a [u8],
pos: usize,
}
impl<'a> Reader<'a> {
fn skip_ws_and_comments(&mut self) {
while self.pos < self.b.len() {
let c = self.b[self.pos];
if c == b'#' {
while self.pos < self.b.len() && self.b[self.pos] != b'\n' && self.b[self.pos] != b'\r' {
self.pos += 1;
}
} else if c.is_ascii_whitespace() {
self.pos += 1;
} else {
break;
}
}
}
fn token(&mut self) -> Result<&'a [u8], CodecError> {
self.skip_ws_and_comments();
let start = self.pos;
while self.pos < self.b.len() && !self.b[self.pos].is_ascii_whitespace() && self.b[self.pos] != b'#' {
self.pos += 1;
}
if start == self.pos {
return Err(err("unexpected end of header"));
}
Ok(&self.b[start..self.pos])
}
fn uint(&mut self) -> Result<u32, CodecError> {
let t = self.token()?;
std::str::from_utf8(t).ok().and_then(|s| s.parse::<u32>().ok()).ok_or_else(|| err("invalid integer in header"))
}
/// Consume the single whitespace byte that separates header and raster.
fn single_ws(&mut self) -> Result<(), CodecError> {
match self.b.get(self.pos) {
Some(c) if c.is_ascii_whitespace() => {
self.pos += 1;
Ok(())
}
_ => Err(err("missing whitespace after header")),
}
}
/// PAM ends its header with an LF-terminated line, unlike P4–P6's single separator.
fn pam_endhdr(&mut self) -> Result<(), CodecError> {
while let Some(&c) = self.b.get(self.pos) {
self.pos += 1;
if c == b'\n' {
// Stop at the first LF: whitespace and '#' after it are raster bytes.
return Ok(());
}
if !c.is_ascii_whitespace() {
return Err(err("unexpected data after PAM ENDHDR"));
}
}
Err(err("unterminated PAM ENDHDR line"))
}
fn rest(&self) -> &'a [u8] {
&self.b[self.pos.min(self.b.len())..]
}
}
fn sample_for_maxval(maxval: u32) -> Result<SampleType, CodecError> {
match maxval {
1..=255 => Ok(SampleType::U8),
256..=65535 => Ok(SampleType::U16),
_ => Err(err(format!("invalid maxval {maxval}"))),
}
}
/// The decoded raster, built straight in the output representation. It is the only buffer sized
/// by the header, so `Limits::check` on the output budgets all of it: no wider scratch buffer
/// (such as one `u32` per sample) sits beside it.
struct Samples {
maxval: u32,
sample: SampleType,
bytes: Vec<u8>,
}
impl Samples {
/// Reserve room for `cap` samples (callers bound `cap` by the file length where the header
/// alone could overstate it).
fn with_capacity(maxval: u32, cap: usize) -> Result<Self, CodecError> {
let sample = sample_for_maxval(maxval)?;
let len = cap.checked_mul(sample.bytes()).ok_or_else(|| CodecError::LimitExceeded(format!("{cap} samples do not fit in memory")))?;
let mut bytes = Vec::new();
bytes.try_reserve_exact(len).map_err(|_| CodecError::LimitExceeded(format!("cannot allocate {len} bytes for the image")))?;
Ok(Samples { maxval, sample, bytes })
}
/// Append one raw value in `[0, maxval]`, rescaled to the full range of the output sample.
fn push(&mut self, v: u32) -> Result<(), CodecError> {
let m = self.maxval;
if v > m {
return Err(err("sample exceeds maxval"));
}
match (self.sample, m) {
(SampleType::U8, 255) => self.bytes.push(v as u8),
(SampleType::U8, m) => self.bytes.push(((v * 255 + m / 2) / m) as u8),
(_, 65535) => self.bytes.extend_from_slice(&(v as u16).to_ne_bytes()),
(_, m) => self.bytes.extend_from_slice(&(((v as u64 * 65535 + m as u64 / 2) / m as u64) as u16).to_ne_bytes()),
}
Ok(())
}
fn into_image(self, w: u32, h: u32, layout: ChannelLayout) -> Result<Image, CodecError> {
Image::from_raw(w, h, layout, self.sample, self.bytes)
}
}
/// `w × h × channels` samples. `Limits::none()` lets any header through, so the product is
/// checked here rather than trusted to the limits.
fn sample_count(w: u32, h: u32, channels: usize) -> Result<usize, CodecError> {
(w as usize)
.checked_mul(h as usize)
.and_then(|p| p.checked_mul(channels))
.ok_or_else(|| CodecError::LimitExceeded(format!("{w}x{h}x{channels} samples do not fit in memory")))
}
fn read_binary(data: &[u8], n: usize, maxval: u32) -> Result<Samples, CodecError> {
let mut out = Samples::with_capacity(maxval, n)?;
if maxval < 256 {
let Some(raw) = data.get(..n) else {
return Err(err("truncated raster"));
};
for &v in raw {
out.push(v as u32)?;
}
} else {
let Some(raw) = n.checked_mul(2).and_then(|len| data.get(..len)) else {
return Err(err("truncated raster"));
};
for c in raw.as_chunks::<2>().0 {
out.push(u16::from_be_bytes(*c) as u32)?;
}
}
Ok(out)
}
/// `P1`..`P7`, `PF` or `Pf` followed by white space.
pub fn looks_like_pnm(b: &[u8]) -> bool {
matches!(b, [b'P', b'1'..=b'7' | b'F' | b'f', s, ..] if s.is_ascii_whitespace())
}
pub fn decode(bytes: &[u8], limits: &Limits) -> Result<Image, CodecError> {
if bytes.len() < 2 || bytes[0] != b'P' {
return Err(err("not a Netpbm file"));
}
let kind = bytes[1];
let mut r = Reader { b: bytes, pos: 2 };
match kind {
b'1' | b'4' => {
let (w, h) = (r.uint()?, r.uint()?);
limits.check(w, h, ChannelLayout::Gray, SampleType::U8)?;
let n = sample_count(w, h, 1)?;
let mut px;
if kind == b'4' {
r.single_ws()?;
let row = (w as usize).div_ceil(8);
let data = r.rest();
if row.checked_mul(h as usize).is_none_or(|len| data.len() < len) {
return Err(err("truncated raster"));
}
px = Vec::with_capacity(n);
for y in 0..h as usize {
for x in 0..w as usize {
let bit = (data[y * row + x / 8] >> (7 - x % 8)) & 1;
px.push(if bit == 1 { 0 } else { 255 });
}
}
} else {
// Each ASCII pixel takes at least a byte, so the file bounds the reservation.
px = Vec::with_capacity(n.min(r.rest().len()));
while px.len() < n {
r.skip_ws_and_comments();
match r.b.get(r.pos) {
Some(b'0') => px.push(255),
Some(b'1') => px.push(0),
Some(_) => return Err(err("invalid PBM digit")),
None => return Err(err("truncated raster")),
}
r.pos += 1;
}
}
Image::from_u8(w, h, ChannelLayout::Gray, px)
}
b'2' | b'3' | b'5' | b'6' => {
let (w, h, maxval) = (r.uint()?, r.uint()?, r.uint()?);
let layout = if matches!(kind, b'2' | b'5') { ChannelLayout::Gray } else { ChannelLayout::Rgb };
limits.check(w, h, layout, sample_for_maxval(maxval)?)?;
let n = sample_count(w, h, layout.channels())?;
let samples = if matches!(kind, b'5' | b'6') {
r.single_ws()?;
read_binary(r.rest(), n, maxval)?
} else {
// Each ASCII sample is a digit and a separator (the last may lack one), so the
// file, not the header, bounds the reservation.
let mut v = Samples::with_capacity(maxval, n.min(r.rest().len() / 2 + 1))?;
for _ in 0..n {
v.push(r.uint()?)?;
}
v
};
samples.into_image(w, h, layout)
}
b'7' => decode_pam(&mut r, limits),
b'F' | b'f' => {
let layout = if kind == b'F' { ChannelLayout::Rgb } else { ChannelLayout::Gray };
let (w, h) = (r.uint()?, r.uint()?);
let scale: f32 = std::str::from_utf8(r.token()?)
.ok()
.and_then(|s| s.parse().ok())
.filter(|s: &f32| s.is_finite() && *s != 0.0)
.ok_or_else(|| err("invalid PFM scale"))?;
r.single_ws()?;
limits.check(w, h, layout, SampleType::F32)?;
let nc = layout.channels();
let row = w as usize * nc;
let data = r.rest();
if sample_count(w, h, nc)?.checked_mul(4).is_none_or(|len| data.len() < len) {
return Err(err("truncated raster"));
}
let le = scale < 0.0;
// Write native-endian bytes straight into the output buffer: a separate `Vec<f32>`
// would double the budgeted allocation.
let row_bytes = row * 4;
let mut out = vec![0u8; row_bytes * h as usize];
for (y, src) in data.chunks_exact(row_bytes).take(h as usize).enumerate() {
// PFM rows are stored bottom-to-top.
let dst_start = (h as usize - 1 - y) * row_bytes;
let Some(dst) = out.get_mut(dst_start..dst_start + row_bytes) else {
return Err(err("truncated raster"));
};
for (d, s) in dst.as_chunks_mut::<4>().0.iter_mut().zip(src.as_chunks::<4>().0) {
let v = if le { f32::from_le_bytes(*s) } else { f32::from_be_bytes(*s) };
*d = v.to_ne_bytes();
}
}
Image::from_raw(w, h, layout, SampleType::F32, out)
}
_ => Err(err("unknown Netpbm subtype")),
}
bridge::format(Format::Pnm, bytes, limits)
}
fn decode_pam(r: &mut Reader<'_>, limits: &Limits) -> Result<Image, CodecError> {
let (mut w, mut h, mut depth, mut maxval) = (None, None, None, None);
let mut tupltype = String::new();
loop {
let tok = r.token()?;
match tok {
b"WIDTH" => w = Some(r.uint()?),
b"HEIGHT" => h = Some(r.uint()?),
b"DEPTH" => depth = Some(r.uint()?),
b"MAXVAL" => maxval = Some(r.uint()?),
b"TUPLTYPE" => {
let t = r.token()?;
if !tupltype.is_empty() {
tupltype.push(' ');
}
tupltype.push_str(std::str::from_utf8(t).map_err(|_| err("bad TUPLTYPE"))?);
}
b"ENDHDR" => break,
_ => return Err(err("unknown PAM header field")),
}
pub fn encode(image: &Image) -> Result<Vec<u8>, CodecError> {
// PFM has only gray and RGB tuples. Preserve this facade's contract that
// unsupported layouts are refused instead of silently dropping alpha.
if image.sample_type() == crate::SampleType::F32 && !matches!(image.layout(), crate::ChannelLayout::Gray | crate::ChannelLayout::Rgb) {
return Err(CodecError::encode("PNM", format!("PFM cannot store {:?}", image.layout())));
}
r.pam_endhdr()?;
let (w, h, depth, maxval) = match (w, h, depth, maxval) {
(Some(a), Some(b), Some(c), Some(d)) => (a, b, c, d),
_ => return Err(err("incomplete PAM header")),
};
let layout = match (tupltype.as_str(), depth) {
("BLACKANDWHITE" | "GRAYSCALE", 1) | ("", 1) => ChannelLayout::Gray,
("BLACKANDWHITE_ALPHA" | "GRAYSCALE_ALPHA", 2) | ("", 2) => ChannelLayout::GrayA,
("RGB", 3) | ("", 3) => ChannelLayout::Rgb,
("RGB_ALPHA", 4) | ("", 4) => ChannelLayout::Rgba,
("CMYK", 4) => ChannelLayout::Cmyk,
("CMYK_ALPHA", 5) => ChannelLayout::CmykA,
(t, d) => {
return Err(CodecError::unsupported(F, format!("PAM tuple type {t:?} with depth {d}")));
}
};
limits.check(w, h, layout, sample_for_maxval(maxval)?)?;
let n = sample_count(w, h, layout.channels())?;
read_binary(r.rest(), n, maxval)?.into_image(w, h, layout)
}
/// Writes `img` as PGM/PPM (gray, RGB), PAM (alpha, CMYK) or PFM (float gray, RGB).
pub fn encode(img: &Image) -> Result<Vec<u8>, CodecError> {
let (w, h) = (img.width(), img.height());
let layout = img.layout();
let mut out = Vec::new();
match img.sample_type() {
SampleType::F32 => {
let tag = match layout {
ChannelLayout::Gray => "Pf",
ChannelLayout::Rgb => "PF",
l => return Err(CodecError::encode(F, format!("PFM cannot store {l:?}"))),
};
out.extend_from_slice(format!("{tag}\n{w} {h}\n-1.0\n").as_bytes());
let s = img.to_f32_samples().unwrap_or_default();
let row = w as usize * layout.channels();
for y in (0..h as usize).rev() {
for v in &s[y * row..(y + 1) * row] {
out.extend_from_slice(&v.to_le_bytes());
}
}
}
sample @ (SampleType::U8 | SampleType::U16) => {
let maxval = if sample == SampleType::U8 { 255 } else { 65535 };
match layout {
ChannelLayout::Gray => out.extend_from_slice(format!("P5\n{w} {h}\n{maxval}\n").as_bytes()),
ChannelLayout::Rgb => out.extend_from_slice(format!("P6\n{w} {h}\n{maxval}\n").as_bytes()),
l => {
let t = match l {
ChannelLayout::GrayA => "GRAYSCALE_ALPHA",
ChannelLayout::Rgba => "RGB_ALPHA",
ChannelLayout::Cmyk => "CMYK",
_ => "CMYK_ALPHA",
};
out.extend_from_slice(
format!("P7\nWIDTH {w}\nHEIGHT {h}\nDEPTH {}\nMAXVAL {maxval}\nTUPLTYPE {t}\nENDHDR\n", l.channels()).as_bytes(),
);
}
}
if sample == SampleType::U8 {
out.extend_from_slice(img.data());
} else {
for v in img.to_u16_samples().unwrap_or_default() {
out.extend_from_slice(&v.to_be_bytes());
}
}
}
}
Ok(out)
bridge::encode(image, Format::Pnm, &Default::default())
}
+7 -237
View File
@@ -1,243 +1,13 @@
//! X PixMap reader for XPM2 plain-text icons and XPM3 C-source icon arrays.
//! Supports transparency (None), RGB hex at 4/8/16 bits per channel and
//! common X11 colour names. Does not execute C code.
//! XPM compatibility facade; implementation and color-name data live in craft-image-codecs.
use crate::{CodecError, Image, Limits, bridge};
use craft_image_codecs::Format;
use std::collections::HashMap;
mod x11_colors;
use crate::{ChannelLayout, CodecError, Image, Limits, SampleType};
const MAX_SOURCE: usize = 256 << 20;
const MAX_COLOURS: usize = 65_536;
const MAX_CPP: usize = 8;
fn bad(msg: impl std::fmt::Display) -> CodecError {
CodecError::malformed("XPM", msg)
}
/// Extract C string literals without treating quoted text or // in a string as a comment.
/// XPM uses one literal for the header, each palette entry and each row.
fn c_strings(bytes: &[u8]) -> Result<Vec<Vec<u8>>, CodecError> {
let mut lines = Vec::new();
let mut i = 0usize;
while i < bytes.len() {
if bytes[i..].starts_with(b"/*") {
let tail = &bytes[i + 2..];
let Some(end) = tail.windows(2).position(|p| p == b"*/") else { return Err(bad("unterminated C comment")) };
i += end + 4;
} else if bytes[i..].starts_with(b"//") {
i += bytes[i..].iter().position(|&c| c == b'\n').unwrap_or(bytes.len() - i);
} else if bytes[i] == b'"' {
i += 1;
let mut s = Vec::new();
let mut closed = false;
while i < bytes.len() {
let c = bytes[i];
i += 1;
match c {
b'"' => {
closed = true;
break;
}
b'\\' => {
let next = *bytes.get(i).ok_or_else(|| bad("truncated C escape"))?;
i += 1;
s.push(match next {
b'n' => b'\n',
b'r' => b'\r',
b't' => b'\t',
b'0' => 0,
_ => next, // quoted backslash or quote
});
}
_ => s.push(c),
}
}
if !closed {
return Err(bad("unterminated XPM string"));
}
lines.push(s);
} else {
i += 1;
}
}
Ok(lines)
}
/// Extract XPM2's plain-text lines without trimming pixel rows: leading and
/// trailing spaces can be palette keys, and physical CRLF is not image data.
fn xpm2_lines(bytes: &[u8]) -> Result<Vec<Vec<u8>>, CodecError> {
let mut input = bytes.split(|&b| b == b'\n');
let header = input.next().ok_or_else(|| bad("missing XPM2 marker"))?;
if header.strip_suffix(b"\r").unwrap_or(header) != b"! XPM2" {
return Err(bad("not an XPM2 image"));
}
let mut lines = Vec::new();
for raw in input {
let line = raw.strip_suffix(b"\r").unwrap_or(raw);
// The header may be preceded by comments and blank lines. After the
// header, a leading '!' is allowed as a palette key or pixel value.
if lines.is_empty() && (line.is_empty() || line.starts_with(b"!")) {
continue;
}
lines.push(line.to_vec());
}
Ok(lines)
}
fn channel(hex: &str) -> Option<u8> {
let v = u32::from_str_radix(hex, 16).ok()?;
let max = (1u32 << (hex.len() * 4)) - 1;
Some(((v * 255 + max / 2) / max) as u8)
}
fn named(name: &str) -> Option<[u8; 3]> {
let s = name.to_ascii_lowercase().replace([' ', '-', '_'], "");
// XPM imports X11 names, whose RGB values differ from CSS for names
// such as gray, maroon and purple. Keep these exact rather than guessing.
if let Ok(index) = x11_colors::X11_COLORS.binary_search_by_key(&s.as_str(), |(name, _)| *name) {
return Some(x11_colors::X11_COLORS[index].1);
}
// Retain useful web color aliases not present in the X11 database.
Some(match s.as_str() {
"silver" => [192, 192, 192],
"olive" => [128, 128, 0],
"teal" => [0, 128, 128],
"fuchsia" => [255, 0, 255],
"navyblue" => [0, 0, 128],
_ => return None,
})
}
/// Look up an exact normalized X11 color name as RGB channels in `0..=1`.
///
/// Names must contain 1–64 bytes of lowercase ASCII letters or digits. Unknown names,
/// unnormalized names and XPM-only aliases return `None`; this does not parse hex colors
/// or transparency. Values are the stored X11 bytes divided by 255, without CSS overrides
/// or color-space conversion. XPM decoding retains its own normalization and alias policy.
pub fn x11_color_rgb(name: &str) -> Option<[f32; 3]> {
// Bound work on untrusted names before searching the shared table, without allocating.
if name.is_empty() || name.len() > 64 || !name.bytes().all(|b| b.is_ascii_lowercase() || b.is_ascii_digit()) {
return None;
}
let index = x11_colors::X11_COLORS.binary_search_by_key(&name, |(entry, _)| *entry).ok()?;
let (_, rgb) = x11_colors::X11_COLORS.get(index)?;
Some(rgb.map(|channel| f32::from(channel) / 255.0))
craft_image_codecs::xpm_named_color_rgb(name)
}
fn color(name: &str) -> Option<[u8; 4]> {
if name.eq_ignore_ascii_case("none") {
return Some([0, 0, 0, 0]);
}
let rgb = if let Some(hex) = name.strip_prefix('#') {
// UTF-8 byte lengths can match a supported hex width while slicing would panic.
// `from_str_radix` would also take a leading `+`: accept hex digits only.
if !hex.bytes().all(|b| b.is_ascii_hexdigit()) {
return None;
}
let digits = match hex.len() {
3 => 1,
6 => 2,
12 => 4,
_ => return None,
};
let rgb = (0..3).map(|i| channel(&hex[i * digits..(i + 1) * digits])).collect::<Option<Vec<_>>>()?;
[rgb[0], rgb[1], rgb[2]]
} else {
named(name)?
};
Some([rgb[0], rgb[1], rgb[2], 255])
pub fn looks_like_xpm(bytes: &[u8]) -> bool {
craft_image_codecs::detect(bytes) == Some(Format::Xpm)
}
/// The XPM3 comment or the XPM2 first line.
pub fn looks_like_xpm(b: &[u8]) -> bool {
b.starts_with(b"/* XPM */") || b.starts_with(b"! XPM2\n") || b.starts_with(b"! XPM2\r\n")
}
pub fn decode(bytes: &[u8], limits: &Limits) -> Result<Image, CodecError> {
if bytes.len() > MAX_SOURCE {
return Err(CodecError::LimitExceeded("XPM source exceeds 256 MiB".into()));
}
let lines = if bytes.starts_with(b"/* XPM */") {
c_strings(bytes)?
} else if bytes.starts_with(b"! XPM2\n") || bytes.starts_with(b"! XPM2\r\n") {
xpm2_lines(bytes)?
} else {
return Err(bad("not an XPM2/XPM3 image"));
};
decode_lines(&lines, limits)
}
fn decode_lines(lines: &[Vec<u8>], limits: &Limits) -> Result<Image, CodecError> {
let header = lines.first().ok_or_else(|| bad("missing image header"))?;
let parts = std::str::from_utf8(header).map_err(|_| bad("non-UTF-8 XPM header"))?;
let mut parts = parts.split_ascii_whitespace();
let number = |key: &str, s: Option<&str>| -> Result<usize, CodecError> {
s.ok_or_else(|| bad(format!("missing {key}")))?.parse::<usize>().map_err(|_| bad(format!("invalid {key}")))
};
let width = number("width", parts.next())?;
let height = number("height", parts.next())?;
let colours = number("palette size", parts.next())?;
let cpp = number("chars per pixel", parts.next())?;
if width == 0 || height == 0 || colours == 0 || colours > MAX_COLOURS || !(1..=MAX_CPP).contains(&cpp) {
return Err(bad("invalid XPM dimensions, palette size or chars per pixel"));
}
let (w, h) = (u32::try_from(width).map_err(|_| bad("width overflow"))?, u32::try_from(height).map_err(|_| bad("height overflow"))?);
limits.check(w, h, ChannelLayout::Rgba, SampleType::U8)?;
let required = 1usize.checked_add(colours).and_then(|n| n.checked_add(height)).ok_or_else(|| bad("row count overflow"))?;
if lines.len() < required {
return Err(bad("truncated palette or image rows"));
}
let mut palette = HashMap::<Vec<u8>, [u8; 4]>::with_capacity(colours);
for line in &lines[1..1 + colours] {
if line.len() < cpp {
return Err(bad("truncated colour key"));
}
let fields = std::str::from_utf8(&line[cpp..]).map_err(|_| bad("invalid colour name"))?;
// XPM priority is colour, gray, four-level gray, then monochrome,
// regardless of the order of keys in the palette entry.
let terms: Vec<&str> = fields.split_ascii_whitespace().collect();
let mut picked: Option<(u8, String)> = None;
let mut i = 0;
while i < terms.len() {
let priority = match terms[i] {
"c" => 4,
"g" => 3,
"g4" => 2,
"m" => 1,
_ => 0, // Symbolic names ('s') are not colour values.
};
let start = i + 1;
i = start;
while i < terms.len() && !matches!(terms[i], "c" | "g" | "g4" | "m" | "s") {
i += 1;
}
if priority > 0 && i > start && picked.as_ref().is_none_or(|(current, _)| priority > *current) {
picked = Some((priority, terms[start..i].join(" ")));
}
}
let value = picked.as_ref().and_then(|(_, name)| color(name)).ok_or_else(|| bad("unsupported or missing XPM colour"))?;
if palette.insert(line[..cpp].to_vec(), value).is_some() {
return Err(bad("duplicate XPM palette key"));
}
}
let row_len = width.checked_mul(cpp).ok_or_else(|| bad("row byte count overflow"))?;
// Validate all source rows before reserving the decoded RGBA image. A malformed
// short row must not be able to make a large header-sized allocation first.
if lines[1 + colours..required].iter().any(|line| line.len() != row_len) {
return Err(bad("XPM row has the wrong width"));
}
let total = width.checked_mul(height).and_then(|n| n.checked_mul(4)).ok_or_else(|| bad("pixel size overflow"))?;
let mut pixels = Vec::new();
pixels.try_reserve_exact(total).map_err(|_| bad("XPM pixel buffer is too large"))?;
pixels.resize(total, 0);
for (y, line) in lines[1 + colours..required].iter().enumerate() {
for x in 0..width {
let key = &line[x * cpp..(x + 1) * cpp];
let rgba = palette.get(key).ok_or_else(|| bad("unknown palette key"))?;
pixels[(y * width + x) * 4..(y * width + x + 1) * 4].copy_from_slice(rgba);
}
}
Image::from_u8(w, h, ChannelLayout::Rgba, pixels)
bridge::format(Format::Xpm, bytes, limits)
}
-666
View File
@@ -1,666 +0,0 @@
//! X11 color-name database (X.Org rgb.txt) normalized to lowercase without
//! spaces, underscores, or hyphens. RGB values are *X11* values, not CSS values.
//! Source: <https://cgit.freedesktop.org/xorg/app/rgb/tree/rgb.txt>
//! License: MIT (X.Org Foundation), see the upstream app/rgb COPYING file.
//! Aliases differing only in case or spaces have been collapsed.
//! Keep sorted: decoder uses binary search without allocation per candidate.
pub(super) const X11_COLORS: &[(&str, [u8; 3])] = &[
("aliceblue", [240, 248, 255]),
("antiquewhite", [250, 235, 215]),
("antiquewhite1", [255, 239, 219]),
("antiquewhite2", [238, 223, 204]),
("antiquewhite3", [205, 192, 176]),
("antiquewhite4", [139, 131, 120]),
("aquamarine", [127, 255, 212]),
("aquamarine1", [127, 255, 212]),
("aquamarine2", [118, 238, 198]),
("aquamarine3", [102, 205, 170]),
("aquamarine4", [69, 139, 116]),
("azure", [240, 255, 255]),
("azure1", [240, 255, 255]),
("azure2", [224, 238, 238]),
("azure3", [193, 205, 205]),
("azure4", [131, 139, 139]),
("beige", [245, 245, 220]),
("bisque", [255, 228, 196]),
("bisque1", [255, 228, 196]),
("bisque2", [238, 213, 183]),
("bisque3", [205, 183, 158]),
("bisque4", [139, 125, 107]),
("black", [0, 0, 0]),
("blanchedalmond", [255, 235, 205]),
("blue", [0, 0, 255]),
("blue1", [0, 0, 255]),
("blue2", [0, 0, 238]),
("blue3", [0, 0, 205]),
("blue4", [0, 0, 139]),
("blueviolet", [138, 43, 226]),
("brown", [165, 42, 42]),
("brown1", [255, 64, 64]),
("brown2", [238, 59, 59]),
("brown3", [205, 51, 51]),
("brown4", [139, 35, 35]),
("burlywood", [222, 184, 135]),
("burlywood1", [255, 211, 155]),
("burlywood2", [238, 197, 145]),
("burlywood3", [205, 170, 125]),
("burlywood4", [139, 115, 85]),
("cadetblue", [95, 158, 160]),
("cadetblue1", [152, 245, 255]),
("cadetblue2", [142, 229, 238]),
("cadetblue3", [122, 197, 205]),
("cadetblue4", [83, 134, 139]),
("chartreuse", [127, 255, 0]),
("chartreuse1", [127, 255, 0]),
("chartreuse2", [118, 238, 0]),
("chartreuse3", [102, 205, 0]),
("chartreuse4", [69, 139, 0]),
("chocolate", [210, 105, 30]),
("chocolate1", [255, 127, 36]),
("chocolate2", [238, 118, 33]),
("chocolate3", [205, 102, 29]),
("chocolate4", [139, 69, 19]),
("coral", [255, 127, 80]),
("coral1", [255, 114, 86]),
("coral2", [238, 106, 80]),
("coral3", [205, 91, 69]),
("coral4", [139, 62, 47]),
("cornflowerblue", [100, 149, 237]),
("cornsilk", [255, 248, 220]),
("cornsilk1", [255, 248, 220]),
("cornsilk2", [238, 232, 205]),
("cornsilk3", [205, 200, 177]),
("cornsilk4", [139, 136, 120]),
("cyan", [0, 255, 255]),
("cyan1", [0, 255, 255]),
("cyan2", [0, 238, 238]),
("cyan3", [0, 205, 205]),
("cyan4", [0, 139, 139]),
("darkblue", [0, 0, 139]),
("darkcyan", [0, 139, 139]),
("darkgoldenrod", [184, 134, 11]),
("darkgoldenrod1", [255, 185, 15]),
("darkgoldenrod2", [238, 173, 14]),
("darkgoldenrod3", [205, 149, 12]),
("darkgoldenrod4", [139, 101, 8]),
("darkgray", [169, 169, 169]),
("darkgreen", [0, 100, 0]),
("darkgrey", [169, 169, 169]),
("darkkhaki", [189, 183, 107]),
("darkmagenta", [139, 0, 139]),
("darkolivegreen", [85, 107, 47]),
("darkolivegreen1", [202, 255, 112]),
("darkolivegreen2", [188, 238, 104]),
("darkolivegreen3", [162, 205, 90]),
("darkolivegreen4", [110, 139, 61]),
("darkorange", [255, 140, 0]),
("darkorange1", [255, 127, 0]),
("darkorange2", [238, 118, 0]),
("darkorange3", [205, 102, 0]),
("darkorange4", [139, 69, 0]),
("darkorchid", [153, 50, 204]),
("darkorchid1", [191, 62, 255]),
("darkorchid2", [178, 58, 238]),
("darkorchid3", [154, 50, 205]),
("darkorchid4", [104, 34, 139]),
("darkred", [139, 0, 0]),
("darksalmon", [233, 150, 122]),
("darkseagreen", [143, 188, 143]),
("darkseagreen1", [193, 255, 193]),
("darkseagreen2", [180, 238, 180]),
("darkseagreen3", [155, 205, 155]),
("darkseagreen4", [105, 139, 105]),
("darkslateblue", [72, 61, 139]),
("darkslategray", [47, 79, 79]),
("darkslategray1", [151, 255, 255]),
("darkslategray2", [141, 238, 238]),
("darkslategray3", [121, 205, 205]),
("darkslategray4", [82, 139, 139]),
("darkslategrey", [47, 79, 79]),
("darkturquoise", [0, 206, 209]),
("darkviolet", [148, 0, 211]),
("deeppink", [255, 20, 147]),
("deeppink1", [255, 20, 147]),
("deeppink2", [238, 18, 137]),
("deeppink3", [205, 16, 118]),
("deeppink4", [139, 10, 80]),
("deepskyblue", [0, 191, 255]),
("deepskyblue1", [0, 191, 255]),
("deepskyblue2", [0, 178, 238]),
("deepskyblue3", [0, 154, 205]),
("deepskyblue4", [0, 104, 139]),
("dimgray", [105, 105, 105]),
("dimgrey", [105, 105, 105]),
("dodgerblue", [30, 144, 255]),
("dodgerblue1", [30, 144, 255]),
("dodgerblue2", [28, 134, 238]),
("dodgerblue3", [24, 116, 205]),
("dodgerblue4", [16, 78, 139]),
("firebrick", [178, 34, 34]),
("firebrick1", [255, 48, 48]),
("firebrick2", [238, 44, 44]),
("firebrick3", [205, 38, 38]),
("firebrick4", [139, 26, 26]),
("floralwhite", [255, 250, 240]),
("forestgreen", [34, 139, 34]),
("gainsboro", [220, 220, 220]),
("ghostwhite", [248, 248, 255]),
("gold", [255, 215, 0]),
("gold1", [255, 215, 0]),
("gold2", [238, 201, 0]),
("gold3", [205, 173, 0]),
("gold4", [139, 117, 0]),
("goldenrod", [218, 165, 32]),
("goldenrod1", [255, 193, 37]),
("goldenrod2", [238, 180, 34]),
("goldenrod3", [205, 155, 29]),
("goldenrod4", [139, 105, 20]),
("gray", [190, 190, 190]),
("gray0", [0, 0, 0]),
("gray1", [3, 3, 3]),
("gray10", [26, 26, 26]),
("gray100", [255, 255, 255]),
("gray11", [28, 28, 28]),
("gray12", [31, 31, 31]),
("gray13", [33, 33, 33]),
("gray14", [36, 36, 36]),
("gray15", [38, 38, 38]),
("gray16", [41, 41, 41]),
("gray17", [43, 43, 43]),
("gray18", [46, 46, 46]),
("gray19", [48, 48, 48]),
("gray2", [5, 5, 5]),
("gray20", [51, 51, 51]),
("gray21", [54, 54, 54]),
("gray22", [56, 56, 56]),
("gray23", [59, 59, 59]),
("gray24", [61, 61, 61]),
("gray25", [64, 64, 64]),
("gray26", [66, 66, 66]),
("gray27", [69, 69, 69]),
("gray28", [71, 71, 71]),
("gray29", [74, 74, 74]),
("gray3", [8, 8, 8]),
("gray30", [77, 77, 77]),
("gray31", [79, 79, 79]),
("gray32", [82, 82, 82]),
("gray33", [84, 84, 84]),
("gray34", [87, 87, 87]),
("gray35", [89, 89, 89]),
("gray36", [92, 92, 92]),
("gray37", [94, 94, 94]),
("gray38", [97, 97, 97]),
("gray39", [99, 99, 99]),
("gray4", [10, 10, 10]),
("gray40", [102, 102, 102]),
("gray41", [105, 105, 105]),
("gray42", [107, 107, 107]),
("gray43", [110, 110, 110]),
("gray44", [112, 112, 112]),
("gray45", [115, 115, 115]),
("gray46", [117, 117, 117]),
("gray47", [120, 120, 120]),
("gray48", [122, 122, 122]),
("gray49", [125, 125, 125]),
("gray5", [13, 13, 13]),
("gray50", [127, 127, 127]),
("gray51", [130, 130, 130]),
("gray52", [133, 133, 133]),
("gray53", [135, 135, 135]),
("gray54", [138, 138, 138]),
("gray55", [140, 140, 140]),
("gray56", [143, 143, 143]),
("gray57", [145, 145, 145]),
("gray58", [148, 148, 148]),
("gray59", [150, 150, 150]),
("gray6", [15, 15, 15]),
("gray60", [153, 153, 153]),
("gray61", [156, 156, 156]),
("gray62", [158, 158, 158]),
("gray63", [161, 161, 161]),
("gray64", [163, 163, 163]),
("gray65", [166, 166, 166]),
("gray66", [168, 168, 168]),
("gray67", [171, 171, 171]),
("gray68", [173, 173, 173]),
("gray69", [176, 176, 176]),
("gray7", [18, 18, 18]),
("gray70", [179, 179, 179]),
("gray71", [181, 181, 181]),
("gray72", [184, 184, 184]),
("gray73", [186, 186, 186]),
("gray74", [189, 189, 189]),
("gray75", [191, 191, 191]),
("gray76", [194, 194, 194]),
("gray77", [196, 196, 196]),
("gray78", [199, 199, 199]),
("gray79", [201, 201, 201]),
("gray8", [20, 20, 20]),
("gray80", [204, 204, 204]),
("gray81", [207, 207, 207]),
("gray82", [209, 209, 209]),
("gray83", [212, 212, 212]),
("gray84", [214, 214, 214]),
("gray85", [217, 217, 217]),
("gray86", [219, 219, 219]),
("gray87", [222, 222, 222]),
("gray88", [224, 224, 224]),
("gray89", [227, 227, 227]),
("gray9", [23, 23, 23]),
("gray90", [229, 229, 229]),
("gray91", [232, 232, 232]),
("gray92", [235, 235, 235]),
("gray93", [237, 237, 237]),
("gray94", [240, 240, 240]),
("gray95", [242, 242, 242]),
("gray96", [245, 245, 245]),
("gray97", [247, 247, 247]),
("gray98", [250, 250, 250]),
("gray99", [252, 252, 252]),
("green", [0, 255, 0]),
("green1", [0, 255, 0]),
("green2", [0, 238, 0]),
("green3", [0, 205, 0]),
("green4", [0, 139, 0]),
("greenyellow", [173, 255, 47]),
("grey", [190, 190, 190]),
("grey0", [0, 0, 0]),
("grey1", [3, 3, 3]),
("grey10", [26, 26, 26]),
("grey100", [255, 255, 255]),
("grey11", [28, 28, 28]),
("grey12", [31, 31, 31]),
("grey13", [33, 33, 33]),
("grey14", [36, 36, 36]),
("grey15", [38, 38, 38]),
("grey16", [41, 41, 41]),
("grey17", [43, 43, 43]),
("grey18", [46, 46, 46]),
("grey19", [48, 48, 48]),
("grey2", [5, 5, 5]),
("grey20", [51, 51, 51]),
("grey21", [54, 54, 54]),
("grey22", [56, 56, 56]),
("grey23", [59, 59, 59]),
("grey24", [61, 61, 61]),
("grey25", [64, 64, 64]),
("grey26", [66, 66, 66]),
("grey27", [69, 69, 69]),
("grey28", [71, 71, 71]),
("grey29", [74, 74, 74]),
("grey3", [8, 8, 8]),
("grey30", [77, 77, 77]),
("grey31", [79, 79, 79]),
("grey32", [82, 82, 82]),
("grey33", [84, 84, 84]),
("grey34", [87, 87, 87]),
("grey35", [89, 89, 89]),
("grey36", [92, 92, 92]),
("grey37", [94, 94, 94]),
("grey38", [97, 97, 97]),
("grey39", [99, 99, 99]),
("grey4", [10, 10, 10]),
("grey40", [102, 102, 102]),
("grey41", [105, 105, 105]),
("grey42", [107, 107, 107]),
("grey43", [110, 110, 110]),
("grey44", [112, 112, 112]),
("grey45", [115, 115, 115]),
("grey46", [117, 117, 117]),
("grey47", [120, 120, 120]),
("grey48", [122, 122, 122]),
("grey49", [125, 125, 125]),
("grey5", [13, 13, 13]),
("grey50", [127, 127, 127]),
("grey51", [130, 130, 130]),
("grey52", [133, 133, 133]),
("grey53", [135, 135, 135]),
("grey54", [138, 138, 138]),
("grey55", [140, 140, 140]),
("grey56", [143, 143, 143]),
("grey57", [145, 145, 145]),
("grey58", [148, 148, 148]),
("grey59", [150, 150, 150]),
("grey6", [15, 15, 15]),
("grey60", [153, 153, 153]),
("grey61", [156, 156, 156]),
("grey62", [158, 158, 158]),
("grey63", [161, 161, 161]),
("grey64", [163, 163, 163]),
("grey65", [166, 166, 166]),
("grey66", [168, 168, 168]),
("grey67", [171, 171, 171]),
("grey68", [173, 173, 173]),
("grey69", [176, 176, 176]),
("grey7", [18, 18, 18]),
("grey70", [179, 179, 179]),
("grey71", [181, 181, 181]),
("grey72", [184, 184, 184]),
("grey73", [186, 186, 186]),
("grey74", [189, 189, 189]),
("grey75", [191, 191, 191]),
("grey76", [194, 194, 194]),
("grey77", [196, 196, 196]),
("grey78", [199, 199, 199]),
("grey79", [201, 201, 201]),
("grey8", [20, 20, 20]),
("grey80", [204, 204, 204]),
("grey81", [207, 207, 207]),
("grey82", [209, 209, 209]),
("grey83", [212, 212, 212]),
("grey84", [214, 214, 214]),
("grey85", [217, 217, 217]),
("grey86", [219, 219, 219]),
("grey87", [222, 222, 222]),
("grey88", [224, 224, 224]),
("grey89", [227, 227, 227]),
("grey9", [23, 23, 23]),
("grey90", [229, 229, 229]),
("grey91", [232, 232, 232]),
("grey92", [235, 235, 235]),
("grey93", [237, 237, 237]),
("grey94", [240, 240, 240]),
("grey95", [242, 242, 242]),
("grey96", [245, 245, 245]),
("grey97", [247, 247, 247]),
("grey98", [250, 250, 250]),
("grey99", [252, 252, 252]),
("honeydew", [240, 255, 240]),
("honeydew1", [240, 255, 240]),
("honeydew2", [224, 238, 224]),
("honeydew3", [193, 205, 193]),
("honeydew4", [131, 139, 131]),
("hotpink", [255, 105, 180]),
("hotpink1", [255, 110, 180]),
("hotpink2", [238, 106, 167]),
("hotpink3", [205, 96, 144]),
("hotpink4", [139, 58, 98]),
("indianred", [205, 92, 92]),
("indianred1", [255, 106, 106]),
("indianred2", [238, 99, 99]),
("indianred3", [205, 85, 85]),
("indianred4", [139, 58, 58]),
("ivory", [255, 255, 240]),
("ivory1", [255, 255, 240]),
("ivory2", [238, 238, 224]),
("ivory3", [205, 205, 193]),
("ivory4", [139, 139, 131]),
("khaki", [240, 230, 140]),
("khaki1", [255, 246, 143]),
("khaki2", [238, 230, 133]),
("khaki3", [205, 198, 115]),
("khaki4", [139, 134, 78]),
("lavender", [230, 230, 250]),
("lavenderblush", [255, 240, 245]),
("lavenderblush1", [255, 240, 245]),
("lavenderblush2", [238, 224, 229]),
("lavenderblush3", [205, 193, 197]),
("lavenderblush4", [139, 131, 134]),
("lawngreen", [124, 252, 0]),
("lemonchiffon", [255, 250, 205]),
("lemonchiffon1", [255, 250, 205]),
("lemonchiffon2", [238, 233, 191]),
("lemonchiffon3", [205, 201, 165]),
("lemonchiffon4", [139, 137, 112]),
("lightblue", [173, 216, 230]),
("lightblue1", [191, 239, 255]),
("lightblue2", [178, 223, 238]),
("lightblue3", [154, 192, 205]),
("lightblue4", [104, 131, 139]),
("lightcoral", [240, 128, 128]),
("lightcyan", [224, 255, 255]),
("lightcyan1", [224, 255, 255]),
("lightcyan2", [209, 238, 238]),
("lightcyan3", [180, 205, 205]),
("lightcyan4", [122, 139, 139]),
("lightgoldenrod", [238, 221, 130]),
("lightgoldenrod1", [255, 236, 139]),
("lightgoldenrod2", [238, 220, 130]),
("lightgoldenrod3", [205, 190, 112]),
("lightgoldenrod4", [139, 129, 76]),
("lightgoldenrodyellow", [250, 250, 210]),
("lightgray", [211, 211, 211]),
("lightgreen", [144, 238, 144]),
("lightgrey", [211, 211, 211]),
("lightpink", [255, 182, 193]),
("lightpink1", [255, 174, 185]),
("lightpink2", [238, 162, 173]),
("lightpink3", [205, 140, 149]),
("lightpink4", [139, 95, 101]),
("lightsalmon", [255, 160, 122]),
("lightsalmon1", [255, 160, 122]),
("lightsalmon2", [238, 149, 114]),
("lightsalmon3", [205, 129, 98]),
("lightsalmon4", [139, 87, 66]),
("lightseagreen", [32, 178, 170]),
("lightskyblue", [135, 206, 250]),
("lightskyblue1", [176, 226, 255]),
("lightskyblue2", [164, 211, 238]),
("lightskyblue3", [141, 182, 205]),
("lightskyblue4", [96, 123, 139]),
("lightslateblue", [132, 112, 255]),
("lightslategray", [119, 136, 153]),
("lightslategrey", [119, 136, 153]),
("lightsteelblue", [176, 196, 222]),
("lightsteelblue1", [202, 225, 255]),
("lightsteelblue2", [188, 210, 238]),
("lightsteelblue3", [162, 181, 205]),
("lightsteelblue4", [110, 123, 139]),
("lightyellow", [255, 255, 224]),
("lightyellow1", [255, 255, 224]),
("lightyellow2", [238, 238, 209]),
("lightyellow3", [205, 205, 180]),
("lightyellow4", [139, 139, 122]),
("limegreen", [50, 205, 50]),
("linen", [250, 240, 230]),
("magenta", [255, 0, 255]),
("magenta1", [255, 0, 255]),
("magenta2", [238, 0, 238]),
("magenta3", [205, 0, 205]),
("magenta4", [139, 0, 139]),
("maroon", [176, 48, 96]),
("maroon1", [255, 52, 179]),
("maroon2", [238, 48, 167]),
("maroon3", [205, 41, 144]),
("maroon4", [139, 28, 98]),
("mediumaquamarine", [102, 205, 170]),
("mediumblue", [0, 0, 205]),
("mediumorchid", [186, 85, 211]),
("mediumorchid1", [224, 102, 255]),
("mediumorchid2", [209, 95, 238]),
("mediumorchid3", [180, 82, 205]),
("mediumorchid4", [122, 55, 139]),
("mediumpurple", [147, 112, 219]),
("mediumpurple1", [171, 130, 255]),
("mediumpurple2", [159, 121, 238]),
("mediumpurple3", [137, 104, 205]),
("mediumpurple4", [93, 71, 139]),
("mediumseagreen", [60, 179, 113]),
("mediumslateblue", [123, 104, 238]),
("mediumspringgreen", [0, 250, 154]),
("mediumturquoise", [72, 209, 204]),
("mediumvioletred", [199, 21, 133]),
("midnightblue", [25, 25, 112]),
("mintcream", [245, 255, 250]),
("mistyrose", [255, 228, 225]),
("mistyrose1", [255, 228, 225]),
("mistyrose2", [238, 213, 210]),
("mistyrose3", [205, 183, 181]),
("mistyrose4", [139, 125, 123]),
("moccasin", [255, 228, 181]),
("navajowhite", [255, 222, 173]),
("navajowhite1", [255, 222, 173]),
("navajowhite2", [238, 207, 161]),
("navajowhite3", [205, 179, 139]),
("navajowhite4", [139, 121, 94]),
("navy", [0, 0, 128]),
("navyblue", [0, 0, 128]),
("oldlace", [253, 245, 230]),
("olivedrab", [107, 142, 35]),
("olivedrab1", [192, 255, 62]),
("olivedrab2", [179, 238, 58]),
("olivedrab3", [154, 205, 50]),
("olivedrab4", [105, 139, 34]),
("orange", [255, 165, 0]),
("orange1", [255, 165, 0]),
("orange2", [238, 154, 0]),
("orange3", [205, 133, 0]),
("orange4", [139, 90, 0]),
("orangered", [255, 69, 0]),
("orangered1", [255, 69, 0]),
("orangered2", [238, 64, 0]),
("orangered3", [205, 55, 0]),
("orangered4", [139, 37, 0]),
("orchid", [218, 112, 214]),
("orchid1", [255, 131, 250]),
("orchid2", [238, 122, 233]),
("orchid3", [205, 105, 201]),
("orchid4", [139, 71, 137]),
("palegoldenrod", [238, 232, 170]),
("palegreen", [152, 251, 152]),
("palegreen1", [154, 255, 154]),
("palegreen2", [144, 238, 144]),
("palegreen3", [124, 205, 124]),
("palegreen4", [84, 139, 84]),
("paleturquoise", [175, 238, 238]),
("paleturquoise1", [187, 255, 255]),
("paleturquoise2", [174, 238, 238]),
("paleturquoise3", [150, 205, 205]),
("paleturquoise4", [102, 139, 139]),
("palevioletred", [219, 112, 147]),
("palevioletred1", [255, 130, 171]),
("palevioletred2", [238, 121, 159]),
("palevioletred3", [205, 104, 137]),
("palevioletred4", [139, 71, 93]),
("papayawhip", [255, 239, 213]),
("peachpuff", [255, 218, 185]),
("peachpuff1", [255, 218, 185]),
("peachpuff2", [238, 203, 173]),
("peachpuff3", [205, 175, 149]),
("peachpuff4", [139, 119, 101]),
("peru", [205, 133, 63]),
("pink", [255, 192, 203]),
("pink1", [255, 181, 197]),
("pink2", [238, 169, 184]),
("pink3", [205, 145, 158]),
("pink4", [139, 99, 108]),
("plum", [221, 160, 221]),
("plum1", [255, 187, 255]),
("plum2", [238, 174, 238]),
("plum3", [205, 150, 205]),
("plum4", [139, 102, 139]),
("powderblue", [176, 224, 230]),
("purple", [160, 32, 240]),
("purple1", [155, 48, 255]),
("purple2", [145, 44, 238]),
("purple3", [125, 38, 205]),
("purple4", [85, 26, 139]),
("red", [255, 0, 0]),
("red1", [255, 0, 0]),
("red2", [238, 0, 0]),
("red3", [205, 0, 0]),
("red4", [139, 0, 0]),
("rosybrown", [188, 143, 143]),
("rosybrown1", [255, 193, 193]),
("rosybrown2", [238, 180, 180]),
("rosybrown3", [205, 155, 155]),
("rosybrown4", [139, 105, 105]),
("royalblue", [65, 105, 225]),
("royalblue1", [72, 118, 255]),
("royalblue2", [67, 110, 238]),
("royalblue3", [58, 95, 205]),
("royalblue4", [39, 64, 139]),
("saddlebrown", [139, 69, 19]),
("salmon", [250, 128, 114]),
("salmon1", [255, 140, 105]),
("salmon2", [238, 130, 98]),
("salmon3", [205, 112, 84]),
("salmon4", [139, 76, 57]),
("sandybrown", [244, 164, 96]),
("seagreen", [46, 139, 87]),
("seagreen1", [84, 255, 159]),
("seagreen2", [78, 238, 148]),
("seagreen3", [67, 205, 128]),
("seagreen4", [46, 139, 87]),
("seashell", [255, 245, 238]),
("seashell1", [255, 245, 238]),
("seashell2", [238, 229, 222]),
("seashell3", [205, 197, 191]),
("seashell4", [139, 134, 130]),
("sienna", [160, 82, 45]),
("sienna1", [255, 130, 71]),
("sienna2", [238, 121, 66]),
("sienna3", [205, 104, 57]),
("sienna4", [139, 71, 38]),
("skyblue", [135, 206, 235]),
("skyblue1", [135, 206, 255]),
("skyblue2", [126, 192, 238]),
("skyblue3", [108, 166, 205]),
("skyblue4", [74, 112, 139]),
("slateblue", [106, 90, 205]),
("slateblue1", [131, 111, 255]),
("slateblue2", [122, 103, 238]),
("slateblue3", [105, 89, 205]),
("slateblue4", [71, 60, 139]),
("slategray", [112, 128, 144]),
("slategray1", [198, 226, 255]),
("slategray2", [185, 211, 238]),
("slategray3", [159, 182, 205]),
("slategray4", [108, 123, 139]),
("slategrey", [112, 128, 144]),
("snow", [255, 250, 250]),
("snow1", [255, 250, 250]),
("snow2", [238, 233, 233]),
("snow3", [205, 201, 201]),
("snow4", [139, 137, 137]),
("springgreen", [0, 255, 127]),
("springgreen1", [0, 255, 127]),
("springgreen2", [0, 238, 118]),
("springgreen3", [0, 205, 102]),
("springgreen4", [0, 139, 69]),
("steelblue", [70, 130, 180]),
("steelblue1", [99, 184, 255]),
("steelblue2", [92, 172, 238]),
("steelblue3", [79, 148, 205]),
("steelblue4", [54, 100, 139]),
("tan", [210, 180, 140]),
("tan1", [255, 165, 79]),
("tan2", [238, 154, 73]),
("tan3", [205, 133, 63]),
("tan4", [139, 90, 43]),
("thistle", [216, 191, 216]),
("thistle1", [255, 225, 255]),
("thistle2", [238, 210, 238]),
("thistle3", [205, 181, 205]),
("thistle4", [139, 123, 139]),
("tomato", [255, 99, 71]),
("tomato1", [255, 99, 71]),
("tomato2", [238, 92, 66]),
("tomato3", [205, 79, 57]),
("tomato4", [139, 54, 38]),
("turquoise", [64, 224, 208]),
("turquoise1", [0, 245, 255]),
("turquoise2", [0, 229, 238]),
("turquoise3", [0, 197, 205]),
("turquoise4", [0, 134, 139]),
("violet", [238, 130, 238]),
("violetred", [208, 32, 144]),
("violetred1", [255, 62, 150]),
("violetred2", [238, 58, 140]),
("violetred3", [205, 50, 120]),
("violetred4", [139, 34, 82]),
("wheat", [245, 222, 179]),
("wheat1", [255, 231, 186]),
("wheat2", [238, 216, 174]),
("wheat3", [205, 186, 150]),
("wheat4", [139, 126, 102]),
("white", [255, 255, 255]),
("whitesmoke", [245, 245, 245]),
("yellow", [255, 255, 0]),
("yellow1", [255, 255, 0]),
("yellow2", [238, 238, 0]),
("yellow3", [205, 205, 0]),
("yellow4", [139, 139, 0]),
("yellowgreen", [154, 205, 50]),
];
@@ -0,0 +1,46 @@
//! The compatibility facade must retain its policy while sharing the codec implementation.
use craft_raster_codecs::{ChannelLayout, CodecError, Image, Limits, SampleType, dds, fits, iff, pnm, xpm};
#[test]
fn facade_refuses_conversions_the_generic_encoder_can_plan() {
for layout in [ChannelLayout::GrayA, ChannelLayout::Rgba, ChannelLayout::Cmyk, ChannelLayout::CmykA] {
let image = Image::from_f32(1, 1, layout, &vec![0.5; layout.channels()]).unwrap();
assert!(matches!(pnm::encode(&image), Err(CodecError::Encode { .. })));
assert!(matches!(fits::encode(&image), Err(CodecError::Encode { .. })));
}
for layout in [ChannelLayout::Gray, ChannelLayout::GrayA, ChannelLayout::Rgb, ChannelLayout::Cmyk, ChannelLayout::CmykA] {
let image = Image::from_u8(1, 1, layout, vec![127; layout.channels()]).unwrap();
for compression in [dds::DdsCompression::Bc1, dds::DdsCompression::Bc2, dds::DdsCompression::Bc3] {
assert!(matches!(dds::encode(&image, dds::DdsOptions { compression, mipmaps: false }), Err(CodecError::Encode { .. })));
}
}
for layout in [ChannelLayout::Rgb, ChannelLayout::Rgba] {
let image = Image::from_u16(1, 1, layout, &vec![32768; layout.channels()]).unwrap();
assert!(matches!(iff::encode(&image), Err(CodecError::Encode { .. })));
assert!(matches!(dds::encode(&image, dds::DdsOptions::default()), Err(CodecError::Encode { .. })));
}
}
#[test]
fn fits_facade_keeps_metadata_samples_and_explicit_limits() {
let mut image = Image::from_u16(2, 1, ChannelLayout::Gray, &[0, 65535]).unwrap();
image.text.push(("OBJECT".into(), "shared codec".into()));
let bytes = fits::encode(&image).unwrap();
let decoded = fits::decode(&bytes, &Limits::default()).unwrap();
assert_eq!(decoded.sample_type(), SampleType::U16);
assert_eq!(decoded.data(), image.data());
assert!(decoded.text.contains(&("OBJECT".into(), "shared codec".into())));
for limits in
[Limits { max_width: 1, ..Limits::default() }, Limits { max_pixels: 1, ..Limits::default() }, Limits { max_alloc: 3, ..Limits::default() }]
{
assert!(matches!(fits::decode(&bytes, &limits), Err(CodecError::LimitExceeded(_))));
}
}
#[test]
fn x11_table_lookup_does_not_adopt_xpm_aliases_or_normalization() {
assert_eq!(xpm::x11_color_rgb("red"), Some([1.0, 0.0, 0.0]));
for name in ["Red", "light blue", "light-blue", "light_blue", "none", "transparent", ""] {
assert_eq!(xpm::x11_color_rgb(name), None, "{name}");
}
}
+5
View File
@@ -52,6 +52,8 @@ vp9-encode = ["craft-media/isobmff"]
av1 = ["av1-decode", "av1-encode"]
av1-decode = []
av1-encode = ["craft-media/isobmff"]
# Tiled AV1 fallback for frames that exceed the clean-room encoder's single-tile limits.
av1-large-encode = ["av1-encode", "dep:rav1e"]
# Decode and encode across worker threads (rayon) in the codecs that support it.
threads = ["dep:rayon"]
@@ -60,6 +62,9 @@ craft-media = { workspace = true }
thiserror = { workspace = true }
rayon = { workspace = true, optional = true }
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
rav1e = { version = "0.8", default-features = false, optional = true }
[dev-dependencies]
craft-media-testkit = { workspace = true }
# The AVI muxer, for the MPEG-4 Part 2 encoder's end-to-end test.
+2 -2
View File
@@ -21,11 +21,11 @@ No codec feature is on by default.
| `dnx` | [`dnx`](src/dnx/README.md) | Avid DNxHD / DNxHR (SMPTE ST 2019-1 VC-3): decoder and encoder |
| `apv` | [`apv`](src/apv/README.md) | APV (Advanced Professional Video, RFC 9924): decoder (`apv-decode` alone) and encoder (`apv-encode` alone) |
| `vp8` | `vp8` | VP8 (RFC 6386): decoder |
| `mpeg2` | [`mpeg2`](src/mpeg2/README.md) | MPEG-2 video (ITU-T H.262) and MPEG-1 video (ISO/IEC 11172-2): decoder (`mpeg2-decode` alone); MPEG-2 encoder with I and P pictures (`mpeg2-encode`, which also turns on the decoder) |
| `mpeg2` | [`mpeg2`](src/mpeg2/README.md) | MPEG-2 video (ITU-T H.262) and MPEG-1 video (ISO/IEC 11172-2): decoder (`mpeg2-decode` alone); MPEG-2 encoder with I, P and B pictures (`mpeg2-encode`, which also turns on the decoder) |
| `mpeg4` | [`mpeg4`](src/mpeg4/README.md) | MPEG-4 Part 2 video (ISO/IEC 14496-2, the Xvid/DivX format): Simple profile encoder (`mpeg4-encode`) |
| `prores` | `prores` | Apple ProRes (SMPTE RDD 36): decoder and encoder |
| `h264` | [`h264`](src/h264/decode/README.md) | ITU-T H.264 / AVC: decoder (`h264-decode` alone) and encoder (`h264-encode` alone) |
| `hevc` | [`hevc`](src/hevc/decode/README.md) | ITU-T H.265 / HEVC: decoder (`hevc-decode` alone) and encoder (`hevc-encode` alone) |
| `vp9` | [`vp9`](src/vp9/decode/README.md) | VP9: decoder (`vp9-decode` alone) and encoder (`vp9-encode` alone) |
| `av1` | [`av1`](src/av1/decode/README.md) | AV1 (AOMedia Video 1): decoder (`av1-decode` alone) and encoder (`av1-encode` alone) |
| `av1` | [`av1`](src/av1/decode/README.md) | AV1 (AOMedia Video 1): decoder (`av1-decode` alone) and clean-room encoder (`av1-encode`); tiled rav1e fallback for large frames (`av1-large-encode`) |
| `threads` | — | Multi-threaded slice/row parallelism via `rayon` |
+9
View File
@@ -3,6 +3,15 @@
Clean-room, pure-Rust AV1 encoder for MP4 / WebM export (layer L0, `std` only,
no `unsafe`, builds for `wasm32-unknown-unknown`).
## Large frame fallback
The optional `av1-large-encode` feature exposes `LargeEncoder`, a tiled rav1e-backed encoder for
8-bit 4:2:0 frames up to 8192 samples per side. Use it when the clean-room `Encoder`'s one-tile
limits (4096 samples per side and 2304 superblocks) would reject the frame. It supports constant
quantizer rate control and emits one low-latency packet per input frame. The fallback is native
only; the clean-room encoder remains available without the feature and supports 8- and 10-bit
input.
## What is implemented
- **Stream**: Main profile (`seq_profile` 0), 4:2:0, 8 or 10 bit, the configured colour description (BT.709 by default),
+155
View File
@@ -0,0 +1,155 @@
//! Tiled AV1 encoding for frames outside the clean-room encoder's single-tile limits.
use super::{EncoderConfig, Error, Frame, Packet, RateControl};
use rav1e::prelude::{
ChromaSampling, ColorDescription, ColorPrimaries, Config, Context, EncoderConfig as Rav1eConfig, FrameParameters, FrameType, FrameTypeOverride,
MatrixCoefficients, PixelRange, Rational, TransferCharacteristics,
};
/// Tiled AV1 encoder used when a frame is too large for [`super::Encoder`].
pub struct LargeEncoder {
ctx: Context<u8>,
width: usize,
height: usize,
seq_header: Option<Vec<u8>>,
}
impl LargeEncoder {
/// Creates a tiled 8-bit 4:2:0 encoder for dimensions up to 8192 samples per side.
pub fn new(cfg: &EncoderConfig) -> Result<Self, Error> {
Self::with_speed(cfg, 6)
}
/// Creates the tiled encoder with a rav1e speed preset from 1 (slower) to 10 (faster).
pub fn with_speed(cfg: &EncoderConfig, speed: u8) -> Result<Self, Error> {
if cfg.width < 16 || cfg.height < 16 || cfg.width > 8192 || cfg.height > 8192 {
return Err(Error::InvalidConfig("large AV1 frame dimensions must be 16..=8192".into()));
}
if cfg.bit_depth != 8 || cfg.fps_num == 0 || cfg.fps_den == 0 {
return Err(Error::InvalidConfig("large AV1 encoding requires 8-bit input and a valid frame rate".into()));
}
let RateControl::ConstantQ(quality) = cfg.rate else {
return Err(Error::InvalidConfig("large AV1 encoding currently supports constant quantizer rate control".into()));
};
let mut ec = Rav1eConfig::with_speed_preset(speed.clamp(1, 10));
ec.width = cfg.width as usize;
ec.height = cfg.height as usize;
ec.time_base = Rational::new(u64::from(cfg.fps_den), u64::from(cfg.fps_num));
ec.bit_depth = 8;
ec.chroma_sampling = ChromaSampling::Cs420;
ec.pixel_range = if cfg.full_range { PixelRange::Full } else { PixelRange::Limited };
ec.color_description = Some(ColorDescription {
color_primaries: ColorPrimaries::BT709,
transfer_characteristics: TransferCharacteristics::BT709,
matrix_coefficients: MatrixCoefficients::BT709,
});
ec.low_latency = true;
ec.quantizer = quality.max(1) as usize;
ec.min_quantizer = ec.quantizer.min(255) as u8;
ec.min_key_frame_interval = 1;
ec.max_key_frame_interval = cfg.keyint.clamp(1, 120) as u64;
ec.tiles = std::thread::available_parallelism().map_or(4, |n| n.get()).clamp(2, 16);
let ctx = Config::new().with_encoder_config(ec).new_context().map_err(|e| Error::InvalidConfig(format!("rav1e: {e}")))?;
Ok(Self { ctx, width: cfg.width as usize, height: cfg.height as usize, seq_header: None })
}
/// Encodes one frame. The frame planes must match the configured 4:2:0 dimensions.
pub fn encode_with_key(&mut self, frame: &Frame<'_>, force_key: bool) -> Result<Packet, Error> {
if frame.y_stride < self.width
|| frame.uv_stride < self.width / 2
|| frame.y.len() < frame.y_stride.saturating_mul(self.height)
|| frame.u.len() < frame.uv_stride.saturating_mul(self.height / 2)
|| frame.v.len() < frame.uv_stride.saturating_mul(self.height / 2)
{
return Err(Error::InvalidFrame("plane dimensions or strides do not match the configured frame".into()));
}
let mut input = self.ctx.new_frame();
copy_plane(&mut input.planes[0], frame.y, frame.y_stride, self.width, self.height)?;
copy_plane(&mut input.planes[1], frame.u, frame.uv_stride, self.width / 2, self.height / 2)?;
copy_plane(&mut input.planes[2], frame.v, frame.uv_stride, self.width / 2, self.height / 2)?;
let params =
FrameParameters { frame_type_override: if force_key { FrameTypeOverride::Key } else { FrameTypeOverride::No }, ..Default::default() };
self.ctx.send_frame((input, params)).map_err(|e| Error::InvalidFrame(format!("rav1e: {e}")))?;
loop {
match self.ctx.receive_packet() {
Ok(packet) => {
let (data, seq) = sample_data(&packet.data)?;
if self.seq_header.is_none() {
self.seq_header = seq;
}
return Ok(Packet { data, keyframe: packet.frame_type == FrameType::KEY });
}
Err(rav1e::prelude::EncoderStatus::Encoded) => continue,
Err(rav1e::prelude::EncoderStatus::NeedMoreData | rav1e::prelude::EncoderStatus::LimitReached) => {
return Err(Error::InvalidFrame("rav1e did not emit a low-latency frame".into()));
}
Err(e) => return Err(Error::InvalidFrame(format!("rav1e: {e}"))),
}
}
}
/// Returns the AV1 configuration record after the first frame has been encoded.
pub fn av1c(&self) -> Option<Vec<u8>> {
self.seq_header.as_ref().map(|obu| {
let mut config = vec![0x81, 31, 0x0c, 0];
config.extend_from_slice(obu);
config
})
}
}
fn copy_plane(plane: &mut rav1e::prelude::Plane<u8>, source: &[u16], stride: usize, width: usize, height: usize) -> Result<(), Error> {
let mut packed = Vec::with_capacity(width * height);
for row in 0..height {
let start = row * stride;
let pixels = &source[start..start + width];
if pixels.iter().any(|&value| value > u8::MAX as u16) {
return Err(Error::InvalidFrame("8-bit AV1 samples must be in 0..=255".into()));
}
packed.extend(pixels.iter().map(|&value| value as u8));
}
plane.copy_from_raw_u8(&packed, width, 1);
Ok(())
}
fn sample_data(data: &[u8]) -> Result<(Vec<u8>, Option<Vec<u8>>), Error> {
let mut pos = 0usize;
let mut sample = Vec::with_capacity(data.len());
let mut sequence = None;
while pos < data.len() {
let start = pos;
let header = data[pos];
if header & 0x80 != 0 {
return Err(Error::InvalidFrame("rav1e emitted an invalid OBU".into()));
}
let kind = (header >> 3) & 0x0f;
pos += 1 + usize::from(header & 0x04 != 0);
let end = if header & 0x02 != 0 {
let mut size = 0usize;
let mut shift = 0usize;
loop {
let byte = *data.get(pos).ok_or_else(|| Error::InvalidFrame("truncated OBU size".into()))?;
pos += 1;
size |= usize::from(byte & 0x7f).checked_shl(shift as u32).ok_or_else(|| Error::InvalidFrame("OBU size overflow".into()))?;
if byte & 0x80 == 0 {
break;
}
shift += 7;
if shift >= usize::BITS as usize {
return Err(Error::InvalidFrame("OBU size overflow".into()));
}
}
pos.checked_add(size).filter(|end| *end <= data.len()).ok_or_else(|| Error::InvalidFrame("OBU exceeds packet bounds".into()))?
} else {
data.len()
};
if kind == 1 && sequence.is_none() {
sequence = Some(data[start..end].to_vec());
}
if kind != 2 && kind != 15 {
sample.extend_from_slice(&data[start..end]);
}
pos = end;
}
Ok((sample, sequence))
}
+5
View File
@@ -20,6 +20,11 @@ mod tables;
mod transform;
mod writer;
#[cfg(all(feature = "av1-large-encode", not(target_arch = "wasm32")))]
mod large;
#[cfg(all(feature = "av1-large-encode", not(target_arch = "wasm32")))]
pub use large::LargeEncoder;
use bitw::obu;
use craft_media::bitstream::BitWriter;
use craft_media::isobmff::Av1Config;
+1 -1
View File
@@ -8,7 +8,7 @@
//! | `dnx` | [`dnx`] | Avid DNxHD / DNxHR (SMPTE ST 2019-1): decoder and encoder |
//! | `apv` | [`apv`] | APV (RFC 9924): decoder (`apv-decode`) and encoder (`apv-encode`) |
//! | `vp8` | [`vp8`] | VP8 (RFC 6386): decoder (`vp8-decode`) and key-frame encoder (`vp8-encode`) |
//! | `mpeg2` | [`mpeg2`] | MPEG-2 video (ITU-T H.262) and MPEG-1 video: decoder (`mpeg2-decode`) and MPEG-2 I/P encoder (`mpeg2-encode`) |
//! | `mpeg2` | [`mpeg2`] | MPEG-2 video (ITU-T H.262) and MPEG-1 video: decoder (`mpeg2-decode`) and MPEG-2 I/P/B encoder (`mpeg2-encode`) |
//! | `mpeg4` | [`mpeg4`] | MPEG-4 Part 2 video (ISO/IEC 14496-2, Xvid/DivX): Simple profile encoder (`mpeg4-encode`) |
//! | `prores` | [`prores`] | Apple ProRes (SMPTE RDD 36): decoder and encoder |
//! | `h264` | [`h264`] | ITU-T H.264 / AVC: decoder (`h264-decode`) and encoder (`h264-encode`) |
+40 -18
View File
@@ -1,7 +1,7 @@
# MPEG-2 and MPEG-1 video decoder, MPEG-2 encoder (`craft_video::mpeg2`, features `mpeg2-decode`, `mpeg2-encode`)
Clean-room MPEG-2 video and MPEG-1 video decoder, and the first step of an MPEG-2 video encoder
(I and P pictures, see "Encoder"), in pure Rust. Depends only on
Clean-room MPEG-2 video and MPEG-1 video decoder, and the first steps of an MPEG-2 video encoder
(I, P and B pictures, see "Encoder"), in pure Rust. Depends only on
`thiserror` and (optional, feature `threads`) `rayon`. Builds for
`wasm32-unknown-unknown`; no `unsafe`. No GPL/LGPL code (FFmpeg, libmpeg2, libavcodec) was
consulted; FFmpeg is used only as an external fixture generator and test oracle.
@@ -77,8 +77,8 @@ the synthetic-stream tests confirmed against FFmpeg:
## Encoder (feature `mpeg2-encode`)
The encoder is the first step of MPEG-2 encoding in this crate, tracked in
storytold/craft-libs#1133. It writes valid MPEG-2 elementary streams, but not yet DVD or
The encoder is built in steps, tracked in storytold/craft-libs#1133: I and P pictures came in
#1136, B pictures in the second step. It writes valid MPEG-2 elementary streams, but not yet DVD or
broadcast deliverables: those need the later steps listed below.
```rust
@@ -86,13 +86,15 @@ use craft_video::mpeg2::{Encoder, EncoderConfig, RateControl, YuvFrame};
let mut cfg = EncoderConfig::new(720, 576, 25, 1);
cfg.rate = RateControl::Abr { kbps: 6000 }; // or RateControl::Quantiser(1..=31)
cfg.gop_size = 12; // one I picture, then P pictures
cfg.gop_size = 12; // pictures from one I picture to the next
cfg.b_pictures = 2; // I B B P B B P ...; 0 for I and P only
cfg.closed_gop = true; // or open GOPs
let mut enc = Encoder::new(cfg)?;
for (i, f) in frames.iter().enumerate() {
let frame = YuvFrame { y: &f.y, cb: &f.cb, cr: &f.cr, y_stride: 720, c_stride: 360 };
for p in enc.encode(&frame, i as i64)? { /* p.data, p.pts, p.dts, p.keyframe, p.picture_type */ }
}
for p in enc.flush() { /* none yet: no B pictures */ }
for p in enc.flush() { /* the pictures held for reordering */ }
es.extend_from_slice(enc.end_of_sequence());
```
@@ -101,9 +103,18 @@ What it does:
- Main Profile (4:2:0) at Low, Main, High-1440 and High Level, and 4:2:2 Profile at Main and
High Level. The lowest level that holds the size, frame rate and (average) bitrate is chosen;
sizes beyond High Level are refused. Any even picture size; edges are padded by repetition.
- Progressive frame pictures, I and P, in closed GOPs. Every GOP starts with a sequence header,
sequence extension and GOP header (with a time code), so every I picture is a random access
point. Packets come out in decoding order, which equals display order without B pictures.
- Progressive frame pictures, I, P and B. Every GOP starts with a sequence header, sequence
extension and GOP header (with a time code), so every I picture is a random access point.
- B pictures (0-4 between anchors) and reordering: pictures go in in display order and packets
come out in decoding order; a B picture is held until the anchor after it is coded, and
`flush` codes the last held picture as a P picture. With B pictures, `dts` is the presentation
times in decoding order one picture interval earlier, so presentation times must step evenly.
A single picture flushed before a second one gets `dts = pts - 1`. With average bitrate, a
GOP that `flush` cuts short gives back the budget of the pictures it did not get.
`low_delay` is set only without B pictures.
- GOPs are closed or open. The B pictures shown before a GOP's I picture (coded after it) predict
backward only in a closed GOP, and from the previous GOP's last anchor too in an open one.
temporal_reference counts display order from the GOP's first picture.
- Forward DCT on the transpose of the decoder's IDCT basis; intra quantisation with a small
dead zone, non-intra quantisation by truncation; default or custom quantiser matrices
(sequence header); linear or non-linear quantiser scale; intra DC precision 8-10 bits;
@@ -112,9 +123,14 @@ What it does:
predictor, the previous picture's vectors), then half-sample refinement; cost SAD + λ·bits.
Each macroblock is coded intra, motion-compensated with or without residual, "no MC" with
residual, or skipped. The search range sets f_code (1-4).
- B pictures: a search per direction (candidates include the P picture's vectors scaled to the
B picture's distance), then forward, backward, interpolated or the skip prediction (the
previous macroblock's directions with the predictors), whichever costs least, or intra.
Interpolated predictions are averaged in the decoder's order.
- Adaptive quantisation by macroblock activity (Test Model 5 §5.2.3).
- Rate control: a constant quantiser, or single-pass average bitrate with Test Model 5's
target bit allocation at picture level. Streams are signalled as variable bitrate
- Rate control: a constant quantiser (B pictures at 1.25 times it), or single-pass average
bitrate with Test Model 5's target bit allocation at picture level (B pictures weighted by
K_b = 1.4). Streams are signalled as variable bitrate
(`vbv_delay` 0xFFFF, the level's maximum bitrate and VBV size in the sequence header); the VBV
buffer is not modelled.
- The reconstruction uses the decoder's own dequantisation, mismatch control, IDCT and motion
@@ -122,7 +138,7 @@ What it does:
- Slices (one per macroblock row) are coded in parallel on rayon with `threads`; the stream is
identical either way.
Later steps (#1133): B pictures and reordering; CBR and VBR with a VBV guarantee; DVD presets
Later steps (#1133): CBR and VBR with a VBV guarantee; DVD presets
(sizes, aspect, GOP length, 9.8 Mb/s, 23.976 soft telecine); interlaced coding (field/frame DCT,
field prediction, alternate scan) and 4:2:2 High Level CBR for XDCAM HD422. MPEG-2 essence in the
MXF writer and a program stream muxer belong to `craft-media`.
@@ -191,9 +207,15 @@ fell to 77–150 fps). These are lower bounds.
rate control converges on its target. `encode/tests.rs`: our decoder outputs exactly the
encoder's reconstruction (intra only, a 30-picture P GOP, 4:2:2, linear and non-linear
quantisers, quantisers 1 and 31, DC precision 8 and 10, custom matrices, odd macroblock counts,
average bitrate); quality and size follow the quantiser; repeated pictures skip; levels and
aspect in the sequence header; bad configurations and short or inconsistent planes are refused.
- `tests/mpeg2/encode.rs`: FFmpeg decodes our streams of `testsrc2` (CIF and 576-line 4:2:2)
without errors and within the decoder suite's tolerance of our reconstruction, ffprobe reports
the profile, level, pixel format and I/P picture types, and average bitrate lands within 10 % of
800 and 2500 kbit/s targets.
average bitrate, each with and without B pictures; 1-4 B pictures with closed and open GOPs,
GOP lengths that are and are not multiples of the anchor distance, and streams that end inside
a group of B pictures); decoding order, decoding times and temporal_reference; a closed GOP
decodes from its I picture with its leading B pictures and an open one without them; B pictures
are smaller than P pictures; uneven presentation times are refused with B pictures; quality and
size follow the quantiser; repeated pictures skip; levels and aspect in the sequence header;
bad configurations and short or inconsistent planes are refused.
- `tests/mpeg2/encode.rs`: FFmpeg decodes our streams of `testsrc2` (CIF and 576-line 4:2:2;
without B pictures, with 2 and 4, closed and open GOPs) without errors and within the decoder
suite's tolerance of our reconstruction, ffprobe reports the profile, level, pixel format and
picture types in display order, and average bitrate lands within 10 % of 800 and 2500 kbit/s
targets.
+272 -54
View File
@@ -1,9 +1,9 @@
//! MPEG-2 video encoder (ITU-T H.262 | ISO/IEC 13818-2), feature `mpeg2-encode`.
//!
//! This is the first step of MPEG-2 encoding in this crate (storytold/craft-libs#1133): I and P
//! pictures, progressive frame pictures, 4:2:0 (Main Profile) and 4:2:2 (4:2:2 Profile), closed
//! GOPs, constant quantiser or single-pass average bitrate. B pictures, a VBV guarantee,
//! interlaced coding and DVD / broadcast presets come later.
//! MPEG-2 encoding in this crate is built in steps (storytold/craft-libs#1133). So far: I, P and B
//! pictures, progressive frame pictures, 4:2:0 (Main Profile) and 4:2:2 (4:2:2 Profile), closed or
//! open GOPs, constant quantiser or single-pass average bitrate. A VBV guarantee, interlaced
//! coding and DVD / broadcast presets come later.
//!
//! ```no_run
//! use craft_video::mpeg2::encode::{Encoder, EncoderConfig, RateControl, YuvFrame};
@@ -36,6 +36,8 @@ mod transform;
#[cfg(test)]
mod tests;
use std::collections::VecDeque;
use crate::mpeg2::ChromaFormat;
use crate::mpeg2::headers::{DEFAULT_INTRA, PictureType, SCAN};
use crate::mpeg2::mc::Frame;
@@ -50,6 +52,10 @@ pub enum EncodeError {
Config(String),
#[error("bad input frame: {0}")]
BadFrame(String),
/// With B pictures, presentation times must increase by a constant step (the decoding times
/// are the presentation times one step earlier).
#[error("bad presentation time: {0}")]
BadTimestamp(String),
}
/// aspect_ratio_information (H.262 Table 6-3).
@@ -97,8 +103,15 @@ pub struct EncoderConfig {
/// 4:2:0 (Main Profile) or 4:2:2 (4:2:2 Profile).
pub chroma: ChromaFormat,
pub aspect: AspectRatio,
/// Pictures per GOP: one I picture, then P pictures. 1 codes every picture as I. 1..=1023.
/// Pictures from one I picture to the next (display order). 1 codes every picture as I.
/// 1..=1023, and at most 1024 with `b_pictures` added.
pub gop_size: u32,
/// B pictures between two anchor (I or P) pictures, 0..=4. 0 gives I and P pictures only and a
/// low-delay stream (no reordering).
pub b_pictures: u32,
/// Closed GOPs: the B pictures shown before a GOP's I picture predict from it alone, so the
/// GOP decodes on its own. Open GOPs let them predict from the previous GOP too.
pub closed_gop: bool,
pub rate: RateControl,
/// q_scale_type: the non-linear quantiser scale (finer steps at low quantisers).
pub nonlinear_quant: bool,
@@ -125,6 +138,8 @@ impl EncoderConfig {
chroma: ChromaFormat::Yuv420,
aspect: AspectRatio::Square,
gop_size: 12,
b_pictures: 2,
closed_gop: true,
rate: RateControl::Quantiser(4),
nonlinear_quant: true,
adaptive_quant: true,
@@ -155,9 +170,12 @@ pub struct Packet {
/// the picture.
pub data: Vec<u8>,
pub pts: i64,
/// Decoding timestamp; equal to `pts` while there are no B pictures.
/// Decoding timestamp: `pts` without B pictures; with them, the presentation times in
/// decoding order one picture interval earlier, so `dts <= pts`. A stream of one picture has
/// no interval: its `dts` is `pts - 1`.
pub dts: i64,
/// An I picture starting a closed GOP (random access point).
/// An I picture (random access point; in an open GOP the B pictures after it in decoding
/// order also need the previous GOP).
pub keyframe: bool,
pub picture_type: PictureType,
/// Average quantiser_scale of the picture's macroblocks.
@@ -260,6 +278,13 @@ fn validate(cfg: &EncoderConfig) -> Result<(), EncodeError> {
if !(1..=1023).contains(&cfg.gop_size) {
return bad(format!("GOP size {} (1..=1023)", cfg.gop_size));
}
if cfg.b_pictures > 4 {
return bad(format!("{} B pictures between anchors (0..=4)", cfg.b_pictures));
}
// temporal_reference (10 bits) counts a GOP's leading B pictures too
if cfg.gop_size + cfg.b_pictures > 1024 {
return bad(format!("GOP size {} with {} B pictures: more than 1024 pictures to number", cfg.gop_size, cfg.b_pictures));
}
match cfg.rate {
RateControl::Quantiser(q) if !(1..=31).contains(&q) => return bad(format!("quantiser_scale_code {q} (1..=31)")),
RateControl::Abr { kbps: 0 } => return bad("bitrate 0".into()),
@@ -284,6 +309,26 @@ fn put_matrix(w: &mut BitWriter, m: &[u8; 64]) {
}
}
/// A source picture waiting for the anchor after it (a B picture).
struct Held {
src: Frame,
pts: i64,
/// Display index.
n: u64,
}
/// A coded picture before rate control and timestamps.
struct Coded {
packet: Packet,
recon: Frame,
mvs: Vec<[i32; 2]>,
avg_q: f64,
}
/// Quantiser ratio of B to P pictures with a constant quantiser (TM5 uses 1.4 for its rate
/// allocation; a constant quantiser keeps B pictures a little closer to the anchors).
const B_QUANT_FACTOR: f64 = 1.25;
/// A stateful encoder. Feed pictures in display order; packets come out in decoding order.
pub struct Encoder {
cfg: EncoderConfig,
@@ -297,16 +342,32 @@ pub struct Encoder {
inter_matrix: [u8; 64],
/// Sequence header and sequence extension, sent before every GOP.
seq_header: Vec<u8>,
/// The reconstruction of the previous picture.
reference: Option<Frame>,
prev_mvs: Vec<[i32; 2]>,
/// Pictures coded so far.
/// The reconstructions of the last two anchor pictures and their display indices: `latest`
/// is the backward reference of the B pictures held, and the forward reference of the next
/// P picture.
older: Option<(Frame, u64)>,
latest: Option<(Frame, u64)>,
/// Forward vectors of the latest anchor when it is a P picture (search candidates).
anchor_mvs: Vec<[i32; 2]>,
/// B pictures waiting for their backward reference.
held: Vec<Held>,
/// Display index of the next picture.
count: u64,
/// Position of the next picture in its GOP.
gop_pos: u32,
/// Display indices of the current GOP's I picture and of its first picture in display order
/// (a leading B picture in front of the I picture, or the I picture).
gop_start: u64,
gop_first: u64,
/// The current GOP is closed: its leading B pictures predict backward only.
gop_closed: bool,
/// Presentation times not yet given to a coded picture as its decoding time, in input order.
display_pts: VecDeque<i64>,
last_pts: Option<i64>,
pts_step: Option<i64>,
/// Packets waiting for the presentation time step (the decoding time offset).
out: Vec<Packet>,
rc: Option<RateCtl>,
recon_capture: bool,
recon: Vec<ReconFrame>,
recon: Vec<(u64, ReconFrame)>,
}
impl Encoder {
@@ -330,10 +391,18 @@ impl Encoder {
intra_matrix: cfg.intra_matrix.unwrap_or(DEFAULT_INTRA),
inter_matrix: cfg.non_intra_matrix.unwrap_or([16; 64]),
seq_header: Vec::new(),
reference: None,
prev_mvs: Vec::new(),
older: None,
latest: None,
anchor_mvs: Vec::new(),
held: Vec::new(),
count: 0,
gop_pos: 0,
gop_start: 0,
gop_first: 0,
gop_closed: true,
display_pts: VecDeque::new(),
last_pts: None,
pts_step: None,
out: Vec::new(),
rc,
recon_capture: false,
recon: Vec::new(),
@@ -367,13 +436,32 @@ impl Encoder {
self.recon_capture = on;
}
/// The reconstructions captured so far, in display order.
pub fn take_recon(&mut self) -> Vec<ReconFrame> {
std::mem::take(&mut self.recon)
let mut r = std::mem::take(&mut self.recon);
r.sort_by_key(|(n, _)| *n);
r.into_iter().map(|(_, f)| f).collect()
}
/// Pictures held for reordering (none yet: there are no B pictures).
/// Code the pictures held for reordering (the last of them becomes a P picture) and return
/// every packet not yet returned. The next picture starts a new GOP.
pub fn flush(&mut self) -> Vec<Packet> {
Vec::new()
let mut out = Vec::new();
if let Some(last) = self.held.pop() {
self.code_anchor(last, PictureType::P, &mut out);
}
// the GOP ends here: its budget covered `gop_size` pictures, so take back the share of
// those that never came, or every flushed GOP would raise the bitrate of the next
if self.latest.is_some() {
let missing = u64::from(self.cfg.gop_size).saturating_sub(self.count - self.gop_start);
if let Some(rc) = self.rc.as_mut() {
rc.end_gop(missing as u32);
}
}
self.older = None;
self.latest = None;
self.anchor_mvs.clear();
self.release(out, true)
}
fn sequence_header_bytes(&self) -> Vec<u8> {
@@ -406,16 +494,15 @@ impl Encoder {
w.put((bit_rate >> 18) as u32 & 0xFFF, 12);
w.bit(true); // marker_bit
w.put((vbv >> 10) as u32 & 0xFF, 8);
w.bit(true); // low_delay: no B pictures
w.bit(c.b_pictures == 0); // low_delay: no B pictures, no reordering
w.put(0, 2); // frame_rate_extension_n
w.put(0, 5); // frame_rate_extension_d
w.finish()
}
/// group_of_pictures_header with the time code of picture `self.count`.
fn gop_header(&self, w: &mut BitWriter) {
/// group_of_pictures_header with the time code of display picture `n`.
fn gop_header(&self, w: &mut BitWriter, n: u64, closed: bool) {
let fps = u64::from(self.cfg.fps_num.div_ceil(self.cfg.fps_den)).max(1);
let n = self.count;
let secs = n / fps;
w.start_code(0xB8);
w.bit(false); // drop_frame_flag
@@ -424,24 +511,40 @@ impl Encoder {
w.bit(true); // marker_bit
w.put((secs % 60) as u32, 6);
w.put((n % fps) as u32, 6);
w.bit(true); // closed_gop
w.bit(closed); // closed_gop
w.bit(false); // broken_link
}
fn picture_header(&self, w: &mut BitWriter, intra: bool) {
fn picture_header(&self, w: &mut BitWriter, ptype: PictureType, temporal_reference: u64) {
w.start_code(0x00);
w.put(self.gop_pos & 0x3FF, 10); // temporal_reference: display order within the GOP
w.put(if intra { 1 } else { 2 }, 3);
w.put((temporal_reference & 0x3FF) as u32, 10); // display order within the GOP
w.put(
match ptype {
PictureType::P => 2,
PictureType::B => 3,
_ => 1,
},
3,
);
w.put(0xFFFF, 16); // vbv_delay: variable bitrate
if !intra {
w.bit(false); // full_pel_forward_vector
w.put(7, 3); // forward_f_code (MPEG-2: in the extension)
for dir in [PictureType::P, PictureType::B] {
if ptype == dir || ptype == PictureType::B {
// full_pel_{forward,backward}_vector and {forward,backward}_f_code: MPEG-2
// carries them in the extension
w.bit(false);
w.put(7, 3);
}
}
w.bit(false); // extra_bit_picture
w.start_code(0xB5);
w.put(8, 4); // picture coding extension
let fc = if intra { 15 } else { u32::from(self.f_code) };
for v in [fc, fc, 15, 15] {
let fc = u32::from(self.f_code);
let f_codes = match ptype {
PictureType::P => [fc, fc, 15, 15],
PictureType::B => [fc; 4],
_ => [15; 4],
};
for v in f_codes {
w.put(v, 4);
}
w.put(u32::from(self.cfg.intra_dc_bits - 8), 2);
@@ -502,28 +605,113 @@ impl Encoder {
acts.iter().map(|&a| qcode_for(nl, base * (2.0 * a + avg) / (a + 2.0 * avg))).collect()
}
/// Encode one picture. Returns the packets that became ready (one per picture for now).
/// With B pictures, presentation times must step by a constant amount, and the decoding
/// times (one step earlier) must fit in an `i64`. Checked before any state changes.
fn check_pts(&self, pts: i64) -> Result<Option<i64>, EncodeError> {
if self.cfg.b_pictures == 0 {
return Ok(None);
}
let no_dts = |pts: i64, step: i64| EncodeError::BadTimestamp(format!("{pts}: no decoding time {step} earlier"));
let Some(last) = self.last_pts else {
// flushed before a second picture, this one decodes at `pts - 1` (see `release`)
return if pts == i64::MIN { Err(no_dts(pts, 1)) } else { Ok(None) };
};
let step = pts.checked_sub(last).filter(|&d| d > 0).ok_or_else(|| EncodeError::BadTimestamp(format!("{pts} after {last}")))?;
match self.pts_step {
Some(s) if s != step => Err(EncodeError::BadTimestamp(format!("{pts} after {last}: step {step}, earlier {s}"))),
// the earliest decoding time is the earlier picture's time less the step
None if last.checked_sub(step).is_none() => Err(no_dts(last, step)),
_ => Ok(Some(step)),
}
}
/// Encode one picture (display order). Returns the packets that became ready, in decoding
/// order: with B pictures, a B picture is held until the anchor after it is coded.
pub fn encode(&mut self, frame: &YuvFrame, pts: i64) -> Result<Vec<Packet>, EncodeError> {
let src = self.load(frame)?;
let reference = if self.gop_pos == 0 { None } else { self.reference.take() };
let intra = reference.is_none();
if let Some(step) = self.check_pts(pts)? {
self.pts_step = Some(step);
}
self.last_pts = Some(pts);
let n = self.count;
self.count += 1;
self.display_pts.push_back(pts);
let held = Held { src, pts, n };
let mut out = Vec::new();
let m = u64::from(self.cfg.b_pictures) + 1;
if self.latest.is_none() || n - self.gop_start >= u64::from(self.cfg.gop_size) {
self.code_anchor(held, PictureType::I, &mut out);
} else if (n - self.gop_start).is_multiple_of(m) {
self.code_anchor(held, PictureType::P, &mut out);
} else {
self.held.push(held);
}
Ok(self.release(out, false))
}
/// Code an anchor picture, then the B pictures held in front of it.
fn code_anchor(&mut self, h: Held, ptype: PictureType, out: &mut Vec<Packet>) {
let intra = ptype == PictureType::I;
if intra {
self.gop_pos = 0;
self.gop_start = h.n;
self.gop_first = self.held.first().map_or(h.n, |b| b.n);
self.gop_closed = self.cfg.closed_gop || self.held.is_empty();
let n = u64::from(self.cfg.gop_size);
let m = u64::from(self.cfg.b_pictures) + 1;
let np = (n - 1) / m;
if let Some(rc) = self.rc.as_mut() {
rc.start_gop(self.cfg.gop_size);
rc.start_gop(np as u32, (n - 1 - np) as u32);
}
}
let fwd = if intra { None } else { self.latest.as_ref().map(|r| &r.0) };
let cand: &[[i32; 2]] = if intra { &[] } else { &self.anchor_mvs };
let c = self.code_picture(&h, ptype, (fwd, None), [cand, &[]]);
let (recon, mvs) = self.finish(c, h.n, out);
self.older = self.latest.take();
self.latest = Some((recon, h.n));
self.anchor_mvs = if intra { Vec::new() } else { mvs };
for b in std::mem::take(&mut self.held) {
self.code_b(b, out);
}
}
/// Code a B picture between the two latest anchors. The leading B pictures of a closed GOP
/// (shown before its I picture) predict backward only.
fn code_b(&mut self, b: Held, out: &mut Vec<Packet>) {
let Some((bwd, bn)) = self.latest.as_ref() else { return };
let leading = b.n < self.gop_start;
let fwd = self.older.as_ref().filter(|_| !(leading && self.gop_closed));
// search candidates: the latest anchor's vectors (which span the two anchors) scaled to
// this picture's distance from each
let span = self.older.as_ref().map_or(1, |o| bn.saturating_sub(o.1).max(1)) as i64;
let scaled = |d: i64| -> Vec<[i32; 2]> {
self.anchor_mvs.iter().map(|v| [(i64::from(v[0]) * d / span) as i32, (i64::from(v[1]) * d / span) as i32]).collect()
};
let cf = fwd.map_or(Vec::new(), |f| scaled(b.n as i64 - f.1 as i64));
let cb = scaled(b.n as i64 - *bn as i64);
let c = self.code_picture(&b, PictureType::B, (fwd.map(|f| &f.0), Some(bwd)), [&cf, &cb]);
self.finish(c, b.n, out);
}
/// Code one picture with the given references and search candidates.
fn code_picture(&self, h: &Held, ptype: PictureType, (fwd, bwd): (Option<&Frame>, Option<&Frame>), cand: [&[[i32; 2]]; 2]) -> Coded {
let base = match (&self.rc, self.cfg.rate) {
(Some(rc), _) => rc.qscale(intra),
(None, RateControl::Quantiser(q)) => f64::from(qscale(self.cfg.nonlinear_quant, q)),
(Some(rc), _) => rc.qscale(ptype),
(None, RateControl::Quantiser(q)) => {
let qs = f64::from(qscale(self.cfg.nonlinear_quant, q));
if ptype == PictureType::B { qs * B_QUANT_FACTOR } else { qs }
}
(None, _) => 8.0,
};
let mb_qcode = self.mb_quant(&src, base);
let src = &h.src;
let mb_qcode = self.mb_quant(src, base);
let mut recon = Frame::new(src.w, src.h, src.cw, src.ch);
let ctx = PicCtx {
src: &src,
reference: reference.as_ref(),
prev_mvs: &self.prev_mvs,
ptype,
src,
fwd,
bwd,
cand,
mb_w: self.mb_w,
shx: self.shx,
shy: self.shy,
@@ -536,11 +724,12 @@ impl Encoder {
mb_qcode: &mb_qcode,
};
let rows = encode_rows(&ctx, &mut recon, self.cfg.threads);
let intra = ptype == PictureType::I;
let mut w = BitWriter::new();
if intra {
self.gop_header(&mut w);
self.gop_header(&mut w, self.gop_first, self.gop_closed);
}
self.picture_header(&mut w, intra);
self.picture_header(&mut w, ptype, h.n - self.gop_first);
let mut data = if intra { self.seq_header.clone() } else { Vec::new() };
data.extend_from_slice(&w.finish());
let mut qsum = 0u64;
@@ -551,18 +740,47 @@ impl Encoder {
mvs.extend_from_slice(&r.mvs);
}
let avg_q = qsum as f64 / (self.mb_w * self.mb_h).max(1) as f64;
let packet = Packet { data, pts: h.pts, dts: h.pts, keyframe: intra, picture_type: ptype, quantiser_scale: avg_q as f32 };
Coded { packet, recon, mvs, avg_q }
}
/// Account for a coded picture (display index `n`): rate control, its decoding time, the
/// reconstruction capture. Returns the reconstruction and the picture's vectors.
fn finish(&mut self, c: Coded, n: u64, out: &mut Vec<Packet>) -> (Frame, Vec<[i32; 2]>) {
let Coded { mut packet, recon, mvs, avg_q } = c;
if let Some(rc) = self.rc.as_mut() {
rc.update(intra, data.len() as u64 * 8, avg_q);
rc.update(packet.picture_type, packet.data.len() as u64 * 8, avg_q);
}
// the k-th coded picture decodes at the k-th presentation time (less the offset that
// `release` subtracts); one time is queued per input picture
packet.dts = self.display_pts.pop_front().unwrap_or(packet.pts);
if self.recon_capture {
self.recon.push(self.crop(&recon));
self.recon.push((n, self.crop(&recon)));
}
self.reference = Some(recon);
self.prev_mvs = mvs;
self.count += 1;
self.gop_pos = (self.gop_pos + 1) % self.cfg.gop_size;
let picture_type = if intra { PictureType::I } else { PictureType::P };
Ok(vec![Packet { data, pts, dts: pts, keyframe: intra, picture_type, quantiser_scale: avg_q as f32 }])
out.push(packet);
(recon, mvs)
}
/// Hand out packets once their decoding times are known: with B pictures they are the
/// presentation times one step earlier, so packets wait for the second picture's time.
fn release(&mut self, out: Vec<Packet>, flushing: bool) -> Vec<Packet> {
self.out.extend(out);
if self.cfg.b_pictures == 0 {
return std::mem::take(&mut self.out);
}
if self.pts_step.is_none() && !flushing {
return Vec::new();
}
// A lone picture flushed before a second one set the step decodes one unit early, the
// smallest step there is: if encoding goes on, the next picture decodes at this one's
// presentation time whatever the step turns out to be, and that must be later.
let off = self.pts_step.unwrap_or(1);
let mut res = std::mem::take(&mut self.out);
for p in &mut res {
// `check_pts` refused the times this would not fit for
p.dts = p.dts.saturating_sub(off);
}
res
}
fn crop(&self, f: &Frame) -> ReconFrame {
+3 -2
View File
@@ -47,7 +47,7 @@ impl Search<'_> {
}
/// A half-sample vector the bitstream can carry whose prediction stays inside the reference.
fn valid(&self, mv: [i32; 2]) -> bool {
pub(crate) fn valid(&self, mv: [i32; 2]) -> bool {
let f = 1i32 << self.f_code.saturating_sub(1);
let (ox, oy) = self.origin();
let size = [self.reference.w as i32, self.reference.h as i32];
@@ -58,7 +58,8 @@ impl Search<'_> {
})
}
fn mv_cost(&self, mv: [i32; 2]) -> u32 {
/// λ·(bits of `mv` against the predictor).
pub(crate) fn mv_cost(&self, mv: [i32; 2]) -> u32 {
let t = enc_tables();
let bits: u32 = (0..2).map(|c| t.motion_bits(wrap_delta(mv[c], self.pmv[c], self.f_code), self.f_code)).sum();
self.lambda * bits
+296 -76
View File
@@ -1,11 +1,11 @@
//! Slices and macroblocks of one frame picture (H.262 §6.2.4-§6.2.6), with a reconstruction
//! that matches the decoder exactly. One slice per macroblock row; slices only depend on the
//! reference picture, so rows can be coded in parallel.
//! reference pictures, so rows can be coded in parallel.
use crate::mpeg2::headers::SCAN;
use crate::mpeg2::headers::{PictureType, SCAN};
use crate::mpeg2::mc::{Block, Frame, predict};
use crate::mpeg2::slice::NON_LINEAR_Q;
use crate::mpeg2::vlc::{MB_FWD, MB_INTRA, MB_PATTERN, MB_QUANT};
use crate::mpeg2::vlc::{MB_BWD, MB_FWD, MB_INTRA, MB_PATTERN, MB_QUANT};
use super::bitwriter::BitWriter;
use super::motion::Search;
@@ -35,12 +35,17 @@ pub(crate) fn qcode_for(nonlinear: bool, qs: f64) -> u8 {
/// What every slice of one picture shares (read-only).
pub(crate) struct PicCtx<'a> {
/// I, P or B.
pub ptype: PictureType,
/// The padded source picture.
pub src: &'a Frame,
/// The reconstructed previous picture (P pictures); `None` codes an I picture.
pub reference: Option<&'a Frame>,
/// Vectors of the previous picture (motion search candidates), one per macroblock.
pub prev_mvs: &'a [[i32; 2]],
/// The reconstructed reference pictures: forward (P and B pictures) and backward (B
/// pictures). A B picture without a forward reference (the leading B pictures of a closed
/// GOP) predicts backward only.
pub fwd: Option<&'a Frame>,
pub bwd: Option<&'a Frame>,
/// Motion search candidates per macroblock, forward and backward (empty: none).
pub cand: [&'a [[i32; 2]]; 2],
pub mb_w: usize,
pub shx: u32,
pub shy: u32,
@@ -166,11 +171,22 @@ impl MbPix {
struct SliceSt {
qcode: u8,
dc: [i32; 3],
pmv: [i32; 2],
/// Motion vector predictors, forward and backward.
pmv: [[i32; 2]; 2],
/// Skipped macroblocks not yet covered by an address increment.
skipped: usize,
/// The vector of the macroblock to the left (motion search candidate).
left_mv: [i32; 2],
/// The vectors of the macroblock to the left (motion search candidates).
left_mv: [[i32; 2]; 2],
/// Prediction directions (`MB_FWD` / `MB_BWD`) of the previous macroblock, or `MB_INTRA`:
/// a skipped macroblock in a B picture repeats them.
last_dirs: i16,
}
/// A B macroblock's prediction: its directions and a vector per direction.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
struct BPred {
dirs: i16,
mvs: [[i32; 2]; 2],
}
/// One macroblock being coded.
@@ -188,7 +204,7 @@ pub(crate) fn encode_row(ctx: &PicCtx, row: usize, out: &mut RowPlanes) -> RowOu
let q0 = ctx.mb_qcode.get(row * ctx.mb_w).copied().unwrap_or(1);
w.put(u32::from(q0), 5);
w.bit(false); // extra_bit_slice
let mut st = SliceSt { qcode: q0, dc: [ctx.dc_reset(); 3], pmv: [0; 2], skipped: 0, left_mv: [0; 2] };
let mut st = SliceSt { qcode: q0, dc: [ctx.dc_reset(); 3], pmv: [[0; 2]; 2], skipped: 0, left_mv: [[0; 2]; 2], last_dirs: MB_INTRA };
let mut ro = RowOut { bytes: Vec::new(), mvs: vec![[0; 2]; ctx.mb_w], stats: RowStats::default() };
for mbx in 0..ctx.mb_w {
macroblock(ctx, &mut st, &mut w, (mbx, row), out, &mut ro);
@@ -205,31 +221,105 @@ fn macroblock(ctx: &PicCtx, st: &mut SliceSt, w: &mut BitWriter, (mbx, mby): (us
let qs = qscale(ctx.nonlinear, qcode);
ro.stats.qsum += qs as u64;
let planes = (ctx.src.w, ctx.src.cw);
let Some(reference) = ctx.reference else {
intra_mb(ctx, st, w, &mb).put(out, mbx, ctx.cmb(), planes);
ro.stats.intra += 1;
return;
let lambda = ((qs * 3 + 4) / 8).max(1) as u32;
let rec = match (ctx.ptype, ctx.fwd) {
(PictureType::P, Some(reference)) => {
let search = Search { reference, src: &src.y, mbx, mby, f_code: ctx.f_code, range: ctx.search, pmv: st.pmv[0], lambda };
let found = search.run(&candidates(ctx, st, addr, 0));
if intra_cost(&src.y).saturating_add(INTRA_BIAS) < found.sad {
None
} else {
let (rec, skipped) = inter_mb(ctx, st, w, &mb, reference, found.mv);
ro.stats.skipped += skipped as u32;
ro.mvs[mbx] = found.mv;
st.left_mv[0] = found.mv;
Some(rec)
}
}
(PictureType::B, _) if ctx.bwd.is_some() => b_decision(ctx, st, &mb, lambda).map(|pred| {
let (rec, skipped) = b_mb(ctx, st, w, &mb, pred);
ro.stats.skipped += skipped as u32;
st.left_mv = pred.mvs;
rec
}),
_ => None,
};
let mut candidates = vec![st.left_mv, st.pmv];
let rec = rec.unwrap_or_else(|| {
ro.stats.intra += 1;
st.left_mv = [[0; 2]; 2];
intra_mb(ctx, st, w, &mb)
});
rec.put(out, mbx, ctx.cmb(), planes);
}
/// Motion search candidates for direction `s` of macroblock `addr`: the left neighbour's vector,
/// the predictor, and the co-located and neighbouring candidates of the picture.
fn candidates(ctx: &PicCtx, st: &SliceSt, addr: usize, s: usize) -> Vec<[i32; 2]> {
let mut c = vec![st.left_mv[s], st.pmv[s]];
for a in [Some(addr), addr.checked_sub(ctx.mb_w), Some(addr + 1), Some(addr + ctx.mb_w)].into_iter().flatten() {
if let Some(&v) = ctx.prev_mvs.get(a) {
candidates.push(v);
if let Some(&v) = ctx.cand[s].get(a) {
c.push(v);
}
}
let lambda = ((qs * 3 + 4) / 8).max(1) as u32;
let search = Search { reference, src: &src.y, mbx, mby, f_code: ctx.f_code, range: ctx.search, pmv: st.pmv, lambda };
let found = search.run(&candidates);
if intra_cost(&src.y).saturating_add(INTRA_BIAS) < found.sad {
intra_mb(ctx, st, w, &mb).put(out, mbx, ctx.cmb(), planes);
ro.stats.intra += 1;
st.left_mv = [0; 2];
return;
c
}
/// Luma SAD of a prediction against the source.
fn sad(a: &[u8; 256], b: &[u8; 256]) -> u32 {
a.iter().zip(b).map(|(x, y)| u32::from(x.abs_diff(*y))).sum()
}
/// Choose a B macroblock's prediction: forward, backward or interpolated, from a motion search
/// per direction, or the skip prediction (the previous macroblock's directions with the
/// predictors). `None`: code it intra.
fn b_decision(ctx: &PicCtx, st: &SliceSt, mb: &MbIn, lambda: u32) -> Option<BPred> {
let addr = mb.mby * ctx.mb_w + mb.mbx;
let mut found = [None, None];
for (s, r) in [ctx.fwd, ctx.bwd].into_iter().enumerate() {
if let Some(reference) = r {
let search =
Search { reference, src: &mb.src.y, mbx: mb.mbx, mby: mb.mby, f_code: ctx.f_code, range: ctx.search, pmv: st.pmv[s], lambda };
let f = search.run(&candidates(ctx, st, addr, s));
found[s] = Some((f.mv, f.sad, search.mv_cost(f.mv)));
}
}
let (rec, skipped) = inter_mb(ctx, st, w, &mb, reference, found.mv);
rec.put(out, mbx, ctx.cmb(), planes);
ro.stats.skipped += skipped as u32;
ro.mvs[mbx] = found.mv;
st.left_mv = found.mv;
let mut best: Option<(BPred, u32)> = None;
let mut consider = |pred: BPred, cost: u32| {
if best.is_none_or(|(_, c)| cost < c) {
best = Some((pred, cost));
}
};
for (s, dir) in [(0, MB_FWD), (1, MB_BWD)] {
if let Some((mv, sad, bits)) = found[s] {
let mut mvs = [[0; 2]; 2];
mvs[s] = mv;
consider(BPred { dirs: dir, mvs }, sad.saturating_add(bits));
}
}
if let (Some((f, _, bits_f)), Some((b, _, bits_b))) = (found[0], found[1]) {
let pred = BPred { dirs: MB_FWD | MB_BWD, mvs: [f, b] };
let p = predict_b(ctx, pred, mb.mbx, mb.mby);
consider(pred, sad(&p.y, &mb.src.y).saturating_add(bits_f).saturating_add(bits_b));
}
// the skip prediction costs no vector bits; the predictors came from the macroblock to the
// left, so they must be checked to stay inside the reference from here
let edge = mb.mbx == 0 || mb.mbx + 1 == ctx.mb_w;
if !edge && st.last_dirs & MB_INTRA == 0 && st.last_dirs != 0 {
let pred = BPred { dirs: st.last_dirs, mvs: st.pmv };
let usable = [(0, MB_FWD, ctx.fwd), (1, MB_BWD, ctx.bwd)].into_iter().all(|(s, dir, r)| {
st.last_dirs & dir == 0
|| r.is_some_and(|reference| {
let search =
Search { reference, src: &mb.src.y, mbx: mb.mbx, mby: mb.mby, f_code: ctx.f_code, range: ctx.search, pmv: st.pmv[s], lambda };
search.valid(st.pmv[s])
})
});
if usable {
consider(pred, sad(&predict_b(ctx, pred, mb.mbx, mb.mby).y, &mb.src.y));
}
}
let (pred, cost) = best?;
(intra_cost(&mb.src.y).saturating_add(INTRA_BIAS) >= cost).then_some(pred)
}
/// Σ |sample − block mean| over the four luma blocks: the cost of coding them intra.
@@ -270,8 +360,12 @@ fn put_coefficients(w: &mut BitWriter, t: &EncTables, levels: &[i32; 64], table:
t.dct_eob[table].put(w);
}
fn put_mb_type(w: &mut BitWriter, t: &EncTables, predicted: bool, flags: i16) {
let table = if predicted { &t.mbtype_p } else { &t.mbtype_i };
fn put_mb_type(w: &mut BitWriter, t: &EncTables, ptype: PictureType, flags: i16) {
let table = match ptype {
PictureType::P => &t.mbtype_p,
PictureType::B => &t.mbtype_b,
_ => &t.mbtype_i,
};
if let Some(c) = table.get(flags as usize).copied().flatten() {
c.put(w);
}
@@ -283,12 +377,13 @@ fn intra_mb(ctx: &PicCtx, st: &mut SliceSt, w: &mut BitWriter, mb: &MbIn) -> MbP
let quant = mb.qcode != st.qcode;
put_increment(w, t, st.skipped + 1);
st.skipped = 0;
put_mb_type(w, t, ctx.reference.is_some(), if quant { MB_INTRA | MB_QUANT } else { MB_INTRA });
put_mb_type(w, t, ctx.ptype, if quant { MB_INTRA | MB_QUANT } else { MB_INTRA });
if quant {
w.put(u32::from(mb.qcode), 5);
st.qcode = mb.qcode;
}
st.pmv = [0; 2];
st.pmv = [[0; 2]; 2];
st.last_dirs = MB_INTRA;
let qs = qscale(ctx.nonlinear, st.qcode);
let dc_mult = 8 >> ctx.dc_prec;
let dc_max = (1 << (8 + ctx.dc_prec)) - 1;
@@ -321,28 +416,16 @@ fn intra_mb(ctx: &PicCtx, st: &mut SliceSt, w: &mut BitWriter, mb: &MbIn) -> MbP
/// whether it was skipped.
fn inter_mb(ctx: &PicCtx, st: &mut SliceSt, w: &mut BitWriter, mb: &MbIn, reference: &Frame, mv: [i32; 2]) -> (MbPix, bool) {
let t = enc_tables();
let mut rec = predict_mb(ctx, reference, mv, mb.mbx, mb.mby);
let mut rec = predict_mb(ctx, Some(reference), mv, mb.mbx, mb.mby);
let qs = qscale(ctx.nonlinear, mb.qcode);
let (cbw, _) = ctx.cmb();
let n = ctx.blocks();
let mut levels = [[0i32; 64]; 8];
let mut cbp = 0u32;
for i in 0..n {
let (s, p) = (mb.src.block(i, cbw), rec.block(i, cbw));
let f = fdct(&std::array::from_fn(|k| s[k] - p[k]));
for pos in 0..64 {
levels[i][pos] = quant_inter(f[pos], ctx.inter_matrix[pos], qs);
}
if levels[i].iter().any(|&l| l != 0) {
cbp |= 1 << (n - 1 - i);
}
}
let (levels, cbp) = residual(ctx, mb, &rec, qs);
st.dc = [ctx.dc_reset(); 3];
st.last_dirs = MB_FWD;
// the first and last macroblock of a slice are always coded
let edge = mb.mbx == 0 || mb.mbx + 1 == ctx.mb_w;
if mv == [0, 0] && cbp == 0 && !edge {
st.skipped += 1;
st.pmv = [0; 2];
st.pmv = [[0; 2]; 2];
return (rec, true);
}
put_increment(w, t, st.skipped + 1);
@@ -358,44 +441,140 @@ fn inter_mb(ctx: &PicCtx, st: &mut SliceSt, w: &mut BitWriter, mb: &MbIn, refere
if quant {
flags |= MB_QUANT;
}
put_mb_type(w, t, true, flags);
put_mb_type(w, t, PictureType::P, flags);
if quant {
w.put(u32::from(mb.qcode), 5);
st.qcode = mb.qcode;
}
if flags & MB_FWD != 0 {
for c in 0..2 {
t.put_motion(w, wrap_delta(mv[c], st.pmv[c], ctx.f_code), ctx.f_code);
t.put_motion(w, wrap_delta(mv[c], st.pmv[0][c], ctx.f_code), ctx.f_code);
}
st.pmv = mv;
st.pmv[0] = mv;
} else {
st.pmv = [0; 2]; // "No MC" resets the predictors
}
if cbp != 0 {
if n == 8 {
t.cbp[(cbp >> 2) as usize].put(w);
w.put(cbp & 3, 2);
} else {
t.cbp[cbp as usize].put(w);
}
for i in 0..n {
if cbp & (1 << (n - 1 - i)) != 0 {
put_coefficients(w, t, &levels[i], 0, 0);
rec.store(i, cbw, &reconstruct(&levels[i], ctx.inter_matrix, qs, false, 0), true);
}
}
st.pmv = [[0; 2]; 2]; // "No MC" resets the predictors
}
put_residual(ctx, w, &levels, cbp, &mut rec, qs);
(rec, false)
}
/// The frame prediction of a macroblock from `f` with vector `mv`, formed as the decoder forms
/// it (§7.6.4: chroma vectors are the luma ones halved towards zero).
fn predict_mb(ctx: &PicCtx, f: &Frame, mv: [i32; 2], mbx: usize, mby: usize) -> MbPix {
let (cbw, cbh) = ctx.cmb();
/// Quantised residual of every block of `mb` against `pred`, and the coded_block_pattern.
fn residual(ctx: &PicCtx, mb: &MbIn, pred: &MbPix, qs: i32) -> ([[i32; 64]; 8], u32) {
let (cbw, _) = ctx.cmb();
let n = ctx.blocks();
let mut levels = [[0i32; 64]; 8];
let mut cbp = 0u32;
for i in 0..n {
let (s, p) = (mb.src.block(i, cbw), pred.block(i, cbw));
let f = fdct(&std::array::from_fn(|k| s[k] - p[k]));
for pos in 0..64 {
levels[i][pos] = quant_inter(f[pos], ctx.inter_matrix[pos], qs);
}
if levels[i].iter().any(|&l| l != 0) {
cbp |= 1 << (n - 1 - i);
}
}
(levels, cbp)
}
/// Write coded_block_pattern and the coded blocks, adding their reconstruction to `rec`.
fn put_residual(ctx: &PicCtx, w: &mut BitWriter, levels: &[[i32; 64]; 8], cbp: u32, rec: &mut MbPix, qs: i32) {
if cbp == 0 {
return;
}
let t = enc_tables();
let (cbw, _) = ctx.cmb();
let n = ctx.blocks();
if n == 8 {
t.cbp[(cbp >> 2) as usize].put(w);
w.put(cbp & 3, 2);
} else {
t.cbp[cbp as usize].put(w);
}
for i in 0..n {
if cbp & (1 << (n - 1 - i)) != 0 {
put_coefficients(w, t, &levels[i], 0, 0);
rec.store(i, cbw, &reconstruct(&levels[i], ctx.inter_matrix, qs, false, 0), true);
}
}
}
/// Code a B macroblock with prediction `pred` (or skip it); returns its reconstruction and
/// whether it was skipped.
fn b_mb(ctx: &PicCtx, st: &mut SliceSt, w: &mut BitWriter, mb: &MbIn, pred: BPred) -> (MbPix, bool) {
let t = enc_tables();
let mut rec = predict_b(ctx, pred, mb.mbx, mb.mby);
let qs = qscale(ctx.nonlinear, mb.qcode);
let (levels, cbp) = residual(ctx, mb, &rec, qs);
st.dc = [ctx.dc_reset(); 3];
// a skipped B macroblock repeats the previous one's directions with the predictors as its
// vectors (§7.6.6.3); the first and last macroblock of a slice are always coded
let edge = mb.mbx == 0 || mb.mbx + 1 == ctx.mb_w;
let same = |s: usize, dir: i16| pred.dirs & dir == 0 || pred.mvs[s] == st.pmv[s];
if cbp == 0 && !edge && st.last_dirs & MB_INTRA == 0 && pred.dirs == st.last_dirs && same(0, MB_FWD) && same(1, MB_BWD) {
st.skipped += 1;
return (rec, true);
}
put_increment(w, t, st.skipped + 1);
st.skipped = 0;
let quant = cbp != 0 && mb.qcode != st.qcode;
let mut flags = pred.dirs;
if cbp != 0 {
flags |= MB_PATTERN;
}
if quant {
flags |= MB_QUANT;
}
put_mb_type(w, t, PictureType::B, flags);
if quant {
w.put(u32::from(mb.qcode), 5);
st.qcode = mb.qcode;
}
for (s, dir) in [(0, MB_FWD), (1, MB_BWD)] {
if pred.dirs & dir != 0 {
for c in 0..2 {
t.put_motion(w, wrap_delta(pred.mvs[s][c], st.pmv[s][c], ctx.f_code), ctx.f_code);
}
st.pmv[s] = pred.mvs[s];
}
}
st.last_dirs = pred.dirs;
put_residual(ctx, w, &levels, cbp, &mut rec, qs);
(rec, false)
}
/// The prediction of a B macroblock: forward, backward, or the average of both, formed in the
/// decoder's order (forward first, then the backward prediction averaged in).
fn predict_b(ctx: &PicCtx, pred: BPred, mbx: usize, mby: usize) -> MbPix {
let mut p = MbPix { y: [0; 256], c: [[0; 256]; 2] };
let mut avg = false;
for (s, dir, r) in [(0, MB_FWD, ctx.fwd), (1, MB_BWD, ctx.bwd)] {
if pred.dirs & dir != 0 {
if let Some(f) = r {
predict_into(ctx, &mut p, f, pred.mvs[s], (mbx, mby), avg);
}
avg = true;
}
}
p
}
/// The frame prediction of a macroblock from `f` with vector `mv` (gray without a reference).
fn predict_mb(ctx: &PicCtx, f: Option<&Frame>, mv: [i32; 2], mbx: usize, mby: usize) -> MbPix {
let mut p = MbPix { y: [128; 256], c: [[128; 256]; 2] };
if let Some(f) = f {
predict_into(ctx, &mut p, f, mv, (mbx, mby), false);
}
p
}
/// Form the frame prediction from `f` with vector `mv` into `p`, or average it with what `p`
/// holds, as the decoder forms it (§7.6.4: chroma vectors are the luma ones halved towards zero).
fn predict_into(ctx: &PicCtx, p: &mut MbPix, f: &Frame, mv: [i32; 2], (mbx, mby): (usize, usize), avg: bool) {
let (cbw, cbh) = ctx.cmb();
let blk =
Block { x: (mbx * 16) as i32 + (mv[0] >> 1), y: (mby * 16) as i32 + (mv[1] >> 1), hx: mv[0] & 1 != 0, hy: mv[1] & 1 != 0, bw: 16, bh: 16 };
predict(&mut p.y, 0, 16, f.plane(0, None), blk, false);
predict(&mut p.y, 0, 16, f.plane(0, None), blk, avg);
let cmv = [if ctx.shx == 1 { mv[0] / 2 } else { mv[0] }, if ctx.shy == 1 { mv[1] / 2 } else { mv[1] }];
let cb = Block {
x: (mbx * cbw) as i32 + (cmv[0] >> 1),
@@ -406,7 +585,48 @@ fn predict_mb(ctx: &PicCtx, f: &Frame, mv: [i32; 2], mbx: usize, mby: usize) ->
bh: cbh,
};
for c in 0..2 {
predict(&mut p.c[c], 0, cbw, f.plane(1 + c, None), cb, false);
predict(&mut p.c[c], 0, cbw, f.plane(1 + c, None), cb, avg);
}
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn a_skip_prediction_never_leaves_the_reference() {
// three macroblocks across; the left neighbour's forward vector (+17 samples) fits its
// own position but points past the right edge from the middle macroblock
let mut f = Frame::new(48, 16, 24, 8);
for (i, v) in f.planes[0].iter_mut().enumerate() {
*v = ((i % 48) * 5 + (i / 48) * 11) as u8;
}
let ctx = PicCtx {
ptype: PictureType::B,
src: &f,
fwd: Some(&f),
bwd: Some(&f),
cand: [&[], &[]],
mb_w: 3,
shx: 1,
shy: 1,
intra_matrix: &crate::mpeg2::headers::DEFAULT_INTRA,
inter_matrix: &[16; 64],
nonlinear: true,
dc_prec: 1,
f_code: 3,
search: 31,
mb_qcode: &[4; 3],
};
let bad = BPred { dirs: MB_FWD, mvs: [[34, 0], [0, 0]] };
// the bitstream can carry the vector (f_code 3: -64..64): only the position rules it out
let at = |mbx| Search { reference: &f, src: &[0; 256], mbx, mby: 0, f_code: ctx.f_code, range: ctx.search, pmv: bad.mvs[0], lambda: 1 };
assert!(at(0).valid(bad.mvs[0]) && !at(1).valid(bad.mvs[0]));
// a source that the out-of-range (edge-clamped) prediction would match exactly
let src = predict_b(&ctx, bad, 1, 0);
let st = SliceSt { qcode: 4, dc: [256; 3], pmv: bad.mvs, skipped: 0, left_mv: bad.mvs, last_dirs: MB_FWD };
let mb = MbIn { src: &src, mbx: 1, mby: 0, qcode: 4 };
let pred = b_decision(&ctx, &st, &mb, 1);
assert_ne!(pred, Some(bad));
}
p
}
+99 -41
View File
@@ -1,18 +1,26 @@
//! Single-pass average bitrate control at picture level, after the target bit allocation of the
//! MPEG-2 Test Model 5: each picture type keeps a complexity `X = bits · average quantiser`, the
//! bits left for the GOP are shared out by complexity, and a picture's quantiser is `X / target`.
//! There is no VBV model: the average converges on the target, single pictures may not.
//! bits left for the GOP are shared out by complexity (B pictures weighted down by `KB`), and a
//! picture's quantiser is `X / target`. There is no VBV model: the average converges on the
//! target, single pictures may not.
use crate::mpeg2::headers::PictureType;
/// TM5's quantiser ratio of B to P pictures (K_b / K_p).
const KB: f64 = 1.4;
pub(crate) struct RateCtl {
bps: f64,
fps: f64,
/// Complexity of I and P pictures.
/// Complexity of I, P and B pictures.
xi: f64,
xp: f64,
xb: f64,
/// Bits left for the current GOP (carries over between GOPs).
remaining: f64,
/// P pictures left in the current GOP.
/// P and B pictures left in the current GOP.
np: u32,
nb: u32,
/// Range of quantiser_scale values.
q_min: f64,
q_max: f64,
@@ -21,34 +29,60 @@ pub(crate) struct RateCtl {
impl RateCtl {
pub fn new(bps: f64, fps: f64, q_range: (f64, f64)) -> Self {
// TM5's starting complexities
Self { bps, fps, xi: 160.0 * bps / 115.0, xp: 60.0 * bps / 115.0, remaining: 0.0, np: 0, q_min: q_range.0, q_max: q_range.1 }
Self {
bps,
fps,
xi: 160.0 * bps / 115.0,
xp: 60.0 * bps / 115.0,
xb: 42.0 * bps / 115.0,
remaining: 0.0,
np: 0,
nb: 0,
q_min: q_range.0,
q_max: q_range.1,
}
}
/// A GOP of `pictures` pictures (one I, the rest P) starts.
pub fn start_gop(&mut self, pictures: u32) {
self.remaining += self.bps * f64::from(pictures) / self.fps;
self.np = pictures.saturating_sub(1);
/// A GOP of one I, `np` P and `nb` B pictures starts.
pub fn start_gop(&mut self, np: u32, nb: u32) {
self.remaining += self.bps * f64::from(1 + np + nb) / self.fps;
self.np = np;
self.nb = nb;
}
/// quantiser_scale for the next picture.
pub fn qscale(&self, intra: bool) -> f64 {
/// The GOP ends `missing` pictures short of what `start_gop` budgeted (the encoder was
/// flushed): their bits are not carried into the next GOP.
pub fn end_gop(&mut self, missing: u32) {
self.remaining -= self.bps * f64::from(missing) / self.fps;
self.np = 0;
self.nb = 0;
}
/// quantiser_scale for the next picture of type `ptype`.
pub fn qscale(&self, ptype: PictureType) -> f64 {
let floor = self.bps / (8.0 * self.fps);
let (target, x) = if intra {
(self.remaining / (1.0 + f64::from(self.np) * self.xp / self.xi), self.xi)
} else {
(self.remaining / f64::from(self.np.max(1)), self.xp)
let (np, nb) = (f64::from(self.np), f64::from(self.nb));
let (target, x) = match ptype {
PictureType::I => (self.remaining / (1.0 + np * self.xp / self.xi + nb * self.xb / (self.xi * KB)), self.xi),
PictureType::B => (self.remaining / (nb.max(1.0) + np * KB * self.xp / self.xb), self.xb),
_ => (self.remaining / (np.max(1.0) + nb * self.xb / (KB * self.xp)), self.xp),
};
(x / target.max(floor)).clamp(self.q_min, self.q_max)
}
/// The picture used `bits` at average quantiser_scale `avg_q`.
pub fn update(&mut self, intra: bool, bits: u64, avg_q: f64) {
let x = bits as f64 * avg_q;
if intra {
self.xi = x.max(1.0);
} else {
self.xp = x.max(1.0);
self.np = self.np.saturating_sub(1);
/// A picture of type `ptype` used `bits` at average quantiser_scale `avg_q`.
pub fn update(&mut self, ptype: PictureType, bits: u64, avg_q: f64) {
let x = (bits as f64 * avg_q).max(1.0);
match ptype {
PictureType::I => self.xi = x,
PictureType::B => {
self.xb = x;
self.nb = self.nb.saturating_sub(1);
}
_ => {
self.xp = x;
self.np = self.np.saturating_sub(1);
}
}
self.remaining -= bits as f64;
}
@@ -58,18 +92,26 @@ impl RateCtl {
mod tests {
use super::*;
/// A picture whose size is `complexity / q` (the model the controller assumes).
fn run(complexity_i: f64, complexity_p: f64, bps: f64, gops: u32) -> f64 {
/// A picture whose size is `complexity / q` (the model the controller assumes), in GOPs of
/// 12 pictures with `b` B pictures between anchors.
fn run(c: [f64; 3], b: usize, bps: f64, gops: u32) -> f64 {
let fps = 25.0;
let types: Vec<PictureType> = (0..12)
.map(|k| match k {
0 => PictureType::I,
k if k % (b + 1) == 0 => PictureType::P,
_ => PictureType::B,
})
.collect();
let np = types.iter().filter(|&&t| t == PictureType::P).count() as u32;
let mut rc = RateCtl::new(bps, fps, (1.0, 112.0));
let mut total = 0.0;
for _ in 0..gops {
rc.start_gop(12);
for k in 0..12 {
let intra = k == 0;
let q = rc.qscale(intra);
let bits = (if intra { complexity_i } else { complexity_p }) / q;
rc.update(intra, bits as u64, q);
rc.start_gop(np, 11 - np);
for &t in &types {
let q = rc.qscale(t);
let bits = c[t as usize] / q;
rc.update(t, bits as u64, q);
total += bits;
}
}
@@ -79,24 +121,40 @@ mod tests {
#[test]
fn converges_on_the_target() {
// complexities whose target quantiser is inside the allowed range
for (ci, cp) in [(4e7, 1e7), (8e7, 2e6), (1e7, 9e6)] {
let got = run(ci, cp, 4e6, 20);
assert!((got / 4e6 - 1.0).abs() < 0.03, "{ci} {cp}: {got}");
for (c, b) in [([4e7, 1e7, 7e6], 0), ([8e7, 2e6, 1e6], 0), ([1e7, 9e6, 8e6], 0), ([4e7, 1e7, 7e6], 2), ([6e7, 2e7, 5e6], 1)] {
let got = run(c, b, 4e6, 20);
assert!((got / 4e6 - 1.0).abs() < 0.03, "{c:?} b {b}: {got}");
}
}
#[test]
fn a_gop_cut_short_gives_its_budget_back() {
let mut rc = RateCtl::new(4e6, 25.0, (1.0, 112.0));
for _ in 0..20 {
// a GOP of 12 that ends after its I picture and two P pictures
rc.start_gop(11, 0);
for t in [PictureType::I, PictureType::P, PictureType::P] {
let q = rc.qscale(t);
rc.update(t, (1e7 / q) as u64, q);
}
rc.end_gop(9);
}
// what is left is the three pictures' rounding, not nine pictures' budget per GOP
assert!(rc.remaining.abs() < 3.0 * 4e6 / 25.0, "{}", rc.remaining);
}
#[test]
fn the_quantiser_stays_in_range() {
let mut rc = RateCtl::new(1e6, 25.0, (2.0, 62.0));
rc.start_gop(2);
rc.start_gop(1, 0);
// a picture far larger than its budget pushes the next quantiser to the top
rc.update(true, 50_000_000, 10.0);
rc.start_gop(2);
assert_eq!(rc.qscale(true), 62.0);
rc.update(PictureType::I, 50_000_000, 10.0);
rc.start_gop(1, 0);
assert_eq!(rc.qscale(PictureType::I), 62.0);
// and a tiny one to the bottom
let mut rc = RateCtl::new(1e6, 25.0, (2.0, 62.0));
rc.start_gop(2);
rc.update(true, 10, 2.0);
assert_eq!(rc.qscale(true), 2.0);
rc.start_gop(1, 0);
rc.update(PictureType::I, 10, 2.0);
assert_eq!(rc.qscale(PictureType::I), 2.0);
}
}
+23 -4
View File
@@ -4,7 +4,7 @@
use std::sync::OnceLock;
use crate::mpeg2::vlc::{
CBP, DC_CHROMA, DC_LUMA, DCT_EOB, DCT_ESCAPE, DCT_ONE, DCT_ZERO, DCT_ZERO_LONG, MBA, MBA_ESCAPE, MBTYPE_I, MBTYPE_P, MOTION, dct_table,
CBP, DC_CHROMA, DC_LUMA, DCT_EOB, DCT_ESCAPE, DCT_ONE, DCT_ZERO, DCT_ZERO_LONG, MBA, MBA_ESCAPE, MBTYPE_B, MBTYPE_I, MBTYPE_P, MOTION, dct_table,
parse_code,
};
@@ -38,9 +38,10 @@ pub(crate) struct EncTables {
/// macroblock_address_increment 1..=33 (index 0 unused) and the escape.
pub mba: [Code; 34],
pub mba_escape: Code,
/// macroblock_type by flags: I pictures, P pictures (index: flags, 0..32).
/// macroblock_type by flags: I, P and B pictures (index: flags, 0..32).
pub mbtype_i: [Option<Code>; 32],
pub mbtype_p: [Option<Code>; 32],
pub mbtype_b: [Option<Code>; 32],
/// coded_block_pattern_420 (the first six blocks).
pub cbp: [Code; 64],
/// motion_code -16..=16 at index code + 16.
@@ -105,6 +106,7 @@ pub(crate) fn enc_tables() -> &'static EncTables {
mba_escape,
mbtype_i: mb_types(MBTYPE_I),
mbtype_p: mb_types(MBTYPE_P),
mbtype_b: mb_types(MBTYPE_B),
cbp: by_value(CBP, 0),
motion: by_value(MOTION, 16),
dc_luma: by_value(DC_LUMA, 0),
@@ -185,11 +187,25 @@ mod tests {
use super::*;
use crate::mpeg2::bits::Bits;
use crate::mpeg2::slice::wrap_vector;
use crate::mpeg2::vlc::{MB_FWD, MB_INTRA, MB_PATTERN, MB_QUANT, rl, tables};
use crate::mpeg2::vlc::{MB_BWD, MB_FWD, MB_INTRA, MB_PATTERN, MB_QUANT, rl, tables};
/// Macroblock types the encoder sends (frame pictures, frame prediction, no B pictures).
/// Macroblock types the encoder sends in P pictures (frame pictures, frame prediction).
const ENC_MB_TYPES: [i16; 7] =
[MB_INTRA, MB_INTRA | MB_QUANT, MB_FWD | MB_PATTERN, MB_PATTERN, MB_FWD, MB_QUANT | MB_FWD | MB_PATTERN, MB_QUANT | MB_PATTERN];
/// And in B pictures: every combination of directions, with and without a residual.
const ENC_MB_TYPES_B: [i16; 11] = [
MB_INTRA,
MB_INTRA | MB_QUANT,
MB_FWD,
MB_BWD,
MB_FWD | MB_BWD,
MB_FWD | MB_PATTERN,
MB_BWD | MB_PATTERN,
MB_FWD | MB_BWD | MB_PATTERN,
MB_QUANT | MB_FWD | MB_PATTERN,
MB_QUANT | MB_BWD | MB_PATTERN,
MB_QUANT | MB_FWD | MB_BWD | MB_PATTERN,
];
#[test]
fn every_code_decodes_to_its_value() {
@@ -223,6 +239,9 @@ mod tests {
}
check(t.mbtype_p[f as usize].unwrap_or_default(), &d.mbtype[1], f);
}
for f in ENC_MB_TYPES_B {
check(t.mbtype_b[f as usize].unwrap_or_default(), &d.mbtype[2], f);
}
for (k, vlc) in [&d.dct_zero, &d.dct_one].into_iter().enumerate() {
for run in 0..=MAX_RUN {
for level in 1..=MAX_LEVEL {
+218 -11
View File
@@ -3,7 +3,7 @@
//! comparison is in `tests/mpeg2/encode.rs`.
use super::*;
use crate::mpeg2::{Decoder, access_units, probe};
use crate::mpeg2::{Decoder, probe};
/// A moving, textured test sequence: a gradient with a sharp pattern drifting by a fraction of a
/// sample per picture, and a block moving across it.
@@ -54,16 +54,21 @@ fn encode(cfg: EncoderConfig, frames: usize) -> (Vec<u8>, Vec<ReconFrame>, Vec<P
packets.push(p);
}
}
packets.extend(enc.flush());
for p in enc.flush() {
es.extend_from_slice(&p.data);
packets.push(p);
}
es.extend_from_slice(enc.end_of_sequence());
(es, enc.take_recon(), packets)
}
fn decode(es: &[u8]) -> Vec<crate::mpeg2::Picture> {
/// Decode packets (each tagged with its presentation time); returns the pictures in display
/// order.
fn decode(packets: &[Packet]) -> Vec<crate::mpeg2::Picture> {
let mut d = Decoder::new();
let mut out = Vec::new();
for (i, r) in access_units(es).into_iter().enumerate() {
out.extend(d.decode(&es[r], i as i64).unwrap());
for p in packets {
out.extend(d.decode(&p.data, p.pts).unwrap());
}
out.extend(d.flush());
assert_eq!(d.errors(), 0, "decoder errors: {:?}", d.last_error());
@@ -71,9 +76,11 @@ fn decode(es: &[u8]) -> Vec<crate::mpeg2::Picture> {
}
fn assert_decodes_to_recon(name: &str, cfg: EncoderConfig, frames: usize) -> Vec<Packet> {
let (es, recon, packets) = encode(cfg, frames);
let pics = decode(&es);
let (_, recon, packets) = encode(cfg, frames);
assert!(packets.windows(2).all(|w| w[0].dts < w[1].dts) && packets.iter().all(|p| p.dts <= p.pts), "{name}: decoding times");
let pics = decode(&packets);
assert_eq!(pics.len(), frames, "{name}: picture count");
assert_eq!(recon.len(), frames, "{name}: reconstruction count");
for (i, (p, r)) in pics.iter().zip(&recon).enumerate() {
assert_eq!(p.pts, i as i64, "{name}: display order");
for (plane, (a, b)) in [("Y", (&p.y, &r.y)), ("Cb", (&p.cb, &r.cb)), ("Cr", (&p.cr, &r.cr))] {
@@ -101,6 +108,7 @@ fn intra_only_decodes_to_the_reconstruction() {
fn long_p_gop_does_not_drift() {
let mut cfg = EncoderConfig::new(96, 64, 25, 1);
cfg.gop_size = 30;
cfg.b_pictures = 0;
let packets = assert_decodes_to_recon("long gop", cfg, 30);
assert_eq!(packets.iter().filter(|p| p.keyframe).count(), 1);
assert!(packets[1..].iter().all(|p| p.picture_type == PictureType::P));
@@ -127,7 +135,201 @@ fn every_coding_option_decodes_to_the_reconstruction() {
("422 odd size", EncoderConfig { width: 70, height: 30, chroma: ChromaFormat::Yuv422, ..base.clone() }),
];
for (name, cfg) in cases {
assert_decodes_to_recon(name, cfg, 8);
assert_decodes_to_recon(name, cfg.clone(), 8);
assert_decodes_to_recon(name, EncoderConfig { b_pictures: 0, ..cfg }, 8);
}
}
#[test]
fn b_pictures_decode_to_the_reconstruction() {
let base = EncoderConfig::new(96, 64, 25, 1);
for b in 1..=4 {
for closed in [true, false] {
for (gop, frames) in [(12, 30), (7, 17), (2, 6), (1, 4), (15, 16)] {
let name = format!("b {b} closed {closed} gop {gop} frames {frames}");
let cfg = EncoderConfig { b_pictures: b, closed_gop: closed, gop_size: gop, ..base.clone() };
let packets = assert_decodes_to_recon(&name, cfg, frames);
if gop > 1 {
assert!(packets.iter().any(|p| p.picture_type == PictureType::B), "{name}: no B pictures");
}
}
}
}
let cases = [
("422", EncoderConfig { chroma: ChromaFormat::Yuv422, ..base.clone() }),
("abr", EncoderConfig { rate: RateControl::Abr { kbps: 400 }, ..base.clone() }),
("odd size", EncoderConfig { width: 50, height: 34, ..base.clone() }),
("small range", EncoderConfig { search_range: 2, ..base.clone() }),
("linear coarse", EncoderConfig { nonlinear_quant: false, rate: RateControl::Quantiser(25), ..base.clone() }),
];
for (name, cfg) in cases {
assert_decodes_to_recon(name, cfg, 14);
}
}
#[test]
fn pictures_are_reordered_into_decoding_order() {
let cfg = EncoderConfig { gop_size: 12, b_pictures: 2, ..EncoderConfig::new(64, 48, 25, 1) };
let (_, _, packets) = encode(cfg, 15);
let order: Vec<(PictureType, i64)> = packets.iter().map(|p| (p.picture_type, p.pts)).collect();
use PictureType::{B, I, P};
#[rustfmt::skip]
let want = [(I, 0), (P, 3), (B, 1), (B, 2), (P, 6), (B, 4), (B, 5), (P, 9), (B, 7), (B, 8),
// B10 and B11 lead the second GOP; at the end the last held picture becomes a P picture
(I, 12), (B, 10), (B, 11), (P, 14), (B, 13)];
assert_eq!(order, want);
// decoding times: the presentation times in order, one interval early
let dts: Vec<i64> = packets.iter().map(|p| p.dts).collect();
assert_eq!(dts, (-1..14).collect::<Vec<_>>());
// temporal_reference counts display order from each GOP's first picture
let pics = decode(&packets);
let tr: Vec<u16> = pics.iter().map(|p| p.temporal_reference).collect();
assert_eq!(tr, [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 0, 1, 2, 3, 4]);
}
#[test]
fn a_closed_gop_decodes_on_its_own() {
for closed in [true, false] {
let cfg = EncoderConfig { gop_size: 6, b_pictures: 2, closed_gop: closed, ..EncoderConfig::new(64, 48, 25, 1) };
let (_, recon, packets) = encode(cfg, 12);
// start decoding at the second GOP's I picture (display 6): B4 and B5 lead it
let at = packets.iter().position(|p| p.pts == 6).unwrap();
assert!(packets[at].keyframe);
let mut d = Decoder::new();
let mut pics = Vec::new();
for p in &packets[at..] {
pics.extend(d.decode(&p.data, p.pts).unwrap());
}
pics.extend(d.flush());
let shown: Vec<i64> = pics.iter().map(|p| p.pts).collect();
if closed {
assert_eq!(shown, (4..12).collect::<Vec<_>>());
for p in &pics {
assert_eq!(p.y, recon[p.pts as usize].y, "closed GOP: picture {}", p.pts);
}
} else {
// the leading B pictures need the previous GOP's last P picture
assert_eq!(shown, (6..12).collect::<Vec<_>>());
}
}
}
#[test]
fn b_pictures_are_smaller_than_p_pictures() {
let cfg = EncoderConfig { gop_size: 12, b_pictures: 2, ..EncoderConfig::new(128, 96, 25, 1) };
let (_, _, packets) = encode(cfg, 12);
let avg = |t: PictureType| {
let s: Vec<usize> = packets.iter().filter(|p| p.picture_type == t).map(|p| p.data.len()).collect();
s.iter().sum::<usize>() as f64 / s.len().max(1) as f64
};
let (p, b) = (avg(PictureType::P), avg(PictureType::B));
assert!(b * 1.5 < p, "P {p:.0} bytes, B {b:.0} bytes");
// static content: the B pictures skip every macroblock but the first and last of a slice
let mut enc = Encoder::new(EncoderConfig { gop_size: 12, b_pictures: 2, ..EncoderConfig::new(128, 64, 25, 1) }).unwrap();
let (y, cb, cr) = scene(128, 64, 64, 32, 0);
let f = YuvFrame { y: &y, cb: &cb, cr: &cr, y_stride: 128, c_stride: 64 };
let mut packets = Vec::new();
for t in 0..7 {
packets.extend(enc.encode(&f, t).unwrap());
}
let i = packets[0].data.len();
let bs: Vec<&Packet> = packets.iter().filter(|p| p.picture_type == PictureType::B).collect();
assert_eq!(bs.len(), 4);
for p in bs {
// a picture header, four slice headers and eight edge macroblocks
assert!(p.data.len() < 64, "static B picture {} of {} bytes (I {i})", p.pts, p.data.len());
}
}
#[test]
fn presentation_times_must_step_evenly_with_b_pictures() {
let mut enc = Encoder::new(EncoderConfig::new(32, 32, 25, 1)).unwrap();
let (y, c) = (vec![0u8; 32 * 32], vec![0u8; 16 * 16]);
let f = YuvFrame { y: &y, cb: &c, cr: &c, y_stride: 32, c_stride: 16 };
// the I picture waits for the second time, which sets the step
assert!(enc.encode(&f, 10).unwrap().is_empty());
let mut packets = enc.encode(&f, 12).unwrap();
for bad in [12, 11, 15] {
assert!(matches!(enc.encode(&f, bad), Err(EncodeError::BadTimestamp(_))), "{bad}");
}
packets.extend(enc.encode(&f, 14).unwrap());
packets.extend(enc.flush());
assert_eq!(packets.iter().map(|p| (p.pts, p.dts)).collect::<Vec<_>>(), [(10, 8), (14, 10), (12, 12)]);
// without B pictures any increasing (or not) times pass through
let mut enc = Encoder::new(EncoderConfig { b_pictures: 0, ..EncoderConfig::new(32, 32, 25, 1) }).unwrap();
for pts in [5, 3, 9] {
let p = enc.encode(&f, pts).unwrap().remove(0);
assert_eq!((p.pts, p.dts), (pts, pts));
}
}
#[test]
fn decoding_times_increase_after_a_lone_picture_is_flushed() {
let mut enc = Encoder::new(EncoderConfig::new(32, 32, 25, 1)).unwrap();
let (y, c) = (vec![0u8; 32 * 32], vec![0u8; 16 * 16]);
let f = YuvFrame { y: &y, cb: &c, cr: &c, y_stride: 32, c_stride: 16 };
// one picture, flushed before a second sets the step: it decodes one unit early
assert!(enc.encode(&f, 100).unwrap().is_empty());
let mut packets = enc.flush();
assert_eq!(packets.iter().map(|p| (p.pts, p.dts)).collect::<Vec<_>>(), [(100, 99)]);
// encoding goes on: the next picture decodes at the first one's presentation time
for pts in [105, 110] {
packets.extend(enc.encode(&f, pts).unwrap());
}
packets.extend(enc.flush());
assert_eq!(packets.iter().map(|p| (p.pts, p.dts)).collect::<Vec<_>>(), [(100, 99), (105, 100), (110, 105)]);
assert!(packets[1].keyframe);
}
#[test]
fn presentation_times_without_a_decoding_time_are_refused() {
let (y, c) = (vec![0u8; 32 * 32], vec![0u8; 16 * 16]);
let f = YuvFrame { y: &y, cb: &c, cr: &c, y_stride: 32, c_stride: 16 };
// the decoding times are one step earlier: they must fit in an i64
for (first, second) in [(i64::MIN + 1, i64::MIN + 3), (i64::MIN + 5, i64::MIN + 20)] {
let mut enc = Encoder::new(EncoderConfig::new(32, 32, 25, 1)).unwrap();
assert!(matches!(enc.encode(&f, i64::MIN), Err(EncodeError::BadTimestamp(_))));
assert!(enc.encode(&f, first).unwrap().is_empty());
assert!(matches!(enc.encode(&f, second), Err(EncodeError::BadTimestamp(_))), "{second} after {first}");
// a refused time leaves the encoder usable
assert_eq!(enc.flush().iter().map(|p| (p.pts, p.dts)).collect::<Vec<_>>(), [(first, first - 1)]);
}
// the lowest times that have one
let mut enc = Encoder::new(EncoderConfig::new(32, 32, 25, 1)).unwrap();
let mut packets = enc.encode(&f, i64::MIN + 1).unwrap();
packets.extend(enc.encode(&f, i64::MIN + 2).unwrap());
packets.extend(enc.flush());
assert_eq!(packets.iter().map(|p| p.dts).collect::<Vec<_>>(), [i64::MIN, i64::MIN + 1]);
// without B pictures every time passes through
let mut enc = Encoder::new(EncoderConfig { b_pictures: 0, ..EncoderConfig::new(32, 32, 25, 1) }).unwrap();
assert_eq!(enc.encode(&f, i64::MIN).unwrap()[0].dts, i64::MIN);
}
/// Average bitrate (bit/s) of the scene coded in groups of `group` pictures, flushed after each.
fn flushed_bitrate(cfg: EncoderConfig, group: usize, groups: usize) -> f64 {
let (w, h) = (cfg.width as usize, cfg.height as usize);
let fps = f64::from(cfg.fps_num) / f64::from(cfg.fps_den);
let mut enc = Encoder::new(cfg).unwrap();
let mut bytes = 0;
for t in 0..group * groups {
let (y, cb, cr) = scene(w, h, w / 2, h / 2, t);
let f = YuvFrame { y: &y, cb: &cb, cr: &cr, y_stride: w, c_stride: w / 2 };
bytes += enc.encode(&f, t as i64).unwrap().iter().map(|p| p.data.len()).sum::<usize>();
if (t + 1) % group == 0 {
bytes += enc.flush().iter().map(|p| p.data.len()).sum::<usize>();
}
}
bytes as f64 * 8.0 * fps / (group * groups) as f64
}
#[test]
fn flushing_short_gops_keeps_the_average_bitrate() {
// every flush ends a GOP of 12 after 4 pictures: the 8 that never came must not leave their
// bits to the next GOP
for b in [0, 2] {
let cfg = EncoderConfig { gop_size: 12, b_pictures: b, rate: RateControl::Abr { kbps: 600 }, ..EncoderConfig::new(176, 144, 25, 1) };
let got = flushed_bitrate(cfg, 4, 15);
assert!((got / 600e3 - 1.0).abs() < 0.15, "b {b}: {got:.0} bit/s for 600000");
}
}
@@ -161,7 +363,7 @@ fn quality_follows_the_quantiser() {
#[test]
fn p_pictures_are_smaller_and_static_content_skips() {
let cfg = EncoderConfig { gop_size: 8, ..EncoderConfig::new(128, 64, 25, 1) };
let cfg = EncoderConfig { gop_size: 8, b_pictures: 0, ..EncoderConfig::new(128, 64, 25, 1) };
let mut enc = Encoder::new(cfg).unwrap();
let (y, cb, cr) = scene(128, 64, 64, 32, 0);
let f = YuvFrame { y: &y, cb: &cb, cr: &cr, y_stride: 128, c_stride: 64 };
@@ -191,7 +393,7 @@ fn the_sequence_header_describes_the_stream() {
let enc = Encoder::new(cfg).unwrap();
assert_eq!(enc.profile_and_level(), pli, "{name}");
let info = probe(enc.sequence_header()).unwrap();
assert_eq!((info.width, info.height, info.mpeg2, info.progressive_sequence, info.low_delay), (w, h, true, true, true));
assert_eq!((info.width, info.height, info.mpeg2, info.progressive_sequence, info.low_delay), (w, h, true, true, false));
assert_eq!(info.codec_name(), format!("MPEG-2 Video ({name})"));
assert_eq!(aspect, AspectRatio::Square);
assert_eq!(info.sar, (1, 1));
@@ -199,6 +401,9 @@ fn the_sequence_header_describes_the_stream() {
let enc = Encoder::new(EncoderConfig { aspect: AspectRatio::Dar16x9, ..EncoderConfig::new(720, 576, 30000, 1001) }).unwrap();
let info = probe(enc.sequence_header()).unwrap();
assert_eq!((info.dar, info.frame_rate), (Some((16, 9)), Some((30000, 1001))));
// without B pictures the stream is low delay
let enc = Encoder::new(EncoderConfig { b_pictures: 0, ..EncoderConfig::new(720, 576, 25, 1) }).unwrap();
assert!(probe(enc.sequence_header()).unwrap().low_delay);
}
#[test]
@@ -214,6 +419,8 @@ fn bad_configurations_are_refused() {
EncoderConfig { fps_den: 0, ..ok.clone() },
EncoderConfig { gop_size: 0, ..ok.clone() },
EncoderConfig { gop_size: 1024, ..ok.clone() },
EncoderConfig { b_pictures: 5, ..ok.clone() },
EncoderConfig { gop_size: 1023, b_pictures: 2, ..ok.clone() },
EncoderConfig { rate: RateControl::Quantiser(0), ..ok.clone() },
EncoderConfig { rate: RateControl::Quantiser(32), ..ok.clone() },
EncoderConfig { rate: RateControl::Abr { kbps: 0 }, ..ok.clone() },
@@ -231,7 +438,7 @@ fn bad_configurations_are_refused() {
#[test]
fn short_or_inconsistent_planes_are_refused() {
let mut enc = Encoder::new(EncoderConfig::new(32, 32, 25, 1)).unwrap();
let mut enc = Encoder::new(EncoderConfig { b_pictures: 0, ..EncoderConfig::new(32, 32, 25, 1) }).unwrap();
let (y, c) = (vec![0u8; 32 * 32], vec![0u8; 16 * 16]);
let ok = YuvFrame { y: &y, cb: &c, cr: &c, y_stride: 32, c_stride: 16 };
assert!(enc.encode(&ok, 0).is_ok());
+1 -1
View File
@@ -1,5 +1,5 @@
//! Clean-room MPEG-2 video (ITU-T H.262 | ISO/IEC 13818-2) and MPEG-1 video (ISO/IEC 11172-2)
//! decoder, and the start of an MPEG-2 encoder ([`encode`], feature `mpeg2-encode`: I and P
//! decoder, and the start of an MPEG-2 encoder ([`encode`], feature `mpeg2-encode`: I, P and B
//! pictures).
//!
//! - Main Profile at Low/Main/High-1440/High Level, 4:2:2 Profile (XDCAM HD422, IMX / D-10),
+42 -18
View File
@@ -6,7 +6,7 @@
use std::path::{Path, PathBuf};
use std::process::{Command, Stdio};
use craft_video::mpeg2::{ChromaFormat, Encoder, EncoderConfig, RateControl, ReconFrame, YuvFrame};
use craft_video::mpeg2::{ChromaFormat, Encoder, EncoderConfig, Packet, RateControl, ReconFrame, YuvFrame};
use crate::common::{Stats, fixture_dir, pix_fmt_of};
use crate::oracle::{MAX_DIFFERING, MIN_PSNR, TOL_MAX};
@@ -39,24 +39,22 @@ fn sizes(cfg: &EncoderConfig) -> (usize, usize, usize) {
(w * h, w / 2 * ch, w / 2)
}
/// Encode `raw` frames; returns the elementary stream and the reconstruction.
fn encode(cfg: &EncoderConfig, raw: &[u8]) -> (Vec<u8>, Vec<ReconFrame>) {
/// Encode `raw` frames; returns the elementary stream, the reconstruction (display order) and
/// the packets (decoding order).
fn encode(cfg: &EncoderConfig, raw: &[u8]) -> (Vec<u8>, Vec<ReconFrame>, Vec<Packet>) {
let (ys, cs, cw) = sizes(cfg);
let fsize = ys + 2 * cs;
let mut enc = Encoder::new(cfg.clone()).expect("config");
enc.set_recon_capture(true);
let mut es = Vec::new();
let mut packets = Vec::new();
for (i, f) in raw.chunks_exact(fsize).enumerate() {
let frame = YuvFrame { y: &f[..ys], cb: &f[ys..ys + cs], cr: &f[ys + cs..], y_stride: cfg.width as usize, c_stride: cw };
for p in enc.encode(&frame, i as i64).expect("encode") {
es.extend_from_slice(&p.data);
}
}
for p in enc.flush() {
es.extend_from_slice(&p.data);
packets.extend(enc.encode(&frame, i as i64).expect("encode"));
}
packets.extend(enc.flush());
let mut es: Vec<u8> = packets.iter().flat_map(|p| p.data.iter().copied()).collect();
es.extend_from_slice(enc.end_of_sequence());
(es, enc.take_recon())
(es, enc.take_recon(), packets)
}
/// ffmpeg's decode of `file`, failing on any decoding error.
@@ -121,10 +119,11 @@ fn check(ff: &Path, c: &Case) -> (Vec<u8>, f64) {
let raw = source(ff, c.cfg.width, c.cfg.height, c.frames, pix_fmt);
let (ys, cs, _) = sizes(&c.cfg);
let fsize = ys + 2 * cs;
let (es, recon) = encode(&c.cfg, &raw);
let (es, recon, packets) = encode(&c.cfg, &raw);
let path = write(c.name, &es);
let decoded = ffmpeg_decode(ff, &path, pix_fmt);
assert_eq!(decoded.len(), c.frames * fsize, "{}: ffmpeg's frame count", c.name);
assert_eq!(recon.len(), c.frames, "{}: reconstruction count", c.name);
let mut all = Stats::default();
for (i, (r, f)) in recon.iter().zip(decoded.chunks_exact(fsize)).enumerate() {
let mut s = Stats::default();
@@ -139,15 +138,21 @@ fn check(ff: &Path, c: &Case) -> (Vec<u8>, f64) {
assert!(quality >= c.min_psnr, "{}: luma PSNR {quality:.2} dB against the source", c.name);
if let Some((stream, types)) = ffprobe(&path) {
assert_eq!(stream, c.probe, "{}: ffprobe", c.name);
let gop = c.cfg.gop_size as usize;
let want: Vec<&str> = (0..c.frames).map(|i| if i % gop == 0 { "I" } else { "P" }).collect();
// ffprobe lists the pictures in display order
let mut shown: Vec<&Packet> = packets.iter().collect();
shown.sort_by_key(|p| p.pts);
let want: Vec<String> = shown.iter().map(|p| format!("{:?}", p.picture_type)).collect();
assert_eq!(types, want, "{}: picture types", c.name);
}
let count = |t: &str| packets.iter().filter(|p| format!("{:?}", p.picture_type) == t).count();
let kbps = es.len() as f64 * 8.0 * 25.0 / c.frames as f64 / 1000.0;
println!(
"{}: {} frames, {kbps:.0} kbit/s, luma PSNR {quality:.2} dB, max diff to ffmpeg {}, {:.3}% differ",
"{}: {} frames ({} I, {} P, {} B), {kbps:.0} kbit/s, luma PSNR {quality:.2} dB, max diff to ffmpeg {}, {:.3}% differ",
c.name,
c.frames,
count("I"),
count("P"),
count("B"),
all.max,
100.0 * all.diff as f64 / all.n as f64
);
@@ -160,6 +165,21 @@ fn ffmpeg_decodes_our_streams() {
let cif = EncoderConfig { gop_size: 12, ..EncoderConfig::new(352, 288, 25, 1) };
let cases = [
Case { name: "cif_q4", cfg: cif.clone(), frames: 25, probe: "mpeg2video,Main,10,yuv420p", min_psnr: 36.0 },
Case { name: "cif_ip", cfg: EncoderConfig { b_pictures: 0, ..cif.clone() }, frames: 25, probe: "mpeg2video,Main,10,yuv420p", min_psnr: 36.0 },
Case {
name: "cif_open_gop",
cfg: EncoderConfig { closed_gop: false, gop_size: 15, ..cif.clone() },
frames: 31,
probe: "mpeg2video,Main,10,yuv420p",
min_psnr: 35.0,
},
Case {
name: "cif_b4",
cfg: EncoderConfig { b_pictures: 4, gop_size: 10, ..cif.clone() },
frames: 23,
probe: "mpeg2video,Main,10,yuv420p",
min_psnr: 34.0,
},
Case {
name: "cif_intra",
cfg: EncoderConfig { gop_size: 1, rate: RateControl::Quantiser(8), ..cif.clone() },
@@ -191,10 +211,14 @@ fn ffmpeg_decodes_our_streams() {
#[test]
fn average_bitrate_reaches_its_target() {
let Some(ff) = craft_media_testkit::ffmpeg_or_skip("mpeg2 encoder bitrate") else { return };
for kbps in [800u32, 2500] {
for (kbps, b) in [(800u32, 2), (2500, 2), (800, 0)] {
let c = Case {
name: if kbps == 800 { "cif_abr_800" } else { "cif_abr_2500" },
cfg: EncoderConfig { rate: RateControl::Abr { kbps }, gop_size: 12, ..EncoderConfig::new(352, 288, 25, 1) },
name: match (kbps, b) {
(800, 0) => "cif_abr_800_ip",
(800, _) => "cif_abr_800",
_ => "cif_abr_2500",
},
cfg: EncoderConfig { rate: RateControl::Abr { kbps }, gop_size: 12, b_pictures: b, ..EncoderConfig::new(352, 288, 25, 1) },
frames: 72,
probe: "mpeg2video,Main,10,yuv420p",
min_psnr: 26.0,
+4
View File
@@ -27,6 +27,10 @@ use std::collections::HashMap;
pub mod document;
/// XFL's edge-attribute grammar, independent of any consuming application's geometry types.
pub mod edges;
/// Borrowed views of native XFL media library records.
pub mod media;
/// Borrowed views of native XFL shape and style elements.
pub mod shape;
/// Largest single entry inflated (bytes).
pub const MAX_ENTRY: usize = 256 * 1024 * 1024;
+190
View File
@@ -0,0 +1,190 @@
//! Borrowed views of XFL's bitmap, sound, and video library-item records.
//!
//! These views expose native XFL metadata and archive member names. Decoding those bytes and
//! mapping the records into an application's media model remain consumer responsibilities.
use crate::shape::XflElement;
/// Archive member named by a library item's native `href` attribute.
pub fn library_member(href: &str) -> String {
format!("LIBRARY/{href}")
}
/// Archive member named by an XFL item's native `*DataHRef` attribute.
pub fn data_member(href: &str) -> String {
format!("bin/{href}")
}
/// A packaged `./...` external video source, normalized to ZIP's slash separators.
pub fn packaged_external_member(path: &str) -> Option<String> {
path.strip_prefix("./").map(|path| path.replace('\\', "/"))
}
/// Media library records in an XFL document, in source order.
#[derive(Clone, Copy, Debug)]
pub struct Catalog<'a, E: XflElement> {
media: Option<&'a E>,
}
impl<'a, E: XflElement> Catalog<'a, E> {
pub fn new(document: &'a E) -> Self {
Self { media: document.child("media") }
}
pub fn bitmaps(&self) -> impl Iterator<Item = Bitmap<'a, E>> + 'a {
let media = self.media;
media.into_iter().flat_map(|media| media.elements_named("DOMBitmapItem")).map(|element| Bitmap { element })
}
pub fn sounds(&self) -> impl Iterator<Item = Sound<'a, E>> + 'a {
let media = self.media;
media.into_iter().flat_map(|media| media.elements_named("DOMSoundItem")).map(|element| Sound { element })
}
pub fn videos(&self) -> impl Iterator<Item = Video<'a, E>> + 'a {
let media = self.media;
media.into_iter().flat_map(|media| media.elements_named("DOMVideoItem")).map(|element| Video { element })
}
}
/// Native bitmap library metadata.
#[derive(Clone, Copy, Debug)]
pub struct Bitmap<'a, E: XflElement> {
element: &'a E,
}
impl<'a, E: XflElement> Bitmap<'a, E> {
pub fn name(&self) -> Option<&'a str> {
self.element.attr("name")
}
pub fn href(&self) -> Option<&'a str> {
self.element.attr("href")
}
pub fn data_href(&self) -> Option<&'a str> {
self.element.attr("bitmapDataHRef")
}
pub fn allow_smoothing(&self) -> Option<bool> {
self.element.attr("allowSmoothing").map(|value| value.trim() == "true")
}
}
/// Native sound library metadata.
#[derive(Clone, Copy, Debug)]
pub struct Sound<'a, E: XflElement> {
element: &'a E,
}
impl<'a, E: XflElement> Sound<'a, E> {
pub fn name(&self) -> Option<&'a str> {
self.element.attr("name")
}
pub fn href(&self) -> Option<&'a str> {
self.element.attr("href")
}
pub fn data_href(&self) -> Option<&'a str> {
self.element.attr("soundDataHRef")
}
}
/// Native video library metadata.
#[derive(Clone, Copy, Debug)]
pub struct Video<'a, E: XflElement> {
element: &'a E,
}
impl<'a, E: XflElement> Video<'a, E> {
pub fn name(&self) -> Option<&'a str> {
self.element.attr("name")
}
pub fn href(&self) -> Option<&'a str> {
self.element.attr("href")
}
pub fn external_path(&self) -> Option<&'a str> {
self.element.attr("sourceExternalFilepath")
}
pub fn data_href(&self) -> Option<&'a str> {
self.element.attr("videoDataHRef")
}
pub fn length(&self) -> Option<f32> {
number(self.element, "length")
}
pub fn frame_count(&self) -> Option<f32> {
number(self.element, "frameCount")
}
pub fn frames_per_second(&self) -> Option<f32> {
number(self.element, "fps")
}
}
fn number(element: &impl XflElement, name: &str) -> Option<f32> {
element.attr(name)?.trim().parse::<f32>().ok().filter(|value| value.is_finite())
}
#[cfg(test)]
mod tests {
use super::*;
fn parse(source: &[u8]) -> craft_xml::El {
craft_xml::Options::default().parse(source).unwrap()
}
#[test]
fn reads_native_media_metadata_in_order_and_ignores_other_records() {
let root = parse(
br#"<DOMDocument><media>
<DOMBitmapItem name="folder/a" href="a.png" bitmapDataHRef="Bitmap 1" allowSmoothing="false"/>
<DOMSoundItem name="s" href="s.wav" soundDataHRef="Sound 1"/>
<DOMVideoItem name="v" sourceExternalFilepath="./LIBRARY/v.flv" videoDataHRef="Video 1" length="3.5" frameCount="70" fps="20"/>
<Other name="ignored"/>
<DOMBitmapItem name="b"/>
</media></DOMDocument>"#,
);
let catalog = Catalog::new(&root);
let bitmaps: Vec<_> = catalog.bitmaps().collect();
assert_eq!(bitmaps.len(), 2);
assert_eq!(bitmaps[0].name(), Some("folder/a"));
assert_eq!(bitmaps[0].href(), Some("a.png"));
assert_eq!(bitmaps[0].data_href(), Some("Bitmap 1"));
assert_eq!(bitmaps[0].allow_smoothing(), Some(false));
assert_eq!(
catalog.sounds().next().map(|item| (item.name(), item.href(), item.data_href())),
Some((Some("s"), Some("s.wav"), Some("Sound 1")))
);
let video = catalog.videos().next().expect("video record");
assert_eq!(video.external_path(), Some("./LIBRARY/v.flv"));
assert_eq!(video.data_href(), Some("Video 1"));
assert_eq!(video.length(), Some(3.5));
assert_eq!(video.frame_count(), Some(70.0));
assert_eq!(video.frames_per_second(), Some(20.0));
}
#[test]
fn missing_or_invalid_media_metadata_stays_optional() {
let root = parse(br#"<DOMDocument><media><DOMVideoItem name="v" length="NaN" fps="?"/></media></DOMDocument>"#);
let video = Catalog::new(&root).videos().next().expect("video record");
assert_eq!(video.name(), Some("v"));
assert_eq!(video.length(), None);
assert_eq!(video.frames_per_second(), None);
let empty = parse(b"<DOMDocument/>");
assert_eq!(Catalog::new(&empty).bitmaps().count(), 0);
}
#[test]
fn native_media_references_resolve_to_the_legacy_archive_members() {
assert_eq!(library_member("folder/a.png"), "LIBRARY/folder/a.png");
assert_eq!(data_member("Bitmap 1"), "bin/Bitmap 1");
assert_eq!(packaged_external_member("./LIBRARY\\v.flv").as_deref(), Some("LIBRARY/v.flv"));
assert_eq!(packaged_external_member("/outside/v.flv"), None);
}
}
+590
View File
@@ -0,0 +1,590 @@
//! Borrowed views of native XFL shape and style elements.
//!
//! These views recognize XFL's element names and attribute grammar without depending on an
//! application's geometry, paint, or animation types. They work with `craft_xml::El` and with
//! compatible borrowed element adapters implemented by consumers.
use crate::edges::{self, Segment};
/// An element source used by the borrowed XFL schema views.
///
/// Consumers with an existing XML facade can implement this small interface and use the same
/// XFL parser without converting or reparsing their tree. Attribute lookup must return the last
/// occurrence when an XML document repeats an attribute, matching the native XFL reader's
/// historical behavior.
pub trait XflElement {
/// Iterator type for direct child elements.
type Elements<'a>: Iterator<Item = &'a Self>
where
Self: 'a;
/// The element's local name, with any namespace prefix removed.
fn local_name(&self) -> &str;
/// The last attribute with this exact name.
fn attr(&self, name: &str) -> Option<&str>;
/// Direct child elements in document order.
fn elements(&self) -> Self::Elements<'_>;
/// The first direct child whose local name matches.
fn child(&self, name: &str) -> Option<&Self> {
self.elements().find(|element| element.local_name() == name)
}
/// Direct children whose local name matches, in document order.
fn elements_named<'a>(&'a self, name: &'a str) -> impl Iterator<Item = &'a Self> + 'a {
self.elements().filter(move |element| element.local_name() == name)
}
}
/// Direct child elements of `craft_xml::El`, used by its `XflElement` implementation.
pub struct XmlElements<'a> {
nodes: std::slice::Iter<'a, craft_xml::Node>,
}
impl<'a> Iterator for XmlElements<'a> {
type Item = &'a craft_xml::El;
fn next(&mut self) -> Option<Self::Item> {
self.nodes.find_map(|node| match node {
craft_xml::Node::El(element) => Some(element),
_ => None,
})
}
}
impl XflElement for craft_xml::El {
type Elements<'a> = XmlElements<'a>;
fn local_name(&self) -> &str {
self.name.rsplit(':').next().unwrap_or(&self.name)
}
fn attr(&self, name: &str) -> Option<&str> {
self.attrs.iter().rev().find(|(key, _)| key == name).map(|(_, value)| value.as_str())
}
fn elements(&self) -> Self::Elements<'_> {
XmlElements { nodes: self.children.iter() }
}
}
/// XFL matrix coefficients, in the native units stored in XML.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Matrix {
pub a: f32,
pub b: f32,
pub c: f32,
pub d: f32,
pub tx: f32,
pub ty: f32,
}
/// A color encoded by an XFL color attribute and its optional alpha attribute.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Color {
pub rgb: u32,
pub alpha: f32,
}
impl Matrix {
/// The matrix used when an XFL element omits its transform.
pub const IDENTITY: Matrix = Matrix { a: 1.0, b: 0.0, c: 0.0, d: 1.0, tx: 0.0, ty: 0.0 };
}
fn number(element: &impl XflElement, name: &str) -> Option<f32> {
element.attr(name)?.trim().parse::<f32>().ok().filter(|value| value.is_finite())
}
fn integer(element: &impl XflElement, name: &str) -> Option<u32> {
element.attr(name)?.trim().parse::<u32>().ok()
}
fn boolean(element: &impl XflElement, name: &str) -> Option<bool> {
element.attr(name).map(|value| value.trim() == "true")
}
/// Parses XFL's hexadecimal color and alpha attributes. Missing or malformed colors use black;
/// missing, malformed, or non-finite alpha uses full opacity, matching the legacy importer.
pub fn color(element: &impl XflElement, color_attribute: &str, alpha_attribute: &str) -> Color {
let rgb = element.attr(color_attribute).and_then(|value| u32::from_str_radix(value.trim().trim_start_matches('#'), 16).ok()).unwrap_or(0);
let alpha = number(element, alpha_attribute).unwrap_or(1.0).clamp(0.0, 1.0);
Color { rgb, alpha }
}
/// Reads the native `<matrix><Matrix .../></matrix>` transform.
///
/// Each absent, malformed, or non-finite coefficient uses its identity default independently.
/// This preserves the prior AniCraft reader's `Element::f32` behavior, including retaining other
/// valid coefficients when one coefficient is invalid.
pub fn matrix(element: &impl XflElement) -> Matrix {
let Some(matrix) = element.child("matrix").and_then(|wrapper| wrapper.child("Matrix")) else {
return Matrix::IDENTITY;
};
Matrix {
a: number(matrix, "a").unwrap_or(1.0),
b: number(matrix, "b").unwrap_or(0.0),
c: number(matrix, "c").unwrap_or(0.0),
d: number(matrix, "d").unwrap_or(1.0),
tx: number(matrix, "tx").unwrap_or(0.0),
ty: number(matrix, "ty").unwrap_or(0.0),
}
}
/// A native `DOMShape` or drawing shape and its XFL style tables.
#[derive(Clone, Copy, Debug)]
pub struct Shape<'a, E: XflElement> {
element: &'a E,
}
/// Kind of native drawable primitive stored in XFL.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum PrimitiveKind {
Rectangle,
Oval,
}
/// Native rectangle or oval object, including its native style definitions.
#[derive(Clone, Copy, Debug)]
pub struct Primitive<'a, E: XflElement> {
element: &'a E,
kind: PrimitiveKind,
}
impl<'a, E: XflElement> Primitive<'a, E> {
/// Views a supported native primitive by its local element name.
pub fn new(element: &'a E) -> Option<Self> {
let kind = match element.local_name() {
"DOMRectangleObject" => PrimitiveKind::Rectangle,
"DOMOvalObject" => PrimitiveKind::Oval,
_ => return None,
};
Some(Self { element, kind })
}
pub fn kind(&self) -> PrimitiveKind {
self.kind
}
pub fn x(&self) -> Option<f32> {
number(self.element, "x")
}
pub fn y(&self) -> Option<f32> {
number(self.element, "y")
}
pub fn width(&self) -> Option<f32> {
number(self.element, "objectWidth")
}
pub fn height(&self) -> Option<f32> {
number(self.element, "objectHeight")
}
pub fn top_left_radius(&self) -> Option<f32> {
number(self.element, "topLeftRadius")
}
pub fn matrix(&self) -> Matrix {
matrix(self.element)
}
pub fn fill(&self) -> Option<Fill<'_, E>> {
self.element.child("fill")?.elements().next().map(|element| Fill { element })
}
pub fn stroke(&self) -> Option<Stroke<'_, E>> {
self.element.child("stroke")?.elements().next().map(|element| Stroke { element })
}
}
impl<'a, E: XflElement> Shape<'a, E> {
/// Views an element as an XFL shape when its local name is `DOMShape`.
pub fn new(element: &'a E) -> Option<Self> {
(element.local_name() == "DOMShape").then_some(Self { element })
}
/// Native shape transform.
pub fn matrix(&self) -> Matrix {
matrix(self.element)
}
/// Whether Animate stores the shape as a drawing object.
pub fn is_drawing_object(&self) -> Option<bool> {
boolean(self.element, "isDrawingObject")
}
/// Fill styles, preserving their native order and index values.
pub fn fills(&self) -> impl Iterator<Item = FillStyle<'_, E>> + '_ {
self.element.child("fills").into_iter().flat_map(|table| table.elements()).map(|element| FillStyle { element })
}
/// Stroke styles, preserving their native order and index values.
pub fn strokes(&self) -> impl Iterator<Item = StrokeStyle<'_, E>> + '_ {
self.element.child("strokes").into_iter().flat_map(|table| table.elements()).map(|element| StrokeStyle { element })
}
/// Native edge records, preserving malformed and unknown data for consumer policy.
pub fn edges(&self) -> impl Iterator<Item = Edge<'_, E>> + '_ {
self.element.child("edges").into_iter().flat_map(|table| table.elements_named("Edge")).map(|element| Edge { element })
}
}
/// A native `FillStyle` entry.
#[derive(Clone, Copy, Debug)]
pub struct FillStyle<'a, E: XflElement> {
element: &'a E,
}
impl<'a, E: XflElement> FillStyle<'a, E> {
pub fn index(&self) -> Option<u32> {
integer(self.element, "index")
}
/// The first native definition element inside this table entry.
pub fn definition(&self) -> Option<Fill<'_, E>> {
self.element.elements().next().map(|element| Fill { element })
}
}
/// Native fill definitions understood by XFL.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum FillKind {
SolidColor,
LinearGradient,
RadialGradient,
Bitmap,
Other,
}
/// A native XFL fill definition.
#[derive(Clone, Copy, Debug)]
pub struct Fill<'a, E: XflElement> {
element: &'a E,
}
impl<'a, E: XflElement> Fill<'a, E> {
/// Views any native fill-definition element, including fills nested in primitives or strokes.
pub fn new(element: &'a E) -> Self {
Self { element }
}
/// Underlying native definition element for consumers that map it into application types.
pub fn element(&self) -> &'a E {
self.element
}
pub fn kind(&self) -> FillKind {
match self.element.local_name() {
"SolidColor" => FillKind::SolidColor,
"LinearGradient" => FillKind::LinearGradient,
"RadialGradient" => FillKind::RadialGradient,
"BitmapFill" => FillKind::Bitmap,
_ => FillKind::Other,
}
}
pub fn color(&self) -> Option<&str> {
self.element.attr("color")
}
pub fn color_value(&self) -> Color {
color(self.element, "color", "alpha")
}
pub fn alpha(&self) -> Option<f32> {
number(self.element, "alpha")
}
pub fn matrix(&self) -> Matrix {
matrix(self.element)
}
pub fn spread_method(&self) -> Option<&str> {
self.element.attr("spreadMethod")
}
pub fn interpolation_method(&self) -> Option<&str> {
self.element.attr("interpolationMethod")
}
pub fn focal_point_ratio(&self) -> Option<f32> {
number(self.element, "focalPointRatio")
}
pub fn bitmap_path(&self) -> Option<&str> {
self.element.attr("bitmapPath")
}
pub fn bitmap_is_clipped(&self) -> Option<bool> {
boolean(self.element, "bitmapIsClipped")
}
/// Gradient entries, preserving source order and raw native ratios.
pub fn gradient_entries(&self) -> impl Iterator<Item = GradientEntry<'_, E>> + '_ {
self.element.elements_named("GradientEntry").map(|element| GradientEntry { element })
}
}
/// A native gradient ramp entry.
#[derive(Clone, Copy, Debug)]
pub struct GradientEntry<'a, E: XflElement> {
element: &'a E,
}
impl<E: XflElement> GradientEntry<'_, E> {
pub fn ratio(&self) -> Option<f32> {
number(self.element, "ratio")
}
pub fn color(&self) -> Option<&str> {
self.element.attr("color")
}
pub fn color_value(&self) -> Color {
color(self.element, "color", "alpha")
}
pub fn alpha(&self) -> Option<f32> {
number(self.element, "alpha")
}
}
/// Native stroke definitions understood by XFL.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum StrokeKind {
Solid,
Dashed,
Dotted,
Ragged,
Stipple,
Hatched,
Other,
}
/// A native `StrokeStyle` table entry.
#[derive(Clone, Copy, Debug)]
pub struct StrokeStyle<'a, E: XflElement> {
element: &'a E,
}
impl<'a, E: XflElement> StrokeStyle<'a, E> {
pub fn index(&self) -> Option<u32> {
integer(self.element, "index")
}
/// The first native definition element inside this table entry.
pub fn definition(&self) -> Option<Stroke<'_, E>> {
self.element.elements().next().map(|element| Stroke { element })
}
}
/// A native XFL stroke definition.
#[derive(Clone, Copy, Debug)]
pub struct Stroke<'a, E: XflElement> {
element: &'a E,
}
impl<'a, E: XflElement> Stroke<'a, E> {
/// Views a native stroke-definition element.
pub fn new(element: &'a E) -> Self {
Self { element }
}
/// Underlying native definition element for consumers that map it into application types.
pub fn element(&self) -> &'a E {
self.element
}
pub fn kind(&self) -> StrokeKind {
match self.element.local_name() {
"SolidStroke" => StrokeKind::Solid,
"DashedStroke" => StrokeKind::Dashed,
"DottedStroke" => StrokeKind::Dotted,
"RaggedStroke" => StrokeKind::Ragged,
"StippleStroke" => StrokeKind::Stipple,
"HatchedStroke" => StrokeKind::Hatched,
_ => StrokeKind::Other,
}
}
pub fn weight(&self) -> Option<f32> {
number(self.element, "weight")
}
pub fn caps(&self) -> Option<&str> {
self.element.attr("caps")
}
pub fn joints(&self) -> Option<&str> {
self.element.attr("joints")
}
pub fn miter_limit(&self) -> Option<f32> {
number(self.element, "miterLimit")
}
pub fn dash1(&self) -> Option<f32> {
number(self.element, "dash1")
}
pub fn dash2(&self) -> Option<f32> {
number(self.element, "dash2")
}
pub fn dot_space(&self) -> Option<f32> {
number(self.element, "dotSpace")
}
/// The first fill definition nested in the stroke.
pub fn fill(&self) -> Option<Fill<'_, E>> {
self.element.child("fill")?.elements().next().map(|element| Fill { element })
}
}
/// A native `<Edge>` record and its style indices.
#[derive(Clone, Copy, Debug)]
pub struct Edge<'a, E: XflElement> {
element: &'a E,
}
impl<E: XflElement> Edge<'_, E> {
pub fn fill_style0(&self) -> Option<u32> {
integer(self.element, "fillStyle0")
}
pub fn fill_style1(&self) -> Option<u32> {
integer(self.element, "fillStyle1")
}
pub fn stroke_style(&self) -> Option<u32> {
integer(self.element, "strokeStyle")
}
pub fn encoded_segments(&self) -> Option<&str> {
self.element.attr("edges")
}
/// Parsed XFL path segments, using the shared bounded edge grammar.
pub fn segments(&self) -> Vec<Segment> {
self.encoded_segments().map(edges::parse_edge_segments).unwrap_or_default()
}
}
#[cfg(test)]
mod tests {
use super::*;
fn parse(source: &[u8]) -> craft_xml::El {
craft_xml::Options::default().parse(source).unwrap()
}
#[test]
fn reads_prefixed_shape_fill_stroke_and_edge_schema() {
let root = parse(br##"<x:DOMShape xmlns:x="urn:xfl" isDrawingObject="false">
<x:matrix><x:Matrix a="2" tx="12"/></x:matrix>
<x:fills><x:FillStyle index="1"><x:LinearGradient spreadMethod="reflect" interpolationMethod="linearRGB">
<x:GradientEntry ratio="0" color="#102030"/><x:GradientEntry ratio="255" color="#ffffff" alpha=".5"/>
</x:LinearGradient></x:FillStyle><x:FillStyle index="2"><x:BitmapFill bitmapPath="Library/a.png" bitmapIsClipped="true"/></x:FillStyle></x:fills>
<x:strokes><x:StrokeStyle index="3"><x:DashedStroke weight="2" dash1="8" dash2="3" caps="square" joints="miter" miterLimit="7"><x:fill><x:SolidColor color="#abcdef"/></x:fill></x:DashedStroke></x:StrokeStyle></x:strokes>
<x:edges><x:Edge fillStyle0="2" fillStyle1="1" strokeStyle="3" edges="!0 0|200 0"/></x:edges>
</x:DOMShape>"##);
let shape = Shape::new(&root).unwrap();
assert_eq!(shape.matrix(), Matrix { a: 2.0, b: 0.0, c: 0.0, d: 1.0, tx: 12.0, ty: 0.0 });
assert_eq!(shape.is_drawing_object(), Some(false));
let fills: Vec<_> = shape.fills().collect();
assert_eq!(fills.iter().map(FillStyle::index).collect::<Vec<_>>(), [Some(1), Some(2)]);
let gradient = fills[0].definition().unwrap();
assert_eq!(gradient.kind(), FillKind::LinearGradient);
assert_eq!(gradient.spread_method(), Some("reflect"));
assert_eq!(gradient.interpolation_method(), Some("linearRGB"));
assert_eq!(gradient.gradient_entries().map(|entry| entry.ratio()).collect::<Vec<_>>(), [Some(0.0), Some(255.0)]);
let bitmap = fills[1].definition().unwrap();
assert_eq!(bitmap.kind(), FillKind::Bitmap);
assert_eq!(bitmap.bitmap_path(), Some("Library/a.png"));
assert_eq!(bitmap.bitmap_is_clipped(), Some(true));
let stroke_style = shape.strokes().next().unwrap();
let stroke = stroke_style.definition().unwrap();
assert_eq!(stroke.kind(), StrokeKind::Dashed);
assert_eq!(stroke.weight(), Some(2.0));
assert_eq!((stroke.dash1(), stroke.dash2()), (Some(8.0), Some(3.0)));
assert_eq!(stroke.fill().unwrap().color(), Some("#abcdef"));
let color = stroke.fill().unwrap().color_value();
assert_eq!(color, Color { rgb: 0xabcdef, alpha: 1.0 });
let edge = shape.edges().next().unwrap();
assert_eq!((edge.fill_style0(), edge.fill_style1(), edge.stroke_style()), (Some(2), Some(1), Some(3)));
assert_eq!(edge.segments().len(), 1);
}
#[test]
fn duplicate_attributes_use_last_value_and_invalid_numbers_are_absent() {
let root = parse(b"<DOMShape isDrawingObject='false' isDrawingObject='true'><matrix><Matrix a='NaN' tx='12'/></matrix><fills><FillStyle index='1' index='4'><SolidColor alpha='Infinity'/></FillStyle></fills></DOMShape>");
let shape = Shape::new(&root).unwrap();
assert_eq!(shape.is_drawing_object(), Some(true));
assert_eq!(shape.matrix(), Matrix { tx: 12.0, ..Matrix::IDENTITY });
let fill = shape.fills().next().unwrap();
assert_eq!(fill.index(), Some(4));
let fill = fill.definition().unwrap();
assert_eq!(fill.alpha(), None);
assert_eq!(fill.color_value(), Color { rgb: 0, alpha: 1.0 });
}
#[test]
fn style_table_views_keep_the_legacy_first_child_and_index_behavior() {
let root = parse(b"<DOMShape><fills><LegacyFill index='5'><SolidColor color='#123456'/></LegacyFill></fills><strokes><LegacyStroke index='6'><SolidStroke weight='2'/></LegacyStroke></strokes></DOMShape>");
let shape = Shape::new(&root).unwrap();
let fill_style = shape.fills().next().unwrap();
assert_eq!(fill_style.index(), Some(5));
assert_eq!(fill_style.definition().map(|fill| fill.kind()), Some(FillKind::SolidColor));
let stroke_style = shape.strokes().next().unwrap();
assert_eq!(stroke_style.index(), Some(6));
assert_eq!(stroke_style.definition().map(|stroke| stroke.kind()), Some(StrokeKind::Solid));
}
#[test]
fn an_application_element_adapter_can_use_the_same_views() {
#[derive(Debug)]
struct AppElement {
name: String,
attrs: Vec<(String, String)>,
children: Vec<AppElement>,
}
impl XflElement for AppElement {
type Elements<'a> = std::slice::Iter<'a, AppElement>;
fn local_name(&self) -> &str {
self.name.rsplit(':').next().unwrap_or(&self.name)
}
fn attr(&self, name: &str) -> Option<&str> {
self.attrs.iter().rev().find(|(key, _)| key == name).map(|(_, value)| value.as_str())
}
fn elements(&self) -> Self::Elements<'_> {
self.children.iter()
}
}
let app = AppElement { name: "x:DOMShape".into(), attrs: vec![("isDrawingObject".into(), "true".into())], children: Vec::new() };
assert_eq!(Shape::new(&app).unwrap().is_drawing_object(), Some(true));
}
#[test]
fn reads_native_rectangle_and_oval_geometry_and_styles() {
let root = parse(br##"<DOMRectangleObject x="-2" y="3" objectWidth="20" objectHeight="10" topLeftRadius="4"><matrix><Matrix tx="7"/></matrix><fill><SolidColor color="#123456"/></fill><stroke><DashedStroke weight="2" dash1="5" dash2="3"/></stroke></DOMRectangleObject>"##);
let primitive = Primitive::new(&root).unwrap();
assert_eq!(primitive.kind(), PrimitiveKind::Rectangle);
assert_eq!(
(primitive.x(), primitive.y(), primitive.width(), primitive.height(), primitive.top_left_radius()),
(Some(-2.0), Some(3.0), Some(20.0), Some(10.0), Some(4.0))
);
assert_eq!(primitive.matrix().tx, 7.0);
assert_eq!(primitive.fill().unwrap().kind(), FillKind::SolidColor);
assert_eq!(primitive.stroke().unwrap().kind(), StrokeKind::Dashed);
let oval = parse(b"<DOMOvalObject objectWidth='10' objectHeight='8'/>");
assert_eq!(Primitive::new(&oval).unwrap().kind(), PrimitiveKind::Oval);
assert!(Primitive::new(&parse(b"<DOMShape/>")).is_none());
}
}