Skip to content

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.py
index 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. The
own 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, str
return {"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 own
side 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 side
out.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.py
index 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: str
text: 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.py
index 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 quarter
of 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 every
taller than an outline, is another place the item shows. Specks of the marker's hue that a clip's colour
blocks 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 = 55
STRAP_ERODE = 0.004
STRAP_MIN_SIDE = 0.016
STRAP_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, faci
facing = None
expect = 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 None
rows, 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, faci
b["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 None
shown = 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 None
else {"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 1
diff --git a/sprite_gen/video/batch.py b/sprite_gen/video/batch.py
index 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_TEXT
else:
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_TEXT
else 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.text
if 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"] = needs
clip = item_dir / "clip.mp4"
clip_report = item_dir / "clip.report.json"
reuse_clip = clip.exists() and clip_report.exists() and not force
diff --git a/sprite_gen/video/clip_prompt.py b/sprite_gen/video/clip_prompt.py
index 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"] = needs
if 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 0
diff --git a/tests/gen/test_handedness.py b/tests/gen/test_handedness.py
index 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 text
if 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 text
if depth == "near" and view == "side":
assert "its left wrist is the near one" in text and "shows clearly" in text
if depth == "near" and view != "side":
@@ -93,6 +96,74 @@ def test_the_clip_sentence_anchors_to_the_image_and_never_names_a_hidden_item(vi
assert "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.py
index 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 way
MOTION = {
"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(na
assert "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(pr
def 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 refused
named = 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.text
for 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).text
assert "must be facing" not in text
assert 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 None
def 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)).text
assert retry.count("The subject must be facing right") == 1 and retry.count("Preserve the subject's design.") == 1
assert 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, mo
return 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().err
assert '[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.extra
diff --git a/tests/qa/test_handed_check.py b/tests/qa/test_handed_check.py
index 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: bool
arms = {"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 is
sliver = 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"] == 0
unchecked = 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")] * 3
report = 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.5
def test_unusable_inputs_are_refused() -> None:
diff --git a/tests/video/test_batch_handed.py b/tests/video/test_batch_handed.py
index 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"] == turned
direction = 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 over
diff --git a/tests/video/test_video_pipeline.py b/tests/video/test_video_pipeline.py
index 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") == 1
assert ", as if on a treadmill" in p
for 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") == 1
assert heading in sentence and "never turns into a side view" in sentence
assert batch_mod.pins_last_frame(state, direction)
assert "turned exactly as in the image" in batch_mod.VIEW_TEXT[direction]