three.js CSMHelper 完整指南可视化级联阴影映射的级联体、阴影边界与主视锥【免费下载链接】three.jsJavaScript 3D Library.项目地址: https://gitcode.com/GitHub_Trending/th/three.jsCSMHelper是 three.js 提供的级联阴影映射Cascaded Shadow Maps, CSM调试助手用于把 CSM 实例内部不可见的级联视锥、级联分割平面和每级阴影相机包围盒直接渲染到场景中。读完本文你将掌握它的完整 API构造参数、displayFrustum/displayPlanes/displayShadowBounds三个显示开关、update()/updateVisibility()/dispose()方法、它在源码中的几何实现方式以及如何结合 webgl_shadowmap_csm.html 示例把它接入自己的动画循环从而快速排查阴影精度、级联划分和阴影范围问题。为什么需要 CSMHelper单个平行光阴影映射只有一张固定分辨率的 shadow map覆盖整个场景时近处物体精度不足、远处物体被浪费。CSM 把主相机的视锥按深度拆分为若干“级联”cascade每一级对应一个独立的光照阴影相机和独立 shadow map近处级联分辨率高、远处级联覆盖范围大。three.js 通过 examples/jsm/csm/CSM.js 中的CSM类实现 WebGL 路径通过 examples/jsm/csm/CSMShadowNode.js 中的CSMShadowNode实现 WebGPU 路径。问题在于级联数量、分割模式、maxFar、lightMargin等参数配错时症状往往是“某段距离阴影模糊”或“级联交界处闪烁”而这些几何关系默认完全不可见。CSMHelper就是为这个调试目的设计的——它把以下三层结构画出来主相机视锥mainFrustum的线框每一级级联视锥的包围盒白色与级联分割平面半透明每一级阴影相机的投影包围盒黄色即 shadow map 实际覆盖范围。导入方式CSMHelper是 addon 模块不在three主包内必须显式导入import { CSMHelper } from three/addons/csm/CSMHelper.js;该模块位于 examples/jsm/csm/CSMHelper.js与CSM、CSMFrustum、CSMShader、CSMShadowNode同目录。它只依赖three主包的几何与材质类Group、Mesh、LineSegments、Box3Helper、Box3、PlaneGeometry等自身不引入任何 addon。构造函数new CSMHelper( csm )new CSMHelper( csm : CSM | CSMShadowNode )csm是要可视化的 CSM 实例。构造后返回一个Group对象继承链为EventDispatcher → Object3D → Group需要手动加入场景const helper new CSMHelper( csm ); scene.add( helper );从源码看examples/jsm/csm/CSMHelper.js构造函数做了两件事保存传入实例到this.csm创建主视锥线框一段 24 个顶点8 顶点 × 3 分量Float32Array(24)加 24 条边索引Uint16Array的LineSegments材质为默认LineBasicMaterial初始加入Group并挂在this.frustumLines上。每个级联的可视化对象不在构造时创建而是在第一次update()时按csm.cascades数量动态生成——这保证了 helper 与级联数量始终同步。属性.csm : CSM | CSMShadowNode要可视化的 CSM 实例。CSMHelper之所以同时接受两类实例是因为两者暴露了相同的几何字段camera、cascades、mainFrustum、frustums、lights见 CSM.js 与 CSMShadowNode.js 中的同名属性。update()依赖这些字段读取每一级级联视锥的远面顶点与对应光照阴影相机因此无论 WebGL 还是 WebGPU 渲染路径都可用同一个 helper。.displayFrustum : boolean是否显示 CSM 视锥线框包括主视锥线框和每级级联视锥的Box3Helper。默认true。.displayPlanes : boolean是否显示级联分割平面每级远面的半透明平面。默认true。注意其可见性受displayFrustum联动只有displayFrustum displayPlanes同时为true时平面才可见见下文updateVisibility()实现。.displayShadowBounds : boolean是否显示每级阴影相机的包围盒黄色线框。默认true。方法.update()更新整个 helper 的几何与变换。必须在应用的动画循环中每帧调用且应在renderer.render()之前、与csm.update()同处一帧。源码CSMHelper.js中update()的执行流程从csm上读取camera、cascades、mainFrustum、frustums、lights若csm.camera null直接返回把 helper 自身的position/quaternion/scale复制为相机的变换并updateMatrixWorld( true )——helper 整体跟随相机动态增减每级对象当cascadeLines.length与csm.cascades不一致时逐个remove或新建。每级新建三件套cascadeLine白色0xffffffBox3Helper表示该级级联视锥cascadePlanePlaneGeometry 半透明MeshBasicMaterialopacity: 0.1、depthWrite: false、side: DoubleSideshadowLineGroup内含黄色0xffff00Box3Helper表示该级 shadow camera 的投影包围盒逐级更新几何cascadeLine.box取该级frustum.vertices.far的对角顶点z轴加1e-4微小偏移避免与平面共面cascadePlane定位到远面对角中点、缩放为远面尺寸shadowLineGroup对齐light.shadow.camera的位姿box由shadowCam的left / right / top / bottom / near / far直接写出最后把mainFrustum.vertices.near / far的 8 个顶点写入主视锥线框的 position 属性并置needsUpdate true。这套逻辑说明了一个重要细节helper 每帧从 CSM 实例“拉取”数据而不是订阅变化。因此 CSM 的级联参数如cascades、maxFar、mode改变后除了调用csm.updateFrustums()重建级联外下一帧的helper.update()会自动让线框数量与形状跟上。.updateVisibility()当运行时修改任一display*属性后必须调用。实现CSMHelper.js就是把当前三个开关翻译成各子对象的visiblecascadeLine.visible displayFrustum; cascadePlane.visible displayFrustum displayPlanes; // 平面受视锥开关联动 shadowLineGroup.visible displayShadowBounds; frustumLines.visible displayFrustum;.dispose()释放该实例占用的 GPU 资源不再使用时应调用。它会 dispose 主视锥线框的几何与材质再逐级 dispose 各Box3Helper其自带dispose方法、级联平面的几何与材质和阴影包围盒线框。实战在 CSM 示例中接入 CSMHelperexamples/webgl_shadowmap_csm.html 是最典型的接入范例核心片段import { CSM } from three/addons/csm/CSM.js; import { CSMHelper } from three/addons/csm/CSMHelper.js; // 1. 先构造 CSMcsmHelper 依赖 csm 实例 csm new CSM( { maxFar: params.far, cascades: 4, mode: params.mode, // uniform | logarithmic | practical parent: scene, shadowMapSize: 1024, lightDirection: new THREE.Vector3( params.lightX, params.lightY, params.lightZ ).normalize(), camera: camera } ); // 2. 创建 helper 并加入场景 csmHelper new CSMHelper( csm ); csmHelper.visible false; // 默认隐藏调试时再打开 scene.add( csmHelper );GUI 面板中为三个显示开关绑定updateVisibility()这正是官方文档强调的调用时机gui.add( csmHelper, displayFrustum ).onChange( () csmHelper.updateVisibility() ); gui.add( csmHelper, displayPlanes ).onChange( () csmHelper.updateVisibility() ); gui.add( csmHelper, displayShadowBounds ).onChange( () csmHelper.updateVisibility() );动画循环中按“先更新 CSM再更新 helper最后渲染”的顺序调用function animate() { camera.updateMatrixWorld(); csm.update(); // 更新各平行光与阴影相机位置 controls.update(); if ( params.autoUpdateHelper ) { csmHelper.update(); // helper 跟随相机并刷新所有线框/平面 } renderer.render( scene, camera ); }几个配套要点均来自该示例与 CSM.js相机/CSM 参数变更后调用csm.updateFrustums()切换相机示例支持正交相机、修改maxFar、mode、fade后都需触发helper 的几何会在后续update()中反映新划分窗口 resize 也要调用csm.updateFrustums()因为主视锥由相机投影矩阵决定材质必须通过csm.setupMaterial( material )注册否则 CSM 的着色逻辑不会注入该材质示例中对地面与两色立方体材质各调用了一次WebGPU 场景的对应写法见 examples/webgpu_shadowmap_csm.html把CSM换成CSMShadowNode构造签名为new CSMShadowNode( light, data )new CSMHelper( csm )用法不变。调试时的判读要点结合 helper 三层可视化可以这样定位常见问题白色盒子大小不均反映各级级联的远面跨度是mode与cascades分配是否合理最直观的证据practical模式按lambda 0.5对均匀与对数两种划分做线性插值见 CSM.js切换uniform/logarithmic/practical对比白盒尺寸差异能直接看到各策略在远近处的取舍黄色盒子与白色盒子的关系黄色盒是 shadow camera 的正交包围范围由该级视锥在光照空间的对角宽度加上lightMargin决定见 CSM.js 的_updateShadowBounds()。黄盒过大意味着lightMargin偏大shadow map 有效分辨率被摊薄过小则可能出现阴影被裁切级联平面位置若某级平面离相机过近近处物体会落入远端低分辨率级联表现为“近处阴影发糊”此时应增大该级 break 或改用practical/custom模式CSM支持customSplitsCallback自定义划分。适用前提与限制适用前提需要 WebGL 或 WebGPU 渲染器 shadow map 已启用helper 仅用于调试可视化生产场景建议保持helper.visible false每级级联对象在update()中按需创建级联数变化时自动增减无需手动重建 helper修改display*开关后不调用updateVisibility()不会生效每帧不调用update()则线框停留在旧位姿与相机脱节移除 helper 时先scene.remove( helper )再helper.dispose()同时 CSM 侧按各自约定调用csm.dispose()或 WebGPU 路径的对应清理。相关源码入口CSMHelper 实现、CSM 实现、CSMFrustum、CSMShader、CSMShadowNode、官方示例。【免费下载链接】three.jsJavaScript 3D Library.项目地址: https://gitcode.com/GitHub_Trending/th/three.js创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考