Files
cad-building-showcase/references/web_presentation_notes.md
zhengwr 6ace84ffba Campus pipeline hardening: backend parity, wall union, mullion grids, Draco tooling
Sandbox round (Linux):
- detect_sheet_frames.py: multi-frame sheet splitter (column AND row layouts),
  grid-vote per-floor offsets, section-elevation harvesting for storey heights
- dwg_dump_json.mjs + dwgjson_to_dxf.py: WASM libredwg DWG->DXF fallback
  (blocks/INSERT preserved, ATTRIB->TEXT so axis labels survive)
- assemble_campus.py: manifest-driven campus assembly with mandatory
  neighbour-gap gate (overlap = exit 3, 0.1-0.3m flagged as expansion joints)
- site_context_from_dump.py: site-context floors (ground/roads/parking/
  fence/trees/context massings) from site-plan dumps
- write_offline_viewer.py + assets/offline-viewer-libs/: fully-offline
  single-file viewer (vendored three r147 + pako, gzip-embedded GLB)
- audit: clip-scoped coverage figures; report: multi_frame_sheet warning;
  audit gate floors_aligned catches the diagonal-staircase failure mode

Mac round:
- build_blender_showcase.py now honors slab_bounds_fallback and prefers
  footprint polygons for generated roofs (bounds rects made roof plates jut
  past the facade and buried campuses under full-extent slabs); contract now
  matches spec_to_glb.py exactly
- merge_wall_solids (default off) in BOTH backends: shapely union in
  spec_to_glb.py, native delaunay_2d_cdt union in Blender; endpoint-shared
  wall ends pre-extended w/2 so L-corners close seamlessly (flat caps leave
  a notch a union alone cannot fill) while openings stay flat
- glazing_mullions (default off): curtain-wall panel grid (verticals every
  glazing_panel_w + floor-line transoms) as pseudo wall segments in the
  <floor>__walls node; glass pane kept
- build_showcase_variants.py keeps source_file=="site" floors intact in all
  variants (roads/trees live on filtered categories)
- web template: instanced low-poly trees from metadata site_trees,
  grade-level shadow catcher (was at basement depth), data-URI favicon
- tools/compress.mjs deps pinned (package.json); 15MB campus GLB -> 0.57MB
- tests: 24 -> 52 checks (wall union, mullions, byte-identical defaults)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-02 17:44:41 +08:00

8.2 KiB

Web Presentation Upgrades (视觉/交互/性能改进清单)

Prioritized playbook for pushing a working showcase model toward digital-twin presentation quality. Apply AFTER the geometry passes the One-Shot Definition of Done — polish never excuses a wrong model. Each item names the code to touch. Ordered by value-per-effort.

Tier 1 — cheap, do by default

  1. Deliver through the official template, not ad-hoc HTML. scripts/write_web_showcase.py + assets/web-showcase-template/ already provide floor explode, section height, camera presets, screenshot, variant downloads. One-off embedded-GLB HTML files are for quick sharing only; they balloon past 10-20 MB (base64) and lack controls.
  2. Draco-compress every delivered GLB. node tools/compress.mjs in.glb out.glb (or Blender's built-in). Typical 10-15 MB campus GLB -> 2-3 MB. The template registers DRACOLoader already. Serve with gzip/brotli on top.
  3. Lighting/material baseline in the viewer: ACES tone mapping (renderer.toneMapping = ACESFilmicToneMapping), scene.environment from RoomEnvironment (no HDR download needed), one shadow-casting DirectionalLight + soft ground shadow (ShadowMaterial plane, or baked AO plane). Cost: ~20 lines in the template, transforms perceived quality.
  4. Glazing as physical glass: MeshPhysicalMaterial with transmission 0.6-0.85, roughness 0.15-0.3, ior 1.5, depthWrite false. Keep alpha-blend fallback for mobile (lowPowerMode flag).

Tier 2 — geometry quality (extraction/export side)

  1. Continuous wall solids — DONE (2026-07-02): config merge_wall_solids (default off) in both spec_to_glb.py (shapely buffer(w/2, cap_style=2) -> unary_union -> extrude, holes preserved) and build_blender_showcase.py (Blender-native delaunay_2d_cdt union — its python has no shapely). KEY GEOMETRY LESSON: flat caps leave a w/2 x w/2 notch at L-corners that the union alone keeps open (T-joints are fine); both backends pre-extend ONLY endpoint-shared wall ends by w/2 (extend_shared_wall_ends) so corners close while door/window openings stay flat. Regression-tested (single-polygon corner, exactly 6 corners, free ends untouched, default off byte-identical). Cost: campus GLB triangles +37% with the flag on — opt-in for closeup shots.
  2. Curtain-wall mullions — DONE (2026-07-02): config glazing_mullions (default off, pitch glazing_panel_w 1.5 m) in both backends. Mullions and floor-line transoms are synthesized as pseudo wall segments (thin box profiles; transoms carry explicit _z0/_z1) and appended to the <floor>__walls node, so the Web viewer colors them as walls with zero viewer changes; the glass pane stays. They deliberately bypass the merge_wall_solids union (a union would fuse transoms into full-height walls). Regression-tested (5 posts on a 6 m band, top+bottom transoms, default off byte-identical); before/after renders: outputs/beian_1hao/mullions_{off,on}_facade.png (the 87 m F2 band).
  3. Door/window openings: subtract door/window spans (already classified per segment) from the wall solid of item 5 before extrusion; insert simple frame boxes. Only worth it at detail variant level.
  4. Site surfaces instead of sticks: roads/parking as filled polygons (polygonize Z5-车行道 boundaries with shapely, fall back to buffered centerlines), green areas from Z4-绿地 boundaries slightly below road level, water as flat translucent plate. Trees: replace posts with a 2-LOD low-poly tree (instanced mesh — one draw call for all trees). Extend scripts/site_context_from_dump.py (--surfaces flag).
  5. Parapets/eaves: RF roof lines already extrude via default_widths.roof; add a small cap strip on top of parapet bands so they read as solid walls from above.

Tier 3 — interaction & scale-out

  1. Click-to-inspect: raycast -> highlight mesh, show floor/category/source layer + drawing file (all present in building_spec.json; write it into GLB extras during export so the viewer needs no extra fetch).
  2. Camera bookmarks + auto-orbit tour; state (visible floors, section height, camera) serialized into the URL hash for sharing.
  3. Progressive loading for campuses: load overview GLB first, swap in standard/detail per building on idle or on selection (build_showcase_variants.py already produces the variants + manifest).
  4. Per-building toggles grouped in the panel (floors nested under building) once floor keys carry building prefixes (1F1 / 2F1 / 3F1 ...).
  5. Instancing & merge policy: merge static same-material meshes per building (BufferGeometryUtils.mergeGeometries) — target < 150 draw calls for a 5-building campus; keep per-floor granularity only for toggleable nodes.
  6. Digital-twin hooks: floor/mesh naming is stable (<floor>__<category>), so IoT bindings can address nodes by name; IFC semantics via scripts/build_ifc_poc.py when the client needs BIM hand-off.

Status on the 贝昂 case (2026-07-02)

DONE in the embedded viewer (outputs/beian_1hao/beian_campus_viewer.html): ACES tone mapping + RoomEnvironment IBL + PCF soft shadows + shadow-catcher ground; physical-glass glazing (transmission); instanced low-poly street trees (2 draw calls for all trees); click-to-inspect (floor/category chip + emissive highlight); per-building grouped floor toggles; payload gzip-embedded via browser DecompressionStream — 19.4 MB -> 3.0 MB with zero decoders.

SANDBOX LIMIT: gltf-transform's Draco/meshopt WASM core-dumps in the Linux sandbox; run tools/compress.mjs on macOS instead (works there). gzip embedding is the sandbox-safe fallback.

CDN LESSON (mainland China): cdn.jsdelivr.net (and most three.js CDNs) are slow/blocked for mainland users — a CDN-importing viewer hangs on the loading screen. For share-by-file delivery, embed EVERYTHING: three r147 UMD + examples/js OrbitControls/GLTFLoader/RoomEnvironment + pako inflate as inline classic scripts (~760 KB total, npm pack three@0.147.0). r147 API deltas: outputEncoding = sRGBEncoding (not outputColorSpace), physicallyCorrectLights = true. Always wire window error/unhandledrejection handlers into the loading overlay so failures are visible, never a silent "加载中". Headless smoke test in node: global.self/window/THREE, then GLTFLoader().parse(buffer) and count meshes.

DONE in the official template (assets/web-showcase-template, 2026-07-02): RoomEnvironment IBL, physical-glass glazing (transmission, clipping-aware), key light moved ABOVE ground (was y=-62 — a Y-up bug that broke shadows), model-sized shadow frustum (default ±5 m frustum is useless for buildings) plus ground shadow catcher. Formalized scripts/write_offline_viewer.py + assets/offline-viewer-libs/ for the share-by-file case.

DONE in the export pipeline (2026-07-02, Mac round): merged wall solids (merge_wall_solids, Tier 2 item 5) and curtain-wall mullion grids (glazing_mullions, Tier 2 item 6) in BOTH spec_to_glb.py and build_blender_showcase.py, regression-tested, default off. Same round: build_blender_showcase.py now honors slab_bounds_fallback and prefers footprint polygons for generated roofs (it used to emit bounds rects — the "roof plate juts past the facade" / "site covered by a giant plate" bugs); build_showcase_variants.py keeps source_file=="site" floors intact in every variant (roads/trees live on detail_lines/grid/trees categories, so category filtering used to strip the whole site from the Web default); the official template gained instanced low-poly trees (metadata site_trees written by write_web_showcase.py from the default variant spec), a grade-level shadow catcher (was at basement depth — shadows floated detached), and a data-URI favicon (console stays clean).

PENDING (Tier 2/3): door/window openings, road/green surfaces (filled polygons), camera tours / URL state, progressive per-building loading.

Honesty rules for presentation upgrades

  • Mullion grids, openings, and wall unions are VISUAL enhancements derived from plan linework — do not present them as BIM-verified elements.
  • Never let polish mask data gaps: a missing building must stay missing (or an explicitly-labeled massing), not be faked with a pretty box.