# Applying this study in Grasshopper

Status: proposed next-model specification, not an implemented replacement definition. Existing `rhino-diorama/grid-city.gh` remains a tested generic baseline.

## What to retain from the existing city

Keep visible controls, deterministic seeds, separated geometry generation and custom preview, grouped native components, and explicit slider tests. Preserve the distinction between live output and a static Rhino snapshot. No part of this audit authorizes rebuilding or replacing that file.

## What the source evidence changes

1. **Input stage:** select a district/crop, read its original units and layer-role map, normalize to meters or another agreed unit, and store a reversible origin transform. Avoid referencing an entire multi-gigabyte district for every graph solution.
2. **Data stage:** keep source filename, object GUID, layer, base elevation, footprint area, local orientation, and association confidence together. A footprint and its roof patches must share a verified or explicitly inferred candidate ID.
3. **Massing stage:** support footprint shapes and several roof/elevation zones. A single XY rectangle and one height remain a fallback approximation, not the source representation.
4. **Context stage:** preserve useful road, sidewalk, park, and parcel geometry without assuming every context curve is closed or unique. Build validated land polygons before calculating coverage.
5. **Output stage:** expose source-derived envelopes, optional synthetic details, and diagnostic overlays separately. Do not bake on every solve.

## Tree structure

Prefer one branch per candidate building, for example `{district; candidate}`, with corresponding footprint/base information and a list of roof/facade patches. If profiles at several heights are reconstructed, use an explicit sub-branch or zone attribute rather than relying on the order of unrelated file objects.

Flattening is appropriate for an aggregate histogram or global preview. It is dangerous before matching envelopes: two flattened lists with equal counts do not prove building correspondence. Graft and simplify deliberately, and verify branch/item counts against a small known case before scaling up.

## Suggested interface

- Source district and crop bounds.
- Physical units, stored local origin, and source-to-local transform.
- Mode: preserve source massing or generate a new design from selected statistics.
- Context/geometric family used to select distributions.
- Seed, height/footprint variation, and landmark treatment for generated designs.
- Level of detail and simplification tolerance.
- Preview toggles for source, candidates, unmatched patches, invalid samples, and invented facade detail.
- An explicit one-time export/bake action outside the recurring solve path.

Do not add all controls before they are needed. For the first useful revision, choose one reviewed crop, preserve its footprints and local orientation, reconstruct a few massing envelopes, and compare them with source geometry.

## Safe thresholds and invalid inputs

Convert thresholds into the source model's physical units. The extractor's 0.10 m roof-association slack is a documented heuristic, not a universal CAD tolerance. Do not use the source document tolerance as a measure of positional survey accuracy. Treat open footprint curves, holes, intersections, and unpaired roof patches as explicit diagnostic outputs rather than forcing them into valid-looking solids.

When candidate matching is ambiguous, preserve all candidate references and leave the association unresolved. A missing result is more useful than a fabricated precise height.

## Known-answer checks for the first implementation

- A rotated 10 × 20 m rectangle has area 200 m², perimeter 60 m, and orientation-aware fill near 1 regardless of its world-axis bounding box.
- Known source points round-trip through the local transform within the chosen numerical tolerance.
- One candidate with several roof patches produces one envelope record and the expected highest roof elevation, without counting the patches as separate buildings.
- Two overlapping candidate footprints expose an ambiguous association rather than silently assigning a roof twice.
- A sloped or multi-ring base is flagged or handled by an explicit rule.
- Repeated solves do not add Rhino objects; export/reimport preserves scale and orientation.

These tests are proposed for a new reconstruction graph. Only the extractor helper tests, source census checks, and documented native-area cross-checks belong to the completed study.
