Files
VRMify-Enhanced/formats/pskio.py
T
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

523 lines
22 KiB
Python
Raw 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 -*-
"""PSK / PSKX 读取器(纯 Python 标准库,不需要 Blender / UE / FBX SDK)。
格式来源:Unreal Engine 的 ActorX 交换格式(.psk)及其扩展(.pskx)。
二进制布局以 DarklightGames/io_scene_psk_psa 的 psk_psa_py 为准,
并由本项目实测的样本文件(含 FACE3200 / VERTEXCOLOR / MRPHINFO / MRPHDATA
等扩展块)逐字段复核过。
文件结构
--------
整份文件是「块(section)」的线性序列,每个块:
struct Section { char name[20]; int32 type_flags; int32 data_size;
int32 data_count; } // 共 32 字节
紧接 data_size * data_count 字节的数据
块名与记录布局(offset 都是相对记录开头):
PNTS0000 Vector3 12 x,y,z 顶点(绑定姿势,物体空间)
VTXW0000 Wedge16 / Wedge32 16 uint32 point_index; float u, v;
uint32 material_index
FACE0000 Face16 12 uint16 i[3]; uint8 mat; uint8 aux;
int32 smoothing
FACE3200 Face32 18 uint32 i[3]; uint8 mat; uint8 aux;
int32 smoothing(紧凑排列)
MATT0000 Material 88 char name[64]; int32 ×6
REFSKELT Bone 120 char name[64]; int32 flags;
int32 children_count; int32 parent_index;
Quat rotation(x,y,z,w); Vector3 location;
float length; Vector3 size
RAWWEIGHTS Weight 12 float weight; int32 point_index;
int32 bone_index
VTXNORMS Vector3 12 顶点法线
VERTEXCOLOR Color 4 r,g,b,a(各 1 字节)
EXTRAUVS* Vector2 8 附加 UV(pskx,可有多套)
MRPHINFO MorphInfo 68 char name[64]; int32 vertex_count
MRPHDATA MorphData 28 Vector3 position_delta;
Vector3 tangent_z_delta; int32 point_index
两个实测坑(都已处理):
1) 部分游戏导出的文件在真正的 PSK 数据前面多写了 32 字节外层头(又是一个
ACTRHEAD,type_flags 位置放的是版本号 20220723)。按块序列顺序读即可自然
跳过:外层 ACTRHEAD 的 data_count=0,读完就落到第二个 ACTRHEAD 上。
2) 四元数要取共轭((x,y,z,w) → 取 (x,y,z) 的负号)后才是引擎常用右手系下
的旋转;不共轭的话骨骼世界坐标会整条链歪出去(实测头骨能偏 30 多个单位)。
"""
import os
import struct
__all__ = ["Psk", "PskBone", "PskMaterial", "PskMorph", "read_psk",
"bone_world", "quat_to_matrix", "write_psk"]
# 写入时用的块头版本号:实测样本(二重螺旋 R2T1*)的两个 ACTRHEAD 都放的是
# 20220723,照抄以保证同一套文件能被同一批工具读。标准 ActorX 写的是 1999801
# 之类的日期串,但那只是个标记,读者一般不校验。
PSK_VERSION = 20220723
# ------------------------------------------------------------------ data ---
class PskBone(object):
__slots__ = ("name", "flags", "children_count", "parent_index",
"rotation", "location", "length", "size")
def __init__(self, name, flags, children_count, parent_index,
rotation, location, length, size):
self.name = name
self.flags = flags
self.children_count = children_count
self.parent_index = parent_index
self.rotation = rotation # (x, y, z, w)
self.location = location # (x, y, z)
self.length = length
self.size = size # (x, y, z)
class PskMaterial(object):
__slots__ = ("name", "texture_index", "poly_flags", "aux_material",
"aux_flags", "lod_bias", "lod_style")
def __init__(self, name, texture_index, poly_flags, aux_material,
aux_flags, lod_bias, lod_style):
self.name = name
self.texture_index = texture_index
self.poly_flags = poly_flags
self.aux_material = aux_material
self.aux_flags = aux_flags
self.lod_bias = lod_bias
self.lod_style = lod_style
class PskMorph(object):
"""一个表情目标:名字 + 顶点位移列表 [(point_index, (dx,dy,dz)), ...]。"""
__slots__ = ("name", "offsets")
def __init__(self, name, offsets):
self.name = name
self.offsets = offsets
class Psk(object):
def __init__(self):
self.points = [] # [(x,y,z), ...]
self.wedges = [] # [(point_index, u, v, material_index), ...]
self.faces = [] # [((i0,i1,i2), material_index), ...]
self.materials = [] # [PskMaterial, ...]
self.bones = [] # [PskBone, ...]
self.weights = [] # [(weight, point_index, bone_index), ...]
self.normals = [] # [(x,y,z), ...]
self.colors = [] # [(r,g,b,a), ...]
self.extra_uvs = [] # [[(u,v), ...], ...]
self.morphs = [] # [PskMorph, ...]
self.face32 = False # 索引用的是 FACE3200(32 位)还是 FACE0000
@property
def has_normals(self):
return bool(self.normals)
@property
def has_morphs(self):
return bool(self.morphs)
# ------------------------------------------------------------------ math ---
def quat_to_matrix(q):
"""(x, y, z, w) → 3×3 旋转矩阵。
列向量约定:v' = M · v(与 bone_world / _mvec / _mmul 一致,别写成转置)。
校验:绕 Z 轴 +90° 的四元数 (0,0,0.7071,0.7071) 应把 (1,0,0) 变成 (0,1,0)。
"""
x, y, z, w = q
return ((1 - 2 * (y * y + z * z), 2 * (x * y - z * w), 2 * (x * z + y * w)),
(2 * (x * y + z * w), 1 - 2 * (x * x + z * z), 2 * (y * z - x * w)),
(2 * (x * z - y * w), 2 * (y * z + x * w), 1 - 2 * (x * x + y * y)))
def _mmul(a, b):
return tuple(tuple(sum(a[i][k] * b[k][j] for k in range(3))
for j in range(3)) for i in range(3))
def _mvec(m, v):
"""列向量:M · v。"""
return tuple(sum(m[i][k] * v[k] for k in range(3)) for i in range(3))
def bone_world(psk):
"""算每根骨骼的世界(物体空间)旋转矩阵与位置。
PSK 的 rotation/location 都是**相对父骨骼**的局部值,世界值沿父链累乘。
四元数先取共轭再转成矩阵(见文件头注释第 2 点)。
返回 (world_rot, world_pos),都是按骨骼下标索引的列表。
"""
bones = psk.bones
n = len(bones)
wrot = [None] * n
wpos = [None] * n
state = [0] * n # 0 未算 / 1 计算中 / 2 已完成
def calc(i, depth=0):
if state[i] == 2 or depth > 512:
return
if state[i] == 1: # 环:当成根,别死循环
x, y, z, w = bones[i].rotation
wrot[i] = quat_to_matrix((-x, -y, -z, w))
wpos[i] = tuple(bones[i].location)
state[i] = 2
return
state[i] = 1
b = bones[i]
x, y, z, w = b.rotation
r = quat_to_matrix((-x, -y, -z, w))
p = b.parent_index
if p < 0 or p >= n or p == i:
wrot[i] = r
wpos[i] = tuple(b.location)
else:
calc(p, depth + 1)
pr, pt = wrot[p], wpos[p]
if pr is None:
wrot[i] = r
wpos[i] = tuple(b.location)
else:
wrot[i] = _mmul(pr, r)
t = _mvec(pr, b.location)
wpos[i] = (pt[0] + t[0], pt[1] + t[1], pt[2] + t[2])
state[i] = 2
for i in range(n):
calc(i)
for i in range(n):
if wrot[i] is None:
x, y, z, w = bones[i].rotation
wrot[i] = quat_to_matrix((-x, -y, -z, w))
wpos[i] = tuple(bones[i].location)
return wrot, wpos
# ----------------------------------------------------------------- reader ---
def _cstr(raw):
return raw.split(b"\x00")[0].decode("ascii", "replace")
def read_psk(path):
"""读 .psk / .pskx,返回 Psk。"""
with open(path, "rb") as fp:
data = fp.read()
psk = Psk()
off = 0
total = len(data)
morph_infos = [] # [(name, vertex_count), ...]
morph_raw = [] # [(delta, tangent_z, point_index), ...]
while off + 32 <= total:
name = data[off:off + 20].split(b"\x00")[0]
if not name or not all(32 < c < 127 for c in name):
break # 不是块头了(尾部填充 / 未知数据)
try:
_flag, dsize, dcount = struct.unpack_from("<iii", data, off + 20)
except struct.error:
break
body = off + 32
nbytes = dsize * dcount
# 注意:ACTRHEAD 这类「空块」的 data_size/data_count 都是 0,不能因此
# 判为块头不可信就中断,否则一上来就什么都读不到。
if dsize < 0 or dcount < 0 or body + nbytes > total:
break # 块头不可信,停在这里
nm = name.decode("ascii")
if nm == "PNTS0000" and dsize >= 12:
psk.points = [struct.unpack_from("<3f", data, body + i * dsize)
for i in range(dcount)]
elif nm == "VTXW0000":
if dsize >= 16:
psk.wedges = [struct.unpack_from("<IffI", data, body + i * dsize)
for i in range(dcount)]
elif dsize >= 12: # 老式 16 位 point_index
for i in range(dcount):
pi = struct.unpack_from("<H", data, body + i * dsize)[0]
u, v = struct.unpack_from("<ff", data, body + i * dsize + 4)
psk.wedges.append((pi, u, v, 0))
elif nm == "FACE0000" and dsize >= 12:
for i in range(dcount):
o = body + i * dsize
a, b, c = struct.unpack_from("<3H", data, o)
psk.faces.append(((a, b, c), data[o + 6]))
psk.face32 = False
elif nm == "FACE3200" and dsize >= 18:
for i in range(dcount):
o = body + i * dsize
a, b, c = struct.unpack_from("<3I", data, o)
psk.faces.append(((a, b, c), data[o + 12]))
psk.face32 = True
elif nm == "MATT0000" and dsize >= 88:
for i in range(dcount):
o = body + i * dsize
psk.materials.append(PskMaterial(
_cstr(data[o:o + 64]),
*struct.unpack_from("<6i", data, o + 64)))
elif nm == "REFSKELT" and dsize >= 120:
for i in range(dcount):
o = body + i * dsize
psk.bones.append(PskBone(
_cstr(data[o:o + 64]),
*struct.unpack_from("<3i", data, o + 64),
rotation=struct.unpack_from("<4f", data, o + 76),
location=struct.unpack_from("<3f", data, o + 92),
length=struct.unpack_from("<f", data, o + 104)[0],
size=struct.unpack_from("<3f", data, o + 108)))
elif nm == "RAWWEIGHTS" and dsize >= 12:
psk.weights = [struct.unpack_from("<fii", data, body + i * dsize)
for i in range(dcount)]
elif nm == "VTXNORMS" and dsize >= 12:
psk.normals = [struct.unpack_from("<3f", data, body + i * dsize)
for i in range(dcount)]
elif nm == "VERTEXCOLOR" and dsize >= 4:
psk.colors = [tuple(data[body + i * dsize: body + i * dsize + 4])
for i in range(dcount)]
elif nm == "MRPHINFO" and dsize >= 68:
for i in range(dcount):
o = body + i * dsize
morph_infos.append((_cstr(data[o:o + 64]),
struct.unpack_from("<i", data, o + 64)[0]))
elif nm == "MRPHDATA" and dsize >= 28:
for i in range(dcount):
o = body + i * dsize
morph_raw.append((struct.unpack_from("<3f", data, o),
struct.unpack_from("<3f", data, o + 12),
struct.unpack_from("<i", data, o + 24)[0]))
elif nm.startswith("EXTRAUVS") and dsize >= 8:
psk.extra_uvs.append([struct.unpack_from("<2f", data,
body + i * dsize)
for i in range(dcount)])
# 其余块(含 ACTRHEAD)直接按大小跳过
off = body + nbytes
# 16 位 point_index 的老工具会把高 16 位写成垃圾;点数还装得下 16 位时
# 统一截掉高位(与 psk_psa_py 的 read_psk 同口径)。
if psk.points and len(psk.points) <= 65536:
psk.wedges = [(w[0] & 0xFFFF, w[1], w[2], w[3]) for w in psk.wedges]
# MRPHDATA 是按 MRPHINFO 的顺序连续排布的:第 i 个表情吃前 vertex_count 条。
if morph_infos and morph_raw:
pos = 0
for name, cnt in morph_infos:
chunk = morph_raw[pos:pos + max(0, cnt)]
pos += max(0, cnt)
offs = [(pi, d) for d, _tz, pi in chunk
if abs(d[0]) + abs(d[1]) + abs(d[2]) > 1e-9]
if offs:
psk.morphs.append(PskMorph(name, offs))
if pos < len(morph_raw): # 名字数和数据条数对不上,兜底塞成一个
rest = [(pi, d) for d, _tz, pi in morph_raw[pos:]
if abs(d[0]) + abs(d[1]) + abs(d[2]) > 1e-9]
if rest:
psk.morphs.append(PskMorph("morph_rest", rest))
return psk
# ----------------------------------------------------------------- writer ---
# 写入的块顺序照抄实测样本(读的一侧对顺序不敏感,但保持一致最省事):
# ACTRHEAD ×2 → PNTS0000 → VTXW0000 → FACE0000/FACE3200 → MATT0000
# → VTXNORMS → REFSKELT → RAWWEIGHTS → VERTEXCOLOR → EXTRAUVS*
# → MRPHINFO → MRPHDATA
# 其中 VTXNORMS / VERTEXCOLOR / EXTRAUVS* / MRPH* 都属于「非标准扩展块」
# (DarklightGames 插件把带这些块的文件叫 .pskx,且只导进不导出),
# 所以 pskx=False 时会整段跳过,写出的就是 Epic 那套标准 .psk。
def _chunk(name, dsize, dcount, payload, flag=0):
head = name.encode("ascii")[:20].ljust(20, b"\x00")
return head + struct.pack("<iii", flag, dsize, dcount) + payload
def _fix_bones(psk):
"""写之前把 children_count / length 补齐。
children_count = 直接子骨数;length = 到第一个子骨的距离。
PSK 骨骼只带平移(本项目写出的都是单位四元数),所以「到子骨的局部平移
长度」就等于世界距离,不用再累乘一条链。
"""
n = len(psk.bones)
kids = [[] for _ in range(n)]
for i, b in enumerate(psk.bones):
p = b.parent_index
if 0 <= p < n and p != i:
kids[p].append(i)
for i, b in enumerate(psk.bones):
b.children_count = len(kids[i])
if kids[i]:
c = psk.bones[kids[i][0]].location
b.length = (c[0] ** 2 + c[1] ** 2 + c[2] ** 2) ** 0.5
else:
b.length = 0.0
return psk
def _pad(seq, n, fill):
"""把 seq 补/截到长度 n(缺的用 fill 填,多出来的丢掉)。"""
seq = list(seq)
if len(seq) >= n:
return seq[:n]
return seq + [fill] * (n - len(seq))
def write_psk(psk, path, pskx=True, version=None, headers=2, face32=None,
log=None):
"""把 Psk 写成 .psk / .pskx 二进制,返回字节数。
pskx : True → 连 VTXNORMS / VERTEXCOLOR / EXTRAUVS* / MRPH* 一起写
(信息最全,与实测样本一致)
False → 只写标准块(PNTS/VTXW/FACE/MATT/REFSKELT/RAWWEIGHTS),
扩展内容会被丢弃并在日志里计数
face32 : None 自动(顶点数 > 65535 就用 FACE3200),也可强制 True/False
headers : 开头的 ACTRHEAD 个数,实测样本是 2(外层那个是游戏多写的)
"""
def _l(msg, tag=None):
if log:
log(msg, tag)
n_point = len(psk.points)
n_wedge = len(psk.wedges)
# ---- 索引合法性:越界的一律夹回范围内,别写出打不开的文件
bad_w = 0
wedges = []
for pi, u, v, mi in psk.wedges:
ip = int(pi)
if not (0 <= ip < n_point) and n_point:
ip = min(max(ip, 0), n_point - 1)
bad_w += 1
wedges.append((ip, float(u), float(v), int(mi or 0)))
if bad_w:
_l("提示:%d 个楔的点索引越界,已夹回合法范围" % bad_w, "warn")
max_idx = 0
for f in psk.faces:
try:
max_idx = max(max_idx, int(f[0][0]), int(f[0][1]), int(f[0][2]))
except (TypeError, IndexError, ValueError):
pass
if face32 is None:
face32 = bool(getattr(psk, "face32", False)) or max_idx > 0xFFFF or \
n_wedge > 0xFFFF
if not face32 and (max_idx > 0xFFFF or n_wedge > 0xFFFF):
_l("提示:顶点数 %d 超过 16 位索引上限,已改用 FACE3200" % n_wedge,
"warn")
face32 = True
bad_f = 0
faces = []
for tri, mi in psk.faces:
a, b, c = int(tri[0]), int(tri[1]), int(tri[2])
if n_wedge and not (0 <= a < n_wedge and 0 <= b < n_wedge
and 0 <= c < n_wedge):
bad_f += 1
faces.append(((a, b, c), int(mi or 0)))
if bad_f:
_l("提示:%d 个面的楔索引越界(文件可能显示为破面)" % bad_f, "warn")
out = []
ver = int(version if version is not None else PSK_VERSION)
for _ in range(int(headers)):
out.append(_chunk("ACTRHEAD", 0, 0, b"", ver))
out.append(_chunk("PNTS0000", 12, n_point,
b"".join(struct.pack("<3f", *p) for p in psk.points)))
out.append(_chunk("VTXW0000", 16, n_wedge,
b"".join(struct.pack("<IffI", *w) for w in wedges)))
if face32:
out.append(_chunk("FACE3200", 18, len(faces),
b"".join(struct.pack("<3IBBi", t[0], t[1], t[2],
m, 0, 0) for t, m in faces)))
else:
out.append(_chunk("FACE0000", 12, len(faces),
b"".join(struct.pack("<3HBBi", t[0], t[1], t[2],
m, 0, 0) for t, m in faces)))
nm = len(psk.materials)
out.append(_chunk("MATT0000", 88, nm,
b"".join(struct.pack("<64s6i",
(x.name or "").encode(
"ascii", "replace")[:63]
.ljust(64, b"\x00"),
int(x.texture_index or 0),
int(x.poly_flags or 0),
int(x.aux_material or 0),
int(x.aux_flags or 0),
int(x.lod_bias or 0),
int(x.lod_style or 0))
for x in psk.materials)))
if pskx:
nrm = _pad(psk.normals, n_wedge, (0.0, 0.0, 1.0))
# 法线按「楔」存(和 EXTRAUVS / VERTEXCOLOR 一样是一楔一条)
out.append(_chunk("VTXNORMS", 12, n_wedge,
b"".join(struct.pack("<3f", *n) for n in nrm)))
_fix_bones(psk)
nb = len(psk.bones)
bb = []
for b in psk.bones:
q = _pad(tuple(b.rotation or ()), 4, 0.0)
sz = _pad(tuple(b.size or ()), 3, 1.0)
bb.append(struct.pack(
"<64s3i4f3ff3f",
(b.name or "").encode("ascii", "replace")[:63].ljust(64, b"\x00"),
int(b.flags or 0), int(b.children_count or 0),
int(b.parent_index if b.parent_index is not None else -1),
float(q[0]), float(q[1]), float(q[2]), float(q[3]),
float(b.location[0]), float(b.location[1]), float(b.location[2]),
float(b.length or 0.0),
float(sz[0]), float(sz[1]), float(sz[2])))
out.append(_chunk("REFSKELT", 120, nb, b"".join(bb)))
nw = len(psk.weights)
out.append(_chunk("RAWWEIGHTS", 12, nw,
b"".join(struct.pack("<fii", float(w), int(pi), int(bi))
for w, pi, bi in psk.weights)))
if pskx:
col = _pad(psk.colors, n_wedge, (255, 255, 255, 255))
out.append(_chunk("VERTEXCOLOR", 4, n_wedge,
b"".join(struct.pack("<4B", *c[:4]) for c in col)))
for k, uv in enumerate(psk.extra_uvs[:8]):
seq = _pad(uv, n_wedge, (0.0, 0.0))
out.append(_chunk("EXTRAUVS%d" % k, 8, n_wedge,
b"".join(struct.pack("<2f", *t[:2])
for t in seq)))
infos = []
data = []
for mo in psk.morphs:
offs = [(int(pi), tuple(d)) for pi, d in mo.offsets
if 0 <= int(pi) < n_point]
if not offs:
continue
infos.append((mo.name, len(offs)))
for pi, d in offs:
data.append((d, pi))
if infos:
out.append(_chunk(
"MRPHINFO", 68, len(infos),
b"".join(struct.pack("<64si",
(nm_ or "").encode("ascii", "replace")
[:63].ljust(64, b"\x00"), c_)
for nm_, c_ in infos)))
out.append(_chunk(
"MRPHDATA", 28, len(data),
b"".join(struct.pack("<3f3fi", d[0], d[1], d[2], 0.0, 0.0,
0.0, pi) for d, pi in data)))
blob = b"".join(out)
d = os.path.dirname(os.path.abspath(path))
if d:
os.makedirs(d, exist_ok=True)
tmp = path + ".tmp"
with open(tmp, "wb") as fp:
fp.write(blob)
os.replace(tmp, path)
_l("PSK:顶点 %d · 楔 %d · 面 %d · 骨骼 %d · 材质 %d · 权重 %d%s"
% (n_point, n_wedge, len(faces), nb, nm, nw,
(" · 表情 %d" % len(psk.morphs)) if (pskx and psk.morphs) else ""),
"info")
return len(blob)