Extended Matrix

Extended Matrix Development Projects

← Back to Roadmap
DP-34

Label & Layout System (prospetti, sezioni, plates)

Tools v1.6 StratiGraph ↗ EMtoolss3Dgraphy

Description

For ten years the Extended Matrix has been documenting the state of a reconstruction — its strata, its volumes, its sources, its paradata. The state lives in the graph, the graph drives the 3D scene, the 3D scene becomes a publishable Heriverse experience. But every archaeological publication, every panel at every excavation site, every catalogue entry for every find, still demands the same set of 2D plates: a plan view, an elevation, a section, a thematic synthesis — each at a specific scale, each with a metric reference, each with the site’s elevation reading. Until 1.6 the EM Tools workflow for these plates was “set up a camera by hand, render, drop the result into your favourite vector editor, draw the scale bar by hand, ship”. Reproducible only for the modeller who set it up, regeneratable only by re-clicking the same sequence of manual steps, prone to silent drift between successive publications of the same panel.

DP-34 closes that gap. The 1.6.0-dev.8 cut already shipped the data substrate the system needs: the Layouts Blender collection (renamed from the legacy CAMS precisely because “Layouts” reflects what the collection actually holds — per-plate camera + label setups, not cameras-for-renders), the Label Tools panel under Visual Manager, the backface-shadeless material convention for stratigraphic sections, and the Grease Pencil pattern for hand-drawn contour overlays. What is still missing — and what this DP delivers — is the guided operator that turns “set up a plate by hand” into “click two points, pick a resolution, render”.

The prospetto workflow, in one paragraph. The modeller activates the Prospetto operator (Visual Manager → Layouts → ”+ New Prospetto” or a viewport gizmo), picks the first point at one end of the wall they want to elevate, picks the second point at the other end. The operator creates a vertical cutting plane through those two points (perpendicular to the floor, configurable vertical extent — by default clamped to the scene’s bounding-box height, with manual overrides for “only this storey”), places an orthographic camera behind the plane looking at it head-on, registers the new plate under Layouts/<plate_name>/ as a sub-collection holding the camera + a fresh Grease Pencil annotation surface + an empty labels sub-collection. The operator dialog then asks for the raster output resolution (named presets Screen 1×, Print A3 300 DPI, Print A2 300 DPI, plus Custom), renders the orthographic view, runs the rendered image through the EM_Plate_Overlay compositor node group which bakes in the metric scale bar (auto-sized to ~1/8 of the viewport horizontal extent, rounded to a clean tick) and the sea-level (quota s.l.m.) horizontal guide lines. The result is a publication-ready raster that names itself <project>/renders/layouts/<plate_name>_<timestamp>.png. Two months later when the catalogue editor asks for the same plate at a different DPI: open the plate, change the resolution preset, re-render, ship.

The sezione workflow is the same two-point picker, but the cutting plane is now a real cut: geometry in front of the plane is hidden (default: via the backface-shadeless section material the existing stratigraphic-section workflow already uses; opt-in: via a boolean-subtract on a hidden helper mesh, for publication-quality output where the cut volume needs to read as filled). The Grease Pencil annotation surface that the operator sets up on the cutting plane’s depth is the surface the modeller draws stratigraphic boundaries on — informal sketches in early drafts, then refined linework as the publication firms up.

Sea-level (quota s.l.m.) lines matter for archaeological practice the way ground lines matter for architectural drawings. DP-34 makes them first-class: each plate can carry a list of elevations (in metres above sea level) that the overlay node group renders as horizontal guide lines on the output, tagged with their elevation values. The source of the baseline (where is sea level relative to this scene?) comes from the Georeferencing panel (DP-56) — specifically the scene.em_tools.geo.elevation_m field if the modeller has set it, with fallback to the GeoPositionNode.altitude reading from the active graph. The modeller can also override per-plate when the site’s reference benchmark differs from the published value.

Why planimetrie are out of scope. The user observation that started this DP — “per le planimetrie in realtà ho anche Blender GIS” — is exactly right. BlenderGIS (already integrated through DP-56) produces georeferenced top views from the survey data: orthographic projection, true scale, world coordinates aligned, EPSG-correct. Re-implementing plan-view authoring inside EM Tools would duplicate work that already runs correctly. The Layouts collection accepts plate kind=plan for cataloguing purposes (a BlenderGIS-driven top-view render can be registered as a plate and stored alongside its prospetti / sezioni siblings), but DP-34 does not provide a Plan authoring operator. If a future workflow demands composite plans — for example, overlaying a stratigraphic activity graph onto a BlenderGIS plan — that becomes a follow-up DP, not a feature of this one.

Articulated cutting planes (sbalzettamenti) are the user’s Phase 2 ask: instead of a single two-point cutting plane, an ordered list of N points forming a polyline cutting plane, with each segment producing its own sub-render that the system concatenates horizontally into the published plate. This is how real archaeological elevations of irregular wall runs (stepped, curved, multi-room sequences) are drawn in publications. DP-34’s data model is forward-compatible with Phase 2 from day one — the plate’s cutting_plane_a / cutting_plane_b storage becomes cutting_plane_points: list[Vector] of arbitrary length, and the operator switches from a two-click picker to a polyline picker. Out of scope for the 1.6 MVP; flagged here so we don’t paint ourselves into a corner.

Sarmizegetusa is the case study that drove this. The Romanian-Polish team working on the Dacian sanctuary needed to publish the same prospetti and sezioni across multiple outlets — a conference panel at A2, a journal catalogue entry at A3, the project website at screen resolution — each requiring different scale ratios and DPI settings. The pain wasn’t authoring any one of them; it was re-authoring them three times. That’s the use case the design optimises for: the plate is a first-class scene object whose camera, cutting plane, labels and annotations are stable; the resolution + output format are the only thing that varies per re-publication.

Why this is in the 1.6 horizon rather than 1.7. The data substrate is already in (1.6.0-dev.8). The operator MVP is a focused, additive piece of work: two new operators (Prospetto and Sezione authoring), one compositor node group for the overlay pass, one PropertyGroup for the plate registry, one panel section under Visual Manager. No structural changes to the graph or to s3dgraphy. The Phase 2 articulated cutting planes carry into 1.7. The graph-side promotion of plates to em:LayoutPlate nodes (so a plate becomes a citable, paradata-rich artefact) is also a 1.7 follow-up — the 1.6 MVP ships without it and the 1.7 cycle adds the node typing once the operator is stable.

Open decisions (seven, full text in the notes: field): clamped vs infinite vertical extent for the cutting plane, sezione “in front” policy (backface-shadeless default vs boolean-subtract opt-in), sea-level source resolution order vs the DP-56 georef panel, graph-side promotion of plates to em:LayoutPlate nodes, raster output storage convention and RMDoc-style promotion, Phase 2 articulated cutting planes data model, Sarmizegetusa canonical illustration once the MVP lands.

Status

1.6 partial — data substrate landed, prospetto/sezione MVP next

Target EM Version

1.6

Incorporated in

EM v1.6.0-dev.8 (data substrate: Layouts collection + Label Tools panel); prospetto/sezione MVP next on 1.6

Impacts

EMtoolss3Dgraphy

Components

  • **`Layouts` Blender collection** (renamed from the legacy `CAMS` in 1.6.0-dev.8) as the per-plate data home. Each plate is one sub-collection under `Layouts/<plate_name>/` holding (a) the camera the plate renders from, (b) the per-plate label sub-collection, and (c) the optional guide-curve assets that visualise the prospetto cutting plane in the viewport. Cross-ref: [[em-blender-tools-doc-em_setup-layouts]] (RST docs page entry on `docs/panels/em_setup.rst` covering the new collection structure).
  • **Prospetto authoring operator** — a two-point picker that produces a cutting plane perpendicular to the floor (vertical plane defined by the line through the two picks, infinite in the vertical axis). The operator: (1) places a new camera at a configurable distance behind the cutting plane, looking at it orthogonally; (2) creates an orthographic projection with the cutting plane as the camera's image plane; (3) clips everything in front of the cutting plane via a backface-shadeless boolean (sezione cut) or via a one-shot Boolean modifier instance on a hidden helper mesh, depending on user choice; (4) registers the plate under `Layouts/<plate_name>/` so the same plate can be re-rendered later with one click.
  • **Sezione authoring operator** — same two-point picker as the prospetto, but the cutting plane is now a real cut (the geometry in front of the plane is hidden or boolean-subtracted) so the rendered output reads the section through the volumes. Section materials use the existing backface-shadeless preset (the `solid section` workflow already used for stratigraphic sections in Blender). The Grease Pencil annotations layer rides on top of the rendered raster for hand-drawn callouts or stratigraphic boundaries the modeller wants to overlay on the section.
  • **Raster resolution selector** — operator pop-up dialog with three named presets (`Screen 1×`, `Print A3 300 DPI`, `Print A2 300 DPI`) plus a `Custom` slot. The selector writes the chosen resolution back to the plate's PropertyGroup (`scene.em_tools.layouts[plate_name].resolution_w` / `_h`) so subsequent re-renders of the same plate reuse it without re-asking.
  • **Metric scale overlay** — a procedurally-generated scale bar baked into the rendered image. Length picked by heuristic (1/8 of the rendered viewport's horizontal extent, rounded to the nearest 0.1 / 0.5 / 1 / 2 / 5 / 10 metre tick). Drawn in the rendered output (compositor node group) so it lives in pixel space, immune to subsequent crops. Configurable position (4 corners + center-bottom); default center-bottom.
  • **Sea-level (quota s.l.m.) horizontal lines overlay** — for each prospetto / sezione, a configurable set of horizontal guide lines tagged with their elevation in metres above sea level. Elevation source resolution order: (1) `scene.em_tools.geo.elevation_m` if the modeller has set it via the Georeferencing panel (DP-56); (2) `GeoPositionNode.altitude` from the active graph (passive-mirror in 1.6, canonical in 1.7+); (3) explicit user override via the operator dialog. The lines are drawn in the same compositor pass as the metric scale.
  • **Label Tools panel** (already in 1.5; lives under Visual Manager — see `visual_manager/label_tools.py`). DP-34 reuses it untouched for the in-viewport label workflow: the user creates labels for selected proxies via the active camera, the labels park in `Layouts/<plate_name>/labels/` and ride into the rendered raster as overhead text. The plate operator wires the active plate camera into the Label Tools' active-camera slot so the modeller doesn't have to switch contexts.
  • **Grease Pencil annotation layer per plate** — each `Layouts/<plate_name>/` gets a Grease Pencil object as an annotation surface, sitting at the cutting plane's depth. Use cases: hand-drawn contour lines for the section's stratigraphic reading; arrowed callouts that the metric scale + labels can't express; informal sketch overlays for in-team drafts.
  • **Compositor node group `EM_Plate_Overlay`** — packaged with the addon, takes the rendered image and the plate's PropertyGroup as inputs, emits the final raster with scale + sea-level lines + (optional) frame border + (optional) metadata stamp (site name, plate name, scale ratio, date).
  • **Plate registry on the scene** — `scene.em_tools.layouts` PropertyGroup holds one `LayoutPlate` entry per Layouts sub-collection, with: `plate_name`, `kind` (`prospetto` | `sezione` | `plan` | `custom`), `cutting_plane_a`, `cutting_plane_b` (the two pick points), `resolution_w/_h`, `scale_position`, `sealevel_lines` (list of float metres), `last_render_path`.
  • **Future Phase 2 — articulated cutting planes (`sbalzettamenti`)** — instead of two pick points, an ordered list of N pick points forming a polyline cutting plane (each segment becomes a sub-camera with its slice of the wall). The rendered output is the horizontal concatenation of the N sub-renders. UI: a list of breakpoint markers in the Layouts panel; modify-in-place via drag in the viewport with a custom gizmo. Out of scope for the 1.6 MVP — flagged here so the storage model (`cutting_plane_a` / `cutting_plane_b` becomes `cutting_plane_points: list[Vector]`) is forward-compatible from day one.
  • **Planimetrie are out of scope.** The reasoning: BlenderGIS (already integrated via the EM Tools 1.5 / 1.6 georeferencing pipeline, DP-56) already produces georeferenced plan views from the survey data — orthographic top view, true scale, world coordinates aligned. Re-implementing planimetria authoring inside EM Tools would duplicate work without adding archaeological value. The Layouts collection accepts plate `kind=plan` for completeness (the modeller can register a BlenderGIS-driven top-view render as a plate) but DP-34 does not provide a `plan authoring operator`. If a future need surfaces — composite plans with overlaid stratigraphic graphs, for instance — that becomes a follow-up DP.

Key Study

Sarmizegetusa — the first reconstruction project that drove this requirement set: the Romanian-Polish team needed a reproducible workflow for publishing prospetti and sezioni of the Dacian sanctuary across multiple publication outlets, each requesting different scales and resolutions. The reproducibility (re-render the same plate at A3 300 DPI for the catalogue, then re-render the same plate at A2 600 DPI for the panel) is what pushed the design from "set up the camera by hand each time" to "plate is a first-class scene object".

Notes

Original 1-line stub expanded against the user's June 2026 brief on prospetti / sezioni. Status moved from `planned` to `in-dev` because the data substrate is already shipping: the renamed `Layouts` Blender collection (DP-34's per-plate home), the Label Tools panel under Visual Manager, the backface-shadeless section material, and the Grease Pencil-based contour pattern are all live in 1.6.0-dev.8. What is still missing is the *guided* operator that automates the two-point cutting-plane setup + raster output with scale + sea-level overlays. That's the next concrete deliverable on the 1.6 cycle. Open decisions to thread at review: (1) cutting plane vertical extent — infinite (entire scene height) or clamped to a configurable Z range (so a prospetto of a wall doesn't render the bedrock 20m below)? Proposal: clamped, with smart defaults from the scene's bounding box and a manual override in the operator dialog. (2) Sezione 'in front of the plane' policy — boolean-subtract the geometry, hide it via a per-camera holdout mask, or use a backface-shadeless material that fades it out? Proposal: backface-shadeless by default (non-destructive, matches the existing stratigraphic-section pattern) with a boolean-subtract option for publication-quality output where the cut volume needs to read as filled. (3) Sea-level lines source priority — see the component description; needs review against DP-56's georef panel UX so the modeller doesn't end up with two sources of truth for the site's elevation reference. (4) Where the plate metadata lives in the graph — proposal: each plate becomes an `em:LayoutPlate` node typed as `crm:E22_Human-Made_Object` (the plate is a derivative artefact), with `em:depicts_section_of` / `em:depicts_elevation_of` edges to the USVs it cuts through. This makes the plate citable, audit-trail-friendly, and exportable to Heriverse as a published artefact. Forward-compat decision; the 1.6 MVP can ship without it and add the graph node in a 1.7 follow-up. (5) Raster output storage — proposal: `<project>/renders/layouts/<plate_name>_<timestamp>.png` plus a thumbnail in `<project>/renders/layouts/_thumbs/`. The plate's `last_render_path` field stores the most recent absolute path; an `RM Doc`-style hypergraph link could promote the rendered plate to a Document Node (DP-47) so the rendered output gets paradata in its own right. (6) Articulated cutting planes (the user's `sbalzettamenti`) — Phase 2, but the data model should be forward-compatible from day one. (7) Sarmizegetusa case study — confirm with the team which prospetto / sezione panel from the published material gets used as the canonical DP-34 illustration once the MVP lands. Cross-refs and adjacencies: DP-56 (Georeferencing Pipeline) — single source of truth for the EPSG + sea-level baseline that DP-34 reads when drawing the quota s.l.m. overlay; DP-46 (Proxy Box Creator) — the proxy volumes that the section cuts through; DP-50 (Surface Areale System) — uses the same backface-shadeless material pattern this DP reuses for sezioni; DP-04 (Landscape and Urban Surfaces Reconstruction) — landscape proxies as the substrate that horizontal sections cut through; DP-67 (Neutral SU empty-volume rendering) — sections through USNV volumes need the empty-volume rendering convention; DP-47 (RMDoc Manager) — once a plate ships, it can be promoted to a Document Node via the RMDoc hypergraph link, picking up author/license/embargo paradata via DP-32; DP-43 (Group Nodes — TimeBranch / Activity / Paradata) — a plate can be associated to a specific Activity or TimeBranch so a publication can present 'state at construction phase vs state at destruction phase' as two plates of the same wall.