Files
cad-building-showcase/references/web_delivery.md

4.2 KiB
Raw Blame History

GLB and Web Delivery

Contents

  1. Variant contract
  2. Served viewer
  3. Offline viewer
  4. Browser smoke test
  5. Strict evidence manifest

Variant Contract

Deliver three variants for Web/digital-twin presentation:

  • overview: walls, glazing, roof, columns, beams, slabs;
  • standard: overview plus railings and doors; use as default;
  • detail: all extracted categories for review.

Generate them with build_showcase_variants.py or cad_showcase.py run. Validate variants_manifest.json and every variant spec. Keep source_file==site floors intact across variants.

The Trimesh branch of cad_showcase.py run writes a retained .raw.glb and then runs tools/compress.mjs (weld, dedup, prune, Draco) to produce each delivered .glb. The Blender branch uses Blender's Draco export. verify_showcase.py --strict must see draco=True and every delivered variant within the size budget.

Both GLB backends consume versioned building_spec.json. They must preserve <floor>__<category> names and glTF Y-up. floor.caps is canonical; exporters must not independently infer different cap groups.

Served Viewer

Use write_web_showcase.py, then install local dependencies from the copied exact-version package.json. Do not use mainland-unreliable CDNs.

The official template includes on-demand rendering, ACES/RoomEnvironment lighting, physical glass, shadows, grouped floor/category toggles, overview-to-standard progressive load, in-page variant switching, explode/section controls, presets, tour, bookmarks, URL-hash state, screenshot, inspection, and downloads.

Require idle window.__renders growth of zero after damping stops.

Offline Viewer

Use write_offline_viewer.py only for double-click/no-server delivery. It embeds vendored Three r147, pako, and a gzip-compressed GLB. Run verify_delivery.py --offline-viewer to decode and verify the embedded payload.

The offline viewer intentionally follows an older Three API. Keep its vendored library versions/checksums documented when updating them; do not copy modern template code blindly into r147.

Browser Smoke Test

cad_showcase.py run --web performs this gate automatically. For a manual/custom delivery, serve the Web directory locally, then run:

node scripts/web_smoke_test.mjs \
  --url http://127.0.0.1:8188 \
  --out outputs/<project>/browser_smoke_report.json \
  --screenshots-dir outputs/<project>/browser_smoke

Install Playwright/Chromium first when needed. The script checks real 1440×900/390×844 viewport dimensions, desktop/mobile control visibility, console/page/request failures, and idle render behavior. Feed the report to final verification with --browser-report. Supplying --web-dir makes the report mandatory: no report is BLOCKED, never PASS.

When an execution tool already has a run_in_background option, launch python3 -m http.server ... as the foreground command of that background process. Do not append shell &; the child server can die with the wrapper. Before presenting the viewer, probe the URL and keep that server process alive. Present the formal web/index.html URL when Web was requested; viewer.html is a separate offline fallback, not a substitute.

Strict Evidence Manifest

Run verify_showcase.py --strict for spec previews and GLB budgets, then:

python3 scripts/verify_delivery.py \
  --source-report outputs/<project>/cad_read_report.json \
  --spec outputs/<project>/building_spec.json \
  --variants-manifest outputs/<project>/delivery/variants_manifest.json \
  --web-dir outputs/<project>/web \
  --offline-viewer outputs/<project>/viewer.html \
  --render outputs/<project>/verify_previews.png outputs/<project>/iso.png \
  --browser-report outputs/<project>/browser_smoke_report.json \
  --require-browser-report \
  --evidence-out outputs/<project>/evidence_manifest.json

The verifier checks schema versions, audit gates, optional campus scope, GLB headers/mesh structure/naming/budgets, render dimensions/nonblank variance, Web assets/placeholders/features/variants, offline payload, and browser report. Only overall PASS is complete. WARN/SKIP produce overall BLOCKED unless the exact check has an explicit --waiver 'CHECK=REASON'; FAIL cannot be waived.