导入上游源码,为所有面向用户的品牌显示处添加「增强版 / Enhanced」标识;包含 unitypackage→VRM 的纯色 Toon 材质、兽耳 SpringBone、Unity 描边、UV 接缝白边补偿修复,以及默认不强制 T-pose。146 个单元测试通过。
17 KiB
PMX → VRM 转换说明
PMX → VRM 的转换规则和命令行用法。转换器只用 Python 标准库,直接读写二进制格式,不依赖 Blender、 mmd_tools、Unity 或 UniVRM。
命令行
# 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 用它定这一节的方向)。
- 一条链一组。从别的链上分叉出来的链并入上层链的组(不然会被模拟两次);组内的碰撞体按关节数多数决定。
- 硬度、阻尼、重力、碰撞半径取组内的中位数;静止时会和碰撞体重叠的,给这一组配一个缩小的碰撞体。
- 胶囊碰撞体沿轴线每隔一个半径换成一个球。
已知限制
- VRM 0.x 的物理比 1.0 粗一些:每组一套参数和一个碰撞半径、碰撞体只有球(见上文)。
- 物理是近似换算:链间横向关节舍弃,整片裙子的联动不如原 PMX;腿抬得很高时裙摆最上一圈和大腿根部会有少量 重叠(原生 VRM 模型同样如此)。
- 材质:乘算球面贴图、共享 toon07~10 没有对应;材质表情只转换显示颜色和透明度。
- 骨骼表情按静止姿势和线性蒙皮烘焙,不经过 IK;权重在 0 和 1 之间时和 MMD 里略有差别(MMD 是旋转插值)。
- T-pose 用线性蒙皮重摆,肩部权重混合区在大角度时会轻微收缩;拇指要转 20~35°,虎口处会有少量拉伸。 拇指指甲的侧向朝向从骨骼位置看不出来,只摆方向。
- 表情预设按名字对应和组合;名字都认不出的模型组合不出来,可以在界面的「调整」里手动指定。
授权信息
VRM meta 默认写成最保守的授权:需要署名、禁止再分发、禁止修改、仅限个人非商业使用,可以在界面的「VRM 信息」 里改。转换前请确认你有权使用该模型,工具不会替你做版权检查。