Skip to content

dxf_engine: dimensions measure the model, one issue list, native DIMENSION entities - #95

Merged
NiJingzhe merged 7 commits into
PhySpace:devfrom
lizaixi01:feat/dxf-engine-bound-dimensions
Nov 16, 2026
Merged

NiJingzhe merged 7 commits into
PhySpace:devfrom
lizaixi01:feat/dxf-engine-bound-dimensions

Conversation

@lizaixi01

Copy link
Copy Markdown
Contributor

What this is

A rework of the drawing engine (simplecadapi.dxf_engine). The loop stays as designed (HLR outline from OCCT, annotation through ezdxf, the engine judges the layout, the agent adjusts); this PR makes both halves of it trustworthy. Some ideas are carried over from AgentCAD (native dimensions with measured text, coded issues with fix hints, read-back of the written file, saying what was not checked).

The full account is in design-docs/drawing-engine-bound-dimensions.md: ten findings from drawing a real plate with the old engine, nine decisions (D1–D9) with what was rejected, and what changes for a caller.

What changes

  • A dimension measures the model. DimDecl(of=...), between=(a, b), extent="x"|"y" take a geometry reference (SDK entity, QL selector resolving to one entity, 3D point). The number on the sheet is the measurement and follows the model; value is the expectation and a difference is an error. Typed p1/p2, center/radius still work and are checked against the figure lines.
  • One conflict test, one issue list. collide.conflicts is used by the solver, the evaluation and the actions; SheetPlan.issues() feeds report() and the diagnostic picture. Before, the report could say R1–R7 ok while the picture marked elements red.
  • New checks, each with a hint: text over a figure line of its own view, DIM_VALUE_MISMATCH, DIM_NOT_ATTACHED, UNDIMENSIONED_CYLINDER, OVERALL_SIZE_MISSING, views outside the frame. Every report ends with what is not checked.
  • What is checked is what is drawn. One geometry derivation per dimension kind; text placed by its box; text width measured in the sheet's font. An element with no clean position is drawn in the least-conflicted one and reported (it used to vanish from the DXF).
  • Native DIMENSION entities (style GB, DIMLFAC = 1/scale) with our own block; the file is read back after writing and each dimension compared with the model.
  • Derived unless declared: scale=None, anchor=None, sheet="A4".."A0", title block shows only declared fields.
  • Added: section views (hatch, title, cutting-plane symbol), centre lines from the model's cylinders, tolerances and fits, count (4×), surface texture (RoughDecl), a diameter on a cylinder seen from the side.
  • planner.py (769 lines) is split into planner, dims, leaders, collide, geom2d, bind, refs, views, sheet, checks.

Behaviour changes to review

  • Dimension text no longer carries (caption) (SheetDecl.show_captions=True restores it).
  • DimDecl.dec=None shows the value's own decimals (was 0: ⌀6.5 was drawn as 6).
  • align gap is the clear distance between views (was measured to the view's origin).
  • Diameter text is inside or outside the circle, never across it. Two tests in test_dxf_engine.py encoded the old rules and were rewritten.
  • material="" and no default designer (they were hard-coded).
  • Small dimensions take the inner rows (the old sort key put the largest first).

Checked

  • test/test_dxf_engine.py (20) and the new test/test_dxf_engine_bound.py (21) pass, with test_auto_docs_gen, test_skill_lint, test_skill_build, test_drawing_skill_integration: 114 in all, rebased on dev at b332b64.
  • Two sheets (a plate with section A-A; a stepped shaft with a cross hole, tolerance and surface texture) were rendered and looked at: 0 issues, every dimension read back equal to the model.

Not verified, not done

  • The DXF was not opened in AutoCAD or any other CAD program.
  • The diagnostic picture itself was not changed or looked at after the rework, and the evaluate → apply loop was not run end to end by an agent; only its unit tests ran.
  • Run on macOS arm64 only, with the 2.3.0 wheel's native module under these Python sources (nothing under src/cpp changed, nothing was rebuilt). The full suite was not run: three unrelated test files need trimesh, which was not installed. CI here is the first full run.
  • Fonts on Windows and Linux: text width falls back to an estimate when the font cannot be loaded.
  • Layout is conflict-free, not optimised for looks; leaders are placed as before.
  • No aligned, angular or chamfer dimensions, threads, welds, geometrical tolerances or assembly sheets. Tolerance values are drawn as declared, not checked against a standard.
  • The engine rewrite is one commit: its decisions touch the same files and could not be staged apart without commits that do not import. The record separates them. Happy to split it another way if you prefer.

🤖 Generated with Claude Code

lizaixi01 and others added 7 commits November 14, 2026 23:28
DECISION: render_plan converts both of its paths to pathlib.Path at entry.

WHY (review of the drawing module with the owner, 2026-11-14): the first sheet drawn in that review called
`plan.render("plate.dxf", "plate.png")` and died after the DXF was written, with
`AttributeError: 'str' object has no attribute 'write_bytes'`. The DXF half already accepted a str (ezdxf does), the PNG
half did not, and neither the docstring nor the skill page says a Path is required. An agent writes str paths by default.

WHAT CHANGES: src/simplecadapi/dxf_engine/render.py, one line.

Checked: test/test_dxf_engine.py passes (18); the review script that failed now writes both files with str paths.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…nd to the model, one truth for checks)

DECISION: the decision record of the dxf_engine rework is design-docs/drawing-engine-bound-dimensions.md. It is committed
first so that the commits that follow can point at it.

WHY (discussion with the owner, 2026-11-14): the owner's note said the drawing module had never been looked after, described
its scheme (HLR outline from OCCT, annotation by ezdxf, the engine judges a layout and shows a diagnostic picture, the agent
adjusts), asked for the experience of AgentCAD to be carried over, and expected a better scheme. The record holds what was
found by drawing a real plate with the old engine (ten findings, each with its cause), what was read in AgentCAD, the nine
decisions D1-D9 with what was rejected, what changes for a caller, what was not done, and what was checked.

WHAT CHANGES: one new file. design-docs/ is git-ignored, hence `git add -f`.

Checked: the findings table was produced by running the old engine; the "Checked" section of the record lists the test runs.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…nd one issue list; native DIMENSION entities

DECISION (D1-D9 of design-docs/drawing-engine-bound-dimensions.md, the record committed as "docs(design): record the rework
of the drawing engine"): the drawing engine takes what a dimension measures from the model, checks a sheet with one test and
reports it as one list of issues, draws exactly the geometry it checked, and writes dimensions a CAD program can edit.

These decisions are one commit because they are one rewrite of the same files (planner.py was split while its solvers
changed); the hunks cannot be staged apart without leaving commits that do not import. The record separates them.

WHY (discussion with the owner, 2026-11-14)
- The owner: the module's ability is poor and "there should be a better scheme" than "the engine finds bad layout, the agent
  adjusts". Drawing a plate with the old engine showed the scheme was sound and both of its halves were not trustworthy:
  the report said R1-R7 ok while the diagnostic picture marked three elements red; texts stood on the lines of their own
  view; for a line pointing left the checked box and the drawn text ran opposite ways; `prefix` was dropped on diameters; the
  thickness of the plate was on no figure and nothing said so; the dimensions were typed coordinates that a parameter change
  leaves behind.
- AgentCAD's measured lesson (its trials report): 7 of 7 agent runs validated themselves as passed, 5 of 7 had visible
  defects; once a check named a defect, agents fixed it unaided. So: bind to geometry, check truthfully, say what is not
  checked.

D1 references: DimDecl.of / between / extent (refs.py, bind.py); the number is the measurement, `value` is the expectation.
D2 one truth: collide.conflicts (solver, evaluation, actions), checks.collect_issues (issues(), report(), picture).
D3 checked = drawn: lin/dia/rad_geometry shared; text placed by its box; width measured in the sheet's font.
D4 checks with hints: truth, completeness, sheet; NOT_CHECKED printed with every report.
D5 never an undrawn element: the least-conflicted candidate is drawn and reported.
D6 native DIMENSION in style GB with our own block; verify_dxf reads the file back.
D7 the sheet is derived unless declared: scale, anchor, format, notes height, title-block fields; gap = clear distance.
D8 sections with hatch and cutting symbol, centre lines from cylinders, tolerances/fits, surface texture.
D9 planner.py (769 lines) split into planner, dims, leaders, collide, geom2d, bind, refs, views, sheet, checks.

ALTERNATIVES CONSIDERED AND REJECTED
- Fully automatic dimensioning from the feature graph: which sizes matter is a design statement; missing ones are proposed
  by checks instead.
- Letting ezdxf render the dimension blocks: its diameter renderer with a user text position drew a degenerate line in a
  trial, and its geometry would not be the geometry the solver checked.
- Keeping the "straddle" diameter text (starting at 0.75 r, crossing the circle): it always stands on the circle it measures.

WHAT CHANGES FOR A CALLER (kept: every old declaration field, evaluate/apply and their action format)
- Defaults: no "(caption)" in dimension text (SheetDecl.show_captions), DimDecl.dec=None, material="", notes_zone=None.
- Two tests of test_dxf_engine.py encoded rules that are reversed on purpose and were rewritten: a text inside an arc may no
  longer stand on a figure line (the circle of the test moved off the box), and the diameter text contract (inside or
  outside, never across). Three tests were added there, 21 in test/test_dxf_engine_bound.py.

Checked: test_dxf_engine.py (20) and test_dxf_engine_bound.py (21) pass. Two sheets (plate with section A-A; stepped shaft
with a cross hole, tolerance and surface texture) were rendered and looked at: 0 issues, every dimension read back equal to
the model. Run on macOS arm64 with the 2.3.0 wheel's native module under these Python sources. Not verified: the DXF in
AutoCAD or another CAD program; fonts on Windows and Linux (the text width then falls back to an estimate).

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…PI pages regenerated

DECISION: the skill's drawing page (domains/engineering-drawing.md) is rewritten around "reference the model, declare, solve,
read the issues", and RoughDecl, Issue and RefError get API pages.

WHY: follows "feat(dxf_engine): a dimension measures the model; ..." (record: design-docs/drawing-engine-bound-dimensions.md).
The page told agents to declare `p1`/`p2` coordinates and to read "R1-R7 ok" as the gate; both are what the rework replaced.
An agent reads only the skill, so an engine change that the page does not teach does not exist for it (core rule R13: an API
not on its page does not exist). The example on the page was run as written.

WHAT CHANGES: the domain page; one gate line of workflows/engineering-drawing.md (issues instead of "R5 no MISS");
tools/auto_docs_gen.py lists dxf_engine/checks.py and refs.py and the three new names; the generated pages under docs/api.

Checked: test_auto_docs_gen, test_skill_lint, test_skill_build, test_drawing_skill_integration pass (the generated pages are
what the generator writes). The installed skill under ~/.claude/skills is not refreshed by this commit.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
DECISION: the rework is listed under a new "Unreleased" heading; no version is chosen here.

WHY: follows "feat(dxf_engine): a dimension measures the model; ..." (record: design-docs/drawing-engine-bound-dimensions.md).
It changes defaults of a public namespace (dimension text, `dec`, `material`, view gap), so a caller has to be told; which
version carries it and whether docs/updates notes are written is the owner's call at release time.

WHAT CHANGES: CHANGELOG.md only.

Checked: nothing to run; the entries were written from the record's "What changes for a caller".

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
…talled or not)

With OCP installed (the verify extra, which the skill tells every user to install for verifier scripts) shape.wrapped is an
OCP shape, and the engine, which works on the SDK's own OCCT (simplecadapi._cpp.occt), raised
"TypeError: Add(): incompatible function arguments" in HLRBRep_Algo.Add: 39 of the 48 drawing tests fail in that
environment (the suite's conftest forces SCA_WRAPPED=native, and CI's main suite has no OCP, so nothing showed it). The
bug is older than this rework (hlr.py), the rework's reference code took the same path.

The SDK states the rule in simplecadapi/_glue/bridge.py: its own Python layers (inspect, drawings, translators) work on
shape._native_wrapped, and native_occt() converts an OCP shape. refs.raw_shape is now that one entry point: an SDK entity
gives its own OCCT shape (nothing copied), an OCP shape is converted, an OCCT shape is kept; a selector's entity goes
through it too, and hlr_project converts its input, so it is usable on its own. No environment variable is read.

Test: test_verify_bridge.py (the one file CI runs with OCP overlaid) draws a sheet from the solid, its .wrapped and an
explicit OCP shape, with .wrapped native and OCP. It fails without the fix (2 failed), passes with it. All 48 drawing
tests pass with SCA_WRAPPED=ocp and with the default, 124 with the skill, bridge and docs tests. ViewDecl.md regenerated.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
The workflow page described the old engine; checked against the code:
- a dimension names what it measures (of / between / extent) in Role 2 and Role 3, centre lines come from the model's
  cylinders, the solid (not .wrapped) is ViewDecl.shape for selector references;
- the picture is SheetDecl.diag_png (grey ok, red warning, orange accepted, blue the obstacle, badge [N] = evaluate() id,
  a close-up per warning); there is no `viz` and no pixel diff of two replays, and the blast radius is read from
  plan.issues();
- the exit gate and acceptance use the issue list (no error, no DIM_VALUE_MISMATCH, every parameter has a carrier) instead
  of an R5 table with MISS, which report() no longer prints;
- a section view is no engine boundary any more (hatching, A-A title, cutting-plane symbol); the boundaries are the domain
  page's; the scale is left to the engine unless a standard fixes it;
- Role 5 reads DIM_RENDER_MISMATCH / DIM_MISSING_IN_FILE and says whether the DXF was opened in the target CAD.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@NiJingzhe
NiJingzhe merged commit cbdba64 into PhySpace:dev Nov 16, 2026
11 checks passed
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.

2 participants