PyPMXVMD API 文档¶
PyPMXVMD 是一个用于解析和修改 MikuMikuDance (MMD) 文件的 Python 库。
版本: 2.7.1
Python要求: >= 3.8
加速: 支持可选 Cython 快速解析与二进制 I/O,若不可用将自动回退到纯 Python 解析。
目录¶
快速开始¶
安装¶
基础用法¶
顶层API¶
PyPMXVMD 提供了简洁的顶层函数,用于文件的加载和保存。
二进制文件操作¶
pypmxvmd.load(file_path, more_info=False)¶
自动检测文件类型并加载。
参数:
- file_path (str | Path): 文件路径
- more_info (bool): 是否显示详细解析信息
返回: VmdMotion | PmxModel | VpdPose
异常: ValueError - 不支持的文件类型
pypmxvmd.save(data, file_path)¶
自动检测数据类型并保存。
参数:
- data: VmdMotion | PmxModel | VpdPose 对象
- file_path (str | Path): 输出文件路径
pypmxvmd.load_vmd(file_path, more_info=False) -> VmdMotion¶
加载VMD动作文件。
参数:
- file_path (str | Path): VMD文件路径
- more_info (bool): 是否显示详细解析信息
返回: VmdMotion 对象
pypmxvmd.save_vmd(motion, file_path)¶
保存VMD动作文件。
参数:
- motion (VmdMotion): VMD动作对象
- file_path (str | Path): 输出文件路径
pypmxvmd.load_pmx(file_path, more_info=False) -> PmxModel¶
加载PMX模型文件。
参数:
- file_path (str | Path): PMX文件路径
- more_info (bool): 是否显示详细解析信息
返回: PmxModel 对象
pypmxvmd.save_pmx(model, file_path)¶
保存PMX模型文件。
参数:
- model (PmxModel): PMX模型对象
- file_path (str | Path): 输出文件路径
pypmxvmd.load_vpd(file_path, more_info=False) -> VpdPose¶
加载VPD姿势文件。
参数:
- file_path (str | Path): VPD文件路径
- more_info (bool): 是否显示详细解析信息
返回: VpdPose 对象
pypmxvmd.save_vpd(pose, file_path)¶
保存VPD姿势文件。
参数:
- pose (VpdPose): VPD姿势对象
- file_path (str | Path): 输出文件路径
文本文件操作¶
PyPMXVMD 还支持文本格式的读写,便于人工编辑和查看。
pypmxvmd.load_vmd_text(file_path, more_info=False) -> VmdMotion¶
从文本格式加载VMD动作。
pypmxvmd.save_vmd_text(motion, file_path)¶
将VMD动作保存为文本格式。
pypmxvmd.load_pmx_text(file_path, more_info=False) -> PmxModel¶
从文本格式加载PMX模型。
pypmxvmd.save_pmx_text(model, file_path)¶
将PMX模型保存为文本格式。
pypmxvmd.load_vpd_text(file_path, more_info=False) -> VpdPose¶
从文本格式加载VPD姿势。
pypmxvmd.save_vpd_text(pose, file_path)¶
将VPD姿势保存为文本格式。
pypmxvmd.load_text(file_path, more_info=False) -> VmdMotion | PmxModel | VpdPose¶
自动检测文本文件格式并加载。
参数:
- file_path (str | Path): 文本文件路径
- more_info (bool): 是否显示详细解析信息
返回: VmdMotion | PmxModel | VpdPose
pypmxvmd.save_text(data, file_path)¶
自动检测数据类型并保存为对应文本格式。
参数:
- data: VmdMotion | PmxModel | VpdPose 对象
- file_path (str | Path): 输出文本文件路径
数据模型¶
VMD模型¶
VMD (Vocaloid Motion Data) 用于存储动作和相机数据。
VmdMotion¶
VMD动作主类,包含所有动作数据。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
header |
VmdHeader |
文件头信息 |
bone_frames |
List[VmdBoneFrame] |
骨骼关键帧列表 |
morph_frames |
List[VmdMorphFrame] |
变形关键帧列表 |
camera_frames |
List[VmdCameraFrame] |
相机关键帧列表 |
light_frames |
List[VmdLightFrame] |
光照关键帧列表 |
shadow_frames |
List[VmdShadowFrame] |
阴影关键帧列表 |
ik_frames |
List[VmdIkFrame] |
IK显示关键帧列表 |
方法:
VmdHeader¶
VMD文件头信息。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
version |
int |
VMD版本 (1=旧版, 2=新版) |
model_name |
str |
模型名称 (日文) |
VmdBoneFrame¶
骨骼关键帧。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
bone_name |
str |
骨骼名称 (日文,最大15字节) |
frame_number |
int |
帧号 (≥0) |
position |
List[float] |
位置 [x, y, z] |
rotation |
List[float] |
旋转欧拉角 [x, y, z] (度) |
interpolation |
List[int] |
插值曲线数据 (16个值) |
physics_disabled |
bool |
是否禁用物理 |
VmdMorphFrame¶
变形关键帧。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
morph_name |
str |
变形名称 (日文,最大15字节) |
frame_number |
int |
帧号 (≥0) |
weight |
float |
权重值 (0.0-1.0) |
VmdCameraFrame¶
相机关键帧。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
frame_number |
int |
帧号 |
distance |
float |
到目标的距离 |
position |
List[float] |
目标位置 [x, y, z] |
rotation |
List[float] |
相机旋转 [x, y, z] (度数,读取时由弧度转换) |
interpolation |
List[int] |
插值曲线数据 (24个值) |
fov |
int |
视野角度 (1-180) |
perspective |
bool |
是否透视投影 |
VmdLightFrame¶
光照关键帧。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
frame_number |
int |
帧号 |
color |
List[float] |
光照颜色 [r, g, b] (0.0-1.0) |
position |
List[float] |
光照位置 [x, y, z] |
VmdShadowFrame¶
阴影关键帧。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
frame_number |
int |
帧号 |
shadow_mode |
ShadowMode |
阴影模式 |
distance |
float |
阴影距离 |
VmdIkFrame¶
IK显示关键帧。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
frame_number |
int |
帧号 |
display |
bool |
是否显示模型 |
ik_bones |
List[VmdIkBone] |
IK骨骼列表 |
VmdIkBone¶
IK骨骼信息。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
bone_name |
str |
IK骨骼名称 (最大20字节) |
ik_enabled |
bool |
是否启用IK |
PMX模型¶
PMX (Polygon Model eXtended) 用于存储3D模型数据。
PmxModel¶
PMX模型主类。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
header |
PmxHeader |
文件头信息 |
vertices |
List[PmxVertex] |
顶点列表 |
faces |
List[List[int]] |
面索引列表 (每面3个顶点索引) |
textures |
List[str] |
纹理路径列表 |
materials |
List[PmxMaterial] |
材质列表 |
bones |
List[PmxBone] |
骨骼列表 |
morphs |
List[PmxMorph] |
变形列表 |
frames |
List[PmxFrame] |
显示框架列表 |
rigidbodies |
List[PmxRigidBody] |
刚体列表 |
joints |
List[PmxJoint] |
关节列表 |
softbodies |
List[PmxSoftBody] |
软体列表 (PMX 2.1) |
方法:
PmxHeader¶
PMX文件头信息。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
version |
float |
PMX版本号 (2.0 或 2.1) |
name_jp |
str |
日文名称 |
name_en |
str |
英文名称 |
comment_jp |
str |
日文注释 |
comment_en |
str |
英文注释 |
PmxVertex¶
PMX顶点数据。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
position |
List[float] |
位置 [x, y, z] |
normal |
List[float] |
法线 [x, y, z] |
uv |
List[float] |
UV坐标 [u, v] |
additional_uvs |
List[List[float]] |
额外UV列表 |
weight_mode |
WeightMode |
权重模式 |
weight |
List[List] |
权重数据 [[bone_idx, weight], ...] |
edge_scale |
float |
边缘缩放 |
PmxMaterial¶
PMX材质数据。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
name_jp |
str |
日文名称 |
name_en |
str |
英文名称 |
diffuse_color |
List[float] |
漫反射色 [r, g, b, a] |
specular_color |
List[float] |
镜面反射色 [r, g, b] |
specular_strength |
float |
镜面反射强度 |
ambient_color |
List[float] |
环境光色 [r, g, b] |
flags |
MaterialFlags |
材质标志位 |
edge_color |
List[float] |
边缘颜色 [r, g, b, a] |
edge_size |
float |
边缘大小 |
texture_path |
str |
纹理路径 |
sphere_path |
str |
球面纹理路径 |
sphere_mode |
SphMode |
球面纹理模式 |
toon_path |
str |
卡通渲染纹理路径 |
comment |
str |
注释 |
face_count |
int |
面顶点数 |
MaterialFlags¶
材质标志位类。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
double_sided |
bool |
双面显示 |
ground_shadow |
bool |
地面阴影 |
self_shadow_map |
bool |
自阴影贴图 |
self_shadow |
bool |
自阴影 |
edge_drawing |
bool |
边缘绘制 |
vertex_color |
bool |
顶点色 |
point_drawing |
bool |
点绘制 |
line_drawing |
bool |
线绘制 |
PmxBone¶
PMX骨骼数据。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
name_jp |
str |
日文名称 |
name_en |
str |
英文名称 |
position |
List[float] |
位置 [x, y, z] |
parent_index |
int |
父骨骼索引 (-1表示无父骨骼) |
deform_layer |
int |
变形层级 |
bone_flags |
BoneFlags |
骨骼标志位 |
tail |
int \| List[float] |
尾端 (骨骼索引或偏移量) |
inherit_parent_index |
int |
继承父索引 |
inherit_ratio |
float |
继承比率 |
fixed_axis |
List[float] |
固定轴 |
local_axis_x |
List[float] |
本地X轴 |
local_axis_z |
List[float] |
本地Z轴 |
external_parent_index |
int |
外部父索引 |
ik_target_index |
int |
IK目标索引 |
ik_loop_count |
int |
IK循环次数 |
ik_angle_limit |
float |
IK角度限制 |
ik_links |
List[PmxBoneIkLink] |
IK链接列表 |
PmxMorph¶
PMX变形数据。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
name_jp |
str |
日文名称 |
name_en |
str |
英文名称 |
panel |
MorphPanel |
面板位置 |
morph_type |
MorphType |
变形类型 |
items |
List |
变形项目列表 |
PmxRigidBody¶
PMX刚体数据。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
name_jp |
str |
日文名称 |
name_en |
str |
英文名称 |
bone_index |
int |
关联骨骼索引 |
group |
int |
碰撞组 |
nocollide_groups |
List[int] |
非碰撞组列表 |
shape |
RigidBodyShape |
形状类型 |
size |
List[float] |
尺寸 [x, y, z] |
position |
List[float] |
位置 [x, y, z] |
rotation |
List[float] |
旋转 [x, y, z] |
physics_mode |
RigidBodyPhysMode |
物理模式 |
mass |
float |
质量 |
move_damping |
float |
移动衰减 |
rotation_damping |
float |
旋转衰减 |
repulsion |
float |
反弹力 |
friction |
float |
摩擦力 |
PmxJoint¶
PMX关节数据。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
name_jp |
str |
日文名称 |
name_en |
str |
英文名称 |
joint_type |
JointType |
关节类型 |
rigidbody1_index |
int |
刚体1索引 |
rigidbody2_index |
int |
刚体2索引 |
position |
List[float] |
位置 |
rotation |
List[float] |
旋转 |
position_min |
List[float] |
位置最小值 |
position_max |
List[float] |
位置最大值 |
rotation_min |
List[float] |
旋转最小值 |
rotation_max |
List[float] |
旋转最大值 |
position_spring |
List[float] |
位置弹簧 |
rotation_spring |
List[float] |
旋转弹簧 |
VPD模型¶
VPD (Vocaloid Pose Data) 用于存储单帧姿势数据。
VpdPose¶
VPD姿势主类。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
model_name |
str |
模型名称 |
bone_poses |
List[VpdBonePose] |
骨骼姿势列表 |
morph_poses |
List[VpdMorphPose] |
变形姿势列表 |
方法:
VpdBonePose¶
VPD骨骼姿势。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
bone_name |
str |
骨骼名称 |
position |
List[float] |
位置 [x, y, z] |
rotation |
List[float] |
旋转四元数 [x, y, z, w] |
VpdMorphPose¶
VPD变形姿势。
属性:
| 属性 | 类型 | 说明 |
|---|---|---|
morph_name |
str |
变形名称 |
weight |
float |
权重值 (0.0-1.0) |
解析器¶
如果需要更精细的控制,可以直接使用解析器类。
解析器会在可用时自动使用 Cython 快速路径,否则回退到纯 Python 实现。
VmdParser¶
VMD文件解析器。
PmxParser¶
PMX文件解析器。
VpdParser¶
VPD文件解析器。
枚举类型¶
VMD枚举¶
ShadowMode¶
阴影模式。
| 值 | 说明 |
|---|---|
OFF (0) |
关闭 |
MODE1 (1) |
模式1 |
MODE2 (2) |
模式2 |
PMX枚举¶
WeightMode¶
顶点权重模式。
| 值 | 说明 |
|---|---|
BDEF1 (0) |
单骨骼变形 |
BDEF2 (1) |
双骨骼变形 |
BDEF4 (2) |
四骨骼变形 |
SDEF (3) |
球面变形 |
QDEF (4) |
四元数变形 |
SphMode¶
球面纹理模式。
| 值 | 说明 |
|---|---|
DISABLED (0) |
禁用 |
MULTIPLY (1) |
乘算 |
ADDITIVE (2) |
加算 |
SUBTEX (3) |
子纹理 |
MorphType¶
变形类型。
| 值 | 说明 |
|---|---|
GROUP (0) |
组变形 |
VERTEX (1) |
顶点变形 |
BONE (2) |
骨骼变形 |
UV (3) |
UV变形 |
EXTENDED_UV1 (4) |
扩展UV1变形 |
EXTENDED_UV2 (5) |
扩展UV2变形 |
EXTENDED_UV3 (6) |
扩展UV3变形 |
EXTENDED_UV4 (7) |
扩展UV4变形 |
MATERIAL (8) |
材质变形 |
FLIP (9) |
翻转变形 |
IMPULSE (10) |
冲击变形 |
MorphPanel¶
变形面板位置。
| 值 | 说明 |
|---|---|
HIDDEN (0) |
隐藏 |
EYEBROW (1) |
眉毛 (左下) |
EYE (2) |
眼睛 (左上) |
MOUTH (3) |
嘴巴 (右上) |
OTHER (4) |
其他 (右下) |
RigidBodyShape¶
刚体形状。
| 值 | 说明 |
|---|---|
SPHERE (0) |
球体 |
BOX (1) |
盒子 |
CAPSULE (2) |
胶囊 |
RigidBodyPhysMode¶
刚体物理模式。
| 值 | 说明 |
|---|---|
BONE (0) |
骨骼跟随 |
PHYSICS (1) |
物理演算 |
PHYSICS_BONE (2) |
物理演算+骨骼追随 |
JointType¶
关节类型。
| 值 | 说明 |
|---|---|
SPRING6DOF (0) |
6DOF弹簧关节 |
使用示例¶
示例1: 读取VMD动作并获取信息¶
示例2: 创建简单的PMX模型¶
示例3: 修改VMD动作¶
示例4: VPD姿势转VMD动作¶
示例5: 数据验证¶
错误处理¶
PyPMXVMD 使用标准Python异常进行错误处理:
| 异常类型 | 说明 |
|---|---|
FileNotFoundError |
文件不存在 |
ValueError |
文件格式无效或数据错误 |
IOError |
文件读写错误 |
AssertionError |
数据验证失败 |
兼容性说明¶
- VMD: 支持旧版(v1)和新版(v2)格式
- PMX: 支持2.0和2.1版本
- VPD: 支持标准VPD文本格式
- 编码: VMD使用Shift-JIS,PMX支持UTF-16LE和UTF-8,VPD使用Shift-JIS
许可证¶
MIT License