导入上游源码,为所有面向用户的品牌显示处添加「增强版 / Enhanced」标识;包含 unitypackage→VRM 的纯色 Toon 材质、兽耳 SpringBone、Unity 描边、UV 接缝白边补偿修复,以及默认不强制 T-pose。146 个单元测试通过。
This commit is contained in:
@@ -0,0 +1,400 @@
|
||||
# -*- 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())
|
||||
Reference in New Issue
Block a user