RFC: read the PDF layer tree — Optional Content Groups as first-class geometry filters

[QuisutDeus1]

The heuristics exist to recover information the file already states

classifyHatchSegs in web/src/lib/oneclick.ts is a wall of tuned constants — HATCH_MIN_RUN, pitch-regularity bands, SPAN_PROTECT_RATIO, the filled-not-stroked poché exemption added after the VA plan drew its walls as solid shapes — and its entire job is to guess which segments are boundary and which are pattern.

A construction document exported from Revit, AutoCAD, or Archicad usually says so outright. PDF Optional Content Groups carry the CAD layer structure through the export, most often on the AIA CAD Layer Guidelines convention:

A-FLOR-OTLN    floor / room outlines
A-FLOR-PATT    finish hatch patterns
A-WALL-FULL    full-height partitions
A-WALL-PRHT    partial-height partitions
A-DOOR         door swings and tags
A-ANNO-*       text, dimensions, leaders
S-*            structural

OpenTakeoff reads none of it. grep -r optionalContent web/src mcp/src returns zero hits. Every path is flattened into one undifferentiated 1-bit mask and then partially un-flattened by heuristics.

Where that costs us

• Hatch classification is guesswork on sheets that don't need any. Fine-pitch tile grids still defeat the classifier (the bundled demo plan's toilet rooms — see RFC: make One-Click Area genuinely great — face extraction, gap tolerance, confidence, and a scored benchmark corpus #60). On a layered sheet, A-FLOR-PATT is the answer, stated by the file, requiring no inference.
• Every new drafting style risks a new constant. That's the deepest problem in RFC: make One-Click Area genuinely great — face extraction, gap tolerance, confidence, and a scored benchmark corpus #60 and layers are the largest single class of cases that stop needing tuning at all.
• Structure can't be excluded. Columns inside a room are on S-COLS, not the floor layer, but the mask can't tell.
• Demolition linework is indistinguishable from new work. A-WALL-DEMO traced as a boundary is a wrong number produced confidently.

The work

1. Capture the OCG id during extraction. pdf.js exposes layer membership through marked-content operators in the operator list (beginMarkedContentProps carrying an OCG ref) and the id→name/visibility mapping through page.getOptionalContentConfig(). extractVectorGeometry already walks the operator list for constructPath; it emits a layerId alongside the existing meta bits and nothing else changes. The marked-content stack nests — this is a small state machine, not a lookup.

2. A layer-name normalizer. New pure module, web/src/lib/layers.ts: raw layer name → { role, confidence } where role is boundary | finish-pattern | annotation | structure | demolition | unknown. The AIA table is the easy half. The real work is the field:

• xref-prefixed names (ARCH-FLOOR|A-WALL-FULL)
• vendor dialects (Bentley, Archicad, Vectorworks)
• truncated and renumbered variants (A-WALL-1, WALL, A-WALL FULL HT)
• the degenerate case where everything sits on layer 0
• non-English layer names

This module is where the RFC actually lives. It's self-contained, pure, table-driven, and testable without any geometry background.

3. buildMask consumes roles instead of guessing. When a page has usable layers: boundary roles go in hard, pattern/annotation/demolition are excluded outright, structure becomes a subtractive hint, and classifyHatchSegs runs only over unknown. When a page has no layers, today's path runs completely untouched. This is a short-circuit, never a replacement — a regression on unlayered sheets is a failed PR.

4. Surface it. sheet_info (MCP) returns the layer table. one_click and detect_rooms accept an optional layers: { include?, exclude? }. The canvas gets a layer visibility panel — an estimator toggling A-FLOR-PATT off to see the room boundary underneath is worth shipping on its own merit, independent of the engine work.

5. Provenance. A trace bounded by declared layers is categorically stronger evidence than one bounded by a pitch heuristic. layer_bounded: true rides the contribution.v2 wire and feeds the confidence field #60 calls for.

Known hard parts

• pdf.js's OCG plumbing is thinly documented and the marked-content stack nests.
• Visibility state matters: a path can be present-but-hidden in the default config. Honor it or you will trace demolition.
• Non-conforming layer names are the majority of real sets, not the exception.
• Some exporters flatten layers entirely. The fallback must be invisible, not a degraded mode with a warning.

Finish line

Against the benchmark corpus (#60): layered fixtures show a measurable IoU floor lift and a refusal-rate drop; unlayered fixtures show exactly zero delta. Both numbers reported in the PR, per fixture.

Explicitly out of scope

Native DWG and IFC ingestion. Both need non-JS dependencies and break the client-only architecture. That's a real lane and a separate decision — it is not this issue, and PRs that start there will be redirected.

Constraints

oneclick.ts and layers.ts stay pure — no DOM, no React. The MCP server runs the identical engine headlessly. Refusal over guessing. New failure modes ship with named regression fixtures.

[QuisutDeus1]

Design comment before code, per house rules. I've verified the pdf.js plumbing against the pinned build (4.10.38), and the state machine is exactly as sketched above — with the arg shapes now confirmed:

What the worker actually emits. `getOperatorList` produces `beginMarkedContentProps` with args `["OC", data]` where `data` is `{type: "OCG", id}` (the objId string), an OCMD form (`{type: "OCMD", ids[], policy}` or a parsed visibility `expression`), or `null` on a malformed property. `beginMarkedContent` (no props) and `endMarkedContent` ride the same stream, and Form XObjects carrying `/OC` get the same op pair wrapped around their body — so ONE nesting-aware stack over the linear op walk covers page content and XObjects alike. The id→(name, visibility) mapping lives on the API side via `getOptionalContentConfig()`, which is the split this repo already lives by: the engine stays pure and gets the mapping handed in.

Extraction. `extractVectorGeometry` gains the marked-content cases in its existing op switch: push the OC id (OCG id; single-id OCMD; null for everything else — including `beginMarkedContent`, which still must push for balanced pops), pop on `endMarkedContent`, attribute each emitted segment to the nearest enclosing OC id. Output: a per-segment layer index (`-1` = none) into a per-sheet layer-id table. An opList with no marked content produces an empty table and all `-1` — byte-identical mask downstream, which a regression test asserts.

`layers.ts`. Pure, table-driven: raw name → `{role, confidence}`, roles as specced. First table: the AIA discipline-code core, xref-prefix stripping (`ARCH-FLOOR|A-WALL-FULL`), separator/truncation tolerance (`A-WALL FULL HT`, `WALL`), layer-0/degenerate → `unknown`. The field dialects grow by fixture, not by speculation.

`buildMask` consumes roles as a short-circuit. boundary → hard, always (no `classifyHatchSegs` vote); finish-pattern / annotation / demolition → excluded before plotting; hidden-in-default-config → excluded regardless of role (or we trace demolition); structure → hard (a column edge should stop a flood; subtractive refinement can come later); `unknown` → today's path, untouched. No layers on the sheet → today's path, untouched, and that's a tested invariant, not an intention.

Surfacing. `sheet_info` returns the layer table (id, name, role, confidence, visible, seg_count); `one_click` / `detect_rooms` take `layers: {include?, exclude?}`. Provenance: `layer_bounded: true` on a trace whose boundary segments all carry boundary-role layers.

Fixture. Neither demo PDF carries OCGs, so a generated layered fixture ships with its generator: walls on `A-WALL-FULL`, a tile grid on `A-FLOR-PATT`, text on `A-ANNO-TEXT`, a demo wall on `A-WALL-DEMO` hidden in the default config. Conformance drives the whole loop against it both ways (with layers honored, and with `exclude` overriding).

Finish line unchanged: layered fixtures show the lift, unlayered fixtures show exactly zero delta, both numbers in the PR.

[QuisutDeus1]

Phase 1 is merged (#141 — the extraction, lib/layers.ts, the buildMask short-circuit, sheet_info.layers, one_click/detect_rooms layers filters, layer_bounded provenance, and the generated layered fixture). The discriminator numbers from the PR: heuristics trap the tile-grid flood in one of nine cells (~69 SF); the stated layers free the whole 625 SF room; unlayered fixtures show exactly zero delta (byte-identical mask, asserted).

Staying open for phase 2: the canvas layer-visibility panel (browser-side role plumbing), corpus-wide IoU once #60's benchmark lands, and name-table dialect growth by fixture.

[QuisutDeus1]

opentakeoff-mcp 0.9.7 is on npm — sheet_info.layers and the layers {include, exclude} filters on one_click/detect_rooms are now in bare npx opentakeoff-mcp (release: https://github.com/Kentucky-ai/opentakeoff/releases/tag/mcp-v0.9.7).