8.1 KiB
Web Presentation Upgrades (视觉/交互/性能改进清单)
Contents
- Tier 1 defaults
- Tier 2 geometry quality
- Tier 3 interaction and scale-out
- Current implementation status
- Honesty rules
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
- 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. - 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. - Lighting/material baseline in the viewer:
ACES tone mapping (
renderer.toneMapping = ACESFilmicToneMapping),scene.environmentfromRoomEnvironment(no HDR download needed), one shadow-casting DirectionalLight + soft ground shadow (ShadowMaterialplane, or baked AO plane). Cost: ~20 lines in the template, transforms perceived quality. - Glazing as physical glass:
MeshPhysicalMaterialwithtransmission 0.6-0.85, roughness 0.15-0.3, ior 1.5, depthWrite false. Keep alpha-blend fallback for mobile (lowPowerModeflag).
Tier 2 — geometry quality (extraction/export side)
- Continuous wall solids — DONE (2026-07-02): config
merge_wall_solids(default off) in bothspec_to_glb.py(shapelybuffer(w/2, cap_style=2)->unary_union-> extrude, holes preserved) andbuild_blender_showcase.py(Blender-nativedelaunay_2d_cdtunion — 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. - Curtain-wall mullions — DONE (2026-07-02): config
glazing_mullions(default off, pitchglazing_panel_w1.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>__wallsnode, so the Web viewer colors them as walls with zero viewer changes; the glass pane stays. They deliberately bypass themerge_wall_solidsunion (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). - 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
detailvariant level. - Site surfaces instead of sticks: roads/parking as filled polygons
(polygonize
Z5-车行道boundaries with shapely, fall back to buffered centerlines), green areas fromZ4-绿地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). Extendscripts/site_context_from_dump.py(--surfacesflag). - 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
- Click-to-inspect — PARTIAL: raycast/highlight plus floor/category is done. Source layer + drawing file still require preserved GLB extras; merging currently collapses that provenance.
- Camera bookmarks + auto-orbit tour + URL-hash state — DONE.
- Progressive loading — PARTIAL: overview -> standard global swap is done; per-building idle/selection loading remains future work.
- Per-building grouped toggles with floor-key prefix fallback — DONE.
- 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. - Digital-twin hooks: floor/mesh naming is stable (
<floor>__<category>), so IoT bindings can address nodes by name; IFC semantics viascripts/build_ifc_poc.pywhen 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), source-layer/drawing provenance through merged GLB extras, and progressive per-building loading. Camera tours / URL state are complete.
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.