@ganziliang/desktop-pet 0.1.0

package/scripts/spritesheet.py

@@ -0,0 +1,425 @@
+#!/usr/bin/env python3
+"""把生图产出的动作序列图（sprite sheet）切成能直接给桌宠用的对齐精灵图。
+
+生图模型画出来的 sheet 有三个坑，这个脚本专门治它们：
+  1. 背景不是干净的纯色，甚至换一张图就换个底色
+     -> 自动从四角取中位数当背景色，再「从边缘 flood fill」抠。
+        只删和画布边缘连通的区域，所以角色身上的白色袜子/鞋子不会被误伤。
+  2. 各帧的角色身高/站位有细微差别，直接切会抖
+     -> 全部帧共用一个缩放系数（取身高中位数），并且共用同一条纵向基线，
+        既消掉忽大忽小，又保留姿势本身的自然起伏（走路该有的上下颠簸）。
+  3. 摆臂抬腿会让包围盒左右跑，按包围盒居中会「左右滑步」
+     -> 用 alpha 掩膜做互相关（IoU），找出每帧相对基准帧的最优水平偏移。
+
+用法：
+  python scripts/spritesheet.py 原始图.png 输出图.png --frames 4 --height 620
+  python scripts/spritesheet.py 原始图.png 输出图.png --frames 4 --debug --dump-frames
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+
+import numpy as np
+from PIL import Image, ImageDraw, ImageFilter
+from scipy import ndimage
+
+# ---------------------------------------------------------------- 背景抠除
+
+
+def border_color(arr: np.ndarray, ring: int = 4) -> np.ndarray:
+    """取画布四边一圈像素的中位数当背景色（比取四个角更抗单点噪声）。"""
+    top = arr[:ring].reshape(-1, 3)
+    bottom = arr[-ring:].reshape(-1, 3)
+    left = arr[:, :ring].reshape(-1, 3)
+    right = arr[:, -ring:].reshape(-1, 3)
+    all_px = np.concatenate([top, bottom, left, right], axis=0)
+    return np.median(all_px, axis=0)
+
+
+def key_out(
+    arr: np.ndarray, bg: np.ndarray, lo: float, hi: float, spill: bool
+) -> np.ndarray:
+    """返回 float32 的 alpha（0..1）。"""
+    dist = np.sqrt(((arr - bg) ** 2).sum(axis=2))
+    near = dist < lo
+    ramp = np.clip((dist - lo) / max(1.0, hi - lo), 0.0, 1.0)
+
+    # 绿幕另外用「绿度」判一次：双马尾和身体之间那种被压暗的绿，颜色距离早就超阈值了，
+    # 但绿度依然很高。而且那种空隙常被头发/身体围成闭合区域，根本连不到画布边框，
+    # 所以绿幕必须允许「全局判绿」，不能只靠边框连通。
+    global_green = None
+    if spill:
+        green = arr[..., 1] - np.maximum(arr[..., 0], arr[..., 2])
+        g_lo, g_hi = 45.0, 95.0
+        global_green = green > g_lo
+        near = near | global_green
+        ramp = np.maximum(ramp, np.clip((green - g_lo) / (g_hi - g_lo), 0.0, 1.0))
+
+    # 1) 生图的底色往往有渐变/噪点，直接连通会碎成很多小岛（实测能碎成几十块）。
+    #    先闭运算把背景缝起来，再标连通域，只取「碰到画布边框」的那些 ——
+    #    也就是真正的背景；角色内部颜色相近的区域（白袜子）不会和边框相连。
+    #    padding 必须填 True：否则 binary_closing 会把画布外的像素当背景，
+    #    边界一圈会被侵蚀掉，边框上就永远取不到背景标签了。
+    pad = 2
+    padded = np.pad(near, pad, mode="constant", constant_values=True)
+    closed = ndimage.binary_closing(padded, structure=np.ones((3, 3), bool), iterations=pad)
+    closed = closed[pad:-pad, pad:-pad]
+    labels, count = ndimage.label(closed)
+    if count:
+        border = np.concatenate([labels[0], labels[-1], labels[:, 0], labels[:, -1]])
+        touches = set(np.unique(border).tolist()) - {0}
+        bg_mask = np.isin(labels, list(touches)) & near
+    else:
+        bg_mask = np.zeros_like(near)
+    if global_green is not None:
+        bg_mask = bg_mask | global_green  # 闭合的绿幕空隙也要去掉
+
+    # 2) 边界一圈用羽化值（半透明像素），里层一律全不透明
+    ring = ndimage.binary_dilation(bg_mask, structure=np.ones((3, 3), bool), iterations=2)
+    ring = ring & ~bg_mask
+    alpha = np.where(bg_mask, 0.0, np.where(ring, ramp, 1.0)).astype(np.float32)
+
+    # 3) 绿幕残留：边缘半透明像素把背景色「拔」出来，免得缩图后挂一圈绿边
+    if spill:
+        g = arr[..., 1]
+        cap = np.maximum(arr[..., 0], arr[..., 2])
+        arr[..., 1] = np.where((alpha < 0.98) & (g > cap), cap, g)
+
+    return alpha
+
+
+def decontaminate(rgb: np.ndarray, alpha: np.ndarray, bg: np.ndarray) -> np.ndarray:
+    """半透明像素里混了背景色，反解回去，否则缩小后边缘会挂一圈底色。"""
+    a = alpha[..., None]
+    safe = np.clip(a, 1e-3, 1.0)
+    out = np.where(a < 0.99, (rgb - (1.0 - a) * bg) / safe, rgb)
+    return np.clip(out, 0, 255)
+
+
+def resize_premultiplied(rgba: np.ndarray, size: tuple[int, int]) -> np.ndarray:
+    """预乘 alpha 再缩放。
+
+    直接对 RGBA 做 LANCZOS 缩放会把「完全透明像素的 RGB」也蹭进边缘 ——
+    抠完背景的透明区往往还留着绿/白，缩完就会挂一圈彩边。
+    先乘上 alpha 再缩、缩完除回去，才是正确做法。
+    """
+    arr = rgba.astype(np.float32)
+    a = arr[..., 3:4] / 255.0
+    prem = np.concatenate([arr[..., :3] * a, arr[..., 3:4]], axis=2)
+    chans = [
+        np.asarray(Image.fromarray(prem[..., i], "F").resize(size, Image.LANCZOS))
+        for i in range(4)
+    ]
+    out = np.stack(chans, axis=2)
+    a2 = np.clip(out[..., 3:4] / 255.0, 0.0, 1.0)
+    rgb = np.where(a2 > 0.004, out[..., :3] / np.clip(a2, 0.004, 1.0), 0.0)
+    return np.concatenate([np.clip(rgb, 0, 255), np.clip(out[..., 3:4], 0, 255)], axis=2)
+
+
+def to_rgba(path: str, bg_hex: str | None, lo: float, hi: float) -> tuple[np.ndarray, np.ndarray]:
+    img = Image.open(path)
+
+    # 生图有时会直接给透明底的 PNG（比后处理抠图干净得多，抗锯齿是模型自己画的），
+    # 有就直接用，不要再去猜背景色。
+    if img.mode in ("RGBA", "LA") or (img.mode == "P" and "transparency" in img.info):
+        rgba = np.asarray(img.convert("RGBA"))
+        if (rgba[..., 3] < 10).mean() > 0.15:
+            print(f"   源图自带透明通道（{100 * (rgba[..., 3] < 10).mean():.1f}% 透明），直接使用")
+            return rgba.copy(), rgba[..., 3].astype(np.float32) / 255.0
+
+    arr = np.asarray(img.convert("RGB")).astype(np.float32)
+
+    if bg_hex:
+        bg = np.array([int(bg_hex[i : i + 2], 16) for i in (0, 2, 4)], dtype=np.float32)
+    else:
+        bg = border_color(arr.astype(np.uint8)).astype(np.float32)
+
+    greenish = bg[1] > max(bg[0], bg[2]) + 40
+    alpha = key_out(arr.copy(), bg, lo, hi, spill=greenish)
+    rgb = decontaminate(arr, alpha, bg)
+
+    rgba = np.dstack([rgb, alpha * 255.0]).astype(np.uint8)
+    print(
+        f"   背景色 rgb({int(bg[0])},{int(bg[1])},{int(bg[2])})"
+        f" -> 抠掉 {100 * (alpha < 0.5).mean():.1f}% 的像素"
+    )
+    return rgba, alpha
+
+
+# ---------------------------------------------------------------- 切帧
+
+
+def figure_runs(alpha: np.ndarray, frames: int, thresh: float = 0.08) -> list[tuple[int, int]]:
+    cols = alpha.max(axis=0) > thresh
+    runs: list[list[int]] = []
+    start = None
+    for x, on in enumerate(cols):
+        if on and start is None:
+            start = x
+        elif not on and start is not None:
+            runs.append([start, x])
+            start = None
+    if start is not None:
+        runs.append([start, len(cols)])
+    runs = [r for r in runs if r[1] - r[0] > 3]
+    if not runs:
+        raise SystemExit("没找到任何角色像素，检查背景色阈值（--lo/--hi）")
+
+    # 生图偶尔会把两帧粘在一起（中缝没留空），按宽度把最宽的劈开
+    while len(runs) < frames:
+        idx = int(np.argmax([r[1] - r[0] for r in runs]))
+        a, b = runs.pop(idx)
+        mid = (a + b) // 2
+        runs[idx:idx] = [[a, mid], [mid, b]]
+        print(f"   [warn] 有帧粘在一起，按宽度对半劈开分帧")
+    # 也可能切出了碎片（头发丝断开），把距离最近的合并
+    while len(runs) > frames:
+        gaps = [runs[i + 1][0] - runs[i][1] for i in range(len(runs) - 1)]
+        i = int(np.argmin(gaps))
+        runs[i] = [runs[i][0], runs[i + 1][1]]
+        runs.pop(i + 1)
+    return [(a, b) for a, b in runs]
+
+
+def bbox_of(alpha: np.ndarray, x0: int, x1: int, thresh: float = 0.35) -> tuple[int, int, int, int]:
+    sub = alpha[:, x0:x1] > thresh
+    rows = np.where(sub.any(axis=1))[0]
+    cols = np.where(sub.any(axis=0))[0]
+    return int(x0 + cols[0]), int(rows[0]), int(x0 + cols[-1] + 1), int(rows[-1] + 1)
+
+
+# ---------------------------------------------------------------- 对齐
+
+
+def best_shift(ref: np.ndarray, cur: np.ndarray, guess: int, radius: int) -> int:
+    """在 guess ± radius 里找让两帧重合度（IoU）最高的水平偏移。
+
+    guess 必须先把「两张掩膜里角色分别站在什么位置」对齐掉，
+    否则两者根本不相交，IoU 恒为 0，argmax 会一路滑到搜索边界。
+    """
+    best_dx, best_iou = guess, -1.0
+    ref_sum = ref.sum()
+    for dx in range(guess - radius, guess + radius + 1):
+        shifted = np.roll(cur, dx, axis=1)
+        if dx > 0:
+            shifted[:, :dx] = 0
+        elif dx < 0:
+            shifted[:, dx:] = 0
+        inter = float((ref * shifted).sum())
+        union = ref_sum + float(shifted.sum()) - inter
+        iou = inter / union if union > 0 else 0.0
+        if iou > best_iou:
+            best_iou, best_dx = iou, dx
+    return best_dx
+
+
+def build_sheet(
+    rgba: np.ndarray,
+    alpha: np.ndarray,
+    frames: int,
+    target: int,
+    pad_x: int,
+    pad_y: int,
+    debug: bool,
+    norm_axis: str = "h",
+    align: str = "iou",
+) -> tuple[Image.Image, list[dict], dict]:
+    runs = figure_runs(alpha, frames)
+    boxes = [bbox_of(alpha, a, b) for a, b in runs]
+    heights = [y1 - y0 for (_x0, y0, _x1, y1) in boxes]
+    widths = [x1 - x0 for (x0, _y0, x1, _y1) in boxes]
+    med_h = float(np.median(heights))
+    med_w = float(np.median(widths))
+    # 竖构图（站/跑）按身高归一化；横构图（游泳）身体是横着的，得按身长归一化，
+    # 否则会把「躺平的角色」按它那点高度放大，尺寸和立绘对不上。
+    med_ref = med_h if norm_axis == "h" else med_w
+    scale = target / med_ref
+
+    info = []
+    for i, ((x0, y0, x1, y1), (ra, rb)) in enumerate(zip(boxes, runs)):
+        info.append(
+            {"i": i, "box": (x0, y0, x1, y1), "run": (ra, rb), "h": y1 - y0, "w": x1 - x0}
+        )
+        if debug:
+            print(
+                f"   frame{i}: box=({x0},{y0})-({x1},{y1}) {x1 - x0}x{y1 - y0} "
+                f"槽位宽={rb - ra} 高差={y1 - y0 - med_h:+.0f}px"
+            )
+    axis_name = "身高" if norm_axis == "h" else "身长"
+    print(f"   {axis_name}中位数 {med_ref:.0f}px，统一缩放 ×{scale:.4f} -> {target}px")
+
+    # 整张图一起缩放：所有帧共用同一个系数，才不会忽大忽小
+    new_w = max(1, int(round(rgba.shape[1] * scale)))
+    new_h = max(1, int(round(rgba.shape[0] * scale)))
+    scaled = resize_premultiplied(rgba, (new_w, new_h))
+    sa = scaled[..., 3] / 255.0
+
+    boxes2 = [bbox_of(sa, int(round(a * scale)), int(round(b * scale))) for a, b in runs]
+
+    # 纵向：所有帧共用同一条带，站位差异原样保留（该有的起伏不抹掉）
+    band_top = max(0, min(b[1] for b in boxes2) - pad_y)
+    band_bottom = min(new_h, max(b[3] for b in boxes2) + pad_y)
+    band_h = band_bottom - band_top
+
+    band_masks = []
+    for (x0, _y0, x1, _y1) in boxes2:
+        m = sa[band_top:band_bottom].copy()
+        m[:, : max(0, x0 - 4)] = 0.0
+        m[:, x1 + 4 :] = 0.0
+        band_masks.append(m)
+
+    # 横向：以「身高最接近中位数」的那帧为基准，互相关对齐。
+    # 只拿上半身参与匹配：腿脚每帧摆幅最大，放进来会把对齐往四肢上带，反而左右滑步。
+    # 横躺的角色（游泳）不能用 IoU 对齐：手臂前伸本来就是动画本身，
+    # 按轮廓重合去对齐会把「前伸」这个动作抵消掉，所以这类只做包围盒粗对齐。
+    focus_h = band_h if align == "center" else max(8, int(0.6 * band_h))
+    focus = [m[:focus_h] for m in band_masks]
+    ref_idx = int(np.argmin([abs(h - med_ref) for h in (heights if norm_axis == "h" else widths)]))
+    ref_cx = (boxes2[ref_idx][0] + boxes2[ref_idx][2]) / 2.0
+    radius = max(12, int(0.05 * new_w / frames))
+    dxs = []
+    for i, m in enumerate(focus):
+        cx_i = (boxes2[i][0] + boxes2[i][2]) / 2.0
+        if i == ref_idx:
+            dx = 0
+        else:
+            # 先用包围盒中心粗对齐，再在附近找精调量
+            guess = int(round(ref_cx - cx_i))
+            dx = guess if align == "center" else best_shift(focus[ref_idx], m, guess, radius)
+        dxs.append(dx)
+        if debug:
+            tag = "基准" if i == ref_idx else f"粗对齐 {int(round(ref_cx - cx_i)):+d} 精调 {dx - int(round(ref_cx - cx_i)):+d}"
+            print(f"   frame{i}: 水平对齐 {dx:+d}px ({tag})")
+
+    # 对齐后的包围盒（都在基准帧的坐标系里），据此定帧宽和中轴
+    left = [boxes2[i][0] + dxs[i] for i in range(frames)]
+    right = [boxes2[i][2] + dxs[i] for i in range(frames)]
+    half = max(max(abs(left[i] - ref_cx), abs(right[i] - ref_cx)) for i in range(frames))
+    frame_w = int(np.ceil(2 * half)) + 2 * pad_x
+    center = frame_w / 2.0
+
+    out = Image.new("RGBA", (frame_w * frames, band_h), (0, 0, 0, 0))
+    for i, m in enumerate(band_masks):
+        # 只留当前这帧的像素，别的帧先抹掉，免得被一起贴进来
+        cut = scaled[band_top:band_bottom].copy()
+        cut[..., 3] = np.where(m > 0, cut[..., 3], 0)
+        piece = Image.fromarray(cut.astype(np.uint8), "RGBA")
+        # 贴图只是平移，不改变内容自身的坐标。
+        # dxs[i] 表示「把这帧移到基准帧位置上需要平移多少」，于是这帧内部
+        # 真正对应基准帧中心的那个点位于 ref_cx - dxs[i]，把它放到帧中心即可。
+        paste_x = int(round(center - ref_cx + dxs[i]))
+        out.paste(piece, (i * frame_w + paste_x, 0), piece)
+
+    return out, info, {
+        "frameW": frame_w,
+        "frameH": band_h,
+        "refPx": int(round(med_ref * scale)),
+        "axis": norm_axis,
+    }
+
+
+# ---------------------------------------------------------------- main
+
+
+def main() -> None:
+    ap = argparse.ArgumentParser(description="生图序列图 -> 对齐的桌宠精灵图")
+    ap.add_argument("src")
+    ap.add_argument("dst")
+    ap.add_argument("--frames", type=int, default=4, help="序列图里有几帧")
+    ap.add_argument(
+        "--size", "--height", dest="size", type=int, default=620,
+        help="输出里角色的特征尺寸（px），默认按身高算",
+    )
+    ap.add_argument(
+        "--norm-axis", choices=("h", "w"), default="h",
+        help="按哪个轴归一化：h=身高（站立/跑步），w=身长（游泳这类横躺的动作）",
+    )
+    ap.add_argument(
+        "--align", choices=("iou", "center"), default="iou",
+        help="帧间水平对齐：iou=轮廓互相关（站立类），center=包围盒居中（横躺类，"
+             "否则会把手臂前伸这个动作本身抵消掉）",
+    )
+    ap.add_argument("--key", default=None, help="写进 sprites.json 的键名，默认从输出文件名推导")
+    ap.add_argument("--manifest", default=None,
+                    help="精灵图元信息清单（帧数/帧尺寸/角色参考尺寸），默认写到输出同目录的 sprites.json")
+    ap.add_argument("--no-manifest", action="store_true", help="不写清单")
+    ap.add_argument("--bg", default=None, help="手动指定背景色 RRGGBB，默认自动识别")
+    ap.add_argument("--lo", type=float, default=34.0, help="颜色距离低于此值算背景")
+    ap.add_argument("--hi", type=float, default=92.0, help="高于此值算完全前景（中间做羽化）")
+    ap.add_argument("--pad-x", type=int, default=10)
+    ap.add_argument("--pad-y", type=int, default=8)
+    ap.add_argument("--debug", action="store_true")
+    ap.add_argument("--dump-frames", action="store_true", help="额外把每一帧单独存出来方便肉眼查")
+    args = ap.parse_args()
+
+    print(f"[1/3] 抠背景  {os.path.basename(args.src)}")
+    rgba, alpha = to_rgba(args.src, args.bg, args.lo, args.hi)
+    frac = float((alpha < 0.5).mean())
+    if frac > 0.85:
+        print(f"   [warn] 抠掉了 {frac * 100:.0f}% 的像素，背景可能和角色颜色太接近，"
+              f"调小 --lo 或换一张源图")
+
+    print("[2/3] 切帧 + 对齐")
+    sheet, info, meta = build_sheet(
+        rgba, alpha, args.frames, args.size, args.pad_x, args.pad_y, args.debug,
+        norm_axis=args.norm_axis, align=args.align,
+    )
+
+    print("[3/3] 输出")
+    os.makedirs(os.path.dirname(os.path.abspath(args.dst)), exist_ok=True)
+    sheet.save(args.dst)
+    fw = sheet.width // args.frames
+    print(f"   {args.dst}  {sheet.width}x{sheet.height}  单帧 {fw}x{sheet.height}")
+
+    if not args.no_manifest:
+        key = args.key or os.path.splitext(os.path.basename(args.dst))[0]
+        if key.startswith("pet-"):
+            key = key[4:]
+        mpath = args.manifest or os.path.join(os.path.dirname(os.path.abspath(args.dst)), "sprites.json")
+        entry = {
+            "file": os.path.basename(args.dst),
+            "frames": args.frames,
+            "frameW": fw,
+            "frameH": sheet.height,
+            "refPx": meta["refPx"],
+            "axis": meta["axis"],
+            "padX": args.pad_x,
+            "padY": args.pad_y,
+        }
+        data = {}
+        if os.path.exists(mpath):
+            try:
+                with open(mpath, encoding="utf-8") as fh:
+                    data = json.load(fh)
+            except Exception:
+                data = {}
+        data[key] = entry
+        with open(mpath, "w", encoding="utf-8") as fh:
+            json.dump(data, fh, indent=2, ensure_ascii=False)
+        print(f"   清单 {mpath}  [{key}] frames={entry['frames']} "
+              f"帧={fw}x{sheet.height} ref={entry['refPx']}px axis={entry['axis']}")
+
+    if args.dump_frames:
+        root, ext = os.path.splitext(args.dst)
+        for i in range(args.frames):
+            sheet.crop((i * fw, 0, (i + 1) * fw, sheet.height)).save(f"{root}-f{i}{ext}")
+        # 拼一张放大预览图，方便一眼看对齐效果
+        preview = Image.new("RGBA", (fw, sheet.height * args.frames), (240, 240, 245, 255))
+        for i in range(args.frames):
+            preview.alpha_composite(
+                sheet.crop((i * fw, 0, (i + 1) * fw, sheet.height)).convert("RGBA"), (0, i * sheet.height)
+            )
+            ImageDraw.Draw(preview).line(
+                [(0, i * sheet.height), (fw, i * sheet.height)], fill=(255, 120, 170, 255), width=2
+            )
+        preview_path = f"{root}-preview{ext}"
+        preview.save(preview_path)
+        print(f"   预览（竖排每帧，方便看有没有左右滑步）: {preview_path}")
+
+
+if __name__ == "__main__":
+    sys.exit(main())