Add an SVG backend, full layer attributes, and close the remaining rendering gaps

[mubeda]

Summary

This branch adds a hand-written SVG backend and full layer-attribute support to ACadSharp.Image, then works through every remaining rendering gap until no drawing in the maintainer's private test set produces a single "not implemented" notification. Along the way it uncovered and worked around a class of document-corruption bugs in ACadSharp 3.7.1 that silently empties geometry in the caller's own document whenever a block is rendered.

130 commits over ten reviewed implementation plans. 460 tests, all green under -warnaserror. Every commit was implemented against a written plan, passed a scoped review, and the branch as a whole passed two independent external code reviews (OpenAI Codex) plus two whole-branch reviews with fix waves.

Breaking change: net6.0 is dropped. This should ship as a new major version.

---

What was built

1. A drawing-surface abstraction and an SVG backend

Rendering was split into a backend-neutral IDrawingSurface with two implementations: the existing SixLabors.ImageSharp raster surface and a new SVG surface written directly with System.Xml.Linq (SkiaSharp was evaluated and rejected: no groups, no dash arrays, native dependencies).

The SVG is designed for React/web consumers:

• One <g> per layer (id="layer-…" class="cad-layer" data-layer="…") so layers can be toggled client-side.
• data-type, data-handle, data-parent and data-block attributes on every primitive for hit-testing and inspection.
• A drawing-unit viewBox with no width/height by default; vector-effect="non-scaling-stroke" on by default.
• Native <ellipse>, <path> Béziers and <text>/<tspan> where the raster tessellates and outlines.
• Adaptive coordinate precision, a separate style-precision formatter, xml:space="preserve" scoped so pretty-print indentation is never drawn.
• SvgOptions: NonScalingStroke, EmitEntityAttributes, EmitSize, IdPrefix, Precision.

Both backends are fed identical geometry and were verified never to disagree on it (see Testing).

2. Layer attributes

Colour, linetype, lineweight, transparency, plottable flag, on/off and frozen state are now honoured, with correct ByLayer/ByBlock inheritance through nested block references and header LTSCALE/CELTSCALE linetype scaling. Layer visibility is opt-in (LayerVisibilityMode.All is the default): Screen honours off/frozen, Plot also honours non-plottable. HideLayers/IncludeLayers filter by name. Filtering runs in the render loop and applies per entity, including block children, and the page frame follows what remains visible.

3. Entities that were missing or wrong

Added or fixed across the branch: hatches (solid and pattern, including on tilted OCS planes inside blocks), 3DFACE with invisible-edge flags, LEADER (straight and splined, default and custom arrowhead blocks), MLINE (offsets, fill, caps, MLEDIT cut segments), WIPEOUT (including inverted clips, drawn as even-odd paths), block ATTRIBs with ATTMODE (including multi-line attributes laid out from their embedded MTEXT), paper-space viewports interleaved in draw order, DRAWORDER tables, SOLID corners on non-world planes, and page-level draw order with correct painter ordering.

4. Text fidelity

SVG font-size is 4/3 of the CAD height; raster text is laid out at a fixed 72 dpi so Dpi affects only line weights. Multi-line blocks are anchored as a whole. MTEXT rectangle-width wrapping uses a greedy fit measured with SixLabors.Fonts (UAX #14 break opportunities shared by both backends). \U+XXXX and %% codes are decoded. Text placed by a block reference follows the transformed up axis for height and the transformed reading axis for width, so non-uniformly scaled inserts stretch text correctly. A font fallback chain (Liberation Sans, DejaVu Sans, Arial, Helvetica, Noto Sans, Segoe UI) covers Linux CI.

5. CLI

--format svg, --hide-layer, --only-layer, --layer-visibility {all|screen|plot}, --list-layers (prints the layer table with per-layer entity counts). Extra positional arguments are rejected instead of silently ignored. Output is routed through a testable Program.Run(args, output, error).

6. Robustness

Malformed entities (e.g. a bulge between coincident vertices, which makes ACadSharp throw) are skipped with a warning instead of aborting the export. Non-finite geometry is caught per entity on both backends. A block reference with no block, or one nested inside a resolvable block, is skipped with a warning rather than throwing out of the public entry point. Page framing and viewport culling use the same bounds the renderer actually draws (EntityBounds). Viewport culling uses a real XY overlap test — CSMath's BoundingBox.IsIn is a corner-containment test that dropped any entity enclosing or crossing a viewport without a corner inside it.

---

ACadSharp 3.7.1 behaviours this branch works around

These are all probe-verified against the shipped package and recorded in code comments, the spec and the README. They are the part of this branch most worth a second pair of eyes.

Document corruption through shared lists. MLine.Clone(), Leader.Clone() and Wipeout.Clone() share their vertex List objects with the source entity; Insert.Explode() and even the Insert(BlockRecord) constructor deep-clone the whole block graph, so rendering a drawing emptied MLINEs in the caller's own document. The renderer snapshots every shared list reachable from a block before anything clones and heals them in place (Clear + AddRange, never reassignment, because clone and source are literally the same object). Six paths were found and closed, each with a RED-verified regression test measuring 2 vertices → 0 without the fix:

• nested Insert.Block
• all four DimensionStyle block properties (ArrowBlock, DimArrow1, DimArrow2, LeaderArrow), reached from both Leader and Dimension
• Dimension.Block, the anonymous picture block
• DrawDimension's top-level UpdateBlock() call

One shared ReferencedBlocks(Entity) enumerator feeds all three walks (snapshot collection, needs-snapshot scan, cycle guard) so the edge set cannot drift. Consequence for callers: a CadDocument must not be rendered concurrently by two exporters (documented in ImageExporter.Render and the README).

Uncatchable stack overflow on circular block graphs. A block that references itself makes Explode() and GetBoundingBox() recurse until the stack dies, and a StackOverflowException cannot be caught in .NET. A dedicated depth-first walk with an on-path set (so a block reused from two places is a diamond, not a cycle) refuses such graphs with a warning before anything recursive runs, on both the draw path and the bounds path. Verified by reverting the guard: the test host dies.

Insert transform diverges from AutoCAD. Insert.GetTransform() computes R·S·p + (InsertPoint − BasePoint); AutoCAD specifies InsertPoint + R·S·(p − BasePoint). They agree only when rotation and scale are identity, so a block with a non-zero base point placed with rotation or scale lands differently than in AutoCAD. Latent (no sample hits it), but the custom-arrowhead code builds a transient Insert on purpose and compensates by measuring where the base point lands and correcting — a method that stays correct under either formula.

Explode leaves text and hatches wrong. Explode() never transforms a TEXT AlignmentPoint or an MTEXT X axis, hands back TEXT/HATCH clones with world points but a mirrored normal, transforms a hatch's raw OCS boundary as if it were world data, and transforms a wipeout's U/V vectors as points (so a translation contaminates them). Text, MTEXT, hatches, wipeouts, leaders and non-world solids inside blocks are therefore drawn from the original entity through the insert transform (UsesOriginalGeometry is the canonical list), with ordinal original/clone pairing — the only identity ACadSharp offers, since clones carry no handle. A count mismatch warns.

Smaller quirks: IPolyline.GetPoints, BoundaryPath.GetPoints and Hatch.ExplodePattern return raw OCS coordinates; ExplodePattern is eager; CSMath.Matrix3.ArbitraryAxis is not orthonormal for tilted normals (the renderer has its own OcsTransform); Ellipse.MajorAxis is a full length; the SpaceLineTypeScaling enum names are swapped relative to the stored DXF value; DimensionStyle.Clone() deep-clones its arrow blocks; Viewport.SelectEntities() enumerates Document.Entities unguarded.

---

Public API changes

• New: RenderedPage (abstract, IDisposable), RenderedImagePage, RenderedSvgPage, SvgOptions, LayerVisibilityMode, ImageExportFormat.Svg.
• ImageConfiguration: LayerVisibility, HideLayers(...), IncludeLayers(...), Svg options, FontFamilyName, MaxHatchLines, SetPadding; Dpi now documented as affecting line weights only.
• ImageExporter.Render() returns RenderedPages carrying the requested format; Render(ImageExportFormat).
• Notifications carry NotificationType (Warning, NotImplemented, …) and the shape [{SubclassMarker}] Handle {X}: ….
• Removed dead overloads (ImageStyleResolver.Resolve, ImagePage-based SVG context overloads).
• net6.0 target dropped.

---

Testing

460 tests, byte-compared PNG baselines and SVG goldens under ACadSharp.Image.Tests/Baselines/ (16 files). Goldens are regenerated only with a documented cause in the commit body and only via a scoped filter, never over the whole suite. Coverage after plan 04 was 90.5% lines / 84.4% branches.

Synthetic golden fixtures render every added feature through both real backends with structural assertions that run after the byte comparison (so regenerating a baseline cannot erase them) and that each fail against the pre-feature behaviour: features.model.01, entities.model.01, fidelity.model.01, plus a code-built paper-space viewport sheet round-tripped through DxfWriter/DxfReader. The fidelity golden also asserts no Warning/NotImplemented fires, which is the check that proves no feature silently fell back.

Real-drawing parity. Against the maintainer's private set of seven production DWGs (not in the repository, never named in it), SVG and PNG output were rasterised to a common size and compared by mutual ink containment with a 5 px dilation: 99.8–100% both ways on every drawing where the comparison is meaningful, unchanged across the last three plans. The same harness was run in five layer-selection modes (all, screen, plot, isolate one layer, hide one layer — 70 renders): parity held in every mode and the SVG layer-group count matched the selection exactly. Every "not implemented" notification on those drawings is gone; the only remaining warnings are 18 malformed polylines that are a defect in the drawing data itself.

Review process. Each plan ran as subagent-driven development: one implementer per task, a scoped spec-and-quality review per task, fix rounds with scoped re-reviews, then a whole-branch review and one fix wave. Two independent read-only reviews by OpenAI Codex were processed with verification-first (findings were probed against ACadSharp before being accepted; declined findings and the reasons are recorded in the plan headers). Notably, every task in plan 10 found an error in its own plan's test expectations, and in each case the reviewer independently upheld the implementer over the plan.

---

Documentation

• Specs: docs/superpowers/specs/2026-09-02-layers-and-svg-design.md (binding design, amended per plan) and 2026-09-04-remaining-limitations-design.md (with an As implemented section recording every divergence).
• Plans: docs/superpowers/plans/2026-09-02-01 … 2026-09-04-10.
• Research: docs/research/layers-and-svg-support.md, remaining-rendering-limitations.md, remaining-limitations-design-options.md (the Codex consultation this work argues from).
• README: supported entities, layer handling, SVG structure and options, thread-safety note, CLI flags.
• CI: path filters now include Directory.Packages.props, Directory.Build.props and the solution; an explicit -warnaserror build step precedes the test step; a DejaVu font install step for text tests.

---

Known limitations (all documented in README)

• MLINE cut positions are read as absolute distances from the element start. The DXF reference reads that way, but ezdxf reads the same values as relative dash/gap lengths and no implementation settles it; the only real-world sample available has its break at the segment end and renders identically either way. A drawing with more than one cut per element may differ from AutoCAD. MLINE fill cuts (group 42) are notified, not drawn.
• A custom arrowhead inside a non-uniformly scaled block reference falls back to the default triangle (an Insert cannot express shear); an empty or self-referencing arrow block does too, with a warning.
• Wipeouts need an opaque background; on a translucent background they are skipped with a warning.
• In SVG, layer grouping takes precedence over painter order, so a wipeout cannot mask a later entity on an older layer group. Exact cross-layer painter order would need per-entity groups.
• An attribute on an insert nested inside another block is laid out in that block's own coordinates.
• Block contents are drawn in stored order at the first nesting level and in handle order below it (BlockRecord.Clone() enumerates GetSortedEntities()).
• TEXT on a non-default plane is drawn with readable glyphs on the mirrored extent; AutoCAD mirrors the glyphs. A deliberate readability choice, not a parity guarantee.

---

Notes for the reviewer

• CI has not yet run on GitHub for this branch; it was validated locally (dotnet test ACadSharp.Image.sln --configuration Release -warnaserror, 460/460) at the final commit.
• Three small follow-ups were deliberately left out and are recorded in the final review: a circular block inside a viewport reports the bounds message rather than the clearer "references itself" one (it is culled before drawing); Leader.Style is dereferenced directly in two places and null-conditionally in two others; EntityRenderDispatcher.cs is ~1,700 lines and the block-graph walks (ReferencedBlocks, CollectSharedVertexLists, ScanBlockSubtree, BlockGraphIsCircular) are a clean, drawing-free module that could be extracted.
• The rendering behaviour that depends on ACadSharp's clone/explode quirks has tripwire tests that will start failing if a package upgrade fixes them upstream (ACustomArrowHonoursANonZeroBlockBasePoint, the …LeavesAnMLineInsideItIntact family, RenderingADimensionThroughTheExporterLeavesAnMLineInsideItsArrowBlockIntact). That is intentional: they should be revisited, not silenced.

🤖 Generated with Claude Code

[albertwoo]

For docs, please also only keep the final spec for the implementation, limitations/issues, idea for future etc. Do not put too much. Make them simple and clean for human to follow.

[albertwoo]

Please keep net6.0

[albertwoo]

Please keep net6.0

[albertwoo]

Keep net6

[mubeda]

I checked whether we can keep .NET 6. The branch was updated to ACadSharp 3.7.1, which brings in CodePages 9.0.6.
That dependency warns that .NET 6 isn’t officially supported, although my initial tests on .NET 6 passed.

The implementation has been developed and tested against ACadSharp 3.7.1; I haven’t established whether that
upgrade is strictly required, so reverting it would need a separate compatibility check.

Would you prefer that I restore .NET 6 and run further CAD reading and rendering tests, accepting the dependency
warning for now, or keep the minimum at .NET 8 until the dependency issue is resolved upstream?

I’ll also simplify the docs to cover the final implementation, known limitations, and future improvements.

[albertwoo]

yes, please restore net6 support. some of my projects still need it and cannot be upgraded for now. thanks.

[albertwoo]

I will merge and clean something and test net6 with my projects. Thanks for the contribution.