3D VOX Model Workbench

一个离线运行于浏览器中的 MagicaVoxel .vox 模型查看与轻量编辑工具。

它适合管理一整个 VOX 素材文件夹：无需为每个文件反复打开桌面编辑器， 即可连续浏览、检查、修改颜色和进行简单的体素编辑。所有模型与图片均只在 本地浏览器中处理，不会上传到服务器。

未打开外部文件时，工作台会载入一个 16 × 16 × 16 的草方块作为默认模型。

主要功能

• 打开文件夹，并在左侧列表浏览其中及其子目录下的全部 .vox 文件。
• 左侧按照真实目录层级显示可展开的文件夹树，不会把子目录文件平铺混合。
• 记住上次授权的模型文件夹，下次打开网页时自动恢复；目录失效时自动清除记录。
• 读取 MagicaVoxel VOX v150、v200 文件。
• 支持调色板、多模型、场景节点、图层、变换和基础动画模型集合。
• 使用 WebGL 预览模型，支持旋转、平移、缩放、坐标轴与网格辅助线。
• 支持使用 W、A、S、D 相对当前镜头方向平移视野。
• 鼠标中键拖动始终平移镜头，鼠标右键拖动始终旋转镜头，不受当前编辑工具影响。
• 显示模型尺寸、场景对象数和可见体素数。
• 添加或删除时显示绿色体素框预览；按住左键拖动可沿命中表面批量编辑矩形区域。
• 支持从模型底部的基准平面开始放置体素。
• 添加、删除和重新上色体素，并支持撤销。
• “采色”工具点击体素后，自动选择该体素使用的调色板颜色。
• 使用“覆盖模型”载入另一份 VOX 内容，再通过“保存 VOX”覆盖当前原文件。
• 编辑 VOX 格式中 255 个可见颜色槽位。
• 从 PNG、JPEG、WebP 或 GIF 图片中自动提取色盘。
• 图片颜色过多时，使用加权中位切分算法合并为最多 255 个代表色。
• 一键恢复按色轮排列的 256 色默认色盘。
• 获得文件夹写入权限后，可直接覆盖保存当前 .vox 源文件。
• 保存时保留多模型集合与场景结构数据。

使用方法

本项目没有构建步骤，也不依赖第三方包。

1. 使用较新的 Chrome、Edge 等 Chromium 浏览器打开 index.html。
2. 点击页面右上角的“打开文件夹”。
3. 授予包含 .vox 素材的文件夹读写权限。
4. 从左侧文件列表选择模型进行查看或编辑。
5. 编辑完成后点击右上角“保存 VOX”，覆盖当前源文件。

如果需要用另一份模型整体替换当前文件，先在左侧选择目标文件，点击 “覆盖模型”并选择新的 .vox。工作台会替换当前内存模型，但仍保留原目标 文件句柄；确认预览无误后点击“保存 VOX”，新模型才会写入原文件。

工具会把上次授权的文件夹句柄保存在浏览器 IndexedDB 中。再次打开网页时， 如果浏览器仍保留访问权限，会自动读取该文件夹；如果权限需要重新确认，点击 “打开文件夹”即可恢复授权。如果目录已删除、不可读取或权限被拒绝，对应记录 会自动清除。浏览器不会保存或绕过操作系统的真实路径权限。

选择“添加体素”或“删除体素”后，鼠标所指位置会显示绿色预览框。按下左键 并拖动可选择一个矩形范围，松开后一次添加或删除该范围内的一层体素。选区 方向由鼠标射线命中的表面决定：命中顶部时形成水平层，命中侧面时形成垂直层。 拖动只会沿命中表面的上下左右放大或缩小，垂直于该表面的方向始终锁定为 一个体素厚度。

也可以使用“打开单个 VOX”只查看一个文件。通过这种方式打开时，如果浏览器 没有授予原文件写入权限，保存操作会改为下载新的 .vox 文件。

部分浏览器会限制 file:// 页面使用文件夹写入权限，此时可以在项目目录启动 任意静态文件服务器：

python -m http.server 8080

然后访问 http://localhost:8080。

图片色盘提取

点击“读取图片色盘”并选择一张图片。工具会在本地缩放图片用于分析，统计其 颜色分布，并生成适合体素模型使用的色盘。

如果图片包含大量颜色，工具会根据颜色分布和出现频率，使用加权中位切分算法 将相近颜色合并为最多 255 个可见颜色。VOX 调色板的索引 0 固定保留为透明色， 因此完整调色板仍为 256 个槽位。

“恢复色轮色盘”会重新生成基础的 256 色默认色盘。色盘横向按照色轮顺序 排列色相，纵向依次提供不同饱和度和明度的浅色、标准色与深色，末尾保留 一组从白到黑的灰阶。

VOX 文件支持

解析器支持现代 MagicaVoxel 文件常用的以下数据块：

• SIZE
• XYZI
• RGBA
• PACK
• nTRN
• nGRP
• nSHP
• LAYR
• MATL

保存时会重新构建完整的模型集合与场景元数据，而不是只导出当前选中的对象。 对于重要的生产素材，仍建议使用 Git 或其他方式保留历史版本。

项目结构

• index.html：应用界面与页面结构。
• workbench.config.js：文件夹句柄持久化配置，包括数据库、存储区与配置键名。
• vox-viewer.css：工作台布局和界面样式。
• vox-core.js：VOX 解析、写入、调色板和场景工具。
• vox-viewer.js：WebGL 渲染、文件夹浏览、模型编辑和图片色盘提取。

隐私

本项目没有后端服务、统计分析、遥测或上传接口。文件通过浏览器本地文件句柄 读取和写入。

浏览器兼容性

建议使用最新版 Chrome 或 Edge。文件夹选择与源文件覆盖保存依赖 File System Access API，其他浏览器可能只能使用单文件打开和下载保存。

开源协议

本项目采用 MIT License。