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

207 lines
17 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.
# 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 信息」
里改。**转换前请确认你有权使用该模型**,工具不会替你做版权检查。