Files
Black-Cyan 60cce66993
Tests / test (push) Has been cancelled
初始化 VRMify 增强版(VRMify Enhanced)
导入上游源码,为所有面向用户的品牌显示处添加「增强版 / Enhanced」标识;包含 unitypackage→VRM 的纯色 Toon 材质、兽耳 SpringBone、Unity 描边、UV 接缝白边补偿修复,以及默认不强制 T-pose。146 个单元测试通过。
2026-11-15 23:21:59 +08:00

275 lines
14 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<p align="center">
<img src="ui/web/icon.png" width="72" alt="">
</p>
<h1 align="center">VRMify 增强版</h1>
<p align="center"><b>VRMify 增强版 · Enhanced</b> — 在上游 VRMify 基础上修复了纯色 Toon 材质丢失、兽耳动骨缺失、Unity 描边丢失、UV 接缝白边,并默认不再强制 T 姿势。</p>
<p align="center">
把 MMD / PMX 模型(以及 FBX、unitypackage、Unreal、XNALara 模型)转成 VRM 虚拟形象。<br>
拖入文件或整个压缩包,预览确认,就完成了。不需要 Blender、Unity 或任何插件。
</p>
<p align="center">
<a href="https://github.com/JiGuang283/VRMify/releases/latest"><img src="https://img.shields.io/github/v/release/JiGuang283/VRMify?label=download" alt="最新版本"></a>
<img src="https://img.shields.io/badge/platform-Windows%2010%20%7C%2011-0078d4" alt="Windows 10 / 11">
<img src="https://img.shields.io/badge/VRM-1.0%20%7C%200.x-7b61ff" alt="VRM 1.0 / 0.x">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-GPL--3.0-007ec6" alt="许可证:GPL-3.0"></a>
</p>
<p align="center">
<a href="README.md">English</a> | 简体中文
</p>
<p align="center">
<img src="docs/images/zh/overview.webp" width="900" alt="VRMify 增强版:左侧是文件列表和转换设置,右侧是三维预览和调整面板">
</p>
## 亮点
- **一个窗口,不用安装。** Windows 绿色版 exe,转换器本身是纯 Python,不需要配置 Blender、Unity 或插件。
- **转出来就好看。** 按 PMX 的 toon 贴图生成 MToon 卡通着色,透明按贴图逐张判定,默认保留模型原姿势
(需要时再手动勾选「转为 T 姿势」),情绪表情像 VRoid 一样眉、眼、嘴一起变。
- **物理手感接近原生 VRM。** PMX 刚体换算成 VRM 1.0 SpringBone 链和碰撞体,裙摆做了专门处理;
没有物理的模型按骨骼名自动补头发、裙摆、飘带。
- **干净的骨架。** MMD、VRChat、Mixamo、Unity 的骨名都能对应 VRM humanoid;付与骨合并,IK、末端骨、
控制骨这类在 VRM 里不起作用的骨去掉,层级和 VRoid 一样。
- **模型网站下载的包直接用。** zip / 7z / rar 原样拖进来,自动找出里面的模型,跳过道具和只有衣服的模型,
老 zip 包里乱码的日文 / 中文文件名也能还原。
- **用之前先看。** three-vrm 预览(和 UniVRM 同一套规则),可以播放走路、跑步动作、试表情,叠加显示骨骼和
碰撞体。预设表情、物理、视线范围、缩略图都能直接调,不用重新转换。
- **输出可靠。** 通过 VRM 官方 JSON Schema 校验,避开会让 UniVRM 导入失败的数据。
## 截图
<table>
<tr>
<td width="50%"><img src="docs/images/zh/preview.webp" alt="预览:动作和灯光"></td>
<td width="50%"><img src="docs/images/zh/skeleton.webp" alt="骨骼显示,按类别分色"></td>
</tr>
<tr>
<td><b>预览</b>:待机、走路、跑步动作,灯光,表情</td>
<td><b>骨骼显示</b>:humanoid、带权重、物理骨分色,悬停显示骨名和父骨</td>
</tr>
<tr>
<td colspan="2" align="center">
<img src="docs/images/zh/tune.webp" height="420" alt="调整面板,显示一条物理链和它的碰撞体">
<img src="docs/images/zh/batch.webp" height="420" alt="转换日志">
</td>
</tr>
<tr>
<td colspan="2"><b>调整</b>:预设表情、视线、逐条链的物理,并显示这条链和它的碰撞体 ·
<b>日志</b>:转换了什么、合并或跳过了什么,一目了然</td>
</tr>
</table>
<sub>截图中的模型:奥黛塔(模型提供 miHoYo,改造 观海),按其使用条款展示。</sub>
## 快速开始
1. 到 [Releases](https://github.com/JiGuang283/VRMify/releases/latest) 下载 `VRMify-v<版本>-win64.zip`,
解压后运行 `VRMify.exe`。
2. 把模型文件、文件夹或压缩包拖进窗口,点「开始转换」。
3. 点文件旁的眼睛图标预览 VRM,需要的话在「调整」里修改。
> [!NOTE]
> 程序没有代码签名,第一次运行时 Windows 可能提示「已保护你的电脑」:点「更多信息 → 仍要运行」。
> 窗口使用系统的 WebView2(Windows 11 自带,Windows 10 基本都有);没有时会改用浏览器打开界面,页面顶上会说明原因,
> 照样可以拖入或添加文件(会先复制一份)。
> 界面和转换日志有中文、英文两种(右上角切换),第一次启动时跟随系统语言。
## 支持的格式
| 输入 | |
|---|---|
| **PMX**(MMD) | 主要路径:骨骼、材质、表情、物理全部转换 |
| **FBX**、**unitypackage** | Unity / VRChat 风格的模型,自动判定朝向和贴图透明 |
| **uemodel**(UEFormat)、**psk / pskx**(Unreal ActorX) | Unreal 模型;uemodel 部件可以按整身参考对齐 |
| **xps**(XNALara) | |
| **zip / 7z / rar** | 找出里面的模型并转换;7z / rar 借用 7-Zip、WinRAR、Bandizip 或 Windows 自带的 `tar` |
| **VRM** | 在预览和「调整」里打开 |
输出:**VRM 1.0** 或 **VRM 0.x**(都带 SpringBone 物理),或只转到 **PMX**。
## 转换时做了什么
<details>
<summary><b>骨骼</b></summary>
- MMD 标准骨名(以及常见的英文、VRChat、Mixamo、Unity 骨名)对应 VRM humanoid;缺少的必需骨位补占位骨,
保证层级合法。
- 足D 这类付与骨连同权重并入它跟随的骨;膝盖、手肘的辅助骨这类按比例跟随关节的骨,权重按比例分给关节骨。
- 有部分网格在 MMD 里跟着关节动、在 VRM 里却不跟,或者 humanoid 骨位置明显不对时,日志里会提示。
- 在 VRM 里不起作用的骨(IK、末端骨、操作中心)去掉。「精简控制骨」(默认开)再去掉センター、グルーブ 这类
没有权重的中间骨,层级是 Root > Hips。蒙皮和动作不受影响。
- 可选的 T-pose 转换(默认关闭,原样保留模型静止姿势):勾选「转为 T 姿势」后把 A-pose 的手臂抬平,
手掌朝下、手指伸直、拇指斜向前 45°;hips 移到骨盆。
</details>
<details>
<summary><b>材质</b></summary>
- MToon 着色:阴影色和明暗交界从 PMX 的 toon 贴图换算。
- 不透明、裁剪、半透明按贴图本身判定;材质名保证不重复。
- 可选贴图瘦身(缩小尺寸、不透明贴图存 JPEG),文件通常能小一半。
</details>
<details>
<summary><b>表情</b></summary>
- 眨眼和口型(aa / ih / ou / ee / oh)按 MMD、VRoid、VRChat、ARKit 和常见中文表情名对应。
- 情绪预设(开心、生气、悲伤、放松、惊讶)像 VRoid 一样组合眉、眼、嘴。
- 材质表情、骨骼表情、UV 表情都会转换;有眼骨时补视线表情。
- 补充固定名字的 `hideHighlight`(关掉眼睛高光)和 `tongue`(吐舌):优先用模型自带的表情,没有关闭高光的
表情时按眼睛高光材质生成。
</details>
<details>
<summary><b>物理</b></summary>
- PMX 的刚体和关节换算成 VRM 1.0 SpringBone 的链、碰撞体和碰撞组。
- 裙摆链的碰撞体会调整位置,被腿推开时整片一起动,不会从中间劈开;手臂、腿上很短的链跟着骨骼刚性移动,
避免抖动。
- 没有刚体的模型(FBX 等)按骨骼名自动补头发、裙摆、袖子、飘带、尾巴的链。
</details>
更多细节和全部选项:[PMX → VRM](docs/pmx-to-vrm.md)、[其它格式 → PMX](docs/other-formats.md)。
## 使用
**设置**分三页:「转换」(目标格式、只转换人物、物理、表情、文件大小、保存位置,更多选项在「高级设置」里)、
「其它格式」(FBX / uemodel / psk / xps 的选项)、「VRM 信息」(写进每个 VRM 的作者、版本和使用许可,
默认是最保守的授权)。
**预览操作**
| | |
|---|---|
| 左键拖动 / 右键拖动 / 滚轮 | 旋转 / 平移 / 朝鼠标位置缩放 |
| 双击模型 | 以这一点为中心旋转 |
| `R` 或 `Home`,或双击空白处 | 回到当前选中的视角 |
| 「骨骼」开关 | 叠加显示骨骼;悬停显示骨名和父骨 |
**调整**不用重新转换就能修改:名称和缩略图、每个预设对应哪个表情和强度、视线范围、整体或逐条链的物理硬度和
重力。鼠标移到某条链上会显示这条链和它会碰到的碰撞体,也可以固定显示或让镜头对准它。修改直接写进 VRM,
下次再转同一个文件会自动套用。
每次转换后会自动截取脸部作为缩略图(可关闭;自己设置的缩略图不会被覆盖)。
## 命令行
```bash
python convert/pmx2vrm.py "model.pmx" -o "model.vrm" # VRM 1.0
python convert/pmx2vrm.py "model.pmx" --spec 0x # VRM 0.x
python convert/fbx2pmx.py "model.fbx" -o "model.pmx" # 其它格式 → PMX,再转 VRM
python tools/qa/check_vrm.py "model.vrm" # 检查 VRM(结构 + 官方 Schema)
```
## 常见问题
<details>
<summary><b>模型是白的 / 部分地方没有贴图</b></summary>
贴图要和模型放在一起、在 PMX 记录的位置:加入整个模型文件夹或压缩包,不要只加 .pmx。贴图在模型文件夹的
其它子文件夹里时会按文件名找到;仍然找不到或读不了的会在转换日志里列出来。
</details>
<details>
<summary><b>UV 接缝处有白边</b></summary>
贴图 UV 岛之间没留边距(gutter)时,glTF / VRM 的 mipmap 采样会把岛外的白底平均进边缘,
沿 UV 接缝就出现一圈白边;Blender / Unity 用不同的插值或较低的贴图导入分辨率,往往看不出来。
UV 数据本身没转错。勾选「贴图不生成 mipmap(消除 UV 接缝白边)」可立刻缓解(远景会有轻微锯齿);
要根治得在贴图里给每个 UV 岛做 4~8 px 的边缘外扩(padding)。
</details>
<details>
<summary><b>Unity 或游戏导入时卡住</b></summary>
多半是 UniVRM 遇到了不合规的数据。用 `python tools/qa/check_vrm.py 文件.vrm` 检查;Unity 程序的日志在
`%USERPROFILE%\AppData\LocalLow\<公司>\<产品>\Player.log`,里面有具体的异常。
</details>
<details>
<summary><b>脸看起来很平、没有阴影</b></summary>
VRoid 等原生 VRM 模型的脸本来也基本是平涂,阴影主要来自头发等的投影。阴影颜色来自 PMX 的 toon 贴图,
可以在预览的「灯光」里调角度、开关投影检查。
</details>
<details>
<summary><b>头发、裙摆抖动或穿模</b></summary>
SpringBone 是 MMD 物理的近似。在「调整」里整体或逐条链调硬度和重力;鼠标移到链上可以看到它用了哪些碰撞体。
</details>
<details>
<summary><b>模型有破洞、黑边,或薄片头发看不见</b></summary>
在「转换」页的「高级设置」里打开「所有材质双面」。描边外壳(翻面后包在脸、身体外面的那层)和衣服的内侧面仍保持单面,
否则会盖住模型,日志里会列出。转换日志里也有三角形绕序的判定结果。
</details>
<details>
<summary><b>FBX 朝向反了或透明不对</b></summary>
在「其它格式」页打开「额外旋转 180°」,或换一种「贴图透明通道」模式。
</details>
## 已知限制
- VRM 0.x 的物理由 1.0 的结果近似换算:每条链只有一套参数和一个碰撞半径,碰撞体只有球。
- PMX 里连接相邻裙摆链的横向关节在 SpringBone 里没有对应,裙摆整片联动的效果比 MMD 弱。
- 乘算 sphere 贴图和共享的 toon07~10 在 MToon 里没有对应;描边默认关闭。
- 预设表情按名字对应,名字特殊的模型需要在「调整」里指定。
- XPS 模型没有表情。
## 从源码运行
需要 Python 3.10 或更高版本。
```bash
python -m venv .venv
.venv\Scripts\pip install -r requirements.txt # 可选:pywebview(独立窗口)、Pillow(贴图处理更快)
python ui/app.py # 或双击 VRMify.bat;--browser 用浏览器打开界面
```
不装可选依赖也能转换,只是界面会在浏览器里打开,也不能瘦身贴图。
<details>
<summary><b>目录结构和开发</b></summary>
```
convert/ 转换器:pmx2vrm.py(PMX → VRM)及其各阶段 vrmconv/,fbx2pmx / uemodel2pmx / psk2pmx / xps2pmx,
pipeline.py(界面的转换流程),vrm_edit.py(调整)
formats/ 文件格式:pmxio、vrmio(GLB)、fbx_reader、uemodelio、pskio、xpsio、archive
ui/ 桌面程序:app.py(入口)、server.py(后端)、web/(页面)、viewer/(three-vrm 预览)
tests/ 单元测试(用 synth.py 生成的小模型)
tools/ 批量转换、VRM 检查、物理测试、真实模型回归、打包发布
docs/ 转换说明
```
```bash
pip install -r requirements-dev.txt # jsonschema、pyinstaller 等
python -m unittest discover -s tests # 单元测试
python tools/regress.py record <模型目录> # 用自己的模型记录基准(不进仓库)
python tools/regress.py check # 改代码后重转并对比
python tools/build_release.py # → dist/VRMify-v<版本>-win64.zip
```
发版:改 `ui/version.py`,提交,推送 `v<版本>` 标签;GitHub Actions 会测试、打包、冒烟测试 exe 并创建草稿 Release。
</details>
## 参与贡献
欢迎提交问题和 Pull Request。反馈转换问题时请附上转换日志,并说明模型的来源和格式——不要附上你无权分享的
模型文件。提交 Pull Request 前请先跑一遍单元测试。
## 许可
- VRMify 增强版 使用 [GPL-3.0](LICENSE) 许可。基于 [SaraKale/Model-To-PMX](https://github.com/SaraKale/Model-To-PMX)。
- 预览使用 [three.js](https://threejs.org/)、[three-vrm](https://github.com/pixiv/three-vrm)(MIT)和
ammo.js(zlib),见 `ui/viewer/vendor/`。
- **转换前请确认你有权使用这个模型。** 很多 MMD 模型禁止再分发或修改,转换后的 VRM 同样受这些条款约束。