zoning-envelope

name	zoning-envelope
description	Generate interactive 3D zoning envelope viewers from zoning analysis reports. Requires a zoning analysis report as input.
allowed-tools	["Read","Write","Bash","Glob","Grep","AskUserQuestion"]

/zoning-envelope — 3D Zoning Envelope Viewer

Generate an interactive 3D axonometric zoning envelope viewer as a self-contained HTML file. Uses Three.js with OrbitControls — opens in any browser, no dependencies.

Requires a zoning analysis report generated by /zoning-analysis-nyc. This skill is a renderer — it does not perform zoning calculations.

Project Dossier

If PROJECT.md exists in the working directory, read it before fetching — lot geometry and bulk controls may already be on file from /zoning-analysis-nyc. After completing, append a one-line envelope summary and the viewer file path to its Zoning section. Update values in place (the dossier holds current state, not history), every entry with a source and date. No PROJECT.md? Skip silently — or mention /project-dossier init if the user is clearly starting a project.

Usage

/zoning-envelope path/to/zoning-analysis.md
/zoning-envelope 250 hudson
/zoning-envelope

Step 1: Find the Report

If a .md path is provided

Read the file directly.

If a search term is provided (address, etc.)

Search for matching zoning analysis reports in the current working directory.

Use Glob + Grep to find reports matching the search term. If multiple matches, show the options and ask the user to pick one.

If no argument is provided

Search for the most recently modified zoning-analysis-*.md file in the current working directory. If found, confirm with the user. If not found, tell the user:

No zoning analysis report found. Run /zoning-analysis-nyc first, then come back with /zoning-envelope.

If no Envelope Data block is found

If the report exists but lacks the ## Envelope Data JSON block (older report format), tell the user:

This report was generated before the Envelope Data format was added. Re-run the zoning analysis to get an updated report, or I can attempt to parse the tables (results may be approximate).

Step 2: Parse Envelope Data

Read the ## Envelope Data JSON block from the report — a fenced code block containing:

{
  "lot_poly": [[x, y], ...],
  "unit": "ft",
  "setbacks": { "front": 6, "rear": 3, "lateral1": 3, "lateral2": 2 },
  "volumes": [
    { "type": "base", "inset": 20, "h_bottom": 0, "h_top": 85, "label": "base" },
    { "type": "tower", "inset": 10, "h_bottom": 85, "h_top": 290, "label": "tower" }
  ],
  "height_cap": 290,
  "info": { "title": "...", "zone": "...", "id": "...", "area": "..." },
  "stats": { "key": "value", ... },
  "scenarios": null
}

Step 3: Normalize to Envelope Model

From the parsed JSON, build the internal model:

• LOT_POLY — the lot boundary polygon in local units
• UNIT — "ft"
• VOLUMES — array of volumes to extrude, each with inset distance, height range, label
• HEIGHT_CAP — max height for the amber cap plane
• INFO — title, zone, id, area for the overlay panels
• STATS — key/value pairs for the parameters panel
• SCENARIOS — if present, multi-scenario toggle data

Compute inset polygons using the insetPolygon(poly, distance) function. For multi-volume envelopes (base + tower), compute the tower inset from the base inset (cumulative), not from the lot polygon — so the tower is always smaller than the base.

Compute volumes by extruding inset polygons between height intervals.

Step 3: Generate HTML

Build a self-contained HTML file following the design system below.

Design System

Element	Color	Opacity
Background	#f5f3ef	1.0
Ground (lot)	#dcd7cd	0.5
Lot boundary	#2c2c2c	1.0
Setback zones	#c85a50	0.2
Base volume faces	#6ba0c5	0.08–0.10
Base volume edges	#6ba0c5	0.30–0.35
Tower/upper volume	#6ba0c5	0.05
Height cap / sky plane	#e8a849	0.10–0.15
Labels	#333333	1.0 (canvas sprites)
Grid	#d0ccc4	0.15

Typography: Helvetica Neue, 11px for overlay panels, canvas sprites for 3D labels.

Layout:

• Top-left: Title + address/zone
• Top-right: Parameters panel (stats)
• Bottom-left: Color legend
• Bottom-right: Controls hint

All materials: transparent: true, depthWrite: false, side: DoubleSide.

CDN Import Map

<script type="importmap">
{ "imports": {
    "three": "https://cdn.jsdelivr.net/npm/three@0.170.0/build/three.module.js",
    "three/addons/": "https://cdn.jsdelivr.net/npm/three@0.170.0/examples/jsm/"
} }
</script>

Required Utility Functions

Include these in every generated HTML:

signedArea(poly) — Returns signed area. Positive = CCW winding.

insetPolygon(poly, d) — Shrinks polygon inward by distance d along edge-normal bisectors. Each vertex moves along the bisector of its two adjacent edge normals, with distance adjusted for the bisector angle. CRITICAL: The normal direction depends on polygon winding, which varies by data source (WGS84 vs EPSG:3857 produce opposite windings). The function MUST self-correct: after computing the inset, compare abs(signedArea(result)) against abs(signedArea(poly)). If the result is LARGER, negate the offset direction and recompute. This makes the function robust regardless of input winding.

triangulate(poly) — Ear-clipping triangulation for arbitrary simple polygons. Returns index array for BufferGeometry.setIndex().

extrudePolygon(poly, hBottom, hTop, color, opacity) — Returns a THREE.Group containing:

1. BufferGeometry with triangulated top/bottom faces + side quads
2. Wireframe edges: top ring, bottom ring, vertical edges at each vertex

groundPolygon(poly, color, opacity, yOffset) — Triangulated flat polygon at a given Y height.

centroid(poly) — Returns [cx, cz] for camera targeting and label placement.

createTextSprite(text, options) — Creates a THREE.Sprite with canvas-rendered text. Options: fontSize, color, bgColor.

Scene Setup

renderer = WebGLRenderer({ antialias: true })
renderer.setClearColor(0xf5f3ef, 1)
camera = PerspectiveCamera(35, aspect, 1, maxDim * 10)
camera.position = centroid + [maxDim * 1.5, maxDim * 1.0, maxDim * 1.5]
controls = OrbitControls with damping
AmbientLight(0xffffff, 0.75)
DirectionalLight(0xffffff, 0.35) from upper-right

Scale camera distance to the lot's maximum dimension so it works for both small townhouse lots (~25 ft) and large assembled sites (170 ft+).

Geometry Pipeline

For each generated file:

1. Fix polygon winding to CCW using signedArea
2. Lot ground plane: groundPolygon(lotPoly, ...) + outline + vertex markers (small spheres)
3. Edge labels: On edges > 20 units, place a createTextSprite at the edge midpoint, offset outward
4. Setback zone: Render lot polygon as red → overlay inset polygon as lot color. Draw inset as dashed line.
5. Volumes: For each volume in the model, compute inset if needed, then extrudePolygon(...)
6. Height cap: groundPolygon(topPoly, amber, ...) at max height
7. Height labels: Dashed vertical lines + text sprites at key heights
8. Street label: At the street-facing edge (Z ≈ 0 or the edge closest to the origin)
9. Area label: At lot centroid
10. Grid: THREE.GridHelper scaled to lot size, subtle opacity

Multi-Scenario Support

If SCENARIOS is populated (multi-lot analysis with apareadas, unified, etc.):

1. Create a THREE.Group per scenario
2. Add toggle buttons in a #scenario-bar div (top-left, below title)
3. showScenario(key) function:
   • Toggle group visibility
   • Update stats panel content
   • Update legend if needed
4. Active button gets .active class (dark background)
5. Lot dividers show/hide based on whether lots are unified

Reference Implementations

File	Pattern
./zoning-envelope-250-hudson-st.html	NYC exact polygon, contextual base+tower

Use this as the code baseline.

Step 5: Save File

Save the HTML next to the source report with zoning-envelope- prefix and the same slug:

• zoning-analysis-250-hudson-st.md → zoning-envelope-250-hudson-st.html

Open the file in the browser after saving.

Notes

• Dependency: This skill requires a zoning analysis report. It does not perform zoning lookups, coordinate conversion, or regulation parsing — that's the analysis skill's job.
• Units: NYC reports use feet. The unit field in the Envelope Data block determines all labels and scaling.
• Camera: Position proportional to max lot dimension. PerspectiveCamera(35) with OrbitControls.
• Multi-lot: When the report includes scenarios, generate toggle buttons. Use simplified rectangles if individual lot polygons are not available in the report.