@flyfish-dev/cad-viewer 0.6.5 → 0.7.0

package/NOTICE

@@ -3,6 +3,7 @@
 This project integrates third-party open-source projects for CAD parsing and rendering:
 
 - @mlightcad/libredwg-web: DWG parsing in the browser through LibreDWG WebAssembly. License: GPL-3.0-only.
+- @mlightcad/shx-parser: AutoCAD SHX shape/font parsing and glyph geometry. License: MIT.
 - dxf-parser: DXF parser for JavaScript. License: MIT.
 - dwf-viewer 0.6.x: native frontend DWF/DWFx/XPS renderer for DWF 6+ ZIP containers, DWFx/OPC/XPS, WHIP/W2D 2D sheets, W3D/HSF eModel content, embedded XPS fonts and optional WASM fallback. License: AGPL-3.0-only.
 

package/README.md

@@ -12,6 +12,20 @@ The project provides a clean loader architecture for **DWG**, **DXF**, **DWF**,
 
 > DWG support uses `@mlightcad/libredwg-web` / LibreDWG WebAssembly in a worker. DXF support uses JavaScript parsing plus a built-in fallback parser. DWF, DWFx and XPS support is powered by `dwf-viewer` 0.6.x, including DWF 6+ ZIP containers, WHIP/W2D 2D sheets, W3D/HSF 3D eModel geometry, DWFx/OPC/XPS pages, adaptive CAD line weights and an optional raster WASM fallback.
 
+## What changed in 0.7.0
+
+- Corrected block-contained DWG geometry after PLAN/UCS transforms, including canonical insert/text rotations, closed-polyline fallback detection and authored constant/vertex widths.
+- Preserved TEXT width factors, alignment points, vertical/horizontal alignment and generation flags through worker normalization and INSERT expansion.
+- Added world-space wide-polyline rendering to Canvas2D and retained WebGL, while keeping dash phase and entity/INSERT linetype scales stable.
+- Added complete external SHX reference handling for complex DWG linetypes: referenced files are exposed through metadata, missing files use a safe marker fallback, and uploaded `File`/`ArrayBuffer` content is parsed, validated, cached and redrawn as real shape/text outlines without resetting the current view.
+- Added `onReferenceStateChange`, `addReferenceFile()`, `addReferenceBuffer()`, `getMissingReferences()` and related lifecycle APIs, plus a contextual SHX upload control in the demo.
+
+## What changed in 0.6.6
+
+- Added automatic initial fitting based on meaningful geometry inside a valid active DWG viewport, preventing remote coordinate clusters from shrinking the main drawing into a dot.
+- Added `fitMode: 'auto' | 'saved-view' | 'extents'` and `viewer.fit(mode)` for automatic content fitting, exact saved-view restoration or complete drawing extents.
+- Unified bounds and fitting behavior across the retained WebGL renderer and Canvas2D fallback.
+
 ## What changed in 0.6.5
 
 - Preserved active DWG VPORT/header UCS saved views and applied safe planar scene transforms exactly once across geometry, text, inserts, bounds and interaction coordinates.
@@ -92,7 +106,8 @@ The project provides a clean loader architecture for **DWG**, **DXF**, **DWF**,
 - **Pure frontend viewer component**: `new CadViewer({ container })` or `new CadViewer({ canvas })`.
 - **Loader registry**: DWG, DXF and DWF loaders are independent and replaceable; native-renderable loaders can mount their own optimized viewer.
 - **DWG preview**: browser-local parsing through LibreDWG WebAssembly, executed in a Web Worker by default.
-- **DWG view and linetype fidelity**: active planar saved views, closed polylines, LTYPE tables, BYLAYER/BYBLOCK inheritance, dash/dot patterns and stable pattern scaling.
+- **DWG view and linetype fidelity**: active planar saved views, block-contained text alignment and widths, closed/wide polylines, LTYPE tables, BYLAYER/BYBLOCK inheritance, dash/dot patterns and stable pattern scaling.
+- **External SHX references**: detects missing complex-linetype shape fonts, accepts local files or API-provided bytes, validates required glyphs and renders SHX shape/text geometry in Canvas2D and WebGL.
 - **DXF preview**: JavaScript parser path with fallback support for common ASCII DXF `ENTITIES`.
 - **DWF/DWFx/XPS preview**: powered by `dwf-viewer` for DWF ZIP packages, WebGL-accelerated W2D and XPS/DWFx 2D vectors, W3D/HSF eModel geometry, embedded XPS fonts, adaptive CAD line weights and raster fallback.
 - **CAD color handling**: ACI, BYLAYER, BYBLOCK inheritance, DWG layer colors, true color, fill color, opacity and adaptive contrast.
@@ -158,6 +173,7 @@ const viewer = new CadViewer({
   canvasOptions: {
     background: '#05070d',
     foreground: '#f8fafc',
+    fitMode: 'auto',
     contrastMode: 'adaptive',
     minColorContrast: 2.45
   }
@@ -171,6 +187,8 @@ input.addEventListener('change', async () => {
 });
 ```
 
+`fitMode: 'auto'` is the default. For DWG files with a valid active VPORT, it fits meaningful geometry inside the saved viewport, so remote survey coordinates or auxiliary geometry do not collapse the main sheet into a dot. Use `viewer.fit('saved-view')` to restore the exact saved viewport, or `viewer.fit('extents')` to include every coordinate cluster.
+
 
 ## WebGL rendering and performance model
 
@@ -264,6 +282,7 @@ const viewer = new CadViewer({
   canvasOptions: {
     background: '#05070d',
     foreground: '#ffffff',
+    fitMode: 'auto',                 // 'auto' | 'saved-view' | 'extents'
     contrastMode: 'adaptive',       // 'adaptive' | 'preserve'
     minColorContrast: 2.45,
     showPageBounds: true,
@@ -289,12 +308,19 @@ const viewer = new CadViewer({
   onLoad(result) {},
   onError(error) {},
   onRenderStats(stats) {},
-  onViewChange(event) {}
+  onViewChange(event) {},
+  onReferenceStateChange(state) {} // missing/loaded external SHX resources
 });
 
 await viewer.loadFile(file);
 await viewer.loadBuffer(arrayBuffer, 'drawing.dxf');
-viewer.fit();
+await viewer.addReferenceFile(shxFile);
+await viewer.addReferenceBuffer(shxArrayBuffer, 'LSG.SHX');
+viewer.getMissingReferences();      // CadMissingReference[]
+viewer.getLoadedReferences();       // CadLoadedReference[]
+viewer.fit();                       // automatic meaningful-content fit
+viewer.fit('saved-view');          // exact active DWG viewport
+viewer.fit('extents');             // all geometry, including remote coordinate clusters
 viewer.zoomIn();
 viewer.zoomOut();
 await viewer.preloadDwg();       // optional DWG worker/WASM warmup
@@ -305,6 +331,30 @@ viewer.clear();
 viewer.destroy();
 ```
 
+### External SHX references
+
+Complex DWG linetypes reference SHX shape/font files by name; their outlines are not embedded in the drawing. `CadViewer` keeps the drawing usable with a marker fallback and reports missing resources through both `onReferenceStateChange` and `document.metadata.missingReferences`.
+
+```ts
+const viewer = new CadViewer({
+  container,
+  onReferenceStateChange({ missing }) {
+    shxUploadButton.hidden = missing.length === 0;
+    shxUploadButton.textContent = missing.map(({ fileName }) => fileName).join(', ');
+  }
+});
+
+await viewer.loadFile(dwgFile);
+
+// User-selected local file.
+await viewer.addReferenceFile(shxFile);
+
+// Or bytes supplied by an application API. Keep the referenced file name.
+await viewer.addReferenceBuffer(shxBytes, 'LSG.SHX');
+```
+
+References can be supplied before or after the drawing. Parsed fonts remain cached across drawing loads until `removeReference()`, `clearReferences()` or `destroy()` is called. Replacing a reference validates the glyphs required by the active drawing; a same-named but incompatible file remains in the missing state. All parsing stays in the browser.
+
 ## Loader architecture
 
 ```text
@@ -365,7 +415,7 @@ viewer.registerLoader({
 
 | Format | Loader | Coverage |
 |---|---|---|
-| DWG | `DwgLoader` | Uses LibreDWG WebAssembly. Preserves active planar saved views, closed polylines and LTYPE definitions; Canvas2D/WebGL render dash/dot patterns with BYLAYER/BYBLOCK inheritance. Complex SHX glyphs use a marker approximation. |
+| DWG | `DwgLoader` | Uses LibreDWG WebAssembly. Preserves active planar saved views, block-contained text transforms/alignment, closed and authored-width polylines, and LTYPE definitions. Canvas2D/WebGL render dash/dot patterns with BYLAYER/BYBLOCK inheritance. Referenced SHX fonts are reported as missing resources; supplied files render complex shape/text glyphs with authored scale, offset and rotation, while unavailable glyphs use a marker fallback. |
 | DXF | `DxfLoader` | Uses `dxf-parser` plus fallback parsing. Supports codepage-aware text decoding, CAD text escape normalization, core entities, blocks/inserts, colors/layers, polylines, hatch boundaries and splines as preview polylines. |
 | DWF | `DwfLoader` + `dwf-viewer` | DWF 6+ ZIP packages, WHIP/W2D 2D sheets, W3D/HSF 3D eModel pages, model tree metadata, WebGL rendering and optional WASM fallback. |
 | DWFx / XPS | `DwfLoader` + `dwf-viewer` | DWFx/OPC/XPS pages with WebGL-accelerated vector paths, embedded fonts, text, images, package resources and adaptive overview line weights through the native DWF renderer. |
@@ -462,4 +512,4 @@ public/wasm/     demo WASM asset output directory
 
 ## License
 
-AGPL-3.0-only. The default DWG loader integrates `@mlightcad/libredwg-web` / LibreDWG, and the DWF renderer integrates `dwf-viewer`. Keep attribution and license notices when redistributing, modifying, embedding or using this package as part of another application. For closed-source commercial products, review all dependency licenses and replace loaders where your licensing model requires it.
+AGPL-3.0-only. The default DWG loader integrates `@mlightcad/libredwg-web` / LibreDWG, SHX decoding uses the MIT-licensed `@mlightcad/shx-parser`, and the DWF renderer integrates `dwf-viewer`. Keep attribution and license notices when redistributing, modifying, embedding or using this package as part of another application. For closed-source commercial products, review all dependency licenses and replace loaders where your licensing model requires it.

package/README.zh-CN.md

@@ -12,6 +12,20 @@
 
 > DWG 使用 `@mlightcad/libredwg-web` / LibreDWG WebAssembly，并默认运行在 Worker 中。DXF 使用 JavaScript 解析器并带内置 fallback。DWF、DWFx、XPS 由 `dwf-viewer` 0.6.x 驱动，覆盖 DWF 6+ ZIP 包、WHIP/W2D 2D 图纸、W3D/HSF 3D eModel、DWFx/OPC/XPS 页面、自适应 CAD 线宽和可选 raster WASM fallback。
 
+## 0.7.0 变更
+
+- 修正 PLAN/UCS 变换后的块内 DWG 几何，包括 INSERT/文字角度归一化、闭合多段线 fallback 检测，以及常量/顶点线宽保留。
+- Worker 归一化和 INSERT 展开过程现在会保留 TEXT 宽度因子、对齐点、水平/垂直对齐及镜像 flag。
+- Canvas2D 与 retained WebGL 新增 world-space 宽多段线渲染，同时保持 dash 相位及实体/INSERT 线型缩放。
+- 增加完整的外部 SHX 引用处理：通过 metadata 暴露复杂 DWG 线型引用的文件；缺失时安全降级为 marker；补传 `File` 或 `ArrayBuffer` 后会解析、校验、缓存并按真实 shape/text 轮廓重绘，同时保持当前视图不跳变。
+- 增加 `onReferenceStateChange`、`addReferenceFile()`、`addReferenceBuffer()`、`getMissingReferences()` 等资源生命周期 API，并在 Demo 中提供按需出现的 SHX 悬浮上传入口。
+
+## 0.6.6 变更
+
+- 新增基于有效 DWG active VPORT 内有意义几何的自动首屏拟合，避免远距离坐标簇把主图压缩成小黑点。
+- 新增 `fitMode: 'auto' | 'saved-view' | 'extents'` 和 `viewer.fit(mode)`，分别用于智能内容拟合、严格恢复保存视口及查看全部图形范围。
+- 统一 retained WebGL renderer 与 Canvas2D fallback 的边界计算和拟合行为。
+
 ## 0.6.5 变更
 
 - 保留 DWG active VPORT/header UCS saved view，并将安全的平面场景变换只应用一次，统一覆盖几何、文字、INSERT、bounds 和交互坐标。
@@ -92,7 +106,8 @@
 - **纯前端组件**：`new CadViewer({ container })` 或 `new CadViewer({ canvas })`。
 - **正确的 loader 架构**：DWG / DXF / DWF 独立 loader，可替换、可扩展；native-renderable loader 可以挂载自己的优化渲染器。
 - **DWG 预览**：通过 LibreDWG WebAssembly 在浏览器本地解析，默认在 Web Worker 中执行。
-- **DWG 视图与线型保真**：active 平面 saved view、闭合多段线、LTYPE 表、BYLAYER/BYBLOCK 继承、dash/dot pattern 和稳定线型缩放。
+- **DWG 视图与线型保真**：active 平面 saved view、块内文字对齐和宽度、闭合/宽多段线、LTYPE 表、BYLAYER/BYBLOCK 继承、dash/dot pattern 和稳定线型缩放。
+- **外部 SHX 引用**：识别复杂线型缺失的 shape 字体，接收本地文件或 API 字节，校验必需 glyph，并在 Canvas2D/WebGL 中渲染真实 SHX shape/text 几何。
 - **DXF 预览**：JavaScript 解析，支持常见 ASCII DXF `ENTITIES`，并带 fallback parser。
 - **DWF/DWFx/XPS 预览**：由 `dwf-viewer` 支持 DWF ZIP 包、WebGL 加速 W2D 与 XPS/DWFx 2D 矢量、W3D/HSF eModel、XPS 嵌入字体、自适应 CAD 线宽和 raster fallback。
 - **CAD 颜色处理**：支持 ACI、BYLAYER、BYBLOCK 继承、DWG 图层颜色、true color、填充色、透明度和自适应对比度。
@@ -158,6 +173,7 @@ const viewer = new CadViewer({
   canvasOptions: {
     background: '#05070d',
     foreground: '#f8fafc',
+    fitMode: 'auto',
     contrastMode: 'adaptive',
     minColorContrast: 2.45
   }
@@ -171,6 +187,8 @@ input.addEventListener('change', async () => {
 });
 ```
 
+`fitMode: 'auto'` 是默认值。DWG 存在有效 active VPORT 时，会拟合保存视口内有意义的几何内容，避免远距离测绘坐标或辅助实体把主图框压成小黑点。使用 `viewer.fit('saved-view')` 可严格恢复保存视口，使用 `viewer.fit('extents')` 可查看全部坐标簇。
+
 
 ## WebGL 渲染与性能策略
 
@@ -264,6 +282,7 @@ const viewer = new CadViewer({
   canvasOptions: {
     background: '#05070d',
     foreground: '#ffffff',
+    fitMode: 'auto',                 // 'auto' | 'saved-view' | 'extents'
     contrastMode: 'adaptive',       // 'adaptive' | 'preserve'
     minColorContrast: 2.45,
     showPageBounds: true,
@@ -289,12 +308,19 @@ const viewer = new CadViewer({
   onLoad(result) {},
   onError(error) {},
   onRenderStats(stats) {},
-  onViewChange(event) {}
+  onViewChange(event) {},
+  onReferenceStateChange(state) {} // 外部 SHX 的 missing/loaded 状态
 });
 
 await viewer.loadFile(file);
 await viewer.loadBuffer(arrayBuffer, 'drawing.dxf');
-viewer.fit();
+await viewer.addReferenceFile(shxFile);
+await viewer.addReferenceBuffer(shxArrayBuffer, 'LSG.SHX');
+viewer.getMissingReferences();      // CadMissingReference[]
+viewer.getLoadedReferences();       // CadLoadedReference[]
+viewer.fit();                       // 自动拟合有意义的首屏内容
+viewer.fit('saved-view');          // 严格恢复 DWG active viewport
+viewer.fit('extents');             // 查看全部几何，包括远距离坐标簇
 viewer.zoomIn();
 viewer.zoomOut();
 await viewer.preloadDwg();       // 可选 DWG worker/WASM 预热
@@ -305,6 +331,30 @@ viewer.clear();
 viewer.destroy();
 ```
 
+### 外部 SHX 引用
+
+复杂 DWG 线型按文件名引用 SHX shape/font，DWG 本身不包含对应轮廓。`CadViewer` 会先用 marker 保证图纸可用，并通过 `onReferenceStateChange` 与 `document.metadata.missingReferences` 同步缺失资源。
+
+```ts
+const viewer = new CadViewer({
+  container,
+  onReferenceStateChange({ missing }) {
+    shxUploadButton.hidden = missing.length === 0;
+    shxUploadButton.textContent = missing.map(({ fileName }) => fileName).join(', ');
+  }
+});
+
+await viewer.loadFile(dwgFile);
+
+// 用户选择的本地文件。
+await viewer.addReferenceFile(shxFile);
+
+// 或由业务 API 提供文件内容；fileName 必须保留图纸引用的名称。
+await viewer.addReferenceBuffer(shxBytes, 'LSG.SHX');
+```
+
+引用可以在图纸加载前或加载后传入。解析后的字体会跨图纸缓存，直到调用 `removeReference()`、`clearReferences()` 或 `destroy()`。替换引用时会校验当前图纸需要的 glyph；同名但不兼容的文件仍会保持 missing 状态。整个过程只在浏览器本地完成。
+
 ## Loader 架构
 
 ```text
@@ -365,7 +415,7 @@ viewer.registerLoader({
 
 | 格式 | Loader | 支持范围 |
 |---|---|---|
-| DWG | `DwgLoader` | 使用 LibreDWG WebAssembly。保留 active 平面 saved view、闭合多段线和 LTYPE 定义；Canvas2D/WebGL 支持 dash/dot 与 BYLAYER/BYBLOCK 继承，复杂 SHX glyph 使用 marker 近似。 |
+| DWG | `DwgLoader` | 使用 LibreDWG WebAssembly。保留 active 平面 saved view、块内文字变换/对齐、闭合及带原始宽度的多段线和 LTYPE 定义；Canvas2D/WebGL 支持 dash/dot 与 BYLAYER/BYBLOCK 继承。外部 SHX 会作为缺失资源报告；补传后按原始缩放、偏移和旋转渲染复杂 shape/text glyph，未提供时使用 marker fallback。 |
 | DXF | `DxfLoader` | 使用 `dxf-parser` + 内置 fallback。支持 codepage-aware 文本解码、CAD 文本转义归一化、基础实体、block/insert、颜色/图层、多段线、hatch boundary、spline 预览。 |
 | DWF | `DwfLoader` + `dwf-viewer` | DWF 6+ ZIP 包、WHIP/W2D 2D 图纸、W3D/HSF 3D eModel、模型树元数据、WebGL 渲染和可选 WASM fallback。 |
 | DWFx / XPS | `DwfLoader` + `dwf-viewer` | DWFx/OPC/XPS 页面，包含 WebGL 加速 vector path、嵌入字体、文本、图片、包内资源和自适应总览线宽，通过原生 DWF 渲染器展示。 |
@@ -462,4 +512,4 @@ public/wasm/     demo 的 WASM 输出目录
 
 ## 许可证
 
-AGPL-3.0-only。默认 DWG loader 集成 `@mlightcad/libredwg-web` / LibreDWG，DWF 渲染器集成 `dwf-viewer`。二开、分发、嵌入或作为应用组成部分使用时，请保留出处和许可证说明。闭源商用产品需要审阅所有依赖许可证，并在授权模型需要时替换对应 loader。
+AGPL-3.0-only。默认 DWG loader 集成 `@mlightcad/libredwg-web` / LibreDWG，SHX 解码使用 MIT 许可的 `@mlightcad/shx-parser`，DWF 渲染器集成 `dwf-viewer`。二开、分发、嵌入或作为应用组成部分使用时，请保留出处和许可证说明。闭源商用产品需要审阅所有依赖许可证，并在授权模型需要时替换对应 loader。