mirror of
https://github.com/NousResearch/hermes-agent.git
synced 2026-11-17 04:11:35 +00:00
* refactor(plugins): remove the Sep 2026 decomposition compat layer on schedule The PLUGIN-COMPAT layer (2776813df3+d63e380324+0a5164cebe) kept pre-#102117 import paths alive for external plugins until 2026-09-14. That window closed two weeks ago; since then the loader has already been skipping plugins that use the old paths. This removes the layer itself: - 328 appended `PLUGIN-COMPAT` blocks (lazy `__getattr__` pointer tables, re-exported third-party names, restored dead definitions) and the three re-export stub modules (gateway/startup_watchdog, hermes_cli/observability/relay_runtime, tools/environments/modal_utils) - COMPAT_MANIFEST.md, compat_manifest.json, scripts/check_compat_pointers.py and its lint step - the reporting surfaces: CLI banner notice, `hermes plugins compat`, the `hermes doctor` section, the post-update notice, the Desktop one-time dialog, the loader's pre-import skip and the `plugins.allow_deprecated_imports` escape hatch An external plugin that still imports an old path now fails to load with its ImportError as the reason in `hermes plugins list`, the same path as any broken plugin. hermes_cli/plugin_compat.py stays as three inert stubs (compat_report, removal_in_effect, summary_lines): an already-running pre-removal `hermes update` lazy-imports them after the checkout swap (tests/compat/old_updater_surface.json). In-tree fallout, both already dead: hermes_cli/setup.py::_check_espeak_ng (no callers; its `shutil` came from a compat block) and gateway/config.py::SessionResetPolicy ("retained solely for the scheduled plugin-compat window"). Two test_run_agent patches targeted the removed `run_agent.handle_function_call` pointer; they now patch `model_tools.handle_function_call`, the seam production reads, like every sibling test in that file. * chore: retrigger CI (zero-job startup_failure phantom) * test: drop resolution allowlist rows for the two deleted which() sites hermes_cli/setup.py::_check_espeak_ng (dead) and tools/skillevaluator_scan.py::scanner_available (a restored definition inside a PLUGIN-COMPAT block) no longer exist; the stale-row gate requires their allowlist entries go with them.
621 lines
29 KiB
Python
621 lines
29 KiB
Python
"""Deterministic spritesheet assembly — generated row strips → Hermes atlas.
|
|
|
|
Image models draw a row of poses well but can't do exact grid geometry, so the
|
|
model never owns the layout: it emits one loose strip per state and these ops
|
|
slice it into centered transparent 192x208 cells packed into the petdex/Codex
|
|
atlas (8 cols x 9 rows, 1536x1872; see ``constants.CODEX_STATE_ROWS``).
|
|
Segmentation/fit/residue logic adapted from OpenAI's ``hatch-pet`` skill (Apache-2.0).
|
|
"""
|
|
|
|
from __future__ import annotations
|
|
|
|
import logging
|
|
import math
|
|
from collections import Counter, deque
|
|
from itertools import groupby
|
|
from pathlib import Path
|
|
|
|
from PIL import Image, ImageChops, ImageFilter
|
|
|
|
from agent.pet.constants import FRAME_H, FRAME_W
|
|
|
|
logger = logging.getLogger(__name__)
|
|
|
|
CELL_WIDTH = FRAME_W
|
|
CELL_HEIGHT = FRAME_H
|
|
|
|
# (state, row index, frame count). Order/row indices MUST match
|
|
# ``constants.CODEX_STATE_ROWS``; frame counts mirror the petdex ``hatch-pet``
|
|
# spec. Rows shorter than 8 leave their tail transparent (renderer trims it).
|
|
# ``running`` is the in-place *working* state; ``running-right``/``-left`` walk.
|
|
ROW_SPECS: list[tuple[str, int, int]] = [
|
|
("idle", 0, 6), ("running-right", 1, 8), ("running-left", 2, 8), ("waving", 3, 4), ("jumping", 4, 5),
|
|
("failed", 5, 8), ("waiting", 6, 6), ("running", 7, 6), ("review", 8, 6),
|
|
]
|
|
|
|
ATLAS_WIDTH = max(count for _, _, count in ROW_SPECS) * CELL_WIDTH
|
|
ATLAS_HEIGHT = len(ROW_SPECS) * CELL_HEIGHT
|
|
|
|
_ALPHA_FLOOR = 16 # alpha at/below which a pixel is "background"
|
|
_CELL_PAD = 10 # padding kept around a fitted sprite
|
|
_NORMALIZE_PAD = 14 # normalized cells fill like real petdex pets (~5px from the edges)
|
|
_SIDE_LOBE_RATIO = 0.18 # adjacent-pose bleed is a small lobe; sizeable lobes (wide poses) survive
|
|
_NEIGHBOURS = ((1, 0), (-1, 0), (0, 1), (0, -1))
|
|
_NEAREST = Image.Resampling.NEAREST # interpolating resamples blur hard pixel-art edges
|
|
|
|
|
|
def _median(values) -> int:
|
|
ordered = sorted(values)
|
|
return ordered[len(ordered) // 2]
|
|
|
|
|
|
def _median_box_size(boxes) -> tuple[int, int]:
|
|
"""``(median width, median height)`` of ``(l, t, r, b)`` *boxes*, each at least 1."""
|
|
return max(1, _median(r - l for l, _t, r, _b in boxes)), max(1, _median(b - t for _l, t, _r, b in boxes))
|
|
|
|
|
|
def _blank(size=(CELL_WIDTH, CELL_HEIGHT)):
|
|
return Image.new("RGBA", size, (0, 0, 0, 0))
|
|
|
|
|
|
def _place(sprite, size: tuple[int, int], offset: tuple[int, int] = (0, 0)):
|
|
"""*sprite* alpha-composited at *offset* onto a new transparent canvas of *size*."""
|
|
canvas = _blank(size)
|
|
canvas.alpha_composite(sprite, offset)
|
|
return canvas
|
|
|
|
|
|
def _clear_region(image, box: tuple[int, int, int, int]) -> None:
|
|
"""Make the ``(left, top, right, bottom)`` region of *image* fully transparent, in place."""
|
|
image.paste(_blank((box[2] - box[0], box[3] - box[1])), (box[0], box[1]))
|
|
|
|
|
|
def _load_rgba(image):
|
|
"""Open a path (or take an image) as RGBA."""
|
|
if isinstance(image, (str, Path)):
|
|
with Image.open(image) as opened:
|
|
return opened.convert("RGBA")
|
|
return image.convert("RGBA")
|
|
|
|
|
|
def _flood(w: int, h: int, visited: bytearray, seeds, accept) -> list[tuple[int, int]]:
|
|
"""4-connected BFS from *seeds* over pixels passing *accept*; returns the visited pixels."""
|
|
queue = deque(seeds)
|
|
pixels: list[tuple[int, int]] = []
|
|
while queue:
|
|
x, y = queue.popleft()
|
|
pixels.append((x, y))
|
|
for dx, dy in _NEIGHBOURS:
|
|
nx, ny = x + dx, y + dy
|
|
if 0 <= nx < w and 0 <= ny < h and not visited[ny * w + nx]:
|
|
visited[ny * w + nx] = 1
|
|
if accept(nx, ny):
|
|
queue.append((nx, ny))
|
|
return pixels
|
|
|
|
|
|
def _border_flood(w: int, h: int, visited: bytearray, accept) -> list[tuple[int, int]]:
|
|
"""Flood from every border pixel passing *accept* (edge-connected region only)."""
|
|
border = [(x, y) for x in range(w) for y in (0, h - 1)] + [(x, y) for y in range(h) for x in (0, w - 1)]
|
|
seeds: list[tuple[int, int]] = []
|
|
for x, y in border: # corners appear twice in ``border``; the visited mark dedupes them
|
|
if not visited[y * w + x] and accept(x, y):
|
|
visited[y * w + x] = 1
|
|
seeds.append((x, y))
|
|
return _flood(w, h, visited, seeds, accept)
|
|
|
|
|
|
def _unvisited_components(w: int, h: int, visited: bytearray, accept):
|
|
"""Yield each 4-connected component of not-yet-visited pixels passing *accept*, in scan order."""
|
|
for start in range(w * h):
|
|
if visited[start]:
|
|
continue
|
|
visited[start] = 1
|
|
x, y = start % w, start // w
|
|
if accept(x, y):
|
|
yield _flood(w, h, visited, [(x, y)], accept)
|
|
|
|
|
|
def _near_key_mask(image, key: tuple[int, int, int], tol: int = 48):
|
|
"""``L`` mask, 255 where a pixel is within *tol* per-channel of *key*.
|
|
|
|
Tight on purpose: marks only near-pure backdrop so trapped chroma pockets seed the flood while chroma-tinted character pixels stay outside it.
|
|
"""
|
|
r, g, b = (ch.point(lambda v, k=k: 255 if abs(v - k) <= tol else 0) for ch, k in zip(image.split()[:3], key))
|
|
return ImageChops.darker(ImageChops.darker(r, g), b)
|
|
|
|
|
|
def _remove_masked(rgba, mask):
|
|
"""Clear the pixels *mask* (``L``, 255 = remove) selects, then erode alpha by 1px (3x3 min).
|
|
|
|
The erosion drops the antialiased key/sprite blend ring (too far from the key to match); the sprite's thick outline keeps the silhouette.
|
|
"""
|
|
out = Image.composite(_blank(rgba.size), rgba, mask)
|
|
out.putalpha(out.getchannel("A").filter(ImageFilter.MinFilter(3)))
|
|
return out
|
|
|
|
|
|
def remove_background(image, *, chroma_key: tuple[int, int, int] | None = None, threshold: float = 90.0):
|
|
"""Return *image* (RGBA) with its flat background keyed out to transparent.
|
|
|
|
Strips already carrying a real alpha background (>5% of pixels at/below the floor)
|
|
are left alone (holes repaired). Otherwise key out *chroma_key* (or the most common
|
|
opaque corner color) from the border inward: a global color match punched holes
|
|
wherever an interior highlight matched the backdrop.
|
|
"""
|
|
rgba = image.convert("RGBA")
|
|
w, h = rgba.size
|
|
alpha = rgba.getchannel("A")
|
|
if alpha.getextrema()[0] <= _ALPHA_FLOOR and sum(alpha.histogram()[: _ALPHA_FLOOR + 1]) > w * h * 0.05:
|
|
return _repair_internal_alpha_holes(rgba)
|
|
px = rgba.load()
|
|
if not (key := chroma_key):
|
|
corners = Counter(tuple(px[x, y][:3]) for x, y in ((0, 0), (w - 1, 0), (0, h - 1), (w - 1, h - 1)) if px[x, y][3] > _ALPHA_FLOOR)
|
|
key = corners.most_common(1)[0][0] if corners else (0, 255, 0)
|
|
# Fast path for saturated chroma keys (our prompts use hot magenta): C-level
|
|
# channel ops clear border backdrop and enclosed pockets alike, no Python flood.
|
|
if max(key) - min(key) >= 120:
|
|
opaque = rgba.getchannel("A").point(lambda a: 255 if a > _ALPHA_FLOOR else 0)
|
|
return _remove_masked(rgba, ImageChops.darker(_near_key_mask(rgba, key), opaque))
|
|
|
|
def _is_bg(x: int, y: int) -> bool:
|
|
r, g, b, a = px[x, y]
|
|
return a > _ALPHA_FLOOR and math.sqrt((r - key[0]) ** 2 + (g - key[1]) ** 2 + (b - key[2]) ** 2) <= threshold
|
|
|
|
# Border-only flood on purpose: a desaturated near-white/gray key must never
|
|
# seed from the character's interior (that is the hole-punching case). Mark
|
|
# removals in a flat mask and composite once in C — per-pixel writes stalled the gateway.
|
|
remove = bytearray(w * h)
|
|
for x, y in _border_flood(w, h, bytearray(w * h), _is_bg):
|
|
remove[y * w + x] = 1
|
|
return _remove_masked(rgba, Image.frombytes("L", (w, h), bytes(remove)).point(lambda v: 255 if v else 0))
|
|
|
|
|
|
def _repair_internal_alpha_holes(image):
|
|
"""Fill transparent islands fully enclosed by opaque sprite pixels.
|
|
|
|
Some providers return "transparent" PNGs with swiss-cheese alpha inside the character; enclosed holes take the average opaque-neighbour color.
|
|
"""
|
|
rgba = image.convert("RGBA")
|
|
w, h = rgba.size
|
|
px = rgba.load()
|
|
visited = bytearray(w * h)
|
|
_is_transparent = lambda x, y: px[x, y][3] <= _ALPHA_FLOOR # noqa: E731
|
|
_border_flood(w, h, visited, _is_transparent) # edge-connected transparency = background
|
|
for hole in _unvisited_components(w, h, visited, _is_transparent):
|
|
seen = set(hole)
|
|
samples = [
|
|
px[nx, ny][:3]
|
|
for x, y in hole
|
|
for dx, dy in _NEIGHBOURS
|
|
if 0 <= (nx := x + dx) < w and 0 <= (ny := y + dy) < h and (nx, ny) not in seen and px[nx, ny][3] > _ALPHA_FLOOR
|
|
]
|
|
color = (*(round(sum(c[i] for c in samples) / len(samples)) for i in range(3)), 255) if samples else (0, 0, 0, 255)
|
|
for hx, hy in hole:
|
|
px[hx, hy] = color
|
|
return rgba
|
|
|
|
|
|
def _fit_to_cell(image):
|
|
"""Crop to content, scale to fit a padded cell, and center on transparent."""
|
|
image = _drop_side_bleed(image)
|
|
if (bbox := image.getbbox()) is None:
|
|
return _blank()
|
|
sprite = image.crop(bbox)
|
|
scale = min((CELL_WIDTH - _CELL_PAD) / sprite.width, (CELL_HEIGHT - _CELL_PAD) / sprite.height, 1.0)
|
|
if scale != 1.0:
|
|
sprite = sprite.resize((max(1, round(sprite.width * scale)), max(1, round(sprite.height * scale))), _NEAREST)
|
|
return _place(sprite, (CELL_WIDTH, CELL_HEIGHT), ((CELL_WIDTH - sprite.width) // 2, (CELL_HEIGHT - sprite.height) // 2))
|
|
|
|
|
|
def _drop_side_bleed(image):
|
|
"""Remove tiny separated left/right lobes (neighbour-pose slivers) before fitting.
|
|
|
|
Component extraction may group a near sliver with the subject; the column profile still shows it as a low-mass lobe. Only those go (wide poses survive).
|
|
"""
|
|
rgba = image.convert("RGBA")
|
|
w, h = rgba.size
|
|
runs = _content_runs(_column_profile(rgba))
|
|
keep = [run for run, m in runs if m >= max(m for _run, m in runs) * _SIDE_LOBE_RATIO] if runs else []
|
|
if len(runs) < 2 or len(keep) == len(runs):
|
|
return rgba
|
|
rgba = rgba.copy()
|
|
prev = 0
|
|
for left, right in [*keep, (w, w)]: # (w, w) sentinel clears the trailing gap
|
|
if left > prev:
|
|
_clear_region(rgba, (prev, 0, left, h))
|
|
prev = right
|
|
return rgba
|
|
|
|
|
|
def _thin_groups(indices: list[int]) -> list[tuple[int, int]]:
|
|
"""``(start, end)`` for each run of consecutive *indices* at most 4 long."""
|
|
runs = ([i for _, i in g] for _k, g in groupby(enumerate(indices), key=lambda p: p[1] - p[0]))
|
|
return [(run[0], run[-1] + 1) for run in runs if len(run) <= 4]
|
|
|
|
|
|
def _erase_long_axis_lines(image):
|
|
"""Remove thin slot-spanning guide/floor/divider lines (they survive keying and bridge clean poses)."""
|
|
rgba = image.convert("RGBA").copy()
|
|
w, h = rgba.size
|
|
alpha = rgba.getchannel("A")
|
|
opaque = [[alpha.getpixel((x, y)) > _ALPHA_FLOOR for x in range(w)] for y in range(h)]
|
|
for top, bottom in _thin_groups([y for y in range(h) if sum(opaque[y]) >= w * 0.85]):
|
|
_clear_region(rgba, (0, top, w, bottom))
|
|
for left, right in _thin_groups([x for x in range(w) if sum(row[x] for row in opaque) >= h * 0.85]):
|
|
_clear_region(rgba, (left, 0, right, h))
|
|
return rgba
|
|
|
|
|
|
def _component_boxes(image) -> list[tuple[tuple[int, int, int, int], int]]:
|
|
"""Connected opaque components as ``[(bbox, mass)]``."""
|
|
rgba = image.convert("RGBA")
|
|
if (bbox := rgba.getbbox()) is None:
|
|
return []
|
|
l0, t0, r0, b0 = bbox
|
|
w, h = r0 - l0, b0 - t0
|
|
alpha = rgba.getchannel("A").load()
|
|
components = _unvisited_components(w, h, bytearray(w * h), lambda x, y: alpha[l0 + x, t0 + y] > _ALPHA_FLOOR)
|
|
return [((l0 + min(xs), t0 + min(ys), l0 + max(xs) + 1, t0 + max(ys) + 1), len(xs)) for xs, ys in map(lambda p: zip(*p), components)]
|
|
|
|
|
|
def _isolate_slot_subject(image):
|
|
"""Keep the slot's real subject; drop detached effects/noise."""
|
|
rgba = _erase_long_axis_lines(image)
|
|
comps = _component_boxes(rgba)
|
|
if not comps:
|
|
return rgba
|
|
main_box, main_mass = max(comps, key=lambda item: item[1])
|
|
ml, _mt, mr, _mb = main_box
|
|
mw = max(1, mr - ml)
|
|
out = _blank(rgba.size)
|
|
for box, mass in comps:
|
|
# Keep attached-looking accessories (halos); drop sparkles/tears/noise.
|
|
left, _top, right, _bottom = box
|
|
overlap = max(0, min(right, mr) - max(left, ml))
|
|
near_main = (ml - mw * 0.25) <= (left + right) / 2 <= (mr + mw * 0.25)
|
|
if box == main_box or (mass >= max(24, main_mass * 0.035) and (overlap >= mw * 0.3 or near_main)):
|
|
out.alpha_composite(rgba.crop(box), (box[0], box[1]))
|
|
return out
|
|
|
|
|
|
def _has_margin(size: tuple[int, int], box: tuple[int, int, int, int], fx: float, fy: float) -> bool:
|
|
"""True when *box* leaves empty room on all four edges of an image of *size* (≥4px, ≤12/16px)."""
|
|
w, h = size
|
|
left, top, right, bottom = box
|
|
min_x, min_y = max(4, min(12, round(w * fx))), max(4, min(16, round(h * fy)))
|
|
return left >= min_x and top >= min_y and w - right >= min_x and h - bottom >= min_y
|
|
|
|
|
|
def _group_component_rows(boxes: list[tuple[int, int, int, int]]) -> list[list[tuple[int, int, int, int]]]:
|
|
"""Group component boxes into visual rows, then sort left→right."""
|
|
if not boxes:
|
|
return []
|
|
cy = lambda b: (b[1] + b[3]) / 2 # noqa: E731
|
|
row_tol = max(12, _median_box_size(boxes)[1] * 0.55)
|
|
rows: list[list[tuple[int, int, int, int]]] = []
|
|
centers: list[float] = []
|
|
for box in sorted(boxes, key=cy):
|
|
i = next((i for i, center in enumerate(centers) if abs(cy(box) - center) <= row_tol), None)
|
|
if i is None:
|
|
rows.append([box])
|
|
centers.append(cy(box))
|
|
else:
|
|
rows[i].append(box)
|
|
centers[i] = sum(cy(b) for b in rows[i]) / len(rows[i])
|
|
ordered = [row for _center, row in sorted(zip(centers, rows, strict=False), key=lambda item: item[0])]
|
|
for row in ordered:
|
|
row.sort(key=lambda b: (b[0] + b[2]) / 2)
|
|
return ordered
|
|
|
|
|
|
def _merge_related_boxes(boxes: list[tuple[int, int, int, int]]) -> list[tuple[int, int, int, int]]:
|
|
"""Merge disconnected parts of one subject (capes, tails, props) on the same row.
|
|
|
|
Merges when vertical spans overlap and the horizontal gap is tiny relative to component size; never bridges the larger gaps between separate poses.
|
|
"""
|
|
def related(a, b) -> bool:
|
|
(al, at, ar, ab), (bl, bt, br, bb) = a, b
|
|
v_overlap, min_h = max(0, min(ab, bb) - max(at, bt)), max(1, min(ab - at, bb - bt))
|
|
gap, min_w = max(0, max(al, bl) - min(ar, br)), max(1, min(ar - al, br - bl))
|
|
return v_overlap >= min_h * 0.45 and gap <= max(14, min_w * 0.22)
|
|
|
|
boxes = list(boxes)
|
|
changed = True
|
|
while changed:
|
|
changed = False
|
|
merged: list[tuple[int, int, int, int]] = []
|
|
used = [False] * len(boxes)
|
|
for i, a in enumerate(boxes):
|
|
if used[i]:
|
|
continue
|
|
used[i] = True
|
|
for j, b in enumerate(boxes[i + 1 :], i + 1):
|
|
if not used[j] and related(a, b):
|
|
a = (min(a[0], b[0]), min(a[1], b[1]), max(a[2], b[2]), max(a[3], b[3]))
|
|
used[j] = changed = True
|
|
merged.append(a)
|
|
boxes = merged
|
|
return boxes
|
|
|
|
|
|
def _component_crops(strip, frame_count: int, *, require_padding: bool = False) -> list | None:
|
|
"""Frames as connected subjects in reading order (robust to 2D grids); ``None`` when *frame_count* can't be met."""
|
|
def attempt(source) -> list | None:
|
|
subjects = _significant_subject_boxes(source, min_mass=64)
|
|
if len(subjects) < frame_count:
|
|
return None
|
|
rows = _group_component_rows(subjects)
|
|
ordered = [box for row in rows for box in row][:frame_count] # rows hold every subject, so exactly frame_count
|
|
if require_padding and not all(_has_margin(source.size, box, 0.01, 0.015) for box in ordered):
|
|
return None
|
|
multirow = len(rows) > 1
|
|
frames = []
|
|
for left, top, right, bottom in ordered:
|
|
pad_x, pad_y = max(8, round((right - left) * 0.08)), max(8, round((bottom - top) * 0.08))
|
|
# One-row strips keep full height so vertical motion survives; grids pad the box.
|
|
cl, cr = (0, source.width) if frame_count == 1 else (max(0, left - pad_x), min(source.width, right + pad_x))
|
|
ct, cb = (max(0, top - pad_y), min(source.height, bottom + pad_y)) if multirow else (0, source.height)
|
|
# No second component filter here: capes/tails can be legitimate
|
|
# disconnected lobes inside the chosen subject box.
|
|
frames.append(_place(source.crop((left, top, right, bottom)), (cr - cl, cb - ct), (left - cl, top - ct)))
|
|
return frames
|
|
|
|
return attempt(strip) or attempt(_erase_long_axis_lines(strip))
|
|
|
|
|
|
def _sever_expected_gutters(strip, frame_count: int):
|
|
"""Cut narrow transparent bands at expected frame boundaries (shared shadows/1px bridges merge poses)."""
|
|
if frame_count <= 1:
|
|
return strip
|
|
out = strip.copy()
|
|
alpha = out.getchannel("A") # zero alpha only; RGB is left untouched
|
|
slot = out.width / frame_count
|
|
half = max(3, min(18, round(slot * 0.06)))
|
|
for x in (round(i * slot) for i in range(1, frame_count)):
|
|
alpha.paste(0, (max(0, x - half), 0, min(out.width, x + half + 1), out.height))
|
|
out.putalpha(alpha)
|
|
return out
|
|
|
|
|
|
def _clean_slot(image):
|
|
return _drop_side_bleed(_isolate_slot_subject(image))
|
|
|
|
|
|
def _slot_crops(strip, frame_count: int, *, require_padding: bool = False) -> list | None:
|
|
"""Slice *strip* into *frame_count* equal, independently cleaned columns (one shared coordinate frame)."""
|
|
w, h = strip.size
|
|
frames = [_clean_slot(strip.crop((round(i * w / frame_count), 0, round((i + 1) * w / frame_count), h))) for i in range(frame_count)]
|
|
if require_padding and any((b := f.getbbox()) is None or not _has_margin(f.size, b, 0.025, 0.02) for f in frames):
|
|
return None
|
|
return frames
|
|
|
|
|
|
def _content_runs(profile: list[int], *, threshold: int = 2) -> list[tuple[tuple[int, int], int]]:
|
|
"""``[((left, right), mass)]`` column spans whose alpha exceeds *threshold* (candidate frames)."""
|
|
runs: list[tuple[tuple[int, int], int]] = []
|
|
start: int | None = None
|
|
for x, v in enumerate(list(profile) + [0]):
|
|
if v > threshold:
|
|
if start is None:
|
|
start = x
|
|
elif start is not None:
|
|
runs.append(((start, x), sum(profile[start:x])))
|
|
start = None
|
|
return runs
|
|
|
|
|
|
def _frame_x_ranges(strip, frame_count: int) -> list[tuple[int, int]] | None:
|
|
"""Per-frame ``(left, right)`` column ranges from the row's empty gutters.
|
|
|
|
Extra spans merge across the smallest gaps (a detached halo sits closer to its body than to the next pose); fewer spans than frames → ``None``.
|
|
"""
|
|
runs = _content_runs(_column_profile(strip))
|
|
groups = [[l, r] for (l, r), m in runs if m >= max(m for _run, m in runs) * 0.02] if runs else []
|
|
if len(groups) < frame_count:
|
|
return None
|
|
while len(groups) > frame_count:
|
|
gi = min(range(len(groups) - 1), key=lambda i: groups[i + 1][0] - groups[i][1])
|
|
groups[gi][1] = groups[gi + 1][1]
|
|
del groups[gi + 1]
|
|
return [tuple(g) for g in groups]
|
|
|
|
|
|
def _significant_subject_boxes(image, *, min_mass: int = 32) -> list[tuple[int, int, int, int]]:
|
|
"""Merged boxes of components carrying meaningful mass (≥12% of the largest)."""
|
|
comps = _component_boxes(image)
|
|
if not comps:
|
|
return []
|
|
max_mass = max(mass for _box, mass in comps)
|
|
return _merge_related_boxes([box for box, mass in comps if mass >= max(min_mass, max_mass * 0.12)])
|
|
|
|
|
|
def _is_multi_pose_outlier(width: int, height: int, med_w: int, med_h: int) -> bool:
|
|
"""A frame several times wider than the median but not proportionally taller."""
|
|
return width > max(med_w * 3.0, med_w + 96) and height <= med_h * 1.6
|
|
|
|
|
|
def _validate_extracted_frames(frames: list, frame_count: int) -> None:
|
|
"""Reject rows where one "frame" is really multiple poses (normalization would shrink the whole pet)."""
|
|
if len(frames) != frame_count:
|
|
raise ValueError(f"expected {frame_count} frames, got {len(frames)}")
|
|
boxes = []
|
|
for i, frame in enumerate(frames):
|
|
if (bbox := frame.getbbox()) is None:
|
|
raise ValueError(f"frame {i} is empty")
|
|
if len(_significant_subject_boxes(frame)) >= 3:
|
|
raise ValueError(f"frame {i} contains multiple separated subjects")
|
|
boxes.append(bbox)
|
|
if frame_count <= 1:
|
|
return
|
|
med_w, med_h = _median_box_size(boxes)
|
|
for i, (left, top, right, bottom) in enumerate(boxes):
|
|
if _is_multi_pose_outlier(right - left, bottom - top, med_w, med_h):
|
|
raise ValueError(f"frame {i} is a multi-pose width outlier")
|
|
|
|
|
|
def extract_strip_frames(
|
|
strip, frame_count: int, *, chroma_key: tuple[int, int, int] | None = None, method: str = "auto", fit: bool = True
|
|
) -> list:
|
|
"""Turn one generated row strip into *frame_count* frames.
|
|
|
|
Keys out the background, then isolates padded subjects (components, then equal slots). When that fails ``components``
|
|
raises while ``auto`` salvages leniently. *fit* centers each frame into a cell; hatching passes ``fit=False`` so
|
|
:func:`normalize_cells` can register the whole pet with one shared scale.
|
|
"""
|
|
strip = remove_background(_load_rgba(strip), chroma_key=chroma_key)
|
|
frames = _component_crops(strip, frame_count, require_padding=True) or _slot_crops(strip, frame_count, require_padding=True)
|
|
if frames is None:
|
|
if method == "components":
|
|
raise ValueError(f"could not segment {frame_count} padded sprites from strip")
|
|
frames = _component_crops(strip, frame_count, require_padding=False)
|
|
if frames is None:
|
|
frames = _salvage_frames(strip, frame_count)
|
|
_validate_extracted_frames(frames, frame_count)
|
|
return [_fit_to_cell(f) for f in frames] if fit else frames
|
|
|
|
|
|
def _salvage_frames(strip, frame_count: int) -> list:
|
|
"""Lenient last resort: gutter ranges (severing expected gutters if needed), else raw slots."""
|
|
source, ranges = strip, _frame_x_ranges(strip, frame_count)
|
|
if ranges is None:
|
|
source = _sever_expected_gutters(strip, frame_count)
|
|
ranges = _frame_x_ranges(source, frame_count)
|
|
if ranges is None:
|
|
return _slot_crops(source, frame_count, require_padding=False) or []
|
|
w, h = source.size
|
|
pad = max(2, min(16, round((w / max(1, frame_count)) * 0.04)))
|
|
return [_clean_slot(source.crop((max(0, left - pad), 0, min(w, right + pad), h))) for left, right in ranges]
|
|
|
|
|
|
def _column_profile(image) -> list[int]:
|
|
"""Per-column alpha mass — collapse to a 1px-tall strip (fast in C)."""
|
|
return list(image.getchannel("A").resize((image.width, 1), Image.BILINEAR).getdata())
|
|
|
|
|
|
def _best_shift(ref: list[int], prof: list[int], window: int) -> int:
|
|
"""Integer dx that best aligns *prof* onto *ref* (1-D cross-correlation; the body dominates, limbs barely move it)."""
|
|
n = len(ref)
|
|
score = lambda d: sum(ref[x] * prof[x - d] for x in range(max(0, d), min(n, n + d))) # noqa: E731
|
|
return max(range(-window, window + 1), key=score) # ties → smallest dx
|
|
|
|
|
|
def normalize_cells(frames_by_state: dict[str, list], *, pad: int = _NORMALIZE_PAD) -> dict[str, list]:
|
|
"""Register every frame into a 192x208 cell — the deterministic anti-jitter math.
|
|
|
|
Per-frame crop→scale→center jitters. Instead: align each frame's column profile
|
|
to the state's median (locks the body), union-crop through one shared window,
|
|
then scale all states by one global factor keyed to median pose height.
|
|
"""
|
|
out: dict[str, list] = {}
|
|
prepared: dict[str, tuple[list, tuple[int, int, int, int], int]] = {}
|
|
target_w, target_h = CELL_WIDTH - pad, CELL_HEIGHT - pad
|
|
for state, frames in frames_by_state.items():
|
|
rgba = [f.convert("RGBA") for f in frames]
|
|
if not any(f.getbbox() for f in rgba):
|
|
out[state] = [_blank() for _ in frames]
|
|
continue
|
|
# Pad every frame to a common canvas so column profiles are comparable.
|
|
w0, h0 = max(f.width for f in rgba), max(f.height for f in rgba)
|
|
canvas = [f if f.size == (w0, h0) else _place(f, (w0, h0)) for f in rgba]
|
|
profiles = [_column_profile(f) for f in canvas]
|
|
ref = [_median(p[x] for p in profiles) for x in range(w0)]
|
|
window = max(8, w0 // 5)
|
|
aligned = [_place(f, (w0 + 2 * window, h0), (window + _best_shift(ref, prof, window), 0)) for f, prof in zip(canvas, profiles)]
|
|
boxes = [b for b in (a.getbbox() for a in aligned) if b]
|
|
union = (min(b[0] for b in boxes), min(b[1] for b in boxes), max(b[2] for b in boxes), max(b[3] for b in boxes))
|
|
prepared[state] = (aligned, union, _median(b[3] - b[1] for b in boxes))
|
|
if not prepared:
|
|
return out
|
|
|
|
# K is the one global cap keeping the tallest/widest motion envelope (a
|
|
# jump's lift) inside the cell; a still row's union ≈ pose so it fills fully.
|
|
K = target_h
|
|
for _aligned, (left, top, right, bottom), pose_h in prepared.values():
|
|
K = min(K, target_h * pose_h / max(1, bottom - top), target_w * pose_h / max(1, right - left))
|
|
for state, (aligned, box, pose_h) in prepared.items():
|
|
scale = K / max(1, pose_h)
|
|
sw, sh = max(1, round((box[2] - box[0]) * scale)), max(1, round((box[3] - box[1]) * scale))
|
|
offset = round((CELL_WIDTH - sw) / 2), round((CELL_HEIGHT - pad // 2) - sh)
|
|
crops = [a.crop(box) for a in aligned]
|
|
out[state] = [_place(c if c.size == (sw, sh) else c.resize((sw, sh), _NEAREST), (CELL_WIDTH, CELL_HEIGHT), offset) for c in crops]
|
|
return out
|
|
|
|
|
|
def single_frame(image, *, fit: bool = True):
|
|
"""One frame from a standalone image (idle fallback); ``fit=False`` yields the raw keyed sprite for :func:`normalize_cells`."""
|
|
keyed = remove_background(_load_rgba(image))
|
|
return _fit_to_cell(keyed) if fit else _drop_side_bleed(keyed)
|
|
|
|
|
|
def _clear_transparent_rgb(image):
|
|
"""Zero the RGB of fully-transparent pixels (no colored-halo residue)."""
|
|
rgba = image.convert("RGBA")
|
|
data = bytearray(rgba.tobytes())
|
|
for i in range(3, len(data), 4):
|
|
if data[i] == 0:
|
|
data[i - 3 : i] = b"\0\0\0"
|
|
return Image.frombytes("RGBA", rgba.size, bytes(data))
|
|
|
|
|
|
def mirror_frames(frames: list) -> list:
|
|
"""Flip each frame horizontally (``running-left`` from ``running-right``; per-frame, NOT a strip reverse)."""
|
|
return [frame.convert("RGBA").transpose(Image.Transpose.FLIP_LEFT_RIGHT) for frame in frames]
|
|
|
|
|
|
def compose_atlas(frames_by_state: dict[str, list]):
|
|
"""Pack per-state frame lists into the atlas; short states leave trailing cells transparent."""
|
|
atlas = _blank((ATLAS_WIDTH, ATLAS_HEIGHT))
|
|
for state, row, count in ROW_SPECS:
|
|
for col, frame in enumerate((frames_by_state.get(state) or [])[:count]):
|
|
cell = cell if (cell := frame.convert("RGBA")).size == (CELL_WIDTH, CELL_HEIGHT) else _fit_to_cell(cell)
|
|
atlas.alpha_composite(cell, (col * CELL_WIDTH, row * CELL_HEIGHT))
|
|
return _clear_transparent_rgb(atlas)
|
|
|
|
|
|
def validate_atlas(atlas) -> dict:
|
|
"""Geometry/occupancy/transparency checks → ``{ok, width, height, errors, warnings, filled_states}``."""
|
|
atlas = _load_rgba(atlas)
|
|
if atlas.size == (ATLAS_WIDTH, ATLAS_HEIGHT):
|
|
errors, warnings, filled = _check_atlas_cells(atlas)
|
|
else:
|
|
errors, warnings, filled = [f"expected {ATLAS_WIDTH}x{ATLAS_HEIGHT}, got {atlas.width}x{atlas.height}"], [], []
|
|
return {"ok": not errors, "width": atlas.width, "height": atlas.height, "errors": errors, "warnings": warnings, "filled_states": filled}
|
|
|
|
|
|
def _check_atlas_cells(atlas) -> tuple[list[str], list[str], list[str]]:
|
|
"""Occupancy/collapse/residue checks for a correctly-sized atlas → ``(errors, warnings, filled_states)``."""
|
|
errors, warnings, filled_states = [], [], []
|
|
cell_boxes_by_state: dict[str, list[tuple[int, int, int, int]]] = {}
|
|
for state, row, count in ROW_SPECS:
|
|
cells = [atlas.crop((c * CELL_WIDTH, row * CELL_HEIGHT, (c + 1) * CELL_WIDTH, (row + 1) * CELL_HEIGHT)) for c in range(count)]
|
|
if any(sum(cell.getchannel("A").histogram()[1:]) for cell in cells):
|
|
filled_states.append(state)
|
|
cell_boxes_by_state[state] = [bbox for cell in cells if (bbox := cell.getbbox()) is not None]
|
|
else:
|
|
warnings.append(f"state '{state}' has no frames")
|
|
|
|
if not filled_states:
|
|
errors.append("atlas is empty — no state produced any frames")
|
|
# A valid pet must occupy the cell: one bad row can poison global
|
|
# normalization and shrink every state while still passing "non-empty".
|
|
all_boxes = [b for boxes in cell_boxes_by_state.values() for b in boxes]
|
|
global_med_w, global_med_h = _median_box_size(all_boxes) if all_boxes else (0, 0)
|
|
if all_boxes and global_med_h < max(56, round(CELL_HEIGHT * 0.28)):
|
|
errors.append(f"atlas sprites are too small after normalization (median frame height {global_med_h}px)")
|
|
for state, boxes in cell_boxes_by_state.items():
|
|
if len(boxes) <= 1:
|
|
continue
|
|
med_w, med_h = _median_box_size(boxes)
|
|
if _is_multi_pose_outlier(max(r - l for l, _t, r, _b in boxes), max(b - t for _l, t, _r, b in boxes), med_w, med_h):
|
|
errors.append(f"state '{state}' contains a multi-pose frame outlier")
|
|
# Per-state collapse guard: one malformed row must not pass on the
|
|
# strength of the healthy ones.
|
|
collapsed = med_w < max(32, round(global_med_w * 0.42)) or med_h < max(40, round(global_med_h * 0.50))
|
|
if (global_med_w and global_med_h) and collapsed:
|
|
errors.append(f"state '{state}' appears collapsed (median {med_w}x{med_h}px, global median {global_med_w}x{global_med_h}px)")
|
|
data = atlas.tobytes()
|
|
residue = sum(1 for i in range(3, len(data), 4) if data[i] == 0 and any(data[i - 3 : i]))
|
|
if residue:
|
|
errors.append(f"{residue} transparent pixels retain RGB residue")
|
|
return errors, warnings, filled_states
|