@flyfish-dev/cad-viewer 0.6.4 → 0.6.6

package/README.md

@@ -12,6 +12,19 @@ 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.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.
+- Added DWG LTYPE normalization and Canvas2D/WebGL rendering for dashed, dotted, BYLAYER and BYBLOCK linetypes, including continuous polyline phase and entity/global scale handling.
+- Preserved LibreDWG closed-polyline flags and added guarded fallbacks for tilted views, complex SHX linetype glyphs and pathological microscopic patterns.
+- Added public line-pattern helpers, `getSourceDocument()` and an eight-case DWG normalization regression suite.
+
 ## What changed in 0.6.4
 
 - Added a stable package export for `@flyfish-dev/cad-viewer/wasm/dwg-worker.js`.
@@ -85,6 +98,7 @@ 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.
 - **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.
@@ -150,6 +164,7 @@ const viewer = new CadViewer({
   canvasOptions: {
     background: '#05070d',
     foreground: '#f8fafc',
+    fitMode: 'auto',
     contrastMode: 'adaptive',
     minColorContrast: 2.45
   }
@@ -163,6 +178,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
 
@@ -256,6 +273,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,
@@ -286,11 +304,15 @@ const viewer = new CadViewer({
 
 await viewer.loadFile(file);
 await viewer.loadBuffer(arrayBuffer, 'drawing.dxf');
-viewer.fit();
+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
 viewer.setCanvasOptions({ background: '#f7f8fb', foreground: '#111827' });
+viewer.getDocument();            // transformed render-space CadDocument
+viewer.getSourceDocument();      // parser-owned WCS CadDocument
 viewer.clear();
 viewer.destroy();
 ```
@@ -355,7 +377,7 @@ viewer.registerLoader({
 
 | Format | Loader | Coverage |
 |---|---|---|
-| DWG | `DwgLoader` | Uses LibreDWG WebAssembly. Rendering coverage depends on the entities exposed by LibreDWG conversion. |
+| 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. |
 | 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. |
@@ -385,6 +407,7 @@ new CadViewer({ canvasOptions: { trueColorByteOrder: 'bgr' } });
 npm install
 npm run dev          # run the demo
 npm run typecheck    # TypeScript validation
+npm test             # build the library and run DWG normalization regressions
 npm run build        # library + demo
 npm run preview      # preview built demo
 ```

package/README.zh-CN.md

@@ -12,6 +12,19 @@
 
 > 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.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 和交互坐标。
+- 新增 DWG LTYPE 归一化与 Canvas2D/WebGL 线型渲染，支持虚线、点线、BYLAYER、BYBLOCK、多段线连续相位以及实体/全局缩放。
+- 保留 LibreDWG 的闭合多段线标志；对倾斜视图、复杂 SHX 线型 glyph 和异常微小 pattern 提供明确降级策略。
+- 新增公开线型工具、`getSourceDocument()` 和 8 项 DWG normalization 回归测试。
+
 ## 0.6.4 变更
 
 - 新增稳定的 package subpath：`@flyfish-dev/cad-viewer/wasm/dwg-worker.js`。
@@ -85,6 +98,7 @@
 - **纯前端组件**：`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 和稳定线型缩放。
 - **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、填充色、透明度和自适应对比度。
@@ -150,6 +164,7 @@ const viewer = new CadViewer({
   canvasOptions: {
     background: '#05070d',
     foreground: '#f8fafc',
+    fitMode: 'auto',
     contrastMode: 'adaptive',
     minColorContrast: 2.45
   }
@@ -163,6 +178,8 @@ input.addEventListener('change', async () => {
 });
 ```
 
+`fitMode: 'auto'` 是默认值。DWG 存在有效 active VPORT 时，会拟合保存视口内有意义的几何内容，避免远距离测绘坐标或辅助实体把主图框压成小黑点。使用 `viewer.fit('saved-view')` 可严格恢复保存视口，使用 `viewer.fit('extents')` 可查看全部坐标簇。
+
 
 ## WebGL 渲染与性能策略
 
@@ -256,6 +273,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,
@@ -286,11 +304,15 @@ const viewer = new CadViewer({
 
 await viewer.loadFile(file);
 await viewer.loadBuffer(arrayBuffer, 'drawing.dxf');
-viewer.fit();
+viewer.fit();                       // 自动拟合有意义的首屏内容
+viewer.fit('saved-view');          // 严格恢复 DWG active viewport
+viewer.fit('extents');             // 查看全部几何，包括远距离坐标簇
 viewer.zoomIn();
 viewer.zoomOut();
 await viewer.preloadDwg();       // 可选 DWG worker/WASM 预热
 viewer.setCanvasOptions({ background: '#f7f8fb', foreground: '#111827' });
+viewer.getDocument();            // 已应用 saved view 的渲染场景 CadDocument
+viewer.getSourceDocument();      // parser 保留的原始 WCS CadDocument
 viewer.clear();
 viewer.destroy();
 ```
@@ -355,7 +377,7 @@ viewer.registerLoader({
 
 | 格式 | Loader | 支持范围 |
 |---|---|---|
-| DWG | `DwgLoader` | 使用 LibreDWG WebAssembly。渲染完整度取决于 LibreDWG converter 暴露出的实体。 |
+| DWG | `DwgLoader` | 使用 LibreDWG WebAssembly。保留 active 平面 saved view、闭合多段线和 LTYPE 定义；Canvas2D/WebGL 支持 dash/dot 与 BYLAYER/BYBLOCK 继承，复杂 SHX glyph 使用 marker 近似。 |
 | 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 渲染器展示。 |
@@ -385,6 +407,7 @@ new CadViewer({ canvasOptions: { trueColorByteOrder: 'bgr' } });
 npm install
 npm run dev          # 运行 demo
 npm run typecheck    # TypeScript 检查
+npm test             # 构建 library 并运行 DWG normalization 回归测试
 npm run build        # 构建 library + demo
 npm run preview      # 预览构建后的 demo
 ```