atlas.py 29 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621
  1. """Deterministic spritesheet assembly — generated row strips → Hermes atlas.
  2. Image models draw a row of poses well but can't do exact grid geometry, so the
  3. model never owns the layout: it emits one loose strip per state and these ops
  4. slice it into centered transparent 192x208 cells packed into the petdex/Codex
  5. atlas (8 cols x 9 rows, 1536x1872; see ``constants.CODEX_STATE_ROWS``).
  6. Segmentation/fit/residue logic adapted from OpenAI's ``hatch-pet`` skill (Apache-2.0).
  7. """
  8. from __future__ import annotations
  9. import logging
  10. import math
  11. from collections import Counter, deque
  12. from itertools import groupby
  13. from pathlib import Path
  14. from PIL import Image, ImageChops, ImageFilter
  15. from agent.pet.constants import FRAME_H, FRAME_W
  16. logger = logging.getLogger(__name__)
  17. CELL_WIDTH = FRAME_W
  18. CELL_HEIGHT = FRAME_H
  19. # (state, row index, frame count). Order/row indices MUST match
  20. # ``constants.CODEX_STATE_ROWS``; frame counts mirror the petdex ``hatch-pet``
  21. # spec. Rows shorter than 8 leave their tail transparent (renderer trims it).
  22. # ``running`` is the in-place *working* state; ``running-right``/``-left`` walk.
  23. ROW_SPECS: list[tuple[str, int, int]] = [
  24. ("idle", 0, 6), ("running-right", 1, 8), ("running-left", 2, 8), ("waving", 3, 4), ("jumping", 4, 5),
  25. ("failed", 5, 8), ("waiting", 6, 6), ("running", 7, 6), ("review", 8, 6),
  26. ]
  27. ATLAS_WIDTH = max(count for _, _, count in ROW_SPECS) * CELL_WIDTH
  28. ATLAS_HEIGHT = len(ROW_SPECS) * CELL_HEIGHT
  29. _ALPHA_FLOOR = 16 # alpha at/below which a pixel is "background"
  30. _CELL_PAD = 10 # padding kept around a fitted sprite
  31. _NORMALIZE_PAD = 14 # normalized cells fill like real petdex pets (~5px from the edges)
  32. _SIDE_LOBE_RATIO = 0.18 # adjacent-pose bleed is a small lobe; sizeable lobes (wide poses) survive
  33. _NEIGHBOURS = ((1, 0), (-1, 0), (0, 1), (0, -1))
  34. _NEAREST = Image.Resampling.NEAREST # interpolating resamples blur hard pixel-art edges
  35. def _median(values) -> int:
  36. ordered = sorted(values)
  37. return ordered[len(ordered) // 2]
  38. def _median_box_size(boxes) -> tuple[int, int]:
  39. """``(median width, median height)`` of ``(l, t, r, b)`` *boxes*, each at least 1."""
  40. 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))
  41. def _blank(size=(CELL_WIDTH, CELL_HEIGHT)):
  42. return Image.new("RGBA", size, (0, 0, 0, 0))
  43. def _place(sprite, size: tuple[int, int], offset: tuple[int, int] = (0, 0)):
  44. """*sprite* alpha-composited at *offset* onto a new transparent canvas of *size*."""
  45. canvas = _blank(size)
  46. canvas.alpha_composite(sprite, offset)
  47. return canvas
  48. def _clear_region(image, box: tuple[int, int, int, int]) -> None:
  49. """Make the ``(left, top, right, bottom)`` region of *image* fully transparent, in place."""
  50. image.paste(_blank((box[2] - box[0], box[3] - box[1])), (box[0], box[1]))
  51. def _load_rgba(image):
  52. """Open a path (or take an image) as RGBA."""
  53. if isinstance(image, (str, Path)):
  54. with Image.open(image) as opened:
  55. return opened.convert("RGBA")
  56. return image.convert("RGBA")
  57. def _flood(w: int, h: int, visited: bytearray, seeds, accept) -> list[tuple[int, int]]:
  58. """4-connected BFS from *seeds* over pixels passing *accept*; returns the visited pixels."""
  59. queue = deque(seeds)
  60. pixels: list[tuple[int, int]] = []
  61. while queue:
  62. x, y = queue.popleft()
  63. pixels.append((x, y))
  64. for dx, dy in _NEIGHBOURS:
  65. nx, ny = x + dx, y + dy
  66. if 0 <= nx < w and 0 <= ny < h and not visited[ny * w + nx]:
  67. visited[ny * w + nx] = 1
  68. if accept(nx, ny):
  69. queue.append((nx, ny))
  70. return pixels
  71. def _border_flood(w: int, h: int, visited: bytearray, accept) -> list[tuple[int, int]]:
  72. """Flood from every border pixel passing *accept* (edge-connected region only)."""
  73. 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)]
  74. seeds: list[tuple[int, int]] = []
  75. for x, y in border: # corners appear twice in ``border``; the visited mark dedupes them
  76. if not visited[y * w + x] and accept(x, y):
  77. visited[y * w + x] = 1
  78. seeds.append((x, y))
  79. return _flood(w, h, visited, seeds, accept)
  80. def _unvisited_components(w: int, h: int, visited: bytearray, accept):
  81. """Yield each 4-connected component of not-yet-visited pixels passing *accept*, in scan order."""
  82. for start in range(w * h):
  83. if visited[start]:
  84. continue
  85. visited[start] = 1
  86. x, y = start % w, start // w
  87. if accept(x, y):
  88. yield _flood(w, h, visited, [(x, y)], accept)
  89. def _near_key_mask(image, key: tuple[int, int, int], tol: int = 48):
  90. """``L`` mask, 255 where a pixel is within *tol* per-channel of *key*.
  91. Tight on purpose: marks only near-pure backdrop so trapped chroma pockets seed the flood while chroma-tinted character pixels stay outside it.
  92. """
  93. 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))
  94. return ImageChops.darker(ImageChops.darker(r, g), b)
  95. def _remove_masked(rgba, mask):
  96. """Clear the pixels *mask* (``L``, 255 = remove) selects, then erode alpha by 1px (3x3 min).
  97. The erosion drops the antialiased key/sprite blend ring (too far from the key to match); the sprite's thick outline keeps the silhouette.
  98. """
  99. out = Image.composite(_blank(rgba.size), rgba, mask)
  100. out.putalpha(out.getchannel("A").filter(ImageFilter.MinFilter(3)))
  101. return out
  102. def remove_background(image, *, chroma_key: tuple[int, int, int] | None = None, threshold: float = 90.0):
  103. """Return *image* (RGBA) with its flat background keyed out to transparent.
  104. Strips already carrying a real alpha background (>5% of pixels at/below the floor)
  105. are left alone (holes repaired). Otherwise key out *chroma_key* (or the most common
  106. opaque corner color) from the border inward: a global color match punched holes
  107. wherever an interior highlight matched the backdrop.
  108. """
  109. rgba = image.convert("RGBA")
  110. w, h = rgba.size
  111. alpha = rgba.getchannel("A")
  112. if alpha.getextrema()[0] <= _ALPHA_FLOOR and sum(alpha.histogram()[: _ALPHA_FLOOR + 1]) > w * h * 0.05:
  113. return _repair_internal_alpha_holes(rgba)
  114. px = rgba.load()
  115. if not (key := chroma_key):
  116. 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)
  117. key = corners.most_common(1)[0][0] if corners else (0, 255, 0)
  118. # Fast path for saturated chroma keys (our prompts use hot magenta): C-level
  119. # channel ops clear border backdrop and enclosed pockets alike, no Python flood.
  120. if max(key) - min(key) >= 120:
  121. opaque = rgba.getchannel("A").point(lambda a: 255 if a > _ALPHA_FLOOR else 0)
  122. return _remove_masked(rgba, ImageChops.darker(_near_key_mask(rgba, key), opaque))
  123. def _is_bg(x: int, y: int) -> bool:
  124. r, g, b, a = px[x, y]
  125. return a > _ALPHA_FLOOR and math.sqrt((r - key[0]) ** 2 + (g - key[1]) ** 2 + (b - key[2]) ** 2) <= threshold
  126. # Border-only flood on purpose: a desaturated near-white/gray key must never
  127. # seed from the character's interior (that is the hole-punching case). Mark
  128. # removals in a flat mask and composite once in C — per-pixel writes stalled the gateway.
  129. remove = bytearray(w * h)
  130. for x, y in _border_flood(w, h, bytearray(w * h), _is_bg):
  131. remove[y * w + x] = 1
  132. return _remove_masked(rgba, Image.frombytes("L", (w, h), bytes(remove)).point(lambda v: 255 if v else 0))
  133. def _repair_internal_alpha_holes(image):
  134. """Fill transparent islands fully enclosed by opaque sprite pixels.
  135. Some providers return "transparent" PNGs with swiss-cheese alpha inside the character; enclosed holes take the average opaque-neighbour color.
  136. """
  137. rgba = image.convert("RGBA")
  138. w, h = rgba.size
  139. px = rgba.load()
  140. visited = bytearray(w * h)
  141. _is_transparent = lambda x, y: px[x, y][3] <= _ALPHA_FLOOR
  142. _border_flood(w, h, visited, _is_transparent) # edge-connected transparency = background
  143. for hole in _unvisited_components(w, h, visited, _is_transparent):
  144. seen = set(hole)
  145. samples = [
  146. px[nx, ny][:3]
  147. for x, y in hole
  148. for dx, dy in _NEIGHBOURS
  149. 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
  150. ]
  151. color = (*(round(sum(c[i] for c in samples) / len(samples)) for i in range(3)), 255) if samples else (0, 0, 0, 255)
  152. for hx, hy in hole:
  153. px[hx, hy] = color
  154. return rgba
  155. def _fit_to_cell(image):
  156. """Crop to content, scale to fit a padded cell, and center on transparent."""
  157. image = _drop_side_bleed(image)
  158. if (bbox := image.getbbox()) is None:
  159. return _blank()
  160. sprite = image.crop(bbox)
  161. scale = min((CELL_WIDTH - _CELL_PAD) / sprite.width, (CELL_HEIGHT - _CELL_PAD) / sprite.height, 1.0)
  162. if scale != 1.0:
  163. sprite = sprite.resize((max(1, round(sprite.width * scale)), max(1, round(sprite.height * scale))), _NEAREST)
  164. return _place(sprite, (CELL_WIDTH, CELL_HEIGHT), ((CELL_WIDTH - sprite.width) // 2, (CELL_HEIGHT - sprite.height) // 2))
  165. def _drop_side_bleed(image):
  166. """Remove tiny separated left/right lobes (neighbour-pose slivers) before fitting.
  167. 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).
  168. """
  169. rgba = image.convert("RGBA")
  170. w, h = rgba.size
  171. runs = _content_runs(_column_profile(rgba))
  172. keep = [run for run, m in runs if m >= max(m for _run, m in runs) * _SIDE_LOBE_RATIO] if runs else []
  173. if len(runs) < 2 or len(keep) == len(runs):
  174. return rgba
  175. rgba = rgba.copy()
  176. prev = 0
  177. for left, right in [*keep, (w, w)]: # (w, w) sentinel clears the trailing gap
  178. if left > prev:
  179. _clear_region(rgba, (prev, 0, left, h))
  180. prev = right
  181. return rgba
  182. def _thin_groups(indices: list[int]) -> list[tuple[int, int]]:
  183. """``(start, end)`` for each run of consecutive *indices* at most 4 long."""
  184. runs = ([i for _, i in g] for _k, g in groupby(enumerate(indices), key=lambda p: p[1] - p[0]))
  185. return [(run[0], run[-1] + 1) for run in runs if len(run) <= 4]
  186. def _erase_long_axis_lines(image):
  187. """Remove thin slot-spanning guide/floor/divider lines (they survive keying and bridge clean poses)."""
  188. rgba = image.convert("RGBA").copy()
  189. w, h = rgba.size
  190. alpha = rgba.getchannel("A")
  191. opaque = [[alpha.getpixel((x, y)) > _ALPHA_FLOOR for x in range(w)] for y in range(h)]
  192. for top, bottom in _thin_groups([y for y in range(h) if sum(opaque[y]) >= w * 0.85]):
  193. _clear_region(rgba, (0, top, w, bottom))
  194. for left, right in _thin_groups([x for x in range(w) if sum(row[x] for row in opaque) >= h * 0.85]):
  195. _clear_region(rgba, (left, 0, right, h))
  196. return rgba
  197. def _component_boxes(image) -> list[tuple[tuple[int, int, int, int], int]]:
  198. """Connected opaque components as ``[(bbox, mass)]``."""
  199. rgba = image.convert("RGBA")
  200. if (bbox := rgba.getbbox()) is None:
  201. return []
  202. l0, t0, r0, b0 = bbox
  203. w, h = r0 - l0, b0 - t0
  204. alpha = rgba.getchannel("A").load()
  205. components = _unvisited_components(w, h, bytearray(w * h), lambda x, y: alpha[l0 + x, t0 + y] > _ALPHA_FLOOR)
  206. 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)]
  207. def _isolate_slot_subject(image):
  208. """Keep the slot's real subject; drop detached effects/noise."""
  209. rgba = _erase_long_axis_lines(image)
  210. comps = _component_boxes(rgba)
  211. if not comps:
  212. return rgba
  213. main_box, main_mass = max(comps, key=lambda item: item[1])
  214. ml, _mt, mr, _mb = main_box
  215. mw = max(1, mr - ml)
  216. out = _blank(rgba.size)
  217. for box, mass in comps:
  218. # Keep attached-looking accessories (halos); drop sparkles/tears/noise.
  219. left, _top, right, _bottom = box
  220. overlap = max(0, min(right, mr) - max(left, ml))
  221. near_main = (ml - mw * 0.25) <= (left + right) / 2 <= (mr + mw * 0.25)
  222. if box == main_box or (mass >= max(24, main_mass * 0.035) and (overlap >= mw * 0.3 or near_main)):
  223. out.alpha_composite(rgba.crop(box), (box[0], box[1]))
  224. return out
  225. def _has_margin(size: tuple[int, int], box: tuple[int, int, int, int], fx: float, fy: float) -> bool:
  226. """True when *box* leaves empty room on all four edges of an image of *size* (≥4px, ≤12/16px)."""
  227. w, h = size
  228. left, top, right, bottom = box
  229. min_x, min_y = max(4, min(12, round(w * fx))), max(4, min(16, round(h * fy)))
  230. return left >= min_x and top >= min_y and w - right >= min_x and h - bottom >= min_y
  231. def _group_component_rows(boxes: list[tuple[int, int, int, int]]) -> list[list[tuple[int, int, int, int]]]:
  232. """Group component boxes into visual rows, then sort left→right."""
  233. if not boxes:
  234. return []
  235. cy = lambda b: (b[1] + b[3]) / 2
  236. row_tol = max(12, _median_box_size(boxes)[1] * 0.55)
  237. rows: list[list[tuple[int, int, int, int]]] = []
  238. centers: list[float] = []
  239. for box in sorted(boxes, key=cy):
  240. i = next((i for i, center in enumerate(centers) if abs(cy(box) - center) <= row_tol), None)
  241. if i is None:
  242. rows.append([box])
  243. centers.append(cy(box))
  244. else:
  245. rows[i].append(box)
  246. centers[i] = sum(cy(b) for b in rows[i]) / len(rows[i])
  247. ordered = [row for _center, row in sorted(zip(centers, rows, strict=False), key=lambda item: item[0])]
  248. for row in ordered:
  249. row.sort(key=lambda b: (b[0] + b[2]) / 2)
  250. return ordered
  251. def _merge_related_boxes(boxes: list[tuple[int, int, int, int]]) -> list[tuple[int, int, int, int]]:
  252. """Merge disconnected parts of one subject (capes, tails, props) on the same row.
  253. Merges when vertical spans overlap and the horizontal gap is tiny relative to component size; never bridges the larger gaps between separate poses.
  254. """
  255. def related(a, b) -> bool:
  256. (al, at, ar, ab), (bl, bt, br, bb) = a, b
  257. v_overlap, min_h = max(0, min(ab, bb) - max(at, bt)), max(1, min(ab - at, bb - bt))
  258. gap, min_w = max(0, max(al, bl) - min(ar, br)), max(1, min(ar - al, br - bl))
  259. return v_overlap >= min_h * 0.45 and gap <= max(14, min_w * 0.22)
  260. boxes = list(boxes)
  261. changed = True
  262. while changed:
  263. changed = False
  264. merged: list[tuple[int, int, int, int]] = []
  265. used = [False] * len(boxes)
  266. for i, a in enumerate(boxes):
  267. if used[i]:
  268. continue
  269. used[i] = True
  270. for j, b in enumerate(boxes[i + 1 :], i + 1):
  271. if not used[j] and related(a, b):
  272. a = (min(a[0], b[0]), min(a[1], b[1]), max(a[2], b[2]), max(a[3], b[3]))
  273. used[j] = changed = True
  274. merged.append(a)
  275. boxes = merged
  276. return boxes
  277. def _component_crops(strip, frame_count: int, *, require_padding: bool = False) -> list | None:
  278. """Frames as connected subjects in reading order (robust to 2D grids); ``None`` when *frame_count* can't be met."""
  279. def attempt(source) -> list | None:
  280. subjects = _significant_subject_boxes(source, min_mass=64)
  281. if len(subjects) < frame_count:
  282. return None
  283. rows = _group_component_rows(subjects)
  284. ordered = [box for row in rows for box in row][:frame_count] # rows hold every subject, so exactly frame_count
  285. if require_padding and not all(_has_margin(source.size, box, 0.01, 0.015) for box in ordered):
  286. return None
  287. multirow = len(rows) > 1
  288. frames = []
  289. for left, top, right, bottom in ordered:
  290. pad_x, pad_y = max(8, round((right - left) * 0.08)), max(8, round((bottom - top) * 0.08))
  291. # One-row strips keep full height so vertical motion survives; grids pad the box.
  292. cl, cr = (0, source.width) if frame_count == 1 else (max(0, left - pad_x), min(source.width, right + pad_x))
  293. ct, cb = (max(0, top - pad_y), min(source.height, bottom + pad_y)) if multirow else (0, source.height)
  294. # No second component filter here: capes/tails can be legitimate
  295. # disconnected lobes inside the chosen subject box.
  296. frames.append(_place(source.crop((left, top, right, bottom)), (cr - cl, cb - ct), (left - cl, top - ct)))
  297. return frames
  298. return attempt(strip) or attempt(_erase_long_axis_lines(strip))
  299. def _sever_expected_gutters(strip, frame_count: int):
  300. """Cut narrow transparent bands at expected frame boundaries (shared shadows/1px bridges merge poses)."""
  301. if frame_count <= 1:
  302. return strip
  303. out = strip.copy()
  304. alpha = out.getchannel("A") # zero alpha only; RGB is left untouched
  305. slot = out.width / frame_count
  306. half = max(3, min(18, round(slot * 0.06)))
  307. for x in (round(i * slot) for i in range(1, frame_count)):
  308. alpha.paste(0, (max(0, x - half), 0, min(out.width, x + half + 1), out.height))
  309. out.putalpha(alpha)
  310. return out
  311. def _clean_slot(image):
  312. return _drop_side_bleed(_isolate_slot_subject(image))
  313. def _slot_crops(strip, frame_count: int, *, require_padding: bool = False) -> list | None:
  314. """Slice *strip* into *frame_count* equal, independently cleaned columns (one shared coordinate frame)."""
  315. w, h = strip.size
  316. frames = [_clean_slot(strip.crop((round(i * w / frame_count), 0, round((i + 1) * w / frame_count), h))) for i in range(frame_count)]
  317. 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):
  318. return None
  319. return frames
  320. def _content_runs(profile: list[int], *, threshold: int = 2) -> list[tuple[tuple[int, int], int]]:
  321. """``[((left, right), mass)]`` column spans whose alpha exceeds *threshold* (candidate frames)."""
  322. runs: list[tuple[tuple[int, int], int]] = []
  323. start: int | None = None
  324. for x, v in enumerate(list(profile) + [0]):
  325. if v > threshold:
  326. if start is None:
  327. start = x
  328. elif start is not None:
  329. runs.append(((start, x), sum(profile[start:x])))
  330. start = None
  331. return runs
  332. def _frame_x_ranges(strip, frame_count: int) -> list[tuple[int, int]] | None:
  333. """Per-frame ``(left, right)`` column ranges from the row's empty gutters.
  334. 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``.
  335. """
  336. runs = _content_runs(_column_profile(strip))
  337. groups = [[l, r] for (l, r), m in runs if m >= max(m for _run, m in runs) * 0.02] if runs else []
  338. if len(groups) < frame_count:
  339. return None
  340. while len(groups) > frame_count:
  341. gi = min(range(len(groups) - 1), key=lambda i: groups[i + 1][0] - groups[i][1])
  342. groups[gi][1] = groups[gi + 1][1]
  343. del groups[gi + 1]
  344. return [tuple(g) for g in groups]
  345. def _significant_subject_boxes(image, *, min_mass: int = 32) -> list[tuple[int, int, int, int]]:
  346. """Merged boxes of components carrying meaningful mass (≥12% of the largest)."""
  347. comps = _component_boxes(image)
  348. if not comps:
  349. return []
  350. max_mass = max(mass for _box, mass in comps)
  351. return _merge_related_boxes([box for box, mass in comps if mass >= max(min_mass, max_mass * 0.12)])
  352. def _is_multi_pose_outlier(width: int, height: int, med_w: int, med_h: int) -> bool:
  353. """A frame several times wider than the median but not proportionally taller."""
  354. return width > max(med_w * 3.0, med_w + 96) and height <= med_h * 1.6
  355. def _validate_extracted_frames(frames: list, frame_count: int) -> None:
  356. """Reject rows where one "frame" is really multiple poses (normalization would shrink the whole pet)."""
  357. if len(frames) != frame_count:
  358. raise ValueError(f"expected {frame_count} frames, got {len(frames)}")
  359. boxes = []
  360. for i, frame in enumerate(frames):
  361. if (bbox := frame.getbbox()) is None:
  362. raise ValueError(f"frame {i} is empty")
  363. if len(_significant_subject_boxes(frame)) >= 3:
  364. raise ValueError(f"frame {i} contains multiple separated subjects")
  365. boxes.append(bbox)
  366. if frame_count <= 1:
  367. return
  368. med_w, med_h = _median_box_size(boxes)
  369. for i, (left, top, right, bottom) in enumerate(boxes):
  370. if _is_multi_pose_outlier(right - left, bottom - top, med_w, med_h):
  371. raise ValueError(f"frame {i} is a multi-pose width outlier")
  372. def extract_strip_frames(
  373. strip, frame_count: int, *, chroma_key: tuple[int, int, int] | None = None, method: str = "auto", fit: bool = True
  374. ) -> list:
  375. """Turn one generated row strip into *frame_count* frames.
  376. Keys out the background, then isolates padded subjects (components, then equal slots). When that fails ``components``
  377. raises while ``auto`` salvages leniently. *fit* centers each frame into a cell; hatching passes ``fit=False`` so
  378. :func:`normalize_cells` can register the whole pet with one shared scale.
  379. """
  380. strip = remove_background(_load_rgba(strip), chroma_key=chroma_key)
  381. frames = _component_crops(strip, frame_count, require_padding=True) or _slot_crops(strip, frame_count, require_padding=True)
  382. if frames is None:
  383. if method == "components":
  384. raise ValueError(f"could not segment {frame_count} padded sprites from strip")
  385. frames = _component_crops(strip, frame_count, require_padding=False)
  386. if frames is None:
  387. frames = _salvage_frames(strip, frame_count)
  388. _validate_extracted_frames(frames, frame_count)
  389. return [_fit_to_cell(f) for f in frames] if fit else frames
  390. def _salvage_frames(strip, frame_count: int) -> list:
  391. """Lenient last resort: gutter ranges (severing expected gutters if needed), else raw slots."""
  392. source, ranges = strip, _frame_x_ranges(strip, frame_count)
  393. if ranges is None:
  394. source = _sever_expected_gutters(strip, frame_count)
  395. ranges = _frame_x_ranges(source, frame_count)
  396. if ranges is None:
  397. return _slot_crops(source, frame_count, require_padding=False) or []
  398. w, h = source.size
  399. pad = max(2, min(16, round((w / max(1, frame_count)) * 0.04)))
  400. return [_clean_slot(source.crop((max(0, left - pad), 0, min(w, right + pad), h))) for left, right in ranges]
  401. def _column_profile(image) -> list[int]:
  402. """Per-column alpha mass — collapse to a 1px-tall strip (fast in C)."""
  403. return list(image.getchannel("A").resize((image.width, 1), Image.BILINEAR).getdata())
  404. def _best_shift(ref: list[int], prof: list[int], window: int) -> int:
  405. """Integer dx that best aligns *prof* onto *ref* (1-D cross-correlation; the body dominates, limbs barely move it)."""
  406. n = len(ref)
  407. score = lambda d: sum(ref[x] * prof[x - d] for x in range(max(0, d), min(n, n + d)))
  408. return max(range(-window, window + 1), key=score) # ties → smallest dx
  409. def normalize_cells(frames_by_state: dict[str, list], *, pad: int = _NORMALIZE_PAD) -> dict[str, list]:
  410. """Register every frame into a 192x208 cell — the deterministic anti-jitter math.
  411. Per-frame crop→scale→center jitters. Instead: align each frame's column profile
  412. to the state's median (locks the body), union-crop through one shared window,
  413. then scale all states by one global factor keyed to median pose height.
  414. """
  415. out: dict[str, list] = {}
  416. prepared: dict[str, tuple[list, tuple[int, int, int, int], int]] = {}
  417. target_w, target_h = CELL_WIDTH - pad, CELL_HEIGHT - pad
  418. for state, frames in frames_by_state.items():
  419. rgba = [f.convert("RGBA") for f in frames]
  420. if not any(f.getbbox() for f in rgba):
  421. out[state] = [_blank() for _ in frames]
  422. continue
  423. # Pad every frame to a common canvas so column profiles are comparable.
  424. w0, h0 = max(f.width for f in rgba), max(f.height for f in rgba)
  425. canvas = [f if f.size == (w0, h0) else _place(f, (w0, h0)) for f in rgba]
  426. profiles = [_column_profile(f) for f in canvas]
  427. ref = [_median(p[x] for p in profiles) for x in range(w0)]
  428. window = max(8, w0 // 5)
  429. aligned = [_place(f, (w0 + 2 * window, h0), (window + _best_shift(ref, prof, window), 0)) for f, prof in zip(canvas, profiles)]
  430. boxes = [b for b in (a.getbbox() for a in aligned) if b]
  431. 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))
  432. prepared[state] = (aligned, union, _median(b[3] - b[1] for b in boxes))
  433. if not prepared:
  434. return out
  435. # K is the one global cap keeping the tallest/widest motion envelope (a
  436. # jump's lift) inside the cell; a still row's union ≈ pose so it fills fully.
  437. K = target_h
  438. for _aligned, (left, top, right, bottom), pose_h in prepared.values():
  439. K = min(K, target_h * pose_h / max(1, bottom - top), target_w * pose_h / max(1, right - left))
  440. for state, (aligned, box, pose_h) in prepared.items():
  441. scale = K / max(1, pose_h)
  442. sw, sh = max(1, round((box[2] - box[0]) * scale)), max(1, round((box[3] - box[1]) * scale))
  443. offset = round((CELL_WIDTH - sw) / 2), round((CELL_HEIGHT - pad // 2) - sh)
  444. crops = [a.crop(box) for a in aligned]
  445. out[state] = [_place(c if c.size == (sw, sh) else c.resize((sw, sh), _NEAREST), (CELL_WIDTH, CELL_HEIGHT), offset) for c in crops]
  446. return out
  447. def single_frame(image, *, fit: bool = True):
  448. """One frame from a standalone image (idle fallback); ``fit=False`` yields the raw keyed sprite for :func:`normalize_cells`."""
  449. keyed = remove_background(_load_rgba(image))
  450. return _fit_to_cell(keyed) if fit else _drop_side_bleed(keyed)
  451. def _clear_transparent_rgb(image):
  452. """Zero the RGB of fully-transparent pixels (no colored-halo residue)."""
  453. rgba = image.convert("RGBA")
  454. data = bytearray(rgba.tobytes())
  455. for i in range(3, len(data), 4):
  456. if data[i] == 0:
  457. data[i - 3 : i] = b"\0\0\0"
  458. return Image.frombytes("RGBA", rgba.size, bytes(data))
  459. def mirror_frames(frames: list) -> list:
  460. """Flip each frame horizontally (``running-left`` from ``running-right``; per-frame, NOT a strip reverse)."""
  461. return [frame.convert("RGBA").transpose(Image.Transpose.FLIP_LEFT_RIGHT) for frame in frames]
  462. def compose_atlas(frames_by_state: dict[str, list]):
  463. """Pack per-state frame lists into the atlas; short states leave trailing cells transparent."""
  464. atlas = _blank((ATLAS_WIDTH, ATLAS_HEIGHT))
  465. for state, row, count in ROW_SPECS:
  466. for col, frame in enumerate((frames_by_state.get(state) or [])[:count]):
  467. cell = cell if (cell := frame.convert("RGBA")).size == (CELL_WIDTH, CELL_HEIGHT) else _fit_to_cell(cell)
  468. atlas.alpha_composite(cell, (col * CELL_WIDTH, row * CELL_HEIGHT))
  469. return _clear_transparent_rgb(atlas)
  470. def validate_atlas(atlas) -> dict:
  471. """Geometry/occupancy/transparency checks → ``{ok, width, height, errors, warnings, filled_states}``."""
  472. atlas = _load_rgba(atlas)
  473. if atlas.size == (ATLAS_WIDTH, ATLAS_HEIGHT):
  474. errors, warnings, filled = _check_atlas_cells(atlas)
  475. else:
  476. errors, warnings, filled = [f"expected {ATLAS_WIDTH}x{ATLAS_HEIGHT}, got {atlas.width}x{atlas.height}"], [], []
  477. return {"ok": not errors, "width": atlas.width, "height": atlas.height, "errors": errors, "warnings": warnings, "filled_states": filled}
  478. def _check_atlas_cells(atlas) -> tuple[list[str], list[str], list[str]]:
  479. """Occupancy/collapse/residue checks for a correctly-sized atlas → ``(errors, warnings, filled_states)``."""
  480. errors, warnings, filled_states = [], [], []
  481. cell_boxes_by_state: dict[str, list[tuple[int, int, int, int]]] = {}
  482. for state, row, count in ROW_SPECS:
  483. cells = [atlas.crop((c * CELL_WIDTH, row * CELL_HEIGHT, (c + 1) * CELL_WIDTH, (row + 1) * CELL_HEIGHT)) for c in range(count)]
  484. if any(sum(cell.getchannel("A").histogram()[1:]) for cell in cells):
  485. filled_states.append(state)
  486. cell_boxes_by_state[state] = [bbox for cell in cells if (bbox := cell.getbbox()) is not None]
  487. else:
  488. warnings.append(f"state '{state}' has no frames")
  489. if not filled_states:
  490. errors.append("atlas is empty — no state produced any frames")
  491. # A valid pet must occupy the cell: one bad row can poison global
  492. # normalization and shrink every state while still passing "non-empty".
  493. all_boxes = [b for boxes in cell_boxes_by_state.values() for b in boxes]
  494. global_med_w, global_med_h = _median_box_size(all_boxes) if all_boxes else (0, 0)
  495. if all_boxes and global_med_h < max(56, round(CELL_HEIGHT * 0.28)):
  496. errors.append(f"atlas sprites are too small after normalization (median frame height {global_med_h}px)")
  497. for state, boxes in cell_boxes_by_state.items():
  498. if len(boxes) <= 1:
  499. continue
  500. med_w, med_h = _median_box_size(boxes)
  501. 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):
  502. errors.append(f"state '{state}' contains a multi-pose frame outlier")
  503. # Per-state collapse guard: one malformed row must not pass on the
  504. # strength of the healthy ones.
  505. collapsed = med_w < max(32, round(global_med_w * 0.42)) or med_h < max(40, round(global_med_h * 0.50))
  506. if (global_med_w and global_med_h) and collapsed:
  507. errors.append(f"state '{state}' appears collapsed (median {med_w}x{med_h}px, global median {global_med_w}x{global_med_h}px)")
  508. data = atlas.tobytes()
  509. residue = sum(1 for i in range(3, len(data), 4) if data[i] == 0 and any(data[i - 3 : i]))
  510. if residue:
  511. errors.append(f"{residue} transparent pixels retain RGB residue")
  512. return errors, warnings, filled_states