viewer.lights — LightsManager

设计意图

Viewer 创建即自带一组内置默认灯光与 IBL 环境,PBR 渲染开箱即用——多数集成根本不需要碰 viewer.lights。这个域服务的是「默认光照不满足」的场景:产品展示的风格化打光、与宿主应用一致的光照氛围、检查内腔死角时临时补光。

关键抽象是 LightHandle 句柄模式:addAmbient / addDirectional / addPoint 返回不透明句柄,移除凭 remove(handle)——公开面不暴露任何底层渲染实现的灯光对象(viewer-core 铁律),灯光生命周期完全由 manager 记账。默认灯光组与用户灯光相互独立:removeDefaults() 只删内置组,clearUserLights() 只清用户加的灯,互不波及。

何时用它:风格化布光的产品展示、对齐宿主应用的光照氛围、检查内腔死角的临时补光。环境光照(IBL / HDRI)归 viewer.quality,与灯光叠加。

典型用法

产品展示:替换默认光照为自定义布光:

viewer.lights.removeDefaults();
viewer.lights.addAmbient({ intensity: 0.25 });
// direction 是光的照射方向(Z-up:z 为负即从上往下照)
viewer.lights.addDirectional({ direction: { x: -1, y: -0.5, z: -1 }, intensity: 1.2 }); // 主光
viewer.lights.addDirectional({ direction: { x: 1, y: 0.8, z: -0.3 }, intensity: 0.4 }); // 辅光

检查内腔:零件附近补一盏点光,看完凭句柄移除:

const fill = viewer.lights.addPoint({ position: { x: 0, y: 0, z: 300 }, intensity: 2, range: 800 });
// ……检查完毕
viewer.lights.remove(fill);

注意事项

• 默认参数:颜色默认白;强度 addAmbient 0.7、addDirectional / addPoint 1.0;点光 range 默认 0(不衰减)。只传必填字段即得这些默认。
• addDirectional 的 direction 是照射方向,不是光源位置。
• remove 凭句柄,句柄无效(已移除或不属于本实例)时静默返回;批量清场用 clearUserLights()。
• removeDefaults() 没有对应的「恢复默认」API:还需要默认观感时别调它,只做增量补光即可。
• 环境光照(IBL)不在本域:HDRI 环境与环境光强度经 viewer.quality 的 setEnvironment / setEnvironmentIntensity 调整,与灯光叠加,见渲染质量与统计。

完整签名与延伸

• LightsManager — 全部方法的精确签名。
• LightHandle — 句柄类型。
• 指南:渲染质量与统计 — IBL 环境与色调映射(与灯光正交的另一半光照)。