Skip to content

PDF underlays: PDFCLIP, PDFFRAME, and object snaps on the page's lines (PDFOSNAP) - #2419

Draft
ATARYS-LAB wants to merge 53 commits into
storytold:mainfrom
ATARYS-LAB:pdf-clip-frame-osnap
Draft

ATARYS-LAB wants to merge 53 commits into
storytold:mainfrom
ATARYS-LAB:pdf-clip-frame-osnap

Conversation

@ATARYS-LAB

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

Copy link
Copy Markdown
Contributor

Part of FF10. Depends on #2396 (stacked on #2394 → #2395 → #2396; until they land, this diff also shows their commits).

Problem

With #2394–#2396 a PDF underlay can be attached, adjusted, shown and saved, but it can't be clipped, its frame can't be hidden, and object snaps don't find anything drawn on the page: tracing over a received plan means guessing where its lines are.

Change

  • PDFCLIP: clip an underlay to a rectangle, a polygon or a selected polyline; Invert clip hides the inside instead; ON / OFF keep the boundary but apply or ignore it; Delete removes it. Typed prompts, or the JSON form {handle?|handles?, rect | polygon | polyline | on | delete, invert?}. The boundary is kept in the page's own units, so it follows MOVE, ROTATE and SCALE. A rectangle on a turned page is aligned with the page and cut to its edges. Drawing a clipped page, and reading and saving its boundary in DXF and DWG, are already in PDF underlays are kept through DXF and DWG: PDFUNDERLAY and PDFDEFINITION read and written #2394 and PDF underlays on screen: their pages read from the PDF and drawn in the draw order #2395.
  • PDFFRAME (0 none, 1 shown and plotted, 2 shown but not plotted), as a system variable of the drawing.
  • Object snaps on the page: endpoint, midpoint, intersection, nearest and the others find the lines drawn on an underlay's page, only inside its clip boundary (outside it when inverted), not on hidden PDF layers, through layout viewports and through block references. The lines are read when an underlay is attached or its drawing opened: on a worker thread when the drawing is opened from the window, so it doesn't wait for them (1.3 s for ten ArchiCAD sheets before), and at once by the OPEN command, so a script's next line can snap to them (at most 128 pages kept, at most 2,000 segments looked at per snap query). PDFOSNAP 0 turns them off; it is a session setting. When a PDF that couldn't be read comes back, its lines are read on a worker thread, once at a time per page (two drawings on the same PDF don't read it twice at once).
  • fr/uk: the new command's label.
  • Docs rows (Parity docs are updated by maintainers in batches, not in each PR #2520): gaps.md FF10 and its file-format row: PDFCLIP, PDFFRAME and PDFOSNAP landed; not plotted, no ULAYERS yet.

Tests

  • crates/engine/tests/pdf_underlay.rs: PDFCLIP with a rectangle, a polygon and a polyline, following the underlay; inverted; typed rectangle and polygon; a rectangle on a turned page aligned with it and cut to it; PDFFRAME and PDFOSNAP; snaps on the page's lines, only inside the clip boundary, through a layout viewport, and through each reference of a block holding an underlay.
  • crates/engine/tests/pdf_lines_read_once.rs: a page's lines aren't read twice at the same time when two drawings' PDF comes back together (fails without the guard: 2 reads); object_snaps_find_the_page_lines_read_in_the_background.
  • cargo xtask ci passes locally.
  • Checked in AutoCAD 2023 with synthetic drawings, on an earlier build of this code: clipped, inverted, rotated and scaled underlays saved here open at the same place, AUDIT reports no errors, and the boundary convention (page units from the insertion point, before scale and rotation) holds both ways.

Known limits

  • PDFFRAME isn't saved with the drawing yet: drawings keep a value other than 1 as a DICTIONARYVAR in their AcDbVariableDictionary, which CADCraft keeps as raw data today; writing it there is left for a follow-up.
  • A page's lines are read once; if the PDF changes on disk, the snaps follow it after the drawing is opened again.
  • The lines kept for snaps are keyed by the path stored in the drawing and the page. Two drawings open at once whose relative path (or file name beside the drawing) names two different PDFs share one set of lines, so the second snaps to the first one's page. Keying them by the drawing's folder needs the snap code to know where the drawing is saved; I'd rather propose that in a small PR of its own.

Not changed

No existing command, file field or catalog line.

@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
ATARYS-LAB force-pushed the pdf-clip-frame-osnap branch from 3927432 to ce229c9 Compare October 28, 2026 19:45
ATARYS-LAB added a commit to ATARYS-LAB/cadcraft that referenced this pull request Oct 29, 2026
…d#2419), and PDFIMPORT refuses a rotation that is not a number

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y9NS8fTTLQsPJ1CcUr
ATARYS-LAB added a commit to ATARYS-LAB/cadcraft that referenced this pull request Oct 29, 2026
@ATARYS-LAB
ATARYS-LAB force-pushed the pdf-clip-frame-osnap branch 2 times, most recently from de49c57 to 101f2f0 Compare October 31, 2026 00:23
ATARYS-LAB added a commit to ATARYS-LAB/cadcraft that referenced this pull request Oct 31, 2026
…d#2419), and PDFIMPORT refuses a rotation that is not a number

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y9NS8fTTLQsPJ1CcUr
ATARYS-LAB added a commit to ATARYS-LAB/cadcraft that referenced this pull request Oct 31, 2026
ATARYS-LAB added a commit to ATARYS-LAB/cadcraft that referenced this pull request Oct 31, 2026
@ATARYS-LAB
ATARYS-LAB force-pushed the pdf-clip-frame-osnap branch 2 times, most recently from 29eb8dc to e26cd2e Compare October 31, 2026 18:58
@ATARYS-LAB
ATARYS-LAB force-pushed the pdf-clip-frame-osnap branch from e26cd2e to 3770c00 Compare October 31, 2026 21:21
ATARYS-LAB added a commit to ATARYS-LAB/cadcraft that referenced this pull request Nov 3, 2026
…d#2419), and PDFIMPORT refuses a rotation that is not a number

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y9NS8fTTLQsPJ1CcUr
ATARYS-LAB added a commit to ATARYS-LAB/cadcraft that referenced this pull request Nov 3, 2026
ATARYS-LAB added a commit to ATARYS-LAB/cadcraft that referenced this pull request Nov 3, 2026
ATARYS-LAB added a commit to ATARYS-LAB/cadcraft that referenced this pull request Nov 3, 2026
…d#2419), and PDFIMPORT refuses a rotation that is not a number

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y9NS8fTTLQsPJ1CcUr
ATARYS-LAB added a commit to ATARYS-LAB/cadcraft that referenced this pull request Nov 3, 2026
ATARYS-LAB added a commit to ATARYS-LAB/cadcraft that referenced this pull request Nov 3, 2026
ATARYS-LAB and others added 7 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
Two drawings whose PDF comes back together each asked for its lines on a worker thread, so a
large PDF was read twice at once. A page being read is noted; a second reading of it reads
nothing.
…s for object snaps on a worker thread

The window waited for every page's lines (1.3 s for ten ArchiCAD sheets);
the OPEN command (scripts, CLI, MCP) still reads them at once, so a snap on
the next line finds them.
…s, so a query looks near the cursor only

Each snap query went through every point of the page's lines (millions on a dense plan). Lines
are now kept in runs of at most 64 points with their bounds, and a query skips the runs away from
the probe, taken into page fractions. The PDF layers key comes from PdfUnderlay::key_of_layers.
# 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
…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.
ATARYS-LAB added a commit to ATARYS-LAB/cadcraft that referenced this pull request Nov 7, 2026
…d#2419), and PDFIMPORT refuses a rotation that is not a number

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01XkJ8y9NS8fTTLQsPJ1CcUr
ATARYS-LAB added a commit to ATARYS-LAB/cadcraft that referenced this pull request Nov 7, 2026
ATARYS-LAB added a commit to ATARYS-LAB/cadcraft that referenced this pull request Nov 7, 2026
@ATARYS-LAB
ATARYS-LAB force-pushed the pdf-clip-frame-osnap branch from f9c9e9c to 6d58738 Compare November 7, 2026 17:12
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