Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.
fix(handed): a far arm's item shows when the arm swings forward; a walk says in place and its view once
Soohong Kimf89910137f74
diff --git a/sprite_gen/gen/handedness.py b/sprite_gen/gen/handedness.pyindex 4ed453d..83af6c3 100644--- a/sprite_gen/gen/handedness.py+++ b/sprite_gen/gen/handedness.py@@ -21,6 +21,12 @@ views turn to `facing`; front and back have none):A view turned to the right shows the character's right side; turned to the left, its left. Theown right side is the mirror of every row. A side view puts both arms over the middle of the body,so it has no picture side, only near and far.++The far side of a side view is hidden behind the body, except for what swings out from behind it:+an arm or a leg (`limb`). A walking character's far arm comes forward of the body with every step,+and what it wears shows then. An item on a far limb is therefore drawn and filmed as showing+whenever that limb is out in front of the body, and the near limb stays bare. Said as hidden, and+never named in the clip, a watch on the far wrist was in no frame of a walk at all (2.22.0)."""from __future__ import annotations@@ -31,6 +37,13 @@ VIEWS = ("side", "front", "back", "front_diagonal", "back_diagonal")# Views turned toward a side of the picture: each is drawn facing right or left.LATERAL_VIEWS = frozenset({"side", "front_diagonal", "back_diagonal"})SIDES = ("left", "right")+# Body parts on a limb that swings with a step: in a side view the far one comes out in front of the body.+ARM_WORDS = frozenset({"wrist", "hand", "arm", "forearm", "elbow", "palm", "finger", "fingers", "thumb", "knuckles"})+LEG_WORDS = frozenset({"ankle", "foot", "leg", "knee", "shin", "calf", "thigh", "heel", "toes"})+# A side walk or run with an item on an arm: the arms are said to swing, never held still. An arm held at+# the body keeps the item off the other arm but walks stiffly, and a far arm that does not swing never+# brings its item into view.+ARMS_SWING_TEXT = "Both arms swing back and forth with each step, opposite to the legs."SPEC_FORM = "'<item>=<left|right> [body part]', e.g. 'the black smartwatch=left wrist'"@@ -51,6 +64,13 @@ class Handed:return "right" if self.side == "left" else "left"+def limb(part: str) -> str | None:+ """"arm" or "leg" when `part` is on a limb that swings with a step ("wrist", "upper arm", "ankle"), else None+ (a side of the head, a shoulder, a hip: on the far side these stay behind the body)."""+ words = set(part.lower().split())+ return "arm" if words & ARM_WORDS else "leg" if words & LEG_WORDS else None++def parse(spec: str) -> Handed:"""'<item>=<left|right> [body part]' -> Handed. The side is the character's own, not the picture's."""if "=" not in spec:@@ -89,15 +109,27 @@ def placement(side: str, view: str, facing: str | None = None) -> dict[str, strreturn {"picture": picture, "depth": depth}-def _view_clause(h: Handed, view: str, facing: str | None) -> str:+def _none(h: Handed, items: list[Handed]) -> str:+ """How the other side's part is said to lack `h`'s item: "none", or "none of it" when another item is on+ that part, so the two sentences are not read against each other."""+ return "none of it" if any(o is not h and (o.side, o.part) == (h.other, h.part) for o in items) else "none"+++def _view_clause(h: Handed, view: str, facing: str | None, items: list[Handed]) -> str:at = placement(h.side, view, facing)+ none = _none(h, items)if view == "side":if at["depth"] == "near":return (f"Facing {facing}, the character's own {h.side} side is toward the viewer: its {h.where()} is the near "f"one, in front of the body, and {h.item} on it shows clearly.")- return (f"Facing {facing}, the character's own {h.other} side is toward the viewer: the near {h.part or 'side'}, in "- f"front of the body, is its own {h.where(h.other)}, with none; the {h.where()} with {h.item} is on the far "- f"side, behind the body, so {h.item} is hidden or at most a sliver of it shows.")+ lead = (f"Facing {facing}, the character's own {h.other} side is toward the viewer: the near {h.part or 'side'}, in "+ f"front of the body, is its own {h.where(h.other)}, with {none}; the {h.where()} with {h.item} is on the far ")+ swings = limb(h.part)+ if swings:+ # the far limb is in view whenever it is forward of the body, and its item with it+ return (f"{lead}{swings}. Wherever the far {swings} reaches out in front of the body, clear of its outline, "+ f"{h.item} shows whole on it; where the body covers that {swings}, it is hidden.")+ return f"{lead}side, behind the body, so {h.item} is hidden or at most a sliver of it shows."lead = {"front": "Seen from the front", "back": "Seen from behind"}.get(view, "In this view")if at["depth"] is None:return (f"{lead}, the character's own {h.where()} is the one at the {at['picture']} of the picture, so {h.item} is "@@ -105,41 +137,85 @@ def _view_clause(h: Handed, view: str, facing: str | None) -> str:near = "nearer the viewer and fully visible" if at["depth"] == "near" else "on the far side of the body"other_picture = "left" if at["picture"] == "right" else "right"return (f"{lead}, the character's own {h.where()} is the one at the {at['picture']} of the picture, {near}, and it has "- f"{h.item}; the {h.part or 'side'} at the {other_picture} of the picture is its own {h.where(h.other)}, with none.")+ f"{h.item}; the {h.part or 'side'} at the {other_picture} of the picture is its own {h.where(h.other)}, with {none}.")++def _names(group: list[Handed]) -> str:+ names = [h.item for h in group]+ text = names[0] if len(names) == 1 else ", ".join(names[:-1]) + " and " + names[-1]+ return text[0].upper() + text[1:]-def _clip_clause(h: Handed, view: str, facing: str | None) -> str:- """One item in a clip. The clip starts from a still already drawn with the item in place, so the sentence- anchors to the image and says the item positively, once, where it shows. Where it is hidden (the far side of- a side view) the item is not named at all, only that the near part stays bare as drawn: a clip prompt that- names a hidden item, and lists what the near part must not wear, draws it on the near part."""++def _clip_clause(group: list[Handed], view: str, facing: str | None, *, gait: bool, other_bare: bool) -> str:+ """The items on one part of one side (`group`), in a clip. The clip starts from a still already drawn with+ them in place, so the sentence anchors to the image and says them positively, once, where they show.++ A side view's far limb in a walk or run (`gait`) shows what it wears each time it swings forward, and the+ sentence says so: left unnamed, a watch on the far wrist was in no frame of the walk. The near limb is said+ bare (`other_bare`: nothing of the caller's is on it), never as a list of what it must not wear — a clip+ prompt that lists that draws it there. Where nothing brings the far side into view (a part that does not+ swing, a state that does not step) the items are not named at all, only that the near part stays bare.+ """+ h = group[0]at = placement(h.side, view, facing)part = h.part or "side"+ stay, they = ("stays", "it") if len(group) == 1 else ("stay", "them")+ swings = limb(h.part) if view == "side" else None+ if swings and gait:+ if at["depth"] == "far":+ bare = f"; the {swings} nearer the viewer stays bare, exactly as in the image" if other_bare else ""+ return (f"{_names(group)} {stay} on the {part} that wears {they} in the image, on the {swings} on the far side "+ f"of the body, and {'shows' if len(group) == 1 else 'show'} each time that {swings} swings forward{bare}.")+ bare = (f"; the other {swings}, on the far side of the body, stays bare both where it shows behind the body and "+ f"where it swings out in front of it") if other_bare else ""+ return (f"{_names(group)} {stay} on the {part} that wears {they} in the image, on the {swings} nearer the "+ f"viewer{bare}.")if view == "side" and at["depth"] == "far":- return f"The {part} in front of the body stays bare, exactly as in the image, for the whole clip."+ return f"The {part} in front of the body stays bare, exactly as in the image, for the whole clip." if other_bare else ""if view == "side":where = f"the {part} in front of the body"elif at["depth"] is None:where = f"the {part} at the {at['picture']} of the picture"else:near = "nearer the viewer" if at["depth"] == "near" else "on the far side of the body"- where = f"the {part} at the {at['picture']} of the picture, {near}"- item = h.item[0].upper() + h.item[1:]- return f"{item} stays on {where} for the whole clip, exactly as in the image, and on no other {part}."+ where = f"the {part} at the {at['picture']} of the picture, {near},"+ return f"{_names(group)} {stay} on {where} for the whole clip, exactly as in the image, and on no other {part}."+++def first_frame_needs(items: list[Handed], view: str, facing: str | None = None, *, gait: bool = False) -> list[str]:+ """What a clip's first frame has to show for the handedness sentences to hold. A clip keeps what its first+ frame shows and makes up what it hides, so a walk or run whose far limb wears an item starts from a still+ with that limb out in front of the body and the item in view."""+ validate_view(view, facing)+ if view != "side" or not gait:+ return []+ return [f"{h.item} is on the far {limb(h.part)} in this view, and the clip shows it only if its first frame does: start "+ f"from a still drawn mid-stride, the far {limb(h.part)} out in front of the body with {h.item} in view and the "+ f"near {limb(h.part)} swung back"+ for h in items if limb(h.part) and placement(h.side, view, facing)["depth"] == "far"]-def text(items: list[Handed], view: str, facing: str | None = None, *, clip: bool = False) -> str:+def text(items: list[Handed], view: str, facing: str | None = None, *, clip: bool = False, gait: bool = False) -> str:"""The handedness sentences for drawing `view` (a still) or filming it (`clip`). A still: per item, which ownside it is on and nowhere else, where that side is in this view, and that the sentences outrank a picture.- A clip: where the item stays, anchored to its first frame (`_clip_clause`)."""+ A clip: where the items stay, anchored to its first frame (`_clip_clause`); `gait` says the clip is a walk+ or run, whose far limb swings into view."""validate_view(view, facing)if clip:- return " ".join(_clip_clause(h, view, facing) for h in items)+ groups: dict[tuple[str, str], list[Handed]] = {}+ for h in items:+ groups.setdefault((h.side, h.part), []).append(h)+ clauses = [_clip_clause(group, view, facing, gait=gait, other_bare=(group[0].other, part) not in groups)+ for (_, part), group in groups.items()]+ if gait and view == "side" and any(limb(h.part) == "arm" for h in items):+ # the far arm's item shows only if the arms swing: said outright, once, before where the items are+ clauses.insert(0, ARMS_SWING_TEXT)+ return " ".join(clause for clause in clauses if clause)out = []for h in items:out.append(f"{h.item[0].upper()}{h.item[1:]} is on the character's own {h.where()} only; the "- f"{h.where(h.other)} has none, and it never moves to the other side.")- out.append(_view_clause(h, view, facing))+ f"{h.where(h.other)} has {_none(h, items)}, and it never moves to the other side.")+ out.append(_view_clause(h, view, facing, items))if items:# a still is often drawn from pictures that disagree with the item's sideout.append("These sentences decide which side each item is on, whatever an attached picture shows.")diff --git a/sprite_gen/gen/prompt_parts.py b/sprite_gen/gen/prompt_parts.pyindex 6cd897b..8bf4b5f 100644--- a/sprite_gen/gen/prompt_parts.py+++ b/sprite_gen/gen/prompt_parts.py@@ -90,7 +90,8 @@ ALREADY_SAID: dict[str, Callable[..., tuple[str, str] | None]] = {@dataclass(frozen=True)class Piece:"""One engine piece and what became of it: attached whole, attached without the sentences the prompt- already had (`why`), or left out (`added` False, `why`, and `found` — the key the prompt named)."""+ already had (`why`), or left out (`added` False, `why`, and `found` — the key the prompt named). `asked`+ and `params` are what `add` was given, so `Prompt.replaced` can put the piece on again."""topic: strtext: str@@ -159,8 +160,9 @@ class Prompt:def note(self, *, facing: str | None = None, handed: list[Any] | None = None, **_: Any) -> None:"""Note what the caller's text says against, or again after, a piece that turns the subject to `facing`- (right, left, or `NO_TURN` for a front or back view) or puts the `handed` items on their sides. `add` calls it for the piece it attaches; a template that- carries the turn in its own first text calls it itself."""+ (right, left, or `NO_TURN` for a front or back view) or puts the `handed` items on their sides. `add`+ calls it for the piece it attaches; a template that carries the turn in its own first text calls it+ itself."""if facing is not None:for words, side in turns_said(self.caller):if facing == NO_TURN:diff --git a/sprite_gen/qa/handed.py b/sprite_gen/qa/handed.pyindex 4f5f9f3..aa5482e 100644--- a/sprite_gen/qa/handed.py+++ b/sprite_gen/qa/handed.py@@ -10,14 +10,20 @@ each blob's centre is compared with the body's own centre (the mean x of its opa- a view with a picture side (front, back, the diagonals): every blob must be on that side;- the item in two places (two blobs farther apart than a link distance, the smaller at least a quarterof the larger; smaller ones are specks of compression tint) fails in every view;-- the near side of a side or diagonal view: the item must show in at least half the frames;-- the far side of a side view: the item is hidden or a sliver — no blob may be larger than half the- item seen whole, measured on `--reference` pictures of the same character (front or back, the item- in full view);+- the near side of a diagonal view: the item must show in at least half the frames; of a side view, in at+ least three quarters (a near arm is in view the whole walk; a far arm's item shows about half of it);+- the far side of a side view, an item on an arm or a leg (`handedness.limb`): the limb swings out in front+ of the body with each step and the item shows then, whole. Every blob must be in front of the body —+ on the facing side of its centre by at least a tenth of the body's height — and with `--state walk` or+ `run` it must show in at least a quarter of the frames. An item that also shows at or behind the body's+ centre is on the near limb, the wrong one;+- the far side of a side view, an item that does not swing (a pin on the far side of the head): hidden or a+ sliver — no blob may be larger than half the item seen whole, measured on `--reference` pictures of the+ same character (front or back, the item in full view);- the near side of a side view, against `--reference`: a frame shows the item only when it is more than- that sliver. A side view has no picture side, so size is all that tells the near wrist from the far- one: a far sliver turned over to face the other way must not count as the near item shown.- Without a reference neither size rule is checked (`far_hidden` / `near_whole`), and the report says so.+ that sliver, so a far sliver turned over to face the other way does not count as the near item shown.+ Against a reference a sliver is also not judged for where it is. Without one the size rules are not+ checked (`far_hidden` / `near_whole`), and the report says so.The screen colour cannot see the item's band without its marker — a watch's bare strap on the other arm.`--strap` names the band's colour (usually dark) and `--zone` the rows the item sits in (black is common:@@ -25,10 +31,11 @@ outlines, a hat, motion smear on the legs); a band of that colour outside everytaller than an outline, is another place the item shows. Specks of the marker's hue that a clip's colourblocks leave on outlines are recorded and not judged.-A picture turned over moves the item: a front view turned over puts it on the wrong side, a side view-facing right (the item on the far arm, hidden or a sliver) turned over to face left hides it, or leaves only-that sliver, on the near arm. So a set that made its left-hand views by mirroring fails here — a side view's-sliver only against `--reference` (`tests/qa/test_handed_check.py` proves it).+A picture turned over moves the item: a front view turned over puts it on the wrong side; a side walk facing+right (the item on the far arm, in view while that arm is forward) turned over to face left shows it in too+few frames for a near arm; one facing left (the item on the near arm, crossing the body) turned over to face+right shows it behind the body's centre. So a set that made its left-hand views by mirroring fails here+(`tests/qa/test_handed_check.py` proves it).Pixels cannot judge everything — an unmarked item, an item drawn on the wrong hand where it stays hidden —so `--board` draws every frame with its blobs ringed (green as expected, red not) for a person to look at."""@@ -76,10 +83,21 @@ STRAP_TOL = 55STRAP_ERODE = 0.004STRAP_MIN_SIDE = 0.016STRAP_GAP = 0.024-# At least this share of the frames must show the item on the near side of a side or diagonal view.+# At least this share of the frames must show the item on the near side of a diagonal view.NEAR_SHOWN_MIN = 0.5+# ... and of a side view, where the share is all that tells a near limb from a far one that swings into view:+# a near limb is in view for the whole walk, a far limb's item for the half of it the limb is forward.+SIDE_NEAR_SHOWN_MIN = 0.75# On the far side of a side view, a blob larger than this share of the item seen whole is not a sliver.FAR_MAX = 0.5+# A far limb's item shows while the limb is out past the front of the body: its centre at least this share of+# the body's height in front of the body's centre. A near limb's item crosses the centre both ways as it+# swings, and stays close to the centre on a limb held at the body.+FAR_FRONT_MIN = 0.1+# In a walk or run, a far limb's item must show in at least this share of the frames: it is in view for about+# half of each step, and a walk that never shows it has lost it.+FAR_SHOWN_MIN = 0.25+GAIT_STATES = ("walk", "run")def parse_marker(value: str) -> tuple[int, int, int]:@@ -201,9 +219,11 @@ def full_ratio(references: list[Image.Image], marker: tuple[int, int, int],def check(frames: list[Image.Image], *, item: handed_mod.Handed, view: str, facing: str | None,marker: tuple[int, int, int], references: list[Image.Image] | None = None,- strap: tuple[int, int, int] | None = None, zone: tuple[float, float] = (0.0, 1.0)) -> dict[str, Any]:+ strap: tuple[int, int, int] | None = None, zone: tuple[float, float] = (0.0, 1.0),+ state: str | None = None) -> dict[str, Any]:"""Every frame against `handedness.placement(item.side, view, facing)`; `ok` is the verdict. With `strap`,- a band without its marker counts as a place the item shows (`STRAP_TOL`)."""+ a band without its marker counts as a place the item shows (`STRAP_TOL`). `state` is the loop's motion+ state: in a walk or run, a far limb's item must show while the limb swings forward (`FAR_SHOWN_MIN`)."""if not 0 <= zone[0] < zone[1] <= 1:raise SystemExit(f"handed-check: --zone is TOP,BOTTOM as fractions of the body's height, 0 <= TOP < BOTTOM <= 1, got {zone}")if not frames:@@ -212,6 +232,8 @@ def check(frames: list[Image.Image], *, item: handed_mod.Handed, view: str, facifacing = Noneexpect = handed_mod.placement(item.side, view, facing)full = full_ratio(references or [], marker, zone)+ # a far limb in a side view swings out in front of the body; any other far part stays behind it+ swings = handed_mod.limb(item.part) if view == "side" and expect["depth"] == "far" else Nonerows, fails = [], []for i, frame in enumerate(frames):m = measure(frame, marker, strap=strap, zone=zone)@@ -229,7 +251,14 @@ def check(frames: list[Image.Image], *, item: handed_mod.Handed, view: str, facib["ratio"] = round(b["area"] / m["body_area"], 6)if expect["picture"] and b["side"] != expect["picture"]:bad.append(f"on the picture's {b['side']}, expected its {expect['picture']}")- if view == "side" and expect["depth"] == "far" and full is not None and b["ratio"] > FAR_MAX * full:+ whole = full is None or b["ratio"] > FAR_MAX * full+ if swings and whole:+ ahead = (b["x"] - m["centre_x"]) * (1 if facing == "right" else -1) / m["body_height"]+ b["ahead"] = round(ahead, 3)+ if ahead < FAR_FRONT_MIN:+ bad.append(f"at or behind the body's centre ({ahead:+.2f} of the body's height in front of it, at "+ f"least {FAR_FRONT_MIN} for a far {swings} swung forward): the item is on the near {swings}")+ elif view == "side" and expect["depth"] == "far" and not swings and full is not None and whole:bad.append(f"in full view ({b['ratio'] / full:.0%} of the whole item) on the far side")rows.append({**m, "bad": bad})if bad:@@ -237,25 +266,35 @@ def check(frames: list[Image.Image], *, item: handed_mod.Handed, view: str, faci# A side view has no picture side, so near and far differ only in size: on the near side a frame shows the# item when its largest blob is more than a sliver (the far side's own limit), or a far sliver turned over# would count as the near item shown.- sized = view == "side" and expect["depth"] == "near" and full is not None+ sized = view == "side" and (expect["depth"] == "near" or swings) and full is not Noneshown = sum(1 for r in rows if r["blobs"] and (not sized or r["blobs"][0]["ratio"] > FAR_MAX * full))rules: dict[str, Any] = {}if expect["picture"]:rules["picture_side"] = expect["picture"]if expect["depth"] == "near":- rules["near_shown"] = {"min": NEAR_SHOWN_MIN, "shown": shown, "frames": len(rows),- "ok": shown >= NEAR_SHOWN_MIN * len(rows)}+ near_min = SIDE_NEAR_SHOWN_MIN if view == "side" else NEAR_SHOWN_MIN+ rules["near_shown"] = {"min": near_min, "shown": shown, "frames": len(rows), "ok": shown >= near_min * len(rows)}if view == "side":size = ({"checked": False, "why": "no --reference: the item seen whole is unknown"} if full is Noneelse {"checked": True, "full_ratio": round(full, 6)})- if expect["depth"] == "far":+ if swings:+ rules["far_in_front"] = {"limb": swings, "min": FAR_FRONT_MIN, "of": "body height, toward the facing side"}+ if state in GAIT_STATES:+ rules["far_shown"] = {"checked": True, "min": FAR_SHOWN_MIN, "shown": shown, "frames": len(rows),+ "ok": shown >= FAR_SHOWN_MIN * len(rows)}+ else:+ why = ("no --state: only a walk or run swings the far limb into view" if state is None+ else f"a {state} does not swing the far {swings} into view")+ rules["far_shown"] = {"checked": False, "why": why, "shown": shown, "frames": len(rows)}+ elif expect["depth"] == "far":rules["far_hidden"] = {**size, **({"max": FAR_MAX} if full is not None else {})}else:rules["near_whole"] = {**size, **({"min": FAR_MAX} if full is not None else {})}- ok = not fails and rules.get("near_shown", {}).get("ok", True)+ ok = not fails and rules.get("near_shown", {}).get("ok", True) and rules.get("far_shown", {}).get("ok", True)return {"kind": "sprite-gen-handed-check","item": vars(item), "view": view, "facing": facing, "expect": expect,+ **({"state": state} if state else {}),"marker": "#%02x%02x%02x" % marker, **({"strap": "#%02x%02x%02x" % strap} if strap else {}),"zone": list(zone), "rules": rules,"frames": len(rows), "frames_shown": shown, "fails": fails, "ok": bool(ok),@@ -338,6 +377,7 @@ def add_arguments(parser: argparse.ArgumentParser) -> None:parser.add_argument("--marker", required=True, help="#RRGGBB: a saturated colour of the item that nothing else on the character has")parser.add_argument("--strap", help="#RRGGBB: the item's band colour (a watch strap, usually dark); a band of it with no marker on it, away from the marker, counts as another place the item shows. Use with --zone")parser.add_argument("--zone", default="0,1", help="TOP,BOTTOM: the rows the item sits in, as fractions of the body's height from its top (default 0,1, the whole body); e.g. 0.5,0.9 for a wrist")+ parser.add_argument("--state", help="the loop's motion state (walk, run, idle, ...): in a walk or run of a side view, an item on the far arm or leg must show while that limb swings forward")parser.add_argument("--reference", action="append", type=Path, default=[], help="a keyed front or back picture of the same character with the item in full view (repeatable): in a side view the far item must stay smaller than half of it, and the near item counts as shown only when larger")parser.add_argument("--report", type=Path, help="write the report JSON here")parser.add_argument("--board", type=Path, help="write the review board PNG here")@@ -350,16 +390,18 @@ def run(**kwargs: object) -> int:report = check(frames, item=handed_mod.parse(str(kwargs["handed"])), view=str(kwargs["direction"]),facing=kwargs.get("facing"), marker=parse_marker(str(kwargs["marker"])), references=references, # type: ignore[arg-type]strap=parse_marker(str(kwargs["strap"])) if kwargs.get("strap") else None,- zone=parse_zone(str(kwargs.get("zone") or "0,1")))+ zone=parse_zone(str(kwargs.get("zone") or "0,1")),+ state=str(kwargs["state"]) if kwargs.get("state") else None)if kwargs.get("board"):report["board"] = str(board(frames, report, Path(str(kwargs["board"]))))if kwargs.get("report"):atomic_write_text(Path(str(kwargs["report"])), json.dumps(report, ensure_ascii=False, indent=2) + "\n")summary = {k: report[k] for k in ("view", "facing", "expect", "frames", "frames_shown", "ok")}summary["fails"] = len(report["fails"])- for rule in ("far_hidden", "near_whole"):- if report["rules"].get(rule, {}).get("checked") is False:- summary["unchecked"] = f"{rule}: {report['rules'][rule]['why']}"+ unchecked = [f"{rule}: {report['rules'][rule]['why']}" for rule in ("far_hidden", "near_whole", "far_shown")+ if report["rules"].get(rule, {}).get("checked") is False]+ if unchecked:+ summary["unchecked"] = "; ".join(unchecked)print(json.dumps(summary, ensure_ascii=False))if not report["ok"]:for f in report["fails"][:10]:@@ -368,6 +410,10 @@ def run(**kwargs: object) -> int:r = report["rules"]["near_shown"]whole = " more than a sliver" if report["rules"].get("near_whole", {}).get("checked") else ""print(f"handed-check: on the near side the item shows{whole} in {r['shown']} of {r['frames']} frames", file=sys.stderr)+ if report["rules"].get("far_shown", {}).get("ok") is False:+ r = report["rules"]["far_shown"]+ print(f"handed-check: on the far {report['rules']['far_in_front']['limb']} the item shows in {r['shown']} of "+ f"{r['frames']} frames of the {report['state']}; it must show while that limb swings forward", file=sys.stderr)return 0 if report["ok"] else 1diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.pyindex f09756d..eab8502 100644--- a/sprite_gen/video/batch.py+++ b/sprite_gen/video/batch.py@@ -121,7 +121,8 @@ HOLD_TEXT = {}# What stays put while a caller's own walk or run moves, by view: in place, and facing the way the image# faces. A request interpreter may ask for any gait (a sneak, a march, a stroll); the engine keeps it on the-# spot and turned the right way, as the built-in gait sentences do. `{facing}` is the side view's.+# spot and turned the right way, as the built-in gait sentences do. That it does not move across the screen+# is the frame sentence's to say (`COMMON_TEXT`), and a side view's facing the view sentence's.GAIT_STATES = frozenset({"walk", "run"})GAIT_HOLD_TEXT = {"front": "It stays in place as if on a treadmill, without coming any closer, and keeps facing the viewer the whole time.",@@ -129,16 +130,22 @@ GAIT_HOLD_TEXT = {"It stays in place as if on a treadmill, without moving any farther away, and keeps facing away from the viewer ""the whole time."),- "side": "It stays in place as if on a treadmill, without moving across the screen, and keeps facing {facing} the whole time.",+ "side": "It stays in place as if on a treadmill.","front_diagonal": (- "It stays in place as if on a treadmill, without moving across the screen, and keeps the exact three-quarter front "- "angle of the image the whole time, never turning into a side view."+ "It stays in place as if on a treadmill and keeps the exact three-quarter front angle of the image the whole time, "+ "never turning into a side view."),"back_diagonal": (- "It stays in place as if on a treadmill, without moving across the screen, and keeps the exact three-quarter back "- "angle of the image the whole time, its face hidden, never turning into a side view."+ "It stays in place as if on a treadmill and keeps the exact three-quarter back angle of the image the whole time, "+ "its face hidden, never turning into a side view."),}+# Views whose walk or run says the view itself, in the gait sentence (`VIEW_MOTION_TEXT`) or the gait hold above:+# "facing the viewer", "keeps the exact three-quarter back angle of the image". Their clip prompt leaves the+# view sentence ("The character is seen from ...") out, which said the same thing a second time. A side+# view's gait says only that it stays in place, so its view sentence stays and carries the facing.+GAIT_SAYS_VIEW = frozenset({"front", "back", "front_diagonal", "back_diagonal"})+VIEW_SENTENCE = " The character is {view}."MOTION_TEXT = {# A side-view full body asked for "a subtle weight sway" and an evenly paced loop steps in place# more often than not, so the feet are held and walking is named as what not to do.@@ -148,8 +155,8 @@ MOTION_TEXT = {"hair and loose cloth, and one natural blink if the face has eyes. The feet never lift, step, shuffle or slide ""— no walking, no marching in place, no turning."),- "walk": "walks naturally in place, as if on a treadmill, without moving across the screen.",- "run": "runs naturally in place, as if on a treadmill, without moving across the screen.",+ "walk": "walks naturally in place, as if on a treadmill.",+ "run": "runs naturally in place, as if on a treadmill.","jump": "performs a modest vertical hop in place over and over: compress, spring up about half the body height, land softly, return to the exact starting stance, repeat at an even rhythm. Same height every time.","attack": ("performs one melee attack with what it is already holding (bare hands only if it holds nothing), keeping "@@ -168,7 +175,8 @@ MOTION_TEXT = {# "walks naturally" swung the arms and kept the knees low (2.15). 2.16 gives the run and the side view the# same form. How a character walks is the caller's to say (`build_prompt(motion=...)`, held in place by# `GAIT_HOLD_TEXT`); the engine's default stays generic. "as if on a treadmill" keeps the treadmill a-# comparison: said as a place, it was sometimes drawn under the feet.+# comparison: said as a place, it was sometimes drawn under the feet. A side or diagonal gait no longer adds+# "without moving across the screen": the frame sentence says it ("does not move across the screen").VIEW_MOTION_TEXT = {("walk", "front"): "walks naturally in place, facing the viewer, as if on a treadmill, without coming any closer.",("walk", "back"): (@@ -185,23 +193,23 @@ VIEW_MOTION_TEXT = {# view drawn facing left heads down or up and to the left (it said "to the right" whatever the facing).("walk", "front_diagonal"): ("walks naturally in place, as if on a treadmill, heading diagonally toward the viewer and to the {facing}, like a "- "character walking down and to the {facing} in an isometric game, without moving across the screen. It keeps the "+ "character walking down and to the {facing} in an isometric game. It keeps the ""exact three-quarter front angle of the image the whole time and never turns into a side view."),("walk", "back_diagonal"): ("walks naturally in place, as if on a treadmill, heading diagonally away from the viewer toward the upper {facing}, "- "like a character walking up and to the {facing} in an isometric game, without moving across the screen. It keeps "+ "like a character walking up and to the {facing} in an isometric game. It keeps ""the exact three-quarter back angle of the image the whole time: its back stays turned toward the viewer at that ""angle and its face stays hidden. It never turns into a side view."),("run", "front_diagonal"): ("runs naturally in place, as if on a treadmill, heading diagonally toward the viewer and to the {facing}, like a "- "character running down and to the {facing} in an isometric game, without moving across the screen. It keeps the "+ "character running down and to the {facing} in an isometric game. It keeps the ""exact three-quarter front angle of the image the whole time and never turns into a side view."),("run", "back_diagonal"): ("runs naturally in place, as if on a treadmill, heading diagonally away from the viewer toward the upper {facing}, "- "like a character running up and to the {facing} in an isometric game, without moving across the screen. It keeps "+ "like a character running up and to the {facing} in an isometric game. It keeps ""the exact three-quarter back angle of the image the whole time: its back stays turned toward the viewer at that ""angle and its face stays hidden. It never turns into a side view."),@@ -317,11 +325,14 @@ def clip_prompt_parts(direction: str, state: str, character: str | None, facing:template = PINNED_LOOP_TEXTelse:template = COMMON_TEXT+ says_view = state in GAIT_STATES and direction in GAIT_SAYS_VIEW+ if says_view:+ template = template.replace(VIEW_SENTENCE, "")if motion is not None:motion = " ".join(motion.split())if not motion:raise SystemExit("video: motion description is empty")- head = "2D game sprite animation. The character {motion} The character is {view}."+ head = "2D game sprite animation. The character {motion}"subject = character.strip().rstrip(".") if character else "The character"parts = prompt_parts.Prompt(f"2D game sprite animation. {motion}", caller=f"{motion} {character or ''}", sep=" ")if state in HOLD_TEXT:@@ -330,7 +341,8 @@ def clip_prompt_parts(direction: str, state: str, character: str | None, facing:parts.add("gait-hold", GAIT_HOLD_TEXT[direction].format(facing=facing))if state in REPEAT_TEXT:parts.add("repeat", REPEAT_TEXT[state])- parts.add("frame", f"{subject} is {view}." + template[len(head):], facing=turned or prompt_parts.NO_TURN)+ frame = template[len(head):].replace(VIEW_SENTENCE, f" {subject} is {view}.", 1)+ parts.add("frame", frame.strip(), facing=turned or prompt_parts.NO_TURN)else:built_in = (VIEW_MOTION_TEXT[(state, direction)].format(facing=facing) if (state, direction) in VIEW_MOTION_TEXTelse MOTION_TEXT.get(state, f"performs the '{state}' action in place, repeating at an even rhythm."))@@ -341,7 +353,7 @@ def clip_prompt_parts(direction: str, state: str, character: str | None, facing:for topic, text in _lite_pieces(state, direction, model, built_in=motion is None):parts.add(topic, text)if handed:- parts.add("handed", handed_mod.text(handed, direction, turned, clip=True), handed=handed)+ parts.add("handed", handed_mod.text(handed, direction, turned, clip=True, gait=state in GAIT_STATES), handed=handed)return parts@@ -495,6 +507,10 @@ def run_item(prompt = parts.textif parts.notes:result["prompt_notes"] = parts.notes+ needs = handed_mod.first_frame_needs(handed or [], direction, facing if direction in handed_mod.LATERAL_VIEWS else None,+ gait=state in GAIT_STATES)+ if needs:+ result["still_needs"] = needsclip = item_dir / "clip.mp4"clip_report = item_dir / "clip.report.json"reuse_clip = clip.exists() and clip_report.exists() and not forcediff --git a/sprite_gen/video/clip_prompt.py b/sprite_gen/video/clip_prompt.pyindex 8ef579a..49bcd9f 100644--- a/sprite_gen/video/clip_prompt.py+++ b/sprite_gen/video/clip_prompt.py@@ -87,6 +87,10 @@ def plan_prompt(*, direction: str, state: str, facing: str = "right", character:"warnings": warnings,**({"notes": parts.notes} if parts.notes else {}),}+ needs = handed_mod.first_frame_needs(handed or [], direction, canvas_facing if direction in handed_mod.LATERAL_VIEWS else None,+ gait=state in batch_mod.GAIT_STATES)+ if needs:+ record["still_needs"] = needsif mid_step:record["start_still"] = {"why": "a front or back walk films from its still redrawn mid-step; from a standing still the clip model walks askew",@@ -122,6 +126,8 @@ def run(**kwargs: object) -> int:)for line in record["warnings"]:print(f"video-prompt: warning: {line}", file=sys.stderr)+ for line in record.get("still_needs", []):+ print(f"video-prompt: the still: {line}", file=sys.stderr)print(json.dumps(record, ensure_ascii=False, indent=2) if kwargs.get("json") else record["prompt"])return 0diff --git a/tests/gen/test_handedness.py b/tests/gen/test_handedness.pyindex 8beab19..5461ba7 100644--- a/tests/gen/test_handedness.py+++ b/tests/gen/test_handedness.py@@ -65,7 +65,10 @@ def test_the_sentence_says_the_side_and_where_it_is_in_the_view(view, facing) ->if picture:assert f"own left wrist is the one at the {picture} of the picture" in textif depth == "far" and view == "side":- assert "on the far side, behind the body, so the black smartwatch is hidden" in text+ # a far arm swings out in front of the body, and what it wears shows then+ assert "the left wrist with the black smartwatch is on the far arm." in text+ assert "Wherever the far arm reaches out in front of the body, clear of its outline, the black smartwatch shows whole" in text+ assert "hidden or at most a sliver" not in textif depth == "near" and view == "side":assert "its left wrist is the near one" in text and "shows clearly" in textif depth == "near" and view != "side":@@ -93,6 +96,74 @@ def test_the_clip_sentence_anchors_to_the_image_and_never_names_a_hidden_item(viassert "the wrist in front of the body" in clip+def test_a_far_part_that_does_not_swing_stays_hidden() -> None:+ """A pin on the far side of the head has nothing to bring it into view: drawn hidden, never named in a clip."""+ pin = [h.parse("the star pin=left side of the head")]+ assert h.limb("wrist") == "arm" and h.limb("upper arm") == "arm" and h.limb("ankle") == "leg"+ assert h.limb("side of the head") is None and h.limb("shoulder") is None and h.limb("") is None+ assert "on the far side, behind the body, so the star pin is hidden or at most a sliver of it shows" in h.text(pin, "side", "right")+ for gait in (False, True):+ clip = h.text(pin, "side", "right", clip=True, gait=gait)+ assert clip == "The side of the head in front of the body stays bare, exactly as in the image, for the whole clip."+++def test_a_walk_shows_the_far_arms_item_when_that_arm_swings_forward() -> None:+ """2.22.0 never named a hidden item, and the far wrist's watch was in no frame of a side walk. A walk's far+ arm comes forward with every step: the sentence says the item shows then, and that the near arm is bare."""+ watch = [h.parse(WATCH)]+ far = h.text(watch, "side", "right", clip=True, gait=True)+ assert far == (h.ARMS_SWING_TEXT + " "+ "The black smartwatch stays on the wrist that wears it in the image, on the arm on the far side of the "+ "body, and shows each time that arm swings forward; the arm nearer the viewer stays bare, exactly as in "+ "the image.")+ near = h.text(watch, "side", "left", clip=True, gait=True)+ assert near == (h.ARMS_SWING_TEXT + " "+ "The black smartwatch stays on the wrist that wears it in the image, on the arm nearer the viewer; the "+ "other arm, on the far side of the body, stays bare both where it shows behind the body and where it "+ "swings out in front of it.")+ # no sentence holds an arm still, and a state that does not step keeps the 2.22.0 sentence+ assert "still" not in far + near and "for the whole clip" not in far + near+ assert h.text(watch, "side", "right", clip=True) == "The wrist in front of the body stays bare, exactly as in the image, for the whole clip."+ assert "shows each time that arm swings forward" in batch_mod.build_prompt("side", "walk", None, handed=watch)+ assert "shows each time that arm swings forward" in batch_mod.build_prompt("side", "run", None, handed=watch)+ assert "swing" not in batch_mod.build_prompt("side", "idle", None, handed=watch)+ assert h.ARMS_SWING_TEXT == "Both arms swing back and forth with each step, opposite to the legs."+ assert h.ARMS_SWING_TEXT not in h.text([h.parse("the red anklet=left ankle")], "side", "right", clip=True, gait=True)+ # the other views have a picture side to name and are unchanged by the state+ for view, facing in (("front", None), ("front_diagonal", "left"), ("back_diagonal", "right")):+ assert h.text(watch, view, facing, clip=True, gait=True) == h.text(watch, view, facing, clip=True)+++def test_a_side_walk_says_what_its_first_frame_must_show() -> None:+ """A clip keeps what its first frame shows: the far arm's item is in the walk only if the still shows it."""+ watch = [h.parse(WATCH)]+ needs = h.first_frame_needs(watch, "side", "right", gait=True)+ assert len(needs) == 1 and "mid-stride, the far arm out in front of the body with the black smartwatch in view" in needs[0]+ assert h.first_frame_needs(watch, "side", "left", gait=True) == [] # the near arm is always in view+ assert h.first_frame_needs(watch, "side", "right") == [] # an idle does not swing it+ assert h.first_frame_needs(watch, "front_diagonal", "right", gait=True) == []+ assert h.first_frame_needs([h.parse("the star pin=left side of the head")], "side", "right", gait=True) == []+ record = clip_prompt.plan_prompt(direction="side", state="walk", facing="right", last_frame=False, handed=watch)+ assert record["still_needs"] == needs+ assert "still_needs" not in clip_prompt.plan_prompt(direction="side", state="walk", facing="left", last_frame=False, handed=watch)+++def test_two_items_do_not_call_a_wrist_bare_that_the_other_is_on() -> None:+ """One sentence per wrist. With an item on each wrist, a side clip said "the wrist in front of the body stays+ bare" and "the red ribbon stays on the wrist in front of the body" together; with two on one wrist it said the+ same sentence twice."""+ watch, ribbon, bracelet = h.parse(WATCH), h.parse("the red ribbon=right wrist"), h.parse("the gold bracelet=left wrist")+ for gait in (False, True):+ each = h.text([watch, ribbon], "side", "right", clip=True, gait=gait)+ assert "bare" not in each and each.count("The red ribbon") == 1+ both = h.text([watch, bracelet], "side", "right", clip=True, gait=gait)+ assert both.count("bare") == 1 and both.count(h.ARMS_SWING_TEXT) == (1 if gait else 0)+ assert h.text([watch, bracelet], "side", "left", clip=True).startswith("The black smartwatch and the gold bracelet stay on ")+ still = h.text([watch, ribbon], "side", "right")+ assert "the right wrist has none of it" in still and "with none of it" in still and "with none;" not in still+ assert "has none," in h.text([watch], "side", "right") and "none of it" not in h.text([watch, bracelet], "side", "right")++def test_the_clip_prompt_ends_with_the_handedness_sentence() -> None:items = [h.parse(WATCH)]plain = batch_mod.build_prompt("front_diagonal", "walk", None, facing="left")diff --git a/tests/gen/test_prompt_assembly.py b/tests/gen/test_prompt_assembly.pyindex 437014d..d54ffde 100644--- a/tests/gen/test_prompt_assembly.py+++ b/tests/gen/test_prompt_assembly.py@@ -30,7 +30,7 @@ HANDED = {"watch+bracelet": ["the black smartwatch=left wrist", "the gold bracelet=left wrist"],"watch+ribbon": ["the black smartwatch=left wrist", "the red ribbon=right wrist"],}-SUBJECT = "A small rabbit mascot, 2D game sprite, full body"+SUBJECT = "A small fox adventurer, 2D game sprite, full body"# The caller's own text: what it already says about the key, the turn and the item. `turn` / `item` is# the side its words name, to tell an agreeing repeat from a conflict with the options.USER_TEXT = {@@ -48,9 +48,9 @@ MODELS = {"pro": "grok-imagine-video-1.5", "lite": "grok-imagine-video-1.5-lite"# --motion: the built-in sentence, the caller's own, one that quotes an engine rule, one that walks the other wayMOTION = {"built-in": {"text": None},- "own": {"text": "The rabbit walks with a cheerful bounce, swinging both arms."},- "quotes-engine": {"text": "The rabbit walks with a cheerful bounce. Camera completely locked, no zoom, no pan, no reframing."},- "says-turn": {"text": "The rabbit walks to the right with a cheerful bounce.", "turn": "right"},+ "own": {"text": "The fox walks with a cheerful bounce, swinging both arms."},+ "quotes-engine": {"text": "The fox walks with a cheerful bounce. Camera completely locked, no zoom, no pan, no reframing."},+ "says-turn": {"text": "The fox walks to the right with a cheerful bounce.", "turn": "right"},}@@ -84,7 +84,7 @@ def _clip_rows():for (view, facing), handed, state, model, motion in itertools.product(_views(), HANDED, STATES, MODELS, MOTION):if MOTION[motion]["text"] and state != "walk":continue- parts = batch.clip_prompt_parts(view, state, "The rabbit mascot", facing=facing or "right",+ parts = batch.clip_prompt_parts(view, state, "The fox", facing=facing or "right",motion=MOTION[motion]["text"], model=MODELS[model], handed=_items(handed))row = {"user": None, "motion": motion, "facing": facing, "handed": handed, "state": state}yield f"clip/{view}@{facing}/{state}/{model}/{motion}/{handed}", parts, row@@ -163,6 +163,40 @@ def test_no_prompt_says_a_sentence_twice_turns_both_ways_or_asks_for_two_keys(naassert "handed" not in conflicts, parts.notes+_CLIP_ROWS = [r for r in ROWS if r[0].startswith("clip")]+# (a part or limb said bare, the same one said to wear an item): never both in one prompt+_BARE_AND_WORN = [+ (r"\bThe (\w[\w ]*?) in front of the body stays bare\b", "stays? on the {0} in front of the body"),+ (r"\bthe (arm|leg) nearer the viewer stays bare\b", "on the {0} nearer the viewer"),+ (r"\bthe other (arm|leg), on the far side of the body, stays bare\b", "on the {0} on the far side of the body"),+]++[email protected]("name,parts,row", _CLIP_ROWS, ids=[r[0] for r in _CLIP_ROWS])+def test_no_clip_calls_a_limb_bare_and_dressed_or_swings_an_arm_that_stands_still(name, parts, row) -> None:+ text = parts.text+ for bare, worn in _BARE_AND_WORN:+ for match in re.finditer(bare, text):+ assert not re.search(worn.format(re.escape(match.group(1))), text), text+ # what the walk paragraph and the frame rules both said: in place across the screen, and the view+ assert len(re.findall(r"\bmov(?:e|ing) across the screen\b", text)) == 1, text+ for view_words in ("facing the viewer", "facing away from the viewer", "three-quarter front angle", "three-quarter back angle",+ "exact side"):+ assert text.count(view_words) <= 1, (view_words, text)+ side = "/side@" in name+ walks = row["state"] in batch.GAIT_STATES+ if not walks:+ # only a step swings a limb: an idle, a jump or an attack is never told that an arm swings+ assert "swing" not in text, text+ if row["handed"] != "none" and side and walks:+ # every item is on a wrist here: the far one is named and shows when its arm comes forward+ far = "the red ribbon" if (row["handed"] == "watch+ribbon" and row["facing"] == "left") else "the black smartwatch"+ if row["facing"] == "right" or row["handed"] == "watch+ribbon":+ assert "each time that arm swings forward" in text and far[4:] in text, text+ assert "The wrist in front of the body stays bare" not in text+ assert text.count("Both arms swing back and forth with each step") == 1++@pytest.mark.parametrize("name,parts,row", [r for r in ROWS if r[0].startswith("still")], ids=[r[0] for r in ROWS if r[0].startswith("still")])def test_a_still_carries_the_key_line_unless_its_text_names_a_key(name, parts, row) -> None:piece = parts.piece("key-background")@@ -176,17 +210,17 @@ def test_a_still_carries_the_key_line_unless_its_text_names_a_key(name, parts, r# -- the known cases ---------------------------------------------------------------------------------@pytest.mark.parametrize("prompt,named", [- ("a rabbit on a background of pure magenta", "magenta"),- ("a rabbit, magenta-colored background", "magenta"),- ("a rabbit, magenta coloured backdrop", "magenta"),+ ("a fox on a background of pure magenta", "magenta"),+ ("a fox, magenta-colored background", "magenta"),+ ("a fox, magenta coloured backdrop", "magenta"),("background: solid green", "green"),- ("a rabbit keyed on pure magenta", "magenta"),- ("a rabbit drawn on a green key", "green"),- ("a rabbit, no green screen", None),- ("a rabbit without a green background", None),- ("a rabbit, not on a magenta background", None),+ ("a fox keyed on pure magenta", "magenta"),+ ("a fox drawn on a green key", "green"),+ ("a fox, no green screen", None),+ ("a fox without a green background", None),+ ("a fox, not on a magenta background", None),("no green screen; use a magenta background", "magenta"),- ("a rabbit with no shadow, on a magenta background", "magenta"),+ ("a fox with no shadow, on a magenta background", "magenta"),("a knight holding a green key", None),("a background of trees with green leaves", None),("a hero in a green screen-printed shirt", None),@@ -202,9 +236,9 @@ def test_a_key_background_is_read_however_it_is_worded_and_not_when_ruled_out(prdef test_a_key_the_text_rules_out_is_not_the_one_the_engine_asks_for() -> None:- assert chroma.ruled_out_key_backgrounds("a rabbit, no green screen") == {"green"}+ assert chroma.ruled_out_key_backgrounds("a fox, no green screen") == {"green"}with pytest.raises(SystemExit, match="rules out a green key background"):- gen.still_prompt("a rabbit, no green screen", refs=True, key="green")+ gen.still_prompt("a fox, no green screen", refs=True, key="green")# the text names the other key itself: nothing is added, so nothing is refusednamed = gen.still_prompt("no green screen; use a magenta background", refs=True, key="green")assert named.piece("key-background").found == "magenta" and not named.piece("key-background").added@@ -213,20 +247,20 @@ def test_a_key_the_text_rules_out_is_not_the_one_the_engine_asks_for() -> None:def test_a_turned_view_says_the_turn_once_and_the_reference_piece_only_pins_the_edge() -> None:"""With --direction the view sentence says the turn. The reference piece said it again as a full profile("facing left (toward the left edge of the image)"), against a three-quarter view's 45 degrees."""- plain = gen.still_prompt("a rabbit", facing="left", refs=True)+ plain = gen.still_prompt("a fox", facing="left", refs=True)assert plain.text.endswith(facing_mod.prompt_suffix("left")) and "must be facing left" in plain.textfor view in sorted(h.LATERAL_VIEWS):- text = gen.still_prompt("a rabbit", view=view, facing="left", refs=True).text+ text = gen.still_prompt("a fox", view=view, facing="left", refs=True).textassert "must be facing" not in textassert text.endswith("Left here means toward the left edge of the image, regardless of the reference image's ""orientation. Preserve the subject's design.")- front = gen.still_prompt("a rabbit", view="front", refs=True)+ front = gen.still_prompt("a fox", view="front", refs=True)assert front.piece("facing") is Nonedef test_a_correction_takes_the_place_of_the_sentence_it_corrects() -> None:"""The regeneration's prompt was the first prompt plus the correction: the facing sentence twice."""- parts = gen.still_prompt("a rabbit", facing="right", refs=True, key="magenta")+ parts = gen.still_prompt("a fox", facing="right", refs=True, key="magenta")retry = parts.replaced("facing", facing_mod.prompt_suffix("right", retry=True)).textassert retry.count("The subject must be facing right") == 1 and retry.count("Preserve the subject's design.") == 1assert retry.endswith(facing_mod.prompt_suffix("right", retry=True))@@ -271,11 +305,11 @@ def test_gen_reports_what_the_callers_text_says_against_the_options(tmp_path, moreturn ProviderRun(self.name, 1, model="test-image", extra={})monkeypatch.setattr(gen, "_make_provider", lambda *a, **kw: Backend())- result = gen.generate_image("fake", "a rabbit facing left, a black smartwatch on its right wrist",+ result = gen.generate_image("fake", "a fox facing left, a black smartwatch on its right wrist",tmp_path / "out.png", view="side", facing="right",handed=h.parse_all(["the black smartwatch=left wrist"]))assert {note["about"] for note in result.extra["prompt_notes"]} == {"facing", "handed"}err = capsys.readouterr().errassert '[gen] warning: the text says "facing left" and the engine\'s sentence says right' in err- quiet = gen.generate_image("fake", "a rabbit", tmp_path / "quiet.png", view="side", facing="right")+ quiet = gen.generate_image("fake", "a fox", tmp_path / "quiet.png", view="side", facing="right")assert "prompt_notes" not in quiet.extradiff --git a/tests/qa/test_handed_check.py b/tests/qa/test_handed_check.pyindex 7a34e7f..cbce530 100644--- a/tests/qa/test_handed_check.py+++ b/tests/qa/test_handed_check.py@@ -17,7 +17,8 @@ WATCH = h.parse("the black smartwatch=left wrist")BLUE = (30, 90, 235)W, H = 200, 320# Where the watch is drawn for each (view, facing): on the arm at the picture's left / right, on the-# near arm (a side view, in front of the body) or nowhere (a side view, behind the body).+# near arm (a side view, in front of the body) or nowhere (a side view, behind the body). "far" is the far+# arm of a right-facing side view swung forward, out in front of the body, the watch in view on it.DRAWN = {("front", None): "right", ("back", None): "left",("front_diagonal", "right"): "right", ("front_diagonal", "left"): "right",@@ -38,6 +39,8 @@ def figure(where: str, *, swing: int = 0, screen: int = 12, outline_split: boolarms = {"left": (40 + swing, 110, 62 + swing, 210), "right": (138 - swing, 110, 160 - swing, 210)}if where == "near":arms = {"near": (92 + swing, 120, 112 + swing, 215)}+ if where == "far":+ arms = {"far": (140 + swing, 120, 162 + swing, 215)}for box in arms.values():d.rectangle(box, fill=(235, 235, 235, 255), outline=(20, 20, 20, 255), width=2)if where in arms:@@ -83,18 +86,54 @@ def test_a_mirrored_view_fails(view, facing, as_view, as_facing) -> None:assert not report["ok"]-def test_the_wrong_wrist_in_a_side_view_needs_a_reference_to_be_caught() -> None:- """Facing right, the left wrist is the far one: a full screen on the near arm is the wrong wrist.- Only the item seen whole (a front reference) tells a sliver from a full screen."""+def test_the_wrong_wrist_in_a_side_view_is_caught_by_where_it_shows() -> None:+ """Facing right, the left wrist is the far one. A far arm's watch shows only out in front of the body, where+ the arm swings forward; a full screen over the body's centre is on the near arm, the wrong wrist."""frames = loop("near")- unchecked = check(frames, "side", "right")- assert unchecked["ok"] and unchecked["rules"]["far_hidden"]["checked"] is False- caught = check(frames, "side", "right", references=[figure("right")])- assert not caught["ok"] and "on the far side" in caught["fails"][0]["why"][0]+ caught = check(frames, "side", "right")+ assert not caught["ok"] and "the item is on the near arm" in caught["fails"][0]["why"][0]+ assert not check(frames, "side", "right", references=[figure("right")])["ok"]+ # against a reference, a sliver of the far watch peeking past the body is not judged for where it issliver = check([figure("near", screen=4)], "side", "right", references=[figure("right")])assert sliver["ok"]+def test_a_far_arms_watch_in_view_while_the_arm_is_forward_passes() -> None:+ """The far wrist's watch, whole, in the frames where that arm is out in front of the body: what a side walk+ should look like. 2.22.0 failed every such frame ("in full view on the far side") against a reference."""+ walk = [figure("hidden")] * 3 + [figure("far", swing=s) for s in (0, 3, 6)]+ for references in (None, [figure("right")]):+ report = check(walk, "side", "right", references=references, state="walk")+ assert report["ok"], report["fails"]+ assert report["rules"]["far_shown"] == {"checked": True, "min": 0.25, "shown": 3, "frames": 6, "ok": True}+ assert report["rules"]["far_in_front"]["limb"] == "arm" and "far_hidden" not in report["rules"]+ assert report["per_frame"][3]["blobs"][0]["ahead"] >= handed.FAR_FRONT_MIN+ # turned over to face left it is the near arm's, and shows in too few frames for one+ mirrored = check([ImageOps.mirror(f) for f in walk], "side", "left", state="walk")+ assert not mirrored["ok"] and mirrored["rules"]["near_shown"] == {"min": 0.75, "shown": 3, "frames": 6, "ok": False}+++def test_a_walk_that_never_shows_the_far_arms_watch_fails_and_other_states_are_not_judged() -> None:+ hidden = loop("hidden")+ walk = check(hidden, "side", "right", state="walk")+ assert not walk["ok"] and walk["fails"] == [] and walk["rules"]["far_shown"]["ok"] is False+ assert check([figure("hidden")] * 7 + [figure("far")], "side", "right", state="run")["ok"] is False # 1 of 8+ idle = check(hidden, "side", "right", state="idle")+ assert idle["ok"] and idle["rules"]["far_shown"]["checked"] is False and "idle" in idle["rules"]["far_shown"]["why"]+ unsaid = check(hidden, "side", "right")+ assert unsaid["ok"] and "no --state" in unsaid["rules"]["far_shown"]["why"]+++def test_a_far_part_that_does_not_swing_keeps_the_hidden_rule() -> None:+ """A pin on the far side of the head stays behind it: in full view there, it is on the wrong side."""+ pin = h.parse("the star pin=left side of the head")+ frames = loop("near")+ unchecked = handed.check(frames, item=pin, view="side", facing="right", marker=BLUE, state="walk")+ assert unchecked["ok"] and unchecked["rules"]["far_hidden"]["checked"] is False and "far_shown" not in unchecked["rules"]+ caught = handed.check(frames, item=pin, view="side", facing="right", marker=BLUE, references=[figure("right")])+ assert not caught["ok"] and "on the far side" in caught["fails"][0]["why"][0]++def test_a_far_sliver_turned_over_is_not_the_near_item_shown() -> None:"""Facing right, the far wrist's watch may show as a sliver as the arm swings. Turned over to face left,that sliver is on the arm behind the body — the own right wrist, the wrong one — and the near wrist is@@ -106,7 +145,7 @@ def test_a_far_sliver_turned_over_is_not_the_near_item_shown() -> None:mirrored = [ImageOps.mirror(f) for f in right]caught = check(mirrored, "side", "left", references=reference)assert not caught["ok"] and caught["fails"] == []- assert caught["rules"]["near_shown"] == {"min": 0.5, "shown": 0, "frames": 6, "ok": False}+ assert caught["rules"]["near_shown"] == {"min": 0.75, "shown": 0, "frames": 6, "ok": False}assert caught["rules"]["near_whole"]["checked"] is True and caught["frames_shown"] == 0unchecked = check(mirrored, "side", "left")assert unchecked["rules"]["near_whole"] == {"checked": False, "why": "no --reference: the item seen whole is unknown"}@@ -132,7 +171,9 @@ def test_the_item_in_two_places_fails_and_a_split_screen_is_one() -> None:def test_a_near_item_hidden_in_most_frames_fails() -> None:frames = [figure("near")] + [figure("hidden")] * 3report = check(frames, "side", "left")- assert not report["ok"] and report["rules"]["near_shown"] == {"min": 0.5, "shown": 1, "frames": 4, "ok": False}+ assert not report["ok"] and report["rules"]["near_shown"] == {"min": 0.75, "shown": 1, "frames": 4, "ok": False}+ # a diagonal's near side keeps the half: its picture side tells the arms apart+ assert check([figure("right")] * 2 + [figure("hidden")] * 2, "front_diagonal", "left")["rules"]["near_shown"]["min"] == 0.5def test_unusable_inputs_are_refused() -> None:diff --git a/tests/video/test_batch_handed.py b/tests/video/test_batch_handed.pyindex cb1ccb0..afbfdf6 100644--- a/tests/video/test_batch_handed.py+++ b/tests/video/test_batch_handed.py@@ -63,7 +63,7 @@ def test_both_facings_film_every_turned_view_twice_from_its_own_still(tmp_path,assert canvas["facing"] == turneddirection = item["direction"]assert prompts[name] == batch.build_prompt(direction, "walk", None, facing=turned, handed=WATCH)- assert prompts[name].endswith(h.text(WATCH, direction, turned, clip=True))+ assert prompts[name].endswith(h.text(WATCH, direction, turned, clip=True, gait=True))assert "and to the left" in prompts["front_diagonal-left-walk"]assert "to the right" not in prompts["front_diagonal-left-walk"]# each side still is inspected for its own facing, into its own copy, never turned overdiff --git a/tests/video/test_video_pipeline.py b/tests/video/test_video_pipeline.pyindex 17fc224..131e09c 100644--- a/tests/video/test_video_pipeline.py+++ b/tests/video/test_video_pipeline.py@@ -500,8 +500,13 @@ def test_every_gait_walks_or_runs_naturally_in_place() -> None:):sentence = batch_mod.VIEW_MOTION_TEXT.get((state, direction)) or batch_mod.MOTION_TEXT[state]p = batch_mod.build_prompt(direction, state, None)- assert p == batch_mod.COMMON_TEXT.format(motion=sentence, view=batch_mod.VIEW_TEXT[direction].format(facing="right"))+ # a front or back gait says which way it faces itself, so the view sentence is not said after it+ template = batch_mod.COMMON_TEXT if direction == "side" else batch_mod.COMMON_TEXT.replace(batch_mod.VIEW_SENTENCE, "")+ assert p == template.format(motion=sentence, view=batch_mod.VIEW_TEXT[direction].format(facing="right"))+ assert ("The character is seen from" in p) is (direction == "side")assert sentence.startswith(opening) and sentence.count(".") == 1+ # that it does not move across the screen is the frame sentence's, once+ assert p.count("move across the screen") + p.count("moving across the screen") == 1assert ", as if on a treadmill" in pfor gone in ("left-right", "on a treadmill:", "lifts and lands", "never turns to the side"):assert gone not in p@@ -518,9 +523,13 @@ def test_a_callers_gait_is_held_in_place_and_facing_the_images_way() -> None:for state in ("walk", "run"):p = batch_mod.build_prompt(direction, state, "The knight", "left", motion=sneak)hold = batch_mod.GAIT_HOLD_TEXT[direction].format(facing="left")- assert p.startswith(f"2D game sprite animation. {sneak} {hold} The knight is {batch_mod.VIEW_TEXT[direction].format(facing='left')}.")+ # the side view's facing is its view sentence's; a front or back hold says the view itself+ view = f" The knight is {batch_mod.VIEW_TEXT[direction].format(facing='left')}." if direction == "side" else ""+ assert p.startswith(f"2D game sprite animation. {sneak} {hold}{view} Stays centered in the frame")assert batch_mod.MOTION_TEXT[state] not in p- assert "keeps facing left the whole time" in batch_mod.GAIT_HOLD_TEXT["side"].format(facing="left")+ assert p.count("move across the screen") + p.count("moving across the screen") == 1+ assert batch_mod.GAIT_HOLD_TEXT["side"] == "It stays in place as if on a treadmill."+ assert "keeps facing the viewer the whole time" in batch_mod.GAIT_HOLD_TEXT["front"]jump = batch_mod.build_prompt("front", "jump", None, motion="The knight hops twice.")assert all(text.split(",")[0] not in jump for text in batch_mod.GAIT_HOLD_TEXT.values())@@ -546,7 +555,9 @@ def test_a_diagonal_walk_is_pinned_and_named_as_an_isometric_heading() -> None:for state in ("walk", "run"):sentence = batch_mod.VIEW_MOTION_TEXT[(state, direction)].format(facing="right")p = batch_mod.build_prompt(direction, state, None)- assert p == batch_mod.PINNED_LOOP_TEXT.format(motion=sentence, view=batch_mod.VIEW_TEXT[direction])+ # the gait sentence keeps the image's angle itself: the view sentence is not said after it+ assert p == batch_mod.PINNED_LOOP_TEXT.replace(batch_mod.VIEW_SENTENCE, "").format(motion=sentence)+ assert "The character is seen from" not in p and p.count("three-quarter") == 1assert heading in sentence and "never turns into a side view" in sentenceassert batch_mod.pins_last_frame(state, direction)assert "turned exactly as in the image" in batch_mod.VIEW_TEXT[direction]