初始化 VRMify 增强版(VRMify Enhanced)
Tests / test (push) Has been cancelled

导入上游源码,为所有面向用户的品牌显示处添加「增强版 / Enhanced」标识;包含 unitypackage→VRM 的纯色 Toon 材质、兽耳 SpringBone、Unity 描边、UV 接缝白边补偿修复,以及默认不强制 T-pose。146 个单元测试通过。
This commit is contained in:
2026-11-15 23:21:59 +08:00
commit 60cce66993
114 changed files with 56114 additions and 0 deletions
+206
View File
@@ -0,0 +1,206 @@
# PMX → VRM 转换说明
PMX → VRM 的转换规则和命令行用法。转换器只用 Python 标准库,直接读写二进制格式,不依赖 Blender、
mmd_tools、Unity 或 UniVRM。
## 命令行
```bash
# VRM 1.0(默认)
python convert/pmx2vrm.py "model.pmx" -o "model.vrm"
# VRM 0.x(只认 0.x 的软件用)
python convert/pmx2vrm.py "model.pmx" --spec 0x --title "名字" --author "作者"
# 检查输出(结构 + VRM 官方 JSON Schema,需要 jsonschema)
python tools/qa/check_vrm.py "model.vrm"
```
| 参数 | 说明 |
|---|---|
| `--spec 1.0` / `--spec 0x` | VRM 版本,默认 1.0 |
| `--scale auto` / 倍率 | 默认把身高归一到 1.6 m |
| `--tpose` | 把 A-pose 手臂、手、手指摆成 VRM 规范的 T-pose(**默认不启用,保留原始姿势**;`--keep-pose` 作为旧版兼容别名保留) |
| `--keep-control-bones` | 保留没有权重的中间骨(全ての親 / センター / グルーブ / 腰 等;默认去掉,层级像 VRoid)。IK、末端骨这类不起作用的骨总会去掉 |
| `--flip-winding` | 强制反转三角形绕序(默认自动判定) |
| `--force-double-sided` | 所有材质双面 |
| `--outline` | 按 PMX 的轮廓线设置写 MToon 描边(默认不描边)。unitypackage / FBX 里 **Unity 材质自己设置的描边**(`.mat` 的 `_Outline_Width` > 0、`_Outline_Color`)会另行保留,与这个开关无关 |
| `--no-spring` / `--no-spring-skirt` | 不转物理 / 不转挂在下半身的链(通常是裙摆) |
| `--spring-stiffness k` | SpringBone 硬度整体倍率,默认 1.0 |
| `--spring-gravity g` / `--spring-gravity-skirt g` | 头发等 / 裙摆的重力,默认 0 / 0.1 |
| `--no-auto-spring` | 模型没有物理刚体时不自动补 |
| `--no-spring-center` | 不以模型根节点为 SpringBone center |
| `--no-combo-expr` | 情绪预设不组合眉 / 眼 / 嘴,每个预设只对应一个表情 |
| `--no-gaze` | 不补视线表情 |
| `--no-extra-expr` | 不补 hideHighlight / tongue 表情 |
| `--dense-morphs` / `--max-morphs N` | 表情用密集存储 / 只导出前 N 个(0 = 不导出) |
| `--tex-max N` / `--tex-jpeg` | 贴图最大边长 / 不透明贴图存 JPEG(需要 Pillow) |
| `--tex-no-mip` | 贴图采样器禁用 mipmap。UV 岛之间没留 gutter 的贴图,mipmap 会把岛外底色混进边缘形成白边;开启后白边基本消失,但远景会有轻微锯齿(默认关闭) |
| `--title` / `--author` | 写进 VRM meta |
在 Python 里调用:`pmx2vrm.convert(pmx_path, vrm_path, spec="1.0", ...)`,参数和上表对应,返回统计信息。
## 坐标系
| 格式 | 正面 | 角色左手侧 | 上 | 手性 |
|---|---|---|---|---|
| PMX(MMD) | -Z | +X | +Y | 左手系 |
| VRM 0.x(glTF) | -Z | -X | +Y | 右手系 |
| VRM 1.0(glTF) | +Z | +X | +Y | 右手系 |
- PMX 和 glTF 手性相反,同一组数字直接搬过去是镜像人形,所以要反射一个轴:转 0.x 时 X 取反,转 1.0 时 Z 取反。
绕 Y 旋转 180° 是纯旋转,改不了手性,转出来左右是反的。
- 反射会把「从外面看逆时针」变成顺时针,所以绕序通常要反转。转换器用反射后的数据,拿每个三角形的几何法线和
顶点法线投票自动判定,日志里有一行「绕序自动判定」。
- 尺寸:MMD 模型约 20 单位高,默认归一到 1.6 m;表情偏移按同样的倍率缩放。
模型镂空时先看「绕序自动判定」那行:判错了(反向面占多数)加 `--flip-winding`;模型本身是薄片几何
(头发、裙摆、飘带)依赖双面显示的,加 `--force-double-sided`。描边外壳(翻了面、紧贴在脸和身体外面的那层,
常叫「エッジ」「outline」)和衣服的内侧面按几何自动认出来,仍保持单面,否则会盖住模型或重叠闪烁,日志里会列出。
## 映射
| PMX | VRM / glTF |
|---|---|
| 骨骼层级 | glTF 节点(静止姿势只有平移),`skin.inverseBindMatrices` |
| 顶点权重 BDEF1/2/4、SDEF、QDEF | `JOINTS_0` + `WEIGHTS_0`(每顶点最多 4 根,已归一化);SDEF 按线性混合 |
| 材质 | MToon:1.0 写 `VRMC_materials_mtoon`,0.x 写 `materialProperties` |
| 加算球面贴图(.spa) | MToon matcap |
| 贴图 | 嵌入 GLB;PNG / JPEG 原样,其它格式转成 PNG |
| 顶点表情(含グループ) | morph target(默认稀疏存储)+ VRM 表情 |
| 材质表情 | 材质颜色绑定(显示 / 隐藏部件) |
| 骨骼表情 | 在静止姿势下摆骨、按线性蒙皮算出顶点位移,烘焙成 morph target |
| UV 表情 | 整个材质一起缩放 / 平移的 → 贴图偏移绑定;做不到的跳过并提示 |
| 左右眼骨 | humanoid leftEye / rightEye,lookAt 用骨骼 |
| 物理刚体 + 关节 | 1.0:`VRMC_springBone`;0.x:`secondaryAnimation` |
| 跟随骨骼的刚体 | SpringBone 碰撞体(球 / 胶囊;0.x 只有球,胶囊换成一串球) |
### 骨骼
MMD 标准骨名对应 VRM humanoid:下半身 → hips、上半身 → spine、上半身2 → chest、首 → neck、頭 → head、
腕 / ひじ / 手首 → UpperArm / LowerArm / Hand、足 / ひざ / 足首 / つま先 → UpperLeg / LowerLeg / Foot / Toes、
目 → Eye(`両目` 是双眼共用的控制骨,不映射)。手指按版本区分:
| MMD | VRM 1.0 | VRM 0.x |
|---|---|---|
| 親指0 / 1 / 2 | ThumbMetacarpal / Proximal / Distal | ThumbProximal / Intermediate / Distal |
| 親指1 / 2(没有 0,親指1 离手腕较远) | ThumbProximal / Distal | ThumbIntermediate / Distal,掌根补占位 ThumbProximal |
| 親指1 / 2(没有 0,親指1 在掌根) | ThumbMetacarpal / Proximal | ThumbProximal / Intermediate |
| 人指・中指・薬指・小指 1 / 2 / 3 | Proximal / Intermediate / Distal | 同左 |
常见的英文骨名(Unity / Mixamo / VRoid / Blender 风格)也能对应。转换时自动修正:
- **付与骨合并**:VRM 没有付与。付与回転率 1 的骨(足D / ひざD / 足首D 等,腿部网格的权重常在它们上面)
连同权重和子骨并入付与親。和付与親不在同一位置的也并,条件是两者跟着同一根 humanoid 骨移动、偏差不超过
那一节骨长的一半;合并后绕付与親的位置转。
- **按比例跟随的付与骨**:ひざ補助、ひじ補助、尻、衣服的调整骨这类跟关节转 30%~65% 的骨,权重按付与率
分给关节骨(线性混合,近似转了一部分角度)。带物理的不动,付与率为负的(腰キャンセル 等)不动。
- **自检**:转换后检查两件事,有问题在日志里提示(不改输出):网格在 MMD 里跟着某个关节转、在 VRM 里却不跟;
humanoid 骨位置明显不对(在身体另一侧、离父骨或网格太远,多半是把模型外面的控制骨当成了 humanoid 骨)。
- **层级**:VRM 要求每个 humanoid 骨在规范父骨位的子树里。MMD 的上半身和下半身是兄弟骨,转换时把上半身改挂到
下半身下,静止姿势下顶点不动。
- **hips 位置**:MMD 的下半身和上半身从同一点出发,hips 和 spine 几乎重合。hips 离 spine 太近时把它移到骨盆
(大腿根往上),和 VRoid 的比例接近;只挪节点,网格和权重不变。
- **T-pose**(`--tpose` / 界面「转为 T 姿势」,默认关闭,不重摆骨架):按 VRM 规范的静止姿势摆——上臂、前臂、手沿水平 ±X,掌心朝下,四指伸直,拇指水平指向
外侧与正前方之间的 45°。动作和手部追踪都是「从这个姿势开始转多少度」,静止姿势歪多少,动起来就一直歪多少。
从手臂往指尖依次转,子骨和顶点(含法线、表情偏移)按蒙皮权重一起转。末节手指没有真实子骨、tail 方向又和上一节
差得远(FBX 转来的模型常见)时,这一节跟着上一节转。
- **占位骨**:缺少规范必需的骨(以及 chest、neck,很多程序默认它们存在)时补 `vrm_xxx` 占位节点,并保证层级合法。
- **去掉无效骨**:既不带权重、也不是 humanoid 骨或物理关节 / 碰撞体,下面也没有这类骨的节点(IK、末端骨、合并掉的
付与骨、操作中心等)不写进 VRM。「精简控制骨」(默认开,`--keep-control-bones` 关闭)再去掉没有权重的中间骨(全ての親 / センター /
グルーブ / 腰 / 肩P 等),子骨挂到最近的保留骨上,层级和 VRoid 一样是 Root > Hips。都只删节点,网格和动作不变。
### 材质
- **透明模式**:根据漫反射 alpha 和贴图 alpha 的分布自动选。只有边缘抗锯齿的用 MASK(裁剪),半透明像素多的用
BLEND;会被材质表情隐藏的不透明材质用 MASK。贴图只统计材质的 UV 用到的区域,几个部件共用的图集、拼着用不到的
半透明图层不会让不透明的部件变成半透明。BLEND 材质按 PMX 材质顺序设置绘制顺序。
- **颜色**:按 MMD 的着色公式算出显示颜色;VRM 1.0 规定颜色因子是线性值,写入时从 sRGB 换算。
- **toon → 阴影**:MMD 的明暗来自 toon 贴图。阴影色取 toon 最暗端、亮部取最亮端,明暗交界的位置和宽度换算成
MToon 的 shadingShift / shadingToony。动漫风格的皮肤 toon 换算后阴影色是浅粉、交界靠后,和 VRoid 原生模型
的观感一致。没有 toon 的材质(通常是眼睛、眉毛、嘴)不画阴影。
- **乘算球面贴图**(.sph)在 MToon 里没有对应项,会被忽略并在日志里提示。
### 表情
- **预设对应**:按表情名对应 VRM 预设(まばたき → blink、あ → aa …)。比较时不分全角半角、大小写和分隔符,
也认变体后缀(怒りA、まばたき2)。除了 MMD 日文名,也认 VRoid(`Fcl_ALL_Joy`)、VRChat(`vrc.v_aa`)等英文名、
ARKit 和常见中文名(眨眼、开心 …),日文名优先。MMD 的「上」「下」是眉毛表情,不当成视线。
- **单眼眨眼**:按动的是哪一边的顶点定 blinkLeft / blinkRight,不看名字(不同模型的命名习惯不一致)。
- **情绪预设组合**:happy / angry / sad / relaxed / surprised 像 VRoid 一样组合眉、眼、嘴三个部位,例如
angry = 怒り + キリッ + 口角下げ。权重按 VRoid 的预设偏含蓄,方便和眨眼、口型叠加。至少两个部位找到才组合,
原来单个对应的表情保留为自定义表情。候选表情和权重见 `convert/vrmconv/expressions.py` 的 `COMBO`;
只有 ARKit 表情的模型用 ARKit 的组合。happy / relaxed(笑眼)设 `overrideBlink: blend`,笑眼时不再叠加眨眼。
- **退路**:名字对应不上时,眨眼用 ARKit 的 eyeBlinkLeft + eyeBlinkRight 或左右单眼合起来,口型用 ARKit 的
jawOpen、mouthPucker 等。
- 转换日志里的「表情预设」一行列出每个预设用了哪些表情、缺哪些。
- **网格划分**:模型按表情分成几个网格(类似 VRoid 的 Face / Body / Hair),每个网格只带动得到它的 morph target。
glTF 要求同一个网格的每个部分带同样的 morph target,而 three.js、Unity 等读取端会展开成「顶点数 × 表情数」的
完整数组;分开后,表情多的大模型在预览和游戏里能省下几百 MB 内存。网格名取网格里最大的材质名。
- **存储**:默认用 glTF 稀疏 accessor,只存实际动到的顶点,文件小很多;个别不支持稀疏 accessor 的老软件用
`--dense-morphs`。
### 视线
- lookAt 的最大转角按眼球几何算:MMD 模型的眼骨支点常贴着眼球,固定角度转眼看不出来,所以按「瞳孔移动约
瞳孔宽度的 28%」反推左右角度(8°~20°),向下取 0.7 倍、向上 0.5 倍;算不出时用 10°。
- 有左右眼骨时补 lookLeft / lookRight / lookUp / lookDown 四个预设表情(转眼骨烘焙成顶点位移),给直接播放
这几个表情的程序用;模型自己有同名表情时不补。每个方向烘焙成「横向」「深度」两个 morph target
(`lookLeftRight_depth`、`lookUpDown_depth` 只是 morph target,不是表情),按 sin / (1 − cos) 的权重组合,
任意角度都和直接转眼骨一致。所以在界面的「调整」里改视线角度时,这几个表情跟着变,不用重新转换。
- 补两个自定义表情,名字固定,程序按名字就能找到(模型已有同名表情时不补):
- `hideHighlight`:关掉眼睛高光。模型自带关闭高光的表情(「ハイライト消し」「eye hi off」等,几组高光各有一个时
合成一个)就用它;没有就按材质名找眼睛高光(「目光」「ハイライト」「eye hi」等,头发高光除外),生成一个把这些
面各自收成一点的表情。高光直接画在瞳孔贴图里的模型做不了,日志里会说明。
- `tongue`:吐舌,复制模型里的「舌出し」「ぺろっ」「べー」「tongueOut」等表情。
### 物理 → SpringBone
目标是在 UniVRM、three-vrm 里的手感接近原生 VRM 模型,而不是复刻 MMD 的 Bullet 物理。参数按 VRM 官方和 VRoid
示例模型在同一套动作(待机、转身、走路、跑步、抬腿)下的表现校准。
- **拆链**:挂了物理刚体的骨从「自己动、父骨不动」处开始沿子骨走成链,分叉处另起一条;链尾补 `xxx_tail` 节点。
- **分类**:挂在 hips 下、或从躯干垂到胯部以下的链算裙摆类;挂在手臂、腿上的算四肢配饰;其余(头发、胸前饰品等)
算头发类。
- **抽稀**:MMD 物理链切得很细,原生发束一般 3~7 节。头发类每节至少约 12 cm;裙摆类保留得密一些,因为
SpringBone 只在关节点检测碰撞,节太稀腿会从关节之间穿过去。
- **硬度**:SpringBone 的 stiffness 不随节长缩放,所以按「每帧回正的角度」换算:头发类软、裙摆类硬(撑住造型、
少穿模)、挂在手臂上的链介于两者之间,并限制在 2~10 之间。
- **阻力和重力**:阻力 0.6;重力头发类 0(加了会把散开的发型拉垂),裙摆类 0.1(抬腿后裙片落回腿上)。
- **短链不模拟**:总长不足 5 cm 的链和很短的四肢配饰(鞋带、手肘吊坠)跟着骨骼刚性移动,否则只会在末端高频颤动。
- **center = 模型根节点**:在模型自身的空间里模拟,人物整体移动(走路的根运动)时头发、裙摆不会被甩到身后、
压到腿上;需要「走路时头发往后飘」时用 `--no-spring-center`。
- **碰撞**:跟随骨骼的刚体转成碰撞体,按 PMX 的碰撞组 / 掩码决定每条链和哪些碰撞体碰撞。静止时就压在碰撞体
里的那几节缩小半径,免得一开始模拟就被弹开;挂在手臂上的链不碰撞。
- **链间横向关节**:PMX 裙摆常用横向关节把相邻的链连成一片,SpringBone 无法表达,只能舍弃(日志提示数量)。
为了不让腿从两条链之间把裙子劈开,每条裙摆链配一份朝裙片法线方向平移过的腿部碰撞体,被腿碰到时整片沿法线
方向移动。
- **模型没有物理时**(FBX 等转来的模型常见):按骨骼名和骨架结构自动补头发、裙摆、袖子、飘带、尾巴的链,
身体自动加碰撞体(`--no-auto-spring` 关掉)。
手感不合适时,先用 `--spring-stiffness` 整体调;导入 Unity 后也可以在 UniVRM 里逐条调,或者用界面的「调整」面板。
**VRM 0.x**:先按上面的规则算出 1.0 的链,再换成 0.x 的结构。0.x 只列每组的根骨,根骨下面整棵子树都会摆动,
每组只有一套参数,碰撞体只有球,所以:
- 只是跟着关节转的骨(被抽稀掉的中间节、链末端的配饰)把权重并到那个关节上、节点去掉,动起来和 1.0 一样;
0.x 文件里的骨因此比 1.0 少。每个关节的下一节排在第一个子节点(0.x 用它定这一节的方向)。
- 一条链一组。从别的链上分叉出来的链并入上层链的组(不然会被模拟两次);组内的碰撞体按关节数多数决定。
- 硬度、阻尼、重力、碰撞半径取组内的中位数;静止时会和碰撞体重叠的,给这一组配一个缩小的碰撞体。
- 胶囊碰撞体沿轴线每隔一个半径换成一个球。
## 已知限制
1. **VRM 0.x 的物理**比 1.0 粗一些:每组一套参数和一个碰撞半径、碰撞体只有球(见上文)。
2. **物理**是近似换算:链间横向关节舍弃,整片裙子的联动不如原 PMX;腿抬得很高时裙摆最上一圈和大腿根部会有少量
重叠(原生 VRM 模型同样如此)。
3. **材质**:乘算球面贴图、共享 toon07~10 没有对应;材质表情只转换显示颜色和透明度。
4. **骨骼表情**按静止姿势和线性蒙皮烘焙,不经过 IK;权重在 0 和 1 之间时和 MMD 里略有差别(MMD 是旋转插值)。
5. **T-pose** 用线性蒙皮重摆,肩部权重混合区在大角度时会轻微收缩;拇指要转 20~35°,虎口处会有少量拉伸。
拇指指甲的侧向朝向从骨骼位置看不出来,只摆方向。
6. **表情预设**按名字对应和组合;名字都认不出的模型组合不出来,可以在界面的「调整」里手动指定。
## 授权信息
VRM meta 默认写成最保守的授权:需要署名、禁止再分发、禁止修改、仅限个人非商业使用,可以在界面的「VRM 信息」
里改。**转换前请确认你有权使用该模型**,工具不会替你做版权检查。