OneCAD-Draft/docs/viewport-dimensions.md

Dimensions through paper-space viewports

Paper-space point commands can snap to displayed model geometry through a planar, orthographic layout viewport. The acquired result retains the original model coordinate, its paper coordinate, the viewport frame, and feature identity. Ordinary selection continues to operate on the active drawing space.

DIMLINEAR, DIMALIGNED, DIMANGULAR, DIMRADIUS, and DIMDIAMETER use this acquisition context. The supported object-pick modes also query viewport geometry. Snapping and object picking share viewport draw order, visibility, and clipping rules. Object picking uses the resident interaction index and applies block instance transforms. Nonuniformly transformed circles and circular arcs are declined as radial object picks because their displayed geometry is elliptical. Array inserts without an addressable instance index are also declined; resolved block geometry must remain within the original pick aperture.

Input and measurement rules

• Free and typed sheet points measure paper units, including points inside a viewport rectangle.
• Measuring points must all belong to the same space and, when applicable, the same viewport. An incompatible pick leaves the command at its current step.
• Dimension-line and text placement do not change the measurement's space.
• Paper geometry takes priority over viewport geometry at an object pick.
• The final dimension style is applied before computing measurement scaling. Length dimensions keep paper-space definition points and a negative DIMLFAC override containing the effective user factor multiplied by 1 / viewport scale. Angular measurements do not use this length factor.
• DIMASSOC=0 uses the same compensated value before exploding the annotation.

Persistent measurement data

OCS_VIEWPORT_MEASUREMENT XData stores three values: version 1 (integer16), the positive user factor (real), and viewport compensation (real). This keeps the user's unit conversion separate from viewport scale. The ordinary DIMLFAC override remains sufficient for displaying the saved measurement in other CAD readers. The data survives DXF/DWG saves and undo/redo.

With DIMASSOC=2, acquired features attach a dimension to its viewport, each block instance, and the source entity. Intersections retain both source chains. Source edits and viewport changes update the definition points and recompute compensation while preserving explicit user-positioned sheet text and dimension style overrides. A successful update invalidates the saved picture block so the new geometry and number are rendered and exported. Undo restores both the reference data and the previous picture.

Properties reports whether the dimension is associated, partially associated, unresolved, broken, or nonassociative. A broken or unsupported required reference preserves the entire dimension's last valid appearance and its original records. Creating another dimension does not announce geometry changes to its sources.

Imported references and support limits

The resolver distinguishes the application's vertex/parameter convention from imported edge references. Imported start/end and midpoint modes use their edge marker and parameter together. The original regression drawing's first-edge start/end pair now reproduces its 0.128 measurement. An imported polyline endpoint beyond the first edge requires a usable stored point to validate the marker; zero/sentinel data cannot establish that identity. Ambiguous imports remain unresolved. Imported viewport scale is updated only when existing OCS metadata or ACAD_DIMASSOC_CALC_DIMLFAC separates compensation from user scaling.

Unsupported cases retain their saved data and appearance:

• Perspective/oblique viewport projections and malformed/missing reference chains.
• Ambiguous intersections within one batched block; they are not attached to a guessed pair of children. Intersections between separate identified chains work.
• Array inserts without an addressable instance index, nesting beyond eight levels, and radial measurements of nonuniformly transformed circular geometry.
• Imported quadrant references whose moved geometry no longer validates the stored point; newly acquired circle/arc quadrants keep their source-local angle.
• Tangency with no verified solution, two dependent perpendicular/tangent references requiring a coupled solve, unsupported snap modes, and imported measurement data that does not identify the old viewport compensation.

The osnap codes and reference fields follow the Autodesk DIMASSOC reference. The restricted imported-marker interpretation above is validated by fixtures; it is not a claim that every exporter uses an interchangeable marker scheme.

Validation

src/app/viewport_dimension_tests.rs exercises snap-engine acquisition, command commits for all five commands, object picks, input retries, active positive and negative style factors, exploded dimensions, undo/redo, DXF/DWG persistence, clipping, overlapping viewports, pan, scale, and twist. These are headless tests; they do not establish visual acceptance in the desktop UI.

Association tests also exercise regeneration, nearest and quadrant parameters, angular arc/polyline object picks, spline tangency, perpendicularity under nonuniform block scale, nested paths, intersection source edits, preserved overrides, erased sources, copy detachment, saved picture invalidation, and history. The checked-in DXF fixture is exercised directly. The original private drawing can be checked separately:

$env:OPENCAD_VIEWPORT_REGRESSION_DXF = 'C:\path\to\115448.dxf'
cargo test --locked --offline --lib viewport_dimension_original -- --ignored --nocapture

Do not treat passing headless checks as completed desktop visual acceptance.