@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 和错误事件可监听后续变化。 初始视口所需的外部 block sidecar 会并行请求；首批结果到达后即可增量渲染，剩余结果合并为尾批提交。 会话会复用几何 Worker 和主 DXB3 解析缓存，避免连续 delta 解析重复传输和解析主缓冲区。

默认几何准备 Worker 从包内的相对资源路径加载。使用非 Vite bundler、CSP 限制环境或自行托管 Worker 资源时，可在会话选项中传入 workerUrl；需要完全控制 Worker 创建时，可传入优先级更高的 workerFactory：

const session = createCadDocumentSession(source, {
  workerUrl: new URL('/assets/geo-prepare.worker.js', window.location.href),
  // workerFactory: () => new Worker('/assets/geo-prepare.worker.js', { type: 'module' }),
});

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

全局文字构建配置

需要显式调整 Troika 文字构建参数时，在第一次 CAD 文字请求（包括字体预热）之前调用 configureCadTextBuilder()：

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

configureCadTextBuilder({
  defaultFontURL: '/fonts/cad-fallback.ttf',
  useWorker: true,
  sdfGlyphSize: 64,
  textureWidth: 2048,
});

该配置沿用 Troika 的全局、模块级、一次性语义，不是文档会话或 Viewer 实例级配置。调用方 负责选择具体字体资源；字符和语言到字体的映射仍通过 resolveTextFont 提供。未调用时， cad-loader 不会设置任何默认值，继续使用 Troika 原有的内置远端资源逻辑。

其他入口

• 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