@nebula-spatial/cad-loader

浏览器侧 DXB3/DXBS CAD pack 加载运行时。负责解析文档、构建 Three.js 渲染资源，并 提供图层、INSERT、文本和外部资源的文档级访问能力。

有完整视图需求的应用通常通过 @nebula-spatial/viewer 的 viewer.cad.open() 接入。 本包适用于需要自行管理 Three.js 场景或 CAD 文档生命周期的集成。

文档会话

createCadDocumentSession() 是推荐的文档级入口。会话提供 header、基础内容就绪状态、 视口需求和只读渲染资源；调用方负责场景挂载和相机/视口同步。

import {
  createCadDocumentSession,
  getCadDocumentRenderResource,
} from '@nebula-spatial/cad-loader';

const session = createCadDocumentSession('/api/files/demo/result', {
  filename: 'demo.dxf',
});
const renderNode = getCadDocumentRenderResource(session);

scene.add(renderNode.object);
const stopChanges = renderNode.onChange(() => requestRender());

const header = await session.headerReady;
fitCamera(header.bounds);

session.setDisplayContext(displayContext);
session.setViewportDemand(viewportDemand);
await session.initialContentReady;

stopChanges();
scene.remove(renderNode.object);
session.dispose();

headerReady 提供文档边界和图层元数据，initialContentReady 表示基础内容已可用。 通过 content-appended、demand-progress、phase-change 和错误事件可监听后续变化。

CadRenderNode 是只读渲染资源。选择状态、属性面板、编辑命令和历史记录由产品层维护。

其他入口

• loadGeo()：简单的 GeoNode 增量加载。适合不需要文档会话的 Three.js 集成。
• createLoadSession()：以异步事件流消费 CAD pack，适合自定义渲染器或流量控制。
• @nebula-spatial/cad-loader/core：不依赖 Three.js、DOM 或 WebGL 的协议解析 API，可用于 Worker、Node.js 和 CLI。

import { loadGeo } from '@nebula-spatial/cad-loader';

const node = loadGeo('/api/files/demo/result');
scene.add(node);
node.setViewportSize(canvas.clientWidth, canvas.clientHeight);
await node.ready;

默认 Worker 使用包内 ESM 资源路径。使用非 Vite bundler 或自行托管 Worker 资源时，可通过 LoadGeoOptions.workerUrl 或 workerFactory 配置 Worker 创建方式。

边界

本包不处理上传、任务轮询、文件目录或原始 DXF/DWG 解析。运行时依赖为 three peer dependency，要求 Node.js 18 或更高版本。

开发

npm run typecheck --workspace @nebula-spatial/cad-loader
npm test --workspace @nebula-spatial/cad-loader
npm run build --workspace @nebula-spatial/cad-loader