Merge remote-tracking branch 'origin/main' into codex/soundcraft-format

This commit is contained in:
Dylan M. Taylor
2026-11-13 09:12:20 +00:00
64 changed files with 3775 additions and 741 deletions
+6
View File
@@ -8,3 +8,9 @@ crates/font-store/index/indexes/*.gz binary
# Copies of the vendored krilla source diff, one per patch (see vendor/krilla/README.craft.md).
vendor/krilla/patches/*.patch linguist-generated=true
# Has a pinned digest and is embedded as bytes by craft-font-store.
crates/font-store/index/sources.json -text
# The build fixture verifies these license files are copied byte-for-byte.
crates/fonts-build/tests/fixture/craft-fonts/fonts/**/OFL.txt -text
Generated
+66
View File
@@ -1336,6 +1336,16 @@ dependencies = [
name = "craft-docpath"
version = "0.1.0"
[[package]]
name = "craft-document-bundle"
version = "0.1.0"
dependencies = [
"craft-zip",
"serde_json",
"thiserror 2.0.21",
"zip",
]
[[package]]
name = "craft-docx"
version = "0.1.0"
@@ -1454,6 +1464,18 @@ dependencies = [
"thiserror 2.0.21",
]
[[package]]
name = "craft-file-formats"
version = "0.1.0"
dependencies = [
"craft-eps",
"craft-idml",
"craft-svg",
"craft-zip",
"serde",
"serde_json",
]
[[package]]
name = "craft-flags"
version = "0.1.0"
@@ -1628,6 +1650,13 @@ dependencies = [
"zip",
]
[[package]]
name = "craft-indd"
version = "0.1.0"
dependencies = [
"indd",
]
[[package]]
name = "craft-jmap"
version = "0.1.0"
@@ -1704,6 +1733,14 @@ dependencies = [
"craft-wordmodel",
]
[[package]]
name = "craft-materialx"
version = "0.1.0"
dependencies = [
"craft-xml",
"thiserror 2.0.21",
]
[[package]]
name = "craft-math"
version = "0.1.0"
@@ -1885,6 +1922,18 @@ dependencies = [
"zip",
]
[[package]]
name = "craft-pcraft-bundle"
version = "0.1.0"
dependencies = [
"blake3",
"craft-atomic",
"craft-pcraft-format",
"craft-zip",
"ruzstd",
"thiserror 2.0.21",
]
[[package]]
name = "craft-pcraft-format"
version = "0.1.0"
@@ -2106,6 +2155,8 @@ dependencies = [
name = "craft-raster-codecs"
version = "0.1.0"
dependencies = [
"base64 0.23.1",
"image",
"rayon",
"thiserror 2.0.21",
]
@@ -2202,6 +2253,15 @@ dependencies = [
"zip",
]
[[package]]
name = "craft-stencilcraft-format"
version = "0.1.0"
dependencies = [
"serde",
"serde_json",
"thiserror 2.0.21",
]
[[package]]
name = "craft-stream-codecs"
version = "0.1.0"
@@ -2278,6 +2338,7 @@ dependencies = [
name = "craft-timeline"
version = "0.1.0"
dependencies = [
"craft-time",
"craft-xml",
"proptest",
"serde",
@@ -4752,6 +4813,11 @@ version = "0.15.0"
source = "registry+https://github.com/rust-lang/crates.io-index"
checksum = "65b27460c2c92b037f3f94c538ed9a3342f3fdf923606781629ccb35f82d042a"
[[package]]
name = "indd"
version = "0.1.0"
source = "git+https://github.com/storytold/indd-utils?rev=7f3060e5bce78d21ea70e0d5eacb96edce15dfbe#7f3060e5bce78d21ea70e0d5eacb96edce15dfbe"
[[package]]
name = "indexmap"
version = "2.14.2"
+7
View File
@@ -39,9 +39,11 @@ craft-dav = { path = "crates/dav" }
craft-dialogs = { path = "crates/dialogs" }
craft-doc-binary = { path = "crates/doc-binary" }
craft-docx = { path = "crates/docx" }
craft-document-bundle = { path = "crates/document-bundle" }
craft-dxf = { path = "crates/dxf" }
craft-drawingml = { path = "crates/drawingml" }
craft-eps = { path = "crates/eps" }
craft-file-formats = { path = "crates/file-formats" }
craft-doc = { path = "crates/doc" }
craft-docpath = { path = "crates/docpath" }
craft-dpx = { path = "crates/dpx" }
@@ -64,6 +66,7 @@ craft-fig = { path = "crates/fig" }
craft-fonts-build = { path = "crates/fonts-build" }
craft-i18n = { path = "crates/i18n" }
craft-idml = { path = "crates/idml" }
craft-indd = { path = "crates/indd" }
craft-jmap = { path = "crates/jmap" }
craft-ical = { path = "crates/ical" }
craft-jpeg = { path = "crates/jpeg" }
@@ -77,6 +80,7 @@ craft-latex = { path = "crates/latex" }
craft-markdown = { path = "crates/markdown" }
craft-math = { path = "crates/math" }
craft-media = { path = "crates/media", default-features = false }
craft-materialx = { path = "crates/materialx" }
craft-media-testkit = { path = "crates/media-testkit" }
craft-midi = { path = "crates/midi" }
craft-sf2 = { path = "crates/sf2" }
@@ -94,6 +98,7 @@ craft-ora = { path = "crates/ora" }
craft-pptx = { path = "crates/pptx" }
craft-penpot = { path = "crates/penpot" }
craft-pcraft-format = { path = "crates/pcraft-format" }
craft-pcraft-bundle = { path = "crates/pcraft-bundle" }
craft-pkcs7 = { path = "crates/pkcs7" }
craft-plotter = { path = "crates/plotter" }
craft-prepress = { path = "crates/prepress" }
@@ -112,6 +117,7 @@ craft-scraft-format = { path = "crates/scraft-format" }
craft-time = { path = "crates/time" }
craft-silhouette-studio = { path = "crates/silhouette-studio" }
craft-svg = { path = "crates/svg" }
craft-stencilcraft-format = { path = "crates/stencilcraft-format" }
craft-svg-paths = { path = "crates/svg-paths" }
craft-stream-codecs = { path = "crates/stream-codecs" }
craft-text = { path = "crates/text" }
@@ -127,6 +133,7 @@ craft-vectordrawable = { path = "crates/vectordrawable" }
craft-xls = { path = "crates/xls" }
craft-wordmodel = { path = "crates/wordmodel" }
craft-xlsx = { path = "crates/xlsx" }
indd = { git = "https://github.com/storytold/indd-utils", rev = "7f3060e5bce78d21ea70e0d5eacb96edce15dfbe" }
craft-xcf = { path = "crates/xcf" }
craft-xml = { path = "crates/xml" }
craft-zip = { path = "crates/zip" }
+1
View File
@@ -327,6 +327,7 @@ See the [release notes](CHANGELOG.md) for included functionality and known limit
- [`craft-sheet`](crates/sheet/README.md): spreadsheet vocabulary shared by `craft-xls`, `craft-xlsx` and `craft-ods`: cell positions and A1 text, cell values and error values, sheet-name quoting, Excel's built-in number formats and indexed colour palette. Not a file format; no dependencies.
- [`craft-sf2`](crates/sf2/README.md): SoundFont 2 (`.sf2`) reader: the sample pool and, per preset, the key and velocity regions a note sounds, with tuning, loop points, pan, level and volume envelope resolved from the preset and instrument zones. Bounded on hostile input. From LoopCraft.
- [`craft-silhouette-studio`](crates/silhouette-studio/src/lib.rs): bounded, fail-closed reader for Silhouette Studio `.studio` and `.studio3` documents: outlines, line colours and page size in millimetres. Protected designs are refused.
- [`craft-stencilcraft-format`](crates/stencilcraft-format/README.md): the versioned `.stencilcraft` JSON wire schema and envelope: required members, version 1 defaults, optional fields, and header checks. The app retains its document model and domain validation.
- [`craft-sketch`](crates/sketch/README.md): clean-room reader for the `.sketch` container (Sketch 48 and newer): the ZIP archive, the version cut, `document.json`, the pages in document order and images, as the JSON the file holds. Bounded on hostile input. Carved from FigCraft.
- [`craft-svg`](crates/svg/src/lib.rs): SVG. `sniff` recognises SVG and SVGZ data; `svgz` unpacks
SVGZ within a byte limit, decodes UTF-8, UTF-16 and ISO 8859-1, and compresses; `guard` bounds
+1 -1
View File
@@ -413,7 +413,7 @@ impl<'a> Native<'a> {
let Some(next) = self.packets.next() else {
// A track that declares no frames (an empty WAV or AIFF) is empty, not broken.
let empty = self.frames_known && self.info.frames == 0 && self.errors == 0;
if !self.decoded && !empty && !(self.seeked && self.errors == 0) {
if !(self.decoded || empty || self.seeked && self.errors == 0) {
return Err(self.no_audio("stream contains no audio"));
}
return Ok(None);
+17
View File
@@ -0,0 +1,17 @@
[package]
name = "craft-document-bundle"
description = "A reusable JSON document bundle envelope over ZIP: metadata, previews, asset entries and legacy inline asset extraction."
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
craft-zip = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
zip = { version = "9", default-features = false, features = ["deflate-flate2"] }
+317
View File
@@ -0,0 +1,317 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
//! A JSON document bundle envelope over ZIP.
//!
//! Applications keep their document models. This crate owns the reusable container mechanics:
//! ordered mimetype, metadata, JSON model, previews, embedded asset paths, compression policy,
//! bounded reads and extraction of legacy base64 asset maps. Entry names and MIME type are
//! supplied by the format using the bundle.
use std::io::{Read, Seek};
use craft_zip::{Archive, Compression, Limits, Writer};
use serde_json::Value;
const MAX_ENTRIES: u64 = 100_000;
const JSON_LIMIT: u64 = 256 << 20;
const ASSET_LIMIT: u64 = 1 << 30;
const EXPANSION_LIMIT: u64 = 4 << 30;
/// Per-entry and total-expansion limits for an untrusted document bundle.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct ReadLimits {
/// Maximum expanded size of metadata and document JSON.
pub json_bytes: u64,
/// Maximum expanded size of one compressed asset. Stored assets are bounded by archive size.
pub compressed_asset_bytes: u64,
/// Maximum expansion beyond the bytes in the source archive.
pub expansion_bytes: u64,
}
impl Default for ReadLimits {
fn default() -> Self {
Self { json_bytes: JSON_LIMIT, compressed_asset_bytes: ASSET_LIMIT, expansion_bytes: EXPANSION_LIMIT }
}
}
/// Names and identity used by one JSON document bundle format.
#[derive(Clone, Copy, Debug)]
pub struct Spec<'a> {
/// Stored first entry and its payload.
pub mimetype_entry: &'a str,
pub mimetype: &'a str,
/// Metadata and document JSON member names.
pub metadata_entry: &'a str,
pub document_entry: &'a str,
/// Optional preview entry name.
pub preview_entry: &'a str,
/// Directory prefix for embedded assets, without a trailing slash.
pub assets_directory: &'a str,
/// Metadata value written in the `format` field.
pub format_name: &'a str,
/// Old single-file JSON field containing base64 assets keyed by decimal id.
pub legacy_assets_field: Option<&'a str>,
}
/// An embedded asset passed to [`write`].
#[derive(Clone, Copy, Debug)]
pub struct Asset<'a> {
/// Decimal asset id used in the archive entry path.
pub id: &'a str,
/// MIME type used to select the extension and compression policy.
pub mime: &'a str,
/// File bytes retained byte-for-byte.
pub data: &'a [u8],
}
/// A document and embedded payloads returned by [`read`].
#[derive(Clone, Debug, PartialEq)]
pub struct Package {
/// Parsed model JSON, after extracting legacy inline assets.
pub document: Value,
/// Format version declared by metadata, or 1 when absent.
pub version: u64,
/// Embedded asset bytes keyed by decimal asset id.
pub assets: Vec<(String, Vec<u8>)>,
}
/// Why a document bundle could not be read or written.
#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
pub enum Error {
/// The bytes are not a bundle or legacy JSON document.
#[error("not a document bundle: {0}")]
NotBundle(String),
/// The bundle requires a newer reader.
#[error("document format {0} is newer than this reader supports")]
TooNew(u64),
/// A member could not be written.
#[error("could not write document bundle: {0}")]
Write(String),
/// A member exceeded a read limit or could not be read.
#[error("could not read document bundle: {0}")]
Read(String),
}
fn extension(mime: &str) -> &'static str {
match mime {
"image/png" => "png",
"image/jpeg" => "jpg",
"image/gif" => "gif",
"image/webp" => "webp",
"image/tiff" => "tif",
"application/pdf" => "pdf",
"application/postscript" => "eps",
"image/svg+xml" => "svg",
_ => "bin",
}
}
/// Whether `bytes` are a ZIP bundle that contains the configured document member.
pub fn has_document(bytes: &[u8], spec: Spec<'_>) -> bool {
let Ok(archive) = Archive::open(bytes, Limits { max_entries: MAX_ENTRIES, max_total_bytes: 0 }) else { return false };
archive.contains(spec.document_entry)
}
/// Whether `prefix` starts with the configured stored mimetype entry.
pub fn starts_with_mimetype(prefix: &[u8], spec: Spec<'_>) -> bool {
craft_zip::stored_mimetype(prefix).is_some_and(|mime| mime == spec.mimetype.as_bytes())
}
/// Write a ZIP document bundle containing the serialized document, metadata, preview and assets.
pub fn write(document: &[u8], version: u32, generator: &str, preview: Option<&[u8]>, assets: &[Asset<'_>], spec: Spec<'_>) -> Result<Vec<u8>, Error> {
let mut writer = Writer::new();
writer.add(spec.mimetype_entry, spec.mimetype.as_bytes(), Compression::Stored).map_err(|e| Error::Write(e.to_string()))?;
let metadata = serde_json::json!({"format":spec.format_name, "version":version, "generator":generator});
let metadata = serde_json::to_vec(&metadata).map_err(|e| Error::Write(e.to_string()))?;
writer.add(spec.metadata_entry, &metadata, Compression::Deflated).map_err(|e| Error::Write(e.to_string()))?;
if let Some(preview) = preview {
writer.add(spec.preview_entry, preview, Compression::Stored).map_err(|e| Error::Write(e.to_string()))?;
}
writer.add(spec.document_entry, document, Compression::Deflated).map_err(|e| Error::Write(e.to_string()))?;
for asset in assets.iter().filter(|asset| !asset.data.is_empty()) {
let path = format!("{}/{}.{}", spec.assets_directory, asset.id, extension(asset.mime));
let compression =
if matches!(asset.mime, "image/png" | "image/jpeg" | "image/gif" | "image/webp") { Compression::Stored } else { Compression::Deflated };
writer.add(&path, asset.data, compression).map_err(|e| Error::Write(e.to_string()))?;
}
writer.finish().map_err(|e| Error::Write(e.to_string()))
}
/// Read a ZIP bundle or legacy JSON document within bounded member sizes.
///
/// Members under the configured assets directory whose id does not occur in the document's
/// `assets` object are never decompressed. Unreferenced data cannot consume the caller's memory.
pub fn read(bytes: &[u8], supported_version: u32, spec: Spec<'_>) -> Result<Package, Error> {
read_with_limits(bytes, supported_version, spec, ReadLimits::default())
}
/// Like [`read`], with caller-selected bounded-read limits.
pub fn read_with_limits(bytes: &[u8], supported_version: u32, spec: Spec<'_>, limits: ReadLimits) -> Result<Package, Error> {
if !bytes.starts_with(b"PK") {
return read_legacy(bytes, spec);
}
let source_size = u64::try_from(bytes.len()).unwrap_or(u64::MAX);
let mut archive = Archive::open(bytes, Limits { max_entries: MAX_ENTRIES, max_total_bytes: source_size.saturating_add(limits.expansion_bytes) })
.map_err(|e| Error::NotBundle(e.to_string()))?;
if archive.has_duplicate_names() {
return Err(Error::NotBundle("the archive has duplicate member names".into()));
}
let version = archive
.read(spec.metadata_entry, limits.json_bytes)
.map_err(|e| Error::Read(e.to_string()))?
.and_then(|metadata| serde_json::from_slice::<Value>(&metadata).ok())
.and_then(|metadata| metadata.get("version").and_then(Value::as_u64))
.unwrap_or(1);
if version > u64::from(supported_version) {
return Err(Error::TooNew(version));
}
let document_bytes = archive
.read(spec.document_entry, limits.json_bytes)
.map_err(|e| Error::Read(e.to_string()))?
.ok_or_else(|| Error::NotBundle(format!("missing {}", spec.document_entry)))?;
let document: Value = serde_json::from_slice(&document_bytes).map_err(|e| Error::NotBundle(e.to_string()))?;
let wanted: std::collections::HashSet<String> =
document.get("assets").and_then(Value::as_object).into_iter().flat_map(|assets| assets.keys().cloned()).collect();
let prefix = format!("{}/", spec.assets_directory);
let mut embedded = Vec::new();
for path in archive.names().map(|name| name.into_owned()).collect::<Vec<_>>() {
let Some(member) = path.strip_prefix(&prefix) else { continue };
let Some(id) = member.split('.').next() else { continue };
if !wanted.contains(id) || id.parse::<u64>().is_err() {
continue;
}
let stored = archive.is_stored(&path).unwrap_or(false);
let limit = if stored { source_size } else { limits.compressed_asset_bytes };
let data = archive.read(&path, limit).map_err(|e| Error::Read(e.to_string()))?;
if let Some(data) = data {
embedded.push((id.to_owned(), data));
}
}
Ok(Package { document, version, assets: embedded })
}
/// Read a preview with a fixed maximum size without decompressing the full bundle.
pub fn read_preview(bytes: &[u8], preview_entry: &str) -> Option<Vec<u8>> {
const PREVIEW_LIMIT: u64 = 4 << 20;
let mut archive = Archive::open(bytes, Limits { max_entries: MAX_ENTRIES, max_total_bytes: PREVIEW_LIMIT }).ok()?;
archive.read(preview_entry, PREVIEW_LIMIT).ok().flatten()
}
/// Read a bounded preview from a seekable file without loading the full bundle into memory.
pub fn read_preview_from<R: Read + Seek>(reader: R, preview_entry: &str) -> Option<Vec<u8>> {
const PREVIEW_LIMIT: u64 = 4 << 20;
let mut zip = zip::ZipArchive::new(reader).ok()?;
let entry = zip.by_name(preview_entry).ok()?;
if entry.size() > PREVIEW_LIMIT {
return None;
}
let mut preview = Vec::new();
entry.take(PREVIEW_LIMIT.saturating_add(1)).read_to_end(&mut preview).ok()?;
(u64::try_from(preview.len()).ok()? <= PREVIEW_LIMIT).then_some(preview)
}
fn read_legacy(bytes: &[u8], spec: Spec<'_>) -> Result<Package, Error> {
let mut document: Value = serde_json::from_slice(bytes).map_err(|e| Error::NotBundle(e.to_string()))?;
let mut assets = Vec::new();
let mut total = 0u64;
if let Some(field) = spec.legacy_assets_field {
if let Some(inline) = document.get(field).and_then(Value::as_object) {
for (id, value) in inline {
if id.parse::<u64>().is_ok()
&& let Some(encoded) = value.as_str()
{
let decoded_size = u64::try_from(encoded.len()).unwrap_or(u64::MAX).saturating_mul(3) / 4;
if decoded_size > ASSET_LIMIT {
return Err(Error::Read(format!("legacy asset {id} exceeds the {ASSET_LIMIT}-byte limit")));
}
total = total.saturating_add(decoded_size);
if total > EXPANSION_LIMIT {
return Err(Error::Read(format!("legacy assets exceed the {EXPANSION_LIMIT}-byte total limit")));
}
assets.push((id.clone(), decode_base64(encoded)));
}
}
}
if let Some(object) = document.as_object_mut() {
object.remove(field);
}
}
Ok(Package { document, version: 1, assets })
}
fn decode_base64(input: &str) -> Vec<u8> {
let mut out = Vec::with_capacity(input.len().saturating_mul(3) / 4);
let (mut buffer, mut bits) = (0u32, 0u32);
for byte in input.bytes() {
let value = match byte {
b'A'..=b'Z' => byte - b'A',
b'a'..=b'z' => byte - b'a' + 26,
b'0'..=b'9' => byte - b'0' + 52,
b'+' | b'-' => 62,
b'/' | b'_' => 63,
_ => continue,
};
buffer = (buffer << 6) | u32::from(value);
bits += 6;
if bits >= 8 {
bits -= 8;
out.push((buffer >> bits) as u8);
}
}
out
}
#[cfg(test)]
mod tests {
use super::*;
const SPEC: Spec<'static> = Spec {
mimetype_entry: "mimetype",
mimetype: "application/vnd.test+zip",
metadata_entry: "meta.json",
document_entry: "document.json",
preview_entry: "preview.png",
assets_directory: "assets",
format_name: "test",
legacy_assets_field: Some("assetData"),
};
#[test]
fn writes_and_reads_bundle_members() {
let payload = [1u8, 2, 3];
let bytes =
write(br#"{"assets":{"7":{}}}"#, 4, "Test 0.1", Some(b"png"), &[Asset { id: "7", mime: "image/png", data: &payload }], SPEC).unwrap();
assert!(has_document(&bytes, SPEC));
assert!(starts_with_mimetype(&bytes, SPEC));
let loaded = read(&bytes, 4, SPEC).unwrap();
assert_eq!(loaded.document, serde_json::json!({"assets":{"7":{}}}));
assert_eq!(loaded.version, 4);
assert_eq!(loaded.assets, [("7".to_owned(), payload.to_vec())]);
assert_eq!(read_preview(&bytes, SPEC.preview_entry).as_deref(), Some(&b"png"[..]));
}
#[test]
fn extracts_legacy_inline_assets() {
let loaded = read(br#"{"assetData":{"7":"AQID"},"name":"x"}"#, 4, SPEC).unwrap();
assert_eq!(loaded.document, serde_json::json!({"name":"x"}));
assert_eq!(loaded.assets, [("7".to_owned(), vec![1, 2, 3])]);
}
#[test]
fn refuses_newer_versions() {
let bytes = write(b"{}", 9, "future", None, &[], SPEC).unwrap();
assert_eq!(read(&bytes, 4, SPEC), Err(Error::TooNew(9)));
}
#[test]
fn stored_assets_use_source_size_and_deflated_assets_use_their_limit() {
let bytes = vec![7u8; 128];
let document = br#"{"assets":{"7":{}}}"#;
let limits = ReadLimits { json_bytes: 1 << 20, compressed_asset_bytes: 8, expansion_bytes: 1 << 20 };
let stored = write(document, 4, "test", None, &[Asset { id: "7", mime: "image/png", data: &bytes }], SPEC).unwrap();
let package = read_with_limits(&stored, 4, SPEC, limits).unwrap();
assert_eq!(package.assets, [("7".to_owned(), bytes.clone())]);
let compressed = write(document, 4, "test", None, &[Asset { id: "7", mime: "application/octet-stream", data: &bytes }], SPEC).unwrap();
assert!(read_with_limits(&compressed, 4, SPEC, limits).is_err());
}
}
+1 -1
View File
@@ -443,7 +443,7 @@ fn read_axes<'a>(c: &mut Chart, pa: &'a El, primary_val: &Option<String>) -> (Op
// A gridline whose `c:spPr/a:ln` has `a:noFill` is not drawn, though the element is there.
let grid = |a: &El, k: &str| {
a.child(Local(k))
.is_some_and(|g| !g.child(Local("spPr")).and_then(|p| p.child(Local("ln"))).is_some_and(|l| l.child(Local("noFill")).is_some()))
.is_some_and(|g| g.child(Local("spPr")).and_then(|p| p.child(Local("ln"))).is_none_or(|l| l.child(Local("noFill")).is_none()))
};
if c.kind == ChartType::Combo && c.series.iter().any(|s| s.secondary_axis) {
let primary_id = val_ax.and_then(|a| a.child(Local("axId")).and_then(|c| c.attr_local("val")));
+6
View File
@@ -166,6 +166,12 @@ pub fn blip_fill(src: &mut dyn Source, bf: &El) -> Option<PictureFill> {
{
pf.artistic = Some(crate::style::Artistic { effect, original });
}
pf.svg = blip.and_then(|b| b.child(Local("extLst"))).and_then(|extensions| {
extensions
.elements()
.filter(|extension| extension.local() == "ext" && extension.attr_local("uri") == Some("{96DAC541-7B7A-43D3-8B79-37D633B846F1}"))
.find_map(|extension| extension.child(Local("svgBlip")).and_then(|svg| media_ref(src, svg)))
});
if let Some(b) = blip {
for e in b.elements() {
match e.local() {
+3
View File
@@ -184,6 +184,9 @@ impl Default for PictureMode {
#[serde(default, rename_all = "camelCase")]
pub struct PictureFill {
pub media: MediaId,
/// Optional vector SVG version of `media`; the regular media remains the bitmap fallback.
#[serde(skip_serializing_if = "Option::is_none")]
pub svg: Option<MediaId>,
/// Source crop as fractions of the image (left, top, right, bottom); negative values pad.
pub crop: [f64; 4],
pub mode: PictureMode,
+8
View File
@@ -107,6 +107,7 @@ pub fn blip_fill(w: &mut Writer, out: &mut dyn Sink, tag: &str, pf: &PictureFill
w.tag(tag).attr("rotWithShape", if pf.upright { "0" } else { "1" }).open();
let adj = &pf.adjust;
let has_kids = pf.alpha.is_some()
|| pf.svg.is_some()
|| adj.brightness != 0.0
|| adj.contrast != 0.0
|| adj.grayscale
@@ -168,6 +169,13 @@ pub fn blip_fill(w: &mut Writer, out: &mut dyn Sink, tag: &str, pf: &PictureFill
w.close();
w.close();
}
if let Some(svg) = pf.svg.and_then(|id| out.media_rel(id, "image")) {
w.open("a:extLst", &[]);
w.tag("a:ext").attr("uri", "{96DAC541-7B7A-43D3-8B79-37D633B846F1}").open();
w.tag("asvg:svgBlip").attr("xmlns:asvg", "http://schemas.microsoft.com/office/drawing/2016/SVG/main").attr("r:embed", &svg).empty();
w.close();
w.close();
}
w.close();
} else {
w.tag("a:blip").list(a).empty();
+2
View File
@@ -19,10 +19,12 @@ pub mod ascii85;
mod container;
mod dsc;
mod preview;
mod rectangles;
pub use container::{DOS_HEADER, DOS_MAGIC, Sections, sections, wrap};
pub use dsc::{Comments, MAX_HEADER, MAX_TRAILER};
pub use preview::{Bitmap, MAX_EPSI, epsi};
pub use rectangles::{MAX_SIMPLE_RECTANGLE_SAVE_DEPTH, MAX_SIMPLE_RECTANGLE_TOKENS, MAX_SIMPLE_RECTANGLES, Rectangle, simple_rectangles};
use std::fmt;
+136
View File
@@ -0,0 +1,136 @@
//! A bounded subset of PostScript used for simple EPS previews.
use std::collections::HashMap;
/// A solid rectangle drawn by a simple EPS program.
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct Rectangle {
/// Left edge in PostScript points.
pub x: f64,
/// Bottom edge in PostScript points.
pub y: f64,
/// Width in PostScript points.
pub width: f64,
/// Height in PostScript points.
pub height: f64,
/// Straight sRGB RGBA.
pub color: [u8; 4],
}
pub const MAX_SIMPLE_RECTANGLES: usize = 200_000;
pub const MAX_SIMPLE_RECTANGLE_TOKENS: usize = 2_000_000;
pub const MAX_SIMPLE_RECTANGLE_SAVE_DEPTH: usize = 64;
/// Simple PostScript tokens without comments, with braces kept as individual tokens.
fn tokens(text: &str) -> impl Iterator<Item = &str> {
text.split(['\n', '\r']).flat_map(|line| {
line.split('%').next().unwrap_or("").split_whitespace().flat_map(|word| word.split_inclusive(['{', '}'])).flat_map(|piece| {
let (body, brace) = match piece.char_indices().last() {
Some((at, '{' | '}')) => (piece.get(..at).unwrap_or(""), piece.get(at..)),
_ => (piece, None),
};
[Some(body).filter(|body| !body.is_empty()), brace].into_iter().flatten()
})
})
}
/// Read solid rectangle fills and their sRGB colours from the restricted PostScript subset used
/// by simple EPS previews. None means the program uses an unsupported operator or exceeds a
/// fixed work bound. The function never executes PostScript.
pub fn simple_rectangles(ps: &[u8]) -> Option<Vec<Rectangle>> {
let text = std::str::from_utf8(ps).ok()?;
let mut aliases: HashMap<String, String> = HashMap::new();
let mut stack: Vec<f64> = Vec::new();
let mut color = [0u8, 0, 0, 255];
let mut saved: Vec<[u8; 4]> = Vec::new();
let mut rectangles = Vec::new();
let mut input = tokens(text);
let mut count = 0usize;
while let Some(token) = input.next() {
count += 1;
if count > MAX_SIMPLE_RECTANGLE_TOKENS {
return None;
}
if let Ok(value) = token.parse::<f64>() {
if !value.is_finite() {
return None;
}
stack.push(value);
continue;
}
if let Some(name) = token.strip_prefix('/') {
let mut body: Vec<&str> = Vec::new();
while body.len() < 5 {
count += 1;
if count > MAX_SIMPLE_RECTANGLE_TOKENS {
return None;
}
match input.next() {
Some("def") | None => break,
Some(token) => body.push(token),
}
}
let op = match body.as_slice() {
["{", op, "}"] | ["{", op, "}", _] => (*op).to_string(),
_ => return None,
};
aliases.insert(name.to_string(), op);
continue;
}
let op = aliases.get(token).map_or(token, String::as_str);
let mut pop = |n: usize| -> Option<Vec<f64>> { (stack.len() >= n).then(|| stack.split_off(stack.len() - n)) };
match op {
"setcmykcolor" => {
let values = pop(4)?;
let black = values[3].clamp(0.0, 1.0);
let channel = |value: f64| ((1.0 - value.clamp(0.0, 1.0)) * (1.0 - black) * 255.0).round() as u8;
color = [channel(values[0]), channel(values[1]), channel(values[2]), 255];
}
"setrgbcolor" => {
let values = pop(3)?;
let channel = |value: f64| (value.clamp(0.0, 1.0) * 255.0).round() as u8;
color = [channel(values[0]), channel(values[1]), channel(values[2]), 255];
}
"setgray" => {
let values = pop(1)?;
let gray = (values[0].clamp(0.0, 1.0) * 255.0).round() as u8;
color = [gray, gray, gray, 255];
}
"rectfill" => {
let values = pop(4)?;
if rectangles.len() >= MAX_SIMPLE_RECTANGLES {
return None;
}
let x1 = values[0] + values[2];
let y1 = values[1] + values[3];
if !x1.is_finite() || !y1.is_finite() {
return None;
}
rectangles.push(Rectangle {
x: values[0].min(x1),
y: values[1].min(y1),
width: (x1 - values[0]).abs(),
height: (y1 - values[1]).abs(),
color,
});
}
"gsave" | "save" => {
if saved.len() >= MAX_SIMPLE_RECTANGLE_SAVE_DEPTH {
return None;
}
saved.push(color);
}
"grestore" | "restore" => {
if let Some(previous) = saved.pop() {
color = previous;
}
}
"pop" => {
pop(1)?;
}
"bind" | "newpath" | "showpage" | "end" | "begin" => {}
_ => return None,
}
}
(!rectangles.is_empty()).then_some(rectangles)
}
+19
View File
@@ -0,0 +1,19 @@
[package]
name = "craft-file-formats"
description = "Shared bounded file signature and extension resolution for Craft applications"
version.workspace = true
edition.workspace = true
license.workspace = true
repository.workspace = true
rust-version.workspace = true
[dependencies]
craft-eps = { workspace = true }
craft-idml = { workspace = true }
craft-svg = { workspace = true }
craft-zip = { workspace = true }
serde = { workspace = true }
serde_json = { workspace = true }
[lints]
workspace = true
+269
View File
@@ -0,0 +1,269 @@
//! Bounded file kind detection and extension resolution shared by Craft applications.
//!
//! This crate identifies a format; it does not parse, validate, or decode the file.
//! Callers remain responsible for choosing which identified formats their product supports.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
/// A supported file family, independent of the application model that consumes it.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum Format {
Pdf,
Eps,
PostScript,
Illustrator,
Dxf,
Svg,
/// Gzip-compressed SVG. Kept distinct so writers do not place plain SVG under `.svgz`.
Svgz,
Png,
Jpeg,
Bmp,
Gif,
Tiff,
WebP,
Heif,
Ase,
Psd,
Affinity,
Ora,
Kra,
Xcf,
Pdn,
Raw,
Pcraft,
Idml,
DesignCraft,
/// Legacy DesignCraft documents serialized as one JSON object.
DesignCraftJson,
Indd,
Docx,
/// Legacy OLE Compound File Word document; identified by its extension only.
LegacyDoc,
Rtf,
Xlsx,
TaggedText,
Pptx,
PlainText,
Csv,
Tsv,
/// Legacy binary Excel workbooks, identified by extension only.
LegacyExcel,
Gcode,
Studio,
StencilCraft,
}
/// Resolve a name and file bytes to a format. Strong signatures take precedence over
/// extension hints. Only format-specific bounded probes and extension tables live here.
pub fn detect(name: &str, bytes: &[u8]) -> Option<Format> {
if craft_idml::is_idml(bytes) {
return Some(Format::Idml);
}
if craft_zip::stored_mimetype(bytes) == Some(b"application/vnd.designcraft+zip") || designcraft_zip_has_document(bytes) {
return Some(Format::DesignCraft);
}
if is_designcraft_json(bytes) {
return Some(Format::DesignCraftJson);
}
if bytes.starts_with(&INDD_SIGNATURE) {
return Some(Format::Indd);
}
if let Some(found) = craft_eps::sniff(bytes) {
return Some(match (found.kind, found.illustrator) {
(_, true) => Format::Illustrator,
(craft_eps::Kind::Pdf, _) => Format::Pdf,
(craft_eps::Kind::Eps, _) => Format::Eps,
(craft_eps::Kind::PostScript, _) => Format::PostScript,
});
}
if bytes.starts_with(b"8BPS") {
return Some(Format::Psd);
}
if bytes.starts_with(b"ASEF") {
return Some(Format::Ase);
}
if bytes.starts_with(b"PDN3") {
return Some(Format::Pdn);
}
if bytes.starts_with(b"gimp xcf ") || gzipped_xcf(name, bytes) {
return Some(Format::Xcf);
}
if bytes.starts_with(b"\0\xffKA") {
return Some(Format::Affinity);
}
if let Some(raster) = raster_signature(bytes) {
return Some(raster);
}
if bytes.starts_with(b"silhouette04;") || bytes.starts_with(b"silhouette05;") {
return Some(Format::Studio);
}
let tagged = bytes.strip_prefix(b"\xef\xbb\xbf").unwrap_or(bytes).trim_ascii_start();
if tagged.starts_with(b"<ASCII-") || tagged.starts_with(b"<UNICODE-") || tagged.starts_with(b"<ANSI-") {
return Some(Format::TaggedText);
}
if bytes.trim_ascii_start().starts_with(b"{\\rtf") {
return Some(Format::Rtf);
}
if craft_svg::sniff::is_svgz(bytes)
&& let Ok(text) = craft_svg::svgz::text(bytes, 64 * 1024 * 1024)
&& craft_svg::sniff::is_svg(text.as_bytes())
{
return Some(Format::Svgz);
}
if craft_svg::sniff::is_svg(bytes) {
return Some(Format::Svg);
}
if let Some(ext) = extension(name)
&& let Some(format) = from_extension(ext)
{
return Some(format);
}
let head = bytes.get(..4096).unwrap_or(bytes);
if dxf_ascii_prefix(head) || head.starts_with(b"AutoCAD Binary DXF\r\n\x1a\0") {
return Some(Format::Dxf);
}
None
}
/// DesignCraft's older ZIPs predate their leading `mimetype`; they are identified by the
/// `document.json` member. The directory is bounded before it is indexed and no entry is inflated.
fn designcraft_zip_has_document(bytes: &[u8]) -> bool {
if !bytes.starts_with(b"PK") {
return false;
}
craft_zip::Archive::open(bytes, craft_zip::Limits { max_entries: 100_000, max_total_bytes: 0 })
.is_ok_and(|archive| archive.contains("document.json"))
}
/// Read only a bounded prefix, stopping as soon as the model's required top-level keys have
/// appeared. This distinguishes legacy DesignCraft JSON from arbitrary JSON without decoding the
/// document or walking its arrays and assets.
fn is_designcraft_json(bytes: &[u8]) -> bool {
const LIMIT: usize = 1 << 20;
const REQUIRED: u16 = (1 << 10) - 1;
const KEYS: [&str; 10] = ["title", "settings", "spreads", "parents", "layers", "stories", "styles", "swatches", "sections", "next_id"];
struct Probe;
impl<'de> serde::de::Visitor<'de> for Probe {
type Value = bool;
fn expecting(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
formatter.write_str("a DesignCraft document object")
}
fn visit_map<A: serde::de::MapAccess<'de>>(self, mut map: A) -> Result<Self::Value, A::Error> {
let mut found = 0u16;
while let Some(key) = map.next_key::<String>()? {
if let Some(index) = KEYS.iter().position(|candidate| *candidate == key) {
found |= 1 << index;
}
map.next_value::<serde::de::IgnoredAny>()?;
if found == REQUIRED {
return Ok(true);
}
}
Ok(false)
}
}
use serde::de::DeserializeSeed;
struct Seed;
impl<'de> DeserializeSeed<'de> for Seed {
type Value = bool;
fn deserialize<D: serde::Deserializer<'de>>(self, deserializer: D) -> Result<Self::Value, D::Error> {
deserializer.deserialize_map(Probe)
}
}
let prefix = bytes.get(..bytes.len().min(LIMIT)).unwrap_or(bytes);
let mut deserializer = serde_json::Deserializer::from_slice(prefix);
Seed.deserialize(&mut deserializer).unwrap_or(false)
}
/// Resolve a file extension to a family, case-insensitively.
pub fn from_extension(ext: &str) -> Option<Format> {
match ext.trim_start_matches('.').to_ascii_lowercase().as_str() {
"pdf" => Some(Format::Pdf),
"eps" => Some(Format::Eps),
"ps" => Some(Format::PostScript),
"ai" => Some(Format::Illustrator),
"dxf" => Some(Format::Dxf),
"svg" => Some(Format::Svg),
"svgz" => Some(Format::Svgz),
"png" => Some(Format::Png),
"jpg" | "jpeg" => Some(Format::Jpeg),
"bmp" => Some(Format::Bmp),
"gif" => Some(Format::Gif),
"tif" | "tiff" => Some(Format::Tiff),
"webp" => Some(Format::WebP),
"heic" | "heif" => Some(Format::Heif),
"ase" => Some(Format::Ase),
"psd" | "psb" => Some(Format::Psd),
"afdesign" | "afphoto" | "afpub" => Some(Format::Affinity),
"ora" => Some(Format::Ora),
"kra" => Some(Format::Kra),
"xcf" => Some(Format::Xcf),
"pdn" => Some(Format::Pdn),
"dng" | "3fr" | "ari" | "arw" | "bay" | "cap" | "cr2" | "cr3" | "dcs" | "dcr" | "drf" | "eip" | "erf" | "fff" | "gpr" | "iiq" | "k25"
| "kdc" | "mdc" | "mef" | "mos" | "mrw" | "nef" | "nrw" | "obm" | "orf" | "pef" | "ptx" | "pxn" | "r3d" | "raf" | "raw" | "rwl" | "rw2"
| "rwz" | "sr2" | "srf" | "sti" | "x3f" => Some(Format::Raw),
"pcraft" => Some(Format::Pcraft),
"idml" => Some(Format::Idml),
"designcraft" | "dcdoc" => Some(Format::DesignCraft),
"indd" | "indt" => Some(Format::Indd),
"docx" => Some(Format::Docx),
"doc" => Some(Format::LegacyDoc),
"rtf" => Some(Format::Rtf),
"xlsx" => Some(Format::Xlsx),
"pptx" => Some(Format::Pptx),
"txt" | "text" | "md" => Some(Format::PlainText),
"csv" => Some(Format::Csv),
"tsv" | "tab" => Some(Format::Tsv),
"xls" | "xlsm" => Some(Format::LegacyExcel),
"studio" | "studio3" => Some(Format::Studio),
"stencilcraft" => Some(Format::StencilCraft),
"gcode" | "nc" => Some(Format::Gcode),
_ => None,
}
}
const INDD_SIGNATURE: [u8; 16] = [0x06, 0x06, 0xED, 0xF5, 0xD8, 0x1D, 0x46, 0xE5, 0xBD, 0x31, 0xEF, 0xE7, 0xFE, 0x74, 0xB7, 0x1D];
fn extension(name: &str) -> Option<&str> {
Some(name.rsplit(['/', '\\']).next()?.rsplit_once('.')?.1)
}
fn gzipped_xcf(name: &str, bytes: &[u8]) -> bool {
let lower = name.rsplit(['/', '\\']).next().unwrap_or(name).to_ascii_lowercase();
bytes.starts_with(&[0x1f, 0x8b]) && (lower.ends_with(".xcf.gz") || lower.ends_with(".xcfgz"))
}
fn dxf_ascii_prefix(bytes: &[u8]) -> bool {
let text = String::from_utf8_lossy(bytes);
let mut lines = text.lines().map(str::trim);
matches!((lines.next(), lines.next(), lines.next(), lines.next()), (Some("0"), Some("SECTION"), Some("2"), Some(section)) if matches!(section, "HEADER" | "CLASSES" | "TABLES" | "BLOCKS" | "ENTITIES" | "OBJECTS"))
}
fn raster_signature(bytes: &[u8]) -> Option<Format> {
let head = bytes.get(..16).unwrap_or(bytes);
if head.starts_with(b"\x89PNG\r\n\x1a\n") {
return Some(Format::Png);
}
if head.starts_with(b"\xff\xd8\xff") {
return Some(Format::Jpeg);
}
if head.starts_with(b"BM") {
return Some(Format::Bmp);
}
if head.starts_with(b"GIF87a") || head.starts_with(b"GIF89a") {
return Some(Format::Gif);
}
if head.starts_with(b"II*\0") || head.starts_with(b"MM\0*") || head.starts_with(b"II+\0") || head.starts_with(b"MM\0+") {
return Some(Format::Tiff);
}
if head.starts_with(b"RIFF") && head.get(8..12) == Some(b"WEBP") {
return Some(Format::WebP);
}
None
}
+14
View File
@@ -0,0 +1,14 @@
[package]
name = "craft-indd"
description = "Shared InDesign document to IDML conversion facade for Craft applications"
version.workspace = true
edition.workspace = true
license.workspace = true
repository.workspace = true
rust-version.workspace = true
[dependencies]
indd = { workspace = true }
[lints]
workspace = true
+17
View File
@@ -0,0 +1,17 @@
//! Shared InDesign document conversion boundary.
//!
//! InDesign's binary document model is converted to IDML here. Applications can import the
//! resulting package through [`craft_idml`] while retaining only their own model and UI mapping.
pub use indd::header::SIGNATURE;
pub use indd::{Conversion, Error, Preview, Warning};
/// Whether `bytes` begins with the fixed signature of an InDesign document.
pub fn is_indd(bytes: &[u8]) -> bool {
bytes.starts_with(&SIGNATURE)
}
/// Convert an InDesign document to IDML. `name` is the file name stored in the package.
pub fn convert(bytes: &[u8], name: &str) -> Result<Conversion, Error> {
indd::convert(bytes, name)
}
+1 -1
View File
@@ -471,7 +471,7 @@ impl Loaded {
/// notes why not otherwise.
fn add(&mut self, name: &str, overrides: Option<Overrides>) {
let shown = || name.chars().take(MAX_SET_NAME).collect::<String>();
if !set_name(name).is_some_and(|n| n == name) {
if set_name(name).is_none_or(|n| n != name) {
self.note(SetProblem::BadName { name: shown() });
} else if self.sets.contains_key(name) {
self.note(SetProblem::Duplicate { name: shown() });
+15
View File
@@ -0,0 +1,15 @@
[package]
name = "craft-materialx"
description = "MaterialX document parsing and writing"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
craft-xml = { workspace = true }
thiserror = { workspace = true }
+593
View File
@@ -0,0 +1,593 @@
//! MaterialX XML documents and node graphs.
//!
//! This crate owns the format boundary: bounded parsing of `.mtlx` documents, ordered access to
//! their nodes and nodegraph outputs, and XML serialization. Applications map shader inputs to
//! their own material models.
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
use std::collections::HashMap;
use craft_xml::{Doctype, El, Error as XmlError, Limits, Options, UnknownEntity};
/// Maximum source document size accepted by the parser.
pub const MAX_BYTES: usize = 16 * 1024 * 1024;
/// Maximum XML nesting depth accepted by the parser.
pub const MAX_DEPTH: usize = 64;
/// Maximum XML element count accepted by the parser.
pub const MAX_NODES: usize = 200_000;
/// An invalid or unsupported MaterialX document.
#[derive(Clone, Debug, PartialEq, Eq, thiserror::Error)]
pub enum Error {
/// The document is not valid MaterialX XML.
#[error("invalid MaterialX document: {0}")]
Xml(#[from] XmlError),
/// The XML root element is not `<materialx>`.
#[error("the XML root element is not <materialx>")]
Root,
/// The document does not contain the requested surface material.
#[error("no MaterialX material named {0:?}")]
MissingMaterial(String),
/// The document has an unsupported or incomplete shader connection.
#[error("unsupported MaterialX material: {0}")]
Unsupported(String),
/// The document's material references are malformed.
#[error("malformed MaterialX material: {0}")]
Malformed(String),
}
/// A MaterialX document, with XML elements kept in source order.
#[derive(Clone, Debug, PartialEq)]
pub struct Document {
root: El,
}
/// A recognized MaterialX surface shader.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum Shader {
/// OpenPBR Surface.
OpenPbr,
/// Autodesk Standard Surface.
StandardSurface,
/// glTF PBR Surface.
GltfPbr,
}
/// The value connected to a shader input.
#[derive(Clone, Debug, PartialEq)]
pub enum Value {
/// A finite numeric literal, kept in the source color space. `colorspace` is the input's
/// explicit tag; document-level defaults remain available on [`Document::root`].
Constant { values: Vec<f32>, colorspace: Option<String> },
/// A file path from an image node, with the effective file prefix applied.
Image(String),
}
/// A surface material resolved from a MaterialX document.
#[derive(Clone, Debug, PartialEq)]
pub struct Material {
/// Material name, or `Material` when omitted.
pub name: String,
/// Shader dialect represented by the material.
pub shader: Shader,
/// Resolved inputs in the supported shader table's deterministic order.
pub inputs: Vec<(String, Value)>,
/// Resolved displacement input, if present.
pub displacement: Option<Value>,
/// First valid image tiling value, or `[1, 1]`.
pub uv_tiling: [f32; 2],
/// Unsupported or ignored constructs encountered while resolving values.
pub warnings: Vec<String>,
}
#[derive(Clone, Debug)]
struct Found {
value: Value,
tiling: Option<[f32; 2]>,
}
const OPEN_PBR_INPUTS: &[&str] = &[
"base_color",
"base_metalness",
"specular_roughness",
"geometry_normal",
"geometry_opacity",
"emission_color",
"coat_weight",
"coat_roughness",
"geometry_coat_normal",
"fuzz_weight",
"fuzz_color",
"fuzz_roughness",
"specular_roughness_anisotropy",
"transmission_weight",
"subsurface_weight",
];
const STANDARD_INPUTS: &[&str] = &[
"base_color",
"metalness",
"specular_roughness",
"normal",
"opacity",
"emission_color",
"coat",
"coat_roughness",
"coat_normal",
"sheen",
"sheen_color",
"sheen_roughness",
"specular_anisotropy",
"transmission",
"subsurface",
];
const GLTF_INPUTS: &[&str] = &[
"base_color",
"metallic",
"roughness",
"normal",
"alpha",
"emission",
"occlusion",
"clearcoat",
"clearcoat_roughness",
"clearcoat_normal",
"sheen_color",
"sheen_roughness",
"transmission",
];
/// OpenPBR input kind accepted by [`write_open_pbr`].
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum InputKind {
/// Color value or color texture.
Color,
/// Scalar value or data texture.
Float,
/// Vector normal texture.
Normal,
/// Displacement map, serialized as the MaterialX displacement shader input.
Height,
}
/// A texture connected to an OpenPBR input.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Texture {
/// MaterialX/OpenPBR input name, such as `base_color` or `geometry_normal`.
pub input: String,
/// Texture filename relative to the MaterialX document.
pub file: String,
/// Color space used for color inputs; data maps ignore this field.
pub colorspace: String,
}
const OPENPBR_WRITABLE: &[(&str, InputKind)] = &[
("base_color", InputKind::Color),
("base_metalness", InputKind::Float),
("specular_roughness", InputKind::Float),
("specular_roughness_anisotropy", InputKind::Float),
("coat_weight", InputKind::Float),
("coat_roughness", InputKind::Float),
("fuzz_weight", InputKind::Float),
("fuzz_color", InputKind::Color),
("fuzz_roughness", InputKind::Float),
("transmission_weight", InputKind::Float),
("subsurface_weight", InputKind::Float),
("emission_color", InputKind::Color),
("geometry_opacity", InputKind::Float),
("geometry_normal", InputKind::Normal),
("height", InputKind::Height),
];
impl Document {
/// Parses a MaterialX document while enforcing size, nesting and node-count limits.
pub fn parse(bytes: &[u8]) -> Result<Self, Error> {
let limits = Limits { max_input: MAX_BYTES, max_depth: MAX_DEPTH, max_nodes: MAX_NODES, max_attrs: 256, max_attrs_total: 400_000 };
let options = Options {
doctype: Doctype::Reject,
unknown_entity: UnknownEntity::Error,
drop_blank_text: true,
names: craft_xml::Names::Local,
ns_decls: false,
..Options::default()
}
.strict()
.with_limits(limits);
let root = options.parse(bytes)?;
if root.name.rsplit(':').next() != Some("materialx") {
return Err(Error::Root);
}
Ok(Document { root })
}
/// Creates a document from a `<materialx>` element.
pub fn from_root(root: El) -> Result<Self, Error> {
if root.name.rsplit(':').next() != Some("materialx") {
return Err(Error::Root);
}
Ok(Document { root })
}
/// The root `<materialx>` element.
pub fn root(&self) -> &El {
&self.root
}
/// The root `<materialx>` element, for application-specific editing.
pub fn root_mut(&mut self) -> &mut El {
&mut self.root
}
/// Serializes the document as XML, preserving element and attribute order.
pub fn to_xml(&self) -> String {
format!("{}{}", craft_xml::DECL, self.root.to_xml_pretty(" "))
}
/// Nodegraphs in document order.
pub fn nodegraphs(&self) -> impl Iterator<Item = &El> {
self.root.children("nodegraph")
}
/// Outputs in a named nodegraph, in document order.
pub fn outputs(&self, graph: &str) -> impl Iterator<Item = &El> {
self.nodegraphs().filter(move |g| g.attr("name") == Some(graph)).flat_map(|g| g.children("output"))
}
/// The output of a named graph. An omitted output name selects the first output in source
/// order. For duplicate output names, the last definition wins, matching the consumer's
/// existing named lookup behavior.
pub fn output(&self, graph: &str, output: Option<&str>) -> Option<&El> {
match output {
Some(name) => self.outputs(graph).filter(|node| node.attr("name") == Some(name)).last(),
None => self.outputs(graph).next(),
}
}
/// Resolves a surface material into shader inputs, image paths and warnings.
pub fn read_material(&self, material: Option<&str>) -> Result<Material, Error> {
let materials: Vec<&El> = self.root.children("surfacematerial").collect();
let mat = match material {
Some(name) => materials.iter().copied().find(|m| m.attr("name") == Some(name)).ok_or_else(|| Error::MissingMaterial(name.to_owned()))?,
None => materials.first().copied().ok_or_else(|| Error::Unsupported("document has no surfacematerial".into()))?,
};
let mut nodes = HashMap::new();
let mut outputs = Vec::new();
for child in self.root.elements() {
if child.name == "nodegraph" {
let Some(graph) = child.attr("name") else { continue };
for node in child.elements() {
let Some(name) = node.attr("name") else { continue };
if node.name == "output" {
if let Some(from) = node.attr("nodename") {
outputs.push((format!("{graph}/{name}"), format!("{graph}/{from}")));
}
} else {
nodes.insert(format!("{graph}/{name}"), node);
}
}
} else if let Some(name) = child.attr("name") {
nodes.insert(name.to_owned(), child);
}
}
let shader_name = mat.children("input").find(|i| i.attr("name") == Some("surfaceshader")).and_then(|i| i.attr("nodename"));
let shader = shader_name.and_then(|n| nodes.get(n).copied()).ok_or_else(|| Error::Malformed("material has no surface shader".into()))?;
let (kind, inputs) = match shader.name.as_str() {
"open_pbr_surface" => (Shader::OpenPbr, OPEN_PBR_INPUTS),
"standard_surface" => (Shader::StandardSurface, STANDARD_INPUTS),
"gltf_pbr" => (Shader::GltfPbr, GLTF_INPUTS),
other => return Err(Error::Unsupported(format!("surface shader is {other}"))),
};
let emission_gate = match kind {
Shader::OpenPbr => Some(("emission_luminance", true)),
Shader::StandardSurface => Some(("emission", true)),
Shader::GltfPbr => None,
};
let emission_enabled = emission_gate.is_none_or(|(name, _)| {
shader
.children("input")
.find(|i| i.attr("name") == Some(name))
.is_some_and(|i| i.attr("value").is_none_or(|v| parse_numbers(v).and_then(|n| n.first().copied()).is_some_and(|v| v > 0.0)))
});
let mut warnings = Vec::new();
let base_weight_name = match kind {
Shader::OpenPbr => Some("base_weight"),
Shader::StandardSurface => Some("base"),
Shader::GltfPbr => None,
};
if base_weight_name.and_then(|n| numeric_input(shader, n)).is_some_and(|w| (w - 1.0).abs() > 1e-6) {
warnings.push("the base weight isn't 1; it was ignored".into());
}
let mut resolved = Vec::new();
let mut tiling = None;
for name in inputs {
let Some(input) = shader.children("input").find(|i| i.attr("name") == Some(*name)) else { continue };
let is_emission = matches!((kind, *name), (Shader::OpenPbr, "emission_color") | (Shader::StandardSurface, "emission_color"));
if is_emission && !emission_enabled {
warnings.push(format!("{name} was skipped: the shader's emission is 0"));
continue;
}
if let Some(found) = resolve_value(&self.root, input, None, &nodes, &outputs, 0, &mut warnings) {
if tiling.is_none() {
tiling = found.tiling;
}
resolved.push(((*name).to_owned(), found.value));
}
}
let displacement = mat
.children("input")
.find(|i| i.attr("name") == Some("displacementshader"))
.and_then(|i| i.attr("nodename"))
.and_then(|n| nodes.get(n).copied())
.and_then(|d| d.children("input").find(|i| i.attr("name") == Some("displacement")))
.and_then(|i| resolve_value(&self.root, i, None, &nodes, &outputs, 0, &mut warnings).map(|f| f.value));
Ok(Material {
name: mat.attr("name").unwrap_or("Material").to_owned(),
shader: kind,
inputs: resolved,
displacement,
uv_tiling: tiling.unwrap_or([1.0, 1.0]),
warnings,
})
}
}
fn numeric_input(shader: &El, name: &str) -> Option<f32> {
shader
.children("input")
.find(|i| i.attr("name") == Some(name))
.and_then(|i| i.attr("value"))
.and_then(parse_numbers)
.and_then(|n| n.first().copied())
}
fn parse_numbers(text: &str) -> Option<Vec<f32>> {
let nums: Option<Vec<f32>> = text.split(',').map(|part| part.trim().parse::<f32>().ok().filter(|v| v.is_finite())).collect();
nums.filter(|v| !v.is_empty() && v.len() <= 4)
}
fn resolve_value(
root: &El,
input: &El,
scope: Option<&str>,
nodes: &HashMap<String, &El>,
outputs: &[(String, String)],
hops: usize,
warnings: &mut Vec<String>,
) -> Option<Found> {
if hops > 16 {
warnings.push("a node chain is longer than 16 nodes (or loops); skipped".into());
return None;
}
if let Some(value) = input.attr("value") {
return parse_numbers(value)
.map(|values| Found { value: Value::Constant { values, colorspace: input.attr("colorspace").map(str::to_owned) }, tiling: None });
}
let target = if let Some(graph) = input.attr("nodegraph") {
let selected = match input.attr("output") {
Some(output) => outputs.iter().rev().find(|(k, _)| k == &format!("{graph}/{output}")),
None => outputs.iter().find(|(k, _)| k.starts_with(&format!("{graph}/"))),
};
selected.map(|(_, node)| node.clone())
} else if let Some(name) = input.attr("nodename") {
let qualified = scope.map(|g| format!("{g}/{name}"));
qualified.filter(|q| nodes.contains_key(q)).or_else(|| Some(name.to_owned()))
} else {
None
}?;
let node = nodes.get(&target).copied()?;
let node_scope = target.split_once('/').map(|(g, _)| g);
match node.name.as_str() {
"image" | "tiledimage" => {
let file = node.children("input").find(|i| i.attr("name") == Some("file")).and_then(|i| i.attr("value"))?;
let prefix = node
.children("input")
.find(|i| i.attr("name") == Some("file"))
.and_then(|i| i.attr("fileprefix"))
.or_else(|| node.attr("fileprefix"))
.or_else(|| root.attr("fileprefix"))
.unwrap_or("");
let uv = node
.children("input")
.find(|i| i.attr("name") == Some("uvtiling"))
.and_then(|i| i.attr("value"))
.and_then(parse_numbers)
.filter(|n| n.len() == 2 && n.iter().all(|v| *v > 0.0))
.map(|n| [n[0].clamp(0.001, 1000.0), n[1].clamp(0.001, 1000.0)]);
Some(Found { value: Value::Image(format!("{prefix}{file}")), tiling: uv })
}
"normalmap" | "convert" => node
.children("input")
.find(|i| i.attr("name") == Some("in"))
.and_then(|i| resolve_value(root, i, node_scope, nodes, outputs, hops + 1, warnings)),
"constant" => node
.children("input")
.find(|i| i.attr("name") == Some("value"))
.and_then(|i| resolve_value(root, i, node_scope, nodes, outputs, hops + 1, warnings)),
other => {
warnings.push(format!("a {other} node ({:?}) is not supported; its input was skipped", node.attr("name").unwrap_or("")));
None
}
}
}
/// Writes an OpenPBR MaterialX document for the supplied textures.
///
/// Unknown inputs and duplicate inputs are skipped; the first texture for an input wins. Color
/// spaces are written for color textures only, while data textures are left linear.
pub fn write_open_pbr(name: &str, textures: &[Texture], physical_size_cm: Option<[f32; 2]>) -> String {
let base = node_name(name);
let mut seen = Vec::new();
let selected: Vec<(&Texture, InputKind)> = textures
.iter()
.filter_map(|t| OPENPBR_WRITABLE.iter().find(|(input, _)| *input == t.input).map(|(_, kind)| (t, *kind)))
.filter(|(texture, _)| {
if seen.iter().any(|name: &&str| *name == texture.input) {
false
} else {
seen.push(texture.input.as_str());
true
}
})
.collect();
let has = |input: &str| selected.iter().any(|(texture, _)| texture.input == input);
let mut root = El::new("materialx").with_attr("version", "1.39").with_attr("colorspace", "lin_rec709");
let shader_name = format!("OPBR_{base}");
let mut shader = El::new("open_pbr_surface").with_attr("name", &shader_name).with_attr("type", "surfaceshader");
for (texture, kind) in &selected {
let (ty, node) = match kind {
InputKind::Color => ("color3", image_node_name(&texture.input)),
InputKind::Float => ("float", image_node_name(&texture.input)),
InputKind::Normal => ("vector3", "normalmap".to_owned()),
InputKind::Height => continue,
};
shader.push(El::new("input").with_attr("name", &texture.input).with_attr("type", ty).with_attr("nodename", node));
}
if has("emission_color") {
shader.push(El::new("input").with_attr("name", "emission_luminance").with_attr("type", "float").with_attr("value", "1"));
}
root.push(shader);
for (texture, kind) in &selected {
let (ty, color) = match kind {
InputKind::Color => ("color3", Some(texture.colorspace.as_str())),
InputKind::Normal => ("vector3", None),
InputKind::Float | InputKind::Height => ("float", None),
};
let mut image = El::new("tiledimage").with_attr("name", image_node_name(&texture.input)).with_attr("type", ty);
let mut file = El::new("input").with_attr("name", "file").with_attr("type", "filename").with_attr("value", &texture.file);
if let Some(space) = color {
file.set_attr("colorspace", space);
}
image.push(file);
root.push(image);
}
if has("geometry_normal") {
root.push(El::new("normalmap").with_attr("name", "normalmap").with_attr("type", "vector3").with_child(
El::new("input").with_attr("name", "in").with_attr("type", "vector3").with_attr("nodename", image_node_name("geometry_normal")),
));
}
if has("height") {
root.push(
El::new("displacement")
.with_attr("name", format!("DISP_{base}"))
.with_attr("type", "displacementshader")
.with_child(
El::new("input").with_attr("name", "displacement").with_attr("type", "float").with_attr("nodename", image_node_name("height")),
)
.with_child(El::new("input").with_attr("name", "scale").with_attr("type", "float").with_attr("value", "1")),
);
}
let mut material = El::new("surfacematerial").with_attr("name", &base).with_attr("type", "material");
if let Some([width, height]) = physical_size_cm.filter(|[w, h]| w.is_finite() && h.is_finite()) {
material.set_attr("doc", format!("Tiles every {width} x {height} cm"));
}
material.push(El::new("input").with_attr("name", "surfaceshader").with_attr("type", "surfaceshader").with_attr("nodename", shader_name));
if has("height") {
material.push(
El::new("input")
.with_attr("name", "displacementshader")
.with_attr("type", "displacementshader")
.with_attr("nodename", format!("DISP_{base}")),
);
}
root.push(material);
format!("{}{}", craft_xml::DECL, root.to_xml_pretty(" "))
}
fn image_node_name(input: &str) -> String {
format!("image_{}", node_name(input))
}
fn node_name(name: &str) -> String {
let mut out: String = name.chars().map(|c| if c.is_ascii_alphanumeric() || c == '_' { c } else { '_' }).collect();
if out.is_empty() || out.starts_with(|c: char| c.is_ascii_digit()) {
out.insert(0, '_');
}
out
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn parses_and_serializes_a_materialx_document() {
let doc = Document::parse(br#"<materialx version="1.39"><surfacematerial name="mat"/></materialx>"#).unwrap();
assert_eq!(doc.root().attr("version"), Some("1.39"));
let roundtrip = Document::parse(doc.to_xml().as_bytes()).unwrap();
assert_eq!(roundtrip, doc);
}
#[test]
fn graph_outputs_keep_source_order_and_named_selection() {
let doc = Document::parse(
br#"<materialx><nodegraph name="g"><output name="second" nodename="b"/><output name="first" nodename="a"/></nodegraph></materialx>"#,
)
.unwrap();
assert_eq!(doc.output("g", None).and_then(|o| o.attr("name")), Some("second"));
assert_eq!(doc.output("g", Some("first")).and_then(|o| o.attr("nodename")), Some("a"));
}
#[test]
fn duplicate_named_outputs_keep_last_definition() {
let doc = Document::parse(
br#"<materialx><nodegraph name="g"><output name="o" nodename="first"/><output name="o" nodename="last"/></nodegraph></materialx>"#,
)
.unwrap();
assert_eq!(doc.output("g", None).and_then(|o| o.attr("nodename")), Some("first"));
assert_eq!(doc.output("g", Some("o")).and_then(|o| o.attr("nodename")), Some("last"));
}
#[test]
fn rejects_wrong_root_doctypes_and_oversized_documents() {
assert_eq!(Document::parse(b"<root/>").err(), Some(Error::Root));
assert!(Document::parse(b"<!DOCTYPE materialx [<!ENTITY x 'y'>]><materialx/>").is_err());
assert!(matches!(Document::parse(&vec![b' '; MAX_BYTES + 1]), Err(Error::Xml(XmlError::TooLarge(_)))));
}
#[test]
fn resolves_openpbr_values_images_graphs_and_displacement() {
let doc = Document::parse(br#"<materialx fileprefix="tex/">
<open_pbr_surface name="S" type="surfaceshader">
<input name="base_color" type="color3" nodename="C"/>
<input name="geometry_normal" type="vector3" nodename="N"/>
<input name="emission_color" type="color3" value="1,0.5,0.25"/>
<input name="emission_luminance" type="float" value="1"/>
</open_pbr_surface>
<tiledimage name="C" type="color3"><input name="file" value="albedo.png"/><input name="uvtiling" value="2,4"/></tiledimage>
<normalmap name="N" type="vector3"><input name="in" nodegraph="g"/></normalmap>
<nodegraph name="g"><image name="normal" type="vector3"><input name="file" value="normal.png"/></image><image name="other" type="vector3"><input name="file" value="wrong.png"/></image><output name="first" nodename="normal"/><output name="second" nodename="other"/></nodegraph>
<displacement name="D" type="displacementshader"><input name="displacement" value="0.25"/></displacement>
<surfacematerial name="M" type="material"><input name="surfaceshader" nodename="S"/><input name="displacementshader" nodename="D"/></surfacematerial>
</materialx>"#).unwrap();
let material = doc.read_material(None).unwrap();
assert_eq!(material.name, "M");
assert_eq!(material.shader, Shader::OpenPbr);
assert_eq!(material.inputs[0], ("base_color".into(), Value::Image("tex/albedo.png".into())));
assert_eq!(material.inputs[1], ("geometry_normal".into(), Value::Image("tex/normal.png".into())));
assert_eq!(material.inputs[2].1, Value::Constant { values: vec![1.0, 0.5, 0.25], colorspace: None });
assert_eq!(material.displacement, Some(Value::Constant { values: vec![0.25], colorspace: None }));
assert_eq!(material.uv_tiling, [2.0, 4.0]);
}
#[test]
fn openpbr_writer_emits_texture_connections_and_roundtrips() {
let textures = vec![
Texture { input: "base_color".into(), file: "albedo<&.png".into(), colorspace: "srgb_texture".into() },
Texture { input: "specular_roughness".into(), file: "rough.png".into(), colorspace: "ignored".into() },
Texture { input: "geometry_normal".into(), file: "normal.png".into(), colorspace: "ignored".into() },
Texture { input: "height".into(), file: "height.png".into(), colorspace: "ignored".into() },
];
let xml = write_open_pbr("Stone", &textures, Some([100.0, 50.0]));
let doc = Document::parse(xml.as_bytes()).unwrap();
let material = doc.read_material(None).unwrap();
assert_eq!(material.name, "Stone");
assert_eq!(material.inputs[0], ("base_color".into(), Value::Image("albedo<&.png".into())));
assert_eq!(material.inputs[1], ("specular_roughness".into(), Value::Image("rough.png".into())));
assert_eq!(material.inputs[2], ("geometry_normal".into(), Value::Image("normal.png".into())));
assert_eq!(material.displacement, Some(Value::Image("height.png".into())));
assert!(xml.contains("colorspace=\"srgb_texture\""));
assert!(xml.contains("doc=\"Tiles every 100 x 50 cm\""));
assert!(!xml.contains("colorspace=\"ignored\""));
}
}
+13
View File
@@ -563,6 +563,19 @@ fn materials(j: &Value, limits: &Limits, scene: &mut Scene) -> Result<()> {
_ => Wrap::Repeat,
};
let images = scene.images.len();
let texture_list = arr(j, "textures");
if texture_list.len() > limits.max_materials {
return Err(too_large(KIND, format!("more than {} textures", limits.max_materials)));
}
scene.texture_variants = texture_list
.iter()
.filter_map(|texture| {
let sampler = idx(texture, "sampler").and_then(|s| arr(j, "samplers").get(s));
let webp = || texture.get("extensions").and_then(|e| e.get("EXT_texture_webp")).and_then(|e| idx(e, "source"));
let image = idx(texture, "source").or_else(webp).filter(|i| *i < images)?;
Some(TextureRef { image, uv_set: 0, wrap: [wrap(sampler, "wrapS"), wrap(sampler, "wrapT")] })
})
.collect();
let tref = |v: Option<&Value>| -> Option<TextureRef> {
let v = v?;
let texture = arr(j, "textures").get(idx(v, "index")?)?;
+6
View File
@@ -621,6 +621,9 @@ pub struct Scene {
pub meshes: Vec<Mesh>,
pub materials: Vec<Material>,
pub images: Vec<Image>,
/// Texture and sampler entries in the file, including ones no material uses. Their image
/// index and wrap modes are format properties; UV sets belong to each material slot.
pub texture_variants: Vec<TextureRef>,
/// Every format fills this: a format without a hierarchy gets one root node per mesh.
pub nodes: Vec<Node>,
/// The top-level nodes.
@@ -684,6 +687,9 @@ impl Scene {
return bad(format!("material `{}` names an image that does not exist", m.name));
}
}
if self.texture_variants.iter().any(|t| t.image >= self.images.len()) {
return bad("a texture names an image that does not exist".into());
}
let n = self.nodes.len();
for node in &self.nodes {
let refs =
+5
View File
@@ -79,6 +79,11 @@ fn validate_catches_what_writers_cannot_take() {
s.validate().unwrap();
s.meshes[0].parts[0].material = Some(0);
assert!(s.validate().is_err());
let mut s = Scene::default();
s.texture_variants.push(TextureRef::default());
assert!(s.validate().is_err(), "a texture references a missing image");
s.images.push(Image::default());
s.validate().unwrap();
let mut s = Scene::from_meshes(vec![tri_mesh()], vec![]);
s.nodes[0].children.push(7);
assert!(s.validate().is_err());
+24
View File
@@ -194,6 +194,30 @@ fn embedded_and_external_resources() {
assert!(parse(&gltf_text("data:;base64,!!!", "x.png").0).is_err());
}
#[test]
fn texture_and_sampler_inventory_includes_unreferenced_entries() {
let doc = serde_json::to_vec(&json!({
"asset": {"version": "2.0"},
"images": [{"uri": "image.png"}],
"samplers": [{"wrapS": 33071, "wrapT": 33648}],
"textures": [
{"source": 0, "sampler": 0},
{"source": 0}
]
}))
.unwrap();
let scene = read(&doc, &Limits::default(), &mut |_| Some(vec![])).unwrap();
assert_eq!(
scene.texture_variants,
[TextureRef { image: 0, uv_set: 0, wrap: [Wrap::Clamp, Wrap::Mirror] }, TextureRef { image: 0, uv_set: 0, wrap: [Wrap::Repeat; 2] },]
);
assert!(scene.validate().is_ok());
let mut invalid = scene;
invalid.texture_variants[0].image = invalid.images.len();
assert!(matches!(invalid.validate(), Err(Error::Malformed(_))));
}
#[test]
fn base64_and_uri_decoding() {
assert_eq!(base64_decode("aGVsbG8=").unwrap(), b"hello");
+32 -5
View File
@@ -1295,13 +1295,35 @@ impl Canvas {
}
}
/// An 8×8 hatch tile (HS_HORIZONTAL, HS_VERTICAL, HS_FDIAGONAL, HS_BDIAGONAL, HS_CROSS,
/// HS_DIAGCROSS): one-pixel lines in `fg` over `bg`, or over nothing when the background is
/// transparent. None for an unknown style.
/// An 8×8 GDI hatch tile (HS_HORIZONTAL through HS_DIAGCROSS). None for an unknown GDI style.
pub(crate) fn hatch_tile(style: u32, fg: [u8; 4], bg: Option<[u8; 4]>) -> Option<Vec<u8>> {
if style > 5 {
hatch_tile_inner(style, fg, bg, false)
}
/// An 8×8 GDI+ tile for the six basic and twelve percentage HatchStyle values. Percentage styles
/// use a Bayer tile with the specified foreground coverage. Other GDI+ styles still use the
/// fallback in `emfplus::Painter::fill` until their patterns have been mapped.
pub(crate) fn emfplus_hatch_tile(style: u32, fg: [u8; 4], bg: Option<[u8; 4]>) -> Option<Vec<u8>> {
hatch_tile_inner(style, fg, bg, true)
}
fn hatch_tile_inner(style: u32, fg: [u8; 4], bg: Option<[u8; 4]>, gdi_plus: bool) -> Option<Vec<u8>> {
if style > if gdi_plus { 17 } else { 5 } {
return None;
}
// An 8×8 Bayer matrix keeps percentage hatches evenly distributed in a small, repeatable
// tile. The twelve values are GDI+'s Percent05 through Percent90 styles.
const BAYER: [[u8; 8]; 8] = [
[0, 48, 12, 60, 3, 51, 15, 63],
[32, 16, 44, 28, 35, 19, 47, 31],
[8, 56, 4, 52, 11, 59, 7, 55],
[40, 24, 36, 20, 43, 27, 39, 23],
[2, 50, 14, 62, 1, 49, 13, 61],
[34, 18, 46, 30, 33, 17, 45, 29],
[10, 58, 6, 54, 9, 57, 5, 53],
[42, 26, 38, 22, 41, 25, 37, 21],
];
const PERCENT: [u32; 12] = [5, 10, 20, 25, 30, 40, 50, 60, 70, 75, 80, 90];
let mut px = Vec::with_capacity(8 * 8 * 4);
for y in 0..8u32 {
for x in 0..8u32 {
@@ -1312,7 +1334,12 @@ pub(crate) fn hatch_tile(style: u32, fg: [u8; 4], bg: Option<[u8; 4]>) -> Option
2 => f,
3 => b,
4 => h || v,
_ => f || b,
5 => f || b,
6..=17 if gdi_plus => {
let count = (PERCENT[(style - 6) as usize] * 64 + 50) / 100;
u32::from(BAYER[y as usize][x as usize]) < count
}
_ => return None,
};
px.extend(if on { fg } else { bg.unwrap_or([0, 0, 0, 0]) });
}
+5 -3
View File
@@ -27,7 +27,7 @@
use std::sync::Arc;
use crate::bytes::Bytes;
use crate::canvas::{BS_NULL, BS_SOLID, Brush, Canvas, LogFont, PS_NULL, Pen, RawTile, Xform, hatch_tile, mul};
use crate::canvas::{BS_NULL, BS_SOLID, Brush, Canvas, LogFont, PS_NULL, Pen, RawTile, Xform, emfplus_hatch_tile, mul};
use crate::canvas::{Raw, RawClip};
use crate::cliprect::{MAX_AREA_CLIP_WORK, clip_polygon_within, convex, flatten, ops_bbox, pts_bbox, rect_poly};
use crate::dib::Rgba;
@@ -845,9 +845,11 @@ impl Painter {
cv.set_brush(Brush::new(BS_SOLID, *c));
cv.shape(ops.to_vec(), true, false);
}
Fill::Hatch { style, fg, bg } => match hatch_tile(*style, *fg, Some(*bg)) {
Fill::Hatch { style, fg, bg } => match emfplus_hatch_tile(*style, *fg, Some(*bg)) {
Some(px) => cv.tile_shape(ops, Arc::new(RawTile { w: 8, h: 8, px, cell: cv.pattern_px })),
// GDI+ has many more hatch styles than GDI: those fill with the blend of both colours.
// Percentage styles are tiled above. The remaining GDI+ hatch styles have no tile
// mapping yet, so keep the existing blended-colour fallback instead of inventing
// a pattern that could disagree with the file.
None => {
cv.set_brush(Brush::new(BS_SOLID, lerp(*fg, *bg, 0.5)));
cv.shape(ops.to_vec(), true, false);
+27 -2
View File
@@ -2237,10 +2237,35 @@ fn emfplus_linear_gradient_fills_with_a_shaded_tile() {
#[test]
fn emfplus_hatch_brush_fills_with_an_8x8_tile() {
let brush = cat(vec![h32(0xDBC0_1002), h32(1), h32(4), h32(0xFF00_0000), h32(0xFFFF_FFFF)]);
// GDI+ HatchStyle.Percent50 (12), as used by System.Drawing's HatchBrush.
let brush = cat(vec![h32(0xDBC0_1002), h32(1), h32(12), h32(0xFF00_0000), h32(0xFFFF_FFFF)]);
let fill = prec(0x400A, 0, &cat(vec![h32(0), h32(1), f32s(&[0.0, 0.0, 16.0, 16.0])]));
let p = plus_pic(vec![prec(0x4008, 0x0100, &brush), fill]);
assert!(matches!(&p.items[0], Item::Pattern { tile, .. } if tile.width == 8 && tile.height == 8));
let tile = pattern_of(&p.items[0]);
assert_eq!((tile.width, tile.height), (8, 8));
let foreground = tile.rgba.as_chunks::<4>().0.iter().filter(|px| **px == [0, 0, 0, 255]).count();
assert_eq!(foreground, 32, "Percent50 uses equal foreground and background coverage");
}
#[test]
fn gdi_plus_percentage_hatch_styles_keep_the_documented_coverage() {
const PERCENT: [usize; 12] = [5, 10, 20, 25, 30, 40, 50, 60, 70, 75, 80, 90];
let fg = [0, 0, 0, 255];
let bg = [255, 255, 255, 255];
for style in 0..=17 {
let tile = crate::canvas::emfplus_hatch_tile(style, fg, Some(bg)).expect("supported GDI+ hatch style");
let foreground = tile.as_chunks::<4>().0.iter().filter(|px| **px == fg).count();
assert!((1..64).contains(&foreground), "style {style} should mix both colours");
if (6..=17).contains(&style) {
let percent = PERCENT[(style - 6) as usize];
assert_eq!(foreground, (percent * 64 + 50) / 100, "percentage style {style}");
}
}
for style in 18..=52 {
assert!(crate::canvas::emfplus_hatch_tile(style, fg, Some(bg)).is_none(), "style {style} has no confirmed tile mapping");
}
assert!(crate::canvas::emfplus_hatch_tile(53, fg, Some(bg)).is_none(), "out-of-range values stay unsupported");
assert!(crate::canvas::hatch_tile(9, fg, Some(bg)).is_none(), "GDI's six-style range is unchanged");
}
#[test]
+19
View File
@@ -0,0 +1,19 @@
[package]
name = "craft-pcraft-bundle"
description = "Bounded ZIP and directory storage for .pcraft manifests, previews and content-addressed objects"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
craft-pcraft-format = { workspace = true }
craft-atomic = { workspace = true }
craft-zip = { workspace = true }
thiserror = { workspace = true }
ruzstd = { version = "0.9.1", default-features = false, features = ["std"] }
blake3 = { version = "1.8", default-features = false, features = ["pure"] }
+654
View File
@@ -0,0 +1,654 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
//! Container and content-addressed object storage for `.pcraft` bundles.
//!
//! Document schemas stay with the application. This crate owns the wire-level paths, ZIP
//! envelope, zstd object frames and content hashes. A caller supplies serialized manifest bytes
//! and opaque tile/blob bytes; it receives their stable paths to put in its manifest.
use std::collections::{BTreeMap, HashMap, HashSet};
use std::fs::{self, OpenOptions};
use std::io::Read;
use std::path::{Path, PathBuf};
use std::time::{Duration, Instant, SystemTime};
use craft_zip::{Archive, Compression, Writer};
/// Default bounds for opening an untrusted `.pcraft` ZIP.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Limits {
/// Maximum number of ZIP entries.
pub max_entries: u64,
/// Maximum total uncompressed ZIP bytes read.
pub max_total_bytes: u64,
/// Maximum manifest size.
pub max_manifest_bytes: u64,
/// Maximum compressed object bytes.
pub max_object_bytes: u64,
/// Maximum decoded object bytes.
pub max_decoded_object_bytes: u64,
}
impl Default for Limits {
fn default() -> Self {
let limits = craft_pcraft_format::Limits::default();
Self {
max_entries: limits.max_items as u64 + 4,
max_total_bytes: limits.max_total_bytes,
max_manifest_bytes: limits.max_manifest_bytes as u64,
max_object_bytes: limits.max_blob_bytes as u64,
max_decoded_object_bytes: limits.max_blob_bytes as u64,
}
}
}
/// Why a `.pcraft` container or object could not be read or written.
#[derive(Debug, thiserror::Error)]
pub enum Error {
/// A path is not one of the bundle's canonical entry names.
#[error("invalid .pcraft entry path: {0}")]
InvalidPath(String),
/// An entry is missing, duplicated or violates a bundle invariant.
#[error("invalid .pcraft bundle: {0}")]
InvalidBundle(String),
/// An entry exceeds its caller-supplied bound.
#[error("{entry} exceeds the {limit}-byte limit")]
LimitExceeded { entry: String, limit: u64 },
/// The object's content hash does not match its entry path.
#[error("content hash mismatch for {0}")]
HashMismatch(String),
/// ZIP container error.
#[error(transparent)]
Zip(#[from] craft_zip::Error),
/// I/O or zstd decoding error.
#[error("{0}")]
Io(String),
}
pub type Result<T> = std::result::Result<T, Error>;
/// Whether a ZIP archive declares a `manifest.json` entry.
pub fn is_pcraft_zip(bytes: &[u8]) -> bool {
if !bytes.starts_with(b"PK\x03\x04") {
return false;
}
let limits = Limits { max_entries: 1_000_000, ..Limits::default() };
Archive::open(bytes, craft_zip::Limits { max_entries: limits.max_entries, max_total_bytes: 0 })
.is_ok_and(|archive| !archive.has_duplicate_names() && archive.contains(craft_pcraft_format::MANIFEST))
}
/// Whether an entry path is a canonical manifest, preview, tile or blob path.
pub fn valid_entry_path(path: &str) -> bool {
if matches!(
path,
craft_pcraft_format::MANIFEST | craft_pcraft_format::THUMB | craft_pcraft_format::COMPOSITE | craft_pcraft_format::FULL_COMPOSITE
) {
return true;
}
let Some((kind, name)) = path.split_once('/') else { return false };
let Some(hash) = name.strip_suffix(craft_pcraft_format::OBJECT_SUFFIX) else { return false };
craft_pcraft_format::is_valid_hash(hash) && (kind == craft_pcraft_format::TILES_DIR || kind == craft_pcraft_format::BLOBS_DIR)
}
/// Content-addressed, compressed object bytes and their canonical bundle path.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct StoredObject {
/// `tiles/<hash>.zst` or `blobs/<hash>.zst`.
pub path: String,
/// BLAKE3 of the uncompressed bytes.
pub hash: String,
/// Zstandard frame containing the uncompressed bytes.
pub compressed: Vec<u8>,
}
/// The kind of content-addressed object being stored.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub enum ObjectKind {
/// Pixel tile samples.
Tile,
/// ICC, metadata, masks, or other opaque document data.
Blob,
}
/// Hashes and compresses an object, returning the path to record in the manifest.
pub fn encode_object(kind: ObjectKind, bytes: &[u8]) -> StoredObject {
let hash = hash_content(bytes);
let path = match kind {
ObjectKind::Tile => craft_pcraft_format::tile_path(&hash),
ObjectKind::Blob => craft_pcraft_format::blob_path(&hash),
}
.unwrap_or_default();
let compressed = encode_frame(bytes);
StoredObject { path, hash, compressed }
}
/// BLAKE3 hash of object bytes, in the canonical lowercase hexadecimal form used by entry paths.
pub fn hash_content(bytes: &[u8]) -> String {
blake3::hash(bytes).to_hex().to_string()
}
/// Encodes one bounded zstd frame at the format's fixed fastest compression level.
pub fn encode_frame(bytes: &[u8]) -> Vec<u8> {
ruzstd::encoding::compress_to_vec(bytes, ruzstd::encoding::CompressionLevel::Fastest)
}
/// Decodes one zstd frame under a byte limit and optional exact output length.
pub fn decode_frame(data: &[u8], max_bytes: usize, exact_bytes: Option<usize>, name: &str) -> Result<Vec<u8>> {
let window = u64::try_from(exact_bytes.unwrap_or(max_bytes)).unwrap_or(u64::MAX).max(8 << 20);
let mut decoder = match ruzstd::decoding::StreamingDecoder::new_with_max_window_size(data, window) {
Ok(decoder) => decoder,
Err(ruzstd::decoding::errors::FrameDecoderError::WindowSizeTooBig { requested, .. }) => {
return Err(Error::LimitExceeded { entry: format!("{name} zstd window ({requested})"), limit: window });
}
Err(error) => return Err(Error::Io(format!("{name}: zstd: {error}"))),
};
let mut out = Vec::new();
let read_limit = u64::try_from(max_bytes).unwrap_or(u64::MAX).saturating_add(1);
(&mut decoder).take(read_limit).read_to_end(&mut out).map_err(|error| Error::Io(format!("{name}: zstd: {error}")))?;
if out.len() > max_bytes {
return Err(Error::LimitExceeded { entry: name.to_owned(), limit: max_bytes as u64 });
}
if let Some(expected) = exact_bytes
&& out.len() != expected
{
return Err(Error::InvalidBundle(format!("{name}: expected {expected} bytes, got {}", out.len())));
}
Ok(out)
}
/// Decompresses a stored object within `max_decoded_bytes` and checks its content hash.
pub fn decode_object(path: &str, compressed: &[u8], max_decoded_bytes: u64) -> Result<Vec<u8>> {
if !valid_object_path(path) {
return Err(Error::InvalidPath(path.to_owned()));
}
let max = usize::try_from(max_decoded_bytes).unwrap_or(usize::MAX);
let decoder = ruzstd::decoding::StreamingDecoder::new(compressed).map_err(|e| Error::Io(e.to_string()))?;
let mut bytes = Vec::new();
decoder.take(max_decoded_bytes.saturating_add(1)).read_to_end(&mut bytes).map_err(|e| Error::Io(e.to_string()))?;
if bytes.len() > max {
return Err(Error::LimitExceeded { entry: path.to_owned(), limit: max_decoded_bytes });
}
let expected = path.rsplit('/').next().unwrap_or_default().trim_end_matches(craft_pcraft_format::OBJECT_SUFFIX);
if hash_content(&bytes) != expected {
return Err(Error::HashMismatch(path.to_owned()));
}
Ok(bytes)
}
fn valid_object_path(path: &str) -> bool {
let Some((kind, _)) = path.split_once('/') else { return false };
(kind == craft_pcraft_format::TILES_DIR || kind == craft_pcraft_format::BLOBS_DIR) && valid_entry_path(path)
}
/// An in-memory `.pcraft` ZIP reader with bounded entry and total reads.
pub struct ZipBundle<'a> {
archive: Archive<'a>,
limits: Limits,
}
impl<'a> ZipBundle<'a> {
/// Opens a bundle, rejecting duplicate entry names and archives without a manifest.
pub fn open(bytes: &'a [u8], limits: Limits) -> Result<Self> {
let archive = Archive::open(bytes, craft_zip::Limits { max_entries: limits.max_entries, max_total_bytes: limits.max_total_bytes })?;
if archive.has_duplicate_names() || !archive.contains(craft_pcraft_format::MANIFEST) {
return Err(Error::InvalidBundle("missing manifest or duplicate entry names".into()));
}
Ok(Self { archive, limits })
}
/// Reads the serialized document manifest.
pub fn manifest(&mut self) -> Result<Vec<u8>> {
self.read(craft_pcraft_format::MANIFEST, self.limits.max_manifest_bytes)
}
/// Reads any canonical bundle entry, including the stored zstd bytes of an object.
pub fn entry(&mut self, path: &str, max_bytes: u64) -> Result<Option<Vec<u8>>> {
if !valid_entry_path(path) {
return Err(Error::InvalidPath(path.to_owned()));
}
self.archive.read(path, max_bytes).map_err(Into::into)
}
/// Reads an optional preview entry.
pub fn preview(&mut self, path: &str) -> Result<Option<Vec<u8>>> {
if !matches!(path, craft_pcraft_format::THUMB | craft_pcraft_format::COMPOSITE | craft_pcraft_format::FULL_COMPOSITE) {
return Err(Error::InvalidPath(path.to_owned()));
}
self.archive.read(path, self.limits.max_object_bytes).map_err(Into::into)
}
/// Reads and verifies a compressed content-addressed object.
pub fn object(&mut self, path: &str) -> Result<Vec<u8>> {
let compressed = self.read(path, self.limits.max_object_bytes)?;
decode_object(path, &compressed, self.limits.max_decoded_object_bytes)
}
fn read(&mut self, path: &str, limit: u64) -> Result<Vec<u8>> {
if !valid_entry_path(path) {
return Err(Error::InvalidPath(path.to_owned()));
}
self.archive.read(path, limit)?.ok_or_else(|| Error::InvalidBundle(format!("missing {path}")))
}
}
/// Builds a deterministic STORE ZIP bundle from format-neutral entries.
#[derive(Default)]
pub struct ZipBundleWriter {
entries: BTreeMap<String, Vec<u8>>,
}
impl ZipBundleWriter {
/// Adds or replaces the manifest bytes.
pub fn set_manifest(&mut self, manifest: Vec<u8>) -> Result<()> {
if manifest.is_empty() {
return Err(Error::InvalidBundle("manifest is empty".into()));
}
self.entries.insert(craft_pcraft_format::MANIFEST.into(), manifest);
Ok(())
}
/// Adds an optional preview.
pub fn set_preview(&mut self, path: &str, bytes: Vec<u8>) -> Result<()> {
if !matches!(path, craft_pcraft_format::THUMB | craft_pcraft_format::COMPOSITE | craft_pcraft_format::FULL_COMPOSITE) {
return Err(Error::InvalidPath(path.to_owned()));
}
self.entries.insert(path.to_owned(), bytes);
Ok(())
}
/// Adds a compressed content-addressed object, returning its manifest path.
pub fn add_object(&mut self, kind: ObjectKind, bytes: &[u8]) -> Result<String> {
let object = encode_object(kind, bytes);
if object.path.is_empty() {
return Err(Error::InvalidBundle("could not construct object path".into()));
}
self.entries.entry(object.path.clone()).or_insert(object.compressed);
Ok(object.path)
}
/// Adds an already-compressed object after checking its path/hash.
pub fn add_stored_object(&mut self, path: &str, compressed: Vec<u8>, max_decoded_bytes: u64) -> Result<()> {
let _ = decode_object(path, &compressed, max_decoded_bytes)?;
self.stage_compressed_object(path, compressed)
}
/// Stages an already-compressed object for a bundle write. Its path is checked now and its
/// frame/hash are verified by [`Self::finish`] or [`DirectoryBundleWriter::save_directory`].
pub fn stage_compressed_object(&mut self, path: &str, compressed: Vec<u8>) -> Result<()> {
if !valid_object_path(path) {
return Err(Error::InvalidPath(path.to_owned()));
}
self.entries.insert(path.to_owned(), compressed);
Ok(())
}
/// Writes entries in canonical path order, with every ZIP member stored without another layer
/// of compression (object payloads already use zstd).
pub fn finish(self) -> Result<Vec<u8>> {
if !self.entries.contains_key(craft_pcraft_format::MANIFEST) {
return Err(Error::InvalidBundle("manifest not set".into()));
}
let mut writer = Writer::new();
let mut entries = self.entries;
let manifest = entries.remove(craft_pcraft_format::MANIFEST).ok_or_else(|| Error::InvalidBundle("manifest not set".into()))?;
writer.add(craft_pcraft_format::MANIFEST, &manifest, Compression::Stored)?;
for (path, bytes) in entries {
if !valid_entry_path(&path) {
return Err(Error::InvalidPath(path));
}
if is_object_path(&path) {
let _ = decode_object(&path, &bytes, 1 << 30)?;
}
writer.add(&path, &bytes, Compression::Stored)?;
}
writer.finish().map_err(Into::into)
}
/// Saves the same entries as a directory bundle. Object files are published before the
/// manifest, the bundle lock serializes writers, and unreferenced canonical objects are
/// collected after the new manifest is durable.
pub fn save_directory(self, root: &Path) -> Result<DirectoryStats> {
DirectoryBundleWriter::default().save_directory(root, self)
}
}
/// Work performed by a directory bundle save.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct DirectoryStats {
/// Entries atomically written, including `manifest.json`.
pub written: usize,
/// Stale content-addressed objects collected after manifest publication.
pub removed: usize,
/// Existing, verified content-addressed objects reused without writing.
pub reused: usize,
/// Canonical object paths written during this save.
pub written_objects: Vec<String>,
/// Canonical object paths reused after verification or a matching cached signature.
pub reused_objects: Vec<String>,
}
/// Incremental directory-bundle persistence with bounded rolling object verification.
pub struct DirectoryBundleWriter {
root: Option<PathBuf>,
generation: u64,
reverify_budget: u64,
lock_wait: Duration,
verified: HashMap<String, CachedFile>,
}
impl Default for DirectoryBundleWriter {
fn default() -> Self {
Self { root: None, generation: 0, reverify_budget: 16 << 20, lock_wait: Duration::from_secs(10), verified: HashMap::new() }
}
}
#[derive(Clone, Copy)]
struct CachedFile {
signature: FileSignature,
checked_at: u64,
}
#[derive(Clone, Copy, PartialEq, Eq)]
struct FileSignature {
len: u64,
modified: SystemTime,
#[cfg(unix)]
unix: (u64, u64, i64, i64),
}
impl DirectoryBundleWriter {
/// Compressed bytes of already-verified objects to re-read on each save.
/// `0` trusts unchanged signatures; `u64::MAX` rechecks all referenced objects.
pub fn set_reverify_budget(&mut self, bytes: u64) {
self.reverify_budget = bytes;
}
/// How long to wait for another writer to release the bundle lock.
pub fn set_lock_wait(&mut self, wait: Duration) {
self.lock_wait = wait;
}
/// Saves an entry set incrementally. Existing objects are reused only after a hash check;
/// unchanged file signatures may skip checks until they enter the rolling verification
/// window. The manifest is atomically published last, then stale previews and objects are
/// collected while the bundle lock is held.
pub fn save_directory(&mut self, root: &Path, bundle: ZipBundleWriter) -> Result<DirectoryStats> {
if !bundle.entries.contains_key(craft_pcraft_format::MANIFEST) {
return Err(Error::InvalidBundle("manifest not set".into()));
}
for path in bundle.entries.keys() {
if !valid_entry_path(path) {
return Err(Error::InvalidPath(path.clone()));
}
}
fs::create_dir_all(root).map_err(io_error)?;
let root = fs::canonicalize(root).map_err(io_error)?;
if self.root.as_ref() != Some(&root) {
self.root = Some(root.clone());
self.verified.clear();
self.generation = 0;
}
let lock_path = root.join(craft_pcraft_format::SAVE_LOCK);
refuse_symlink(&lock_path)?;
let lock = OpenOptions::new().read(true).write(true).create(true).truncate(false).open(&lock_path).map_err(io_error)?;
let start = Instant::now();
let _lock = loop {
match lock.try_lock() {
Ok(()) => break Some(lock),
Err(std::fs::TryLockError::WouldBlock) if start.elapsed() < self.lock_wait => std::thread::sleep(Duration::from_millis(20)),
Err(std::fs::TryLockError::WouldBlock) => {
return Err(Error::Io("another save of this bundle is in progress".into()));
}
Err(std::fs::TryLockError::Error(_)) => break None,
}
};
self.generation = self.generation.saturating_add(1);
let generation = self.generation;
let recheck = self.rolling_recheck(&bundle.entries);
let mut stats = DirectoryStats::default();
for (path, bytes) in bundle.entries.iter().filter(|(path, _)| is_object_path(path)) {
let target = safe_target(&root, path)?;
if let Some(parent) = target.parent() {
ensure_directory(parent)?;
}
refuse_symlink(&target)?;
if let Some(signature) = file_signature(&target)? {
let cached = self.verified.get(path).is_some_and(|entry| entry.signature == signature);
if cached && !recheck.contains(path) {
stats.reused = stats.reused.saturating_add(1);
stats.reused_objects.push(path.clone());
continue;
}
let existing = read_bounded(&target, 1 << 30)?;
if decode_object(path, &existing, 1 << 30).is_ok() {
if let Some(signature) = file_signature(&target)? {
self.verified.insert(path.clone(), CachedFile { signature, checked_at: generation });
}
stats.reused = stats.reused.saturating_add(1);
stats.reused_objects.push(path.clone());
continue;
}
}
let _ = decode_object(path, bytes, 1 << 30)?;
craft_atomic::atomic_write(&target, bytes).map_err(io_error)?;
if let Some(signature) = file_signature(&target)? {
self.verified.insert(path.clone(), CachedFile { signature, checked_at: generation });
}
stats.written = stats.written.saturating_add(1);
stats.written_objects.push(path.clone());
}
for (path, bytes) in bundle.entries.iter().filter(|(path, _)| !is_object_path(path) && path.as_str() != craft_pcraft_format::MANIFEST) {
let target = safe_target(&root, path)?;
if let Some(parent) = target.parent() {
ensure_directory(parent)?;
}
refuse_symlink(&target)?;
craft_atomic::atomic_write(&target, bytes).map_err(io_error)?;
stats.written = stats.written.saturating_add(1);
}
let manifest = bundle.entries.get(craft_pcraft_format::MANIFEST).ok_or_else(|| Error::InvalidBundle("manifest not set".into()))?;
let manifest_path = root.join(craft_pcraft_format::MANIFEST);
refuse_symlink(&manifest_path)?;
craft_atomic::atomic_write(&manifest_path, manifest).map_err(io_error)?;
stats.written = stats.written.saturating_add(1);
let mut removed_paths = Vec::new();
for kind in [craft_pcraft_format::TILES_DIR, craft_pcraft_format::BLOBS_DIR] {
let dir = root.join(kind);
if !dir.exists() {
continue;
}
refuse_symlink(&dir)?;
for entry in fs::read_dir(&dir).map_err(io_error)? {
let entry = entry.map_err(io_error)?;
let name = entry.file_name();
let path = format!("{kind}/{}", name.to_string_lossy());
if is_object_path(&path) && !bundle.entries.contains_key(&path) {
let metadata = fs::symlink_metadata(entry.path()).map_err(io_error)?;
if metadata.file_type().is_symlink() || !metadata.is_file() {
return Err(Error::InvalidBundle(format!("refusing to collect non-file object {path}")));
}
fs::remove_file(entry.path()).map_err(io_error)?;
removed_paths.push(path);
stats.removed = stats.removed.saturating_add(1);
}
}
}
for path in [craft_pcraft_format::THUMB, craft_pcraft_format::COMPOSITE, craft_pcraft_format::FULL_COMPOSITE] {
if !bundle.entries.contains_key(path) {
let target = root.join(path);
refuse_symlink(&target)?;
if fs::symlink_metadata(&target).is_ok() {
fs::remove_file(&target).map_err(io_error)?;
}
}
}
self.verified.retain(|path, _| bundle.entries.contains_key(path) && !removed_paths.contains(path));
Ok(stats)
}
fn rolling_recheck(&self, entries: &BTreeMap<String, Vec<u8>>) -> HashSet<String> {
if self.reverify_budget == 0 {
return HashSet::new();
}
let mut cached: Vec<(&String, &CachedFile)> = self.verified.iter().filter(|(path, _)| entries.contains_key(*path)).collect();
cached.sort_by(|a, b| a.1.checked_at.cmp(&b.1.checked_at).then_with(|| a.0.cmp(b.0)));
let mut out = HashSet::new();
let mut spent = 0u64;
for (path, value) in cached {
let next = spent.saturating_add(value.signature.len);
if !out.is_empty() && next > self.reverify_budget {
break;
}
spent = next;
out.insert(path.clone());
}
out
}
}
fn is_object_path(path: &str) -> bool {
path.starts_with("tiles/") || path.starts_with("blobs/")
}
fn file_signature(path: &Path) -> Result<Option<FileSignature>> {
let metadata = match fs::symlink_metadata(path) {
Ok(metadata) if metadata.is_file() && !metadata.file_type().is_symlink() => metadata,
Ok(_) => return Err(Error::InvalidBundle(format!("{} is not a regular file", path.display()))),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(error) => return Err(io_error(error)),
};
let modified = metadata.modified().unwrap_or(SystemTime::UNIX_EPOCH);
#[cfg(unix)]
let unix = {
use std::os::unix::fs::MetadataExt;
(metadata.dev(), metadata.ino(), metadata.ctime(), metadata.ctime_nsec())
};
Ok(Some(FileSignature {
len: metadata.len(),
modified,
#[cfg(unix)]
unix,
}))
}
fn read_bounded(path: &Path, max: u64) -> Result<Vec<u8>> {
let metadata = fs::metadata(path).map_err(io_error)?;
if metadata.len() > max {
return Err(Error::LimitExceeded { entry: path.display().to_string(), limit: max });
}
let bytes = fs::read(path).map_err(io_error)?;
if bytes.len() as u64 > max {
return Err(Error::LimitExceeded { entry: path.display().to_string(), limit: max });
}
Ok(bytes)
}
fn io_error(error: std::io::Error) -> Error {
Error::Io(error.to_string())
}
fn refuse_symlink(path: &Path) -> Result<()> {
match fs::symlink_metadata(path) {
Ok(metadata) if metadata.file_type().is_symlink() => Err(Error::InvalidBundle(format!("refusing symlink {}", path.display()))),
Ok(_) => Ok(()),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => Ok(()),
Err(error) => Err(io_error(error)),
}
}
fn ensure_directory(path: &Path) -> Result<()> {
refuse_symlink(path)?;
match fs::symlink_metadata(path) {
Ok(metadata) if metadata.is_dir() => Ok(()),
Ok(_) => Err(Error::InvalidBundle(format!("{} is not a directory", path.display()))),
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
fs::create_dir(path).map_err(io_error)?;
Ok(())
}
Err(error) => Err(io_error(error)),
}
}
fn safe_target(root: &Path, relative: &str) -> Result<PathBuf> {
if !valid_entry_path(relative) {
return Err(Error::InvalidPath(relative.to_owned()));
}
let mut target = root.to_path_buf();
let components = relative.split('/').collect::<Vec<_>>();
for (index, component) in components.iter().enumerate() {
target.push(component);
if index + 1 < components.len() {
ensure_directory(&target)?;
}
}
Ok(target)
}
/// Opens a directory bundle and reads canonical entries with caller-provided limits.
pub struct DirectoryBundle {
root: PathBuf,
limits: Limits,
}
impl DirectoryBundle {
/// Opens a bundle directory containing a regular `manifest.json`.
pub fn open(root: &Path, limits: Limits) -> Result<Self> {
let root = fs::canonicalize(root).map_err(io_error)?;
let manifest = root.join(craft_pcraft_format::MANIFEST);
refuse_symlink(&manifest)?;
let metadata = fs::metadata(&manifest).map_err(io_error)?;
if !metadata.is_file() || metadata.len() > limits.max_manifest_bytes {
return Err(Error::LimitExceeded { entry: craft_pcraft_format::MANIFEST.into(), limit: limits.max_manifest_bytes });
}
Ok(Self { root, limits })
}
/// Reads the serialized document manifest.
pub fn manifest(&self) -> Result<Vec<u8>> {
self.read(craft_pcraft_format::MANIFEST, self.limits.max_manifest_bytes)
}
/// Reads any canonical bundle entry.
pub fn entry(&self, path: &str, max_bytes: u64) -> Result<Option<Vec<u8>>> {
self.read_optional(path, max_bytes)
}
/// Reads an optional preview entry.
pub fn preview(&self, path: &str) -> Result<Option<Vec<u8>>> {
if !matches!(path, craft_pcraft_format::THUMB | craft_pcraft_format::COMPOSITE | craft_pcraft_format::FULL_COMPOSITE) {
return Err(Error::InvalidPath(path.to_owned()));
}
self.read_optional(path, self.limits.max_object_bytes)
}
/// Reads and verifies a compressed content-addressed object.
pub fn object(&self, path: &str) -> Result<Vec<u8>> {
let compressed = self.read(path, self.limits.max_object_bytes)?;
decode_object(path, &compressed, self.limits.max_decoded_object_bytes)
}
fn read(&self, path: &str, limit: u64) -> Result<Vec<u8>> {
self.read_optional(path, limit)?.ok_or_else(|| Error::InvalidBundle(format!("missing {path}")))
}
fn read_optional(&self, path: &str, limit: u64) -> Result<Option<Vec<u8>>> {
let target = safe_target(&self.root, path)?;
refuse_symlink(&target)?;
let metadata = match fs::metadata(&target) {
Ok(metadata) => metadata,
Err(error) if error.kind() == std::io::ErrorKind::NotFound => return Ok(None),
Err(error) => return Err(io_error(error)),
};
if !metadata.is_file() || metadata.len() > limit {
return Err(Error::LimitExceeded { entry: path.to_owned(), limit });
}
let bytes = fs::read(target).map_err(io_error)?;
if bytes.len() as u64 > limit {
return Err(Error::LimitExceeded { entry: path.to_owned(), limit });
}
Ok(Some(bytes))
}
}
+3 -3
View File
@@ -8,10 +8,10 @@ fn scenes() -> Vec<Scene> {
scene::load_dir(&scene::scenes_dir()).unwrap()
}
/// On CI (`CI` set) the workflow provisions the font, so a scene that left text out fails.
/// Local runs without the font skip text and only note it.
/// When the licensed fixture directory is configured, every scene must write its text.
/// Workflows that do not provision those fixtures can still validate scenes without text.
fn text_must_be_written() -> bool {
std::env::var_os("CI").is_some_and(|v| !v.is_empty() && v != "false")
std::env::var_os(reference::FONT_DIR_ENV).is_some_and(|v| !v.is_empty())
}
fn missing_font(scene: &Scene) -> String {
+1 -1
View File
@@ -242,7 +242,7 @@ fn score(enc: &'static Encoding, name: &[u8], hint_letters: &std::collections::B
// never writes this one, says the writer meant that ("état", not "Žtat").
let written = |c: char| c.to_lowercase().all(|l| hint_letters.contains(&l));
let mac = name.get(i..=i).map(|b| decode(b, MACINTOSH)).and_then(|s| s.chars().next());
word_initial && !(mac.is_some_and(|m| m.is_alphabetic() && written(m)) && !written(ch))
word_initial && (written(ch) || !mac.is_some_and(|m| m.is_alphabetic() && written(m)))
} else if enc == WINDOWS_1251 && is_cyrillic(ch) {
(cyrillic_name && !lone_after_digit(&decoded, i)) || cyrillic_word(&decoded, i)
} else {
+118 -4
View File
@@ -2,19 +2,67 @@
//! without the layer and mask section or any pixels.
//!
//! This is what a file browser or a metadata reader needs (size, depth, colour mode, ICC profile,
//! EXIF, XMP, resolution, thumbnail): a few kilobytes at the start of a file that may be
//! gigabytes long. [`Head::from_source`] reads exactly those bytes; [`Head::from_bytes`] accepts a
//! prefix of the file and reports how many more bytes it needs when the prefix is too short.
//! EXIF, XMP, resolution, thumbnail): a few bytes at the start of a file that may be gigabytes
//! long. [`Head::from_source`] reads exactly those bytes; [`Head::from_bytes`] accepts a prefix of
//! the file and reports how many more bytes it needs when the prefix is too short. Both return
//! owned data. For untrusted files with large resource sections, [`HeadView`] borrows the input
//! and parses resource records lazily.
use crate::error::Result;
use crate::header::Header;
use crate::io::Reader;
use crate::resources::{self, ImageResource};
use crate::resources::{self, ImageResource, ResourceIter};
use crate::source::Source;
/// Length of the file header.
const HEADER_LEN: u64 = 26;
/// A zero-copy view of a PSD/PSB head.
///
/// The header and section lengths are validated eagerly. Colour-mode data and resource records
/// remain borrowed from the input; [`HeadView::resources`] validates one resource at a time and
/// stops at the first malformed record. This avoids cloning unknown or attacker-sized resource
/// payloads and lets callers keep valid records that precede a damaged one.
#[derive(Debug, Clone)]
pub struct HeadView<'a> {
/// The file header.
pub header: Header,
/// The colour mode data section (the palette of an indexed file, duotone or HDR toning data).
pub color_mode_data: &'a [u8],
resources: &'a [u8],
/// Offset in the file of the layer and mask information section (of its length field).
pub layer_section_offset: u64,
}
impl<'a> HeadView<'a> {
/// Parses the fixed header and section bounds from `data` without copying colour data or
/// resources. Individual resource records are validated by the iterator returned from
/// [`HeadView::resources`].
pub fn from_bytes(data: &'a [u8]) -> Result<Self> {
let header = Header::from_bytes(data)?;
let mut r = Reader::new(data);
r.skip(HEADER_LEN as usize)?;
let color_mode_len = r.u32()?;
let color_mode_data = r.bytes_u64(u64::from(color_mode_len))?;
let resource_len = r.u32()?;
let resources = r.bytes_u64(u64::from(resource_len))?;
Ok(HeadView { header, color_mode_data, resources, layer_section_offset: r.pos() as u64 })
}
/// Iterates over resource records without allocating. If a record is malformed, its error is
/// returned once and iteration stops; earlier records remain available to the caller.
pub fn resources(&self) -> ResourceIter<'a> {
ResourceIter::new(self.resources)
}
/// Iterates over at most `max_records` resources. Returns one limit error if additional bytes
/// remain after that many records, then stops. Use this for untrusted files where record
/// processing itself needs a caller-defined work bound.
pub fn resources_limited(&self, max_records: usize) -> ResourceIter<'a> {
ResourceIter::with_limit(self.resources, max_records)
}
}
/// The first three sections of a file. The same values [`crate::PsdFile`] holds in its fields of
/// the same names.
#[derive(Debug, Clone, PartialEq, Eq)]
@@ -132,6 +180,72 @@ mod tests {
}
}
#[test]
fn head_view_borrows_sections_and_records() {
for (file, bytes) in cases() {
let view = HeadView::from_bytes(&bytes).unwrap();
let owned = Head::from_bytes(&bytes).unwrap();
assert_eq!(view.header, owned.header);
assert_eq!(view.color_mode_data, owned.color_mode_data);
assert_eq!(view.layer_section_offset, owned.layer_section_offset);
let bytes_start = bytes.as_ptr() as usize;
let bytes_end = bytes_start + bytes.len();
let color_start = view.color_mode_data.as_ptr() as usize;
assert!(bytes_start <= color_start && color_start + view.color_mode_data.len() <= bytes_end);
let borrowed = view.resources().collect::<Result<Vec<_>>>().unwrap();
assert_eq!(borrowed.iter().map(|r| (*r).into_owned()).collect::<Vec<_>>(), file.resources);
let nonempty = borrowed.iter().find(|r| !r.data.is_empty()).expect("test resource has bytes");
let data_start = nonempty.data.as_ptr() as usize;
assert!(bytes_start <= data_start && data_start + nonempty.data.len() <= bytes_end);
}
}
#[test]
fn head_view_keeps_valid_resources_before_a_malformed_record() {
let (_, mut bytes) = cases().remove(0);
let color_len = u32::from_be_bytes(bytes[26..30].try_into().unwrap()) as usize;
let resource_len_at = 30 + color_len;
let resource_start = resource_len_at + 4;
let name_len = usize::from(bytes[resource_start + 6]);
let name_total = (1 + name_len + 1) & !1;
let data_len_at = resource_start + 6 + name_total;
let data_len = u32::from_be_bytes(bytes[data_len_at..data_len_at + 4].try_into().unwrap()) as usize;
let first_end = data_len_at + 4 + data_len + data_len % 2;
let resource_len = u32::from_be_bytes(bytes[resource_len_at..resource_len_at + 4].try_into().unwrap());
let damaged_record = b"JUNK";
bytes[resource_len_at..resource_len_at + 4].copy_from_slice(&(resource_len + damaged_record.len() as u32).to_be_bytes());
bytes.splice(first_end..first_end, damaged_record.iter().copied());
let view = HeadView::from_bytes(&bytes).unwrap();
let mut resources = view.resources();
let first = resources.next().expect("first valid resource").unwrap();
assert_eq!(first.id, 1005);
assert!(resources.next().expect("malformed second resource").is_err());
assert!(resources.next().is_none(), "iteration stops after the first malformed record");
assert!(Head::from_bytes(&bytes).is_err(), "the strict owned API still rejects malformed resources");
}
#[test]
fn head_view_resource_limit_is_enforced_after_valid_records() {
let (_, mut bytes) = cases().remove(0);
let color_len = u32::from_be_bytes(bytes[26..30].try_into().unwrap()) as usize;
let resource_len_at = 30 + color_len;
let resource_start = resource_len_at + 4;
let resource_len = u32::from_be_bytes(bytes[resource_len_at..resource_start].try_into().unwrap()) as usize;
let duplicate = bytes[resource_start..resource_start + resource_len].to_vec();
bytes[resource_len_at..resource_start].copy_from_slice(&((resource_len * 2) as u32).to_be_bytes());
bytes.splice(resource_start + resource_len..resource_start + resource_len, duplicate);
let view = HeadView::from_bytes(&bytes).unwrap();
let all = view.resources().collect::<Result<Vec<_>>>().unwrap();
assert!(all.len() > 1);
let mut limited = view.resources_limited(1);
assert!(limited.next().unwrap().is_ok());
assert!(limited.size_hint().1.unwrap() >= 1, "limit error is included in the upper bound");
assert!(limited.next().unwrap().is_err());
assert!(limited.next().is_none());
}
#[test]
fn a_prefix_ending_with_the_resources_is_enough_and_one_byte_less_is_not() {
for (_, bytes) in cases() {
+2 -2
View File
@@ -105,13 +105,13 @@ pub use descriptor::{Descriptor, VersionedDescriptor};
pub use error::{PsdError, Result};
pub use file::{GlobalLayerMask, LayerInfoPlacement, PsdFile};
pub use float::FloatImage;
pub use head::Head;
pub use head::{Head, HeadView};
pub use header::{ColorMode, Header, Version};
pub use image_data::ImageData;
pub use layer::{BlendingRanges, ChannelData, LayerFlags, LayerInfo, LayerMask, LayerRecord, MaskData, MaskParameters, RealMask, Rect};
pub use pixels::{GrayImage, Layer, RgbaImage};
pub use preview::Preview;
pub use resources::{ImageResource, ResolutionInfo, ResourceData};
pub use resources::{ImageResource, ImageResourceView, ResolutionInfo, ResourceData, ResourceIter};
pub use rows::RowDecoder;
#[cfg(any(unix, windows))]
pub use source::FileSource;
+120 -13
View File
@@ -2,7 +2,7 @@
use crate::descriptor::UnicodeString;
use crate::error::{PsdError, Result};
use crate::io::{Reader, WriteExt, read_pascal, write_pascal};
use crate::io::{Reader, WriteExt, write_pascal};
/// Well-known resource ids.
pub mod ids {
@@ -48,6 +48,124 @@ pub struct ImageResource {
pub data: Vec<u8>,
}
/// An image-resource record that borrows its name and data from the PSD/PSB input.
///
/// Use [`ImageResourceView::into_owned`] only when the data must outlive the input bytes. Parsing a
/// view does not allocate proportional to the resource's declared size.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct ImageResourceView<'a> {
/// Signature, normally `8BIM` (also `MeSa`, `AgHg`, `PHUT`, `DCSR` seen in the wild).
pub signature: [u8; 4],
/// Resource id.
pub id: u16,
/// Pascal name bytes (usually empty).
pub name: &'a [u8],
/// Resource data (without the even padding).
pub data: &'a [u8],
}
impl ImageResourceView<'_> {
/// Copies this view into an owned resource.
pub fn into_owned(self) -> ImageResource {
ImageResource { signature: self.signature, id: self.id, name: self.name.to_vec(), data: self.data.to_vec() }
}
}
impl<'a> ImageResourceView<'a> {
pub(crate) fn read(r: &mut Reader<'a>) -> Result<Self> {
let signature = r.array::<4>()?;
if !matches!(&signature, b"8BIM" | b"MeSa" | b"AgHg" | b"PHUT" | b"DCSR") {
return Err(PsdError::InvalidSignature { expected: "8BIM resource", found: signature });
}
let id = r.u16()?;
let name_len = usize::from(r.u8()?);
let name = r.bytes(name_len)?;
let name_total = 1 + name_len;
let name_pad = (2 - name_total % 2) % 2;
r.skip(name_pad)?;
let len = r.u32()?;
let data = r.bytes_u64(u64::from(len))?;
if len % 2 == 1 {
r.skip(1)?;
}
Ok(ImageResourceView { signature, id, name, data })
}
}
/// Lazily parses image-resource records from a borrowed resource section.
///
/// Records are yielded one at a time. If a record is malformed, the iterator yields its error
/// once and then stops; records yielded before it remain usable.
pub struct ResourceIter<'a> {
reader: Reader<'a>,
remaining_records: usize,
failed: bool,
}
impl<'a> ResourceIter<'a> {
pub(crate) fn new(bytes: &'a [u8]) -> Self {
ResourceIter::with_limit(bytes, usize::MAX)
}
pub(crate) fn with_limit(bytes: &'a [u8], max_records: usize) -> Self {
ResourceIter { reader: Reader::new(bytes), remaining_records: max_records, failed: false }
}
}
impl<'a> Iterator for ResourceIter<'a> {
type Item = Result<ImageResourceView<'a>>;
fn next(&mut self) -> Option<Self::Item> {
if self.failed || self.reader.is_empty() {
return None;
}
if self.remaining_records == 0 {
self.failed = true;
return Some(Err(PsdError::LimitExceeded("image resource record count")));
}
match ImageResourceView::read(&mut self.reader) {
Ok(resource) => {
self.remaining_records -= 1;
Some(Ok(resource))
}
Err(error) => {
self.failed = true;
Some(Err(error))
}
}
}
fn size_hint(&self) -> (usize, Option<usize>) {
// A valid record consumes at least 12 bytes. A truncated record or exhausted limit can
// produce one final error without consuming a full record.
let upper =
if self.failed || self.reader.is_empty() { 0 } else { (self.reader.remaining() / 12).min(self.remaining_records).saturating_add(1) };
(0, Some(upper))
}
}
impl std::iter::FusedIterator for ResourceIter<'_> {}
#[cfg(test)]
mod view_tests {
use super::ResourceIter;
#[test]
fn resource_size_hint_respects_the_record_limit() {
let data = vec![0; 12_000];
let iter = ResourceIter::with_limit(&data, 3);
assert_eq!(iter.size_hint(), (0, Some(4)));
}
#[test]
fn truncated_resource_size_hint_includes_error_item() {
let mut iter = ResourceIter::new(b"JUNK");
assert!(iter.size_hint().1.unwrap() >= 1);
assert!(iter.next().unwrap().is_err());
assert_eq!(iter.size_hint(), (0, Some(0)));
}
}
/// Fixed-point resolution info (resource 1005).
///
/// `h_res_fixed` and `v_res_fixed` are always pixels per inch (16.16 fixed).
@@ -292,18 +410,7 @@ impl ImageResource {
}
pub(crate) fn read(r: &mut Reader<'_>) -> Result<Self> {
let signature = r.array::<4>()?;
if !matches!(&signature, b"8BIM" | b"MeSa" | b"AgHg" | b"PHUT" | b"DCSR") {
return Err(PsdError::InvalidSignature { expected: "8BIM resource", found: signature });
}
let id = r.u16()?;
let name = read_pascal(r, 2)?;
let len = r.u32()?;
let data = r.bytes_u64(u64::from(len))?.to_vec();
if len % 2 == 1 {
r.skip(1)?;
}
Ok(ImageResource { signature, id, name, data })
Ok(ImageResourceView::read(r)?.into_owned())
}
pub(crate) fn write(&self, out: &mut Vec<u8>) -> Result<()> {
+2
View File
@@ -11,7 +11,9 @@ repository.workspace = true
workspace = true
[dependencies]
base64 = "0.23"
thiserror = { workspace = true }
image = { version = "0.25", default-features = false, features = ["png", "jpeg", "bmp", "gif", "tiff", "webp"] }
# The DDS encoder compresses rows of blocks in parallel on native; wasm stays single-threaded.
[target.'cfg(not(target_arch = "wasm32"))'.dependencies]
+130
View File
@@ -0,0 +1,130 @@
//! Bounded decoding and PNG encoding for common photographic and web image formats.
//!
//! This facade is for applications that need a single RGBA pixel buffer regardless of whether
//! the source was PNG, JPEG, BMP, GIF, TIFF, or WebP. Format sniffing and codec dispatch stay
//! inside this crate. Callers choose their own stricter file and image limits.
use std::io::Cursor;
use base64::{Engine as _, engine::general_purpose::STANDARD};
use image::{ImageReader, Limits as ImageLimits, RgbaImage};
use crate::CodecError;
pub use image::{Rgba as Pixel, RgbaImage as Pixels};
/// Limits applied before allocating the decoded image.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DecodeLimits {
pub max_file_bytes: usize,
pub max_width: u32,
pub max_height: u32,
pub max_pixels: u64,
pub max_alloc_bytes: u64,
}
impl Default for DecodeLimits {
fn default() -> Self {
Self { max_file_bytes: 64 * 1024 * 1024, max_width: 10_000, max_height: 10_000, max_pixels: 16_000_000, max_alloc_bytes: 256 * 1024 * 1024 }
}
}
/// Decode one frame into straight-alpha RGBA pixels. Animated images use the first frame.
pub fn decode_rgba(bytes: &[u8], limits: DecodeLimits) -> Result<RgbaImage, CodecError> {
if bytes.len() > limits.max_file_bytes {
return Err(CodecError::LimitExceeded(format!("{} encoded bytes exceed max {}", bytes.len(), limits.max_file_bytes)));
}
if is_heif(bytes) {
return Err(CodecError::unsupported("image", "HEIC/HEIF is not supported by the enabled codecs"));
}
let reader = || -> Result<ImageReader<Cursor<&[u8]>>, CodecError> {
let mut reader = ImageReader::new(Cursor::new(bytes)).with_guessed_format().map_err(|e| CodecError::malformed("image", e))?;
if reader.format().is_none() {
return Err(CodecError::unsupported("image", "unrecognised image format"));
}
let mut image_limits = ImageLimits::default();
image_limits.max_image_width = Some(limits.max_width);
image_limits.max_image_height = Some(limits.max_height);
image_limits.max_alloc = Some(limits.max_alloc_bytes);
reader.limits(image_limits);
Ok(reader)
};
let (width, height) = reader()?.into_dimensions().map_err(|e| CodecError::malformed("image", e))?;
check_dimensions(width, height, limits)?;
let decoded = reader()?.decode().map_err(|e| CodecError::malformed("image", e))?;
check_dimensions(decoded.width(), decoded.height(), limits)?;
Ok(decoded.to_rgba8())
}
/// Encode an RGBA image as PNG.
pub fn encode_png(pixels: &RgbaImage) -> Result<Vec<u8>, CodecError> {
let mut out = Cursor::new(Vec::new());
pixels.write_to(&mut out, image::ImageFormat::Png).map_err(|e| CodecError::encode("PNG", e))?;
Ok(out.into_inner())
}
/// Encode an RGBA image as standard Base64 containing PNG bytes, for a document field that stores
/// an inline PNG image.
pub fn encode_png_base64(pixels: &RgbaImage) -> Result<String, CodecError> {
encode_png(pixels).map(|bytes| STANDARD.encode(bytes))
}
/// Decode standard Base64 containing one PNG into straight-alpha RGBA pixels.
///
/// The encoded length is checked before Base64 allocates the decoded buffer, and the decoded PNG
/// then passes through the same file, dimension, pixel-count, and allocation limits as any other
/// raster input.
pub fn decode_png_base64(text: &str, limits: DecodeLimits) -> Result<RgbaImage, CodecError> {
let max_encoded_bytes = limits.max_file_bytes.div_ceil(3).saturating_mul(4);
if text.len() > max_encoded_bytes {
return Err(CodecError::LimitExceeded(format!("{} Base64 characters exceed max {max_encoded_bytes}", text.len())));
}
let bytes = STANDARD.decode(text).map_err(|e| CodecError::malformed("PNG Base64", e))?;
if !bytes.starts_with(b"\x89PNG\r\n\x1a\n") {
return Err(CodecError::malformed("PNG Base64", "decoded data has no PNG signature"));
}
decode_rgba(&bytes, limits)
}
/// Encode RGBA pixels as JPEG at the requested quality (1–100).
pub fn encode_jpeg(pixels: &RgbaImage, quality: u8) -> Result<Vec<u8>, CodecError> {
if !(1..=100).contains(&quality) {
return Err(CodecError::InvalidImage(format!("JPEG quality {quality} is outside 1–100")));
}
let rgb = image::DynamicImage::ImageRgba8(pixels.clone()).to_rgb8();
let mut out = Cursor::new(Vec::new());
image::codecs::jpeg::JpegEncoder::new_with_quality(&mut out, quality).encode_image(&rgb).map_err(|e| CodecError::encode("JPEG", e))?;
Ok(out.into_inner())
}
/// Encode pixels according to a destination filename's extension.
pub fn encode_for_path(path: impl AsRef<std::path::Path>, pixels: &RgbaImage) -> Result<Vec<u8>, CodecError> {
let extension = path.as_ref().extension().and_then(std::ffi::OsStr::to_str).unwrap_or_default();
match extension.to_ascii_lowercase().as_str() {
"png" => encode_png(pixels),
"jpg" | "jpeg" => encode_jpeg(pixels, 90),
"bmp" => encode_dynamic(pixels, image::ImageFormat::Bmp),
"gif" => encode_dynamic(pixels, image::ImageFormat::Gif),
"tif" | "tiff" => encode_dynamic(pixels, image::ImageFormat::Tiff),
"webp" => encode_dynamic(pixels, image::ImageFormat::WebP),
other => Err(CodecError::unsupported("image", format!("cannot encode files with the .{other} extension"))),
}
}
fn encode_dynamic(pixels: &RgbaImage, format: image::ImageFormat) -> Result<Vec<u8>, CodecError> {
let mut out = Cursor::new(Vec::new());
image::DynamicImage::ImageRgba8(pixels.clone()).write_to(&mut out, format).map_err(|e| CodecError::encode("image", e))?;
Ok(out.into_inner())
}
fn is_heif(bytes: &[u8]) -> bool {
bytes.get(4..8) == Some(b"ftyp") && matches!(bytes.get(8..12), Some(b"heic" | b"heix" | b"hevc" | b"mif1" | b"msf1" | b"avif"))
}
fn check_dimensions(width: u32, height: u32, limits: DecodeLimits) -> Result<(), CodecError> {
let pixels = u64::from(width).checked_mul(u64::from(height)).ok_or_else(|| CodecError::LimitExceeded("image dimensions overflow".into()))?;
if width == 0 || height == 0 || width > limits.max_width || height > limits.max_height || pixels > limits.max_pixels {
return Err(CodecError::LimitExceeded(format!("image dimensions {width}x{height} exceed configured limits")));
}
Ok(())
}
+2
View File
@@ -18,6 +18,8 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
/// Common bounded decoding and PNG/JPEG encoding for common image formats.
pub mod common;
pub mod dds;
mod dds_bc;
pub mod dicom;
+16
View File
@@ -0,0 +1,16 @@
[package]
name = "craft-stencilcraft-format"
description = "Reader and writer for the versioned StencilCraft JSON document format"
version.workspace = true
edition.workspace = true
license.workspace = true
rust-version.workspace = true
repository.workspace = true
[lints]
workspace = true
[dependencies]
serde = { workspace = true }
serde_json = { workspace = true }
thiserror = { workspace = true }
+23
View File
@@ -0,0 +1,23 @@
# craft-stencilcraft-format
Reader and writer for the versioned `.stencilcraft` JSON file. The JSON header is
`{"stencilcraft":{"name":"stencilcraft","version":1}}`; the document fields share the
top-level object with the header. `DocumentFields` owns field names, flattening, required fields,
version 1 defaults, and omitted optional members. Its values remain JSON so the consuming app
owns the domain model, geometry validation, and field-to-model mapping.
The crate does not open files or set a file-size policy. Callers perform bounded file I/O before
calling `File::read`.
```toml
craft-stencilcraft-format = { git = "https://github.com/storytold/craft-libs", rev = "<commit>" }
```
`File::read` parses JSON, validates the name and exact supported version, reads `DocumentFields`,
and ignores unknown members for version 1 compatibility. `File::new` and `to_json_pretty` write
the current header and flattened fields. Absent `next-shape-id` defaults to 1 and absent `images`
defaults to an empty list, matching early version 1 files.
`cargo test -p craft-stencilcraft-format` covers round-trip wire shape, version 1 defaults,
unknown members, wrong and missing headers, unsupported versions, malformed JSON, and missing
required fields.
+414
View File
@@ -0,0 +1,414 @@
#![deny(clippy::unwrap_used, clippy::expect_used, clippy::panic, clippy::unimplemented, clippy::todo, clippy::unreachable)]
#![forbid(unsafe_code)]
//! Reader and writer for the versioned JSON document format.
//!
//! The file stores a format header under `stencilcraft` and the document's wire fields at the
//! top level:
//!
//! ```json
//! {
//! "stencilcraft": { "name": "stencilcraft", "version": 1 },
//! "board": { "width_mm": 100.0, "height_mm": 150.0 },
//! "kerf": { "width_mm": 0.0, "apply_to_exports": false },
//! "layers": []
//! }
//! ```
//!
//! [`DocumentFields`] owns the JSON field names, required and defaulted fields, and the
//! flattening rule. Its values are JSON because the consuming app owns the document model,
//! domain validation, and conversion between that model and the wire fields. The crate does not
//! open files or set a file-size policy; callers handle bounded file I/O. [`File::read_from`]
//! lets callers parse from a reader without first buffering source bytes in a string.
use serde::de::{self, IgnoredAny, MapAccess, SeqAccess, Visitor};
use serde::{Deserialize, Deserializer, Serialize};
use serde_json::{Map, Value};
use std::fmt;
use std::io::Read;
/// The extension, without the leading dot.
pub const EXTENSION: &str = "stencilcraft";
/// The format name stored in the header.
pub const FORMAT_NAME: &str = "stencilcraft";
/// The newest document format version this crate reads and writes.
pub const FORMAT_VERSION: u64 = 1;
/// The top-level member containing the format header.
pub const HEADER_KEY: &str = "stencilcraft";
/// Wire fields in the flattened native document object.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct DocumentFields {
/// Required millimetre artboard dimensions.
pub board: Value,
/// Required kerf settings.
pub kerf: Value,
/// Required drawing layers.
pub layers: Value,
/// Next document object id; absent in early version 1 files, where it defaults to 1.
#[serde(rename = "next-shape-id", default = "default_next_shape_id")]
pub next_shape_id: u64,
/// Embedded raster images; absent in early version 1 files, where it defaults to empty.
#[serde(default)]
pub images: Vec<Value>,
/// Optional canvas page setup, omitted when absent.
#[serde(rename = "board-setup", default, skip_serializing_if = "Option::is_none")]
pub board_setup: Option<Value>,
/// Optional pages, omitted when absent.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub pages: Option<Value>,
/// Optional guides, omitted when absent.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub guides: Option<Value>,
/// Optional grid settings, omitted when absent.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub grid: Option<Value>,
/// Optional snap settings, omitted when absent.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub snap: Option<Value>,
/// Optional groups, omitted when absent.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub groups: Option<Value>,
/// Optional user metadata, omitted when absent.
#[serde(default, skip_serializing_if = "Option::is_none")]
pub meta: Option<Value>,
}
fn default_next_shape_id() -> u64 {
1
}
/// A native document and its flattened wire fields.
#[derive(Debug, Clone, PartialEq)]
pub struct File {
/// The fields after the header have been parsed, with app-domain objects still encoded as
/// JSON values.
pub document: DocumentFields,
}
impl File {
/// Builds a native document from its wire fields.
pub fn new(document: DocumentFields) -> Self {
Self { document }
}
/// Parses JSON, validates the format header and version, then reads the wire fields.
pub fn read(text: &str) -> Result<Self, Error> {
let wire: RawWire = serde_json::from_str(text).map_err(Error::Json)?;
Self::from_wire(wire)
}
/// Parses JSON from a reader, without first buffering the source bytes in a string.
///
/// Parsed document fields are still materialized as JSON values. Callers that impose a
/// total file-size policy should enforce it on the reader before calling this method.
pub fn read_from(reader: impl Read) -> Result<Self, Error> {
let wire: RawWire = serde_json::from_reader(reader).map_err(Error::Json)?;
Self::from_wire(wire)
}
fn from_wire(wire: RawWire) -> Result<Self, Error> {
let header = wire.fields.get(HEADER_KEY).and_then(Value::as_object).ok_or(Error::NotStencilCraft)?;
if header.get("name").and_then(Value::as_str) != Some(FORMAT_NAME) {
return Err(Error::NotStencilCraft);
}
let Some(version) = header.get("version").and_then(Value::as_u64) else {
return Err(Error::NotStencilCraft);
};
if version != FORMAT_VERSION {
return Err(Error::Version { found: version, supported: FORMAT_VERSION });
}
let raw: RawFile = serde_json::from_value(Value::Object(wire.fields)).map_err(|source| Error::Document { source })?;
Ok(Self { document: raw.document })
}
/// Writes the current format header and flattened wire fields as indented JSON.
pub fn to_json_pretty(&self) -> Result<String, Error> {
let raw = RawFileRef { header: HeaderRef { name: FORMAT_NAME, version: FORMAT_VERSION }, document: &self.document };
let value = serde_json::to_value(raw).map_err(Error::Json)?;
serde_json::to_string_pretty(&value).map_err(Error::Json)
}
}
#[derive(Debug, Serialize, Deserialize)]
struct Header {
name: String,
version: u64,
}
#[derive(Debug, Deserialize)]
struct RawFile {
#[serde(rename = "stencilcraft")]
_header: Header,
#[serde(flatten)]
document: DocumentFields,
}
/// A top-level streaming visitor that stores only fields owned by this wire schema.
///
/// Values are kept as `Value` because consumers own their document models. Unknown fields are
/// skipped, duplicate fields retain serde_json's last-value-wins behavior, and header checks run
/// only after the full JSON input has been parsed.
struct RawWire {
fields: Map<String, Value>,
}
impl<'de> Deserialize<'de> for RawWire {
fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
where
D: Deserializer<'de>,
{
struct RawWireVisitor;
impl<'de> Visitor<'de> for RawWireVisitor {
type Value = RawWire;
fn expecting(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str("a JSON value containing a StencilCraft document")
}
fn visit_map<A>(self, mut access: A) -> Result<Self::Value, A::Error>
where
A: MapAccess<'de>,
{
let mut fields = Map::new();
while let Some(key) = access.next_key::<String>()? {
if is_wire_field(&key) {
fields.insert(key, access.next_value()?);
} else {
let _ = access.next_value::<IgnoredAny>()?;
}
}
Ok(RawWire { fields })
}
fn visit_seq<A>(self, mut access: A) -> Result<Self::Value, A::Error>
where
A: SeqAccess<'de>,
{
while access.next_element::<IgnoredAny>()?.is_some() {}
Ok(RawWire { fields: Map::new() })
}
fn visit_bool<E>(self, _value: bool) -> Result<Self::Value, E>
where
E: de::Error,
{
Ok(RawWire { fields: Map::new() })
}
fn visit_i64<E>(self, _value: i64) -> Result<Self::Value, E>
where
E: de::Error,
{
Ok(RawWire { fields: Map::new() })
}
fn visit_u64<E>(self, _value: u64) -> Result<Self::Value, E>
where
E: de::Error,
{
Ok(RawWire { fields: Map::new() })
}
fn visit_f64<E>(self, _value: f64) -> Result<Self::Value, E>
where
E: de::Error,
{
Ok(RawWire { fields: Map::new() })
}
fn visit_str<E>(self, _value: &str) -> Result<Self::Value, E>
where
E: de::Error,
{
Ok(RawWire { fields: Map::new() })
}
fn visit_string<E>(self, _value: String) -> Result<Self::Value, E>
where
E: de::Error,
{
Ok(RawWire { fields: Map::new() })
}
fn visit_unit<E>(self) -> Result<Self::Value, E>
where
E: de::Error,
{
Ok(RawWire { fields: Map::new() })
}
fn visit_none<E>(self) -> Result<Self::Value, E>
where
E: de::Error,
{
Ok(RawWire { fields: Map::new() })
}
}
deserializer.deserialize_any(RawWireVisitor)
}
}
fn is_wire_field(name: &str) -> bool {
matches!(
name,
HEADER_KEY
| "board"
| "kerf"
| "layers"
| "next-shape-id"
| "images"
| "board-setup"
| "pages"
| "guides"
| "grid"
| "snap"
| "groups"
| "meta"
)
}
#[derive(Serialize)]
struct HeaderRef<'a> {
name: &'a str,
version: u64,
}
#[derive(Serialize)]
struct RawFileRef<'a> {
#[serde(rename = "stencilcraft")]
header: HeaderRef<'a>,
#[serde(flatten)]
document: &'a DocumentFields,
}
/// A file was malformed, belongs to another format, or uses an unsupported version.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum Error {
/// The input is not valid JSON, or the file could not be serialized.
#[error(transparent)]
Json(#[from] serde_json::Error),
/// The input has no valid StencilCraft format header.
#[error("not a stencilcraft file")]
NotStencilCraft,
/// The input names a version other than [`FORMAT_VERSION`].
#[error("format version {found}, this build reads {supported}")]
Version { found: u64, supported: u64 },
/// The JSON envelope is valid, but a required or typed wire field is malformed.
#[error("{source}")]
Document { source: serde_json::Error },
}
#[cfg(test)]
mod tests {
use std::io::{self, Cursor, Read};
use serde_json::{Value, json};
use super::{DocumentFields, Error, FORMAT_VERSION, File};
fn fields() -> DocumentFields {
DocumentFields {
board: json!({"width_mm": 100.0, "height_mm": 150.0}),
kerf: json!({"width_mm": 0.0, "apply_to_exports": false}),
layers: json!([]),
next_shape_id: 1,
images: Vec::new(),
board_setup: None,
pages: None,
guides: None,
grid: None,
snap: None,
groups: None,
meta: None,
}
}
#[test]
fn writes_flattened_schema_with_the_current_header_and_reads_it() -> Result<(), Error> {
let file = File::new(fields());
let text = file.to_json_pretty()?;
assert!(text.starts_with("{\n \"board\":"));
let value: Value = serde_json::from_str(&text)?;
assert_eq!(value["stencilcraft"]["name"], "stencilcraft");
assert_eq!(value["stencilcraft"]["version"], FORMAT_VERSION);
assert_eq!(value["board"], file.document.board);
assert_eq!(value["layers"], file.document.layers);
assert!(value.get("board-setup").is_none());
assert_eq!(File::read(&text)?, file);
Ok(())
}
#[test]
fn reads_version_one_defaults_and_ignores_unknown_fields() -> Result<(), Error> {
let text = r#"{"stencilcraft":{"name":"stencilcraft","version":1},"board":{},"kerf":{},"layers":[],"future-field":true}"#;
let file = File::read(text)?;
assert_eq!(file.document.next_shape_id, 1);
assert!(file.document.images.is_empty());
Ok(())
}
#[test]
fn refuses_missing_or_mismatched_headers() {
for text in [
r#"{"board":{},"kerf":{},"layers":[]}"#,
r#"{"stencilcraft":{"name":"other","version":1}}"#,
r#"{"stencilcraft":{"name":"stencilcraft","version":"1"}}"#,
] {
assert!(matches!(File::read(text), Err(Error::NotStencilCraft)));
}
}
#[test]
fn scalar_roots_are_not_documents() {
for text in ["false", "-1", "1", "1.5", "\"scalar\"", "null"] {
assert!(matches!(File::read(text), Err(Error::NotStencilCraft)));
}
assert!(matches!(File::read_from(Cursor::new(br#""scalar""#)), Err(Error::NotStencilCraft)));
}
#[test]
fn refuses_versions_other_than_the_current_version() {
assert!(matches!(File::read(r#"{"stencilcraft":{"name":"stencilcraft","version":2}}"#), Err(Error::Version { found: 2, supported: 1 })));
}
#[test]
fn reader_preserves_duplicate_key_and_error_precedence_behavior() -> Result<(), Error> {
let duplicate = r#"{"stencilcraft":{"name":"wrong","version":1},"stencilcraft":{"name":"stencilcraft","version":1},"board":{"first":true},"board":{"width_mm":100,"height_mm":150},"kerf":{},"layers":[]}"#;
let file = File::read_from(Cursor::new(duplicate))?;
assert_eq!(file.document.board, json!({"width_mm":100,"height_mm":150}));
let malformed_after_bad_header = Cursor::new(br#"{"stencilcraft":{"name":"other","version":1},"board": "#);
assert!(matches!(File::read_from(malformed_after_bad_header), Err(Error::Json(_))));
assert!(matches!(File::read_from(Cursor::new(b"[]")), Err(Error::NotStencilCraft)));
Ok(())
}
#[test]
fn reader_accepts_large_input_in_short_reads() -> Result<(), Error> {
struct ShortReads<R>(R);
impl<R: Read> Read for ShortReads<R> {
fn read(&mut self, buffer: &mut [u8]) -> io::Result<usize> {
let length = buffer.len().min(1024);
self.0.read(&mut buffer[..length])
}
}
let text = format!(
r#"{{"stencilcraft":{{"name":"stencilcraft","version":1}},"board":{{}},"kerf":{{}},"layers":[],"future-field":"{}"}}"#,
"x".repeat(8 * 1024 * 1024)
);
let file = File::read_from(ShortReads(Cursor::new(text.as_bytes())))?;
assert_eq!(file.document.layers, json!([]));
Ok(())
}
#[test]
fn separates_json_errors_from_wire_schema_errors() {
assert!(matches!(File::read("{"), Err(Error::Json(_))));
assert!(matches!(File::read(r#"{"stencilcraft":{"name":"stencilcraft","version":1}}"#), Err(Error::Document { .. })));
}
}
+1
View File
@@ -20,6 +20,7 @@
pub mod color;
pub mod guard;
pub mod paths;
pub mod preflight;
pub mod sniff;
pub mod svgz;
#[cfg(feature = "tree")]
+91
View File
@@ -0,0 +1,91 @@
//! Decode and validate SVG/SVGZ text before a caller hands it to a renderer.
//!
//! This boundary has no dependency on an SVG renderer. It decodes the file's text encoding and
//! bounded gzip container, then checks entity expansion, attribute work, XML structure, node
//! count and nesting depth.
use std::borrow::Cow;
/// Limits for decoding and validating one SVG document.
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub struct Limits {
/// Bytes of source text, also the largest unpacked SVGZ.
pub bytes: usize,
/// Deepest XML element nesting (the root alone is 1).
pub depth: usize,
/// Total bytes entities may expand to.
pub entity_bytes: usize,
/// Refuse a doctype entity containing markup.
pub refuse_entity_markup: bool,
/// Attributes on one element.
pub attributes: usize,
/// Sum of squared attribute counts across the document.
pub attribute_work: usize,
/// Maximum XML nodes after entity expansion.
pub xml_nodes: u32,
}
impl Default for Limits {
fn default() -> Self {
Limits {
bytes: 64 << 20,
depth: 256,
entity_bytes: crate::guard::MAX_ENTITY_EXPANSION,
refuse_entity_markup: false,
attributes: crate::guard::MAX_ATTRIBUTES,
attribute_work: crate::guard::MAX_ATTRIBUTE_WORK,
xml_nodes: 4_000_000,
}
}
}
/// Why an SVG's text or XML could not be read within `Limits`.
#[derive(Debug, Clone, PartialEq, Eq, thiserror::Error)]
pub enum Error {
/// The bytes are too large, corrupt SVGZ, nested SVGZ, or invalid text encoding.
#[error(transparent)]
Text(#[from] crate::svgz::Error),
/// Entity references expand past the configured limit.
#[error("the SVG's entities expand to too much text")]
Entities,
/// A doctype entity contains markup and is refused by the caller's policy.
#[error("the SVG's document type declares an entity holding markup, which isn't supported")]
EntityMarkup,
/// XML element nesting exceeds the configured limit.
#[error("the SVG's elements are nested more than {0} levels deep")]
TooDeep(usize),
/// Attribute count or total attribute work exceeds the configured limit.
#[error("an element of the SVG has more than {0} attributes, or its elements have too many in all")]
TooWide(usize),
/// The XML is malformed or exceeds the node limit.
#[error("invalid SVG XML: {0}")]
Xml(String),
}
/// Decodes SVG or SVGZ text and checks the XML against `limits`.
pub fn text<'a>(bytes: &'a [u8], limits: &Limits) -> Result<Cow<'a, str>, Error> {
let text = crate::svgz::text(bytes, limits.bytes)?;
parse_text(&text, limits)?;
Ok(text)
}
/// Parses already-decoded SVG text and checks it against `limits`.
pub fn parse_text<'a>(svg: &'a str, limits: &Limits) -> Result<roxmltree::Document<'a>, Error> {
if svg.len() > limits.bytes {
return Err(Error::Text(crate::svgz::Error::TooLarge(limits.bytes)));
}
if limits.refuse_entity_markup && crate::guard::entity_holds_markup(svg) {
return Err(Error::EntityMarkup);
}
if crate::guard::entities_expand_past(svg, limits.entity_bytes) {
return Err(Error::Entities);
}
if crate::guard::too_wide(svg, limits.attributes, limits.attribute_work) {
return Err(Error::TooWide(limits.attributes));
}
if crate::guard::deeper_than(svg, limits.depth) {
return Err(Error::TooDeep(limits.depth));
}
let options = roxmltree::ParsingOptions { allow_dtd: true, nodes_limit: limits.xml_nodes, ..Default::default() };
roxmltree::Document::parse_with_options(svg, options).map_err(|e| Error::Xml(e.to_string()))
}
+17 -17
View File
@@ -125,23 +125,23 @@ pub fn parse_text(svg: &str, limits: &Limits, options: &usvg::Options<'_>) -> Re
/// Every check on SVG text, cheapest first; the XML it parses to on the way.
fn checked<'s>(svg: &'s str, limits: &Limits) -> Result<roxmltree::Document<'s>, Error> {
if svg.len() > limits.bytes {
return Err(Error::Text(svgz::Error::TooLarge(limits.bytes)));
}
if limits.refuse_entity_markup && guard::entity_holds_markup(svg) {
return Err(Error::EntityMarkup);
}
if guard::entities_expand_past(svg, limits.entity_bytes) {
return Err(Error::Entities);
}
if guard::too_wide(svg, limits.attributes, limits.attribute_work) {
return Err(Error::TooWide(limits.attributes));
}
if guard::deeper_than(svg, limits.depth) {
return Err(Error::TooDeep(limits.depth));
}
let options = roxmltree::ParsingOptions { allow_dtd: true, nodes_limit: limits.xml_nodes, ..Default::default() };
let xml = roxmltree::Document::parse_with_options(svg, options).map_err(|e| Error::Xml(e.to_string()))?;
let preflight_limits = crate::preflight::Limits {
bytes: limits.bytes,
depth: limits.depth,
entity_bytes: limits.entity_bytes,
refuse_entity_markup: limits.refuse_entity_markup,
attributes: limits.attributes,
attribute_work: limits.attribute_work,
xml_nodes: limits.xml_nodes,
};
let xml = crate::preflight::parse_text(svg, &preflight_limits).map_err(|e| match e {
crate::preflight::Error::Text(e) => Error::Text(e),
crate::preflight::Error::Entities => Error::Entities,
crate::preflight::Error::EntityMarkup => Error::EntityMarkup,
crate::preflight::Error::TooDeep(depth) => Error::TooDeep(depth),
crate::preflight::Error::TooWide(attributes) => Error::TooWide(attributes),
crate::preflight::Error::Xml(msg) => Error::Xml(msg),
})?;
if height(&xml, limits.depth)?.is_none() {
return Err(Error::TooDeep(limits.depth));
}
+1 -1
View File
@@ -35,7 +35,7 @@ assert_eq!(audio_sample, one_sec);
Frame rates are represented as exact fractions (`num / den`):
```rust
use craft_time::FrameRate;
use craft_time::{FrameRate, Tick};
// Standard NTSC and PAL rates
let ntsc_24 = FrameRate::FPS_23_976; // 24000 / 1001
+163 -19
View File
@@ -35,8 +35,7 @@ impl Tick {
/// Seconds to ticks, clamped to [`Tick::MIN`]..=[`Tick::MAX`].
pub fn from_seconds_f64(s: f64) -> Tick {
let t = (s * TICKS_PER_SECOND as f64).round();
Tick((t as i64).clamp(Tick::MIN.0, Tick::MAX.0))
Tick((s * TICKS_PER_SECOND as f64).round() as i64)
}
pub fn seconds(self) -> f64 {
@@ -246,7 +245,7 @@ impl TimeRange {
}
pub fn overlaps(&self, o: &TimeRange) -> bool {
self.start < o.end() && o.start < self.end()
!self.is_empty() && !o.is_empty() && self.start < o.end() && o.start < self.end()
}
pub fn intersect(&self, o: &TimeRange) -> Option<TimeRange> {
@@ -316,6 +315,19 @@ impl FrameRate {
FrameRate::new((fps * 1000.0).round() as i64, 1000)
}
/// Closest standard rate when `fps` is within `tolerance` of it, otherwise the nearest
/// 1/1000 rate. This retains the timeline API's coarse-timebase compatibility behavior.
pub fn from_f64_within(fps: f64, tolerance: f64) -> Self {
let mut best: Option<(f64, FrameRate)> = None;
for rate in Self::COMMON {
let off = (rate.as_f64() - fps).abs();
if off <= tolerance * rate.as_f64() && best.is_none_or(|(closest, _)| off < closest) {
best = Some((off, rate));
}
}
best.map_or_else(|| Self::from_f64(fps), |(_, rate)| rate)
}
/// Returns this frame rate if positive, or the default rate ([`FrameRate::FPS_23_976`]).
///
/// ### Application Compatibility Note
@@ -341,6 +353,11 @@ impl FrameRate {
clamp_i64(frame_index(self.sane(), t))
}
/// Frames from `start` to `end`, counted between their frame indices.
pub fn frames_between(self, start: Tick, end: Tick) -> i64 {
self.frame_at(end).saturating_sub(self.frame_at(start))
}
/// Start tick of frame `f` (ceiling division).
pub fn tick_of(self, f: i64) -> Tick {
Tick(clamp_i64(frame_boundary(self.sane(), i128::from(f))))
@@ -432,6 +449,9 @@ impl TimeDisplay {
pub const ALL: [TimeDisplay; 6] =
[TimeDisplay::Timecode, TimeDisplay::Feet35, TimeDisplay::Feet16, TimeDisplay::Frames, TimeDisplay::AudioSamples, TimeDisplay::Seconds];
/// The video display formats (Sequence Settings ▸ Display Format, the burn-in's Time Format).
pub const VIDEO: [TimeDisplay; 4] = [TimeDisplay::Timecode, TimeDisplay::Feet35, TimeDisplay::Feet16, TimeDisplay::Frames];
pub fn label(self) -> &'static str {
match self {
TimeDisplay::Timecode => "Timecode",
@@ -442,6 +462,32 @@ impl TimeDisplay {
TimeDisplay::Seconds => "Seconds",
}
}
/// Stable id used by commands and the UI.
pub fn id(self) -> &'static str {
match self {
TimeDisplay::Timecode => "timecode",
TimeDisplay::Frames => "frames",
TimeDisplay::Feet16 => "feet16",
TimeDisplay::Feet35 => "feet35",
TimeDisplay::AudioSamples => "samples",
TimeDisplay::Seconds => "seconds",
}
}
/// The display with this [`id`](Self::id), ignoring case.
pub fn from_id(id: &str) -> Option<TimeDisplay> {
TimeDisplay::ALL.into_iter().find(|display| display.id().eq_ignore_ascii_case(id))
}
/// Frames per foot for the Feet + Frames displays.
pub fn frames_per_foot(self) -> Option<i64> {
match self {
TimeDisplay::Feet35 => Some(16),
TimeDisplay::Feet16 => Some(40),
_ => None,
}
}
}
fn df_params(rate: FrameRate) -> (i64, i64) {
@@ -509,35 +555,33 @@ pub fn format_time(t: Tick, rate: FrameRate, drop_frame: bool, display: TimeDisp
match display {
TimeDisplay::Timecode => format_timecode_frames(frame, rate, drop_frame),
TimeDisplay::Frames => format!("{frame}"),
TimeDisplay::Feet35 | TimeDisplay::Feet16 => {
let per_ft = if display == TimeDisplay::Feet35 { 16 } else { 40 };
let neg = frame < 0;
let a = frame.unsigned_abs();
format!("{}{}+{:02}", if neg { "-" } else { "" }, a / per_ft, a % per_ft)
}
TimeDisplay::Feet35 | TimeDisplay::Feet16 => format_feet_frames(frame, display.frames_per_foot().unwrap_or(16)),
TimeDisplay::AudioSamples => {
let neg = t.0 < 0;
let abs_ticks = t.0.unsigned_abs();
let total_secs = abs_ticks / (TICKS_PER_SECOND as u64);
let rem_ticks = abs_ticks % (TICKS_PER_SECOND as u64);
let rem_samples = (rem_ticks as u128 * sample_rate as u128) / (TICKS_PER_SECOND as u128);
let rem_samples = Tick(rem_ticks as i64).to_units_floor(sample_rate.max(0));
let h = total_secs / 3600;
let m = (total_secs / 60) % 60;
let s = total_secs % 60;
format!("{}{:02}:{:02}:{:02}:{:05}", if neg { "-" } else { "" }, h, m, s, rem_samples)
}
TimeDisplay::Seconds => format!("{:.3}", t.seconds()),
TimeDisplay::Seconds => {
let seconds = format!("{:.3}", t.seconds());
if seconds == "-0.000" { "0.000".into() } else { seconds }
}
}
}
/// Format a frame count as Feet + Frames (film footage counting).
pub fn format_feet_frames(frame: i64, per_foot: i64) -> String {
let pf = per_foot.max(1);
let per_foot = per_foot.max(1);
let sign = if frame < 0 { "-" } else { "" };
let a = frame.unsigned_abs();
let pf = pf as u64;
let w = if pf > 100 { 3 } else { 2 };
format!("{sign}{:04}+{:0w$}", a / pf, a % pf)
let frames = frame.unsigned_abs();
let per_foot = per_foot as u64;
let width = if per_foot > 100 { 3 } else { 2 };
format!("{sign}{:04}+{:0width$}", frames / per_foot, frames % per_foot)
}
/// Error from timecode parsing.
@@ -561,15 +605,42 @@ impl std::error::Error for ParseError {}
/// saturates to `i64::MAX` (or `i64::MIN`) to keep calculations total without errors.
/// In contrast, EffectCraft returns `Err(ParseError("timecode too large"))`.
pub fn parse_timecode(input: &str, rate: FrameRate, drop_frame: bool, current: i64) -> Result<i64, ParseError> {
parse_timecode_with_negative_policy(input, rate, drop_frame, current, true)
}
/// Parse timecode with the relative-negative policy used by the historical timeline API.
/// A leading minus offsets from `current`, including a complete four-field timecode.
pub fn parse_timecode_relative(input: &str, rate: FrameRate, drop_frame: bool, current: i64) -> Result<i64, ParseError> {
parse_timecode_with_negative_policy(input, rate, drop_frame, current, false)
}
fn parse_timecode_with_negative_policy(
input: &str,
rate: FrameRate,
drop_frame: bool,
current: i64,
full_negative_is_absolute: bool,
) -> Result<i64, ParseError> {
let s = input.trim();
if s.is_empty() {
return Err(ParseError("empty timecode".into()));
}
if s.len() > 80 {
return Err(ParseError("timecode is too long".into()));
}
let (sign_char, body) = match s.as_bytes()[0] {
b'+' => (Some('+'), &s[1..]),
b'-' => (Some('-'), &s[1..]),
_ => (None, s),
};
// Four fields is the complete timecode grammar. Check limits before allocating split vectors.
let separators = body.bytes().filter(|b| matches!(b, b':' | b';' | b'.' | b',')).count();
if separators > 3 {
return Err(ParseError("too many timecode fields".into()));
}
if separators == 0 && body.len() > if sign_char.is_some() { 19 } else { 8 } {
return Err(ParseError("timecode is too long".into()));
}
let parts: Vec<&str> = body.split([':', ';', '.', ',']).collect();
let nums: Vec<i64> = if parts.len() == 1 {
let digits = parts[0];
@@ -615,7 +686,10 @@ pub fn parse_timecode(input: &str, rate: FrameRate, drop_frame: bool, current: i
let base = rate.timecode_base();
let frames = if nums.len() == 1 && sign_char.is_some() {
fr
} else if drop_frame && rate.supports_drop_frame() && m < 60 && sec < 60 && fr < base {
} else if drop_frame && rate.supports_drop_frame() {
let (sec, fr) = (sec.saturating_add(fr / base), fr % base);
let (m, sec) = (m.saturating_add(sec / 60), sec % 60);
let (h, m) = (h.saturating_add(m / 60), m % 60);
fields_to_frames(h, m, sec, fr, rate, true)
} else {
h.saturating_mul(3600).saturating_add(m.saturating_mul(60)).saturating_add(sec).saturating_mul(base).saturating_add(fr)
@@ -623,10 +697,11 @@ pub fn parse_timecode(input: &str, rate: FrameRate, drop_frame: bool, current: i
match sign_char {
Some('+') => Ok(current.saturating_add(frames)),
Some('-') if full_negative_is_absolute && nums.len() == 4 => Ok(-frames),
Some('-') => {
// A full 4-field timecode with leading '-' represents an absolute negative timecode (e.g. preroll).
// Single-number or partial relative offsets (e.g. -15 or -1.00) offset from current.
if nums.len() == 4 { Ok(-frames) } else { Ok(current.saturating_sub(frames)) }
// The timeline compatibility path treats every leading minus as an offset instead.
Ok(current.saturating_sub(frames))
}
None | Some(_) => Ok(frames),
}
@@ -671,6 +746,65 @@ pub fn parse_feet_frames(input: &str, per_foot: i64, current: i64) -> Result<i64
}
}
/// Parse text using a [`TimeDisplay`] representation.
pub fn parse_time_display(input: &str, rate: FrameRate, drop_frame: bool, display: TimeDisplay, current: i64) -> Result<i64, ParseError> {
parse_time_display_with_negative_policy(input, rate, drop_frame, display, current, true)
}
/// Parse text using a [`TimeDisplay`] representation and the historical timeline relative-minus rule.
pub fn parse_time_display_relative(input: &str, rate: FrameRate, drop_frame: bool, display: TimeDisplay, current: i64) -> Result<i64, ParseError> {
parse_time_display_with_negative_policy(input, rate, drop_frame, display, current, false)
}
fn parse_time_display_with_negative_policy(
input: &str,
rate: FrameRate,
drop_frame: bool,
display: TimeDisplay,
current: i64,
full_negative_is_absolute: bool,
) -> Result<i64, ParseError> {
let per_foot = match display {
TimeDisplay::Frames => 1,
TimeDisplay::Feet35 | TimeDisplay::Feet16 => display.frames_per_foot().unwrap_or(16),
_ => {
return if full_negative_is_absolute {
parse_timecode(input, rate, drop_frame, current)
} else {
parse_timecode_relative(input, rate, drop_frame, current)
};
}
};
let text = input.trim();
if text.is_empty() {
return Err(ParseError("empty time".into()));
}
let (relative, body) = match text.as_bytes()[0] {
b'+' => (Some(1), &text[1..]),
b'-' => (Some(-1), &text[1..]),
_ => (None, text),
};
let field = |part: &str| -> Result<i64, ParseError> {
if part.is_empty() {
Ok(0)
} else if !part.bytes().all(|byte| byte.is_ascii_digit()) {
Err(ParseError(format!("not a time: `{input}`")))
} else {
part.parse::<i64>().map_err(|_| ParseError("number too large".into()))
}
};
let parts: Vec<&str> = body.split(['+', ':', ';', '.', ',']).collect();
let frames = match parts.as_slice() {
[number] => field(number)?,
[feet, frames] if per_foot > 1 => field(feet)?.saturating_mul(per_foot).saturating_add(field(frames)?),
_ => return Err(ParseError(format!("not a time: `{input}`"))),
};
Ok(match relative {
Some(sign) => current.saturating_add(frames.saturating_mul(sign)),
None => frames,
})
}
/// Common audio sample rates offered in sequence settings.
pub const SAMPLE_RATES: [i64; 6] = [32_000, 44_100, 48_000, 88_200, 96_000, 192_000];
@@ -701,6 +835,15 @@ mod tests {
}
}
#[test]
fn timecode_parser_rejects_oversized_inputs_before_field_collection() {
let too_many_fields = ":".repeat(100_000);
assert!(parse_timecode(&too_many_fields, FrameRate::FPS_30, false, 0).is_err());
let compact = "1".repeat(9);
assert!(parse_timecode(&compact, FrameRate::FPS_30, false, 0).is_err());
assert!(parse_timecode_relative("+12345678901234567890", FrameRate::FPS_30, false, 0).is_err());
}
#[test]
fn test_broadcast_frame_rates() {
for r in FrameRate::COMMON {
@@ -735,6 +878,7 @@ mod tests {
assert_eq!(format_time(neg_complex, r, false, TimeDisplay::AudioSamples, 48_000), "-01:01:01:00000");
let zero = Tick::ZERO;
assert_eq!(format_time(Tick(2), r, false, TimeDisplay::AudioSamples, -1), "00:00:00:00000");
assert_eq!(format_time(zero, r, false, TimeDisplay::AudioSamples, 48_000), "00:00:00:00000");
}
+1 -1
View File
@@ -76,7 +76,7 @@ pub fn format_length(start: Samples, len: Samples, fmt: TimeFormat, sr: SampleRa
let t0 = map.samples_to_ticks(start, sr);
let t1 = map.samples_to_ticks(start.saturating_add(len), sr);
let m = map.meter_at_tick(t0);
let d = (t1 - t0).max(0);
let d = t1.saturating_sub(t0).max(0);
let bars = d / m.ticks_per_bar().max(1);
let rem = d % m.ticks_per_bar().max(1);
format!("{bars}| {}| {:03}", rem / m.ticks_per_beat().max(1), rem % m.ticks_per_beat().max(1))
+35 -5
View File
@@ -430,7 +430,7 @@ impl GridValue {
// always four quarter notes and therefore keeps a continuous tick origin.
let bb = map.bar_beat_at_tick(t);
let bar_tick = map.bar_start_tick(bb.bar);
let origin = if value == NoteValue::Whole { 0 } else { bar_tick };
let origin = if value == NoteValue::Whole || (value == NoteValue::Bar && dotted) { 0 } else { bar_tick };
let step = Self::note_ticks(value, dotted, triplet, map, origin);
let k = (t - origin).div_euclid(step);
map.tick_to_samples(origin + k * step, sr)
@@ -547,7 +547,14 @@ impl GridValue {
}
let step = self.step_samples(line, sr, map, rate);
let candidate = self.line_at_or_before(line.saturating_add(step), sr, map, rate);
if candidate > line { candidate } else { line.saturating_add(step) }
let next = if candidate > line { candidate } else { line.saturating_add(step) };
if matches!(self, GridValue::Note { value: NoteValue::Bar, .. }) {
return next;
}
let tick = map.samples_to_ticks(line, sr);
let bar = map.bar_beat_at_tick(tick).bar;
let next_bar = map.tick_to_samples(map.bar_start_tick(bar.saturating_add(1)), sr);
if next_bar > line { next.min(next_bar) } else { next }
}
/// All grid lines within `[start, end)`, capped at `max` lines.
@@ -681,6 +688,27 @@ mod tests {
assert_eq!(note(NoteValue::Half).lines(0, 150_000, sr, &map, rate, 10), [0, 48_000, 72_000, 120_000, 144_000]);
}
#[test]
fn dotted_bar_grid_keeps_its_spacing_across_bars() {
let (sr, map, rate) = (SampleRate::HZ_48000, TempoMap::default(), FrameRate::Fps25);
let grid = GridValue::Note { value: NoteValue::Bar, dotted: true, triplet: false };
assert_eq!(grid.line_at_or_before(143_999, sr, &map, rate), 0);
assert_eq!(grid.line_at_or_before(144_000, sr, &map, rate), 144_000);
assert_eq!(grid.next_line(0, sr, &map, rate), 144_000);
}
#[test]
fn dotted_note_does_not_skip_a_meter_change_boundary() {
let sr = SampleRate::HZ_48000;
let mut map = TempoMap::default();
map.set_meter(TICKS_PER_QUARTER * 4, 2, 4).unwrap();
let rate = FrameRate::Fps25;
let grid = GridValue::Note { value: NoteValue::Half, dotted: true, triplet: false };
assert_eq!(grid.next_line(72_000, sr, &map, rate), 96_000);
assert!(grid.lines(72_000, 120_000, sr, &map, rate, 10).contains(&96_000));
assert_eq!(grid.snap(90_000, sr, &map, rate), 96_000);
}
#[test]
fn seconds_grid_lines_land_on_whole_seconds() {
let (sr, map, rate) = (SampleRate::HZ_44100, TempoMap::default(), FrameRate::Fps30);
@@ -745,7 +773,8 @@ mod tests {
let frame = GridValue::drop_second_frame(seconds, rate);
let line = rate.samples_at_frame(frame, sr);
assert_eq!(grid.line_at_or_before(line, sr, &map, rate), line, "{rate:?} second {seconds}");
assert_eq!(grid.line_at_or_before(-line, sr, &map, rate), -line, "{rate:?} second -{seconds}");
let negative_line = rate.samples_at_frame(-frame, sr);
assert_eq!(grid.line_at_or_before(negative_line, sr, &map, rate), negative_line, "{rate:?} second -{seconds}");
for offset in -2..=rate.nominal() + 2 {
let position = rate.samples_at_frame(frame.saturating_add(offset), sr);
let before = grid.line_at_or_before(position, sr, &map, rate);
@@ -761,8 +790,9 @@ mod tests {
let boundary = rate.samples_at_frame(minute_frame, sr);
assert_eq!(grid.line_at_or_before(boundary, sr, &map, rate), boundary, "{rate:?} positive minute boundary");
assert_eq!(grid.snap(boundary, sr, &map, rate), boundary, "{rate:?} positive minute snap");
assert_eq!(grid.line_at_or_before(-boundary, sr, &map, rate), -boundary, "{rate:?} negative minute boundary");
assert_eq!(grid.snap(-boundary, sr, &map, rate), -boundary, "{rate:?} negative minute snap");
let negative_boundary = rate.samples_at_frame(-minute_frame, sr);
assert_eq!(grid.line_at_or_before(negative_boundary, sr, &map, rate), negative_boundary, "{rate:?} negative minute boundary");
assert_eq!(grid.snap(negative_boundary, sr, &map, rate), negative_boundary, "{rate:?} negative minute snap");
}
}
+27 -1
View File
@@ -38,8 +38,16 @@ pub enum TimeError {
/// Sample rates supported by sessions (Pro Tools offers 44.1 k – 192 k; we accept 8 k – 768 k).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, serde::Serialize, serde::Deserialize)]
#[serde(try_from = "u32")]
pub struct SampleRate(u32);
impl TryFrom<u32> for SampleRate {
type Error = TimeError;
fn try_from(hz: u32) -> Result<Self, Self::Error> {
Self::new(hz)
}
}
impl SampleRate {
pub const HZ_44100: SampleRate = SampleRate(44_100);
pub const HZ_48000: SampleRate = SampleRate(48_000);
@@ -107,7 +115,7 @@ impl Range {
s >= self.start && s < self.end
}
pub fn overlaps(&self, o: &Range) -> bool {
self.start < o.end && o.start < self.end
!self.is_empty() && !o.is_empty() && self.start < o.end && o.start < self.end
}
pub fn intersect(&self, o: &Range) -> Option<Range> {
let s = self.start.max(o.start);
@@ -123,6 +131,24 @@ impl Range {
mod tests {
use super::*;
#[test]
fn sample_rate_serde_validates_nonzero_bounds() {
assert!(serde_json::from_str::<SampleRate>("0").is_err());
assert!(serde_json::from_str::<SampleRate>("7999").is_err());
let rate = SampleRate::new(48_000).unwrap();
assert_eq!(serde_json::to_string(&rate).unwrap(), "48000");
assert_eq!(serde_json::from_str::<SampleRate>("48000").unwrap(), rate);
}
#[test]
fn empty_ranges_never_overlap() {
let point = Range::point(5);
let span = Range::new(0, 10);
assert!(!point.overlaps(&span));
assert!(!span.overlaps(&point));
assert!(Range::new(0, 5).overlaps(&span));
}
#[test]
fn sample_rate_bounds() {
assert!(SampleRate::new(48_000).is_ok());
+17 -6
View File
@@ -108,9 +108,12 @@ impl FrameRate {
if n == 0 {
return 0;
}
// Round half away from zero so negative frames mirror positive ones.
let mag = (i128::from(f.unsigned_abs()) * i128::from(sr.hz()) * i128::from(d) + i128::from(n) / 2) / i128::from(n);
let v = if f < 0 { -mag } else { mag };
// Use the first integer sample whose floored frame lookup is `f`; nearest rounding
// can put fractional-rate frame starts just before their own lookup interval.
let numerator = i128::from(f) * i128::from(sr.hz()) * i128::from(d);
let denominator = i128::from(n);
let floor = numerator.div_euclid(denominator);
let v = floor + i128::from(numerator.rem_euclid(denominator) != 0);
i64::try_from(v).unwrap_or(if v < 0 { i64::MIN } else { i64::MAX })
}
@@ -194,6 +197,12 @@ impl Timecode {
Some(r) => (true, r),
None => (false, t),
};
if t.len() > 80 {
return Err(TimeError::Parse("timecode is too long".into(), "timecode"));
}
if t.bytes().filter(|b| matches!(b, b':' | b';' | b'.')).count() > 3 {
return Err(TimeError::Parse(text.to_string(), "timecode"));
}
let parts: Vec<&str> = t.split([':', ';', '.']).collect();
if parts.is_empty() || parts.len() > 4 {
return Err(TimeError::Parse(text.to_string(), "timecode"));
@@ -232,15 +241,16 @@ mod tests {
}
#[test]
fn negative_timecode_rounds_symmetrically() {
fn fractional_frame_starts_match_floored_lookup_on_both_sides_of_zero() {
let sr = SampleRate::HZ_48000;
let tc = Timecode::parse("-00:00:01:00").unwrap();
assert_eq!(tc.to_samples(FrameRate::Fps25, sr), -48_000);
for r in [FrameRate::Fps25, FrameRate::Fps29_97, FrameRate::Fps29_97Drop, FrameRate::Fps23_976] {
for f in [1i64, 7, 25, 1799, 107_892] {
assert_eq!(r.samples_at_frame(-f, sr), -r.samples_at_frame(f, sr), "{r:?} frame {f}");
for f in [-107_892i64, -25, -7, -1, 0, 1, 2, 7, 25, 1799, 107_892] {
assert_eq!(r.frames_at(r.samples_at_frame(f, sr), sr), f, "{r:?} frame {f}");
}
}
assert_eq!(FrameRate::Fps29_97.frames_at(FrameRate::Fps29_97.samples_at_frame(2, sr), sr), 2);
}
#[test]
@@ -299,6 +309,7 @@ mod tests {
assert_eq!((tc.seconds, tc.frames), (3, 4));
assert!(Timecode::parse("a:b").is_err());
assert!(Timecode::parse("1:2:3:4:5").is_err());
assert!(Timecode::parse(&format!("{}:", "1".repeat(100_000))).is_err());
}
#[test]
+1
View File
@@ -20,6 +20,7 @@ otio = ["dep:serde_json"]
[dependencies]
serde = { workspace = true, optional = true }
craft-time.workspace = true
craft-xml = { workspace = true, optional = true }
serde_json = { workspace = true, optional = true }
+16 -616
View File
@@ -1,627 +1,27 @@
//! Exact media time.
//! Compatibility re-exports for timeline time primitives.
//!
//! All time is an integer number of [`Tick`]s at [`TICKS_PER_SECOND`] = 254 016 000 000/s. That
//! rate divides evenly into every broadcast frame duration (23.976, 24, 25, 29.97, 30, 48, 50,
//! 59.94, 60, 120 …) and every common audio sample duration (8 k … 192 kHz, including the 44.1 k
//! family), so edits, frame math and audio alignment never drift.
//!
//! Timecode (SMPTE drop/non-drop, frames, feet+frames, samples) is only a *display* of ticks.
//!
//! Every conversion is total: a zero or negative rate (from a damaged file or project) gives
//! zero instead of a division-by-zero panic, and an invalid [`FrameRate`] counts as the default.
//! The implementation lives in `craft-time`; this module keeps the established
//! `craft_timeline::time::*` paths available to downstream users.
use std::fmt;
use std::ops::{Add, AddAssign, Neg, Sub, SubAssign};
pub use craft_time::{
FrameRate, ParseError, SAMPLE_RATES, TICKS_PER_SECOND, Tick, TimeDisplay, TimeRange, fields_to_frames, format_timecode_frames, frames_to_fields,
parse_time_display_relative as parse_time_display, parse_timecode_relative as parse_timecode,
};
/// Ticks per second.
pub const TICKS_PER_SECOND: i64 = 254_016_000_000;
/// A point or duration in time, in ticks.
/// Arithmetic saturates at the i64 storage limits; representable results remain exact.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
#[cfg_attr(feature = "serde", serde(transparent))]
pub struct Tick(pub i64);
impl Tick {
pub const ZERO: Tick = Tick(0);
pub const MAX: Tick = Tick(i64::MAX / 4);
pub const MIN: Tick = Tick(i64::MIN / 4);
pub fn from_seconds_f64(s: f64) -> Tick {
Tick((s * TICKS_PER_SECOND as f64).round() as i64)
}
pub fn seconds(self) -> f64 {
self.0 as f64 / TICKS_PER_SECOND as f64
}
/// Exact conversion from a count of `units` at `per_second` (e.g. samples at 48 000).
pub fn from_units(units: i64, per_second: i64) -> Tick {
Tick(clamp_i64((units as i128 * TICKS_PER_SECOND as i128).checked_div(per_second as i128).unwrap_or(0)))
}
/// Floor conversion to a count of units at `per_second`.
pub fn to_units_floor(self, per_second: i64) -> i64 {
clamp_i64((self.0 as i128 * per_second as i128).div_euclid(TICKS_PER_SECOND as i128))
}
/// Conversion from a rational timestamp `pts * num / den` seconds (container timebases).
pub fn from_rational(pts: i64, num: i64, den: i64) -> Tick {
if den == 0 {
return Tick::ZERO;
}
let Some(t) = (pts as i128 * num as i128).checked_mul(TICKS_PER_SECOND as i128) else {
// A product beyond i128 divided by an i64 cannot fit back into i64.
return Tick(if (pts < 0) ^ (num < 0) ^ (den < 0) { i64::MIN } else { i64::MAX });
};
Tick(clamp_i64(t.div_euclid(den as i128)))
}
/// Inverse of [`Tick::from_rational`], floored to the timebase.
pub fn to_rational_floor(self, num: i64, den: i64) -> i64 {
clamp_i64((self.0 as i128 * den as i128).checked_div_euclid(num as i128 * TICKS_PER_SECOND as i128).unwrap_or(0))
}
/// Inverse of [`Tick::from_rational`], rounded to the nearest timebase unit (halves up).
///
/// For finding a sample by its timestamp: containers store timestamps rounded to their
/// timebase (Matroska usually to 1 ms), so a stamp can sit up to half a unit after the true
/// time. Flooring the requested time misses every frame whose stamp was rounded up.
pub fn to_rational_round(self, num: i64, den: i64) -> i64 {
let n = self.0 as i128 * den as i128;
let unit = num as i128 * TICKS_PER_SECOND as i128;
let (n, unit) = if unit < 0 { (-n, -unit) } else { (n, unit) };
let (Some(q), Some(r)) = (n.checked_div_euclid(unit), n.checked_rem_euclid(unit)) else { return 0 };
// 0 <= r < unit: round up from the halfway point
clamp_i64(if r * 2 >= unit { q + 1 } else { q })
}
pub fn abs(self) -> Tick {
Tick(self.0.saturating_abs())
}
pub fn min(self, o: Tick) -> Tick {
Tick(self.0.min(o.0))
}
pub fn max(self, o: Tick) -> Tick {
Tick(self.0.max(o.0))
}
pub fn clamp(self, lo: Tick, hi: Tick) -> Tick {
// max/min rather than `clamp`, which panics when the bounds cross.
Tick(self.0.max(lo.0).min(hi.0))
}
/// Scale by a rational factor (`num/den`), flooring.
pub fn mul_ratio(self, num: i64, den: i64) -> Tick {
Tick(clamp_i64((self.0 as i128 * num as i128).checked_div_euclid(den as i128).unwrap_or(0)))
}
}
impl Add for Tick {
type Output = Tick;
fn add(self, o: Tick) -> Tick {
Tick(self.0.saturating_add(o.0))
}
}
impl Sub for Tick {
type Output = Tick;
fn sub(self, o: Tick) -> Tick {
Tick(self.0.saturating_sub(o.0))
}
}
impl Neg for Tick {
type Output = Tick;
fn neg(self) -> Tick {
Tick(self.0.saturating_neg())
}
}
impl AddAssign for Tick {
fn add_assign(&mut self, o: Tick) {
self.0 = self.0.saturating_add(o.0);
}
}
impl SubAssign for Tick {
fn sub_assign(&mut self, o: Tick) {
self.0 = self.0.saturating_sub(o.0);
}
}
/// A half-open time range `[start, start + duration)`.
/// Zero or negative durations are empty and never overlap another range.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct TimeRange {
pub start: Tick,
pub duration: Tick,
}
impl TimeRange {
pub fn new(start: Tick, duration: Tick) -> Self {
Self { start, duration }
}
pub fn from_bounds(start: Tick, end: Tick) -> Self {
Self { start, duration: end - start }
}
pub fn end(&self) -> Tick {
self.start + self.duration
}
pub fn contains(&self, t: Tick) -> bool {
t >= self.start && t < self.end()
}
pub fn overlaps(&self, o: &TimeRange) -> bool {
!self.is_empty() && !o.is_empty() && self.start < o.end() && o.start < self.end()
}
pub fn intersect(&self, o: &TimeRange) -> Option<TimeRange> {
let s = self.start.max(o.start);
let e = self.end().min(o.end());
(e > s).then(|| TimeRange::from_bounds(s, e))
}
pub fn is_empty(&self) -> bool {
self.duration.0 <= 0
}
}
/// A frame rate as an exact rational (`num / den` frames per second).
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct FrameRate {
pub num: i64,
pub den: i64,
}
impl Default for FrameRate {
fn default() -> Self {
FrameRate::FPS_23_976
}
}
impl FrameRate {
pub const FPS_23_976: FrameRate = FrameRate { num: 24000, den: 1001 };
pub const FPS_24: FrameRate = FrameRate { num: 24, den: 1 };
pub const FPS_25: FrameRate = FrameRate { num: 25, den: 1 };
pub const FPS_29_97: FrameRate = FrameRate { num: 30000, den: 1001 };
pub const FPS_30: FrameRate = FrameRate { num: 30, den: 1 };
pub const FPS_48: FrameRate = FrameRate { num: 48, den: 1 };
pub const FPS_50: FrameRate = FrameRate { num: 50, den: 1 };
pub const FPS_59_94: FrameRate = FrameRate { num: 60000, den: 1001 };
pub const FPS_60: FrameRate = FrameRate { num: 60, den: 1 };
pub const FPS_119_88: FrameRate = FrameRate { num: 120000, den: 1001 };
pub const FPS_120: FrameRate = FrameRate { num: 120, den: 1 };
/// Rates offered in sequence settings (Premiere's list).
pub const COMMON: [FrameRate; 11] = [
Self::FPS_23_976,
Self::FPS_24,
Self::FPS_25,
Self::FPS_29_97,
Self::FPS_30,
Self::FPS_48,
Self::FPS_50,
Self::FPS_59_94,
Self::FPS_60,
Self::FPS_119_88,
Self::FPS_120,
];
pub fn new(num: i64, den: i64) -> Self {
let g = i128::from(gcd(num.unsigned_abs(), den.unsigned_abs()).max(1));
FrameRate { num: (i128::from(num) / g) as i64, den: (i128::from(den) / g) as i64 }
}
/// Closest standard rate for a float (e.g. from a container's average rate).
pub fn from_f64(fps: f64) -> Self {
for r in Self::COMMON {
if (r.as_f64() - fps).abs() < 0.005 {
return r;
}
}
FrameRate::new((fps * 1000.0).round() as i64, 1000)
}
/// Closest standard rate when `fps` is within `tolerance` of it, `tolerance` a fraction of the
/// rate (`0.005` is half a percent), else the nearest 1/1000 rate. A rate a container reports
/// from timestamps rounded to a coarse unit lands slightly off a standard rate: at 90 kHz,
/// whole milliseconds leave a 30 fps clip's average at 30.02 or 29.95 (#1700).
pub fn from_f64_within(fps: f64, tolerance: f64) -> Self {
let mut best: Option<(f64, FrameRate)> = None;
for r in Self::COMMON {
let off = (r.as_f64() - fps).abs();
if off <= tolerance * r.as_f64() && best.is_none_or(|(closest, _)| off < closest) {
best = Some((off, r));
}
}
best.map_or_else(|| Self::from_f64(fps), |(_, r)| r)
}
/// This rate if it is positive, else the default (a damaged file or project can carry a zero
/// or negative rate; every frame computation uses this so it can't divide by zero).
pub fn sane(self) -> FrameRate {
if self.num > 0 && self.den > 0 { self } else { FrameRate::default() }
}
pub fn as_f64(self) -> f64 {
self.num as f64 / self.den as f64
}
/// Exact duration of one frame (rounded down only for exotic rates).
/// Values outside the integer tick range saturate at its limit.
pub fn frame_duration(self) -> Tick {
let r = self.sane();
Tick(clamp_i64((TICKS_PER_SECOND as i128 * r.den as i128) / r.num as i128))
}
/// Index of the frame containing `t` (floor), saturated to the integer frame range.
pub fn frame_at(self, t: Tick) -> i64 {
clamp_i64(frame_index(self.sane(), t))
}
/// Frames from `start` to `end`, counted between their frame indices. `frame_at(end - start)`
/// can read one short when a frame is not a whole number of ticks: the ticks between two
/// boundaries can be one fewer than the exact length of those frames.
pub fn frames_between(self, start: Tick, end: Tick) -> i64 {
self.frame_at(end).saturating_sub(self.frame_at(start))
}
/// Start tick of frame `f` (ceiling division).
///
/// Uses ceiling (not floor) so that `frame_at(tick_of(f)) == f` holds for every
/// representable frame boundary with at least one tick per frame, even when the frame duration is not an integer number of ticks
/// (exotic rates like 37.516 fps where `TICKS_PER_SECOND * den / num` has a
/// fractional remainder). Floor division truncates the remainder, causing each
/// frame boundary to drift backward by one tick until `frame_at` returns `f - 1`
/// instead of `f` — frame stepping then stalls or moves backward.
/// Values outside the integer tick range saturate at its limit.
pub fn tick_of(self, f: i64) -> Tick {
Tick(clamp_i64(frame_boundary(self.sane(), i128::from(f))))
}
/// Snap `t` down to a frame boundary.
pub fn snap(self, t: Tick) -> Tick {
let r = self.sane();
Tick(clamp_i64(frame_boundary(r, frame_index(r, t))))
}
/// Snap `t` to the nearest frame boundary.
pub fn snap_nearest(self, t: Tick) -> Tick {
let r = self.sane();
// Keep the frame index and both boundaries wide until choosing the nearest. Saturating
// an unrepresentable upper boundary first would make it seem closer than it really is.
let f = frame_index(r, t);
let a = frame_boundary(r, f);
let b = frame_boundary(r, f.saturating_add(1));
let t = i128::from(t.0);
Tick(clamp_i64(if t - a <= b - t { a } else { b }))
}
/// Timecode base (frames counted per timecode second): 30 for 29.97, 24 for 23.976.
pub fn timecode_base(self) -> i64 {
let r = self.sane();
(r.num / r.den).saturating_add(i64::from(r.num % r.den != 0)).max(1)
}
/// NTSC (x/1001) rates can use drop-frame timecode.
pub fn is_ntsc(self) -> bool {
self.den == 1001
}
/// Whether drop-frame counting applies (29.97 / 59.94 / 119.88).
pub fn supports_drop_frame(self) -> bool {
self.is_ntsc() && self.timecode_base() % 30 == 0
}
pub fn label(self) -> String {
if self.den == 1 {
format!("{}", self.num)
} else {
let v = self.as_f64();
let s = format!("{v:.3}");
let s = s.trim_end_matches('0').trim_end_matches('.');
s.to_string()
}
}
}
impl fmt::Display for FrameRate {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(f, "{} fps", self.label())
}
}
/// Narrow only after applying the storage bounds, never by a wrapping integer cast.
fn clamp_i64(value: i128) -> i64 {
value.clamp(i128::from(i64::MIN), i128::from(i64::MAX)) as i64
}
/// Callers pass a positive rate. Products of two i64 values fit in i128.
fn frame_index(rate: FrameRate, t: Tick) -> i128 {
(i128::from(t.0) * i128::from(rate.num)).div_euclid(i128::from(TICKS_PER_SECOND) * i128::from(rate.den))
}
/// Ceiling of the rational boundary. An overflowing numerator divided by an i64 rate cannot
/// fit in an i64 tick, so saturating that intermediate preserves the public result. Boundaries
/// derived from frame_index remain within i128 (at most one frame away from an i64 tick).
fn frame_boundary(rate: FrameRate, frame: i128) -> i128 {
let Some(n) = frame.checked_mul(i128::from(TICKS_PER_SECOND)).and_then(|n| n.checked_mul(i128::from(rate.den))) else {
return if frame < 0 { i128::MIN } else { i128::MAX };
};
let d = i128::from(rate.num);
// Flooring a fractional boundary puts the tick in the preceding frame.
n.div_euclid(d) + i128::from(n.rem_euclid(d) != 0)
}
fn gcd(mut a: u64, mut b: u64) -> u64 {
while b != 0 {
(a, b) = (b, a % b);
}
a
}
/// How time is displayed (Premiere: Timecode, Feet+Frames 16mm/35mm, Frames, Audio Samples).
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub enum TimeDisplay {
#[default]
Timecode,
Frames,
Feet16,
Feet35,
AudioSamples,
Seconds,
}
impl TimeDisplay {
pub const ALL: [TimeDisplay; 6] =
[TimeDisplay::Timecode, TimeDisplay::Feet35, TimeDisplay::Feet16, TimeDisplay::Frames, TimeDisplay::AudioSamples, TimeDisplay::Seconds];
pub fn label(self) -> &'static str {
match self {
TimeDisplay::Timecode => "Timecode",
TimeDisplay::Frames => "Frames",
TimeDisplay::Feet16 => "Feet + Frames 16mm",
TimeDisplay::Feet35 => "Feet + Frames 35mm",
TimeDisplay::AudioSamples => "Audio Samples",
TimeDisplay::Seconds => "Seconds",
}
}
}
impl TimeDisplay {
/// The video display formats (Sequence Settings ▸ Display Format, the burn-in's Time Format).
pub const VIDEO: [TimeDisplay; 4] = [TimeDisplay::Timecode, TimeDisplay::Feet35, TimeDisplay::Feet16, TimeDisplay::Frames];
/// Stable id used by commands and the UI: `timecode`, `feet35`, `feet16`, `frames`, `samples`, `seconds`.
pub fn id(self) -> &'static str {
match self {
TimeDisplay::Timecode => "timecode",
TimeDisplay::Frames => "frames",
TimeDisplay::Feet16 => "feet16",
TimeDisplay::Feet35 => "feet35",
TimeDisplay::AudioSamples => "samples",
TimeDisplay::Seconds => "seconds",
}
}
/// The display with this [`id`](Self::id), ignoring case.
pub fn from_id(id: &str) -> Option<TimeDisplay> {
TimeDisplay::ALL.into_iter().find(|d| d.id().eq_ignore_ascii_case(id))
}
/// Frames per foot of film for the Feet + Frames displays: 16 for 35mm 4-perf, 40 for 16mm.
pub fn frames_per_foot(self) -> Option<i64> {
match self {
TimeDisplay::Feet35 => Some(16),
TimeDisplay::Feet16 => Some(40),
_ => None,
}
}
}
/// Format a frame count as film feet + frames (`F+FF`, e.g. `2+08`; negative: `-2+08`).
/// `frames_per_foot` below 1 is treated as 1 so a bad value never divides by zero.
/// Format a timeline frame count as film feet + frames, retaining its established compact display.
pub fn format_feet_frames(frame: i64, frames_per_foot: i64) -> String {
let per_ft = frames_per_foot.max(1).unsigned_abs();
let a = frame.unsigned_abs();
format!("{}{}+{:02}", if frame < 0 { "-" } else { "" }, a / per_ft, a % per_ft)
let per_foot = frames_per_foot.max(1).unsigned_abs();
let frames = frame.unsigned_abs();
format!("{}{}+{:02}", if frame < 0 { "-" } else { "" }, frames / per_foot, frames % per_foot)
}
/// Drop-frame parameters: frames dropped per minute and nominal base.
fn df_params(rate: FrameRate) -> (i64, i64) {
let base = rate.timecode_base();
(base / 15, base) // 30 → 2, 60 → 4, 120 → 8
}
/// Convert a frame count to SMPTE fields `(negative, h, m, s, f)`.
pub fn frames_to_fields(frame: i64, rate: FrameRate, drop_frame: bool) -> (bool, i64, i64, i64, i64) {
let neg = frame < 0;
let mut n = i128::from(frame).abs();
let (drop, base) = df_params(rate);
let (drop, base) = (i128::from(drop), i128::from(base));
if drop_frame && rate.supports_drop_frame() {
let per_min = base * 60 - drop;
let per_10 = per_min * 10 + drop;
let d = n / per_10;
let m = n % per_10;
n = n.saturating_add(drop * 9 * d);
if m > drop {
n = n.saturating_add(drop * ((m - drop) / per_min));
}
/// Format time using the timeline's historical compact Feet + Frames display.
pub fn format_time(tick: Tick, rate: FrameRate, drop_frame: bool, display: TimeDisplay, sample_rate: i64) -> String {
if let TimeDisplay::Feet35 | TimeDisplay::Feet16 = display {
return format_feet_frames(rate.frame_at(tick), display.frames_per_foot().unwrap_or(16));
}
let f = n % base;
let s = (n / base) % 60;
let mi = (n / (base * 60)) % 60;
let h = n / (base * 3600);
(neg, clamp_i64(h), clamp_i64(mi), clamp_i64(s), clamp_i64(f))
craft_time::format_time(tick, rate, drop_frame, display, sample_rate)
}
/// Convert SMPTE fields back to a frame count.
pub fn fields_to_frames(h: i64, m: i64, s: i64, f: i64, rate: FrameRate, drop_frame: bool) -> i64 {
let (drop, base) = df_params(rate);
let seconds = i128::from(h) * 3600 + i128::from(m) * 60 + i128::from(s);
// Nominal drop-frame labels can exceed i64 even when the final frame count fits.
let mut n = seconds.saturating_mul(i128::from(base)).saturating_add(i128::from(f));
if drop_frame && rate.supports_drop_frame() {
let total_min = i128::from(h) * 60 + i128::from(m);
n = n.saturating_sub(i128::from(drop) * (total_min - total_min / 10));
}
clamp_i64(n)
}
/// Format a frame count as SMPTE timecode (`HH:MM:SS:FF`, or `HH;MM;SS;FF` for drop-frame).
pub fn format_timecode_frames(frame: i64, rate: FrameRate, drop_frame: bool) -> String {
let df = drop_frame && rate.supports_drop_frame();
let (neg, h, m, s, f) = frames_to_fields(frame, rate, df);
let sep = if df { ';' } else { ':' };
let fw = if rate.timecode_base() >= 100 { 3 } else { 2 };
format!("{}{h:02}{sep}{m:02}{sep}{s:02}{sep}{f:0fw$}", if neg { "-" } else { "" })
}
/// Format a tick according to a display mode.
pub fn format_time(t: Tick, rate: FrameRate, drop_frame: bool, display: TimeDisplay, sample_rate: i64) -> String {
let frame = rate.frame_at(t);
match display {
TimeDisplay::Timecode => format_timecode_frames(frame, rate, drop_frame),
TimeDisplay::Frames => format!("{frame}"),
TimeDisplay::Feet35 | TimeDisplay::Feet16 => format_feet_frames(frame, display.frames_per_foot().unwrap_or(16)),
TimeDisplay::AudioSamples => {
let neg = t.0 < 0;
let a = t.0.unsigned_abs();
let tps = TICKS_PER_SECOND.unsigned_abs();
let secs = a / tps;
let rem = Tick((a % tps) as i64).to_units_floor(sample_rate);
format!("{}{:02}:{:02}:{:02}:{rem:05}", if neg { "-" } else { "" }, secs / 3600, (secs / 60) % 60, secs % 60)
}
TimeDisplay::Seconds => {
let s = format!("{:.3}", t.seconds());
// A tiny negative time rounds to zero but keeps its sign: drop it.
if s == "-0.000" { "0.000".to_string() } else { s }
}
}
}
/// Error from [`parse_timecode`].
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct ParseError(pub String);
impl fmt::Display for ParseError {
fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
f.write_str(&self.0)
}
}
impl std::error::Error for ParseError {}
/// Parse user-typed timecode into a frame count, the way Premiere's timecode fields do:
/// - `01:02:03:04`, `01;02;03;04`, `1.2.3.4` (any of `:;.,` separators),
/// - bare digits are read right-aligned as `HHMMSSFF` (`1000` = 00:00:10:00),
/// - a leading `+`/`-` makes the value relative to `current` (`+15` = 15 frames later, `-1.00` = 1 s earlier).
pub fn parse_timecode(input: &str, rate: FrameRate, drop_frame: bool, current: i64) -> Result<i64, ParseError> {
let s = input.trim();
if s.is_empty() {
return Err(ParseError("empty timecode".into()));
}
let (rel, body) = match s.as_bytes()[0] {
b'+' => (Some(1), &s[1..]),
b'-' => (Some(-1), &s[1..]),
_ => (None, s),
};
let parts: Vec<&str> = body.split([':', ';', '.', ',']).collect();
let nums: Vec<i64> = if parts.len() == 1 {
let digits = parts[0];
if digits.is_empty() || !digits.bytes().all(|b| b.is_ascii_digit()) {
return Err(ParseError(format!("not a timecode: `{input}`")));
}
// Right-aligned pairs: "12345" -> [1, 23, 45]; relative bare numbers are frames.
if rel.is_some() {
vec![digits.parse().map_err(|_| ParseError("number too large".into()))?]
} else {
let mut v = Vec::new();
let b = digits.as_bytes();
let mut end = b.len();
while end > 0 {
let start = end.saturating_sub(2);
v.push(digits[start..end].parse::<i64>().unwrap_or(0));
end = start;
}
v.reverse();
v
}
} else {
parts
.iter()
.map(|p| {
if p.is_empty() {
Ok(0)
} else if !p.bytes().all(|b| b.is_ascii_digit()) {
Err(ParseError(format!("bad field `{p}`")))
} else {
p.parse::<i64>().map_err(|_| ParseError(format!("bad field `{p}`")))
}
})
.collect::<Result<_, _>>()?
};
if nums.len() > 4 {
return Err(ParseError("too many timecode fields".into()));
}
let mut f4 = [0i64; 4];
let off = 4 - nums.len();
f4[off..].copy_from_slice(&nums);
let [h, m, sec, fr] = f4;
// Overflowing fields (e.g. 90 frames) are allowed, as in Premiere.
let base = rate.timecode_base();
let frames = if nums.len() == 1 && rel.is_some() {
fr
} else if drop_frame && rate.supports_drop_frame() {
// overflowing fields carry into the next one first, then drop-frame counting applies
let (sec, fr) = (sec.saturating_add(fr / base), fr % base);
let (m, sec) = (m.saturating_add(sec / 60), sec % 60);
let (h, m) = (h.saturating_add(m / 60), m % 60);
fields_to_frames(h, m, sec, fr, rate, true)
} else {
// Saturating: typed or agent-sent timecodes can have absurdly large fields.
h.saturating_mul(3600).saturating_add(m.saturating_mul(60)).saturating_add(sec).saturating_mul(base).saturating_add(fr)
};
Ok(match rel {
Some(sign) => current.saturating_add(frames.saturating_mul(sign)),
None => frames,
})
}
/// Parse typed text in the given display format into a frame count.
///
/// - [`TimeDisplay::Frames`]: a plain frame count (`240`).
/// - [`TimeDisplay::Feet35`] / [`TimeDisplay::Feet16`]: `F+FF` (`2+08`; `.`, `:`, `;` and `,` also
/// separate); a bare number is a frame count. A frames field past the foot rolls over
/// (`1+20` at 35mm is 36 frames), as the timecode parser does.
/// - A leading `+` / `-` makes the value relative to `current` (a bare relative number is frames).
/// - Every other display parses as timecode ([`parse_timecode`]).
pub fn parse_time_display(input: &str, rate: FrameRate, drop_frame: bool, display: TimeDisplay, current: i64) -> Result<i64, ParseError> {
let per_ft = match display {
TimeDisplay::Frames => 1,
TimeDisplay::Feet35 | TimeDisplay::Feet16 => display.frames_per_foot().unwrap_or(16),
_ => return parse_timecode(input, rate, drop_frame, current),
};
let s = input.trim();
if s.is_empty() {
return Err(ParseError("empty time".into()));
}
let (rel, body) = match s.as_bytes()[0] {
b'+' => (Some(1), &s[1..]),
b'-' => (Some(-1), &s[1..]),
_ => (None, s),
};
let field = |p: &str| -> Result<i64, ParseError> {
if p.is_empty() {
Ok(0)
} else if !p.bytes().all(|b| b.is_ascii_digit()) {
Err(ParseError(format!("not a time: `{input}`")))
} else {
p.parse::<i64>().map_err(|_| ParseError("number too large".into()))
}
};
let parts: Vec<&str> = body.split(['+', ':', ';', '.', ',']).collect();
let frames = match parts.as_slice() {
[n] => field(n)?,
[feet, fr] if per_ft > 1 => field(feet)?.saturating_mul(per_ft).saturating_add(field(fr)?),
_ => return Err(ParseError(format!("not a time: `{input}`"))),
};
Ok(match rel {
Some(sign) => current.saturating_add(frames.saturating_mul(sign)),
None => frames,
})
}
/// Common audio sample rates offered in sequence settings.
pub const SAMPLE_RATES: [i64; 6] = [32_000, 44_100, 48_000, 88_200, 96_000, 192_000];
#[cfg(test)]
mod tests;
+4
View File
@@ -1,6 +1,10 @@
use super::*;
use proptest::prelude::*;
fn clamp_i64(value: i128) -> i64 {
value.clamp(i128::from(i64::MIN), i128::from(i64::MAX)) as i64
}
#[test]
fn empty_time_ranges_never_overlap() {
let clip = TimeRange::new(Tick(0), Tick(10));
+1 -1
View File
@@ -117,7 +117,7 @@ impl<P: Clone + Eq + Hash + Debug + Send + Sync + 'static> Renderer<'_, P> {
// release outside the window floats.
let gone = !has_pointer && !touch_ended;
let floats_outside = !self.style.float_on_empty_drop && drag.gesture != GroupGesture::Window;
if !(released && !gone) && !(gone && floats_outside) {
if !(released && !gone || gone && floats_outside) {
return;
}
let Some(pointer) = pointer.filter(|p| !self.blockers.iter().any(|r| r.contains(*p))) else { return };
+2 -1
View File
@@ -99,7 +99,8 @@ A picture is refused when the pictures the decoder would hold do not fit
1 GiB on 32-bit targets): the DPB (the larger of its slots at the new size and what it holds
now), the picture being decoded, and what is in flight or waiting in the output queue. Pictures
already held count at their own size, and a buffer shared by the DPB and the queue counts once.
The per-picture size cap applies as well.
The default per-picture luma cap is 2^25 samples; applications with a different bounded frame
policy can raise it with `Decoder::set_max_picture_luma_samples`.
`configure_avcc` checks every entry of the record before it handles any: the first list holds
SPS NAL units and the second PPS NAL units. A record that carries a picture slice is an error and
+12 -1
View File
@@ -115,6 +115,8 @@ pub struct Decoder {
/// Bytes the picture store may take ([`crate::budget`]).
memory_budget: u64,
threads: usize,
/// Maximum reconstructed luma samples in one picture.
max_luma_samples: u64,
/// Draft mode: skip deblocking of non-reference pictures ([`Decoder::set_draft`]).
draft: bool,
}
@@ -179,6 +181,7 @@ impl Decoder {
max_in_flight: threads.max(1) + 2,
memory_budget: crate::budget::DECODE_MEMORY_BUDGET,
threads: workers,
max_luma_samples: super::params::MAX_LUMA_SAMPLES,
draft: false,
}
}
@@ -391,7 +394,7 @@ impl Decoder {
// Before the header fields that depend on the SPS: they are validated for the streams
// we decode (a 10-bit slice may have a QP below 0), so a stream we cannot decode must
// fail as unsupported here, not as invalid there (#626).
sps.check_supported()?;
sps.check_supported_with_limit(self.max_luma_samples)?;
found = Some((pps.clone(), sps.clone()));
Ok((&**pps, &**sps))
})?;
@@ -468,6 +471,14 @@ impl Decoder {
self.memory_budget = bytes;
}
/// Set the maximum luma sample count allowed in a single decoded picture.
///
/// The default is 2^25 samples. This is a per-picture geometry guard; the separate
/// memory budget controls aggregate decoded picture storage.
pub fn set_max_picture_luma_samples(&mut self, samples: u64) {
self.max_luma_samples = samples;
}
/// Refuse an SPS whose pictures would not fit the memory budget, before anything is allocated.
fn check_budget(&self, sps: &Sps) -> Result<()> {
let chroma = sps.chroma_array_type();
+84 -5
View File
@@ -176,6 +176,7 @@ impl<F: Clone> Dpb<F> {
return Ok(lists);
}
let cur_fn = sh.frame_num;
ensure!(max_frame_num > 0 && max_frame_num <= (1 << 16) && cur_fn < max_frame_num, "frame number out of range");
let pic_num = |e: &DpbEntry<F>| Self::frame_num_wrap(e, cur_fn, max_frame_num);
let short: Vec<&DpbEntry<F>> = self.entries.iter().filter(|e| e.mark == RefMark::Short).collect();
let mut long: Vec<&DpbEntry<F>> = self.entries.iter().filter(|e| e.mark == RefMark::Long).collect();
@@ -212,6 +213,7 @@ impl<F: Clone> Dpb<F> {
let mut ref_idx = 0usize;
for m in &sh.ref_pic_list_mod[l] {
ensure!(ref_idx < n, "too many ref_pic_list_modification entries");
ensure!(m.idc >= 2 || m.value < max_frame_num, "abs_diff_pic_num_minus1 out of range");
list.push(None); // temporarily one longer
let (target, is_long): (Option<&DpbEntry<F>>, bool) = match m.idc {
0 | 1 => {
@@ -272,13 +274,13 @@ impl<F: Clone> Dpb<F> {
/// Adaptive memory control (8.2.5.4). Returns true if MMCO 5 was executed.
fn apply_mmcos(&mut self, mmcos: &[Mmco], cur_frame_num: u32, max_frame_num: u32, cur_long: &mut Option<u32>) -> Result<bool> {
let mut had5 = false;
let curr_pic_num = cur_frame_num as i32;
let curr_pic_num = i64::from(cur_frame_num);
for m in mmcos {
match m.op {
1 => {
let pn = curr_pic_num - (m.difference_of_pic_nums_minus1 as i32 + 1);
let pn = curr_pic_num - (i64::from(m.difference_of_pic_nums_minus1) + 1);
for e in &mut self.entries {
if e.mark == RefMark::Short && Self::frame_num_wrap(e, cur_frame_num, max_frame_num) == pn {
if e.mark == RefMark::Short && i64::from(Self::frame_num_wrap(e, cur_frame_num, max_frame_num)) == pn {
e.mark = RefMark::Unused;
}
}
@@ -295,14 +297,14 @@ impl<F: Clone> Dpb<F> {
self.max_long_term_frame_idx.is_some_and(|max| m.long_term_frame_idx <= max),
"MMCO long-term index exceeds the configured limit"
);
let pn = curr_pic_num - (m.difference_of_pic_nums_minus1 as i32 + 1);
let pn = curr_pic_num - (i64::from(m.difference_of_pic_nums_minus1) + 1);
for e in &mut self.entries {
if e.mark == RefMark::Long && e.long_term_frame_idx == m.long_term_frame_idx {
e.mark = RefMark::Unused;
}
}
for e in &mut self.entries {
if e.mark == RefMark::Short && Self::frame_num_wrap(e, cur_frame_num, max_frame_num) == pn {
if e.mark == RefMark::Short && i64::from(Self::frame_num_wrap(e, cur_frame_num, max_frame_num)) == pn {
e.mark = RefMark::Long;
e.long_term_frame_idx = m.long_term_frame_idx;
}
@@ -461,6 +463,83 @@ mod tests {
})
}
fn reference_slice() -> SliceHeader {
SliceHeader {
nal_ref_idc: 1,
nal_unit_type: 1,
idr: false,
first_mb_in_slice: 0,
slice_type_raw: 0,
slice_type: SliceType::P,
pps_id: 0,
colour_plane_id: 0,
frame_num: 0,
field_pic: false,
bottom_field: false,
idr_pic_id: 0,
pic_order_cnt_lsb: 0,
delta_pic_order_cnt_bottom: 0,
delta_pic_order_cnt: [0; 2],
redundant_pic_cnt: 0,
direct_spatial_mv_pred: false,
num_ref_idx_active: [1, 0],
ref_pic_list_mod: [Vec::new(), Vec::new()],
pred_weight_table: None,
no_output_of_prior_pics: false,
long_term_reference: false,
adaptive_ref_pic_marking: false,
mmcos: Vec::new(),
cabac_init_idc: 0,
slice_qp_delta: 0,
sp_for_switch: false,
slice_qs_delta: 0,
disable_deblocking_filter_idc: 0,
slice_alpha_c0_offset_div2: 0,
slice_beta_offset_div2: 0,
slice_group_change_cycle: 0,
header_bits: 0,
}
}
#[test]
fn large_picture_number_differences_do_not_overflow() {
for op in [1, 3] {
for difference in [i32::MAX as u32, 1 << 31, u32::MAX] {
let mut dpb: Dpb<u32> = Dpb::new();
dpb.max_long_term_frame_idx = Some(0);
let op = Mmco {
op,
difference_of_pic_nums_minus1: difference,
long_term_pic_num: 0,
long_term_frame_idx: 0,
max_long_term_frame_idx_plus1: 0,
};
assert!(dpb.apply_mmcos(&[op], 5, 16, &mut None).is_ok());
}
}
}
#[test]
fn invalid_reference_list_differences_are_rejected() {
use crate::h264::decode::slice::RefPicListMod;
for idc in [0, 1] {
for value in [0, 15] {
let mut sh = reference_slice();
sh.frame_num = 5;
sh.ref_pic_list_mod[0].push(RefPicListMod { idc, value });
let dpb: Dpb<u32> = Dpb::new();
assert!(dpb.build_ref_lists(&sh, 0, 16, |entry| entry.frame).is_ok());
}
for value in [16, i32::MAX as u32, 1 << 31, u32::MAX] {
let mut sh = reference_slice();
sh.frame_num = 5;
sh.ref_pic_list_mod[0].push(RefPicListMod { idc, value });
let dpb: Dpb<u32> = Dpb::new();
assert!(dpb.build_ref_lists(&sh, 0, 16, |entry| entry.frame).is_err());
}
}
}
/// A huge frame_num jump must only materialise the frames the sliding window keeps (#2779).
#[test]
fn frame_num_gap_materialises_at_most_max_num_ref_frames() {
+31 -2
View File
@@ -6,7 +6,7 @@ use craft_media::bitstream::BitReader;
/// Maximum supported reconstructed luma area. 8K UHD fits comfortably while
/// hostile SPS dimensions cannot allocate full pictures and decoder work state.
const MAX_LUMA_SAMPLES: u64 = 1 << 25;
pub(super) const MAX_LUMA_SAMPLES: u64 = 1 << 25;
/// Scaling matrices after applying fall-back rules, stored in raster order (weightScale).
#[derive(Clone, Debug, PartialEq, Eq)]
@@ -527,7 +527,11 @@ impl Sps {
}
pub fn check_supported(&self) -> Result<()> {
if u64::from(self.width()).saturating_mul(u64::from(self.height())) > MAX_LUMA_SAMPLES {
self.check_supported_with_limit(MAX_LUMA_SAMPLES)
}
pub(super) fn check_supported_with_limit(&self, max_luma_samples: u64) -> Result<()> {
if u64::from(self.width()).saturating_mul(u64::from(self.height())) > max_luma_samples {
return unsupported("picture dimensions exceed the decoder memory limit");
}
if !self.frame_mbs_only {
@@ -744,6 +748,31 @@ mod tests {
assert_eq!(sps.pic_order_cnt_type, 2);
assert_eq!(sps.crop_rect(), (0, 0, 176, 144));
}
#[test]
fn caller_can_raise_single_picture_sample_limit() {
let mut w = BitWriter::new();
w.write_bits(66, 8);
w.write_bits(0xC0, 8);
w.write_bits(30, 8);
w.write_ue(0);
w.write_ue(0);
w.write_ue(2);
w.write_ue(1);
w.write_bit(false);
w.write_ue(511); // 8192 luma samples wide
w.write_ue(511); // 8192 luma samples high
w.write_bit(true);
w.write_bit(true);
w.write_bit(false);
w.write_bit(false);
w.rbsp_trailing();
let sps = Sps::parse(&w.finish()).unwrap();
assert_eq!((sps.width(), sps.height()), (8192, 8192));
assert!(sps.check_supported().is_err());
assert!(sps.check_supported_with_limit(1 << 26).is_ok());
}
/// Baseline SPS with the given `ue(v)` overrides for the fields hostile streams can max out.
fn hostile_sps(profile: u32, bit_depth: u32, log2_frame_num: u32, w: u32, h: u32, crop: u32) -> Vec<u8> {
let mut bw = BitWriter::new();
+49 -19
View File
@@ -462,39 +462,42 @@ impl PocState {
let (prev_msb, prev_lsb) = if sh.idr { (0, 0) } else { (self.prev_ref_msb, self.prev_ref_lsb) };
let max_lsb = 1i32 << sps.log2_max_poc_lsb;
let lsb = sh.pic_order_cnt_lsb as i32;
let msb = if lsb < prev_lsb && prev_lsb.wrapping_sub(lsb) >= max_lsb / 2 {
prev_msb.wrapping_add(max_lsb)
} else if lsb > prev_lsb && lsb.wrapping_sub(prev_lsb) > max_lsb / 2 {
prev_msb.wrapping_sub(max_lsb)
let msb = if lsb < prev_lsb && prev_lsb.saturating_sub(lsb) >= max_lsb / 2 {
prev_msb.saturating_add(max_lsb)
} else if lsb > prev_lsb && lsb.saturating_sub(prev_lsb) > max_lsb / 2 {
prev_msb.saturating_sub(max_lsb)
} else {
prev_msb
};
let top = msb.wrapping_add(lsb);
let bottom = top.wrapping_add(sh.delta_pic_order_cnt_bottom);
let top = msb.saturating_add(lsb);
let bottom = top.saturating_add(sh.delta_pic_order_cnt_bottom);
Poc { top, bottom, msb, frame_num_offset: 0 }
}
1 => {
let frame_num_offset = self.frame_num_offset(sh.idr, sh.frame_num, sps);
let n = sps.offset_for_ref_frame.len() as i32;
let mut abs_frame_num = if n != 0 { frame_num_offset.wrapping_add(sh.frame_num as i32) } else { 0 };
let n = sps.offset_for_ref_frame.len() as i64;
let mut abs_frame_num = if n != 0 { i64::from(frame_num_offset) + i64::from(sh.frame_num) } else { 0 };
if sh.nal_ref_idc == 0 && abs_frame_num > 0 {
abs_frame_num -= 1;
}
let mut expected = 0i32;
let mut expected = 0i64;
if abs_frame_num > 0 {
let cycle_cnt = (abs_frame_num - 1) / n;
let in_cycle = (abs_frame_num - 1) % n;
let delta_cycle = sps.offset_for_ref_frame.iter().fold(0i32, |a, &o| a.wrapping_add(o));
expected = cycle_cnt.wrapping_mul(delta_cycle);
let delta_cycle = sps.offset_for_ref_frame.iter().map(|&o| i64::from(o)).sum::<i64>();
expected = cycle_cnt.saturating_mul(delta_cycle);
for &o in &sps.offset_for_ref_frame[..=in_cycle as usize] {
expected = expected.wrapping_add(o);
expected = expected.saturating_add(i64::from(o));
}
}
if sh.nal_ref_idc == 0 {
expected = expected.wrapping_add(sps.offset_for_non_ref_pic);
expected = expected.saturating_add(i64::from(sps.offset_for_non_ref_pic));
}
let top = expected.wrapping_add(sh.delta_pic_order_cnt[0]);
let bottom = top.wrapping_add(sps.offset_for_top_to_bottom_field).wrapping_add(sh.delta_pic_order_cnt[1]);
let top = expected.saturating_add(i64::from(sh.delta_pic_order_cnt[0])).clamp(i64::from(i32::MIN), i64::from(i32::MAX)) as i32;
let bottom = i64::from(top)
.saturating_add(i64::from(sps.offset_for_top_to_bottom_field))
.saturating_add(i64::from(sh.delta_pic_order_cnt[1]))
.clamp(i64::from(i32::MIN), i64::from(i32::MAX)) as i32;
Poc { top, bottom, msb: 0, frame_num_offset }
}
_ => {
@@ -502,9 +505,9 @@ impl PocState {
let temp = if sh.idr {
0
} else if sh.nal_ref_idc == 0 {
2i32.wrapping_mul(frame_num_offset.wrapping_add(sh.frame_num as i32)).wrapping_sub(1)
2i32.saturating_mul(frame_num_offset.saturating_add(sh.frame_num as i32)).saturating_sub(1)
} else {
2i32.wrapping_mul(frame_num_offset.wrapping_add(sh.frame_num as i32))
2i32.saturating_mul(frame_num_offset.saturating_add(sh.frame_num as i32))
};
Poc { top: temp, bottom: temp, msb: 0, frame_num_offset }
}
@@ -515,7 +518,7 @@ impl PocState {
if idr {
0
} else if self.prev_frame_num > frame_num {
self.prev_frame_num_offset.wrapping_add(sps.max_frame_num() as i32)
self.prev_frame_num_offset.saturating_add(sps.max_frame_num() as i32)
} else {
self.prev_frame_num_offset
}
@@ -528,7 +531,7 @@ impl PocState {
if sh.nal_ref_idc != 0 {
if mmco5 {
self.prev_ref_msb = 0;
self.prev_ref_lsb = poc.top.wrapping_sub(poc.frame());
self.prev_ref_lsb = poc.top.saturating_sub(poc.frame());
} else {
self.prev_ref_msb = poc.msb;
self.prev_ref_lsb = sh.pic_order_cnt_lsb as i32;
@@ -624,6 +627,14 @@ mod poc_tests {
}
}
#[test]
fn extreme_bottom_delta_saturates_instead_of_reversing_picture_order() {
let sps = sps(0);
let sh = header(0, 1, i32::MAX, [0, 0], 1);
let poc = PocState::default().compute(&sh, &sps);
assert_eq!((poc.top, poc.bottom), (1, i32::MAX));
}
/// Offsets and deltas are se(v) values that a stream may set anywhere in the i32 range.
#[test]
fn poc_does_not_overflow_on_extreme_deltas() {
@@ -654,4 +665,23 @@ mod poc_tests {
let _ = poc.frame();
state.update(&sh, &poc);
}
#[test]
fn poc_type1_cancellation_happens_before_clamping() {
let sps = sps(1);
let sh = header(0, 0, 0, [-i32::MAX, 0], 1);
let state = PocState { prev_frame_num_offset: 2, ..PocState::default() };
let poc = state.compute(&sh, &sps);
assert_eq!(poc.top, i32::MAX);
}
#[test]
fn poc_type1_saturates_only_after_wide_cycle_arithmetic_exceeds_i64() {
let mut sps = sps(1);
sps.offset_for_ref_frame = vec![i32::MAX; 255];
let sh = header(u32::MAX, 0, 0, [0, 0], 1);
let state = PocState { prev_frame_num_offset: i32::MAX, ..PocState::default() };
let poc = state.compute(&sh, &sps);
assert_eq!(poc.top, i32::MAX);
}
}
+7
View File
@@ -16,6 +16,8 @@ use craft_video::prores::*;
let frame: Frame = decode_frame(&sample)?; // 10-bit 4:2:2 / 12-bit 4:4:4
let f10 = decode_frame_with(&sample, &DecodeOptions { bit_depth: Some(10), threads: true })?;
decode_frame_into(&sample, &DecodeOptions::default(), &mut frame_buf)?; // reuses planes
let limits = DecodeLimits { max_pixels: 8192 * 8192, max_frame_bytes: 512 * 1024 * 1024 };
let bounded = decode_frame_with_limits(&sample, &DecodeOptions::default(), &limits)?;
let hdr: FrameHeader = probe(&sample)?; // header only
// Encode (progressive).
@@ -28,6 +30,11 @@ alpha: Option<Vec<u16>>, interlace: Interlace, color: ColorInfo { primaries, tra
aspect_ratio, frame_rate_code }` holds planar samples with no row padding (`chroma_width()` is
`ceil(width/2)` for 4:2:2). The colour codes are H.273 code points straight from the frame header.
`DecodeLimits` bounds both frame area and aggregate decoded plane storage before allocation.
`decode_frame_with` uses an aggregate limit of 300 MiB and does not impose an additional area
limit; use `decode_frame_with_limits` when the application needs a stricter pixel policy or a
different finite memory ceiling.
`Profile` = `Proxy` (`apco`), `Lt` (`apcs`), `Standard` (`apcn`), `Hq` (`apch`), `P4444` (`ap4h`),
`P4444Xq` (`ap4x`). The frame itself doesn't say which profile it is (only the container fourcc
does), so the decoder doesn't need to know.
+68 -2
View File
@@ -11,6 +11,21 @@ use crate::prores::{AlphaType, ChromaFormat, Error, Frame, Interlace, Result};
/// Maximum aggregate decoded plane storage for one ProRes frame (300 MiB; 8K ProRes 4444 with alpha is ~265 MiB).
const MAX_FRAME_BYTES: usize = 300 * 1024 * 1024;
/// Resource limits for decoding one ProRes frame.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DecodeLimits {
/// Maximum frame width × height. Checked before any plane allocation.
pub max_pixels: u64,
/// Maximum aggregate output plane storage in bytes.
pub max_frame_bytes: usize,
}
impl Default for DecodeLimits {
fn default() -> Self {
Self { max_pixels: u64::MAX, max_frame_bytes: MAX_FRAME_BYTES }
}
}
/// Decoder options.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct DecodeOptions {
@@ -105,15 +120,28 @@ impl Scratch {
/// Decode one ProRes frame.
pub fn decode_frame_with(data: &[u8], opts: &DecodeOptions) -> Result<Frame> {
decode_frame_with_limits(data, opts, &DecodeLimits::default())
}
/// Decode one ProRes frame with explicit geometry and aggregate-memory limits.
pub fn decode_frame_with_limits(data: &[u8], opts: &DecodeOptions, limits: &DecodeLimits) -> Result<Frame> {
let mut f = Frame::new(0, 0, ChromaFormat::Yuv422, 10, false)?;
decode_frame_into(data, opts, &mut f)?;
decode_frame_into_with_limits(data, opts, limits, &mut f)?;
Ok(f)
}
/// Decode one ProRes frame into `out`, reusing its plane allocations (the fastest way to decode
/// a sequence). On error the contents of `out` are unspecified.
pub fn decode_frame_into(data: &[u8], opts: &DecodeOptions, out: &mut Frame) -> Result<()> {
decode_frame_into_with_limits(data, opts, &DecodeLimits::default(), out)
}
/// Decode one ProRes frame into `out` under explicit resource limits.
pub fn decode_frame_into_with_limits(data: &[u8], opts: &DecodeOptions, limits: &DecodeLimits, out: &mut Frame) -> Result<()> {
let (hdr, mut off, frame_size) = FrameHeader::parse(data)?;
if u64::from(hdr.width) * u64::from(hdr.height) > limits.max_pixels {
return Err(Error::Unsupported("frame size"));
}
let data = &data[..frame_size];
let depth = opts.bit_depth.unwrap_or(match hdr.chroma {
ChromaFormat::Yuv422 => 10,
@@ -131,7 +159,7 @@ pub fn decode_frame_into(data: &[u8], opts: &DecodeOptions, out: &mut Frame) ->
.checked_add(chroma.checked_mul(2).ok_or(Error::Invalid("chroma plane count overflows"))?)
.and_then(|n| if hdr.alpha == AlphaType::None { Some(n) } else { n.checked_add(luma) })
.ok_or(Error::Invalid("frame plane count overflows"))?;
if samples.checked_mul(std::mem::size_of::<u16>()).is_none_or(|n| n > MAX_FRAME_BYTES) {
if samples.checked_mul(std::mem::size_of::<u16>()).is_none_or(|n| n > limits.max_frame_bytes) {
return Err(Error::Invalid("frame dimensions exceed the decoder memory limit"));
}
let interlaced = hdr.interlace != Interlace::Progressive;
@@ -564,6 +592,44 @@ mod alpha_decode_tests {
assert_eq!(slice_quantiser(224).unwrap(), qscale(224));
}
#[test]
fn custom_limits_preserve_large_4444_geometry_before_allocating() {
let hdr = FrameHeader {
header_size: 20,
bitstream_version: 1,
encoder_id: *b"test",
width: 8192,
height: 8192,
chroma: ChromaFormat::Yuv444,
interlace: Interlace::Progressive,
aspect_ratio: 0,
frame_rate_code: 0,
color: crate::prores::ColorInfo::default(),
alpha: AlphaType::Bits16,
qmat_luma: [4; 64],
qmat_chroma: [4; 64],
luma_matrix_present: false,
chroma_matrix_present: false,
};
let header = hdr.write();
let frame_size = 8 + header.len();
let mut data = Vec::with_capacity(frame_size);
data.extend_from_slice(&(frame_size as u32).to_be_bytes());
data.extend_from_slice(&crate::prores::header::FRAME_ID);
data.extend_from_slice(&header);
let defaults = DecodeLimits { max_pixels: 8192 * 8192, ..DecodeLimits::default() };
assert!(matches!(
decode_frame_with_limits(&data, &DecodeOptions::default(), &defaults),
Err(Error::Invalid("frame dimensions exceed the decoder memory limit"))
));
let soundcraft = DecodeLimits { max_pixels: 8192 * 8192, max_frame_bytes: 512 * 1024 * 1024 };
assert!(matches!(decode_frame_with_limits(&data, &DecodeOptions::default(), &soundcraft), Err(Error::Truncated)));
let too_few_pixels = DecodeLimits { max_pixels: 8192 * 8192 - 1, ..soundcraft };
assert!(matches!(decode_frame_with_limits(&data, &DecodeOptions::default(), &too_few_pixels), Err(Error::Unsupported("frame size"))));
}
#[test]
fn alpha_decoder_requires_complete_bounded_runs() {
let mut out = [0u16; 1];
+3 -1
View File
@@ -18,7 +18,9 @@ mod encode;
pub mod header;
mod tables;
pub use decode::{DecodeOptions, decode_frame, decode_frame_into, decode_frame_with, probe};
pub use decode::{
DecodeLimits, DecodeOptions, decode_frame, decode_frame_into, decode_frame_into_with_limits, decode_frame_with, decode_frame_with_limits, probe,
};
pub use encode::{Encoder, EncoderConfig};
pub use header::{FrameHeader, PictureHeader};
+19 -1
View File
@@ -115,6 +115,7 @@ pub struct Decoder {
sign_bias: [bool; 4],
color_space: u8,
stats: DecodeStats,
max_luma_samples: usize,
}
impl Default for Decoder {
@@ -125,6 +126,14 @@ impl Default for Decoder {
impl Decoder {
pub fn new() -> Decoder {
Self::with_max_luma_samples(MAX_LUMA_SAMPLES)
}
/// Set the maximum padded luma samples retained for one frame.
///
/// The default is 36 million. Consumers that historically supported a larger bound can
/// choose it explicitly while retaining the same checked allocation limit.
pub fn with_max_luma_samples(max_luma_samples: usize) -> Decoder {
Decoder {
ctx: EntropyContext::default(),
seg: Segmentation::default(),
@@ -138,6 +147,7 @@ impl Decoder {
sign_bias: [false; 4],
color_space: 0,
stats: DecodeStats::default(),
max_luma_samples,
}
}
@@ -178,7 +188,7 @@ impl Decoder {
let (w, h) = (usize::from(tag.width), usize::from(tag.height));
let (mb_w, mb_h) = (w.div_ceil(16), h.div_ceil(16));
let samples = mb_w.checked_mul(16).and_then(|w| w.checked_mul(mb_h)).and_then(|h| h.checked_mul(16));
ensure!(samples.is_some_and(|n| n <= MAX_LUMA_SAMPLES), "frame size {}x{} exceeds the decoder memory limit", tag.width, tag.height);
ensure!(samples.is_some_and(|n| n <= self.max_luma_samples), "frame size {}x{} exceeds the decoder memory limit", tag.width, tag.height);
if w != self.width || h != self.height {
self.width = w;
self.height = h;
@@ -1032,6 +1042,14 @@ mod segment_map_tests {
assert_eq!((d.width, d.height), (8192, 4320));
}
#[test]
fn caller_may_preserve_a_larger_existing_frame_limit() {
let mut decoder = Decoder::with_max_luma_samples(1 << 26);
assert!(decoder.begin_key_frame(&key_tag(8192, 8192)).is_ok());
let mut default = Decoder::new();
assert!(default.begin_key_frame(&key_tag(8192, 8192)).is_err());
}
#[test]
fn tiny_inter_partition_is_rejected_as_truncated() {
let mut d = Decoder::new();
+3 -6
View File
@@ -598,7 +598,7 @@ fn resolve_pending(
st.unsupported(TOO_MUCH);
continue;
}
if !st.formula_at(p.pos).is_some_and(|f| f.text.chars().count() <= MAX_SHARED_TEMPLATE) {
if st.formula_at(p.pos).is_none_or(|f| f.text.chars().count() > MAX_SHARED_TEMPLATE) {
failed.insert(p.anchor);
}
} else {
@@ -902,11 +902,8 @@ fn sheet_record(rec: &Record<'_>, st: &mut SheetState<'_>, budget: &mut Budget,
report.warn(Warning::ConditionalFormattingSkipped);
}
},
0x01B1 => {
if conditional_format(&mut c, st).is_none() {
report.warn(Warning::ConditionalFormattingSkipped);
}
}
0x01B1 if conditional_format(&mut c, st).is_none() => report.warn(Warning::ConditionalFormattingSkipped),
0x01B1 => {}
0x0879 => report.warn(Warning::ConditionalFormatting12),
// A short DVal starts no rules.
0x01B2 => st.dv_left = crate::dv::dval(&mut c).unwrap_or(0),
+7
View File
@@ -123,6 +123,13 @@ impl<'a> Archive<'a> {
self.zip.by_index_raw(index).ok().map(|f| f.compressed_size())
}
/// Is `name` stored without compression? The answer lets a format with in-memory source bytes
/// apply an output-size cap to compressed entries while bounding stored reads by source size.
pub fn is_stored(&mut self, name: &str) -> Option<bool> {
let index = self.zip.index_for_name(name)?;
self.zip.by_index_raw(index).ok().map(|f| f.compression() == zip::CompressionMethod::Stored)
}
/// The first `n` bytes of entry `name` (all of it when it is shorter), or `None` when there
/// is no such entry: for telling a file by its signature without inflating it. The bytes are
/// charged to the total; a total with less left than the bytes wanted refuses before reading.