@nebula-spatial/viewer

浏览器侧只读 Three.js Viewer Facade。负责场景运行时、相机、输入、拾取、渲染循环和 资源释放；viewer.cad 提供与 @nebula-spatial/cad-loader 集成的 CAD 文档能力。

Viewer 不解析 DXF/DWG，也不提供编辑命令、历史记录或业务状态管理。

CAD 快速开始

import { createViewer } from '@nebula-spatial/viewer';

const viewer = createViewer({
  viewport: document.querySelector<HTMLElement>('#viewport')!,
  canvas: document.querySelector<HTMLCanvasElement>('#viewport canvas')!,
  initialViewMode: '2d',
});

viewer.cad.on('document-change', ({ document }) => {
  updateDocumentTitle(document?.filename ?? '');
});

await viewer.cad.open('/api/files/demo/result', {
  documentKey: 'demo',
  filename: 'demo.dxf',
});

viewer.dispose();

CadLoadSource 支持 URL、ArrayBuffer、File 及对应的 { kind: ... } 形式。open() 会替换当前 CAD 文档；调用 viewer.cad.close() 可仅关闭文档并保留 Viewer。

viewer.cad 暴露以下只读模型，可通过 document-change、layer-change、 block-change、inspector-change 和 hud-change 绑定到产品 UI：

• document：文档信息和加载阶段。
• layers：图层可见性与颜色覆盖。
• blocks：INSERT 使用项和实例可见性。
• inspector：当前 CAD INSERT 或文本选择。
• hud：视图与渲染统计。

可选的 ui 配置会挂载 cad-readonly 预设 UI；产品层也可以完全自行呈现这些模型。

通用 Three.js 对象

Viewer 同样可管理非 CAD 的 Object3D：

viewer.addObject(model);
viewer.fitView(model);

const stopPicking = viewer.on('pick', ({ result }) => {
  selectObject(result?.object ?? null);
});

viewer.setHighlight(model, { color: 0x5b8cff });
stopPicking();

默认点击会执行通用 Raycaster 拾取。格式专用的交互可通过 pointerPick: false 关闭它， 并监听 pointer-click、pointer-move 和 pointer-leave。screenToWorldOnPlane() 用于 通用的屏幕坐标到世界平面转换。

生命周期

Viewer 借用 addObject() 传入的 Object3D。removeObject() 和 dispose() 只解除场景 挂载，不会释放调用方的 Geometry、Material 或 Texture。

Viewer 自行拥有 SceneRuntime、Renderer、Camera、Controls、事件监听和 CAD 会话；调用 dispose() 会统一释放这些资源。运行时依赖为 three peer dependency，要求 Node.js 18 或更高版本。

开发

npm run typecheck --workspace @nebula-spatial/viewer
npm test --workspace @nebula-spatial/viewer
npm run build --workspace @nebula-spatial/viewer