dwgreader / PROJECT_README.md
dellweb3's picture
Release v1.1.0: progressive 3DM preview and hierarchical layer visibility
f1d3305 verified
|
Raw History Blame Contribute Delete
7.36 kB

图阅 · DWG / 3DM 阅读器

一个在本机运行的图纸与模型阅读器:DWG 采用二维平移缩放,Rhino 3DM 采用三维旋转、平移与部件聚焦。文件在浏览器中解析,不发送到外部服务,也不会修改原文件。

启动

需要 Node.js 20.19+ 或 22.12+。首次使用先在项目目录运行 npm ci。Windows 用户随后双击 启动阅读器.cmd,浏览器会打开 http://127.0.0.1:5173/。

也可在本目录运行:

npm run dev

启动器仅监听 127.0.0.1,后台服务日志位于 .local/server.log 和 .local/server-error.log。关闭浏览器后本地服务继续运行。开发时可以在运行 npm run dev 的终端按 Ctrl+C 停止。

三个核心功能

  1. 打开文件:点击“打开文件”,或把 DWG / 3DM 拖入窗口。支持 100 MB 以内的文件,读取过程中可以取消。左侧列出打开过的文件,可直接重开。
  2. 查看主图或模型:DWG 用鼠标左键拖动平移,滚轮缩放。3DM 用左键旋转,右键或 Shift 加左键拖动平移,滚轮缩放。双击或按 F / Home 显示全部。
  3. 结构定位与属性:右侧按图层、图块/部件或文字浏览和搜索。点击目录对象自动定位并高亮;3DM 也支持直接点击模型几何对象聚焦。属性区显示文件信息,选中后显示对应的类型、图层、尺寸等。没有命名的三维对象以类型和序号标识。图层眼睛可临时隐藏图层;DWG 可切换模型/布局空间。

界面采用三栏布局:左侧文件,中间主视图,右侧结构与属性。顶部两个面板按钮可展开、收起左右两侧,并在当前浏览器记住状态。

快捷键:Ctrl+O 打开文件,/ 搜索;焦点在主图时 + / - 缩放,Esc 取消图中高亮。

界面和主图采用浅蓝色底色,原图浅色线条会自动调整为更适合浅色背景的颜色,保持可读性。

左侧文件面板自动保存成功读取过的 DWG 和 3DM,刷新或关闭页面后可在同一浏览器、同一地址直接重新打开。历史记录使用 IndexedDB 保留文件副本,最多 10 份、合计 250 MB,超出时移除较早的记录。可单独移除或清空。历史副本反映上次读取的版本,原文件有修改时应重新选择文件;清理浏览器数据也会清除历史,浏览器存储不可用或空间不足时会提示。

解析结果缓存在当前浏览器页面内,重复打开相同内容可跳过解析;DWG 和 3DM 各保留最近三个文件的解析结果。刷新或关闭页面会清除内存缓存,历史副本仍可重开。缓存和文件都不会发送到服务器。

3DM 先显示模型概貌,随后在后台补齐完整几何与目录。目录保留对象原名和父子图层,未命名对象以图层名、类型及序号标识。展开箭头可逐级浏览,眼睛按钮切换图层显隐,父图层同时控制子层;默认显示全部图层。

指定示例文件路径保存在被 Git 忽略的 .local/sample-path.json 中。双击启动器后首页可直接打开这份文件,文件本身没有复制进项目。开发终端如需同样入口,可以先设置 $env:DWG_SAMPLE='完整DWG路径' 再运行 npm run dev。

读取范围与限制

DWG 支持直线、多段线及凸度圆弧、圆、圆弧、椭圆、样条曲线、文字/属性文字、嵌套图块和已有标注图块。处理图块基点、二维旋转缩放、继承图层以及标注图块插入偏移。

3DM 显示文件内的网格、曲线、点、带显示网格的曲面等对象;没有预存网格的拉伸体可根据轮廓生成近似网格。打开时显示隐藏图层,可在图层面板切换。需要浏览器支持 WebGL。部分 NURBS 曲面没有预存显示网格时无法显示,应在 Rhino 中启用保存显示网格后另存。三维目录反映文件已有对象和组合关系,不自动推断“柜门、柜体”等语义。模型的非嵌入外部纹理或环境资源不会联网读取,材质和灯光与 Rhino 的最终渲染可能不同。

  • 图案填充目前显示边界;实体填充显示实心区域,多环填充的孔洞可能不精确。
  • 布局支持二维正交矩形视口的模型投影与裁剪;透视、倾斜和非矩形裁剪视口暂不支持。WIPEOUT 遮罩、外部图片、三维实体、自定义代理实体尚不支持。缺少外部参照内容时不会自动寻找其他文件。
  • 使用系统中文字体替代 CAD 的 SHX 字体,复杂多行文字的格式、宽度、字间距和线型/线宽可能与 AutoCAD 不一致。
  • 解析告警和未完整显示的对象会汇总在左下角,点击状态可查看详情;不能将此版本视为 AutoCAD 的精确打印或审图替代品。

真实图纸和模型的本机验证资料仅留在忽略目录。出现解析告警时会显示兼容提示,不能将部分读取视为完整还原。

开发和验证

npm test
npm run build
npm run preview

几何测试覆盖嵌套图块坐标、标注偏移、模型/布局隔离、隐藏实体、循环引用及圆弧。scripts/browser-check.mjs 检查 DWG;scripts/model-check.mjs 检查 3DM 聚焦、旋转、平移、面板折叠、DWG 切换与历史重开。浏览器脚本默认使用 Playwright 的 Chromium,也可通过 PLAYWRIGHT_EXECUTABLE_PATH 指定浏览器;实际文件路径从忽略的 .local/sample-path.json / .local/model-path.json 读取。截图和结果仅写入 .local/。

源码:src/geometry.ts 构建 DWG 结构和坐标;src/parser.worker.ts 解析 DWG;src/viewer.ts 绘制二维图;src/model-viewer.ts 读取三维模型与控制相机;src/main.ts 组织界面。

私有资料保护

本仓库只保存源码、测试和通用文档。DWG/DXF/3DM、模型和图纸副本、截图、提取数据、历史记录、日志与凭据均不上传。上传前运行 npm run check:upload 检查 Git 暂存区。该检查是额外防线,不能替代提交内容的人工核对。

第三方组件与许可证

DWG 解析使用 MLightCAD LibreDWG-Web 0.8.7(GPL-3.0),其底层为 GNU LibreDWG。本项目按 GPL-3.0-or-later 标记。Vite 使用 MIT 许可证,TypeScript 使用 Apache-2.0 许可证。重新分发时应保留对应许可证和源代码要求。

三维渲染使用 Three.js 的 Rhino3dmLoader 与 OrbitControls,3DM 解析使用 rhino3dm,均为 MIT 许可证。解析用的 JS / WASM 由本机依赖构建并提供,不使用外部 CDN。

HF 部署

Dockerfile 使用 Node 构建前端,运行阶段仅提供 dist 的静态文件,监听 7860 端口,不提供模型上传接口。.dockerignore 只允许构建所需源码进入构建上下文。Space 元数据模板为 deploy/SPACE_README.md,上传时映射为目标 Space 的根 README.md,项目说明映射为 PROJECT_README.md。

发布只从核对后的 Git 文件清单选取源码,不能上传整个工作目录。部署凭据与实际文件路径只在本机忽略目录或用户指定的本机位置使用,不能写入镜像、Space Secrets 或仓库。HF 上的浏览器历史与本机开发地址各自独立。