feat(vrm_mesh_tools): Add standalone VRM mesh tools addon with separation and UV merging

- Add VRM Mesh Tools addon as independent Blender extension with complete functionality
- Implement Body Mesh Separator operator to isolate non-skin materials (CLOTH, etc.) from Body mesh
- Implement UV Edge Merger operator to convert triangles to quads based on UV coordinates
- Add comprehensive UI panel in sidebar with material list and operation buttons
- Include UV edge data JSON files for 10 VRM material types (Body, Face, Eyes, Hair, etc.)
- Add detailed README with installation instructions, usage guide, and compatibility notes
- Configure addon manifest for Blender 4.2+ with proper namespace isolation (vrm_mesh_tools)
- Ensure full compatibility with official VRM addon through independent naming conventions
- Add utility functions for mesh operations, material detection, and JSON data loading
This commit is contained in:
2026-01-02 14:06:18 +08:00
parent 21222044c4
commit 77806a351f
18 changed files with 96964 additions and 0 deletions

110
vrm_mesh_tools/README.md Normal file
View File

@@ -0,0 +1,110 @@
# VRM Mesh Tools
独立的 Blender 网格工具插件,提供 VRM 模型的网格分离和 UV 边融并功能。
## 功能特性
- **Body Mesh Separator模型分离**: 将 Body 网格中非皮肤材质CLOTH 等)的面分离为独立对象
- **UV Edge Merger四边面转换**: 根据 UV 坐标将三角面转换为四边面
## 系统要求
- Blender 4.2.0 或更高版本
## 安装方法
### 方法一:通过扩展管理器安装(推荐)
1. 下载插件的 zip 文件
2. 打开 Blender进入 `Edit > Preferences > Get Extensions`
3. 点击右上角的下拉菜单,选择 `Install from Disk...`
4. 选择下载的 zip 文件
5. 安装完成后,插件会自动启用
### 方法二:手动安装
1. 下载并解压插件文件
2.`vrm_mesh_tools` 文件夹复制到 Blender 的扩展目录:
- Windows: `%APPDATA%\Blender Foundation\Blender\4.2\extensions\user_default\`
- macOS: `~/Library/Application Support/Blender/4.2/extensions/user_default/`
- Linux: `~/.config/blender/4.2/extensions/user_default/`
3. 重启 Blender
4. 进入 `Edit > Preferences > Add-ons`,搜索 "VRM Mesh Tools" 并启用
## 使用方法
### 访问工具面板
1. 在 3D 视图中,按 `N` 键打开侧边栏
2. 找到 "VRM Tools" 标签页
3. 选中包含 Body 网格的 Armature 对象(或其子网格对象)
### Body Mesh Separator分离非皮肤面
此功能将 Body 网格中的非皮肤材质面(如 CLOTH分离为独立对象。
1. 选中 VRM 模型的 Armature
2. 在 "VRM Tools" 面板中查看材质列表
- `[保留]` 标记的材质SKIN、HAIR将保留在原网格中
- `[分离]` 标记的材质CLOTH 等)将被分离
3. 点击 "分离非皮肤面" 按钮
4. 分离后的面将创建为名为 "Body_Separated" 的新对象
### UV Edge Merger根据 UV 转四边面)
此功能根据预定义的 UV 坐标数据,将三角面转换为四边面。
1. 确保模型同时包含 Body 和 Face 网格
2. 选中 VRM 模型的 Armature
3. 点击 "根据UV转四边面" 按钮
4. 插件将自动处理所有支持的材质
## 与 VRM 官方插件的兼容性
本插件设计为可以与 [VRM-Addon-for-Blender](https://github.com/saturday06/VRM-Addon-for-Blender)VRM 官方插件)同时安装和使用。
### 命名空间隔离
为确保兼容性,本插件使用完全独立的命名空间:
| 组件 | VRM 官方插件 | VRM Mesh Tools |
|------|-------------|----------------|
| 插件 ID | `vrm` | `vrm_mesh_tools` |
| 操作符前缀 | `vrm.` | `vrm_tools.` |
| 面板前缀 | `VRM_PT_` | `VRM_TOOLS_PT_` |
| 侧边栏分类 | `VRM` | `VRM Tools` |
### 注意事项
- 两个插件可以同时启用,不会产生冲突
- 本插件不依赖 VRM 官方插件的任何模块
- 如果同时安装了两个插件,它们会在侧边栏显示为不同的标签页
## 支持的材质
插件内置了以下 VRoid 模型材质的 UV 边数据:
- `N00_000_00_Body_00_SKIN (Instance)` - Body 皮肤
- `N00_000_00_Face_00_SKIN (Instance)` - Face 皮肤
- `N00_000_00_FaceMouth_00_FACE (Instance)` - 嘴部
- `N00_000_00_FaceEyeline_00_FACE (Instance)` - 眼线
- `N00_000_00_FaceEyelash_00_FACE (Instance)` - 睫毛
- `N00_000_00_hH_00_FACE (Instance)` - 面部细节
- `N00_000_00_EyeIris_00_EYE (Instance)` - 虹膜
- `N00_000_00_EyeWhite_00_EYE (Instance)` - 眼白
- `N00_000_00_EyeHighlight_00_EYE (Instance)` - 眼部高光
- `N00_000_00_HairBack_00_HAIR (Instance)` - 后发
## 错误处理
- 如果未找到 Body 网格,面板将显示错误提示
- 如果未找到 Face 网格,"根据UV转四边面" 按钮将被禁用
- 如果某个材质的 JSON 数据文件缺失,该材质将被跳过并显示警告
## 许可证
MIT License
## 问题反馈
如果您遇到任何问题或有功能建议,请在项目仓库中提交 Issue。