feat(pdf): group paper objects into optional layers

Continue the existing #7626 handoff with five ordered default-visible optional-content groups, bounded marked content, paint order and style preservation. Original implementation and earlier tests retained; an original five-kind repeated-group fixture adds independent structure and PDFium visibility acceptance.

Focused validation: complete IO 162 passed, 0 failed, 2 existing ignored; all18 PDF cases, strict IO Clippy and wasm passed. Exact native build artifact reused after a preserved private runner drain failure. Full cargo xtask ci, Drawing UI and print acceptance remain unrun; this is saved draft work, not a ready/merge claim.
This commit is contained in:
lillith committed 2026-10-28 17:38:23 +01:00
1 parent dc911d80d1
commit effaf49113
2 files changed
+213 -29

No files matched your search

+91 -26
View File
@@ -1,5 +1,5 @@
//! A paper scene as a vector PDF (#4890, P1): one page the sheet's size, its lines and fills,
//! geometry only (text follows with P2).
//! geometry and optional-content layers (text follows with P2).
//!
//! - **The file** comes from `pdf-writer`: a catalog, one page whose MediaBox is the sheet in
//! points, its content deflated, and an Info dictionary with the Producer, the Title when there
@@ -15,6 +15,10 @@
//! - **Paint:** strokes at their width `w` (the walk never gives 0, which 8.4.3.2 says is a device
//! pixel and shouldn't be used), butt caps, miter joins and a miter limit of 4, dashed by `d`;
//! fills black, even-odd (`f*`). Black on no background, as SVG.
//! - **Layers:** nonempty groups share one PDF optional-content group for each
//! distinct paper object kind. Group order remains the original paint order,
//! and each kind's PDF layer uses ObjectKind::layer, as in DXF. Empty
//! groups do not invent layers. All present layers start visible.
//! - **Content size:** every append checks the cumulative byte limit before growing the
//! buffer, including inside a path/arc and the final graphics-state restore. Allocation
//! failure is an error. The limit is for uncompressed content, not total export memory.
@@ -24,8 +28,8 @@ use std::io::Write as _;
use flate2::Compression;
use flate2::write::ZlibEncoder;
use pdf_writer::{Date, Filter, Pdf, Rect, Ref, TextStr};
use solidcraft_geom::paper::{Grid, GridDashes, GridGroup, GridItem, GridPath, GridPoint, GridReport, Piece, Prepared};
use pdf_writer::{Date, Filter, Name, Pdf, Rect, Ref, TextStr};
use solidcraft_geom::paper::{Grid, GridDashes, GridGroup, GridItem, GridPath, GridPoint, GridReport, ObjectKind, Piece, Prepared};
use solidcraft_geom::{Seg2, Vec2};
use super::push_mm;
@@ -70,7 +74,8 @@ pub fn paper_pdf(scene: &Prepared, options: &PdfOptions) -> Result<(Vec<u8>, Pdf
return Err(IoError::Invalid(format!("a sheet PDF's page is at least {MIN_PAGE_PT} pt (about 1.06 mm) a side")));
}
let content = content(&on.groups)?;
let layers = collect_layers(&on.groups)?;
let content = content_with_limit_and_layers(&on.groups, &layers, MAX_DRAWING_BYTES)?;
let mut deflate = ZlibEncoder::new(Vec::new(), Compression::default());
let compressed = deflate.write_all(content.as_bytes()).and_then(|()| deflate.finish());
let compressed = compressed.map_err(|e| IoError::Invalid(format!("the sheet PDF: {e}")))?;
@@ -78,11 +83,32 @@ pub fn paper_pdf(scene: &Prepared, options: &PdfOptions) -> Result<(Vec<u8>, Pdf
// Each object's number, used once (pdf-writer panics on a number written twice).
let (catalog, tree, page_id, contents, info) = (Ref::new(1), Ref::new(2), Ref::new(3), Ref::new(4), Ref::new(5));
let mut pdf = Pdf::new();
pdf.catalog(catalog).pages(tree);
{
let mut root = pdf.catalog(catalog);
root.pages(tree);
if !layers.is_empty() {
// PDF 1.5 optional content: one group per used paper object kind.
// The default configuration orders all layers and starts them ON.
let mut properties = root.insert(Name(b"OCProperties")).dict();
properties.insert(Name(b"OCGs")).array().items(layers.iter().map(|l| l.reference));
let mut default = properties.insert(Name(b"D")).dict();
default.insert(Name(b"Order")).array().items(layers.iter().map(|l| l.reference));
default.insert(Name(b"ON")).array().items(layers.iter().map(|l| l.reference));
default.pair(Name(b"BaseState"), Name(b"ON"));
}
}
pdf.pages(tree).kids([page_id]).count(1);
let mut writer = pdf.page(page_id);
writer.parent(tree).media_box(Rect::new(0.0, 0.0, page[0] as f32, page[1] as f32)).contents(contents);
writer.resources();
{
let mut resources = writer.resources();
if !layers.is_empty() {
let mut properties = resources.insert(Name(b"Properties")).dict();
for layer in &layers {
properties.pair(Name(layer.tag.as_bytes()), layer.reference);
}
}
}
drop(writer);
pdf.stream(contents, &compressed).filter(Filter::FlateDecode);
let mut doc = pdf.document_info(info);
@@ -94,6 +120,11 @@ pub fn paper_pdf(scene: &Prepared, options: &PdfOptions) -> Result<(Vec<u8>, Pdf
doc.creation_date(date).modified_date(date);
}
drop(doc);
for layer in &layers {
let mut group = pdf.indirect(layer.reference).dict();
group.pair(Name(b"Type"), Name(b"OCG"));
group.pair(Name(b"Name"), TextStr(layer.kind.layer()));
}
Ok((pdf.finish(), on.report))
}
@@ -108,39 +139,73 @@ fn date(secs: u64) -> Result<Date> {
Ok(Date::new(u16::try_from(year).unwrap_or(0)).month(month).day(day).hour(hour).minute(minute).second(second).utc_offset_hour(0))
}
/// One PDF layer for every kind with actual paper marks, in first paint order.
struct Layer {
kind: ObjectKind,
reference: Ref,
tag: String,
}
fn collect_layers(groups: &[GridGroup]) -> Result<Vec<Layer>> {
let mut layers: Vec<Layer> = Vec::new();
for group in groups.iter().filter(|group| !group.items.is_empty()) {
if layers.iter().any(|layer| layer.kind == group.kind) {
continue;
}
layers.try_reserve(1).map_err(|_| IoError::Invalid("the sheet PDF: cannot allocate its layer list".into()))?;
let index = i32::try_from(layers.len()).ok().and_then(|n| n.checked_add(6)).ok_or_else(|| IoError::Invalid("too many PDF layers".into()))?;
layers.push(Layer { kind: group.kind, reference: Ref::new(index), tag: format!("L{}", layers.len()) });
}
Ok(layers)
}
/// The page's content stream: the scene in millimetres, scaled to points once.
#[cfg(test)]
fn content(groups: &[GridGroup]) -> Result<String> {
content_with_limit(groups, MAX_DRAWING_BYTES)
}
// The private seam permits smaller test limits, never a higher production cap.
#[cfg(test)]
fn content_with_limit(groups: &[GridGroup], max_bytes: usize) -> Result<String> {
let layers = collect_layers(groups)?;
content_with_limit_and_layers(groups, &layers, max_bytes)
}
fn content_with_limit_and_layers(groups: &[GridGroup], layers: &[Layer], max_bytes: usize) -> Result<String> {
let mut w = Content::new(max_bytes)?;
w.append(&format!("q {PT_PER_MM:.9} 0 0 {PT_PER_MM:.9} 0 0 cm 0 J 0 j 4 M\n"))?;
for item in groups.iter().flat_map(|g| &g.items) {
match item {
GridItem::Stroke { width, path, dashes } => {
if w.width != Some(*width) {
w.number(*width)?;
w.append(" w\n")?;
w.width = Some(*width);
for group in groups.iter().filter(|group| !group.items.is_empty()) {
let layer = layers.iter().find(|layer| layer.kind == group.kind).ok_or_else(|| IoError::Invalid("missing paper PDF layer".into()))?;
w.append("/OC /")?;
w.append(&layer.tag)?;
w.append(" BDC\n")?;
for item in &group.items {
match item {
GridItem::Stroke { width, path, dashes } => {
if w.width != Some(*width) {
w.number(*width)?;
w.append(" w\n")?;
w.width = Some(*width);
}
if w.dashes.as_ref() != dashes.as_ref() {
w.dashes(dashes.as_ref())?;
w.dashes.clone_from(dashes);
}
w.path(path)?;
// A closed path's closing line, then the stroke: `s`.
w.append(if path.closed { "s\n" } else { "S\n" })?;
}
if w.dashes.as_ref() != dashes.as_ref() {
w.dashes(dashes.as_ref())?;
w.dashes.clone_from(dashes);
GridItem::Fill { loops } => {
for l in loops {
w.path(l)?;
w.append("h\n")?;
}
w.append("f*\n")?;
}
w.path(path)?;
// A closed path's closing line, then the stroke: `s`.
w.append(if path.closed { "s\n" } else { "S\n" })?;
}
GridItem::Fill { loops } => {
for l in loops {
w.path(l)?;
w.append("h\n")?;
}
w.append("f*\n")?;
}
}
w.append("EMC\n")?;
}
w.append("Q\n")?;
Ok(w.out)
+122 -3
View File
@@ -120,9 +120,22 @@ fn check_xref(bytes: &[u8]) -> std::result::Result<usize, String> {
let number = bytes.get(at..).ok_or("missing xref offset")?.split(|b| b.is_ascii_whitespace()).next().ok_or("missing xref offset")?;
let start: usize = std::str::from_utf8(number).map_err(|_| "xref offset is not ASCII")?.parse().map_err(|_| "invalid xref offset")?;
let tail = bytes.get(start..).ok_or("xref offset outside file")?;
let table = tail.strip_prefix(b"xref\n0 6\n").ok_or("xref offset is not the expected subsection")?;
let entries = table.get(..120).ok_or("truncated xref entries")?;
for (n, entry) in entries.as_chunks::<20>().0.iter().enumerate() {
let rest = tail.strip_prefix(b"xref\n0 ").ok_or("xref offset is not the expected subsection")?;
let end_of_count = rest.iter().position(|&c| c == b'\n').ok_or("truncated xref count")?;
let count: usize =
std::str::from_utf8(&rest[..end_of_count]).map_err(|_| "xref count is not ASCII")?.parse().map_err(|_| "invalid xref count")?;
// Five fixed objects plus up to five distinct current ObjectKinds, and the free object.
if !(6..=11).contains(&count) {
return Err(format!("unexpected PDF object count {count}"));
}
let table = rest.get(end_of_count + 1..).ok_or("truncated xref table")?;
let entry_bytes = count.checked_mul(20).ok_or("xref count overflow")?;
let entries = table.get(..entry_bytes).ok_or("truncated xref entries")?;
let (entries, remainder) = entries.as_chunks::<20>();
if !remainder.is_empty() {
return Err("xref entry does not occupy 20 bytes".into());
}
for (n, entry) in entries.iter().enumerate() {
if ![&b" \n"[..], &b"\r\n"[..]].contains(&&entry[18..]) {
return Err(format!("entry {n} does not occupy 20 bytes"));
}
@@ -393,3 +406,109 @@ fn content_budget_reuses_the_original_formatter_at_integer_extremes() {
assert!(too_small.out.is_empty());
}
}
/// P3: one optional-content group per nonempty kind, shared across repeats.
/// The scene's drawing order remains the content stream's paint order.
#[test]
fn pdf_layers_share_object_kinds_and_keep_noncontiguous_paint_order() {
let path = |y: f64| vec![Seg2::Line { a: p(10.0, y), b: p(100.0, y) }];
let sheet = Scene {
size_mm: p(210.0, 297.0),
groups: vec![
Group { object: 10, kind: ObjectKind::TitleBlock, items: vec![stroke(path(10.0), false, 0.35, None)] },
Group { object: 20, kind: ObjectKind::DrawingBorder, items: vec![stroke(path(20.0), false, 0.35, None)] },
Group { object: 11, kind: ObjectKind::TitleBlock, items: vec![stroke(path(30.0), false, 0.35, None)] },
Group { object: 30, kind: ObjectKind::SheetBorder, items: vec![] },
],
};
let bytes = pdf(&sheet, &NONE);
assert!(check_xref(&bytes).is_ok(), "{:?}", check_xref(&bytes));
assert_eq!(pdf(&sheet, &NONE), bytes, "layer order and object ids must be deterministic");
let file = text(&bytes);
assert!(file.contains("/OCProperties"), "the catalog must declare optional content");
assert!(file.contains("/OCGs [6 0 R 7 0 R]"), "the same kind must reuse its OCG: {file}");
assert!(file.contains("/Order [6 0 R 7 0 R]"), "the visible layers are ordered");
assert!(file.contains("/ON [6 0 R 7 0 R]"), "both are visible by default");
assert!(file.contains("/BaseState /ON"), "the default state is ON");
assert!(file.contains("/Name (TITLE_BLOCK)") && file.contains("/Name (DRAWING_BORDER)"));
assert!(!file.contains("/Name (SHEET_BORDER)"), "an empty group has no painted layer");
assert!(file.contains("/Properties") && file.contains("/L0 6 0 R") && file.contains("/L1 7 0 R"));
let stream = content(&bytes);
let markers: Vec<_> = stream.lines().filter(|line| line.ends_with(" BDC") || *line == "EMC").collect();
assert_eq!(markers, ["/OC /L0 BDC", "EMC", "/OC /L1 BDC", "EMC", "/OC /L0 BDC", "EMC"]);
assert_eq!(stream.lines().filter(|line| *line == "S").count(), 3);
assert!(check_number_grid(&stream).is_ok());
}
/// Every current paper kind has one independently named layer, without sorting
/// noncontiguous groups or losing graphics state across marked-content boundaries.
#[test]
fn pdf_layers_cover_all_five_kinds_and_preserve_paint_and_styles() {
let line = |y: f64| vec![Seg2::Line { a: p(10.0, y), b: p(100.0, y) }];
let dashed = Some(Dashes { lengths_mm: vec![4.0, 2.0], phase_mm: 0.0 });
let square = Loop2::polygon(&[p(10.0, 30.0), p(20.0, 30.0), p(20.0, 40.0), p(10.0, 40.0)]);
let sheet = Scene {
size_mm: p(210.0, 297.0),
groups: vec![
Group { object: 10, kind: ObjectKind::TitleBlock, items: vec![stroke(line(10.0), false, 0.35, None)] },
Group { object: 20, kind: ObjectKind::DrawingBorder, items: vec![stroke(line(20.0), false, 0.7, dashed.clone())] },
Group { object: 30, kind: ObjectKind::PartsList, items: vec![Item::Fill { region: Region2 { outer: square, holes: vec![] } }] },
Group { object: 40, kind: ObjectKind::RevisionTable, items: vec![stroke(line(50.0), false, 0.7, dashed)] },
Group { object: 50, kind: ObjectKind::SheetBorder, items: vec![stroke(line(60.0), false, 0.35, None)] },
Group { object: 11, kind: ObjectKind::TitleBlock, items: vec![stroke(line(70.0), false, 0.35, None)] },
Group { object: 60, kind: ObjectKind::DrawingBorder, items: vec![] },
],
};
let bytes = pdf(&sheet, &NONE);
assert_eq!(pdf(&sheet, &NONE), bytes);
assert!(check_xref(&bytes).is_ok(), "{:?}", check_xref(&bytes));
let file = text(&bytes);
for key in ["OCGs", "Order", "ON"] {
assert!(file.contains(&format!("/{key} [6 0 R 7 0 R 8 0 R 9 0 R 10 0 R]")), "{file}");
}
assert!(file.contains("/BaseState /ON"));
assert_eq!(file.matches("/Type /OCG\n").count(), 5, "one OCG per kind, with no empty-group duplicate");
// Literal expected names and references are independent of ObjectKind::layer.
for (number, name) in [(6, "TITLE_BLOCK"), (7, "DRAWING_BORDER"), (8, "PARTS_LIST"), (9, "REVISION_TABLE"), (10, "SHEET_BORDER")] {
let header = format!("{number} 0 obj\n");
let object = file.split_once(&header).unwrap().1.split_once("endobj").unwrap().0;
assert!(object.contains("/Type /OCG") && object.contains(&format!("/Name ({name})")), "{object}");
assert_eq!(file.matches(&format!("/Name ({name})")).count(), 1);
assert!(file.contains(&format!("/L{} {number} 0 R", number - 6)));
}
let stream = content(&bytes);
let markers: Vec<_> = stream.lines().filter(|line| line.ends_with(" BDC") || *line == "EMC").collect();
assert_eq!(
markers,
["/OC /L0 BDC", "EMC", "/OC /L1 BDC", "EMC", "/OC /L2 BDC", "EMC", "/OC /L3 BDC", "EMC", "/OC /L4 BDC", "EMC", "/OC /L0 BDC", "EMC",]
);
let operators = ops(&stream);
let paints: Vec<_> = operators.iter().map(|(op, _)| op.as_str()).filter(|op| ["S", "h", "f*"].contains(op)).collect();
assert_eq!(paints, ["S", "S", "h", "f*", "S", "S", "S"]);
let starts: Vec<_> = operators.iter().filter(|(op, _)| op == "m").map(|(_, n)| (n[0], n[1])).collect();
assert_eq!(starts, [(10.0, 10.0), (10.0, 20.0), (10.0, 30.0), (10.0, 50.0), (10.0, 60.0), (10.0, 70.0)]);
let styles: Vec<(&str, &[f64])> = operators.iter().filter(|(op, _)| op == "w" || op == "d").map(|(op, n)| (op.as_str(), n.as_slice())).collect();
assert_eq!(styles, [("w", &[0.35][..]), ("w", &[0.7][..]), ("d", &[4.0, 2.0, 0.0][..]), ("w", &[0.35][..]), ("d", &[0.0][..])]);
assert!(check_number_grid(&stream).is_ok());
// A reviewer may retain these exact asserted bytes for independent PDF readers.
if let Some(path) = std::env::var_os("SOLIDCRAFT_PDF_LAYER_REVIEW_OUTPUT") {
let written = std::fs::write(&path, &bytes);
assert!(written.is_ok(), "could not write the asserted layer fixture to {path:?}: {written:?}");
}
}
/// P3: no phantom layer dictionary on a truly empty scene, and content
/// limits include all OCG markers instead of silently cutting them off.
#[test]
fn pdf_layers_obey_content_budget_and_skip_empty_groups() {
let empty = scene(p(210.0, 297.0), vec![]);
let bytes = pdf(&empty, &NONE);
assert!(check_xref(&bytes).is_ok());
assert!(!text(&bytes).contains("/OCProperties"));
assert!(!content(&bytes).contains(" BDC"));
let line = scene(p(210.0, 297.0), vec![stroke(vec![Seg2::Line { a: p(10.0, 10.0), b: p(100.0, 10.0) }], false, 0.35, None)]);
let grid = line.prepare().unwrap().on_grid(Grid::TEN_NANOMETRES).unwrap();
let full = super::content_with_limit(&grid.groups, MAX_DRAWING_BYTES).unwrap();
assert!(full.contains("/OC /L0 BDC") && full.contains("EMC"));
assert_eq!(super::content_with_limit(&grid.groups, full.len()).unwrap(), full);
assert!(super::content_with_limit(&grid.groups, full.len() - 1).is_err());
}