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

5.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.

Both backends retain a decoder-free .raw.glb for offline embedding. The Trimesh branch then runs tools/compress.mjs (weld, dedup, prune, Draco), while the Blender branch performs a second Blender Draco export for each delivered .glb. 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 uncompressed GLB. The Trimesh pipeline therefore uses retained standard.raw.glb; passing a Draco GLB is a hard error because this offline bundle intentionally has no Draco decoder.

cad_showcase.py run --offline automatically opens the result via file:// in Chromium and writes offline_browser_smoke_report.json plus a screenshot. For a manual/custom delivery, run offline_viewer_smoke.mjs and pass its report to verify_delivery.py --offline-browser-report. Decoding the base64 payload is not proof that GLTFLoader can render it.

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.

The verifier validates the report contract, not just its top-level status: all required named checks must exist and be PASS, viewport details must match exactly, and console/page/request arrays must be present and empty. A hand-written {status: PASS} report is invalid.

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 \
  --audit outputs/<project>/extraction_audit.json --require-audit \
  --scope-manifest work/<project>/scope_manifest.json --require-scope-manifest \
  --variants-manifest outputs/<project>/delivery/variants_manifest.json \
  --web-dir outputs/<project>/web \
  --offline-viewer outputs/<project>/viewer.html \
  --offline-browser-report outputs/<project>/offline_browser_smoke_report.json \
  --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, scope artifacts, GLB headers/mesh structure/naming/budgets, render dimensions/foreground occupancy/noise, Web assets/placeholders/features/variants, offline payload, offline file:// browser load, and served-Web browser report. Only overall PASS is complete. Applicable WARN/SKIP produce overall BLOCKED unless the exact check has an explicit --waiver 'CHECK=REASON'; NOT_APPLICABLE is recorded but non-blocking, and FAIL cannot be waived.