初始化 VRMify 增强版(VRMify Enhanced)
Tests / test (push) Has been cancelled

导入上游源码,为所有面向用户的品牌显示处添加「增强版 / Enhanced」标识;包含 unitypackage→VRM 的纯色 Toon 材质、兽耳 SpringBone、Unity 描边、UV 接缝白边补偿修复,以及默认不强制 T-pose。146 个单元测试通过。
This commit is contained in:
2026-11-15 23:21:59 +08:00
commit 60cce66993
114 changed files with 56114 additions and 0 deletions
View File
+257
View File
@@ -0,0 +1,257 @@
# -*- coding: utf-8 -*-
"""zip 以外的压缩包:7z / rar / tar(.tar .tar.gz .tgz .tar.bz2 .tar.xz)。
kind(path) → "7z" / "rar" / "tar" / None(分卷包只认第一卷)
extract(path, dest) → 解出的文件数;解不了抛 RuntimeError(说明原因和怎么办)
tools() → 找到的解压工具(界面显示用)
tar 用 Python 自带的 tarfile。7z / rar 没有可靠的纯 Python 实现,借用电脑上已有的解压工具,
按顺序找:
1. 7-Zip(7z.exe / 7za / 7zz) 7z、rar 都行
2. WinRAR(UnRAR.exe / Rar.exe) rar(新版也能解 7z,失败了再换下一个)
3. Bandizip(bz.exe) 7z、rar 都行
4. Windows 自带的 tar.exe(bsdtar / libarchive)
Windows 11 的版本 7z(含 LZMA)和 rar / rar5 都能解;Windows 10 的老版本解不了 LZMA 的 7z。
它按系统的 ANSI 编码处理文件名:简体中文系统上中文、假名没问题,GBK 里没有的字(emoji 等)
会解压失败
5. py7zr(装了才用,只管 7z)
都不行时提示装 7-Zip。
安全:只解到 dest 里(工具自己会去掉绝对路径和 ..;解完再检查一遍,跑到外面的文件删掉),
不解链接;有密码的包不会卡住等输入(stdin 关掉、给 7-Zip 一个假密码),直接报错。
"""
import os
import re
import shutil
import subprocess
import sys
import tarfile
_TAR = (".tar", ".tar.gz", ".tgz", ".tar.bz2", ".tbz2", ".tbz", ".tar.xz", ".txz")
EXTS = (".7z", ".rar") + _TAR # 文件对话框的过滤、拖放识别都用这个
_NO_WINDOW = 0x08000000 if sys.platform == "win32" else 0
def kind(path):
"""→ "7z" / "rar" / "tar" / None。分卷包(.part2.rar、.7z.002、.r00)只认第一卷。"""
n = os.path.basename(path).lower()
m = re.search(r"\.part(\d+)\.rar$", n)
if m:
return "rar" if int(m.group(1)) == 1 else None
if n.endswith(".rar"):
return "rar"
m = re.search(r"\.7z\.(\d{3})$", n)
if m:
return "7z" if int(m.group(1)) == 1 else None
if n.endswith(".7z"):
return "7z"
if n.endswith(_TAR):
return "tar"
return None
# ---- 找工具
def _reg_paths():
"""注册表里 7-Zip / WinRAR / Bandizip 的安装目录。"""
if sys.platform != "win32":
return []
import winreg
out = []
for key, vals in ((r"SOFTWARE\7-Zip", ("Path64", "Path")),
(r"SOFTWARE\WinRAR", ("exe64", "exe32")),
(r"SOFTWARE\Bandizip", ("ProgramFolder",))):
for hive in (winreg.HKEY_LOCAL_MACHINE, winreg.HKEY_CURRENT_USER):
for view in (winreg.KEY_WOW64_64KEY, winreg.KEY_WOW64_32KEY):
try:
with winreg.OpenKey(hive, key, 0, winreg.KEY_READ | view) as k:
for v in vals:
try:
p = winreg.QueryValueEx(k, v)[0]
except OSError:
continue
if p:
out.append(os.path.dirname(p) if p.lower().endswith(".exe") else p)
except OSError:
continue
return out
def _find(names, dirs):
for d in dirs:
for n in names:
p = os.path.join(d, n)
if os.path.isfile(p):
return p
for n in names:
p = shutil.which(n)
if p:
return p
return None
def _bsdtar():
"""Windows 自带的 tar.exe 是 bsdtar;Git 带的 GNU tar 解不了 7z / rar,不能用 PATH 里的。"""
cands = []
if sys.platform == "win32":
cands.append(os.path.join(os.environ.get("SystemRoot", r"C:\Windows"), "System32", "tar.exe"))
for n in ("bsdtar",):
p = shutil.which(n)
if p:
cands.append(p)
for p in cands:
if not os.path.isfile(p):
continue
try:
r = subprocess.run([p, "--version"], capture_output=True, timeout=10,
stdin=subprocess.DEVNULL, creationflags=_NO_WINDOW)
except (OSError, subprocess.SubprocessError):
continue
if b"bsdtar" in r.stdout or b"libarchive" in r.stdout:
return p
return None
_TOOLS = None
def tools(refresh=False):
"""→ {"7z": 路径, "unrar": 路径, "bandizip": 路径, "bsdtar": 路径, "py7zr": bool}(找不到为 None)。"""
global _TOOLS
if _TOOLS is None or refresh:
pf = [os.environ.get(k) for k in ("ProgramW6432", "ProgramFiles", "ProgramFiles(x86)")]
pf = [p for p in pf if p]
reg = _reg_paths()
try:
import py7zr # noqa: F401
has_py7zr = True
except Exception: # noqa: BLE001
has_py7zr = False
_TOOLS = {
"7z": _find(("7z.exe", "7za.exe", "7zz.exe", "7z", "7za", "7zz"),
reg + [os.path.join(p, "7-Zip") for p in pf]),
"unrar": _find(("UnRAR.exe", "Rar.exe", "unrar", "rar"),
reg + [os.path.join(p, "WinRAR") for p in pf]),
"bandizip": _find(("bz.exe",), reg + [os.path.join(p, "Bandizip") for p in pf]),
"bsdtar": _bsdtar(),
"py7zr": has_py7zr,
}
return _TOOLS
# ---- 解压
def _count_and_check(dest):
"""解完检查:不在 dest 里的、链接都删掉,返回普通文件数。"""
root = os.path.realpath(dest)
n = 0
for d, dirs, files in os.walk(dest):
for name in list(dirs) + files:
p = os.path.join(d, name)
if os.path.islink(p) or not os.path.realpath(p).startswith(root + os.sep):
if os.path.isdir(p) and not os.path.islink(p):
shutil.rmtree(p, ignore_errors=True)
else:
try:
os.remove(p)
except OSError:
pass
if name in dirs:
dirs.remove(name)
elif name in files:
n += 1
return n
def _safe_tar(path, dest):
n = 0
root = os.path.realpath(dest)
with tarfile.open(path) as tf:
for m in tf:
if not m.isfile(): # 目录随文件建;链接、设备文件不解
continue
parts = [p for p in m.name.replace("\\", "/").split("/") if p not in ("", ".", "..")]
if parts and ":" in parts[0]:
parts = parts[1:]
if not parts:
continue
target = os.path.join(dest, *parts)
if not os.path.realpath(target).startswith(root + os.sep):
continue
os.makedirs(os.path.dirname(target), exist_ok=True)
src = tf.extractfile(m)
if src is None:
continue
with src, open(target, "wb") as f:
shutil.copyfileobj(src, f)
n += 1
return n
def _run(cmd, timeout=1800):
try:
r = subprocess.run(cmd, capture_output=True, timeout=timeout, stdin=subprocess.DEVNULL,
creationflags=_NO_WINDOW)
except subprocess.TimeoutExpired:
return False, "超时"
except OSError as e:
return False, str(e)
msg = (r.stderr or r.stdout or b"").decode("utf-8", "replace").strip()
if not msg and r.returncode:
msg = (r.stdout or b"").decode(sys.getfilesystemencoding() or "utf-8", "replace").strip()
return r.returncode == 0, msg[-400:]
def _py7zr(path, dest):
import py7zr
with py7zr.SevenZipFile(path, "r") as z:
z.extractall(dest)
def extract(path, dest, log=None):
"""把 7z / rar / tar 压缩包解到 dest,返回解出的文件数。"""
k = kind(path)
if k is None:
raise ValueError("不是支持的压缩包:%s" % os.path.basename(path))
os.makedirs(dest, exist_ok=True)
if k == "tar":
return _safe_tar(path, dest)
t = tools()
src = os.path.abspath(path)
tries = []
if t["7z"]:
# -p 给个假密码:有密码的包直接失败,不会停在「输入密码」
tries.append(("7-Zip", [t["7z"], "x", "-y", "-bd", "-pnopassword", "-o" + dest, "--", src]))
if t["unrar"] and k == "rar":
tries.append(("WinRAR", [t["unrar"], "x", "-y", "-o+", "-p-", "-idq", src, dest + os.sep]))
if t["bandizip"]:
tries.append(("Bandizip", [t["bandizip"], "x", "-y", "-o:" + dest, src]))
if t["bsdtar"]:
tries.append(("tar", [t["bsdtar"], "-xf", src, "-C", dest]))
errors = []
for name, cmd in tries:
ok, msg = _run(cmd)
n = _count_and_check(dest)
if ok and n:
if log:
log("用 %s 解压" % name, "info")
return n
errors.append("%s:%s" % (name, msg or "没有解出文件"))
for x in os.listdir(dest): # 解了一半的清掉再换下一个工具
p = os.path.join(dest, x)
shutil.rmtree(p, ignore_errors=True) if os.path.isdir(p) else os.remove(p)
if k == "7z" and t["py7zr"]:
try:
_py7zr(src, dest)
n = _count_and_check(dest)
if n:
return n
except Exception as e: # noqa: BLE001
errors.append("py7zr:%s" % e)
hint = ("没有找到能解 %s 的工具,请安装 7-Zip(https://www.7-zip.org/)后重试,"
"或者先手动解压再把文件夹拖进来" % k)
if errors:
hint = ("解压失败。常见原因:有密码、分卷不全、文件损坏;只用 Windows 自带的 tar 时,"
"文件名里有系统编码(简体中文系统是 GBK)以外的字符、或者是 Windows 10 上 LZMA 压缩的 7z "
"都解不了——装 7-Zip(https://www.7-zip.org/)可以解决:\n " + "\n ".join(errors))
raise RuntimeError(hint)
+411
View File
@@ -0,0 +1,411 @@
"""Standalone FBX (7.x) reader —— 二进制 + ASCII 两种都读。
No Autodesk FBX SDK, no Blender. Implements the record tree + property
decoding, including zlib / delta / zigzag compressed arrays.
2026-09-18 起也支持 **ASCII FBX**(文本版):工程新加的 fbxout.py 写的就是
ASCII(文本好调试、任何 DCC 都认),不补这条读取路径的话,自己写出来的 FBX
拖回本工具会直接「not a binary FBX」,也没法做往返自校验。
两种格式解析成同一棵 FbxNode 树,下游(fbx2pmx / 预览)完全无感——
尤其注意数组:二进制里 `Vertices` 的属性就是那个长数组(props[0] = [..]),
ASCII 里数据写在子节点 `a` 里,所以解析时要把 `*N { a: ... }` 折叠成同样的
「props[0] = 数组」,否则 fbx2pmx 的 `g.get("Vertices").props[0]` 会拿到垃圾。
"""
import os
import struct
import zlib
class FbxNode:
__slots__ = ("name", "props", "children", "ps", "plen", "cls")
def __init__(self, name, props, children, ps=0, plen=0):
self.name = name
self.props = props
self.children = children
self.ps = ps # absolute offset of the property list
self.plen = plen # byte length of the property list
self.cls = props[2] if len(props) > 2 and isinstance(props[2], str) else name
def find(self, name):
return [c for c in self.children if c.name == name]
def get(self, name):
for c in self.children:
if c.name == name:
return c
return None
def walk(self):
yield self
for c in self.children:
for n in c.walk():
yield n
def __repr__(self):
return "<%s props=%d kids=%d>" % (self.name, len(self.props),
len(self.children))
def _read_prop(d, p):
t = chr(d[p])
p += 1
if t == "Y":
v = struct.unpack_from("<h", d, p)[0]
p += 2
elif t == "C":
v = d[p]
p += 1
elif t == "I":
v = struct.unpack_from("<i", d, p)[0]
p += 4
elif t == "F":
v = struct.unpack_from("<f", d, p)[0]
p += 4
elif t == "D":
v = struct.unpack_from("<d", d, p)[0]
p += 8
elif t == "L":
v = struct.unpack_from("<q", d, p)[0]
p += 8
elif t == "S":
n = struct.unpack_from("<I", d, p)[0]
p += 4
v = d[p:p + n].decode("utf-8", "replace")
p += n
elif t == "R":
n = struct.unpack_from("<I", d, p)[0]
p += 4
v = d[p:p + n]
p += n
elif t in "fdlibc":
n, enc, ln = struct.unpack_from("<III", d, p)
p += 12
raw = d[p:p + ln]
p += ln
if enc == 1:
raw = zlib.decompress(raw)
if t == "f":
v = list(struct.unpack_from("<%df" % n, raw, 0))
elif t == "d":
v = list(struct.unpack_from("<%dd" % n, raw, 0))
elif t in "il":
fmt = "<%d" % n + ("i" if t == "i" else "q")
v = list(struct.unpack_from(fmt, raw, 0))
# NOTE: Autodesk docs describe delta+zigzag for deflated integer
# arrays, but files written by the Blender exporter (verified on
# FBX 7400) store plain little-endian ints. Decoding them as
# delta produces out-of-range polygon indices, so we keep raw.
# Set FBX_INT_DELTA=1 in the environment to force delta decoding.
if enc == 1 and os.environ.get("FBX_INT_DELTA") == "1":
for i in range(1, n):
v[i] = (v[i] >> 1) ^ -(v[i] & 1)
v[i] += v[i - 1]
else:
v = list(raw)
else:
raise ValueError("unknown property type %r at %d" % (t, p))
return v, p
def _read_node(d, p, wide):
if wide:
end, nprop, plen = struct.unpack_from("<QQQ", d, p)
p += 24
else:
end, nprop, plen = struct.unpack_from("<III", d, p)
p += 12
if end == 0:
return None, p + (24 if wide else 12)
nlen = d[p]
p += 1
name = d[p:p + nlen].decode("utf-8", "replace")
p += nlen
props_start = p
props = []
for _ in range(nprop):
val, p = _read_prop(d, p)
props.append(val)
p = props_start + plen
children = []
while p < end:
ch, p2 = _read_node(d, p, wide)
if ch is None:
p = p2
break
children.append(ch)
p = p2
p = end
return FbxNode(name, props, children, props_start, plen), p
def _load_binary(path):
d = open(path, "rb").read()
assert d[:20] == b"Kaydara FBX Binary ", "not a binary FBX"
ver = struct.unpack_from("<I", d, 23)[0]
wide = ver >= 7500
p = 27
top = []
while p < len(d) - 32:
try:
node, p2 = _read_node(d, p, wide)
except Exception:
break
if node is None:
break
top.append(node)
if p2 <= p:
break
p = p2
return ver, top
# --------------------------------------------------------------- ASCII FBX --
class _Arr(object):
"""ASCII 里的 `*N` 数组标记,解析完用子节点 a 的数据替换掉。"""
__slots__ = ("n",)
def __init__(self, n):
self.n = n
class _AsciiParser(object):
def __init__(self, text):
self.s = text
self.i = 0
self.n = len(text)
# -- 词法
def _skip(self):
"""跳过空白和 `;` 行注释(换行也跳过)。"""
s, n = self.s, self.n
while self.i < n:
c = s[self.i]
if c in " \t\r\n":
self.i += 1
elif c == ";":
j = s.find("\n", self.i)
self.i = n if j < 0 else j + 1
else:
break
def _skip_inline(self):
while self.i < self.n and self.s[self.i] in " \t":
self.i += 1
def _name(self):
s, j = self.s, self.i
while j < self.n and s[j] not in ":{ \t\r\n":
j += 1
nm = s[self.i:j]
self.i = j
return nm
def _string(self):
s, j = self.s, self.i + 1
buf = []
while j < self.n:
c = s[j]
if c == "\\":
if j + 1 < self.n:
buf.append(s[j + 1])
j += 2
continue
if c == '"':
j += 1
break
buf.append(c)
j += 1
self.i = j
return "".join(buf)
def _number(self):
s, j = self.s, self.i
while j < self.n and s[j] in "+-.0123456789eE":
j += 1
tok = s[self.i:j]
self.i = j
try:
return float(tok) if any(c in tok for c in ".eE") else int(tok)
except ValueError:
return 0
def _token(self):
s, j = self.s, self.i
while j < self.n and s[j] not in " \t\r\n,{}":
j += 1
tok = s[self.i:j]
self.i = max(j, self.i + 1)
return tok
# -- 语法
def _array_block(self):
"""读 `{ a: v,v,v a: v,v ... }` 这种数组块,返回展平的数值列表。
实际存在的三种写法都要吃下(实测踩过):
* Autodesk 风格:整个数组一条 `a: ...` 行,可能长达几 MB;
* 分行且每行重复行标签:`a: v,v` 换行 `a: v,v`(本工程的写出器这样写);
* 分行但只有第一行有标签,后续行直接续数(可能以逗号开头)。
"""
vals = []
self._skip()
if not (self.i < self.n and self.s[self.i] == "{"):
return vals
self.i += 1
while True:
self._skip()
if self.i >= self.n or self.s[self.i] == "}":
break
# 行首可能是行标签(`a`)也可能直接就是数值:先看一眼再决定
save = self.i
self._name()
self._skip_inline()
if self.i < self.n and self.s[self.i] == ":":
self.i += 1
else:
self.i = save
# 读这一行的数值,换行即止
while True:
self._skip_inline()
if self.i >= self.n:
break
c = self.s[self.i]
if c in "\r\n}":
break
if c == ",":
self.i += 1
continue
if c == '"':
vals.append(self._string())
elif c in "+-.0123456789":
vals.append(self._number())
else:
self._token() # 认不出的 token 丢掉,别污染数值
if self.i < self.n and self.s[self.i] == "}":
self.i += 1
return vals
def node(self):
"""解析一个节点。
普通节点的属性必须写在同一行 —— 遇到换行即终止属性列表,否则会把
下一行的兄弟节点名字吃进自己的 props。真正会跨行的只有数组数据,
那部分由 `_array_block()` 专门处理。
"""
self._skip()
if self.i >= self.n or self.s[self.i] == "}":
return None
name = self._name()
if not name:
return None
self._skip()
if self.i < self.n and self.s[self.i] == ":":
self.i += 1
props = []
counts = []
rows = []
while True:
self._skip_inline()
if self.i >= self.n:
break
c = self.s[self.i]
if c in "{\r\n}":
break
if c == ",":
self.i += 1
continue
if c == '"':
props.append(self._string())
elif c == "*":
self.i += 1
n_arr = self._number()
counts.append(n_arr)
props.append(_Arr(n_arr))
rows.extend(self._array_block())
elif c in "+-.0123456789":
props.append(self._number())
else:
props.append(self._token())
has_arr = any(isinstance(p, _Arr) for p in props)
children = []
self._skip()
if self.i < self.n and self.s[self.i] == "{":
self.i += 1
while True:
mark = self.i
# 数组块的 `{...}` 已经被 _array_block 吃掉,这里剩下的都是
# 普通单行属性子节点。
ch = self.node()
if ch is None:
break
children.append(ch)
if self.i <= mark: # 防死循环
break
self._skip()
if self.i < self.n and self.s[self.i] == "}":
self.i += 1
if has_arr:
# 按声明长度把行数据切回各个数组属性;只有一个数组时整份给它
# (`*N` 与行数据不一致时以行数据为准,宁可多也别丢)。
filled = []
off = 0
k = 0
for p in props:
if isinstance(p, _Arr):
if len(counts) > 1:
n = counts[k] if k < len(counts) else 0
filled.append(rows[off:off + n])
off += n
else:
filled.append(rows)
k += 1
else:
filled.append(p)
props = filled
return FbxNode(name, props, children)
def _load_ascii(path):
with open(path, "r", encoding="utf-8-sig", errors="replace") as f:
text = f.read()
p = _AsciiParser(text)
top = []
while True:
mark = p.i
nd = p.node()
if nd is None:
break
top.append(nd)
if p.i <= mark:
break
ver = 7400
for nd in top:
if nd.name == "FBXHeaderExtension":
for c in nd.children:
if c.name == "FBXVersion" and c.props:
try:
ver = int(c.props[0])
except (TypeError, ValueError):
pass
if not top:
raise ValueError("既不是二进制 FBX,也解析不出 ASCII FBX 节点:%s" % path)
return ver, top
def load(path):
"""返回 (version, [顶层节点])。二进制 / ASCII 自动识别。"""
with open(path, "rb") as f:
head = f.read(23)
if head[:20] == b"Kaydara FBX Binary ":
return _load_binary(path)
return _load_ascii(path)
def index_by_id(nodes):
"""Collect every node that carries an (id, name) pair, keyed by id."""
out = {}
for n in nodes:
if n.props and isinstance(n.props[0], int) and len(n.props) >= 3:
out[n.props[0]] = n
return out
+688
View File
@@ -0,0 +1,688 @@
# -*- coding: utf-8 -*-
"""fbxout.py - 把网格 + 骨骼 + 蒙皮写成 **ASCII FBX 7.4**(纯标准库)。
为什么要 ASCII:二进制 FBX 要做 deflate + 节点表 + 32/64 位偏移宽度,
坑多且难调试(本工程读 FBX 时就踩过 7400=32 位偏移的坑)。ASCII FBX 是
纯文本,任何 DCC(Blender / Maya / 3ds Max / Unity / UE)都认,出问题能直接
肉眼看字节。
坐标系(与工程的 FBX 读取路径**互为逆操作**,可自校验)
fbx = (x, y, -z)_pmx —— 即读取侧的「Z 取反」
PMX 左手系、fbx 右手系 ⇒ 手性和绕序一起翻,所以三角形要**反转绕序**。
GlobalSettings 里如实声明 UpAxis=Y / FrontAxis=Z(sign +1) / CoordAxis=X,
这样 Blender、Maya 之流会按声明把模型摆正(角色在 Blender 里仍朝 -Y)。
用本工程的 FBX→PMX 路径(Z 轴翻转=开)再读回来,应当与源 PMX 一致。
蒙皮约定(FBX SDK 的老规矩)
对每个 Cluster:TransformLink = 绑定姿势下骨骼的世界矩阵 W,
Transform = W⁻¹
于是 TransformLink · Transform = I ⇒ 顶点本来就在绑定姿势里,静止时不变形;
摆姿势时按 A_bone · (Transform · v) 的公式走。绑定姿势的骨骼只有平移
(PMX 的骨骼本来就不带旋转),所以两个矩阵都是纯平移。
矩阵按**行主序**写 16 个数,平移落在最后一行(第 13/14/15 个)。
用法(也可直接当命令行工具,接 .pmx):
python fbxout.py model.pmx -o model.fbx
"""
import argparse
import os
import sys
import time
_HERE = os.path.dirname(os.path.abspath(__file__))
def _log_default(msg, tag=None):
try:
print(msg)
except UnicodeEncodeError:
print(msg.encode("utf-8", "replace").decode("ascii", "replace"))
def _f(v):
"""FBX 里的浮点写法:够短又不丢精度。"""
x = float(v)
if x == int(x) and abs(x) < 1e15:
return str(int(x))
return "%.6g" % x
def _arr(w, indent, values):
"""把整个数组写成一条 `a: ...` 行。
Autodesk 自己的 ASCII FBX 就是这么写的 —— 顶点表几 MB 全塞在一行里很正常。
早期版本按固定条数换行、每行重复写一次 `a:` 标签,虽然也有工具这么干,
但那样会让不少第三方解析器(以及本工程自己)在续行处多吃/漏吃数值,
所以统一改成一条行最保险。
"""
w("%sa: %s" % (indent, ",".join(values)))
def _esc(s):
return (s or "").replace("\\", "\\\\").replace('"', '\\"')
def _san(s):
"""名字里的非 ASCII 会被某些工具当成编码问题,统一换成下划线。"""
out = []
for ch in (s or ""):
out.append(ch if 32 < ord(ch) < 127 else "_")
nm = "".join(out).strip() or "unnamed"
return nm[:120]
def _name(prefix, s):
"""带 `Class::` 命名空间的名字(FBX 里的传统写法)。"""
return "%s::%s" % (prefix, _san(s))
def _clip(s, n=120):
"""名字清洗:去掉控制字符(换行会破坏 FBX 的行结构)并截断。
与 `_san` 不同,这里**保留非 ASCII** —— 表情名用日文/中文很常见,
而 FBX 文本本身就是 UTF-8,SDK 与 Blender 都能正确解码。
"""
s = (s or "").strip()
s = "".join(ch for ch in s if ord(ch) >= 32)
return s[:n]
class _Ids(object):
def __init__(self, start=1000000, step=100000):
self.n = start
self.step = step
def block(self):
base = self.n
self.n += self.step
return base
def _weights_of(vertex):
"""PMX 顶点 → [(骨骼下标, 权重)]。
PMX 的约定:wt=1(BDEF2) 只存 w1,w2 = 1-w1;wt=3(SDEF) 同 BDEF2;
wt=4(QDEF) 同 BDEF4。把补位权重丢掉,只留真正参与的点。
"""
wt = vertex.get("wtype", 0)
bs = list(vertex.get("wbones") or [])
ws = list(vertex.get("wweights") or [])
out = []
if wt in (0,) or not bs:
return [(bs[0] if bs else 0, 1.0)]
if wt in (1, 3):
w1 = ws[0] if ws else 1.0
out = [(bs[0], w1), (bs[1] if len(bs) > 1 else bs[0], 1.0 - w1)]
else: # 2=BDEF4 / 4=QDEF
for k in range(min(len(bs), 4)):
w = ws[k] if k < len(ws) else 0.0
if w > 1e-6:
out.append((bs[k], w))
out = [(b, w) for b, w in out if w > 1e-6]
return out or [(0, 1.0)]
def export_model(path, verts, faces, materials, bones, morphs=None,
mirror_z=True, reverse_winding=True, tex_dir=None, log=None,
creator="ueformat2pmx", name=None, model_name="model",
flip_v=True):
"""写出 ASCII FBX。
verts : PMX 顶点 dict 列表(pos/normal/uv/wtype/wbones/wweights)
faces : 展平的三角索引
materials : PMX 材质 dict 列表(用 name/diffuse/tex)
bones : PMX 骨骼 dict 列表(用 name/pos/parent)
morphs : PMX 表情 dict 列表;kind=1(顶点表情)会写成
BlendShape/BlendShapeChannel/Shape —— 只写真正动过的控制点,
数值是**增量**(FBX 文件里 Shape 的 Vertices 就是这个语义)。
骨骼/UV/材质表情 FBX 装不下,跳过。
model_name : 网格节点名(默认 "model",传模型名更友好)
flip_v : 是否把 UV 的 V 轴翻过来(**默认必须翻**,见下面注释)
返回统计 dict。
"""
_l = log or _log_default
sx = 1.0
sz = -1.0 if mirror_z else 1.0
if name:
model_name = name
model_name = _san(model_name)
def xf(p):
return (p[0] * sx, p[1], p[2] * sz)
nv = len(verts)
ntris = len(faces) // 3
out = []
w = out.append
# ------------------------------------------------- 表情预处理(→ Shape)--
# **FBX 文件里 Shape 的 Vertices 是「相对基础控制点的增量」,不是绝对坐标**
# (实测确认:写全 0 → 读回等于原网格;写基础坐标 → 读回是两倍)。
# FBX SDK / Blender 读取时会给未列在 Indexes 里的控制点补 0 增量,
# 并把结果展开成与网格控制点等长的绝对坐标数组 —— 读取端因此**不需要**
# 知道我们只写了变化点,插件侧的 FbxShape.GetControlPointAt 拿到的就是
# 与网格一一对应的绝对坐标。
# 于是这里只写「真正动过的控制点」:本工程样本 161 个表情、每个约 600 点,
# 合计约 3 MB;若按全量写,光这一个模型就要 300 MB 以上。
morph_shapes = []
for mo in (morphs or []):
if int(mo.get("kind", 1)) != 1:
continue # 只搬顶点表情;骨骼/UV/材质表情 FBX 装不下
pairs = {}
for vi, d in (mo.get("offsets") or []):
vi = int(vi)
if 0 <= vi < nv:
pairs[vi] = d
if pairs:
morph_shapes.append((mo, pairs))
n_shape = len(morph_shapes)
n_attr = len(bones) + 1 # 每根骨骼一个 + 网格一个
# 每根骨骼影响哪些顶点(Cluster 用;顺带决定 Definitions 里 Deformer 的数量)
per_bone = {}
for vi, v in enumerate(verts):
for b, wt in _weights_of(v):
if 0 <= b < len(bones):
per_bone.setdefault(b, []).append((vi, wt))
n_cluster = len(per_bone)
n_def = 1 + n_cluster + (1 + n_shape if n_shape else 0)
hdr_axis = "Z" if mirror_z else "-Z"
_l("FBX:%d 顶点 · %d 三角面 · %d 骨骼 · %d 材质(ASCII 7.4,%s-up,前方 %s)%s"
% (nv, ntris, len(bones), len(materials), "Y", hdr_axis,
("· %d 个顶点表情写入 BlendShape" % n_shape) if n_shape else ""))
ids = _Ids()
gid = ids.block() # Geometry
mid = ids.block() # Mesh Model
bone_id0 = ids.block() # 骨骼 Model 段
mat_id0 = ids.block() # Material 段
tex_id0 = ids.block() # Texture / Video 段
def_id0 = ids.block() # Deformer 段(Skin + Cluster)
na_id0 = ids.block() # NodeAttribute 段(骨骼 + 网格)
morph_id0 = ids.block() # BlendShape / BlendShapeChannel / Shape 段
bone_model = [bone_id0 + i for i in range(max(len(bones), 1))]
# ------------------------------------------------------------ 头 + 设置 --
w("; FBX 7.4.0 project file")
w("; 由 %s 生成(纯 Python,ASCII FBX)" % creator)
w("; ----------------------------------------------------")
w("")
t = time.localtime()
w("FBXHeaderExtension: {")
w("\tFBXHeaderVersion: 1003")
w("\tFBXVersion: 7400")
w("\tCreationTimeStamp: {")
w("\t\tVersion: 1000")
w("\t\tYear: %d" % t.tm_year)
w("\t\tMonth: %d" % t.tm_mon)
w("\t\tDay: %d" % t.tm_mday)
w("\t\tHour: %d" % t.tm_hour)
w("\t\tMinute: %d" % t.tm_min)
w("\t\tSecond: %d" % t.tm_sec)
w("\t\tMillisecond: 0")
w("\t}")
w('\tCreator: "%s"' % creator)
w("}")
w("")
w("GlobalSettings: {")
w("\tVersion: 1000")
w("\tProperties70: {")
w('\t\tP: "UpAxis", "int", "Integer", "",1')
w('\t\tP: "UpAxisSign", "int", "Integer", "",1')
w('\t\tP: "FrontAxis", "int", "Integer", "",2')
w('\t\tP: "FrontAxisSign", "int", "Integer", "",%d'
% (1 if mirror_z else -1))
w('\t\tP: "CoordAxis", "int", "Integer", "",0')
w('\t\tP: "CoordAxisSign", "int", "Integer", "",1')
w('\t\tP: "OriginalUpAxis", "int", "Integer", "",1')
w('\t\tP: "OriginalUpAxisSign", "int", "Integer", "",1')
w('\t\tP: "UnitScaleFactor", "double", "Number", "",1')
w('\t\tP: "OriginalUnitScaleFactor", "double", "Number", "",1')
w('\t}')
w("}")
w("")
# ------------------------------------------------------------ Definitions --
n_tex = sum(1 for m in materials
if isinstance(m.get("tex"), int) and m["tex"] >= 0)
w("Definitions: {")
w("\tVersion: 100")
# Count = 下面 ObjectType 块的**个数**:GlobalSettings / Model / Geometry /
# Material / Deformer / NodeAttribute,有贴图时再加 Texture 与 Video。
w("\tCount: %d" % (6 + (2 if n_tex else 0)))
w('\tObjectType: "GlobalSettings" {')
w("\t\tCount: 1")
w("\t}")
w('\tObjectType: "Model" {')
w("\t\tCount: %d" % (1 + len(bones)))
w("\t}")
w('\tObjectType: "Geometry" {')
w("\t\tCount: %d" % (1 + n_shape))
w("\t}")
# NodeAttribute 段不能省:**Model 的「类型」是由它挂着的 NodeAttribute
# 对象决定的**,Model 行里的 "LimbNode" 只是个字符串。
# 少了它,FBX SDK 侧 node.GetNodeAttribute() 返回 null(网格还能靠
# Geometry 连接被 SDK 兜回来,骨骼却没有任何线索),任何按 SDK API
# 判断骨骼的导入器都会一根骨头都收不到 —— PE 的 FBX 导入插件就是这样
# 在 PE 里「只有网格、没有骨骼」的。
w('\tObjectType: "NodeAttribute" {')
w("\t\tCount: %d" % n_attr)
w("\t}")
if n_tex:
w('\tObjectType: "Video" {')
w("\t\tCount: %d" % n_tex)
w("\t}")
w('\tObjectType: "Texture" {')
w("\t\tCount: %d" % n_tex)
w("\t}")
w('\tObjectType: "Material" {')
w("\t\tCount: %d" % max(len(materials), 1))
w("\t}")
w('\tObjectType: "Deformer" {')
w("\t\tCount: %d" % n_def)
w("\t}")
w("}")
w("")
# ---------------------------------------------------------------- Objects --
w("Objects: {")
# Geometry
w('\tGeometry: %d, "%s", "Mesh" {' % (gid, _name("Geometry", "mesh")))
w("\t\tVertices: *%d {" % (nv * 3))
_arr(w, "\t\t\t", [_f(c) for v in verts for c in xf(v["pos"])])
w("\t\t} ")
# 三角形的顶点顺序。**PVI / 法线 / UVIndex 三处必须用同一个顺序**:
# 法线与 UV 都是 ByPolygonVertex(每个多边形顶点一项,按多边形顶点顺序
# 一一对应)。镜像手性时绕序要反转,但如果只反 PVI、不反 UVIndex 与
# 法线,等于把每个三角形首末两个角的 UV/法线对调 —— 几何形状完全正确、
# 贴图却整片错乱(用户报的「FBX 材质显示不对、同时导出的 PMX 正常」
# 就是这个:实测 115563/115563 个三角形全部首末对调)。
tris = []
for t2 in range(ntris):
a, b, c = faces[t2 * 3], faces[t2 * 3 + 1], faces[t2 * 3 + 2]
if reverse_winding:
a, b, c = c, b, a
tris.append((a, b, c))
w("\t\tPolygonVertexIndex: *%d {" % (ntris * 3))
buf = []
for a, b, c in tris:
buf.append("%d,%d,%d" % (a, b, -(c + 1))) # 末位取反 = 多边形结束
_arr(w, "\t\t\t", buf)
w("\t\t} ")
w("\t\tGeometryVersion: 124")
# 法线:ByPolygonVertex(最兼容的写法)
w("\t\tLayerElementNormal: 0 {")
w("\t\t\tVersion: 101")
w('\t\t\tName: ""')
w('\t\t\tMappingInformationType: "ByPolygonVertex"')
w('\t\t\tReferenceInformationType: "Direct"')
w("\t\t\tNormals: *%d {" % (ntris * 9))
buf = []
for tri in tris:
for vi in tri:
n = verts[vi]["normal"] if vi < nv else (0.0, 1.0, 0.0)
buf.append("%s,%s,%s" % (_f(n[0] * sx), _f(n[1]), _f(n[2] * sz)))
_arr(w, "\t\t\t\t", buf)
w("\t\t\t} ")
w("\t\t}")
# UV:ByPolygonVertex + IndexToDirect
# **V 轴必须翻**:MMD / PMX / UE 的 UV 原点在**左上**(v 向下),而 FBX 的
# 通行约定(Autodesk / Blender / Maya)原点在**左下**(v 向上)。原样写出去,
# 下游按 v 向上解释就把贴图上下颠倒了 —— 表现为形状完全正确、图案整体错位
# (脸上出现嘴/脖子处的图、腿脚出现靴子、头发出现大片黑斑)。本工程的
# fbx2pmx 读 FBX 时同样做 `1.0 - v`,两边对称,导入导出往返才能对上。
w("\t\tLayerElementUV: 0 {")
w("\t\t\tVersion: 101")
w('\t\t\tName: "UVChannel_1"')
w('\t\t\tMappingInformationType: "ByPolygonVertex"')
w('\t\t\tReferenceInformationType: "IndexToDirect"')
w("\t\t\tUV: *%d {" % (nv * 2))
buf = []
for v in verts:
u = v.get("uv") or (0.0, 0.0)
vv = (1.0 - u[1]) if flip_v else u[1]
buf.append("%s,%s" % (_f(u[0]), _f(vv)))
_arr(w, "\t\t\t\t", buf)
w("\t\t\t} ")
w("\t\t\tUVIndex: *%d {" % (ntris * 3))
buf = []
for tri in tris:
buf.append("%d,%d,%d" % tri)
_arr(w, "\t\t\t\t", buf)
w("\t\t\t} ")
w("\t\t}")
# 逐面材质
if materials:
w("\t\tLayerElementMaterial: 0 {")
w("\t\t\tVersion: 101")
w('\t\t\tName: ""')
w('\t\t\tMappingInformationType: "ByPolygon"')
w('\t\t\tReferenceInformationType: "IndexToDirect"')
w("\t\t\tMaterials: *%d {" % ntris)
per_mat = []
for mi, mt in enumerate(materials):
per_mat.extend([mi] * (max(0, int(mt.get("faces", 0))) // 3))
if len(per_mat) < ntris:
per_mat.extend([0] * (ntris - len(per_mat)))
del per_mat[ntris:]
_arr(w, "\t\t\t\t", [str(x) for x in per_mat])
w("\t\t\t} ")
w("\t\t}")
w("\t\tLayer: 0 {")
w("\t\t\tVersion: 100")
w('\t\t\tLayerElement: {')
w('\t\t\t\tType: "LayerElementNormal"')
w("\t\t\t\tTypedIndex: 0")
w("\t\t\t}")
w('\t\t\tLayerElement: {')
w('\t\t\t\tType: "LayerElementUV"')
w("\t\t\t\tTypedIndex: 0")
w("\t\t\t}")
if materials:
w('\t\t\tLayerElement: {')
w('\t\t\t\tType: "LayerElementMaterial"')
w("\t\t\t\tTypedIndex: 0")
w("\t\t\t}")
w("\t\t}")
w("\t}")
# 骨骼:Model(LimbNode),Lcl Translation = 相对父骨骼的位置(绑定姿势只有平移)
bpos = [xf(b["pos"]) for b in bones]
for bi, b in enumerate(bones):
p = b.get("parent", -1)
if 0 <= p < len(bones):
d = (bpos[bi][0] - bpos[p][0], bpos[bi][1] - bpos[p][1],
bpos[bi][2] - bpos[p][2])
else:
d = bpos[bi]
# 骨名写**裸名**、不加 `Model::` 前缀。本工程自己的 FBX→PMX 读取路径
# 会把 Model 名字原样当骨名用,加前缀会让「导出再读回」的骨名变成
# `Model::Bip001Pelvis`,导进 Blender / UE 看着也脏。
w('\tModel: %d, "%s", "LimbNode" {' % (bone_model[bi], _san(b["name"])))
w("\t\tVersion: 232")
w("\t\tProperties70: {")
w('\t\t\tP: "InheritType", "enum", "", "",1')
# **DefaultAttributeIndex 不能省**(网格 Model 一直有它,骨骼以前漏了):
# FBX SDK 只在 Model 显式声明这个属性之后,才会把 "OO" 连接上来的
# NodeAttribute 挂到该节点上;缺了它 node.GetNodeAttribute() 永远是 null。
# 这正是「骨骼在 Blender 里看得见(Blender 自己解析文件,不看这个属性),
# 在 PE 的 FBX 导入插件里却一根都没有(插件走 FBX SDK 的 API)」的原因。
# 实测:同一份文件只补这一行,eSkeleton 节点数 0 → 489。
w('\t\t\tP: "DefaultAttributeIndex", "int", "Integer", "",0')
w('\t\t\tP: "Lcl Translation", "Lcl Translation", "", "A",%s,%s,%s'
% (_f(d[0]), _f(d[1]), _f(d[2])))
w('\t\t\tP: "Lcl Rotation", "Lcl Rotation", "", "A",0,0,0')
w('\t\t\tP: "Lcl Scaling", "Lcl Scaling", "", "A",1,1,1')
w('\t\t}')
w('\t\tShading: T')
w('\t\tCulling: "CullingOff"')
w("\t}")
# 网格节点
w('\tModel: %d, "%s", "Mesh" {' % (mid, _san(model_name)))
w("\t\tVersion: 232")
w("\t\tProperties70: {")
w('\t\t\tP: "InheritType", "enum", "", "",1')
w('\t\t\tP: "DefaultAttributeIndex", "int", "Integer", "",0')
w("\t\t}")
w("\t\tShading: T")
w('\t\tCulling: "CullingOff"')
w("\t}")
# 节点属性:骨骼 → Skeleton,网格 → Mesh。名字照 Autodesk 的习惯留空
# (`"NodeAttribute::"`),类型由第三个字符串决定。
for bi in range(len(bones)):
w('\tNodeAttribute: %d, "NodeAttribute::", "LimbNode" {' % (na_id0 + bi))
w('\t\tTypeFlags: "Skeleton"')
w("\t}")
w('\tNodeAttribute: %d, "NodeAttribute::", "Mesh" {' % (na_id0 + len(bones)))
w('\t\tTypeFlags: "Mesh"')
w("\t\tGeometryVersion: 124")
w("\t}")
# 材质(+ 贴图 Video/Texture)
mat_ids = []
tex_ids = []
for mi, mt in enumerate(materials or [{"name": "material_0",
"diffuse": (1.0, 1.0, 1.0, 1.0),
"tex": -1}]):
myid = mat_id0 + mi
mat_ids.append(myid)
diff = list(mt.get("diffuse") or (1.0, 1.0, 1.0, 1.0))
alpha = diff[3] if len(diff) > 3 else 1.0
w('\tMaterial: %d, "%s", "" {' % (myid, _name("Material", mt.get("name"))))
w("\t\tVersion: 102")
w('\t\tShadingModel: "phong"')
w("\t\tMultiLayer: 0")
w("\t\tProperties70: {")
w('\t\t\tP: "DiffuseColor", "Color", "", "A",%s,%s,%s'
% (_f(diff[0]), _f(diff[1]), _f(diff[2])))
w('\t\t\tP: "DiffuseFactor", "Number", "", "A",1')
w('\t\t\tP: "TransparencyFactor", "Number", "", "A",%s'
% _f(1.0 - max(0.0, min(1.0, alpha))))
w('\t\t\tP: "SpecularColor", "Color", "", "A",0,0,0')
w('\t\t\tP: "SpecularFactor", "Number", "", "A",0')
w('\t\t\tP: "ShininessExponent", "Number", "", "A",0')
w('\t\t\tP: "EmissiveColor", "Color", "", "A",0,0,0')
w('\t\t\tP: "AmbientColor", "Color", "", "A",0.5,0.5,0.5')
w("\t\t}")
w("\t}")
ti = mt.get("tex", -1)
if isinstance(ti, int) and ti >= 0:
tex_ids.append((mi, ti))
# 贴图(引用文本文件名,不内嵌二进制)
tex_files = {}
if tex_ids and tex_dir is not None:
folder_idx = {}
try:
for fn in os.listdir(tex_dir):
folder_idx.setdefault(fn.lower(), fn)
except OSError:
pass
for mi, ti in tex_ids:
vid = tex_id0 + mi * 2
tid = vid + 1
# 文件名由调用方通过 materials[i]["_tex_file"] 传入;没有就按序号找
fn = materials[mi].get("_tex_file")
if not fn:
hits = [v for k, v in folder_idx.items()
if k.endswith(".png") and ("tex%02d" % ti) in k]
fn = hits[0] if hits else None
if not fn:
continue
rel = "textures/" + fn
tex_files[mi] = rel
w('\tVideo: %d, "Video::tex%d", "Clip" {' % (vid, mi))
w("\t\tType: \"Clip\"")
w("\t\tProperties70: {")
w('\t\t\tP: "Path", "KString", "XRefUrl", "", "%s"' % _esc(rel))
w("\t\t}")
w("\t\tUseMipMap: 0")
w('\t\tFilename: "%s"' % _esc(rel))
w('\t\tRelativeFilename: "%s"' % _esc(rel))
w("\t}")
w('\tTexture: %d, "Texture::tex%d", "" {' % (tid, mi))
w('\t\tType: "TextureVideoClip"')
w("\t\tVersion: 202")
w('\t\tTextureName: "Texture::tex%d"' % mi)
w('\t\tMedia: "Video::tex%d"' % mi)
w('\t\tFileName: "%s"' % _esc(rel))
w('\t\tRelativeFilename: "%s"' % _esc(rel))
w("\t\tModelUVTranslation: 0,0")
w("\t\tModelUVScaling: 1,1")
w('\t\tTexture_Alpha_Source: "None"')
w("\t\tCropping: 0,0,0,0")
w("\t}")
# 蒙皮:Skin + 每个骨骼一个 Cluster
skin_id = def_id0
w('\tDeformer: %d, "Deformer::Skin", "Skin" {' % skin_id)
w("\t\tVersion: 101")
w("\t\tLink_DeformAcuracy: 50")
w("\t}")
# per_bone / n_cluster 已经在前面算好(Definitions 里要用到)
for bi in sorted(per_bone):
pairs = sorted(per_bone[bi])
cx = bpos[bi]
w('\tDeformer: %d, "SubDeformer::%s", "Cluster" {'
% (skin_id + 1 + bi, _san(bones[bi]["name"])))
w("\t\tVersion: 100")
w('\t\tUserData: "", ""')
w("\t\tIndexes: *%d {" % len(pairs))
_arr(w, "\t\t\t", [str(x[0]) for x in pairs])
w("\t\t} ")
w("\t\tWeights: *%d {" % len(pairs))
_arr(w, "\t\t\t", [_f(x[1]) for x in pairs])
w("\t\t} ")
# 行主序 4x4:TransformLink = W(骨骼世界),Transform = W⁻¹
w("\t\tTransform: *16 {")
w("\t\t\ta: " + ",".join(["1", "0", "0", "0", "0", "1", "0", "0",
"0", "0", "1", "0",
_f(-cx[0]), _f(-cx[1]), _f(-cx[2]), "1"]))
w("\t\t} ")
w("\t\tTransformLink: *16 {")
w("\t\t\ta: " + ",".join(["1", "0", "0", "0", "0", "1", "0", "0",
"0", "0", "1", "0",
_f(cx[0]), _f(cx[1]), _f(cx[2]), "1"]))
w("\t\t} ")
w("\t}")
# 表情:BlendShape → BlendShapeChannel(一个表情一个)→ Shape(增量)
# 名字一律写**裸名**(和骨名一样,不加 `SubDeformer::` / `Shape::` 前缀):
# · FBX SDK 侧 channel.GetName() 会把前缀剥掉,两种写法结果相同;
# · 本工程自己的 fbx2pmx 直接取字段原文,写裸名才不会把表情名变成
# "Shape::L_P";
# · Blender 的 shape key 名字也直接取这个字段。
# 名字里的非 ASCII(日文表情名很常见)**保留原样** —— FBX 文本是 UTF-8,
# SDK 与 Blender 都能正确解码,换成下划线反而让用户在 PE 里认不出表情。
shape_ids = {}
if n_shape:
w('\tDeformer: %d, "BlendShape", "BlendShape" {' % morph_id0)
w("\t\tVersion: 101")
w("\t}")
for k, (mo, pairs) in enumerate(morph_shapes):
cid = morph_id0 + 1 + k * 2
sid = cid + 1
shape_ids[k] = (cid, sid)
nm = _esc(_clip(mo.get("name"))) or ("morph_%d" % k)
w('\tDeformer: %d, "%s", "BlendShapeChannel" {' % (cid, nm))
w("\t\tVersion: 100")
# 字段名是 DeformPercent(不是 DeformerPercent)——后者会被 SDK 当成
# 未知字段默默丢掉,通道权重就一直是 0。
w("\t\tDeformPercent: 0")
# FullWeights = 每个 target shape 的默认权重(百分比)。SDK 导出时必写。
w("\t\tFullWeights: *1 {")
w("\t\t\ta: 100")
w("\t\t} ")
w("\t}")
keys = sorted(pairs)
w('\tGeometry: %d, "%s", "Shape" {' % (sid, nm))
w("\t\tVersion: 100")
w("\t\tIndexes: *%d {" % len(keys))
_arr(w, "\t\t\t", [str(x) for x in keys])
w("\t\t} ")
w("\t\tVertices: *%d {" % (len(keys) * 3))
buf = []
for vi in keys:
d = xf(pairs[vi])
buf.append("%s,%s,%s" % (_f(d[0]), _f(d[1]), _f(d[2])))
_arr(w, "\t\t\t", buf)
w("\t\t} ")
w("\t}")
w("}")
w("")
# ------------------------------------------------------------ Connections --
w("Connections: {")
w('\tC: "OO",%d,0' % mid)
w('\tC: "OO",%d,%d' % (gid, mid))
w('\tC: "OO",%d,%d' % (skin_id, gid))
# 每个 Model 挂自己的 NodeAttribute(没有它 SDK 认不出节点类型)
w('\tC: "OO",%d,%d' % (na_id0 + len(bones), mid))
for bi in range(len(bones)):
w('\tC: "OO",%d,%d' % (na_id0 + bi, bone_model[bi]))
# 表情链:Shape → Channel → BlendShape → Geometry
if n_shape:
w('\tC: "OO",%d,%d' % (morph_id0, gid))
for k in range(n_shape):
cid, sid = shape_ids[k]
w('\tC: "OO",%d,%d' % (cid, morph_id0))
w('\tC: "OO",%d,%d' % (sid, cid))
for bi in range(len(bones)):
p = bones[bi].get("parent", -1)
if 0 <= p < len(bones):
w('\tC: "OO",%d,%d' % (bone_model[bi], bone_model[p]))
else:
w('\tC: "OO",%d,0' % bone_model[bi])
if bi in per_bone:
w('\tC: "OO",%d,%d' % (skin_id + 1 + bi, skin_id))
w('\tC: "OO",%d,%d' % (bone_model[bi], skin_id + 1 + bi))
for mi, myid in enumerate(mat_ids):
w('\tC: "OO",%d,%d' % (myid, mid))
if mi in tex_files:
tid = tex_id0 + mi * 2 + 1
w('\tC: "OP",%d,%d, "DiffuseColor"' % (tid, myid))
w("}")
w("")
w("Takes: {")
w('\tCurrent: ""')
w("}")
w("")
data = "\n".join(out)
tmp = path + ".tmp"
with open(tmp, "w", encoding="utf-8", newline="\n") as f:
f.write(data)
os.replace(tmp, path)
st = {"bytes": len(data.encode("utf-8")), "vertices": nv, "tris": ntris,
"bones": len(bones), "materials": len(materials or []),
"clusters": n_cluster, "textures": len(tex_files),
"shapes": n_shape, "morphs": len(morphs or [])}
_l("FBX:%d 个 Cluster · %d 个表情 Shape · 引用贴图 %d 张 · %.2f MB"
% (n_cluster, n_shape, len(tex_files), st["bytes"] / 1048576.0))
return st
def export_pmx(pmx_path, fbx_path, log=None, mirror_z=True):
"""直接读 PMX 再写 FBX(命令行用)。"""
import pmxio
m = pmxio.read_pmx(pmx_path)
tex_dir = os.path.join(os.path.dirname(os.path.abspath(pmx_path)), "textures")
for mt in m["materials"]:
ti = mt.get("tex", -1)
if isinstance(ti, int) and 0 <= ti < len(m["textures"]):
mt["_tex_file"] = os.path.basename(m["textures"][ti])
model_name = (m.get("name") or "").strip() or \
os.path.splitext(os.path.basename(pmx_path))[0]
return export_model(fbx_path, m["vertices"], m["faces"], m["materials"],
m["bones"], m["morphs"], mirror_z=mirror_z,
reverse_winding=True, tex_dir=tex_dir, log=log,
creator="fbxout.py", model_name=model_name)
def main(argv=None):
ap = argparse.ArgumentParser(description="PMX → ASCII FBX 7.4(纯 Python)")
ap.add_argument("src")
ap.add_argument("-o", "--out", default=None)
ap.add_argument("--no-mirror", action="store_true",
help="不取反 Z(默认取反,与工程 FBX 读取路径互逆)")
a = ap.parse_args(argv)
out = a.out or (os.path.splitext(a.src)[0] + ".fbx")
st = export_pmx(a.src, out, log=lambda m_, t=None: print(m_),
mirror_z=not a.no_mirror)
print("完成:%s(%.2f MB)" % (out, st["bytes"] / 1048576.0))
return 0
if __name__ == "__main__":
sys.exit(main())
+177
View File
@@ -0,0 +1,177 @@
# -*- coding: utf-8 -*-
r"""Windows 超长路径(MAX_PATH 260)兼容层 —— 纯标准库。
问题
----
Windows 默认把路径限制在 260 字符(MAX_PATH)。Unity 资源包解出来的目录树
本身就很深,例如::
Assets/NFD_Costume/HatsukoiVampire/Gimmick/Resource/Animator/
Animation/Toggle/Accessory/NeckRibbon/Accessory_NeckRibbon_ON.anim
再叠上「输出目录 / 文件名_日期_序号 / 文件名_extracted」这几层,很容易超过
260。一旦超出,open() / os.makedirs() 就抛::
FileNotFoundError: [Errno 2] No such file or directory: 'F:\...'
而且报错里那串路径看着完全正常,非常难排查。
注意:这**不是中文路径的问题**。Python 3 的 Unicode 路径本来就是好的,中文、
日文、空格、方括号、全角符号都没问题,纯粹是「总长度」超限。所以同一台机器
上路径浅就能转、路径深就报错,换台电脑因为存放位置不同结果又不一样。
绕过办法
--------
给路径加 ``\?\`` 前缀(Win32 扩展长度路径),直接跳过 MAX_PATH 检查。它
**不依赖**注册表 LongPathsEnabled,也不需要管理员权限或重启,所以在别人的
电脑上同样有效。
本模块把常用的文件 API 包一层:
* 路径短(< 240)→ 原样透传,行为和以前完全一致;
* 路径长 → 自动补 ``\?\``。
因此对现有用户零影响,只在「本来必然失败」的长路径上生效。
用法
----
``import longpath`` 即可,模块导入时自动安装(重复导入无副作用)。
"""
import builtins
import os
import os.path as _path
import shutil
# 文件路径上限 260、目录上限 248。这里留余量:超过 240 就上前缀,
# 免得刚好卡在 258 那种「有时行有时不行」的位置。
_THRESHOLD = 240
_PREFIX = '\\\\?\\' # \?\
_UNC_PREFIX = '\\\\?\\UNC\\' # \?\UNC\
_installed = False
_originals = {}
def long_path(path):
r"""路径过长时返回带 ``\?\`` 前缀的绝对路径;否则原样返回。
短路径一律原样返回(连 abspath 都不做),保证不改变任何现有行为。
"""
if os.name != 'nt':
return path
if not isinstance(path, str) or not path:
return path # 只处理 str;fd / PathLike 原样放行
if path.startswith(_PREFIX):
return path # 已经加过前缀,别重复加
if len(path) < _THRESHOLD:
return path # 短路径不碰
try:
p = _path.abspath(path)
except (OSError, ValueError):
return path
if len(p) < _THRESHOLD:
return path
if p.startswith('\\\\'):
# UNC:\\server\share\x → \?\UNC\server\share\x
return _UNC_PREFIX + p[2:]
return _PREFIX + p
def _install():
"""给 os / builtins / shutil 的相关函数套上长路径包装。幂等。"""
global _installed
if _installed or os.name != 'nt':
return
_installed = True
# ---- 单路径参数 ------------------------------------------------------
for name in ('makedirs', 'mkdir', 'rmdir', 'remove', 'unlink',
'stat', 'lstat', 'chmod', 'utime', 'listdir', 'scandir',
'access', 'truncate', 'readlink', 'startfile'):
fn = getattr(os, name, None)
if fn is None:
continue
_originals[name] = fn
def make(fn):
def wrapper(path, *a, **kw):
return fn(long_path(path), *a, **kw)
return wrapper
setattr(os, name, make(fn))
# ---- 双路径参数(源、目标都要处理)------------------------------------
for name in ('rename', 'replace'):
fn = getattr(os, name, None)
if fn is None:
continue
_originals[name] = fn
def make2(fn):
def wrapper(src, dst, *a, **kw):
return fn(long_path(src), long_path(dst), *a, **kw)
return wrapper
setattr(os, name, make2(fn))
# ---- 内置 open -------------------------------------------------------
_originals['open'] = builtins.open
def _open(file, *a, **kw):
return _originals['open'](long_path(file), *a, **kw)
builtins.open = _open
# ---- shutil:显式包一层(虽然底层最终也会走到上面的 open/stat)---------
for name in ('copyfile', 'copy', 'copy2', 'copymode', 'copystat',
'rmtree'):
fn = getattr(shutil, name, None)
if fn is None:
continue
_originals['shutil.' + name] = fn
def makes(fn):
def wrapper(path, *a, **kw):
return fn(long_path(path), *a, **kw)
return wrapper
setattr(shutil, name, makes(fn))
for name in ('move',):
fn = getattr(shutil, name, None)
if fn is None:
continue
_originals['shutil.' + name] = fn
def makes2(fn):
def wrapper(src, dst, *a, **kw):
return fn(long_path(src), long_path(dst), *a, **kw)
return wrapper
setattr(shutil, name, makes2(fn))
_install()
def probe(base):
"""自检:在 base 下建一条超长路径并写入/读回,返回 (是否成功, 说明)。
给界面或命令行排查用;平时不调用。
"""
deep = os.path.join(base, '_longpath_probe')
while len(deep) < 300:
deep = os.path.join(deep, 'LongSegmentName_0123456789')
target = os.path.join(deep, 'probe.txt')
try:
os.makedirs(deep, exist_ok=True)
with open(target, 'w', encoding='utf-8') as f:
f.write('ok')
with open(target, encoding='utf-8') as f:
got = f.read()
return got == 'ok', '长度 %d,写入并读回成功' % len(target)
except Exception as e: # pragma: no cover
return False, '%s: %s' % (type(e).__name__, e)
if __name__ == '__main__': # pragma: no cover
import sys
base = sys.argv[1] if len(sys.argv) > 1 else os.getcwd()
ok, msg = probe(base)
print(('[OK] ' if ok else '[FAIL] ') + msg)
+878
View File
@@ -0,0 +1,878 @@
# -*- coding: utf-8 -*-
"""pmxio.py - 完整的 PMX 2.0 / 2.1 读写(纯 Python 标准库)。
读进模型的全部内容(含表情 offset、骨骼 IK/付与/轴限制、刚体、关节),并且能原样写回。
PMX → VRM 和各格式 → PMX 的转换都基于它。
数据结构(dict):
model = {
"version", "enc", "add_uv",
"name", "name_en", "comment", "comment_en",
"vertices": [ {"pos":(3), "normal":(3), "uv":(2), "add_uv":[(4)...],
"wtype":0..4, "wbones":[int..], "wweights":[float..],
"sdef":(C,R0,R1) 或 None,
"edge":float} ],
"faces": [v0, v1, v2, ...], # 展平
"textures":["相对路径", ...],
"materials":[ {"name","name_en","diffuse":(4),"specular":(3),"shininess",
"ambient":(3),"flag","edge_color":(4),"edge_size",
"tex","sph","sph_mode","toon_flag","toon","memo","faces"} ],
"bones": [ {"name","name_en","pos":(3),"parent","layer","flag",
"tail_kind":0/1,"tail":(3)或int,
"inherit_rot":(bone,ratio)或None,
"inherit_mov":(bone,ratio)或None,
"fixed_axis":(3)或None,
"local_axis":(X,Z)或None,
"external":int 或 None,
"ik":{...}或None} ],
"morphs": [ {"name","name_en","panel","kind","offsets":[...]} ],
"frames": [ {"name","name_en","special","items":[(type,index)]} ],
"rigid_bodies":[...],
"joints":[...],
}
"""
import os
import struct
_DBG = bool(os.environ.get("PMXIO_DEBUG"))
FLOAT = "f"
WEIGHT_BONES = {0: 1, 1: 2, 2: 4, 3: 2, 4: 4}
WEIGHT_FLOATS = {0: 0, 1: 1, 2: 4, 3: 1, 4: 4}
# PMX 头部的文本编码取值:0 = UTF-16LE,1 = UTF-8。
# MMD 本体只认 0(原版提示「エンコード方式がUTF16のPMXファイルしか読み込めません」,
# 汉化版误译成「不能载入编码为UTF16的PMX文件」,其实意思正好相反)。
# PMX Editor / mmd_tools 也都默认写 0,所以输出一律用 UTF-16LE。
ENC_UTF16 = 0
ENC_UTF8 = 1
MMD_ENC = ENC_UTF16
# ------------------------------------------------------------------ reader --
class _R:
def __init__(self, d):
self.d = d
self.p = 0
self.enc = 1
# 当前解析到的段落/条目,仅用于出错时给出能定位的信息
self.sec = "头部"
def _fail(self, what):
return "PMX 解析错位(段落:%s):" % self.sec
def _need(self, n, what):
if self.p + n > len(self.d):
raise ValueError(
self._fail(what)
+ "读取「%s」时越过文件末尾(偏移 %d / 文件 %d 字节)。"
"可能是某一段的结构与写入程序不一致,请反馈此模型文件。"
% (what, self.p, len(self.d)))
def i32(self, what="int"):
self._need(4, what)
v = struct.unpack_from("<i", self.d, self.p)[0]
self.p += 4
return v
def u8(self, what="byte"):
self._need(1, what)
v = self.d[self.p]
self.p += 1
return v
def f32(self, what="float"):
self._need(4, what)
v = struct.unpack_from("<f", self.d, self.p)[0]
self.p += 4
return v
def text(self, what="text"):
self._need(4, what)
n = self.i32(what)
if n < 0 or self.p + n > len(self.d):
raise ValueError(
self._fail(what)
+ "「%s」长度 %d 超出文件剩余字节(偏移 %d / %d)。"
% (what, n, self.p, len(self.d)))
s = self.d[self.p:self.p + n]
self.p += n
return s.decode("utf-16-le" if self.enc == 0 else "utf-8", "replace")
def idx(self, size, signed=True, what="index"):
self._need(size, what)
if size == 1:
v = struct.unpack_from("<b" if signed else "<B", self.d, self.p)[0]
self.p += 1
elif size == 2:
v = struct.unpack_from("<h" if signed else "<H", self.d, self.p)[0]
self.p += 2
else:
v = self.i32()
if not signed:
v &= 0xFFFFFFFF
return v
_IDX = {1: "b", 2: "h", 4: "i"} # 索引宽度 → struct 格式(有符号;面的顶点索引用大写 = 无符号)
def read_pmx(path):
with open(path, "rb") as f:
d = f.read()
if d[:4] != b"PMX ":
raise ValueError("不是 PMX 文件:%s" % path)
version = struct.unpack_from("<f", d, 4)[0]
r = _R(d)
r.p = 8
gc = r.u8()
g = [r.u8() for _ in range(gc)]
while len(g) < 8:
g.append(1)
enc, add_uv, vi, ti, mi, bi, moi, ri = g[:8]
r.enc = enc
m = {"version": version, "enc": enc, "add_uv": add_uv,
"sizes": (vi, ti, mi, bi, moi, ri)}
m["name"] = r.text()
m["name_en"] = r.text()
m["comment"] = r.text()
m["comment_en"] = r.text()
# ---- vertices:每个顶点按固定布局批量解(逐个字段 struct.unpack 是读大模型时最慢的一段)
r.sec = "顶点"
verts = []
head = struct.Struct("<%df" % (8 + 4 * add_uv)) # 位置、法线、UV、追加 UV
bone_st = {n: struct.Struct("<%d%s" % (n, _IDX[bi])) for n in (1, 2, 4)}
float_st = {n: struct.Struct("<%df" % n) for n in (1, 4, 9)}
for vi_ in range(r.i32("vertex count")):
r.sec = "顶点[%d]" % vi_
r._need(head.size + 1, "vertex")
v = head.unpack_from(d, r.p)
r.p += head.size
pos, nrm, uv = v[0:3], v[3:6], v[6:8]
au = [v[8 + 4 * k:12 + 4 * k] for k in range(add_uv)]
wt = d[r.p]
r.p += 1
nb = WEIGHT_BONES.get(wt, 1)
nf = WEIGHT_FLOATS.get(wt, 0)
st = bone_st[nb]
r._need(st.size, "weight bones")
bs = list(st.unpack_from(d, r.p))
r.p += st.size
ws = []
if nf:
st = float_st[nf]
r._need(st.size, "weights")
ws = list(st.unpack_from(d, r.p))
r.p += st.size
sdef = None
if wt == 3:
st = float_st[9]
r._need(st.size, "SDEF")
c = st.unpack_from(d, r.p)
r.p += st.size
sdef = (c[0:3], c[3:6], c[6:9])
edge = r.f32()
verts.append({"pos": pos, "normal": nrm, "uv": uv, "add_uv": au,
"wtype": wt, "wbones": bs, "wweights": ws,
"sdef": sdef, "edge": edge})
m["vertices"] = verts
# ---- faces(一次解完)
r.sec = "面"
nface = r.i32("face count")
r._need(nface * vi, "faces")
m["faces"] = list(struct.unpack_from("<%d%s" % (nface, _IDX[vi].upper()), d, r.p))
r.p += nface * vi
# ---- textures
r.sec = "贴图"
m["textures"] = [r.text() for _ in range(r.i32())]
# ---- materials
r.sec = "材质"
mats = []
for mi_ in range(r.i32("material count")):
r.sec = "材质[%d]" % mi_
mm = {}
mm["name"] = r.text()
mm["name_en"] = r.text()
mm["diffuse"] = (r.f32(), r.f32(), r.f32(), r.f32())
mm["specular"] = (r.f32(), r.f32(), r.f32())
mm["shininess"] = r.f32()
mm["ambient"] = (r.f32(), r.f32(), r.f32())
mm["flag"] = r.u8()
mm["edge_color"] = (r.f32(), r.f32(), r.f32(), r.f32())
mm["edge_size"] = r.f32()
mm["tex"] = r.idx(ti)
mm["sph"] = r.idx(ti)
mm["sph_mode"] = r.u8()
mm["toon_flag"] = r.u8()
# toon 的宽度**取决于 flag**,两个方向别搞反(PMX 规范 + mmd_tools 的
# `is_shared_toon_texture` 都这么写):
# flag = 1 → 共享/内建 toon(MMD 的 Data/toon01.bmp..toon10.bmp),
# 字段是**1 字节编号**,**编号 0 对应 toon01.bmp**
# (mmd_tools: `"toon%02d.bmp" % (shared_toon_texture + 1)`;
# MMD 的 Data 目录里并没有 toon00.bmp)
# flag = 0 → 本模型纹理表里的贴图,字段是**纹理索引宽度(ti)**,
# **-1 = なし(不使用 toon)** ← 「不使用」只能这么写
# mmd_tools: `if is_shared: self.toon_texture = fs.readSignedByte()
# else: self.toon_texture = fs.readTextureIndex()`
mm["toon"] = r.idx(ti) if mm["toon_flag"] == 0 else r.u8()
mm["memo"] = r.text()
mm["faces"] = r.i32()
mats.append(mm)
m["materials"] = mats
# ---- bones
r.sec = "骨骼"
bones = []
for bi_ in range(r.i32("bone count")):
r.sec = "骨骼[%d]" % bi_
b = {}
b["name"] = r.text()
b["name_en"] = r.text()
b["pos"] = (r.f32(), r.f32(), r.f32())
b["parent"] = r.idx(bi)
b["layer"] = r.i32()
r._need(2, "flag")
flag = struct.unpack_from("<H", d, r.p)[0]
r.p += 2
b["flag"] = flag
b["tail_kind"] = 1 if flag & 0x0001 else 0
b["tail"] = r.idx(bi) if (flag & 0x0001) else (r.f32(), r.f32(), r.f32())
b["inherit_rot"] = None
b["inherit_mov"] = None
b["fixed_axis"] = None
b["local_axis"] = None
b["external"] = None
b["ik"] = None
if flag & 0x0100 or flag & 0x0200:
# PMX 仕様:付与親/付与率は「共通の 1 組」しか書かれない——
# 付与回転(0x0100)と付与移動(0x0200)が同時でも 1 組だけ。
# 按两个 flag 各读一遍会多读 6 字节,从第一根双付与骨开始整体错位
# (实测小食Taberu:センター flag=0x031E 只有一组 (3, 1.0))。
gparent = r.idx(bi)
grate = r.f32()
if flag & 0x0100:
b["inherit_rot"] = (gparent, grate)
if flag & 0x0200:
b["inherit_mov"] = (gparent, grate)
if flag & 0x0400:
b["fixed_axis"] = (r.f32(), r.f32(), r.f32())
if flag & 0x0800:
b["local_axis"] = ((r.f32(), r.f32(), r.f32()),
(r.f32(), r.f32(), r.f32()))
if flag & 0x2000:
# 外部親変形:只有 4 字节的 Key,后面没有索引字节
b["external"] = r.i32()
if flag & 0x0020:
ik = {}
ik["target"] = r.idx(bi)
ik["iterations"] = r.i32()
ik["limit_angle"] = r.f32()
links = []
for _ in range(r.i32()):
lb = r.idx(bi)
has = r.u8()
if has:
links.append({"bone": lb,
"min": (r.f32(), r.f32(), r.f32()),
"max": (r.f32(), r.f32(), r.f32())})
else:
links.append({"bone": lb, "min": None, "max": None})
ik["links"] = links
b["ik"] = ik
bones.append(b)
m["bones"] = bones
# ---- morphs
r.sec = "表情"
if _DBG:
print("[dbg] morphs start p=%d" % r.p)
morphs = []
# 顶点 / UV 表情的偏移是定长记录(无符号顶点索引 + 3 / 4 个 float),整段一次解
vert_st = struct.Struct("<%s3f" % _IDX[vi].upper())
uv_st = struct.Struct("<%s4f" % _IDX[vi].upper())
for mo_ in range(r.i32("morph count")):
r.sec = "表情[%d]" % mo_
mo = {}
mo["name"] = r.text()
mo["name_en"] = r.text()
mo["panel"] = r.u8()
kind = r.u8()
mo["kind"] = kind
n = r.i32()
offs = []
if kind == 1 or kind in (3, 4, 5, 6, 7): # 顶点:3 个偏移;UV / 追加UV:4 个
st = vert_st if kind == 1 else uv_st
size = max(n, 0) * st.size
r._need(size, "morph offsets")
offs =[(o[0], o[1:]) for o in st.iter_unpack(d[r.p:r.p + size])]
r.p += size
n = 0
for _ in range(n):
if kind == 2: # 骨骼
offs.append((r.idx(bi),
(r.f32(), r.f32(), r.f32()),
(r.f32(), r.f32(), r.f32(), r.f32())))
elif kind == 8: # 材质
mat_i = r.idx(mi)
op = r.u8()
vals = [r.f32() for _ in range(28)]
offs.append((mat_i, op, vals))
elif kind == 0 or kind == 9: # グループ / フリップ
offs.append((r.idx(moi), r.f32()))
elif kind == 10: # インパルス
if _DBG:
print("[dbg] impulse morph %r n=%d @p=%d" % (mo["name"], n, r.p))
# 剛体Index, ローカルフラグ(1byte), 移動速度(3), 回転トルク(3)
offs.append((r.idx(ri), r.u8(),
(r.f32(), r.f32(), r.f32()),
(r.f32(), r.f32(), r.f32())))
else:
raise ValueError("未知的 PMX 表情类型 %d" % kind)
mo["offsets"] = offs
morphs.append(mo)
m["morphs"] = morphs
# ---- display frames
r.sec = "表示枠"
frames = []
for fr_ in range(r.i32("frame count")):
r.sec = "表示枠[%d]" % fr_
if _DBG:
print("[dbg] frame at p=%d" % r.p)
fr = {}
fr["name"] = r.text()
fr["name_en"] = r.text()
fr["special"] = r.u8()
items = []
for _ in range(r.i32()):
t = r.u8()
# 要素対象:0 = ボーン(ボーンIndex幅), 1 = モーフ(モーフIndex幅)
items.append((t, r.idx(bi) if t == 0 else r.idx(moi)))
fr["items"] = items
frames.append(fr)
m["frames"] = frames
# ---- rigid bodies
r.sec = "刚体"
if _DBG:
print("[dbg] after frames p=%d (nframes=%d)" % (r.p, len(frames)))
rbs = []
for rb_ in range(r.i32("rigid body count")):
r.sec = "刚体[%d]" % rb_
rb = {}
rb["name"] = r.text()
rb["name_en"] = r.text()
rb["bone"] = r.idx(bi)
rb["group"] = r.u8()
r._need(2, "mask")
rb["mask"] = struct.unpack_from("<H", d, r.p)[0]
r.p += 2
rb["shape"] = r.u8()
rb["size"] = (r.f32(), r.f32(), r.f32())
rb["pos"] = (r.f32(), r.f32(), r.f32())
rb["rot"] = (r.f32(), r.f32(), r.f32())
rb["mass"] = r.f32()
rb["move_damp"] = r.f32()
rb["rot_damp"] = r.f32()
rb["repulsion"] = r.f32()
rb["friction"] = r.f32()
rb["mode"] = r.u8()
rbs.append(rb)
m["rigid_bodies"] = rbs
# ---- joints
r.sec = "关节"
jts = []
for jt_ in range(r.i32("joint count")):
r.sec = "关节[%d]" % jt_
j = {}
j["name"] = r.text()
j["name_en"] = r.text()
j["type"] = r.u8()
j["rb_a"] = r.idx(ri)
j["rb_b"] = r.idx(ri)
j["pos"] = (r.f32(), r.f32(), r.f32())
j["rot"] = (r.f32(), r.f32(), r.f32())
j["move_min"] = (r.f32(), r.f32(), r.f32())
j["move_max"] = (r.f32(), r.f32(), r.f32())
# PMX 2.0 关节是 8 个 vec3:位置/旋转/移动下限/移动上限/
# 旋转下限/旋转上限/移动弹簧/旋转弹簧
j["rot_min"] = (r.f32(), r.f32(), r.f32())
j["rot_max"] = (r.f32(), r.f32(), r.f32())
j["spring_move"] = (r.f32(), r.f32(), r.f32())
j["spring_rot"] = (r.f32(), r.f32(), r.f32())
jts.append(j)
m["joints"] = jts
m["consumed"] = r.p
m["filesize"] = len(d)
# PMX 2.1 在关节之后还有一段 SoftBody
# 注意:float32 的 2.1 读回来是 2.0999999...,直接写 >= 2.1 永远不成立,
# 必须用容差比较(否则 PMX 2.1 文件末尾会剩 4 字节 SoftBody 计数读不到)。
if version > 2.05:
if r.p == len(d):
# 少数工具(如 MikuMikuDayo 的粒子 PMX)标着 2.1 却没写
# SoftBody 计数字段,容错当作 0 处理,别一棒子打死。
m["soft_bodies"] = 0
else:
r._need(4, "softbody count")
nsoft = r.i32("softbody count")
m["soft_bodies"] = nsoft
m["consumed"] = r.p
if nsoft:
raise ValueError(
"该模型是 PMX 2.1 且含 %d 个 SoftBody,本转换器暂不支持 SoftBody。"
% nsoft)
if m["consumed"] != m["filesize"]:
raise ValueError(
"PMX 解析后仍有 %d 字节未读完(已读 %d / 共 %d),"
"说明某一段的结构与写入程序不一致,请反馈此模型文件。"
% (m["filesize"] - m["consumed"], m["consumed"], m["filesize"]))
return m
# ------------------------------------------------------------------ writer --
def _isize(count, signed=True):
"""按数量挑索引字节宽度。"""
if signed:
if count <= 127:
return 1
if count <= 32767:
return 2
return 4
if count <= 255:
return 1
if count <= 65535:
return 2
return 4
class _W:
def __init__(self):
self.buf = bytearray()
def i32(self, v):
self.buf += struct.pack("<i", v)
def u8(self, v):
self.buf += struct.pack("<B", v)
def u16(self, v):
self.buf += struct.pack("<H", v)
def f32(self, v):
self.buf += struct.pack("<f", v)
def text(self, s, enc):
b = (s or "").encode("utf-16-le" if enc == 0 else "utf-8")
self.i32(len(b))
self.buf += b
def idx(self, v, size, signed=True):
if size == 1:
self.buf += struct.pack("<b" if signed else "<B", v)
elif size == 2:
self.buf += struct.pack("<h" if signed else "<H", v)
else:
self.i32(v)
def write_pmx(model, path):
m = model
verts = m["vertices"]
faces = m["faces"]
mats = m["materials"]
bones = m["bones"]
morphs = m["morphs"]
nv = len(verts)
vi = _isize(nv + 1, signed=False)
ti = _isize(len(m["textures"]) + 1)
mi = _isize(len(mats) + 1)
bi = _isize(len(bones) + 1)
moi = _isize(len(morphs) + 1)
ri = _isize(max(len(m.get("rigid_bodies") or []), 1) + 1)
w = _W()
enc = m.get("enc", MMD_ENC)
add_uv = m.get("add_uv", 0)
w.buf += b"PMX "
w.f32(m.get("version", 2.0))
w.u8(8)
for b in (enc, add_uv, vi, ti, mi, bi, moi, ri):
w.u8(b)
w.text(m.get("name", "model"), enc)
w.text(m.get("name_en", m.get("name", "model")), enc)
w.text(m.get("comment", ""), enc)
w.text(m.get("comment_en", ""), enc)
w.i32(nv)
for v in verts:
w.f32(v["pos"][0]); w.f32(v["pos"][1]); w.f32(v["pos"][2])
w.f32(v["normal"][0]); w.f32(v["normal"][1]); w.f32(v["normal"][2])
w.f32(v["uv"][0]); w.f32(v["uv"][1])
for _ in range(add_uv):
for k in range(4):
au = v.get("add_uv") or []
w.f32(au[_][k] if _ < len(au) else 0.0)
wt = v["wtype"]
w.u8(wt)
nb = WEIGHT_BONES.get(wt, 1)
bs = list(v["wbones"]) + [-1] * nb
for k in range(nb):
w.idx(bs[k] if bs[k] >= 0 else 0, bi)
if wt in (1, 3):
ws = list(v["wweights"]) + [0.0]
w.f32(ws[0])
elif wt in (2, 4):
ws = list(v["wweights"]) + [0.0] * 4
for k in range(4):
w.f32(ws[k])
if wt == 3 and v.get("sdef"):
for t in v["sdef"]:
for k in range(3):
w.f32(t[k])
elif wt == 3:
for _ in range(9):
w.f32(0.0)
w.f32(v.get("edge", 1.0))
w.i32(len(faces))
for f in faces:
w.idx(f, vi, signed=False)
w.i32(len(m["textures"]))
for t in m["textures"]:
w.text(t, enc)
w.i32(len(mats))
for mm in mats:
w.text(mm["name"], enc)
w.text(mm.get("name_en", mm["name"]), enc)
for k in range(4):
w.f32(mm["diffuse"][k])
for k in range(3):
w.f32(mm["specular"][k])
w.f32(mm["shininess"])
for k in range(3):
w.f32(mm["ambient"][k])
w.u8(mm["flag"])
for k in range(4):
w.f32(mm["edge_color"][k])
w.f32(mm["edge_size"])
w.idx(mm["tex"], ti)
w.idx(mm["sph"], ti)
w.u8(mm["sph_mode"])
w.u8(mm["toon_flag"])
# 宽度随 flag 变(见读取侧注释):flag=1 → 1 字节内建 toon 号;
# flag=0 → 纹理索引宽度。
if mm["toon_flag"] == 0:
w.idx(mm["toon"], ti)
else:
w.u8(mm["toon"])
w.text(mm.get("memo", ""), enc)
w.i32(mm["faces"])
w.i32(len(bones))
for b in bones:
w.text(b["name"], enc)
w.text(b.get("name_en", b["name"]), enc)
for k in range(3):
w.f32(b["pos"][k])
w.idx(b["parent"], bi)
w.i32(b.get("layer", 0))
flag = b["flag"]
w.u16(flag)
if flag & 0x0001:
w.idx(b["tail"], bi)
else:
for k in range(3):
w.f32(b["tail"][k])
if flag & 0x0100 or flag & 0x0200:
# 与读取侧同理:付与親/付与率只写共通的一组。
# 两个 flag 同开时两组值理应一致;万一不一致(旧版本写出的文件),
# 以回転付与为准,避免丢信息。
if flag & 0x0100:
gp, gr = b["inherit_rot"]
else:
gp, gr = b["inherit_mov"]
w.idx(gp, bi)
w.f32(gr)
if flag & 0x0400:
for k in range(3):
w.f32(b["fixed_axis"][k])
if flag & 0x0800:
for t in b["local_axis"]:
for k in range(3):
w.f32(t[k])
if flag & 0x2000:
ext = b["external"]
w.i32(ext if isinstance(ext, int) else (ext or (0,))[0])
if flag & 0x0020:
ik = b["ik"]
w.idx(ik["target"], bi)
w.i32(ik["iterations"])
w.f32(ik["limit_angle"])
w.i32(len(ik["links"]))
for lk in ik["links"]:
w.idx(lk["bone"], bi)
if lk.get("min"):
w.u8(1)
for k in range(3):
w.f32(lk["min"][k])
for k in range(3):
w.f32(lk["max"][k])
else:
w.u8(0)
w.i32(len(morphs))
for mo in morphs:
w.text(mo["name"], enc)
w.text(mo.get("name_en", mo["name"]), enc)
w.u8(mo["panel"])
kind = mo["kind"]
w.u8(kind)
w.i32(len(mo["offsets"]))
for off in mo["offsets"]:
if kind == 1:
w.idx(off[0], vi, signed=False)
for k in range(3):
w.f32(off[1][k])
elif kind in (3, 4, 5, 6, 7):
w.idx(off[0], vi, signed=False)
for k in range(4):
w.f32(off[1][k])
elif kind == 2:
w.idx(off[0], bi)
for k in range(3):
w.f32(off[1][k])
for k in range(4):
w.f32(off[2][k])
elif kind == 8:
w.idx(off[0], mi)
w.u8(off[1])
for x in off[2]:
w.f32(x)
elif kind == 0 or kind == 9:
w.idx(off[0], moi)
w.f32(off[1])
elif kind == 10:
w.idx(off[0], ri)
for k in range(3):
w.f32(off[1][k])
for k in range(3):
w.f32(off[2][k])
frames = m.get("frames") or []
w.i32(len(frames))
for fr in frames:
w.text(fr["name"], enc)
w.text(fr.get("name_en", fr["name"]), enc)
w.u8(fr.get("special", 0))
w.i32(len(fr["items"]))
for t, i in fr["items"]:
w.u8(t)
w.idx(i, bi if t == 0 else moi)
rbs = m.get("rigid_bodies") or []
w.i32(len(rbs))
for rb in rbs:
w.text(rb["name"], enc)
w.text(rb.get("name_en", rb["name"]), enc)
w.idx(rb["bone"], bi)
w.u8(rb["group"])
w.u16(rb["mask"])
w.u8(rb["shape"])
for k in range(3):
w.f32(rb["size"][k])
for k in range(3):
w.f32(rb["pos"][k])
for k in range(3):
w.f32(rb["rot"][k])
w.f32(rb["mass"])
w.f32(rb["move_damp"])
w.f32(rb["rot_damp"])
w.f32(rb["repulsion"])
w.f32(rb["friction"])
w.u8(rb["mode"])
jts = m.get("joints") or []
w.i32(len(jts))
for j in jts:
w.text(j["name"], enc)
w.text(j.get("name_en", j["name"]), enc)
w.u8(j["type"])
w.idx(j["rb_a"], ri)
w.idx(j["rb_b"], ri)
for k in range(3):
w.f32(j["pos"][k])
for k in range(3):
w.f32(j["rot"][k])
for k in range(3):
w.f32(j["move_min"][k])
for k in range(3):
w.f32(j["move_max"][k])
rm = j.get("rot_min") or (0.0, 0.0, 0.0)
rx = j.get("rot_max") or (0.0, 0.0, 0.0)
for k in range(3):
w.f32(rm[k])
for k in range(3):
w.f32(rx[k])
for k in range(3):
w.f32(j["spring_move"][k])
for k in range(3):
w.f32(j["spring_rot"][k])
# PMX 2.1 需要写 SoftBody 计数(本转换器不支持 SoftBody,恒写 0)
if m.get("version", 2.0) > 2.05:
w.i32(0)
with open(path, "wb") as f:
f.write(w.buf)
return len(w.buf)
# ------------------------------------------------------- 缠绕顺序自动判定 --
def detect_winding(positions, normals, faces, sample=4000):
"""判断三角形的缠绕方向是否与法线一致。
positions: [(x,y,z), ...]
normals : [(x,y,z), ...] 与 positions 一一对应
faces : [i0,i1,i2, ...] 展平的索引
返回 (need_flip, agree, disagree):
need_flip=True 表示按现在的顺序算出来的几何法线与顶点法线相反,
应该交换后两个索引。
实测:PMX 与 glTF 的原始数据都是「从外面看逆时针」,几何法线与顶点法线同向。
注意(2026-09-18):这只对「未经手性修正的原始数据」成立。
pmx2vrm 做镜面反射(改手性)之后,绕序会被颠倒,
所以转换器里的 auto 判定必须用「反射后的数据」重新投票,
那时会判「需要反转」——这是正确的,别因此改回不反转。
以前硬编码「必须反转」是错的,会让模型在 MMD / VRM 查看器里被背面剔除,
表现就是大面积镂空 + 轮廓线糊成一片黑。
"""
n_tri = len(faces) // 3
if n_tri == 0 or not normals or len(normals) < len(positions):
return False, 0, 0
step = 1 if n_tri <= sample else (n_tri + sample - 1) // sample
agree = disagree = 0
for t in range(0, n_tri, step):
a = faces[t * 3]
b = faces[t * 3 + 1]
c = faces[t * 3 + 2]
if a >= len(positions) or b >= len(positions) or c >= len(positions):
continue
pa, pb, pc = positions[a], positions[b], positions[c]
e1 = (pb[0] - pa[0], pb[1] - pa[1], pb[2] - pa[2])
e2 = (pc[0] - pa[0], pc[1] - pa[1], pc[2] - pa[2])
gn = (e1[1] * e2[2] - e1[2] * e2[1],
e1[2] * e2[0] - e1[0] * e2[2],
e1[0] * e2[1] - e1[1] * e2[0])
if abs(gn[0]) + abs(gn[1]) + abs(gn[2]) < 1e-12:
continue
na = normals[a]
nb = normals[b]
nc = normals[c]
vn = (na[0] + nb[0] + nc[0], na[1] + nb[1] + nc[1],
na[2] + nb[2] + nc[2])
d = gn[0] * vn[0] + gn[1] * vn[1] + gn[2] * vn[2]
if d > 0:
agree += 1
elif d < 0:
disagree += 1
if agree + disagree == 0:
return False, 0, 0
return (disagree > agree), agree, disagree
# ------------------------------------------------------------- 空模型工具 --
def new_model(name="Model"):
return {
"version": 2.0, "enc": MMD_ENC, "add_uv": 0,
"name": name, "name_en": name, "comment": "", "comment_en": "",
"vertices": [], "faces": [], "textures": [], "materials": [],
"bones": [], "morphs": [], "frames": [],
"rigid_bodies": [], "joints": [],
}
def strip_edges(model, force_double_sided=True):
"""去除 PMX 的黑色轮廓线(MMD 轮廓线 / edge line)。
对输出到 MMD 后常见的“模型边缘出现黑边”问题,把材质的轮廓线标记、
粗细、颜色 alpha 全部关闭,并把每个顶点的 edge 系数置 0。
可选同时强制开启双面描绘,减少因背面剔除产生的黑缝/镂空。
"""
for v in model.get("vertices", []):
v["edge"] = 0.0
for mm in model.get("materials", []):
mm["flag"] = (mm.get("flag", 0x0F) & ~0x10)
if force_double_sided:
mm["flag"] |= 0x01
mm["edge_size"] = 0.0
ec = list(mm.get("edge_color") or (0.0, 0.0, 0.0, 1.0))
while len(ec) < 4:
ec.append(1.0)
ec[3] = 0.0
mm["edge_color"] = tuple(ec)
return model
# ------------------------------------------------------- 文本编码转换工具 --
def convert_encoding(src, dst=None, enc=MMD_ENC, verbose=True):
"""把已有 PMX 的文本编码改成 enc(默认 UTF-16LE —— MMD 唯一认的编码)。
用于修复早先版本导出的 UTF-8 PMX:MMD 会报
「MMDではエンコード方式がUTF16のPMXファイルしか読み込めません」而拒绝载入。
不传 dst 时写到同目录的 "<名字>_utf16.pmx"(不覆盖原文件)。
返回 (输出路径, 字节数)。
"""
model = read_pmx(src)
old = model.get("enc", ENC_UTF8)
model["enc"] = enc
if dst is None:
stem, _ext = os.path.splitext(src)
dst = stem + ("_utf16.pmx" if enc == ENC_UTF16 else "_utf8.pmx")
tmp = dst + ".tmp"
n = write_pmx(model, tmp)
# 回读校验:能完整解析、名称一致才认账,避免把文件改坏
back = read_pmx(tmp)
if back["name"] != model["name"] or back["consumed"] != back["filesize"]:
os.remove(tmp)
raise ValueError("改写后回读校验失败,未写入:%s" % src)
os.replace(tmp, dst)
if verbose:
print("%-40s 编码 %d(%s) -> %d(%s) %.2f MB" % (
os.path.basename(src), old, "UTF-8" if old else "UTF-16LE",
enc, "UTF-8" if enc else "UTF-16LE", n / 1048576.0))
return dst, n
if __name__ == "__main__":
import argparse
ap = argparse.ArgumentParser(
description="把 PMX 的文本编码改成 MMD 能读的那种(默认 UTF-16LE)")
ap.add_argument("files", nargs="+", help="要处理的 .pmx")
ap.add_argument("--enc", choices=("utf16", "utf8"), default="utf16",
help="目标编码,默认 utf16(MMD 只认这个)")
ap.add_argument("-o", "--out", default=None, help="输出路径(仅限单个输入)")
ap.add_argument("--in-place", action="store_true",
help="直接覆盖原文件(危险,建议先备份)")
a = ap.parse_args()
if a.out and len(a.files) > 1:
ap.error("-o 只能配合单个输入文件使用")
want = ENC_UTF16 if a.enc == "utf16" else ENC_UTF8
for p in a.files:
try:
convert_encoding(p, a.out or (p if a.in_place else None), want)
except Exception as e:
print("失败 %s:%s" % (p, e))
+522
View File
@@ -0,0 +1,522 @@
# -*- 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)
+873
View File
@@ -0,0 +1,873 @@
# -*- coding: utf-8 -*-
"""UEFormat(.uemodel)读写库 —— 纯标准库。
`.uemodel` 不是某游戏的私有格式,而是 **UEFormat**:FortnitePorting / FModel /
CUE4Parse 用来在「UE 资源」和「Blender / UE 插件」之间交换模型的公开中间格式,
规范在 https://github.com/h4lfheart/UEFormat (docs/generic.md + docs/uemodel.md),
Blender 插件(io_scene_ueformat)与 UE 插件都是开源的。所以它**有统一标准**。
但标准有过一次结构性改版(version.py 里的 AttributeFormatRestructure = 10),
所以实际存在两套字节布局:
v <= 9(legacy)
头部: "UEFORMAT" + FString Identifier + u8 FileVersion + FString ObjectName
+ bool bIsCompressed
主体: 从当前位置一口气读到 EOF,每个「分块」是
FString Name + i32 ArraySize + i32 ByteSize + ByteSize 字节负载
ArraySize 是**负载内**数组的元素个数,写在分块头部;
负载里不再重复数组长度。
v >= 10(AttributeFormatRestructure)
头部: 同上,但在 ObjectName 之后多了 FString ObjectPath
主体: FDataAttributeSet = i32 Count + Count × (FString Name + i32 ByteSize + 负载)
数组长度写在负载内部的 TArray 前缀里(i32 Count + 元素)。
读取端按版本自动分派;写出端两版都能写。
坐标与单位(实测样本 + UE 约定)
UE 是**左手系、Z 轴向上**,X 向前、Y 向右;1 单位 = 1 cm。
MMD/PMX 是左手系、Y 轴向上、脸朝 -Z。两边手性相同(行列式 +1),
所以只需要换轴、**不需要反绕序**(见 convert/uemodel2pmx.py)。
自检口径:`read_uemodel()` 结束时必须 `r.p == len(r.b)`,与 pmxio 的
`consumed == filesize` 一个路子;分块负载也逐个按 ByteSize 切片消费,
任何一段读偏都会在末尾暴露成「末尾字节数不符」。
"""
import os
import struct
import sys
MAGIC = b"UEFORMAT"
IDENT_MODEL = "UEMODEL"
VERSION_LATEST = 10 # AttributeFormatRestructure
V_SERIALIZE_BINORMAL = 1 # NORMALS 里开始带 binormalSign
V_MULTI_VCOLOR = 2 # VERTEXCOLORS 支持多套
V_LOD_RESTRUCTURE = 4 # LOD 变成 name + 独立大小
V_VIRTUAL_BONES = 5
V_MATERIAL_PATH = 6
V_ASSET_METADATA = 7
V_PRESERVE_TRANSFORM = 8 # BONES 带 scale
V_ATTR_RESTRUCTURE = 10 # 布局大改(见模块 docstring)
def _repair_version(v):
"""老版本写出来的 0 号版本其实等于 1(BinormalSign 已经在了)。"""
return V_SERIALIZE_BINORMAL if v == 0 else v
# ------------------------------------------------------------------ 数据结构 --
class Bone(object):
__slots__ = ("name", "parent", "pos", "rot", "scale")
def __init__(self, name="", parent=-1, pos=(0.0, 0.0, 0.0),
rot=(0.0, 0.0, 0.0, 1.0), scale=(1.0, 1.0, 1.0)):
self.name = name
self.parent = parent
self.pos = pos
self.rot = rot
self.scale = scale
class Socket(object):
__slots__ = ("name", "bone", "pos", "rot", "scale")
def __init__(self, name="", bone="", pos=(0.0, 0.0, 0.0),
rot=(0.0, 0.0, 0.0, 1.0), scale=(1.0, 1.0, 1.0)):
self.name = name
self.bone = bone
self.pos = pos
self.rot = rot
self.scale = scale
class Skeleton(object):
__slots__ = ("path", "bones", "sockets", "virtual_bones")
def __init__(self):
self.path = ""
self.bones = []
self.sockets = []
self.virtual_bones = [] # [(source, target, virtual)]
class VertexColor(object):
__slots__ = ("name", "data") # data: [(r,g,b,a)] 0~255
def __init__(self, name="COL0", data=None):
self.name = name
self.data = data or []
class Material(object):
__slots__ = ("name", "path", "first_index", "num_faces")
def __init__(self, name="", path="", first_index=0, num_faces=0):
self.name = name
self.path = path
self.first_index = first_index # 索引入缓冲(顶点索引)里的起点
self.num_faces = num_faces # 三角面数
@property
def first_face(self):
return self.first_index // 3
class Weight(object):
__slots__ = ("bone", "vertex", "weight")
def __init__(self, bone=0, vertex=0, weight=0.0):
self.bone = bone
self.vertex = vertex
self.weight = weight
class MorphDelta(object):
__slots__ = ("pos", "normal", "vertex")
def __init__(self, pos=(0.0, 0.0, 0.0), normal=(0.0, 0.0, 0.0), vertex=0):
self.pos = pos
self.normal = normal
self.vertex = vertex
class Morph(object):
__slots__ = ("name", "deltas")
def __init__(self, name="", deltas=None):
self.name = name
self.deltas = deltas or []
class UVSet(object):
__slots__ = ("name", "uvs")
def __init__(self, name="UV0", uvs=None):
self.name = name
self.uvs = uvs or []
class Collision(object):
__slots__ = ("name", "vertices", "indices", "faces")
def __init__(self, name="", vertices=None, indices=None):
self.name = name
self.vertices = vertices or []
self.indices = indices or []
class LOD(object):
def __init__(self, name="LOD0"):
self.name = name
self.vertices = [] # [(x, y, z)]
self.normals = [] # [(x, y, z)]
self.binormals = [] # 每顶点 binormal sign(FNormal 的第一个 float)
self.tangents = [] # [(x, y, z)]
self.uvs = [] # [UVSet]
self.indices = [] # 三角面顶点索引(每 3 个一面)
self.colors = [] # [VertexColor]
self.materials = [] # [Material]
self.weights = [] # [Weight](稀疏:一个顶点可能有多条)
self.morphs = [] # [Morph]
def stats(self):
return {"verts": len(self.vertices), "tris": len(self.indices) // 3,
"mats": len(self.materials), "weights": len(self.weights),
"morphs": len(self.morphs), "uvsets": len(self.uvs)}
class UEModel(object):
def __init__(self):
self.identifier = IDENT_MODEL
self.version = VERSION_LATEST
self.name = ""
self.path = ""
self.compressed = False
self.lods = []
self.skeleton = Skeleton()
self.collisions = []
def stats(self):
return {"version": self.version, "lods": len(self.lods),
"bones": len(self.skeleton.bones),
"sockets": len(self.skeleton.sockets),
"collisions": len(self.collisions),
"skinned": bool(self.lods and self.lods[0].weights)}
# --------------------------------------------------------------------- 读取 --
class _R(object):
__slots__ = ("b", "p")
def __init__(self, data):
self.b = data
self.p = 0
def eof(self):
return self.p >= len(self.b)
def left(self):
return len(self.b) - self.p
def u8(self):
v = self.b[self.p]
self.p += 1
return v
def bool(self):
return self.u8() != 0
def i16(self):
v = struct.unpack_from("<h", self.b, self.p)[0]
self.p += 2
return v
def u16(self):
v = struct.unpack_from("<H", self.b, self.p)[0]
self.p += 2
return v
def i32(self):
v = struct.unpack_from("<i", self.b, self.p)[0]
self.p += 4
return v
def u32(self):
v = struct.unpack_from("<I", self.b, self.p)[0]
self.p += 4
return v
def f32(self):
v = struct.unpack_from("<f", self.b, self.p)[0]
self.p += 4
return v
def vec(self, n):
v = struct.unpack_from("<%df" % n, self.b, self.p)
self.p += 4 * n
return v
def ints(self, n):
v = struct.unpack_from("<%dI" % n, self.b, self.p) if n > 0 else ()
self.p += 4 * n
return v
def bytes(self, n):
v = self.b[self.p:self.p + n]
self.p += n
return v
def fstr(self):
n = self.i32()
if n <= 0:
return ""
raw = self.b[self.p:self.p + n]
self.p += n
return raw.rstrip(b"\x00").decode("utf-8", "replace")
def _chunks(r, version):
"""按版本迭代「分块」,产出 (name, array_size, payload_reader)。
负载一律按声明字节数切出来单独给一个 reader —— 与官方 iter_chunks 的
「读完 seek 到下一个块」等价,任何一段读偏都不会污染后面的分块。
"""
if version >= V_ATTR_RESTRUCTURE:
count = r.i32()
for _ in range(count):
name = r.fstr()
size = r.i32()
yield name, None, _R(r.bytes(max(0, size)))
else:
while not r.eof():
name = r.fstr()
arr = r.i32()
size = r.i32()
yield name, arr, _R(r.bytes(max(0, size)))
def _arr_len(payload, version, array_size):
"""取「数组元素个数」:v10 在负载里,v9 在分块头。"""
if version >= V_ATTR_RESTRUCTURE:
return payload.i32()
return array_size if array_size is not None else 0
def _read_lod(r, version):
lod = LOD(name=r.fstr())
if version >= V_ATTR_RESTRUCTURE:
body = r
else:
body = _R(r.bytes(max(0, r.i32())))
for name, arr, pl in _chunks(body, version):
if name == "VERTICES":
n = _arr_len(pl, version, arr)
lod.vertices = [tuple(pl.vec(3)) for _ in range(n)]
elif name == "NORMALS":
n = _arr_len(pl, version, arr)
if version >= V_SERIALIZE_BINORMAL:
for _ in range(n):
sign = pl.f32()
lod.binormals.append(sign)
lod.normals.append(tuple(pl.vec(3)))
else:
lod.normals = [tuple(pl.vec(3)) for _ in range(n)]
elif name == "TANGENTS":
n = _arr_len(pl, version, arr)
lod.tangents = [tuple(pl.vec(3)) for _ in range(n)]
elif name == "TEXCOORDS":
n = _arr_len(pl, version, arr)
for _ in range(n):
# v10 起每个 UV 通道带名字,v9 没有
uname = pl.fstr() if version >= V_ATTR_RESTRUCTURE else ""
c = pl.i32()
uv = [tuple(pl.vec(2)) for _ in range(max(0, c))]
lod.uvs.append(UVSet(uname or ("UV%d" % len(lod.uvs)), uv))
elif name == "INDICES":
n = _arr_len(pl, version, arr)
lod.indices = list(pl.ints(max(0, n)))
elif name == "VERTEXCOLORS":
n = _arr_len(pl, version, arr)
for _ in range(n):
vc = VertexColor(name="COL0")
if version >= V_MULTI_VCOLOR:
vc.name = pl.fstr()
c = pl.i32()
raw = pl.bytes(max(0, c) * 4)
vc.data = [tuple(raw[i * 4:i * 4 + 4]) for i in range(max(0, c))]
lod.colors.append(vc)
elif name == "MATERIALS":
n = _arr_len(pl, version, arr)
for _ in range(n):
mat = Material(name=pl.fstr())
if version >= V_MATERIAL_PATH:
mat.path = pl.fstr()
mat.first_index = pl.i32()
mat.num_faces = pl.i32()
lod.materials.append(mat)
elif name == "WEIGHTS":
n = _arr_len(pl, version, arr)
for _ in range(n):
b = pl.u16() if version >= V_ATTR_RESTRUCTURE else pl.i16()
lod.weights.append(Weight(b, pl.i32(), pl.f32()))
elif name == "MORPHTARGETS":
n = _arr_len(pl, version, arr)
for _ in range(n):
mo = Morph(name=pl.fstr())
c = pl.i32()
for _ in range(max(0, c)):
p = tuple(pl.vec(3))
nn = tuple(pl.vec(3))
mo.deltas.append(MorphDelta(p, nn, pl.i32()))
lod.morphs.append(mo)
# 未知分块按声明大小跳过(已经按 ByteSize 切片,天然安全)
return lod
def _read_bones(payload, n, version):
"""骨骼数组:v10 带 scale;v9 不带。带自动回退以兼容不同写入器。"""
with_scale = version >= V_ATTR_RESTRUCTURE
bones = []
try:
for _ in range(n):
b = Bone(name=payload.fstr())
b.parent = payload.i32()
b.pos = tuple(payload.vec(3))
b.rot = tuple(payload.vec(4))
b.scale = tuple(payload.vec(3)) if with_scale else ()
bones.append(b)
except struct.error:
return None
if payload.p != len(payload.b):
return None
if not with_scale:
# 若按「无 scale」读却没正好吃到末尾,改按「有 scale」重来
alt = _R(payload.b)
bones2 = []
try:
for _ in range(n):
b = Bone(name=alt.fstr())
b.parent = alt.i32()
b.pos = tuple(alt.vec(3))
b.rot = tuple(alt.vec(4))
b.scale = tuple(alt.vec(3))
bones2.append(b)
except struct.error:
return bones
if alt.p == len(alt.b):
return bones2
return bones
def _read_skeleton(r, version):
sk = Skeleton()
for name, arr, pl in _chunks(r, version):
if name == "METADATA":
sk.path = pl.fstr()
elif name == "BONES":
n = _arr_len(pl, version, arr)
got = _read_bones(pl, max(0, n), version)
if got is not None:
sk.bones = got
elif name == "SOCKETS":
n = _arr_len(pl, version, arr)
for _ in range(max(0, n)):
s = Socket(name=pl.fstr(), bone=pl.fstr())
s.pos = tuple(pl.vec(3))
s.rot = tuple(pl.vec(4))
s.scale = tuple(pl.vec(3))
sk.sockets.append(s)
elif name == "VIRTUALBONES":
n = _arr_len(pl, version, arr)
for _ in range(max(0, n)):
sk.virtual_bones.append((pl.fstr(), pl.fstr(), pl.fstr()))
return sk
def _read_collision(h, version):
col = Collision(name=h.fstr())
nv = h.i32()
col.vertices = [tuple(h.vec(3)) for _ in range(max(0, nv))]
ni = h.i32()
col.indices = list(h.ints(max(0, ni)))
return col
def _decompress_body(r, src):
"""读取压缩体头部并解压,返回未压缩的字节流(分块流)。
支持 UEFormat 已用到的两种压缩:ZSTD(需 zstandard 第三方库)、
GZIP(标准库 gzip)。压缩体头部布局见 parse_uemodel 中的说明。
"""
import io
cfmt = (r.fstr() or "").upper()
uncompressed = r.i32()
compressed = r.i32()
payload = r.bytes(compressed) if compressed > 0 else r.left()
if cfmt == "ZSTD":
try:
import zstandard as zstd
except ImportError:
raise ValueError("该 .uemodel 是 ZSTD 压缩体,但运行环境缺少 zstandard 库,"
"无法解压:%s" % src)
dctx = zstd.ZstdDecompressor()
try:
if uncompressed > 0:
return dctx.decompress(payload, uncompressed)
# 帧内未记录原始大小:改用流式解压读完整帧
with dctx.stream_reader(io.BytesIO(payload)) as reader:
return reader.read()
except Exception as e:
raise ValueError("ZSTD 解压失败:%s(%s)" % (src, e))
elif cfmt in ("GZIP", "GZIPSTREAM"):
import gzip
try:
return gzip.decompress(payload)
except Exception as e:
raise ValueError("GZIP 解压失败:%s(%s)" % (src, e))
else:
raise ValueError("不支持的压缩格式 %r:%s" % (cfmt, src))
def read_uemodel(path, verbose=False):
"""读 .uemodel。返回 UEModel;末尾字节数不符直接抛 ValueError。"""
with open(path, "rb") as f:
data = f.read()
return parse_uemodel(data, verbose=verbose, src=path)
def parse_uemodel(data, verbose=False, src=""):
r = _R(data)
if r.bytes(8) != MAGIC:
raise ValueError("不是 UEFormat 文件(魔数不是 UEFORMAT):%s" % src)
m = UEModel()
m.identifier = r.fstr()
m.version = r.u8()
m.name = r.fstr()
if m.version >= V_ATTR_RESTRUCTURE:
m.path = r.fstr() # v10 起才有 ObjectPath
m.compressed = r.bool()
if m.compressed:
# 压缩体头部紧跟在 bIsCompressed 之后(UEFormat 规范):
# FString CompressionFormat + i32 UncompressedSize
# + i32 CompressedSize + CompressedData
# 解压后得到的就是未压缩的「分块流」,从偏移 0 起按普通流程解析即可。
raw = _decompress_body(r, src)
r = _R(raw)
if m.identifier not in ("UEMODEL", ""):
raise ValueError("不是模型文件(Identifier=%r):%s" % (m.identifier, src))
if m.version > VERSION_LATEST:
raise ValueError("UEFormat 版本 %d 高于本库支持的 %d:%s"
% (m.version, VERSION_LATEST, src))
ver = _repair_version(m.version)
for name, arr, pl in _chunks(r, ver):
if name == "LODS":
n = _arr_len(pl, ver, arr)
for _ in range(max(0, n)):
m.lods.append(_read_lod(pl, ver))
elif name == "SKELETON":
m.skeleton = _read_skeleton(pl, ver)
elif name == "COLLISION":
n = _arr_len(pl, ver, arr)
for _ in range(max(0, n)):
m.collisions.append(_read_collision(pl, ver))
# 未知顶层分块忽略
if r.p != len(r.b):
raise ValueError("解析失步:消费 %d 字节,文件 %d 字节(差 %d)"
% (r.p, len(r.b), len(r.b) - r.p))
if verbose:
print_uemodel(m, src=src)
return m
# --------------------------------------------------------------------- 写出 --
class _W(object):
__slots__ = ("buf",)
def __init__(self):
self.buf = bytearray()
def u8(self, v):
self.buf.append(v & 0xFF)
def bool(self, v):
self.u8(1 if v else 0)
def i16(self, v):
self.buf += struct.pack("<h", int(v))
def u16(self, v):
self.buf += struct.pack("<H", int(v) & 0xFFFF)
def i32(self, v):
self.buf += struct.pack("<i", int(v))
def u32(self, v):
self.buf += struct.pack("<I", int(v))
def f32(self, v):
self.buf += struct.pack("<f", float(v))
def vec(self, v):
self.buf += struct.pack("<%df" % len(v), *[float(x) for x in v])
def raw(self, b):
self.buf += b
def fstr(self, s):
b = (s or "").encode("utf-8")
self.i32(len(b))
self.buf += b
def get(self):
return bytes(self.buf)
def _pack_chunk(name, array_size, payload, version):
w = _W()
w.fstr(name)
if version < V_ATTR_RESTRUCTURE:
w.i32(array_size if array_size is not None else 0)
w.i32(len(payload))
w.raw(payload)
return w.get()
def _pack_attrset(items, version):
"""items: [(name, array_size, payload_bytes)]"""
w = _W()
if version >= V_ATTR_RESTRUCTURE:
w.i32(len(items))
for name, arr, payload in items:
w.raw(_pack_chunk(name, arr, payload, version))
return w.get()
def _pack_vec_array(vecs, version, width=3):
w = _W()
if version >= V_ATTR_RESTRUCTURE:
w.i32(len(vecs))
for v in vecs:
w.vec(v)
return w.get()
def _pack_indices(idx, version):
w = _W()
if version >= V_ATTR_RESTRUCTURE:
w.i32(len(idx))
for v in idx:
w.u32(v)
return w.get()
def _pack_lod(lod, version):
w = _W()
items = []
nv = len(lod.vertices)
items.append(("VERTICES", nv, _pack_vec_array(lod.vertices, version)))
nrm = _W()
if version >= V_ATTR_RESTRUCTURE:
nrm.i32(nv)
for i in range(nv):
n = lod.normals[i] if i < len(lod.normals) else (0.0, 0.0, 1.0)
sign = lod.binormals[i] if i < len(lod.binormals) else 1.0
nrm.f32(sign)
nrm.vec(n)
if version < V_SERIALIZE_BINORMAL:
# 极老版本(本库不产出):只写向量
old = _W()
for i in range(nv):
old.vec(lod.normals[i] if i < len(lod.normals) else (0.0, 1.0, 0.0))
items.append(("NORMALS", nv, old.get()))
else:
items.append(("NORMALS", nv, nrm.get()))
if lod.tangents:
items.append(("TANGENTS", nv, _pack_vec_array(lod.tangents, version)))
tex = _W()
if version >= V_ATTR_RESTRUCTURE:
tex.i32(len(lod.uvs))
for i, st in enumerate(lod.uvs):
if version >= V_ATTR_RESTRUCTURE:
tex.fstr(st.name or ("UV%d" % i))
tex.i32(len(st.uvs))
for uv in st.uvs:
tex.vec(uv)
items.append(("TEXCOORDS", len(lod.uvs), tex.get()))
items.append(("INDICES", len(lod.indices),
_pack_indices(lod.indices, version)))
if lod.colors:
vc = _W()
if version >= V_ATTR_RESTRUCTURE:
vc.i32(len(lod.colors))
for st in lod.colors:
if version >= V_MULTI_VCOLOR:
vc.fstr(st.name or "COL0")
vc.i32(len(st.data))
for c in st.data:
vc.u8(c[0] if len(c) > 0 else 255)
vc.u8(c[1] if len(c) > 1 else 255)
vc.u8(c[2] if len(c) > 2 else 255)
vc.u8(c[3] if len(c) > 3 else 255)
items.append(("VERTEXCOLORS", len(lod.colors), vc.get()))
if lod.materials:
mm = _W()
if version >= V_ATTR_RESTRUCTURE:
mm.i32(len(lod.materials))
for mt in lod.materials:
mm.fstr(mt.name)
if version >= V_MATERIAL_PATH:
mm.fstr(mt.path)
mm.i32(mt.first_index)
mm.i32(mt.num_faces)
items.append(("MATERIALS", len(lod.materials), mm.get()))
if lod.weights:
wt = _W()
if version >= V_ATTR_RESTRUCTURE:
wt.i32(len(lod.weights))
for x in lod.weights:
if version >= V_ATTR_RESTRUCTURE:
wt.u16(x.bone)
else:
wt.i16(x.bone)
wt.i32(x.vertex)
wt.f32(x.weight)
items.append(("WEIGHTS", len(lod.weights), wt.get()))
if lod.morphs:
mo = _W()
if version >= V_ATTR_RESTRUCTURE:
mo.i32(len(lod.morphs))
for m in lod.morphs:
mo.fstr(m.name)
mo.i32(len(m.deltas))
for d in m.deltas:
mo.vec(d.pos)
mo.vec(d.normal)
mo.i32(d.vertex)
items.append(("MORPHTARGETS", len(lod.morphs), mo.get()))
body = _pack_attrset(items, version)
if version >= V_ATTR_RESTRUCTURE:
# v10 的 UEModelLOD = FString Name + FDataAttributeSet(规范 docs/uemodel.md):
# 名字照写,但属性集**自带** i32 Count 定界,不再套一层 ByteSize。
# 曾经漏写这里的名 → 读取端读了名,整条 LOD 流错位,末尾报「解析失步」。
w.fstr(lod.name or "")
w.raw(body)
else:
w.fstr(lod.name)
w.i32(len(body))
w.raw(body)
return w.get()
def _pack_skeleton(sk, version):
items = []
if sk.path:
w = _W()
w.fstr(sk.path)
items.append(("METADATA", 1, w.get()))
bw = _W()
if version >= V_ATTR_RESTRUCTURE:
bw.i32(len(sk.bones))
for b in sk.bones:
bw.fstr(b.name)
bw.i32(b.parent)
bw.vec(b.pos)
bw.vec(b.rot if len(b.rot) == 4 else (0.0, 0.0, 0.0, 1.0))
if version >= V_ATTR_RESTRUCTURE:
bw.vec(b.scale if len(b.scale) == 3 else (1.0, 1.0, 1.0))
items.append(("BONES", len(sk.bones), bw.get()))
if sk.sockets:
sw = _W()
if version >= V_ATTR_RESTRUCTURE:
sw.i32(len(sk.sockets))
for s in sk.sockets:
sw.fstr(s.name)
sw.fstr(s.bone)
sw.vec(s.pos)
sw.vec(s.rot)
sw.vec(s.scale)
items.append(("SOCKETS", len(sk.sockets), sw.get()))
if sk.virtual_bones:
vw = _W()
if version >= V_ATTR_RESTRUCTURE:
vw.i32(len(sk.virtual_bones))
for t in sk.virtual_bones:
vw.fstr(t[0])
vw.fstr(t[1])
vw.fstr(t[2])
items.append(("VIRTUALBONES", len(sk.virtual_bones), vw.get()))
return _pack_attrset(items, version)
def _pack_collision(col, version):
w = _W()
w.fstr(col.name)
w.i32(len(col.vertices))
for v in col.vertices:
w.vec(v)
w.i32(len(col.indices))
for i in col.indices:
w.i32(i)
return w.get()
def build_uemodel_bytes(m, version=None):
"""把 UEModel 序列化成字节。version=None 用 m.version。"""
ver = _repair_version(int(version if version else m.version))
w = _W()
w.raw(MAGIC)
w.fstr(m.identifier or IDENT_MODEL)
w.u8(ver)
w.fstr(m.name)
if ver >= V_ATTR_RESTRUCTURE:
w.fstr(m.path or "")
w.bool(False)
items = []
lw = _W()
if ver >= V_ATTR_RESTRUCTURE:
lw.i32(len(m.lods))
for lod in m.lods:
lw.raw(_pack_lod(lod, ver))
items.append(("LODS", len(m.lods), lw.get()))
items.append(("SKELETON", 1, _pack_skeleton(m.skeleton, ver)))
if m.collisions:
cw = _W()
if ver >= V_ATTR_RESTRUCTURE:
cw.i32(len(m.collisions))
for col in m.collisions:
cw.raw(_pack_collision(col, ver))
items.append(("COLLISION", len(m.collisions), cw.get()))
w.raw(_pack_attrset(items, ver))
return w.get()
def write_uemodel(m, path, version=None):
data = build_uemodel_bytes(m, version=version)
tmp = path + ".tmp"
with open(tmp, "wb") as f:
f.write(data)
os.replace(tmp, path)
return len(data)
# ----------------------------------------------------------------- 文本输出 --
def print_uemodel(m, src=""):
if src:
print("文件:%s" % src)
print("UEFormat v%d · %s · 名称 %s" % (m.version, m.identifier, m.name))
if m.path:
print(" 资源路径:%s" % m.path)
sk = m.skeleton
print(" 骨骼 %d · 插槽 %d · 虚拟骨 %d · 碰撞 %d"
% (len(sk.bones), len(sk.sockets), len(sk.virtual_bones),
len(m.collisions)))
if sk.path:
print(" 骨骼资源:%s" % sk.path)
for i, lod in enumerate(m.lods):
st = lod.stats()
print(" LOD[%d] %-8s 顶点 %d · 三角面 %d · 材质 %d · 权重 %d · 表情 %d · UV %d"
% (i, lod.name, st["verts"], st["tris"], st["mats"],
st["weights"], st["morphs"], st["uvsets"]))
for mt in lod.materials[:40]:
print(" 材质 %-42s 面 %6d 起 %d"
% (mt.name[:42], mt.num_faces, mt.first_index))
if len(lod.materials) > 40:
print(" …另有 %d 个材质" % (len(lod.materials) - 40))
for mo in lod.morphs[:40]:
print(" 表情 %-30s 顶点 %d" % (mo.name[:30], len(mo.deltas)))
if len(lod.morphs) > 40:
print(" …另有 %d 个表情" % (len(lod.morphs) - 40))
if sk.bones:
print(" 前 12 根骨骼:")
for b in sk.bones[:12]:
print(" %-28s parent=%-4d pos=(%.3f, %.3f, %.3f)"
% (b.name[:28], b.parent, b.pos[0], b.pos[1], b.pos[2]))
def main(argv=None):
argv = list(sys.argv[1:] if argv is None else argv)
if not argv:
print("用法:python formats/uemodelio.py <model.uemodel> [--roundtrip]")
return 1
path = argv[0]
m = read_uemodel(path, verbose=True)
if "--roundtrip" in argv:
for ver in (9, 10):
tmp = os.path.join(os.path.dirname(os.path.abspath(path)), "_rt_v%d.uemodel" % ver)
write_uemodel(m, tmp, version=ver)
back = read_uemodel(tmp)
ok = (len(back.lods) == len(m.lods)
and back.skeleton.bones and len(back.skeleton.bones) == len(m.skeleton.bones))
print("往返 v%d:%d 字节 → %s" % (ver, os.path.getsize(tmp),
"一致" if ok else "不一致"))
os.remove(tmp)
return 0
if __name__ == "__main__":
sys.exit(main())
+270
View File
@@ -0,0 +1,270 @@
# -*- coding: utf-8 -*-
"""Unity 工程 / 解开的 unitypackage 里的材质 → 底色贴图。
Unity 导出的 FBX 常常不带贴图文件名(Texture 节点的 FileName 是空的),贴图是在 Unity 的
材质(.mat,YAML 文本)里按 GUID 指定的:
m_Name: mat_Body
m_TexEnvs: _MainTex / _Main_Texture / _BaseMap … → m_Texture: {fileID: 2800000, guid: 1db2…}
而 GUID 写在贴图旁边的 .meta 里(`guid: 1db2…`)。这里把两边对起来:材质名 → 贴图路径。
FBX 里的材质名和 .mat 的 m_Name 一致(Unity 导入 FBX 时按材质名找 / 建 .mat)。
新旧两种 .mat 序列化格式都认:
* Unity 5+: m_TexEnvs:\\n - _MainTex:\\n m_Texture: {…}
* Unity 4.x: m_TexEnvs:\\n data:\\n first:\\n name: _MainTex\\n second:\\n m_Texture: {…}
二进制序列化的 .mat 读不了,跳过。
"""
import os
import re
IMAGE_EXT = (".png", ".tga", ".jpg", ".jpeg", ".bmp", ".dds", ".psd", ".tif", ".tiff")
# 当底色用的槽位,按优先级
MAIN_SLOTS = ("_maintex", "_main_texture", "_basemap", "_basecolormap", "_basetexture", "_albedo",
"_albedomap", "_diffuse", "_diffusemap", "_colortex", "_tex")
# 当主色用的槽位,按优先级(_ShadeColor / _OutlineColor 这些不能当底色)
COLOR_SLOTS = ("_color", "_basecolor", "_maincolor", "_tintcolor", "_diffusecolor",
"_maintexcolor", "_color0", "_basecolour", "_maincolour", "_colour")
NOT_MAIN = ("normal", "bump", "spec", "metal", "rough", "occlusion", "emission", "emissive", "mask",
"matcap", "sphere", "ramp", "shade", "outline", "rim", "detail", "parallax", "height", "noise")
_GUID = re.compile(r"guid:\s*([0-9a-fA-F]{32})")
_NAME = re.compile(r"^\s*m_Name:\s*(.*?)\s*$", re.M)
_COLOR = re.compile(r"\{\s*r:\s*([-+0-9.eE]+)\s*,\s*g:\s*([-+0-9.eE]+)\s*,"
r"\s*b:\s*([-+0-9.eE]+)\s*,\s*a:\s*([-+0-9.eE]+)\s*\}")
# Toon shader 的描边在 shader 的 Outline pass 里,参数只写在 .mat(FBX 没有对应信息)
OUTLINE_WIDTH_SLOTS = ("_outline_width", "_outlinewidth", "_outline_size", "_outlinesize")
OUTLINE_COLOR_SLOTS = ("_outline_color", "_outlinecolor")
def find_root(start, max_up=8):
"""Unity 资源的根:往上找 Assets 文件夹;没有(解开的 unitypackage 去掉了 Assets/)时,
只要上一层还像 Unity 资源文件夹(有 .meta 文件)就继续往上,最后至少往上两层。"""
d = os.path.abspath(start)
for _ in range(max_up):
if os.path.basename(d).lower() == "assets":
return d
parent = os.path.dirname(d)
if parent == d:
break
d = parent
d = os.path.abspath(start)
for k in range(max_up):
parent = os.path.dirname(d)
if parent == d:
break
try:
unityish = any(n.lower().endswith(".meta") for n in os.listdir(parent))
except OSError:
unityish = False
if not unityish and k >= 2:
break
d = parent
return d
def _walk(root, limit):
n = 0
for d, dirs, files in os.walk(root):
dirs[:] = [x for x in dirs if x.lower() not in ("library", "temp", "obj", ".git", "node_modules")]
for f in files:
n += 1
if n > limit:
return
yield d, f
def _slots(text):
"""→ [(槽位名, guid)],按文件里的顺序。"""
out = []
i = text.find("m_TexEnvs:")
if i < 0:
return out
end = len(text)
for key in ("m_Floats:", "m_Ints:", "m_Colors:"):
j = text.find(key, i)
if j > 0:
end = min(end, j)
block = text[i:end]
# Unity 5+: - _MainTex: Unity 4: name: _MainTex
marks = [(m.start(), m.group(1)) for m in re.finditer(r"^\s*-\s*([A-Za-z_][\w]*):\s*$", block, re.M)]
marks += [(m.start(), m.group(1)) for m in re.finditer(r"^\s*name:\s*([A-Za-z_][\w]*)\s*$", block, re.M)]
marks.sort()
for k, (pos, name) in enumerate(marks):
seg = block[pos:marks[k + 1][0] if k + 1 < len(marks) else len(block)]
m = re.search(r"m_Texture:\s*\{[^}]*\}", seg)
if not m:
continue
g = _GUID.search(m.group(0)) # 空槽位是 {fileID: 0},没有 guid
if g:
out.append((name, g.group(1).lower()))
return out
def _main_guid(slots):
if not slots:
return None
by = {n.lower(): g for n, g in slots}
for s in MAIN_SLOTS:
if s in by:
return by[s]
for n, g in slots:
if not any(k in n.lower() for k in NOT_MAIN):
return g
return None
def _colors(text):
"""→ {颜色槽位名(小写): [r, g, b, a]}。
Unity 5+ 写 `- _Color: {r: 0, g: 0, b: 0, a: 1}`,Unity 4.x 写
`name: _Color` 再在 second 段里给 `{r: …, a: …}`(字段名可能是 val / m_Color);
m_Colors 也可能套在 m_SavedProperties 里。两种都按块扫描。
"""
i = text.find("m_Colors:")
if i < 0:
return {}
end = len(text)
for key in ("m_TexEnvs:", "m_Floats:", "m_Ints:", "m_SavedProperties:", "---"):
j = text.find(key, i + len("m_Colors:"))
if j > 0:
end = min(end, j)
block = text[i:end]
out = {}
for m in re.finditer(r"^\s*-\s*([A-Za-z_][\w]*):\s*(\{[^}]*\})", block, re.M):
v = _COLOR.search(m.group(2))
if v:
out[m.group(1).lower()] = [float(x) for x in v.groups()]
marks = [(m.start(), m.group(1)) for m in
re.finditer(r"^\s*name:\s*([A-Za-z_][\w]*)\s*$", block, re.M)]
for k, (pos, name) in enumerate(marks):
seg = block[pos:marks[k + 1][0] if k + 1 < len(marks) else len(block)]
v = _COLOR.search(seg)
if v:
out[name.lower()] = [float(x) for x in v.groups()]
return out
def _main_color(colors):
"""→ 底色 [r, g, b, a];只认主色槽位,阴影色 / 描边色不算。"""
if not colors:
return None
for s in COLOR_SLOTS:
if s in colors:
return colors[s]
for n, c in colors.items():
if not any(k in n for k in NOT_MAIN):
return c
return None
def _floats(text):
"""→ {属性名(小写): float},m_Floats 段里的 `- _Key: 1.0`。"""
i = text.find("m_Floats:")
if i < 0:
return {}
end = len(text)
for key in ("m_Colors:", "m_TexEnvs:", "m_Ints:", "m_BuildTextureStacks:", "---"):
j = text.find(key, i + len("m_Floats:"))
if j > 0:
end = min(end, j)
out = {}
for m in re.finditer(r"^\s*-\s*([A-Za-z_][\w]*):\s*([-+0-9.eE]+)\s*$", text[i:end], re.M):
try:
out[m.group(1).lower()] = float(m.group(2))
except ValueError:
pass
return out
def _outline(text):
"""→ {"width", "color": [r,g,b], "mode"} 或 None。
UCTS / Toon_DoubleShadeWithFeather 这类 shader 的描边是一个额外的 Outline pass:
`m_ShaderKeywords` 里有 `_OUTLINE_NML` / `_OUTLINE_POS`,宽度在 `m_Floats._Outline_Width`、
颜色在 `m_Colors._Outline_Color`。FBX 里完全没有对应信息,必须在这里读出来。
注意 `_OUTLINE` 只是 NML/POS 模式枚举(0 = NML),不是开关;宽度 > 0 才算开了描边。
"""
fl = _floats(text)
width = next((fl[k] for k in OUTLINE_WIDTH_SLOTS if fl.get(k, 0) > 0), 0.0)
if width <= 0:
return None
col = _colors(text)
rgb = next((col[k][:3] for k in OUTLINE_COLOR_SLOTS if k in col), [0.0, 0.0, 0.0])
return {"width": width, "color": [float(x) for x in rgb],
"mode": "POS" if "_OUTLINE_POS" in text else "NML"}
def material_properties(start, limit=50000):
"""→ {材质名: {"tex": 底色贴图绝对路径或 None, "color": [r,g,b,a] 或 None}}。
start 是 FBX 所在文件夹。没有贴图、只有 m_Colors 的材质(Toon shader 的纯黑 /
纯白)也在这里返回,颜色交给 fbx2pmx 烘焙成一张纯色贴图;找不到 Unity 资源返回 {}。
"""
root = find_root(start)
guid_path = {}
mats = []
for d, f in _walk(root, limit):
low = f.lower()
if low.endswith(".meta"):
asset = f[:-5]
if asset.lower().endswith(IMAGE_EXT):
try:
with open(os.path.join(d, f), encoding="utf-8", errors="replace") as fh:
m = _GUID.search(fh.read(2000))
except OSError:
continue
if m and os.path.isfile(os.path.join(d, asset)):
guid_path[m.group(1).lower()] = os.path.join(d, asset)
elif low.endswith(".mat"):
mats.append(os.path.join(d, f))
# 注意不能因为「一张图片 .meta 都没有」就提前返回:纯色材质的 .mat 里本来就没有
# 贴图 GUID,以前的 `not mats or not guid_path` 会把它们全部丢掉。
if not mats:
return {}
# 同名材质可能有好几份(每套衣服一个文件夹,各有一个 mat_Hair)。按 Unity 导入 FBX 时的
# 查找顺序(Recursive-Up)挑:FBX 所在文件夹及其 Materials/,再往上一层……直到 Assets;
# 都不在这条链上的(别的角色 / 别的衣服的材质)排最后
chain = []
d = os.path.normcase(os.path.abspath(start))
while True:
chain.append(d)
if os.path.basename(d).lower() == "assets" or os.path.dirname(d) == d:
break
d = os.path.dirname(d)
def rank(mat_path):
md = os.path.normcase(os.path.dirname(os.path.abspath(mat_path)))
for k, a in enumerate(chain):
if md.lower() == a.lower() or md.lower() == os.path.join(a, "materials").lower():
return k
return 1000
best = {}
for p in mats:
try:
with open(p, "rb") as fh:
raw = fh.read(200000)
except OSError:
continue
if not raw.startswith(b"%YAML"):
continue # 二进制序列化的材质
text = raw.decode("utf-8", "replace")
nm = _NAME.search(text)
name = nm.group(1).strip().strip('"') if nm else os.path.splitext(os.path.basename(p))[0]
tex = guid_path.get(_main_guid(_slots(text)) or "")
color = _main_color(_colors(text))
outline = _outline(text)
if tex is None and color is None and outline is None:
continue
r = rank(p)
prop = {"tex": tex, "color": color, "outline": outline}
for key in {name, os.path.splitext(os.path.basename(p))[0]}:
if key not in best or r < best[key][0]:
best[key] = (r, prop)
return {k: v[1] for k, v in best.items()}
def material_textures(start, limit=50000):
"""→ {材质名: 底色贴图的绝对路径}。兼容旧调用,只返回有贴图的材质。"""
return {k: v["tex"] for k, v in material_properties(start, limit).items() if v["tex"]}
+140
View File
@@ -0,0 +1,140 @@
"""Unpack a .unitypackage without Unity.
一个 .unitypackage 只是一个经过 gzip 压缩的 tar 归档文件。每个资源都存放在一个以其 32 位十六进制 GUID 命名的文件夹中,该文件夹包含:
asset the real file (FBX, prefab, png, ...)
asset.meta Unity metadata (importer type, guid)
pathname original path inside Assets/
preview.png optional thumbnail
解包后的落盘规则:
asset → <输出目录>/<Assets 里的相对路径> 例:.../FBX/model.fbx
辅助文件 → 与资产同层,名字带上资产名 例:.../FBX/model.fbx.meta
(asset.meta → <名>.meta,pathname / preview.png → <名>.pathname 等)
文件夹资源 → 建出同名空文件夹(tar 里没有它的 asset 本体)
辅助文件之所以带上资产名,是因为同一目录下常有两个以上资产,若统一叫
asset.meta / pathname 就会互相覆盖,只剩最后一个。
Usage:
python unitypackage_unpack.py <file.unitypackage> [-o OUTDIR] [--list]
# 先看包里有什么(不解包)
python unitypackage_unpack.py "Sexy Sailor_Sapphy_v1.00.unitypackage" --list
# 解包到默认目录(<文件名>_extracted)
python unitypackage_unpack.py "Sexy Sailor_Sapphy_v1.00.unitypackage"
# 解包到指定目录
python unitypackage_unpack.py "Sexy Sailor_Sapphy_v1.00.unitypackage" -o "D:/output/Sapphy"
只要路径里带空格或中文,就套一层双引号,否则 shell 会按空格切参数。
"""
import argparse
import os
import shutil
import sys
import tarfile
# Windows 超长路径支持:Unity 包里的目录树很深,再叠上输出目录很容易超 260
# 字符而报 FileNotFoundError。这个模块导入即生效,短路径行为不变。
# 单独把本文件拷出去用时可能找不到,所以吞掉 ImportError。
try:
import longpath # noqa: F401
except ImportError: # pragma: no cover
pass
def _members(src):
"""按包里的顺序逐个给出 (GUID, 文件名, 内容),整个包只解压一遍(流式读 tar)。
以前先 getmembers() 走一遍、再按成员回头读 pathname、再逐个解出:gzip 不能往回跳,
每次回头都从头再解,161 MB 的包要解三遍。"""
with tarfile.open(src, 'r|gz') as t:
for m in t:
if m.isfile():
guid, fn = m.name.split('/', 1)
yield guid, fn, t.extractfile(m).read()
def _target(outdir, raw, guid, fn):
"""一个成员的落盘路径,以及它是不是「文件夹」资源的辅助文件(要建出空文件夹)。"""
# pathname 以 '/' 结尾 = 这是一个「文件夹」资源(Unity 里文件夹也是资源)。
# tar 里没有它的 asset 本体,只有 asset.meta / pathname / preview.png。
is_folder = raw.endswith('/') or not raw or raw == guid
# 去掉开头的 "Assets/"(以前用 lstrip('Assets/'),那是按字符集剥:
# "Assets/shaders/x" 会被剥成 "haders/x")
rel = (raw[len('Assets/'):] if raw.startswith('Assets/') else raw).rstrip('/') or guid
if fn == 'asset':
return os.path.join(outdir, rel), rel, False
# asset.meta / pathname / preview.png 是辅助文件:跟资产放在同一层,
# 名字里带上资产名(asset.meta 按 Unity 习惯写成 <名>.meta)。
# 早先直接写 <父目录>/<文件名>,同一目录下有两个以上资产时,
# 后一个会把前一个**静默覆盖**(实测 172 个输出里 51 个碰撞、
# 168 个成员被覆盖,其中 92 个 asset.meta + 92 个 pathname)。
name = os.path.basename(rel) or guid
aux = name + '.meta' if fn == 'asset.meta' else name + '.' + fn
return os.path.join(outdir, os.path.dirname(rel), aux), rel, is_folder
def unpack(src, outdir, list_only=False, verbose=True):
"""解包到 outdir;verbose=False 时不逐个列出文件(界面 / 流水线自己记一行汇总)。
一个资源的成员在包里是挨着的(asset、asset.meta、pathname、preview.png),落盘路径要等
读到 pathname 才知道:之前的成员先留在内存里(最多一个资源的大小),读到它再按原顺序写出。"""
if list_only:
paths, sizes = {}, []
for guid, fn, data in _members(src):
if fn == 'pathname':
paths[guid] = data.decode('utf-8', 'replace').strip()
elif fn == 'asset':
sizes.append((guid, len(data)))
for guid, size in sizes:
print('%10d %s' % (size, paths.get(guid, '?')))
return 0
if os.path.isdir(outdir):
shutil.rmtree(outdir)
os.makedirs(outdir)
paths, pending = {}, {}
n = 0
def write(guid, fn, data):
dst, rel, folder = _target(outdir, paths.get(guid, ''), guid, fn)
os.makedirs(os.path.dirname(dst), exist_ok=True)
if folder:
# 文件夹资源的 asset 本体不存在,不在这里建的话空文件夹会丢
os.makedirs(os.path.join(outdir, rel), exist_ok=True)
with open(dst, 'wb') as w:
w.write(data)
if verbose:
print(' %8.1f KB %s' % (len(data) / 1024, os.path.relpath(dst, outdir)))
for guid, fn, data in _members(src):
if fn == 'pathname':
paths[guid] = data.decode('utf-8', 'replace').strip()
if guid in paths:
for item in pending.pop(guid, ()):
write(guid, *item)
write(guid, fn, data)
else:
pending.setdefault(guid, []).append((fn, data))
n += 1
for guid, items in pending.items(): # 没有 pathname 的资源:按 GUID 落盘
for item in items:
write(guid, *item)
if verbose:
print('\n%d files -> %s' % (n, outdir))
return 0
def main():
ap = argparse.ArgumentParser()
ap.add_argument('src')
ap.add_argument('-o', '--out', default=None)
ap.add_argument('--list', action='store_true')
a = ap.parse_args()
out = a.out or os.path.splitext(a.src)[0] + '_extracted'
return unpack(a.src, out, a.list)
if __name__ == '__main__':
sys.exit(main())
+983
View File
@@ -0,0 +1,983 @@
# -*- coding: utf-8 -*-
"""vrmio.py - GLB / glTF 容器读写 + 纯 Python 图片编解码。
只依赖标准库。提供:
GLBBuilder —— 构造 glTF JSON + 单一 BIN chunk
read_glb —— 拆开 .vrm/.glb 得到 (json dict, bin bytes)
write_glb —— 打包成 .vrm/.glb
to_png / decode_image / save_image —— 贴图处理
"""
import io
import json
import os
import struct
import zlib
GLB_MAGIC = 0x46546C67 # "glTF"
CHUNK_JSON = 0x4E4F534A # "JSON"
CHUNK_BIN = 0x004E4942 # "BIN\0"
FLOAT = 5126
UNSIGNED_BYTE = 5121
SHORT = 5122
UNSIGNED_SHORT = 5123
UNSIGNED_INT = 5125
_COMP_FMT = {FLOAT: "<f", UNSIGNED_BYTE: "<B", SHORT: "<h",
UNSIGNED_SHORT: "<H", UNSIGNED_INT: "<I"}
_COMP_SIZE = {FLOAT: 4, UNSIGNED_BYTE: 1, SHORT: 2,
UNSIGNED_SHORT: 2, UNSIGNED_INT: 4}
_TYPE_COUNT = {"SCALAR": 1, "VEC2": 2, "VEC3": 3, "VEC4": 4,
"MAT4": 16}
# --------------------------------------------------------------- glb build --
class GLBBuilder:
"""边填数据边生成 bufferViews / accessors / images。"""
def __init__(self):
self.bin = bytearray()
self.bufferViews = []
self.accessors = []
self.images = [] # (mime, bytes) 占位,稍后统一写入
self.samplers = []
self.textures = []
# -- raw
def add_bytes(self, data, target=None):
while len(self.bin) % 4:
self.bin.append(0)
off = len(self.bin)
self.bin += data
bv = {"buffer": 0, "byteOffset": off, "byteLength": len(data)}
if target:
bv["target"] = target
self.bufferViews.append(bv)
return len(self.bufferViews) - 1
# -- accessor
def add_accessor(self, values, comp_type, type_str,
target=None, minmax=True):
"""values: 展平的 python 数字列表。"""
n = _TYPE_COUNT[type_str]
count = len(values) // n
fmt = _COMP_FMT[comp_type]
data = struct.pack("<%d%s" % (len(values), fmt[1:]), *values)
bv = self.add_bytes(data, target)
acc = {"bufferView": bv, "componentType": comp_type,
"count": count, "type": type_str}
if minmax and count:
lo = [min(values[i::n]) for i in range(n)]
hi = [max(values[i::n]) for i in range(n)]
if comp_type == UNSIGNED_SHORT:
acc["min"] = [int(x) & 0xFFFF for x in lo]
acc["max"] = [int(x) & 0xFFFF for x in hi]
else:
acc["min"] = [float(x) for x in lo]
acc["max"] = [float(x) for x in hi]
self.accessors.append(acc)
return len(self.accessors) - 1
def add_sparse_accessor(self, count, indices, values, type_str):
"""稀疏 FLOAT accessor:没列出的元素一律为 0。
indices: 非零元素的下标(升序);values: 对应的展平值。
用于 morph target——大多数表情只动几百个顶点,密集存储
每个表情都要「顶点数 × 12 字节」,稀疏存储只存动到的那些。
glTF 要求 sparse.count ≥ 1,全零的 target 也写 1 个零元素。
POSITION 类 accessor 必须带 min/max,按「含隐式 0」的全集计算。
"""
n = _TYPE_COUNT[type_str]
if not indices:
indices, values = [0], [0.0] * n
ib = self.add_bytes(struct.pack("<%dI" % len(indices), *indices))
vb = self.add_bytes(struct.pack("<%df" % len(values), *values))
lo = [min([0.0] + values[i::n]) for i in range(n)]
hi = [max([0.0] + values[i::n]) for i in range(n)]
self.accessors.append({
"componentType": FLOAT, "count": count, "type": type_str,
"min": lo, "max": hi,
"sparse": {"count": len(indices),
"indices": {"bufferView": ib,
"componentType": UNSIGNED_INT},
"values": {"bufferView": vb}}})
return len(self.accessors) - 1
# -- image / texture
def add_image(self, data, mime):
bv = self.add_bytes(data)
self.images.append({"bufferView": bv, "mimeType": mime})
return len(self.images) - 1
def add_texture(self, image_index, sampler=0):
self.textures.append({"sampler": sampler, "source": image_index})
return len(self.textures) - 1
def default_sampler(no_mip=False):
"""glTF 贴图采样器。
no_mip=True 时 minFilter 用 LINEAR(不生成 mipmap)。UV 岛之间没有留 gutter 的
贴图在 mipmap 高层会把岛外的底色(常见是白 / 米白)平均进岛边缘,模型上就出现
一圈沿 UV 接缝的白边;关掉 mipmap 后只剩双线性的半个像素,基本看不出来。
代价是远景会有轻微锯齿 / 摩尔纹,所以默认不启用,由用户按需打开。
"""
return {"magFilter": 9729, "minFilter": 9729 if no_mip else 9987,
"wrapS": 10497, "wrapT": 10497}
def write_glb(gltf, bin_bytes, path):
"""bin_bytes:bytes / bytearray / memoryview 都行,直接写进文件、不复制(大模型的二进制块有几十 MB)。"""
js = json.dumps(gltf, ensure_ascii=False, separators=(",", ":")).encode("utf-8")
js += b" " * (-len(js) % 4)
n = len(bin_bytes)
pad = -n % 4
total = 12 + 8 + len(js) + (8 + n + pad if n else 0)
with open(path, "wb") as f:
f.write(struct.pack("<III", GLB_MAGIC, 2, total))
f.write(struct.pack("<II", len(js), CHUNK_JSON))
f.write(js)
if n:
f.write(struct.pack("<II", n + pad, CHUNK_BIN))
f.write(bin_bytes)
f.write(b"\x00" * pad)
return total
def read_glb(path):
with open(path, "rb") as f:
d = f.read()
if len(d) < 20 or struct.unpack_from("<I", d, 0)[0] != GLB_MAGIC:
raise ValueError("不是 GLB/VRM 文件:%s" % path)
total = struct.unpack_from("<I", d, 8)[0]
js = None
bin_data = b""
p = 12
while p + 8 <= min(len(d), total):
clen, ctype = struct.unpack_from("<II", d, p)
p += 8
chunk = d[p:p + clen]
p += clen
if ctype == CHUNK_JSON:
js = json.loads(chunk.decode("utf-8"))
elif ctype == CHUNK_BIN:
bin_data = chunk
if js is None:
raise ValueError("GLB 里没有 JSON chunk")
return js, bin_data
# ------------------------------------------------------------- gltf utils --
def read_accessor(gltf, bin_data, index):
"""把 accessor 读成展平的 python 数字列表,支持稀疏存储。"""
acc = gltf["accessors"][index]
return accessor_sparse(gltf, bin_data, index)
def accessor_sparse(gltf, bin_data, index):
"""返回 (values, sparse_pairs) —— 稀疏 accessor 支持。"""
acc = gltf["accessors"][index]
n = _TYPE_COUNT[acc["type"]]
count = acc["count"]
comp = acc["componentType"]
fmt = _COMP_FMT[comp]
size = _COMP_SIZE[comp]
out = [0.0] * (count * n)
if "bufferView" in acc:
bv = gltf["bufferViews"][acc["bufferView"]]
off = bv.get("byteOffset", 0) + acc.get("byteOffset", 0)
stride = bv.get("byteStride") or (size * n)
for i in range(count):
base = off + i * stride
for k in range(n):
out[i * n + k] = struct.unpack_from(fmt, bin_data,
base + k * size)[0]
sp = acc.get("sparse")
if sp:
icount = sp["count"]
ibv = gltf["bufferViews"][sp["indices"]["bufferView"]]
icomp = sp["indices"]["componentType"]
ifmt = _COMP_FMT[icomp]
isize = _COMP_SIZE[icomp]
ioff = ibv.get("byteOffset", 0) + sp["indices"].get("byteOffset", 0)
vbv = gltf["bufferViews"][sp["values"]["bufferView"]]
voff = vbv.get("byteOffset", 0) + sp["values"].get("byteOffset", 0)
for i in range(icount):
vi = struct.unpack_from(ifmt, bin_data, ioff + i * isize)[0]
for k in range(n):
out[vi * n + k] = struct.unpack_from(
fmt, bin_data, voff + (i * n + k) * size)[0]
return out
def node_world_matrices(gltf):
"""返回每个 node 的世界矩阵(列主序 4x4 列表)。"""
nodes = gltf.get("nodes") or []
n = len(nodes)
world = [None] * n
parent = [-1] * n
for i, nd in enumerate(nodes):
for c in nd.get("children") or []:
if 0 <= c < n:
parent[c] = i
def local(nd):
if "matrix" in nd:
return list(nd["matrix"])
t = nd.get("translation") or [0.0, 0.0, 0.0]
r = nd.get("rotation") or [0.0, 0.0, 0.0, 1.0]
s = nd.get("scale") or [1.0, 1.0, 1.0]
x, y, z, w = r
x2, y2, z2 = x + x, y + y, z + z
xx, xy, xz = x * x2, x * y2, x * z2
yy, yz, zz = y * y2, y * z2, z * z2
wx, wy, wz = w * x2, w * y2, w * z2
# 列主序
return [s[0] * (1 - (yy + zz)), s[0] * (xy + wz), s[0] * (xz - wy), 0.0,
s[1] * (xy - wz), s[1] * (1 - (xx + zz)), s[1] * (yz + wx), 0.0,
s[2] * (xz + wy), s[2] * (yz - wx), s[2] * (1 - (xx + yy)), 0.0,
t[0], t[1], t[2], 1.0]
def mul(a, b):
o = [0.0] * 16
for c in range(4):
for r_ in range(4):
o[c * 4 + r_] = (a[r_] * b[c * 4] + a[4 + r_] * b[c * 4 + 1] +
a[8 + r_] * b[c * 4 + 2] +
a[12 + r_] * b[c * 4 + 3])
return o
order = sorted(range(n), key=lambda i: _depth(i, parent))
for i in order:
loc = local(nodes[i])
p = parent[i]
world[i] = mul(world[p], loc) if p >= 0 and world[p] else loc
return world
def _depth(i, parent):
d = 0
while parent[i] >= 0:
d += 1
i = parent[i]
return d
def world_translation(m):
return (m[12], m[13], m[14])
# ----------------------------------------------------------------- images --
def encode_png(width, height, rows_rgba):
"""rows_rgba: 每行为 bytes,长度 width*4。"""
raw = bytearray()
for r in rows_rgba:
raw.append(0)
raw += r
def chunk(typ, data):
return (struct.pack(">I", len(data)) + typ + data +
struct.pack(">I", zlib.crc32(typ + data) & 0xFFFFFFFF))
out = bytearray(b"\x89PNG\r\n\x1a\n")
out += chunk(b"IHDR", struct.pack(">IIBBBBB", width, height,
8, 6, 0, 0, 0))
out += chunk(b"IDAT", zlib.compress(bytes(raw), 6))
out += chunk(b"IEND", b"")
return bytes(out)
def _png_from_rgba(w, h, pix):
"""pix: bytes,长度 w*h*4,按行自上而下。"""
rows = [pix[y * w * 4:(y + 1) * w * 4] for y in range(h)]
return encode_png(w, h, rows)
def _decode_bmp(data):
if data[:2] != b"BM":
return None
off = struct.unpack_from("<I", data, 10)[0]
dib = struct.unpack_from("<I", data, 14)[0]
if dib < 40:
return None
w = struct.unpack_from("<i", data, 18)[0]
h = struct.unpack_from("<i", data, 22)[0]
bpp = struct.unpack_from("<H", data, 28)[0]
comp = struct.unpack_from("<I", data, 30)[0]
if bpp not in (24, 32) or comp not in (0, 3):
return None
flip = h > 0
h = abs(h)
stride = ((w * bpp + 31) // 32) * 4
pix = bytearray(w * h * 4)
src = off
for y in range(h):
sy = (h - 1 - y) if flip else y
row = data[src + sy * stride: src + sy * stride + stride]
for x in range(w):
if bpp == 24:
b, g, r = row[x * 3], row[x * 3 + 1], row[x * 3 + 2]
a = 255
else:
b, g, r, a = row[x * 4], row[x * 4 + 1], row[x * 4 + 2], row[x * 4 + 3]
o = (y * w + x) * 4
pix[o] = r
pix[o + 1] = g
pix[o + 2] = b
pix[o + 3] = a
return _png_from_rgba(w, h, bytes(pix))
def _decode_tga(data):
idlen = data[0]
cmap_type = data[1]
img_type = data[2]
w = struct.unpack_from("<H", data, 12)[0]
h = struct.unpack_from("<H", data, 14)[0]
depth = data[16]
desc = data[17]
if img_type not in (2, 10) or depth not in (24, 32):
return None
p = 18 + idlen
bpp = depth // 8
pix = bytearray(w * h * 4)
top = bool(desc & 0x20)
idx = 0
if img_type == 2:
raw = data[p:p + w * h * bpp]
for i in range(w * h):
b = raw[i * bpp]
g = raw[i * bpp + 1]
r = raw[i * bpp + 2]
a = raw[i * bpp + 3] if bpp == 4 else 255
o = i * 4
pix[o] = r
pix[o + 1] = g
pix[o + 2] = b
pix[o + 3] = a
else:
while idx < w * h and p < len(data):
rep = data[p]
p += 1
count = (rep & 0x7F) + 1
if rep & 0x80:
px = data[p:p + bpp]
p += bpp
chunkpx = [px] * count
else:
chunkpx = [data[p + i * bpp:p + (i + 1) * bpp]
for i in range(count)]
p += count * bpp
for px in chunkpx:
if idx >= w * h:
break
b, g, r = px[0], px[1], px[2]
a = px[3] if bpp == 4 else 255
o = idx * 4
pix[o] = r
pix[o + 1] = g
pix[o + 2] = b
pix[o + 3] = a
idx += 1
if not top: # 底到顶存储,翻过来
rows = [bytes(pix[y * w * 4:(y + 1) * w * 4]) for y in range(h)]
rows.reverse()
pix = bytearray(b"".join(rows))
return _png_from_rgba(w, h, bytes(pix))
# ------------------------------------------------------------------- DDS ----
# XPS / XNALara 的贴图大量是 DDS(实测轩辕剑柒的样本是 2048×2048 的 DXT1 与
# 512×512 的 DXT5)。MMD 本体虽然认 .dds(见 VPVP wiki 的「拡張子」表,所以
# 转换时原样拷过去就行),但 GUI 预览的图片解码走的是纯标准库路线,没装
# Pillow 时只认 PNG/TGA/BMP,DDS 会解不出来、预览变灰模。这里补一个
# DXT1/DXT3/DXT5 与未压缩 RGB(A) 的解码,解成 PNG 后预览就能正常显示。
# 一个索引字节 → 4 个 2 位索引(低位在前),DXT 全系都用这个位序
_DXT_Q = tuple(((b & 3), ((b >> 2) & 3), ((b >> 4) & 3), ((b >> 6) & 3))
for b in range(256))
def _rgb565(v):
r = (v >> 11) & 0x1F
g = (v >> 5) & 0x3F
b = v & 0x1F
return ((r << 3) | (r >> 2), (g << 2) | (g >> 4), (b << 3) | (b >> 2))
def _dxt_palette(c0, c1, allow_transparent):
"""(c0, c1) → 4 个 RGBA 字节串。
allow_transparent(只有 DXT1 传 True)时,c0 <= c1 表示用「3 色 + 全透明」
档,第 4 个是透明黑 —— 这是 DXT1 唯一的 alpha 来源。
"""
r0, g0, b0 = _rgb565(c0)
r1, g1, b1 = _rgb565(c1)
p0 = bytes((r0, g0, b0, 255))
p1 = bytes((r1, g1, b1, 255))
if allow_transparent and c0 <= c1:
return (p0, p1,
bytes(((r0 + r1) // 2, (g0 + g1) // 2, (b0 + b1) // 2, 255)),
b"\x00\x00\x00\x00")
return (p0, p1,
bytes(((2 * r0 + r1) // 3, (2 * g0 + g1) // 3, (2 * b0 + b1) // 3,
255)),
bytes(((r0 + 2 * r1) // 3, (g0 + 2 * g1) // 3, (b0 + 2 * b1) // 3,
255)))
def _dxt5_alpha_ramp(a0, a1):
"""DXT5 的 8 个 alpha 值:a0 > a1 是 6 插值档,否则 4 插值 + 0/255。"""
if a0 > a1:
return (a0, a1) + tuple(
((7 - i) * a0 + i * a1) // 7 for i in range(1, 7))
return (a0, a1) + tuple(
((5 - i) * a0 + i * a1) // 5 for i in range(1, 5)) + (0, 255)
def _decode_dds(data):
"""DDS → PNG 字节;不支持的子格式返回 None。"""
if data[:4] != b"DDS " or len(data) < 128:
return None
hdr = struct.unpack_from("<7I", data, 4)
height, width = hdr[2], hdr[3]
if not width or not height or width > 16384 or height > 16384:
return None
fourcc = data[84:88]
rgb_bits = struct.unpack_from("<I", data, 88)[0]
pix = bytearray(width * height * 4)
stride = width * 4
if fourcc in (b"DXT1", b"DXT3", b"DXT5"):
block = 8 if fourcc == b"DXT1" else 16
bw = (width + 3) // 4
bh = (height + 3) // 4
if len(data) < 128 + bw * bh * block:
return None
off = 128
Q = _DXT_Q
if fourcc == b"DXT1":
for by in range(bh):
y0 = by * 4
for bx in range(bw):
c0 = data[off] | (data[off + 1] << 8)
c1 = data[off + 2] | (data[off + 3] << 8)
bits = struct.unpack_from("<I", data, off + 4)[0]
pal = _dxt_palette(c0, c1, True)
off += 8
x0 = bx * 4
for r in range(4):
if y0 + r >= height:
break
q = Q[(bits >> (8 * r)) & 0xFF]
row = (pal[q[0]] + pal[q[1]] + pal[q[2]] + pal[q[3]])
o = (y0 + r) * stride + x0 * 4
if x0 + 4 <= width:
pix[o:o + 16] = row
else:
pix[o:o + (width - x0) * 4] = \
row[:(width - x0) * 4]
elif fourcc == b"DXT3":
for by in range(bh):
y0 = by * 4
for bx in range(bw):
al = data[off:off + 8]
c0 = data[off + 8] | (data[off + 9] << 8)
c1 = data[off + 10] | (data[off + 11] << 8)
bits = struct.unpack_from("<I", data, off + 12)[0]
pal = _dxt_palette(c0, c1, False)
off += 16
x0 = bx * 4
for r in range(4):
if y0 + r >= height:
break
o = (y0 + r) * stride + x0 * 4
for k in range(4):
if x0 + k >= width:
break
i = r * 4 + k
n = (al[i >> 1] >> (4 * (i & 1))) & 0xF
c = pal[(bits >> (2 * i)) & 3]
pix[o + k * 4] = c[0]
pix[o + k * 4 + 1] = c[1]
pix[o + k * 4 + 2] = c[2]
pix[o + k * 4 + 3] = n * 17
else: # DXT5
for by in range(bh):
y0 = by * 4
for bx in range(bw):
ramp = _dxt5_alpha_ramp(data[off], data[off + 1])
abits = int.from_bytes(data[off + 2:off + 8], "little")
c0 = data[off + 8] | (data[off + 9] << 8)
c1 = data[off + 10] | (data[off + 11] << 8)
bits = struct.unpack_from("<I", data, off + 12)[0]
pal = _dxt_palette(c0, c1, False)
off += 16
x0 = bx * 4
for r in range(4):
if y0 + r >= height:
break
o = (y0 + r) * stride + x0 * 4
for k in range(4):
if x0 + k >= width:
break
i = r * 4 + k
c = pal[(bits >> (2 * i)) & 3]
pix[o + k * 4] = c[0]
pix[o + k * 4 + 1] = c[1]
pix[o + k * 4 + 2] = c[2]
pix[o + k * 4 + 3] = ramp[(abits >> (3 * i)) & 7]
return _png_from_rgba(width, height, bytes(pix))
if fourcc == b"\x00\x00\x00\x00" and rgb_bits in (24, 32):
rmask, gmask, bmask, amask = struct.unpack_from("<4I", data, 92)
bpp = rgb_bits // 8
if len(data) < 128 + width * height * bpp:
return None
# 常见布局走快路:24 位 BGR / 32 位 BGRA
if (rgb_bits == 24 and rmask == 0xFF0000 and gmask == 0xFF00
and bmask == 0xFF):
src = data[128:128 + width * height * 3]
for i in range(width * height):
o = i * 4
pix[o] = src[i * 3 + 2]
pix[o + 1] = src[i * 3 + 1]
pix[o + 2] = src[i * 3]
pix[o + 3] = 255
return _png_from_rgba(width, height, bytes(pix))
if (rgb_bits == 32 and rmask == 0xFF0000 and gmask == 0xFF00
and bmask == 0xFF and amask == 0xFF000000):
src = data[128:128 + width * height * 4]
for i in range(width * height):
o = i * 4
pix[o] = src[i * 4 + 2]
pix[o + 1] = src[i * 4 + 1]
pix[o + 2] = src[i * 4]
pix[o + 3] = src[i * 4 + 3]
return _png_from_rgba(width, height, bytes(pix))
# 其它掩码:按位段通用抽取
def _shift(mask):
if not mask:
return 0, 0
s = 0
while not (mask >> s) & 1:
s += 1
bits = bin(mask >> s).count("1")
return s, bits
rs, rb = _shift(rmask)
gs, gb = _shift(gmask)
bs, bb = _shift(bmask)
as_, ab = _shift(amask)
def _comp(v, s, n, default=255):
if not n:
return default
x = (v >> s) & ((1 << n) - 1)
return x * 255 // ((1 << n) - 1)
src = data[128:128 + width * height * bpp]
for i in range(width * height):
v = int.from_bytes(src[i * bpp:(i + 1) * bpp], "little")
o = i * 4
pix[o] = _comp(v, rs, rb)
pix[o + 1] = _comp(v, gs, gb)
pix[o + 2] = _comp(v, bs, bb)
pix[o + 3] = _comp(v, as_, ab, 255)
return _png_from_rgba(width, height, bytes(pix))
return None
def _bmp_pil(Image, data):
"""BMP → Pillow 图像。24 / 32 位的像素和 _decode_bmp 一样(32 位的第 4 个字节当 alpha,Pillow 自己
打开时会把它当成填充字节丢掉);纯 Python 版不认的(8 位调色板 / 灰度等)交给 Pillow 自己解。"""
off = struct.unpack_from("<I", data, 10)[0]
w, h = struct.unpack_from("<ii", data, 18)
bpp = struct.unpack_from("<H", data, 28)[0]
comp = struct.unpack_from("<I", data, 30)[0]
if struct.unpack_from("<I", data, 14)[0] < 40 or bpp not in (24, 32) or comp not in (0, 3):
im = Image.open(io.BytesIO(data), formats=["BMP"])
im.load()
return im
if w <= 0 or h == 0:
return None
stride = ((w * bpp + 31) // 32) * 4
size = stride * abs(h)
if len(data) < off + size:
return None
mode, raw = ("RGBA", "BGRA") if bpp == 32 else ("RGB", "BGR")
return Image.frombuffer(mode, (w, abs(h)), data[off:off + size], "raw", raw, stride, -1 if h > 0 else 1)
def _decode_pil(data, kind):
"""BMP / TGA / DDS → PNG 字节,用 Pillow(C 解码,比下面的纯 Python 版快几十倍)。
没装 Pillow 或它解不了时返回 None,交给纯 Python 版。没有 alpha 的图存成 RGB PNG。"""
try:
from PIL import Image
except ImportError:
return None
try:
if kind == "BMP":
im = _bmp_pil(Image, data)
if im is None:
return None
else:
im = Image.open(io.BytesIO(data), formats=[kind])
im.load()
if im.mode not in ("RGB", "RGBA"):
alpha = im.mode in ("LA", "PA", "La", "RGBa") or "transparency" in im.info
im = im.convert("RGBA" if alpha else "RGB")
buf = io.BytesIO()
im.save(buf, "PNG")
return buf.getvalue()
except Exception: # noqa: BLE001 罕见子格式:纯 Python 版再试
return None
def decode_image(data):
"""任意常见贴图字节 → PNG 字节;无法处理时返回 None。BMP / TGA / DDS 装了 Pillow 时用 Pillow 解。"""
if not data:
return None
if data[:8] == b"\x89PNG\r\n\x1a\n":
return data
if data[:3] == b"\xff\xd8\xff":
return data # JPEG 直接透传
for kind, ok, pure in (
("BMP", data[:2] == b"BM", _decode_bmp),
("DDS", data[:4] == b"DDS ", _decode_dds),
("TGA", len(data) > 18 and data[2] in (2, 3, 10, 11) and data[1] in (0, 1), _decode_tga)):
if ok:
out = _decode_pil(data, kind)
if out:
return out
try:
return pure(data)
except Exception:
return None
return None
def decode_rgba(data, max_pixels=4 << 20):
"""贴图字节 → (宽, 高, 行列表),每行是 (r, g, b, a) 元组的列表;失败返回 None。
纯 Python,给 toon 渐变这类小图取色用(BMP / TGA / DDS 先转成 PNG)。
只支持 8 位、非隔行的 PNG;超过 max_pixels 的大图不解(太慢)。
"""
if not data:
return None
if data[:8] != b"\x89PNG\r\n\x1a\n":
data = decode_image(data)
if not data or data[:8] != b"\x89PNG\r\n\x1a\n":
return None
p = 8
idat = []
w = h = bd = ct = il = 0
plte = trns = None
while p + 8 <= len(data):
ln, ty = struct.unpack(">I4s", data[p:p + 8])
body = data[p + 8:p + 8 + ln]
p += 12 + ln
if ty == b"IHDR":
w, h, bd, ct, _, _, il = struct.unpack(">IIBBBBB", body[:13])
elif ty == b"IDAT":
idat.append(body)
elif ty == b"PLTE":
plte = body
elif ty == b"tRNS":
trns = body
elif ty == b"IEND":
break
if bd != 8 or il or ct not in (0, 2, 3, 4, 6) or w * h > max_pixels:
return None
if ct == 3 and not plte:
return None
bpp = {0: 1, 2: 3, 3: 1, 4: 2, 6: 4}[ct]
stride = w * bpp
try:
raw = zlib.decompress(b"".join(idat))
except zlib.error:
return None
if len(raw) < h * (stride + 1):
return None
rows = []
prev = bytearray(stride)
for y in range(h):
base = y * (stride + 1)
f = raw[base]
out = bytearray(raw[base + 1:base + 1 + stride])
if f == 1:
for x in range(bpp, stride):
out[x] = (out[x] + out[x - bpp]) & 255
elif f == 2:
for x in range(stride):
out[x] = (out[x] + prev[x]) & 255
elif f == 3:
for x in range(stride):
left = out[x - bpp] if x >= bpp else 0
out[x] = (out[x] + ((left + prev[x]) >> 1)) & 255
elif f == 4:
for x in range(stride):
a = out[x - bpp] if x >= bpp else 0
b = prev[x]
c = prev[x - bpp] if x >= bpp else 0
pa, pb, pc = abs(b - c), abs(a - c), abs(a + b - 2 * c)
out[x] = (out[x] + (a if pa <= pb and pa <= pc
else (b if pb <= pc else c))) & 255
prev = out
if ct == 6:
rows.append([tuple(out[i:i + 4]) for i in range(0, stride, 4)])
elif ct == 2:
rows.append([tuple(out[i:i + 3]) + (255,) for i in range(0, stride, 3)])
elif ct == 0:
rows.append([(v, v, v, 255) for v in out])
elif ct == 4:
rows.append([(out[i], out[i], out[i], out[i + 1]) for i in range(0, stride, 2)])
else:
rows.append([tuple(plte[3 * v:3 * v + 3]) +
((trns[v] if trns and v < len(trns) else 255),) for v in out])
return w, h, rows
def png_alpha_stats_image(im):
"""已经用 Pillow 打开的 PNG → 和 png_alpha_stats 相同的结果(解码时出错会抛异常)。
FBX 转换判断透明时已经解过一遍贴图,用它算好交给后面的 PMX → VRM,不用再解一遍。"""
if im.mode in ("RGBA", "LA", "PA"):
a = im.getchannel("A")
elif im.mode == "P" and "transparency" in im.info:
a = im.convert("RGBA").getchannel("A")
else:
return None # 没有 alpha(tRNS 色键和纯 Python 版一样忽略)
h = a.histogram()
return (sum(h), sum(h[:250]), sum(h[11:245]))
def _png_alpha_stats_pil(data):
"""png_alpha_stats 的 Pillow 版(C 解码,比纯 Python 版快十倍以上,统计整张图)。
没有 alpha 通道的图看文件头就知道,不解码。没装 Pillow 或解不开时返回 NotImplemented,交给纯 Python 版。"""
try:
from PIL import Image
except ImportError:
return NotImplemented
try:
return png_alpha_stats_image(Image.open(io.BytesIO(data)))
except Exception: # noqa: BLE001 坏图 / 罕见格式:纯 Python 版有自己的保守处理
return NotImplemented
def png_alpha_stats(data, max_rows=512):
"""统计 PNG 的透明度分布,用来决定材质的 alphaMode。
返回 (采样像素数, 透明像素数 a<250, 半透明像素数 10<a<245);
图片没有 alpha(RGB / 灰度 / 无 tRNS 的调色板 / JPEG)返回 None。
只解 alpha 通道:PNG 的行滤波按「同一通道的左边/上边字节」做,
alpha 字节只依赖 alpha 字节,不必把 RGB 也算一遍。
大图只抽约 max_rows 行(从最近的「不依赖上一行」的行开始连续解到目标行),
纯 Python 也能在一两秒内处理 2048² 的贴图。装了 Pillow(打包的 exe 里都有)时先用 Pillow。
"""
if not data or data[:8] != b"\x89PNG\r\n\x1a\n":
return None
fast = _png_alpha_stats_pil(data)
if fast is not NotImplemented:
return fast
p = 8
idat = []
w = h = bd = ct = il = 0
trns = None
while p + 8 <= len(data):
ln, ty = struct.unpack(">I4s", data[p:p + 8])
body = data[p + 8:p + 8 + ln]
p += 12 + ln
if ty == b"IHDR":
w, h, bd, ct, _, _, il = struct.unpack(">IIBBBBB", body[:13])
elif ty == b"IDAT":
idat.append(body)
elif ty == b"tRNS":
trns = body
elif ty == b"IEND":
break
if ct == 3:
if not trns:
return None
lut = bytes(trns) + b"\xff" * (256 - len(trns))
elif ct not in (4, 6):
return None # tRNS 色键这种少见情况忽略
if il or bd not in (8, 16) and ct != 3:
return (1, 1, 1) # 隔行/罕见位深:保守地当半透明
try:
raw = zlib.decompress(b"".join(idat))
except zlib.error:
return (1, 1, 1)
if ct == 3:
if bd != 8:
return (1, 1, 1)
bpp, aoff = 1, 0
else:
ch = 4 if ct == 6 else 2
bpp = ch * (bd // 8)
aoff = bpp - (bd // 8) # 16 位取 alpha 的高字节
stride = w * bpp
if len(raw) < h * (stride + 1):
return (1, 1, 1)
step = max(1, h // max_rows)
filt = [raw[y * (stride + 1)] for y in range(h)]
def unfilter(y, prev):
"""只还原第 y 行 alpha(调色板图还原索引),prev 为上一行结果或 None。"""
base = y * (stride + 1) + 1
src = raw[base + aoff:base + stride:bpp]
f = filt[y]
if f == 0:
return bytearray(src)
out = bytearray(len(src))
if f == 1:
a = 0
for x, v in enumerate(src):
a = (v + a) & 255
out[x] = a
return out
up = prev if prev is not None else bytes(len(src))
if f == 2:
for x, v in enumerate(src):
out[x] = (v + up[x]) & 255
return out
a = c = 0
for x, v in enumerate(src):
b = up[x]
if f == 3:
a = (v + ((a + b) >> 1)) & 255
else:
pa = b - c
pb = a - c
pc = abs(pa + pb)
pa = abs(pa)
pb = abs(pb)
pr = a if (pa <= pb and pa <= pc) else (b if pb <= pc else c)
a = (v + pr) & 255
out[x] = a
c = b
return out
n = trans = mid = 0
last_y, last_row = -1, None
for t in range(0, h, step):
if last_y >= 0 and t - last_y <= step:
y, prev = last_y + 1, last_row
else:
y = t
while y > 0 and filt[y] > 1 and y > last_y + 1:
y -= 1
prev = last_row if y == last_y + 1 else None
row = prev
while y <= t:
row = unfilter(y, prev)
prev = row
y += 1
last_y, last_row = t, row
if ct == 3:
row = row.translate(lut)
n += len(row)
for v in row:
if v < 250:
trans += 1
if 10 < v < 245:
mid += 1
return (n, trans, mid)
IMAGE_EXTS = (".png", ".jpg", ".jpeg", ".bmp", ".tga", ".dds", ".spa", ".sph", ".gif", ".webp", ".tif", ".tiff")
class TextureFinder:
"""模型里记的贴图路径(相对模型所在文件夹)→ 磁盘上的文件。
依次试:记的相对路径;模型文件夹里的同名文件(作者留了自己电脑上的绝对路径之类);模型文件夹的
子文件夹里的同名文件(不分大小写,比如记的是 body.png、实际在 tex/body.png);同名不同扩展名
(记的 .png、实际是 .tga / .dds)。子文件夹按需建一次索引,最多看 max_files 个文件(不只是图片)、max_depth 层,
拖进来的是「下载」这种大文件夹时也不会慢。find 可以在线程里调用。
"""
def __init__(self, base_dir, max_files=20000, max_depth=6):
import threading
self.base_dir = base_dir
self.max_files, self.max_depth = max_files, max_depth
self._index = None
self._lock = threading.Lock()
def _build(self):
by_name, by_stem, n = {}, {}, 0
root = os.path.abspath(self.base_dir)
depth0 = root.rstrip("\\/").count(os.sep)
for d, dirs, files in os.walk(root):
if d.count(os.sep) - depth0 >= self.max_depth:
dirs[:] = []
dirs.sort()
n += len(files) # 所有文件都算数:模型放在「下载」这种大文件夹里时不会一直找下去
for f in sorted(files):
low = f.lower()
if low.endswith(IMAGE_EXTS):
p = os.path.join(d, f)
by_name.setdefault(low, []).append(p)
by_stem.setdefault(os.path.splitext(low)[0], []).append(p)
if n >= self.max_files:
break
return by_name, by_stem
def find(self, rel):
"""→ (路径, how):how 是 "exact"(就在记的位置)、"moved"(在别处按文件名找到的);找不到为 (None, None)。"""
rel = (rel or "").replace("\\", "/").strip()
if not rel:
return None, None
c = os.path.join(self.base_dir, *[x for x in rel.split("/") if x]) if not os.path.isabs(rel) else rel
if os.path.isfile(c):
return c, "exact"
name = rel.rsplit("/", 1)[-1]
c = os.path.join(self.base_dir, name)
if os.path.isfile(c):
return c, "moved"
with self._lock:
if self._index is None:
self._index = self._build()
by_name, by_stem = self._index
cands = by_name.get(name.lower()) or by_stem.get(os.path.splitext(name.lower())[0]) or []
if not cands:
return None, None
# 几个同名的:选所在子文件夹和记的路径对得最多的,再选层级浅的
want = [x.lower() for x in rel.split("/")[:-1]]
def score(p):
parts = os.path.relpath(os.path.dirname(p), self.base_dir).lower().replace("\\", "/").split("/")
return (-sum(1 for x in want if x in parts), len(parts), p)
return min(cands, key=score), "moved"
def load_texture(path):
"""读取磁盘贴图,返回 (bytes, mime);失败返回 (None, None)。"""
try:
with open(path, "rb") as f:
data = f.read()
except OSError:
return None, None
if data[:8] == b"\x89PNG\r\n\x1a\n":
return data, "image/png"
if data[:3] == b"\xff\xd8\xff":
return data, "image/jpeg"
out = decode_image(data)
if out is None:
return None, None
return out, ("image/png" if out[:8] == b"\x89PNG\r\n\x1a\n" else "image/jpeg")
def save_image(data, path):
if data[:8] == b"\x89PNG\r\n\x1a\n":
p = os.path.splitext(path)[0] + ".png"
elif data[:3] == b"\xff\xd8\xff":
p = os.path.splitext(path)[0] + ".jpg"
elif data[:4] == b"RIFF" and data[8:12] == b"WEBP":
p = os.path.splitext(path)[0] + ".webp"
elif data[:4] == b"\xabKTX":
p = os.path.splitext(path)[0] + ".ktx2"
else:
p = path
with open(p, "wb") as f:
f.write(data)
return p
+400
View File
@@ -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())