一款适用于 QuickLook 的免费、离线、增强型三维网格预览插件。
An enhanced, offline mesh preview plugin for QuickLook, featuring model dimensions, unit normalization, color modes, edge display, and intuitive mouse controls.
QuickLook 4.5.0 已通过内置 HelixViewer 支持本项目涉及的网格格式。本插件不是为了增加新的文件扩展名，而是提供一套更统一、更适合机械模型快速检查的预览体验：
- 显示 X/Y/Z 外形尺寸；
- 统一换算 glTF、GLB 和 3MF 的单位；
- 提供灰色、逐三角面彩色和深色显示模式；
- 区分“旋转模型”和“移动模型”两种鼠标操作；
- 使用与 QuickLook.Plugin.StepViewer 一致的简洁界面。
插件优先级高于 QuickLook 内置 HelixViewer。安装后，支持的文件会优先使用本插件预览。
- 完全本地解析，不上传模型；
- 无需安装第三方 CAD 或建模软件；
- 浅色背景、默认灰色模型、无投影阴影；
- 左下角显示 X/Y/Z 外形尺寸；
- 灰色、逐三角面彩色、深色三种材质模式；
- 适合窗口与边线显示开关；
- 拖动空白区域：模型原地旋转；
- 抓住模型拖动：移动模型位置；
- 鼠标滚轮：缩放模型；
- 支持中文、空格及特殊字符文件路径；
- 作者链接在系统默认浏览器中打开。
| 格式 | 支持情况 | 说明 |
|---|---|---|
| STL | 支持 | ASCII 与 Binary |
| OBJ | 支持 | 几何模型；当前显示模式会覆盖原材质 |
| PLY | 支持 | ASCII 与 Binary |
| GLB | 支持 | 标准未压缩 glTF 2.0 Binary |
| GLTF | 支持 | 支持同目录外部 .bin 和贴图资源 |
| 3MF | 支持 | 读取文件中声明的长度单位 |
当前不支持 Draco 或 Meshopt 压缩的 GLTF/GLB。插件的颜色模式会统一替换模型原始材质和贴图，以保持机械模型查看风格一致。
| 格式 | 尺寸单位处理 |
|---|---|
| GLTF / GLB | 按 glTF 规范以米为单位，并换算为毫米显示 |
| 3MF | 读取文件声明的 micron、millimeter、centimeter、inch、foot 或 meter 并换算为毫米 |
| STL / OBJ / PLY | 格式通常不携带标准单位，按文件坐标值为毫米显示 |
- Windows 10 或 Windows 11；
- QuickLook 4.5.0 或更高版本；
- Microsoft Edge WebView2 Runtime。Windows 10/11 通常已安装。
- 从 GitHub Releases 下载
QuickLook.Plugin.MeshViewer.qlplugin； - 确保 QuickLook 正在运行；
- 选中下载的
.qlplugin文件并按空格键； - 点击 Install；
- 从系统托盘完全退出并重新启动 QuickLook；
- 选中受支持的三维文件并按空格键预览。
| 操作 | 功能 |
|---|---|
| 在空白区域按住左键拖动 | 原地旋转模型 |
| 在模型表面按住左键拖动 | 移动模型位置 |
| 鼠标滚轮 | 缩放模型 |
| “适合”按钮 | 恢复默认位置、角度和大小 |
| “边线”按钮 | 显示或隐藏模型边线 |
- Node.js 与 npm；
- .NET 8 SDK；
- Windows PowerShell 5.1 或更高版本。
powershell -ExecutionPolicy Bypass -File .\Scripts\pack.ps1构建结果：
QuickLook.Plugin.MeshViewer.qlplugin
powershell -ExecutionPolicy Bypass -File .\Scripts\package-source.ps1QuickLook.Plugin.MeshViewer/
├─ Plugin.cs QuickLook 插件入口
├─ MeshViewerPanel.cs WebView2 宿主与本地文件映射
├─ QuickLook.Plugin.Metadata.config 插件元数据
├─ Web/
│ ├─ index.html 预览界面
│ ├─ viewer.css 界面样式
│ └─ viewer-src.js 格式解析、渲染与交互
└─ Scripts/
├─ build.ps1 构建脚本
├─ pack.ps1 生成 .qlplugin
└─ package-source.ps1 生成源码包
模型仅在本机读取和渲染。本插件不会上传文件，也不依赖云端转换服务。外部链接只允许打开作者的 GitHub 页面，并交由系统默认浏览器处理。
- ASCII / Binary STL；
- ASCII / Binary PLY；
- OBJ；
- GLB；
- 使用外部
.bin与 PNG 贴图的 GLTF； - 毫米与英寸单位的 3MF；
- 灰色、彩色和深色模式；
- 旋转、抓取移动与滚轮缩放；
- 已知模型尺寸验证：10 × 20 × 30 mm。
- STL、OBJ 和 PLY 通常没有可靠的单位元数据，尺寸值按毫米解释；
- 不支持 Draco/Meshopt 压缩的 GLTF/GLB；
- 颜色模式会覆盖模型原始材质、顶点色和贴图；
- 极大的高面数模型仍受可用内存和 GPU 性能限制。
项目采用 MIT License。第三方组件许可证请参阅 THIRD-PARTY-NOTICES.txt。