Skip to content

PDF underlays: the page on PDF, PNG and SVG plots, and in SVG export - #2420

Draft
ATARYS-LAB wants to merge 63 commits into
storytold:mainfrom
ATARYS-LAB:pdf-plot
Draft

ATARYS-LAB wants to merge 63 commits into
storytold:mainfrom
ATARYS-LAB:pdf-plot

Conversation

@ATARYS-LAB

@ATARYS-LAB ATARYS-LAB commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Part of FF10. Depends on the PDFCLIP / PDFFRAME / PDFOSNAP PR (#2419) (stacked on it; until it lands, this diff also shows the earlier commits).

Problem

With #2395 an underlay's page is shown on screen, but plots and exports draw its frame only: a plan traced over a received PDF can't be printed with it.

Change

  • Each underlay's page is drawn to pixels at the plot's resolution (200 dpi on paper), with its fade, contrast and monochrome, its paper transparent, cut to its clip boundary and to the viewport it is seen through, without the PDF layers it hides, at its place in the drawing order (DRAWORDER). Colours are never adjusted for a dark background on paper.
  • PDF plots place it as an image with a soft mask; PNG plots draw it among the objects (the thin lines gathered before it are drawn first, so they stay under it); SVG plots and SVG export write it as a PNG image.
  • A PNG export (EXPORT, cadcraft-cli --export) draws it as the canvas shows it on its dark background: faded toward the background, with its lightness turned over when it adjusts its colours. turn_lightness moves to the document crate so the export and the canvas share it; the engine re-exports it.
  • A relative path is found from the drawing's folder (document in the plot options).
  • A plot or SVG export of the extents takes in the part of each underlay's page shown: with PDFFRAME 0 nothing else marks where a page is, and the sheet was fitted without it.
  • cadcraft-cli convert warns only about underlays whose PDF wasn't found.
  • Docs rows (Parity docs are updated by maintainers in batches, not in each PR #2520): gaps.md FF10, its file-format row and file-format-parity.md PDFUNDERLAY: pages plotted (PDF, PNG, SVG) and exported to SVG and PNG; ULAYERS and the External References palette's PDF entries remain.

Tests

  • crates/io/src/underlay_plot.rs: the page on PDF and PNG plots, upright in SVG plots and export, with its contrast, only inside its clip boundary, in the drawing order (PDF and PNG), through a layout viewport, a relative path found from the drawing, and a plot (PDF, PNG) and SVG export of the extents with the frames off fitted as with them (fails without the change: 398 dark pixels instead of 3,286, an SVG view box of the stray line alone); a PNG export drawing the page, light on its dark background (fails without the change: 1,521 light pixels with or without the PDF).
  • crates/render/tests/underlay_order.rs: on PNG plots, thin lines drawn before the page are under it and over it once DRAWORDER sends it back (fails if the gathered lines aren't drawn before the page).
  • apps/cadcraft-cli/tests/it/undrawn_entities.rs.
  • cargo xtask ci passes locally.

Not changed

No existing command or file field.

@coderabbitai

coderabbitai Bot commented Oct 28, 2026 •

Copy link
Copy Markdown

Important

Draft PR not reviewed

Draft PRs are not automatically reviewed by default.

  • Trigger a manual review

To automatically review draft PRs, update your CodeRabbit configuration:

reviews:
  auto_review:
    drafts: true
  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

ATARYS-LAB and others added 17 commits November 3, 2026 18:45
…TION read and written

A drawing with PDF underlays lost them on a DWG save (they were kept as
unknown entities, which acadrust drops). They are now a PdfUnderlay entity:
placement, scale, rotation, fade, contrast, monochrome, colour adjustment,
clip boundary (inverted too), the shown and clip flags, PDF layer overrides
and the definition's unloaded state, read and written in DXF and DWG, each
definition listing the underlays using it as its reactors.

The page's size isn't stored in a file: it comes from the PDF, which this change doesn't read yet, so the page isn't shown; its frame
follows PDFFRAME. Paths copied from a file into underlays share a memory
budget, as image definitions do.

Also credits ATARYS-LAB as "Julien - ATARYS" in contributors/people.toml.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8yBKhyaWL4FXpNDAj6j
…derlays of distinct files is linear

Each PDFDEFINITION's reactors were found by scanning every underlay, so a drawing with one PDF per
underlay saved in quadratic time (60,000 underlays: 266 s, now under a second). The users are
recorded on the planned definition, as image definitions do (CWE-407).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y9NS8fTTLQsPJ1CcUr
… inverted clip's frame counts in the bounds

A page is never shown mirrored: it now lands, unmirrored, on the mirrored
outline, turned the way that keeps it nearer upright, with its clip boundary
on the mirrored one (before, it left from the mirrored insertion point with
the same turn, off the outline). An inverted clip's boundary counts in the
bounds, so its frame can be picked before the page size is read. The hidden
flag's doc says what stays: the frame, as PDFFRAME says.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y83ji68FwkuL22Qf4n
… layer application is registered only when used

An underlay whose definition is gone read with an empty path and no word why its page stayed
blank; it now leaves a read note. AdeskUnderlayLayerOverrideData is registered in APPID only
when an underlay hides PDF layers, so files without them are written as before.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y83ji68FwkuL22Qf4n
With PDFFRAME 0 the frame is not drawn, but its corners and midpoints were still snap
candidates, in model space and inside blocks. They are now left out; picking still finds
the underlay by its frame.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y83ji68FwkuL22Qf4n
…sertion point, as an image's

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y83ji68FwkuL22Qf4n
…a DWF or DGN underlay keeps its layer overrides

PDFFRAME 0 now also keeps a frame out of the snaps when the underlay is in the block a
dimension draws. AdeskUnderlayLayerOverrideData is CADCraft's own only on a PDFUNDERLAY;
on a DWF or DGN underlay, kept without being read, it is kept like other applications' xdata.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y83ji68FwkuL22Qf4n
…he draw order

An underlay's page is read with the craft apps' shared, patched Hayro reader
(craft-libs, at craft-pdf's revision; no bundled fonts) and drawn under the
drawing: in the draw order (DRAWORDER), through layout viewports (clipped to
them), inside blocks, with its own clip boundary, fade, contrast, monochrome
and, on a dark background, its lightness turned over. Its paper is
transparent, so the drawing's background shows through.

The page is read on a worker thread, so the canvas doesn't wait for it. Zoomed
in past its pixels, or far out, the visible part is drawn again at the
screen's resolution once the view settles; the part shown keeps its own
region while the next one is drawn.

Opening a drawing gives its underlays their page size, read from each PDF (a
file stores none): a page is its size in inches, or its size in points times
its measuring scale, the convention files exchanged in this format use. A PDF that moved beside the drawing is
found by its name; one that can't be read is reported and its underlay kept.

The engine reaches the reader through hooks the apps install, so it stays
I/O-agnostic.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8yBKhyaWL4FXpNDAj6j
…d view and sharper parts per list

- More pages on screen than the 16 kept no longer empty the cache every frame (each frame read
  every PDF again and the pages blinked): a new page replaces the one drawn longest ago, never one
  drawn this frame; those over the limit show their frame until one is free.
- The active viewport's list and the layout's are drawn through different transforms: each keeps
  its own settled view, so neither restarts the other's wait, and its own sharper parts, so one
  underlay seen in both doesn't redraw its part after each result.
- A sharper part is shaded on the worker thread, as the whole page is (it can be 4096 px square).
- `ListUnderlay::shown_of` takes the triangles the canvas already has: the page isn't clipped
  twice a frame.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y9NS8fTTLQsPJ1CcUr
…m, twice in a row

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y9NS8fTTLQsPJ1CcUr
…after a while

A PDF missing or unreadable when the drawing opened (a network share not yet reachable, a file
copied in later) left its underlays showing their frame until a restart. The failure is kept
with its time, as for sharper parts, and the page is read again after 5 s.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y9NS8fTTLQsPJ1CcUr
…8 with its byte order mark

A name without a byte order mark was read as Latin-1, so a layer named with PDFDocEncoding's
own characters (0xA0 the euro sign, 0x84 an em dash...) was listed under another name and could
not be turned off by it.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y9NS8fTTLQsPJ1CcUr
…Encrypt, /ID and /Info

The trailer appended to hide layers named only /Size, /Root and /Prev, so a reader no longer
decrypted the file: its layer names and page came out as noise. The entries are carried over from
the previous trailer or cross-reference stream dictionary, read with nesting, strings and their
escapes. Tests: an encrypted PDF (standard security handler, revision 2) with one layer, then a
second, hidden; trailer parsing with direct dictionaries, literal strings and hostile bytes.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y9NS8fTTLQsPJ1CcUr
…harper parts dropped with the last underlay

- An underlay opened while its PDF couldn't be read had no page size, so the page's own retry
  never ran. While such an underlay is shown, its PDF is looked for every 5 s
  (`underlay::retry_sizes`, quiet); once found, the size is set, the drawing redrawn, and an
  unmodified drawing stays unmodified.
- With no underlay left on screen (the last one deleted, another drawing), the canvas still
  drops sharper parts past their keep time: each can hold 4096 px squared.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y9NS8fTTLQsPJ1CcUr
… trailer is read from its keyword

The trailer window started at the section, so a classic table longer than 64 KiB (some 3,200
objects) hid the trailer and the update lost /Encrypt and /ID again. For a classic table the
window starts at `trailer`. Test: an encrypted PDF of 4,500 objects.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y9NS8fTTLQsPJ1CcUr
…d the drawing redrawn at once

The retry read and parsed each missing PDF on the UI thread every 5 s: a share that isn't
reachable or a large damaged PDF froze the canvas each time. The engine now splits it into
`unsized_pages`, `page_size` (files only, for a worker) and `set_sizes`; the canvas reads on a
worker, one reading at a time, applies what it found and repaints at once. A PDF that is there
but gives no size isn't read again until its modification time changes. `retry_sizes` stays,
on the calling thread, for hosts without a UI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y9NS8fTTLQsPJ1CcUr
…and the canvas is redrawn once they are

From CodeRabbit's review of c33b73b:
- A page size read on the worker carries the drawing it was read for (its uid and the file it is
  saved at): switching drawings meanwhile no longer gives one drawing another's size, and a
  drawing saved elsewhere since gets nothing. Pages noted unreadable are noted per drawing too,
  as one relative path can name two PDFs.
- A PDF larger than the 512 MB cap is unreadable, by its length, until it changes, instead of
  missing and read again every 5 s.
- The worker asks for a repaint when it is done, so a PDF that is back shows at once instead of
  at the next retry.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8yA6ibQ4twvHAJjDU3d
@ATARYS-LAB

Copy link
Copy Markdown
Contributor Author

Rebased on today's main (b639b18) with the rest of the series; details on #2394. cargo xtask ci passes.

…4 PDFs and 1024 pages, reported in a few lines

A drawing citing thousands of pages read the whole PDF again for each, and wrote a line for
each it couldn't size. Pages are now grouped by PDF, for the open and for the canvas's worker
(page_sizes), within caps, and the open reports at most 16 lines and a count of the others.
The PDF layers key is kept in one place (PdfUnderlay::key_of_layers), and the workspace
manifest says what happens to PDF text in fonts that aren't embedded.
…an cut short, found as on screen

The plot read the first 512 MB of a larger PDF and drew from that. It is now left out, as the
engine refuses it, with one cap (cadcraft_doc::UNDERLAY_MAX_PDF_BYTES) for both, and a drawing's
relative folder is made absolute before a stored path is resolved from it, as the engine does.
# Conflicts:
#	apps/cadcraft-cli/src/output.rs
#	apps/cadcraft-cli/tests/it/undrawn_entities.rs
#	contributors/people.toml
#	crates/render/src/draw.rs
# Conflicts:
#	Cargo.lock
#	apps/cadcraft-web/src/main.rs
#	crates/engine/src/cmd/file.rs
#	crates/io/Cargo.toml
#	crates/render/src/lib.rs
#	crates/render/src/viewports.rs
#	crates/ui-egui/src/canvas.rs
#	crates/ui-egui/src/canvas/draw.rs
#	crates/ui-egui/src/canvas/viewport.rs
# Conflicts:
#	apps/cadcraft/src/main.rs
#	crates/ui-egui/src/i18n/zh.tsv
#	crates/ui-egui/src/lib.rs
# Conflicts:
#	crates/engine/src/cmd/file.rs
#	crates/engine/src/sysvars/table.rs
#	crates/ui-egui/src/i18n/fr.tsv
#	crates/ui-egui/src/i18n/uk.tsv
#	crates/ui-egui/src/i18n/zh.tsv
# Conflicts:
#	apps/cadcraft-cli/src/output.rs
#	apps/cadcraft-cli/tests/it/undrawn_entities.rs
…saved drawing

A relative path given to PDFATTACH (its `path`, the typed file prompt, or the dialog's choice)
was read from the folder CADCraft was started in. It is now from the drawing's folder and is
stored as the full path it names. A drawing without a file has no folder, so the path is refused
with "save the drawing first, or give a full path", as storytold#2765 says for IMAGEATTACH.
storytold#1534 routes every file dialog through pick_then / Pick. PDFATTACH and the
PDF Underlay dialog's Browse button now do too, with a Pick::Pdf variant:
on macOS the PDF picker is a sheet like the others, and its answer acts on
the drawing that asked.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant