Future work items from Alex (2026-09-19), with initial technical framing. None of these are solved; this doc records the problem statements and candidate approaches so design can start from something concrete.
A recurring theme: several of these introduce known, directional bias
(overestimated air volume, overestimated floor area). The project's answer is
the same everywhere — don't pretend the bias is zero; measure it, attribute it
to the convention that caused it, and report it. The validation battery
(validate/) is the natural home for these "convention bias" numbers.
Added 2026-10-19. What 1.0 means for matchline: the first version a professional can lean on. It is a stability and validation milestone, not a feature milestone: the seven hard problems in Part I stay post-1.0 features, except the two pieces already promised by decisions (item 1's validation check and item 4's absorbed-area accounting), which land through the convention report gate below.
- A documented, versioned public API (Python and CLI) with semver and a deprecation policy, so a user can pin to it.
- Every generated model simulates: an end-to-end EnergyPlus gate on CI.
- Bad inputs fail loudly: coded, actionable diagnostics instead of bare tracebacks, plus a documented IFC flavor coverage matrix.
- Stated performance budgets (wall-clock and memory) on a reference large model, tracked in CI so regressions surface before release.
- Published accuracy numbers per slice from real licensed buildings (#748), with the convention report attached, so claims are measured, not asserted.
- Versioned schemas (canonical model, review artifacts, telemetry) with migration guides for every breaking change.
- Docs to standard: API reference, quickstart, tutorial, upgrade guide.
- A stated and tested support matrix (Python versions, Linux/macOS/Windows).
Each gate has an issue with acceptance criteria. Gates 1-6 and 8-9 can start now; the benchmark gate (7) stays blocked on licensed building data (#748).
| # | Gate | Issue |
|---|---|---|
| 1 | Public API surface frozen and documented | #1159 |
| 2 | End-to-end simulation gate on CI | #1160 |
| 3 | IFC frontend robustness battery | #1161 |
| 4 | Performance and memory budgets | #1162 |
| 5 | Platform and Python support matrix | #1163 |
| 6 | Schema versioning and migration guides | #1164 |
| 7 | Real-building benchmark numbers published | #1165 |
| 8 | Convention report artifact | #1166 |
| 9 | Docs to standard | #1167 |
Kept out of the 1.0 bar so the freeze stays about stability: Part I items 2 (sloped roofs), 3 (skylights), 5 (shading surfaces), 6 (per-space constructions) and the R1/R2 research tracks. They remain the 1.x feature roadmap exactly as Part I frames them. The convention report (gate 8) is the one Part I piece pulled in, because "measured bias, never silent" is already the project's stated answer and the report is what a 1.0 user audits.
Chosen approach: keep thick walls internally (per convention at export).
Rationale. The canonical model stores wall thickness explicitly (BEMElement.thickness_m
and BimElement.material_layers); surfaces are derived per convention at export
time. This approach:
- Aligns with the existing schema (wall thickness is already a first-class field).
- Solves the BIM path analytically:
IfcMaterialLayerSetgives true per-layer thickness — no convention needed, just extract and store. - Enables the
convention_biascheck: validation computes the volume delta between interior-face and exterior-face derivations rather than hand-waving a fixed percentage. - Is future-proof: any convention (interior-face, centerline, exterior-face) can be derived at export without re-extracting from the source.
Drawing-path implementation note. The drawing path must extract wall thickness from plan geometry (wall-thickness pairs, dimension annotations, or legends). This is an implementation detail; the architectural decision is settled.
Validation: add a convention_bias check reporting volume delta between
interior-face and exterior-face derivations per level.
Rejected alternatives. "Decouple area from volume at export" was considered but rejected because it requires two geometry representations in the export format (gbXML/EnergyPlus space volume field) rather than one canonical form, and it kicks the convention question to the exporter rather than owning it in the canonical model.
Complex roofs (hips, valleys, dormers) need the same treatment as the area-budgeted wall simplifier — but slope drives solar gain, so a pure geometric area budget is insufficient.
Candidate approaches:
- Extend
geometry_simplify.pywith a roof mode: merge near-coplanar facets within an angle tolerance, replace multi-facet hips with equivalent single-slope planes. - Error metric must be solar-weighted, not just geometric: preserve orientation-weighted aperture (area × cos(incidence) integrated over representative sun positions), not just m².
- Validation: add a solar-aperture conservation check alongside the area budget.
Schema, extraction, and tests for roof glazing.
Candidate approaches:
- Extend
SpaceOpeningwithcategory="skylight",host="roof", plus tilt/azimuth from the roof plane. - gbXML has native
Skylightelements; IFC viaIfcWindowwith appropriate predefined type. Both exporters need the new path. - Daylighting: skylights drive top-lighting zones — different geometry than
the sidelighting rules in
elevation_windows.py(roughly: floor area under skylight + perimeter spread by ceiling height). - Validation: skylight area ≤ host roof area per space; skylight count reconciles against roof-plan annotations.
- Tests: synthetic roof with known skylight layout, same pattern as the elevation-window defect-injection tests.
Not every enclosed polygon is a room. Current practice: split duct shafts between adjacent spaces; merge elevators/janitor closets into the adjacent corridor. Both practices inflate space floor areas (affects LPD, loads).
Candidate approaches:
- Classification first. Signals: presence of a room-number label (rooms have them; shafts/closets often don't), polygon area thresholds, aspect ratio, labels on the mechanical plan (a polygon called out as a shaft on mech but unlabeled on arch is a strong signal), door count (a polygon with no door swing is suspicious).
- Absorbed-area accounting. Every merge/split records where the area went:
"corridor C-101 absorbed 4.2 m² from closet J-3 and 1.8 m² from shaft split."
Stored as provenance on the space. Then:
- LPD and loads can be reported both ways (as-drawn room vs. as-modeled space),
- the validation battery gets a conservation check: absorbed areas must sum exactly to the unassigned-polygon areas — no square foot vanishes.
- Shaft splitting needs an adjacency graph (shared wall segments between
polygons) — a natural extension of the wall-segment work in
link/. - Open question: should shafts be split by adjacent wall length weighting, or is there a better rule? Worth asking a mechanical engineer, not guessing.
Balconies, fins, and other projections matter for BEM as shading.
Candidate approaches:
- Detection: projections beyond the exterior wall face on plan/elevation. (CMP Facade already labels balconies as class 7 — a training signal exists.)
- Generate shading surfaces with depth = projection distance from the facade;
attach to host wall/window. gbXML supports shading surfaces natively;
EnergyPlus via
Shading:Zone:Detailed. - Validation: every shading surface must reference an adjacent host wall/window; warn on shading with no host (likely a detection error).
- Keep separate from the envelope area budget — shading is not envelope.
Different wall types on different envelope portions; the correct overall U-value is per space, area-weighted over its wall segments.
Candidate approaches:
- Schema: every exterior wall segment carries a
construction_id; each space's envelope references its segments (segments already exist inlink/— this extends them). - Per-space area-weighted U-value: Σ(Uᵢ × Aᵢ) / ΣAᵢ, computed in the takeoff layer and exported per space.
- Detection: wall-type legends on elevations are usually hatch patterns — a texture/pattern-classification problem per wall segment, analogous to the symbol legend-learning idea in the detector plan.
- Validation: every exterior wall segment has exactly one construction; every construction id resolves in the schedule; per-space weighted U-value is recomputed independently in the check (don't trust the rollup).
- Unresolved: how wall-type transitions within a single wall run are marked on real drawings (notes? detail callouts?) — needs real-sheet observation before the detector design is fixed.
- Items 1 and 4 both create measured overestimation. The unified answer is a "convention report" emitted with every export: volume bias %, absorbed-area table, area-budget drift — all in one place, all auditable.
- Items 2, 5, 6 all need the wall/roof segment as a first-class entity with
attributes (construction, tilt, host). The segment work in
link/is the foundation; it should be promoted from an internal detail to a schema-level concept. - Item 4's classifier is the only one here that needs real labeled data before design can start; the rest can be prototyped synthetically.
The drawing pipeline and a BIM pipeline should converge on the same canonical model. Alex's point: the surface-count reduction and validation logic are needed in BIM→BEM just as badly, and the industry hasn't handled it well.
Candidate approaches:
- Two frontends, one core. The architecture already has the right shape:
source-specific extraction feeding the source-agnostic canonical model
(
building_model.py), then shared downstream (simplify → validate → export). IFC becomes a second frontend: parse with IfcOpenShell (already vendored for export — reading is the same library in reverse) and populate spaces, levels, openings, constructions. Everything downstream is reused unchanged. - The simplifier is the shared asset. BIM geometry is often more over-faceted than drawings (curtain-wall mullions as individual surfaces, every stud modeled). The area-budgeted simplifier applies directly, and the 1–5% budget gives BIM→BEM something it lacks today: a stated, checked fidelity bound instead of silent decimation.
- The validation battery is arguably more valuable on BIM input. BIM→BEM failures are silent: unenclosed zones, sliver spaces, dropped space boundaries. Area/volume conservation and closure checks catch exactly these.
- The hard part is space boundaries.
IfcRelSpaceBoundaryquality varies wildly in the wild — this is where Autodesk and others struggle too. Apply the project's review-queue philosophy: low-confidence boundary mappings get flagged, never silently accepted or silently dropped. - Design the frontend in tiers so space boundaries are optional, not
load-bearing (Alex's question, 2026-09-19):
- Tier 0 — no boundaries needed.
IfcSpaceentities carry identity (name/number) and their own 3D geometry.IfcWall/Slab/Roof/Window/Doorcarry geometry, type info, and material layer sets.IfcOpeningElement+IfcRelVoidsElement/IfcRelFillsElementrecover window/door placement in walls.IfcRelAggregates+IfcRelContainedInSpatialStructuregive the storey structure. Tier 0 alone already delivers takeoffs (wall/window/door areas), the room list, and the envelope element inventory. - Tier 1 — geometric inference. Space↔element adjacency via proximity/clash queries (walls intersecting the space solid's expanded boundary); interior-vs-exterior classification via outward ray tests. Every inferred association carries method + confidence + provenance, and ambiguous cases go to the review queue. Audited inference, not perfect inference.
- Tier 2 — authored boundaries as cross-check. When
IfcRelSpaceBoundarydoes exist, treat it as untrusted input: run Tier 1 independently and flag disagreements for review. Inferred-vs-authored agreement becomes a validation check rather than a load-bearing dependency.
- Tier 0 — no boundaries needed.
- Bonus: IFC solves the wall-thickness problem analytically.
IfcMaterialLayerSetgives true per-layer thickness — interior and exterior faces are derivable, not convention-guessed. This feeds roadmap item 1 directly: the "derive faces per convention at export" design gets real thickness data on the BIM path. - Thermal properties remain a gap on both paths.
Pset_MaterialThermalis usually absent in practice; both frontends need the same material→property lookup table. - Testing bonus: IFC round-trip gives ground truth for the drawing pipeline. Where both an IFC and drawings of one building exist, the two frontends should produce models that agree within the validation tolerances — a cross-frontend consistency check.
- Ecosystem note: abstract.build (Simon's company) does BIM data analysis for thermal simulations — adjacent and complementary, not competitive. They start from BIM; wisard-bem starts from drawings and could start from BIM. Worth showing Simon once the IFC frontend exists; the validation battery and simplifier are the components most likely to interest him.
These sit alongside the numbered items above: time-boxed research spikes whose outcomes decide which detection technology we productionize. They are labelled R1/R2 (not numbered) so they merge cleanly next to the numbered roadmap items.
Context (2026-09-19): Kamai (kamai.io) is an Israeli startup doing exactly this — proprietary in-house "geometric models" that read vector geometry directly from PDF/CAD drawings (no rasterization, claimed sub-mm measurement), return typed structured output (rooms, wall polygons, openings with widths/relations/tags like "D-01"), and expose it as a public REST API. Their approach validates the direction; this track is to build our own reproducible, auditable version and know when it beats the raster path.
Candidate approaches:
- Know the input alphabet first. Survey what a plan sheet actually exposes as vector primitives (lines, arcs, polylines, hatches, positioned text) via parsing libraries (pdfplumber/pypdf for PDFs, ezdxf for DXF/DWG). Decide the model only after the primitive inventory is understood.
- VecFormer as the leading learned candidate. VecFormer (NeurIPS 2025) is a transformer over vector line primitives rather than pixels — potentially both more accurate and more auditable than raster detectors on vector PDFs. Evaluate it as the vector-native counterpart to YOLOv11+SAHI.
- Spike prototype. Parse vector line primitives from one real PDF plan sheet; extract entities (walls as parallel-line pairs, openings as gaps in runs, rooms as closed loops); compare extraction accuracy head-to-head against the raster YOLO+SAHI path on the same sheet. Time-boxed.
- Benchmark target. Replicate Kamai's AEC-Geometric-Bench protocol: object F1 at IoU 0.50 across doors/windows/fixtures, 8 classes. Accuracy target: meet or beat Kamai's published 0.929 with a reproducible, auditable vector-native pipeline.
- Licensing caveat. The bench data is CC BY-NC 4.0 — usable for evaluation but not for training weights that will be commercially distributed; NC-trained weights stay quarantined per the legal gating already flagged. Also, Kamai's number is vendor-published on vendor-owned data (bias openly disclosed); reproduce with their public 15-sheet scorer, and report our numbers on the same protocol plus our own drawing-set results.
Spike outcome (2026-10-15, #973). Real legacy plan sheets expose rich vector primitives (8k+ lines on a single plan page), and rooms parse directly from them (flood-fill prototype: 22 and 31 plausible rooms on two plan pages). The shipped vector pipeline's blocker on legacy sets is sheet routing, not extraction (no sheet number in 2006-era title blocks; follow-up #1016). VecFormer stays deferred: it is a symbol spotter, not a wall parser, and would enter through the R2 DetectionProvider interface if ever needed. Full write-up in docs/r1_vector_spike.md. Decision: raster YOLO+SAHI stays the production path; vector-native geometry stays an open research track, unblocked by the routing fix; the meet-or-beat-0.929 F1 target waits on a labeled evaluation set.
Context: detection backends are currently hard-wired (YOLOv11+SAHI). If R1 shows a vector-native path wins, or a third-party API becomes worth paying for, swapping backends must be a config change, not a rewrite.
Candidate approaches:
- Define the provider contract. A
DetectionProviderinterface that takes a sheet (raster and/or vector) and returns typed entities with geometry, class, confidence, and provenance — the same schema the canonical model already expects — so simplify → validate → export stay backend-agnostic. - Backends behind the contract: (1) the current YOLOv11+SAHI raster detector; (2) the R1 vector-native prototype; (3) third-party APIs — evaluated candidates named below, with Kreo as the only verified Kamai alternative and an open-source self-hosted option.
- Evaluated third-party candidates.
- Kamai — cost-blocked for now. Self-serve API access starts at the Contractor tier ($800/mo, ~800 sheets, ~$1–2/sheet) — too expensive for a quick evaluation. Evaluate Kamai integration only if a free trial or partner evaluation access is obtained (their stated go-to-market is B2B2B/partner sales; a sales conversation is the realistic path to eval access). In the meantime, the R1 track doubles as our own research into what their geometric models do.
- Kreo Software — Auto Measure API (https://www.kreo.net/features/api) — the only other verified public drawing-in → structured-geometry-out REST API. Accepts PDF/DWG/DXF/DWF/PNG/JPG/TIFF; returns walls (ext/int), doors, windows, rooms/areas (GEA/GIA/NIA) as JSON with per-object pixel contours, OCR text, area/perimeter/length/thickness. Example pricing ≈$0.85/request (~$670/mo at 500 requests); sandbox + limited free requests via sales. Unverified: data retention, privacy/DPA terms, hosting region, and on-premise options — resolve before any production use.
- FloorPlanAnalyzer (https://github.com/mageaustralia/FloorPlanAnalyzer) — open-source YOLOv8 + OCR, self-hosted (self-hosting solves the privacy/on-prem story outright). Accuracy on commercial construction drawings unverified; license terms unverified.
- Excluded (with reason). Togal.ai: no verified public/self-serve detection API (partner-managed integrations only). Rasterscan: an API and claimed on-premise exist, but a paying customer reports API failures with no support response — too risky for now. magicplan/CubiCasa: capture workflows (phone scans), not arbitrary-drawing parsers. Autodesk ACC Takeoff, STACK, Bluebeam: public APIs exist but cannot trigger AI detection headlessly (read/file-management APIs only).
- Provider-agnostic conformance. Run the same AEC sheets through each backend under the same F1-at-IoU-0.50 protocol; report per-backend deltas in the audit artifact. Backend disagreement becomes a cross-check, not just a number.
A categorized backlog from an eight-persona review (legal, marketing, product design, project management, software architecture, MEP engineering, energy modeling, incumbent vendor) on 2026-09-19. These are not sequenced or numbered: they are directions to pull into the numbered roadmap as priorities crystallize. Items marked with multiple-persona support independently came up in more than one review.
- Professional-use disclaimer and E&O framing ★
- Stampable, dated sign-off report with source/revision traceability ★
- Versioned data-contribution agreement for the flywheel ★
- Training-data license ledger and quarantine for noncommercial data/weights ★
- CLA or DCO for code contributions
- Privacy/security-sensitive-building policy and guaranteed local-only mode
- GUI/service terms governing liability and data retention/deletion
- Defensive publication of novel methods
- Legal review of professional-licensure / "practicing engineering" risk
- Drawing-set ingestion via cover-sheet index/title-block parsing
- Revision/addenda tracking and takeoff diffs
- Match lines, split sheets, and enlarged-plan deduplication
- Per-project legend/tag/convention learning ★
- SD/DD/CD design-phase awareness
- Explicit area definitions: GSF, BOMA rentable, program/assignable
- Worst-first, keyboard-first review queue with bulk actions
- Correction history, undo, and revert-to-automatic output
- Loud, specific failure modes for bad inputs
- Progressive takeoff mode vs full-BEM mode
- Export package: model + one-page trust report + editable decisions file + share-back preview ★
- ASHRAE 90.1 Appendix G perimeter/core thermal zoning
- Below-grade detection and correct ground/outdoor boundaries
- Space-use classification to cited load/schedule templates
- Versioned construction library with cited U-values; never fabricate missing values
- Blocking OpenStudio importer round-trip gate
- Inter-story surface matching and atrium/shaft consistency
- Split rooms at Appendix G block lines, pieces joined by air walls (#638)
- Multi-storey gbXML/IFC export (#639)
- Atria handled automatically, not just flagged for review (#640)
- Walk-out basements: exterior walls split at grade, not just flagged for review (#641)
- Mechanical schedule parsing and system-type classification
- Engineering reconciliation gates and discipline-specific accuracy bars
- Lighting controls and control zones
- Riser/one-line topology parsing
- First-class system entities linked to rooms
- Plumbing fixture takeoffs and service-water-heating inputs
- Architect-facing plan-vs-schedule coordination QA
- Positioning: "auditable extraction, not AI magic"; feed incumbents rather than replace them
- Real-building benchmark on 3–5 commercial buildings ★
- Five-minute demo, bundled sample project, results gallery ★
- Quiet beta with friendly firms before public launch
- Community presence through Unmet Hours, LinkedIn, IBPSA/ASHRAE
- Visible monthly flywheel/model changelog
- Rename before public launch because WiSARD is not the production detector (done: production docs name the YOLO detector; the one surviving "WiSARD" in hvac_trace.py is jesse.py's research classifier inside its cascade, noted in its docstring — #979)
- Revit/AutoCAD plugin
- Enterprise trust package: SSO, audit logs, isolation, SOC 2 story, air-gapped/on-prem mode
- Standalone BIM import health score
- Platform-risk hedge: keep IFC and web GUI first-class
- Deliberate open-core commercial model
- Publish validation checks as an industry benchmark
- Define Monday validation exit criteria before fine-tuning
- Define v0.1.0 scope and release cadence
- Maintain an in-repo risk register
- Add a dependency/sequencing map
- Add explicit non-goals and parked ideas
- Set a review-bandwidth budget, maximum PR size, review cadence, and SLA ★
★ = raised independently by multiple personas — highest signal.
Explicitly not goals for v0.1.x (see docs/release.md for scope and
cadence; the dependency map lives there too):
- matchline does not run energy simulations. It reads drawings and IFC models and exports gbXML and IFC4; the simulation itself stays with OpenStudio/EnergyPlus. Zone load inputs are set before any HVAC sizing decision is made downstream.
- WiSARD never becomes the production detector.
jesse.pyis a deterministic research asset; production symbol spotting is the YOLO pipeline indetector/. - No raster-to-walls from sheet images. The image input yields symbols and takeoff only, stated honestly wherever it appears.
- No second PDF library. pypdfium2 is the only PDF entry point; AGPL options (PyMuPDF) stay rejected.
- No noncommercial data in shipped artifacts. NC / copy-left benchmark data and weights stay eval-only and quarantined (#751).
- No automatic releases. Releases cut by hand from
developwith green CI and release notes that match reality. - No unreviewed merges for higher-risk changes. The duck review and green CI gate everything; ambiguous or high-risk changes wait for personal review regardless of CI.
Parked ideas: deliberately unstarted, listed here so they do not get re-discovered as gaps. Revit/AutoCAD plugins, the enterprise trust items (SSO, audit logs, SOC 2 story, air-gapped mode), the standalone BIM import health score, and the open-core commercial model all sit under Strategy above; they are future-facing by design. Nexus-style infrastructure projects and anything outside drawings/IFC-to-BEM scope stay out of this repo entirely.
From Alex (2026-10-15): the model's value depends on the user's ability to check it, fix it, and teach us from it. Three directions — see the model, fix the model, learn from the user. Not sequenced; each slice gets its own numbered issue with acceptance criteria when pulled into the roadmap.
The review queue is a list; a wrong wall is a shape. The user should be able to look at the final simplified model and find where matchline may have made mistakes before trusting the numbers.
- Read-only first. Pan, rotate, and zoom; isolate one level at a time; a top-down orthographic view per level to check space layout against the plan. Toggle overlays: floor plans and elevations registered to the model, MEP takeoffs, and traces.
- Render from the canonical model the export writes, never a second geometry copy. A viewer that lies is worse than no viewer. The share-back preview in the export package and this viewer should share one render core.
- Comparison is the feature: plan-over-model alignment exposes the mistakes (a shifted wall, a merged room, a door called a window), and per-element confidence heat-mapping points the eye where errors are most likely.
- Open question: self-contained HTML (same constraint as the share-back preview) vs matchline-ui. Decide when the first slice is pulled.
Finding a mistake is half the loop; fixing it in place is the other half.
- Start with the cheap, unambiguous edits: rename a space, reclassify a door as a window (and the reverse), merge or split spaces. Moving an interior wall is the stretch goal and needs a designed geometry-edit model first, not a quick add.
- Every correction writes back through the existing decisions.json workflow (--confirm/--reject/--apply), lands in the correction history with before/after values, source, and timestamp, and surfaces in the review queue. The viewer never forks a private copy of the model.
- A correction is provenance, not just a patch: what the automatic result got wrong is exactly the signal the detector wants and the telemetry below should carry.
The flywheel needs data from users, and every byte we ask for is friction.
- Minimum, not maximum. Candidate metrics: per-class detection confidence distributions, correction counts by type (what users fix most is what the detector should learn), which validation checks fail most often, binned aggregate areas and counts, pipeline stage outcomes and timings. Explicitly excluded: geometry, labels, names, coordinates, sheet images, anything that identifies a building or a firm.
- Strip at source. The emitter can only produce fields on an allowlist, and a test proves the payload carries no building-specific data. Local-only mode (Part II privacy item) turns telemetry fully off.
- The ask must be legible. A one-page, plain-language description of exactly what leaves the machine, versioned alongside the data-contribution agreement (Part II trust item). A user should be able to decide in one read.
- Structured feedback: capture at the moment of friction (a detector override, an abandoned review item, a failed parse), plus a simple open-ended channel for bugs, feature requests, and places where the conversation doesn't work well. Feedback themes re-rank this roadmap.