Overview | Duc

Elements are the fundamental spatial building blocks of .duc, including geometric, document, model, and layout elements.

What is an Element?

Every visual entity on the 2D canvas whether it is a simple geometric line, a rich text note, a spatial spreadsheet table, a 3D CAD model, an embedded PDF document, an artboard frame, or a reusable block instance is represented as an Element.

Model Elements are the only element type that can produce an interactive 3D model in a .duc file. Other element types can depict depth or contain a 2D projection of 3D geometry, but they do not carry executable model source, external CAD model data, or a persistent 3D viewer state. Model Elements are not limited to 3D content: they also represent interactive 2D CAD sources such as DXF and DWG.

The Universal Element Foundation

All elements inherit a core set of base spatial, structural, and identity properties (_DucElementBase):

1. Spatial Identity & Placement

id: Unique string identifier for the element.
x, y: Spatial origin coordinates (PrecisionValue), stored normalized to the meter (NEUTRAL_SCOPE = "m").
width, height: Physical bounding dimensions (PrecisionValue).
angle: Rotation angle in radians.
scope: The measurement unit scope (mm, cm, m, in, ft, mi) in which the element was created.

2. Visibility & Layering

isVisible: Boolean flag determining viewport visibility.
isDeleted: Soft-deletion flag preserving historical undo/redo and DAG version control.
zIndex: Explicit stacking order determining which elements render on top.
layerId: Reference to the drawing layer the element belongs to.
frameId: Reference to the parent artboard frame container, if enclosed within one.

Every element also carries ordered background and stroke lists. See Styling Elements for layering, opacity, stroke geometry, content preferences, and adapter-safe mutation.

3. Structural Relationships & Grouping

groupIds: Ordered array of parent group IDs, supporting nested selection and manipulation.
regionIds: List of boolean operation region boundaries the element participates in.
blockIds: Populated if this element helps define a master Block definition.
instanceId: Populated if this element belongs to a live Block Instance on the canvas.

4. Concurrency & Reconciliation

version: Integer incremented on each state change, used for real-time collaboration reconciliation.
versionNonce: Deterministic random seed regenerated per edit to resolve identical version collisions in multi-user sessions.

Catalog of Element Types

.duc categorizes elements into distinct functional groups:

1. Geometric Primitives

rectangle: Rectangular shapes with configurable corner roundness.
ellipse: Circles, ellipses, and arc segments.
polygon: Multi-sided regular or arbitrary closed polygons.
line: Straight lines and multi-segment polylines.
freedraw: Freehand vector stroke paths generated by stylus, pen, or mouse input.

2. Typography & Annotation

text: Rich typography supporting custom font families, font sizes, line spacing, text alignments (left, center, right), and vertical alignments.

Text Elements store their primary and fallback font family names rather than font files. See Using Fonts for the cross-element font contract and adapter examples.

3. Structured Data & Documents

table: Interactive spatial spreadsheets holding tabular data cells, rows, and columns directly on the canvas.
doc: Embedded typst code document containers for rich project notes and technical specifications that is compiled to a PDF.
pdf: Vector PDF overlays rendering multi-page document attachments in vector resolution.

4. Interactive Models & Procedural Code

model: The exclusive container for interactive 3D models in .duc, with persistent viewer and camera state. Its source can be procedural python code or an external IFC, STEP, STL, DXF, or DWG file. The same element type also supports interactive 2D CAD content from DXF and DWG.

5. Media & External Embeds

image: Raster image asset attachments and SVG vector graphics.
embeddable: Interactive external web application iframe embeds.

6. Spatial Layout & Output Boundaries

frame: Artboard containers that visually group, clip, and organize canvas regions.
plot: Export and print plotting boundaries defining printable page areas.

7. Reusable Block Instances

instance: A specialized element acting as a live reference instance on the canvas, linked directly to a master Block definition. Explore how elements can be combined into reusable templates in the Blocks page.