Merge pull request #1564 from storytold/dot/shared-pctip

pcraft-format: share PCTIP1 brush-tip serialization
This commit is contained in:
Dylan M. Taylor
2026-11-15 07:29:12 -05:00
committed by GitHub
6 changed files with 180 additions and 1 deletions
Generated
+1
View File
@@ -2244,6 +2244,7 @@ dependencies = [
name = "craft-pcraft-format"
version = "0.1.0"
dependencies = [
"flate2",
"serde",
"serde_json",
"thiserror 2.0.21",
+3
View File
@@ -16,3 +16,6 @@ serde = { workspace = true }
# the nesting against `Limits::max_depth` before parsing.
serde_json = { workspace = true, features = ["unbounded_depth"] }
thiserror = { workspace = true }
# Same pure-Rust backend as the PhotoCraft source codec. MIT OR Apache-2.0.
flate2 = { version = "1.1.10", default-features = false, features = ["zlib-rs", "runtime_detection"] }
+13 -1
View File
@@ -5,7 +5,7 @@ references, the entry paths, the limits for reading a manifest, and the runner f
migrations. The document model stays in PhotoCraft and is a type parameter here. The crate
does not read ZIP archives, open files or decode tiles. No `unsafe`, no panics on malformed
input, and it builds for `wasm32-unknown-unknown`. The dependencies are `serde`, `serde_json`
and `thiserror`.
`thiserror`, and `flate2`.
```toml
craft-pcraft-format = { git = "https://github.com/storytold/craft-libs", rev = "<commit>" }
@@ -120,3 +120,15 @@ limits.max_manifest_bytes = 16 << 20;
`.github/workflows/pcraft-format.yml` runs fmt, clippy and the tests on Linux and Windows, and
a `wasm32-unknown-unknown` check.
## Brush-tip envelope
`tip::encode`, `tip::decode` and `tip::decode_with_max_side` share PhotoCraft's PCTIP1
brush-tip codec: a six-byte magic, one-byte depth, little-endian width/height and zlib
samples. Eight-bit-compatible samples use 8 bits, otherwise 16-bit little-endian.
Dimensions, sample count, exact inflated length and caller preview side limits are checked.
Preset group schemas, tip hashes and storage policy remain application-owned.
Ported from `storytold/photocraft` commit `19aec5eb44131de44361189d64910e7b3e19e57c`,
`crates/engine/src/preset_store.rs`. Original codec by Brandon Thomas (PhotoCraft #82),
with later bounds/backend/storage changes by David Mann and FinnNk, under MIT OR Apache-2.0.
+3
View File
@@ -36,6 +36,9 @@ mod limits;
mod migrate;
mod read;
/// Lossless brush-tip envelope used by PhotoCraft preset libraries.
pub mod tip;
use serde::{Deserialize, Serialize};
pub use limits::{
+102
View File
@@ -0,0 +1,102 @@
//! PhotoCraft's PCTIP1 brush-tip envelope and lossless grayscale sample serialization.
//!
//! Extracted from PhotoCraft preset_store.rs at 19aec5eb44131de44361189d64910e7b3e19e57c.
//! Original implementation: Brandon Thomas; subsequent codec changes: David Mann and FinnNk.
//! Group schemas, file naming, content hashes and storage policy remain with the application.
/// Largest accepted tip side.
pub const MAX_SIDE: u32 = 16384;
/// Largest accepted sample count.
pub const MAX_SAMPLES: u64 = 1 << 26;
const TIP_MAGIC: &[u8; 6] = b"PCTIP1";
const TIP_HEADER: usize = 6 + 1 + 4 + 4;
/// Decoded grayscale samples. Eight-bit samples expand losslessly by multiplication by 257.
#[derive(Clone, Debug, PartialEq, Eq)]
pub struct Tip {
pub width: u32,
pub height: u32,
pub data: Vec<u16>,
}
/// `PCTIP1`, bits (8|16), width, height (u32 LE), then the zlib-deflated samples.
/// Returns an empty vector for invalid dimensions/sample counts or compression failure.
pub fn encode(width: u32, height: u32, data: &[u16]) -> Vec<u8> {
use std::io::Write;
let count = u64::from(width) * u64::from(height);
if width == 0 || height == 0 || width > MAX_SIDE || height > MAX_SIDE || count > MAX_SAMPLES || count != data.len() as u64 {
return Vec::new();
}
let eight = data.iter().all(|v| v % 257 == 0);
let mut out = Vec::with_capacity(TIP_HEADER + data.len() / 4);
out.extend_from_slice(TIP_MAGIC);
out.push(if eight { 8 } else { 16 });
out.extend_from_slice(&width.to_le_bytes());
out.extend_from_slice(&height.to_le_bytes());
// Level 3: zlib-rs level 1 writes static Huffman blocks only, 13-30% bigger than miniz's level 1.
let mut z = flate2::write::ZlibEncoder::new(out, flate2::Compression::new(3));
let mut buf = Vec::with_capacity(8192);
let mut ok = true;
for chunk in data.chunks(4096) {
buf.clear();
if eight {
buf.extend(chunk.iter().map(|v| (v / 257) as u8));
} else {
for v in chunk {
buf.extend_from_slice(&v.to_le_bytes());
}
}
ok &= z.write_all(&buf).is_ok();
}
match z.finish() {
Ok(v) if ok => v,
_ => Vec::new(),
}
}
/// Inverse of [`encode`]; any malformed, truncated or oversized input is an error.
pub fn decode(bytes: &[u8]) -> Result<Tip, String> {
decode_with_max_side(bytes, MAX_SIDE)
}
/// [`decode`] refusing (before inflating anything) a bitmap with a side over `max_side`.
pub fn decode_with_max_side(bytes: &[u8], max_side: u32) -> Result<Tip, String> {
let head = bytes.get(..TIP_HEADER).ok_or("truncated tip header")?;
if &head[..6] != TIP_MAGIC {
return Err("not a PhotoCraft tip".into());
}
let bits = head[6];
let u32_at = |i: usize| u32::from_le_bytes([head[i], head[i + 1], head[i + 2], head[i + 3]]);
let (w, h) = (u32_at(7), u32_at(11));
if w == 0 || h == 0 || w > MAX_SIDE.min(max_side) || h > MAX_SIDE.min(max_side) {
return Err(format!("bad tip size {w}×{h}"));
}
let n = u64::from(w) * u64::from(h);
if n > MAX_SAMPLES {
return Err(format!("tip too large ({w}×{h})"));
}
let bytes_per = match bits {
8 => 1u64,
16 => 2,
b => return Err(format!("unsupported tip depth {b}")),
};
let want = n * bytes_per;
// One byte beyond the declared size detects overlong output, without allocating for
// an attacker-controlled expansion. Require the zlib trailer, not merely enough samples.
let mut raw = Vec::with_capacity(want as usize + 1);
let status = flate2::Decompress::new(true)
.decompress_vec(&bytes[TIP_HEADER..], &mut raw, flate2::FlushDecompress::Finish)
.map_err(|e| format!("tip data: {e}"))?;
if status != flate2::Status::StreamEnd {
return Err("tip data: truncated or oversized zlib stream".into());
}
if raw.len() as u64 != want {
return Err(format!("tip data has {} bytes, expected {want}", raw.len()));
}
let data: Vec<u16> = if bits == 8 {
raw.iter().map(|&v| u16::from(v) * 257).collect()
} else {
raw.as_chunks::<2>().0.iter().map(|c| u16::from_le_bytes(*c)).collect()
};
Ok(Tip { width: w, height: h, data })
}
+58
View File
@@ -0,0 +1,58 @@
use craft_pcraft_format::tip::{MAX_SAMPLES, MAX_SIDE, decode, decode_with_max_side, encode};
use std::io::Write;
fn fixture(bits: u8, width: u32, height: u32, samples: &[u8]) -> Vec<u8> {
let mut out = b"PCTIP1".to_vec();
out.push(bits);
out.extend(width.to_le_bytes());
out.extend(height.to_le_bytes());
let mut z = flate2::write::ZlibEncoder::new(out, flate2::Compression::new(3));
z.write_all(samples).unwrap();
z.finish().unwrap()
}
#[test]
fn legacy_eight_and_sixteen_bit_fixtures_and_roundtrips() {
for (bits, raw, samples) in [(8, vec![0, 128, 255], vec![0, 32896, 65535]), (16, vec![1, 0, 52, 18, 255, 255], vec![1, 0x1234, 65535])] {
let legacy = fixture(bits, 3, 1, &raw);
let tip = decode(&legacy).unwrap();
assert_eq!((tip.width, tip.height), (3, 1));
assert_eq!(tip.data, samples);
let encoded = encode(3, 1, &samples);
assert_eq!(&encoded[..15], &legacy[..15]);
assert_eq!(decode(&encoded).unwrap(), tip);
}
}
#[test]
fn checks_headers_limits_and_sample_lengths() {
let good = fixture(8, 1, 1, &[255]);
for n in 0..good.len() {
assert!(decode(&good[..n]).is_err(), "truncation at {n}");
}
let mut bad = good.clone();
bad[0] = b'X';
assert!(decode(&bad).is_err());
for (bits, w, h) in [(7, 1, 1), (8, 0, 1), (8, 1, 0), (8, MAX_SIDE + 1, 1), (8, MAX_SIDE, MAX_SIDE)] {
assert!(decode(&fixture(bits, w, h, &[])).is_err());
}
assert!(MAX_SAMPLES < u64::from(MAX_SIDE) * u64::from(MAX_SIDE));
for raw in [vec![], vec![0, 1], vec![0; 10000]] {
assert!(decode(&fixture(8, 1, 1, &raw)).is_err());
}
assert!(decode(&fixture(16, 1, 1, &[1])).is_err());
let mut checksum = good;
*checksum.last_mut().unwrap() ^= 1;
assert!(decode(&checksum).is_err());
assert!(encode(0, 1, &[]).is_empty());
assert!(encode(1, 1, &[]).is_empty());
assert!(encode(MAX_SIDE + 1, 1, &[0]).is_empty());
}
#[test]
fn preview_side_limit_is_checked_before_inflation() {
let good = encode(2, 1, &[0, 65535]);
assert!(decode_with_max_side(&good, 1).is_err());
assert!(decode_with_max_side(&good, 2).is_ok());
assert!(decode_with_max_side(&good, 0).is_err());
}