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

401 lines
14 KiB
Python
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.
# -*- coding: utf-8 -*-
"""XPS / XNALara 模型读取器(纯 Python 标准库,不需要 Blender / XPS 本体)。
格式来源
--------
XNALara(后被 XPS / XNA Posing Studio 继承)的二进制模型格式。字段布局以
GLLara 的公开文档 `Documentation/XNALara Model File Format.md` 为准,并由本项目
实测样本(轩辕剑柒 chu hong,XPS 11.8 导出)逐字段复核过。
两种变体
--------
1) **Generic Item 2**(XPS 自己的格式,现在最常遇到)
第一个 uint32 是魔数 323232(0x0004EEA0),据此识别:
uint32 magic = 323232
uint16 majorVersion
uint16 minorVersion
string toolAuthor // 固定 "XNAaraL"
uint32 countOfUnknownInts
string unknownString1 // 作者名 / 机器名,不需要
string unknownString2
string unknownString3 // 含原始文件路径
uint32 unknownInts[countOfUnknownInts]
uint32 numBones
Bone bones[numBones]
uint32 numMeshes
Mesh meshes[numMeshes]
... // 之后还有一段与转换无关的尾部数据
2) **旧版 XNALara 二进制**(没有魔数,直接就是 numBones)
结构与上面相同,只是没有 header 那一段;顶点里**多一套切线**。
要判断是哪种,只看文件头 4 字节是不是 323232 即可(文档明确这么写)。
骨骼
----
string name
uint16 parentIndex // 65535(0xFFFF) = 没有父级
float defaultPositionX // **世界坐标**,不是相对父级的位移
float defaultPositionY
float defaultPositionZ
网格
----
string name
uint32 numUVLayers
uint32 numTextures
Texture textures[numTextures] // { string filename; uint32 uvLayer; }
uint32 numVertices
Vertex vertices[numVertices]
uint32 numTriangles // ⚠ 是**三角面数**,不是索引数
uint32 indices[numTriangles * 3] // 索引数组长度是三角面数的 3 倍
顶点(随版本/UV 层数/是否有骨骼而变)
-------------------------------------
通用项:
float vertex[3]
float normal[3]
uint8 color[4]
float texCoord[2][numUVLayers]
只有旧版 XNALara(非 Generic Item 2)**且** majorVersion < 2 时才有:
float tangent[4][numUVLayers]
有骨骼时:
// Generic Item 2 且 majorVersion >= 3:
uint16 boneCountForVertex // 每顶点独立,通常 4,也可能更高
uint16 boneIndex[boneCountForVertex]
float boneWeight[boneCountForVertex]
// 其余情况:固定 4 根
uint16 boneIndex[4]
float boneWeight[4]
实测记录(轩辕剑柒 chu hong,majorVersion=3,minorVersion=15)
-----------------------------------------------------------
* 136 根骨骼 / 9 个网格 / 57415 顶点 / 82592 三角面,全部自洽。
* 每个顶点 boneCount 恒为 4,顶点步长 62 字节(1 套 UV)。
* 轴向实测:`head eyeball left` 在 +X、`head eyeball right` 在 -X → **+X = 左**;
`head nose tip` 与 `leg left toes` 的 Z 都**大于**各自的父级(鼻尖 1.030 > 头根
0.925,脚尖 0.974 > 脚踝 0.879)→ **+Z = 正面**;`root ground` 在 y=0、头顶
y≈1.71(米)→ **+Y = 上**。也就是「左手 +X、正面 +Z、上 +Y」的**右手系**。
MMD/PMX 是「左手 +X、正面 -Z、上 +Y」,所以只要**把 Z 取反**即可对齐
(详见 convert/xps2pmx.py 里 xf() 的说明)。
* 尾部还有 129 字节与模型无关的数据,读完最后一个网格直接停即可。
"""
import os
import struct
__all__ = ["Xps", "XpsBone", "XpsMesh", "read_xps", "XPS_MAGIC"]
# Generic Item 2 的魔数:0x0004EEA0 == 323232
XPS_MAGIC = 323232
# 顶点里索引/权重最多取多少根(PMX 上限就是 4,这里读进来后由转换器再裁)
MAX_BONES_PER_VERTEX = 64
class XpsBone(object):
__slots__ = ("name", "parent_index", "position")
def __init__(self, name, parent_index, position):
self.name = name
self.parent_index = parent_index # 65535 = 无父级
self.position = position # (x, y, z) 世界坐标
class XpsMesh(object):
__slots__ = ("name", "uv_layers", "textures", "positions", "normals",
"colors", "uvs", "bone_indices", "bone_weights",
"triangles", "bone_counts")
def __init__(self, name, uv_layers):
self.name = name
self.uv_layers = uv_layers
self.textures = [] # [(filename, uv_layer), ...]
self.positions = [] # [(x, y, z), ...]
self.normals = [] # [(x, y, z), ...]
self.colors = [] # [(r, g, b, a), ...]
self.uvs = [] # [(u, v), ...] 第 0 套(MMD 只吃第 0 套)
self.bone_indices = [] # [[bone_index, ...], ...]
self.bone_weights = [] # [[weight, ...], ...]
self.bone_counts = [] # [int, ...] 每个顶点的权重根数
self.triangles = [] # [(i0, i1, i2), ...]
@property
def n_vertices(self):
return len(self.positions)
@property
def n_triangles(self):
return len(self.triangles)
@property
def diffuse(self):
"""基础色贴图文件名:XPS 约定 textures[0] 就是 diffuse。
实测样本里 4 张一组时顺序是 `_d / _l / _n / _s`(漫反射 / 光照图 /
法线 / 高光),只有 1 张时就是 `_d`,所以取第 0 个总是对的。
"""
return self.textures[0][0] if self.textures else ""
class Xps(object):
def __init__(self):
self.magic = 0
self.version_major = 0
self.version_minor = 0
self.author = ""
self.paths = [] # header 里那三条字符串(作者名/机器名/路径)
self.is_generic2 = False # True = XPS 的 Generic Item 2
self.bones = [] # [XpsBone, ...]
self.meshes = [] # [XpsMesh, ...]
self.tail = b"" # 网格之后的剩余字节(与转换无关)
@property
def n_vertices(self):
return sum(len(m.positions) for m in self.meshes)
@property
def n_triangles(self):
return sum(len(m.triangles) for m in self.meshes)
# ------------------------------------------------------------------ 读取 ------
class _R(object):
"""把整份文件读进内存后按偏移取数(比逐字段 read() 快得多)。"""
__slots__ = ("d", "o", "n")
def __init__(self, data):
self.d = data
self.o = 0
self.n = len(data)
def need(self, k):
if self.o + k > self.n:
raise ValueError("文件在偏移 %d 处提前结束(还需 %d 字节,仅剩 %d)"
% (self.o, k, self.n - self.o))
def u8(self):
v = self.d[self.o]
self.o += 1
return v
def u16(self):
self.need(2)
v = struct.unpack_from("<H", self.d, self.o)[0]
self.o += 2
return v
def u32(self):
self.need(4)
v = struct.unpack_from("<I", self.d, self.o)[0]
self.o += 4
return v
def vec(self, k):
self.need(4 * k)
v = struct.unpack_from("<%df" % k, self.d, self.o)
self.o += 4 * k
return v
def raw(self, k):
self.need(k)
v = self.d[self.o:self.o + k]
self.o += k
return v
def string(self):
"""XPS 的字符串:长度用「每字节 7 位、低位在前」的变长编码,再接原文。
文档原话:`Only the bottom seven bits of a byte are considered. If the
top bit is set, the next byte is length too.` 实测 'XNAaraL' 是单字节
长度 7;152 字节的长路径是 `0x98 0x01` → 0x18 | (1<<7) = 152,确认无误。
字符串不带结束符。
"""
ln = 0
shift = 0
while True:
b = self.u8()
ln |= (b & 0x7f) << shift
if not (b & 0x80):
break
shift += 7
if shift > 28:
raise ValueError("字符串长度编码异常(偏移 %d)" % (self.o - 1))
if ln == 0:
return ""
raw = self.raw(ln)
try:
return raw.decode("utf-8")
except UnicodeDecodeError:
return raw.decode("latin-1")
def _read_bones(r):
n = r.u32()
if n > 100000:
raise ValueError("骨骼数异常(%d),文件可能不是 XPS 或已损坏" % n)
bones = []
for _ in range(n):
name = r.string()
parent = r.u16()
pos = r.vec(3)
bones.append(XpsBone(name, 0xFFFF if parent == 0xFFFF else parent, pos))
return bones
def _read_vertex(r, nuv, has_bones, has_tangent, variable_bone_count):
"""读一个顶点,返回 (pos, nrm, col, uv0, idxs, wts)。"""
pos = r.vec(3)
nrm = r.vec(3)
col = struct.unpack_from("<4B", r.d, r.o)
r.o += 4
uvs = r.vec(2 * nuv) if nuv else ()
if has_tangent:
r.o += 16 * nuv # 旧版才有切线,MMD 用不上,跳过
idxs = ()
wts = ()
if has_bones:
if variable_bone_count:
bc = r.u16()
if bc > MAX_BONES_PER_VERTEX:
raise ValueError("顶点权重根数异常(%d)" % bc)
else:
bc = 4
if bc:
r.need(2 * bc + 4 * bc)
idxs = struct.unpack_from("<%dH" % bc, r.d, r.o)
r.o += 2 * bc
wts = struct.unpack_from("<%df" % bc, r.d, r.o)
r.o += 4 * bc
uv0 = (uvs[0], uvs[1]) if nuv else (0.0, 0.0)
return pos, nrm, col, uv0, idxs, wts
def _read_meshes(r, has_bones, has_tangent, variable_bone_count, log):
n_mesh = r.u32()
if n_mesh > 100000:
raise ValueError("网格数异常(%d)" % n_mesh)
meshes = []
for mi in range(n_mesh):
name = r.string()
nuv = r.u32()
ntex = r.u32()
if nuv > 8 or ntex > 64:
raise ValueError("网格 %d 的 UV 层数/贴图数异常(%d / %d)"
% (mi, nuv, ntex))
mesh = XpsMesh(name, nuv)
for _ in range(ntex):
fn = r.string()
ul = r.u32()
mesh.textures.append((fn, ul))
nv = r.u32()
if nv > 40000000:
raise ValueError("网格 %d 的顶点数异常(%d)" % (mi, nv))
mesh.positions = [None] * nv
mesh.normals = [None] * nv
mesh.colors = [None] * nv
mesh.uvs = [None] * nv
mesh.bone_indices = [None] * nv
mesh.bone_weights = [None] * nv
mesh.bone_counts = [0] * nv
for vi in range(nv):
pos, nrm, col, uv0, idxs, wts = _read_vertex(
r, nuv, has_bones, has_tangent, variable_bone_count)
mesh.positions[vi] = pos
mesh.normals[vi] = nrm
mesh.colors[vi] = col
mesh.uvs[vi] = uv0
mesh.bone_indices[vi] = idxs
mesh.bone_weights[vi] = wts
mesh.bone_counts[vi] = len(idxs)
ntri = r.u32()
if ntri > 40000000:
raise ValueError("网格 %d 的三角面数异常(%d)" % (mi, ntri))
r.need(12 * ntri)
flat = struct.unpack_from("<%dI" % (3 * ntri), r.d, r.o)
r.o += 12 * ntri
if nv:
bad = 0
tris = []
for k in range(0, len(flat), 3):
a, b, c = flat[k], flat[k + 1], flat[k + 2]
if a >= nv or b >= nv or c >= nv:
bad += 1
continue
tris.append((a, b, c))
mesh.triangles = tris
if bad and log:
log("网格 %d 有 %d 个三角面索引越界,已跳过" % (mi, bad), "warn")
meshes.append(mesh)
return meshes
def read_xps(path, log=None):
"""读取 .xps(XPS Generic Item 2 或旧版 XNALara 二进制)→ Xps。"""
with open(path, "rb") as f:
data = f.read()
if len(data) < 8:
raise ValueError("文件太小,不是 XPS 模型")
r = _R(data)
m = Xps()
m.magic = r.u32()
m.is_generic2 = (m.magic == XPS_MAGIC)
if m.is_generic2:
m.version_major = r.u16()
m.version_minor = r.u16()
m.author = r.string()
n_unk = r.u32()
if n_unk > 1000000:
raise ValueError("XPS 头部异常(countOfUnknownInts=%d)" % n_unk)
m.paths = [r.string(), r.string(), r.string()]
r.o += 4 * n_unk # 一段与模型无关的整数设置
has_bones = True
else:
# 旧版 XNALara:没有 header,第一个 uint32 就是骨骼数。
# 把已经读掉的 4 字节退回去,后面按同一套结构读。
r.o = 0
m.version_major = 1
has_bones = True
if log:
log("XPS 格式:旧版 XNALara 二进制格式(无 Generic Item 2 头)", "info")
# 切线:只有旧版 XNALara 且 majorVersion < 2 才有
has_tangent = (not m.is_generic2) and m.version_major < 2
# 变长权重根数:Generic Item 2 且 majorVersion >= 3
variable_bone_count = m.is_generic2 and m.version_major >= 3
if log:
if m.is_generic2:
log("XPS 格式:Generic Item 2 · 版本 %d.%d · 作者 %s"
% (m.version_major, m.version_minor, m.author or "?"), "info")
if has_tangent:
log("XPS 格式:旧版格式含切线数据(转换时忽略)", "info")
m.bones = _read_bones(r)
if not m.bones:
raise ValueError("文件中没有骨骼数据")
m.meshes = _read_meshes(r, has_bones, has_tangent, variable_bone_count, log)
m.tail = data[r.o:]
if not m.meshes:
raise ValueError("文件中没有网格数据")
return m
# ------------------------------------------------------------------- CLI ------
def main(argv=None):
import argparse
ap = argparse.ArgumentParser(description="查看 XPS / XNALara 模型结构")
ap.add_argument("src")
a = ap.parse_args(argv)
m = read_xps(a.src, log=lambda s, t=None: print(s))
print("骨骼 %d · 网格 %d · 顶点 %d · 三角面 %d"
% (len(m.bones), len(m.meshes), m.n_vertices, m.n_triangles))
return 0
if __name__ == "__main__":
import sys
sys.exit(main())