Skip to content

Generate clean 2D game sprites & animation atlases — component-row pipeline: state rows, alpha cleanup, frame extraction, runtime atlases. Codex/Claude skill.

13.5 KB
Raw Blame
# SPDX-License-Identifier: Apache-2.0
"""Handedness: which of the character's own sides an asymmetric item is on, seen from each view.

A watch on one wrist, a pin on one side of the head, a bag on one shoulder: turned over, the
picture puts the item on the other side. A character like that has its left-facing views drawn,
not mirrored, and each drawing is told where the item goes. The caller names the item and its
side once (`parse`: "the black smartwatch=left wrist"); the engine works out where that side is in
each view (`placement`) and says it in the still and clip prompts (`text`).

Where the character's own left side is, by view and facing (the side view and the three-quarter
views turn to `facing`; front and back have none):

| view | facing right | facing left |
|---|---|---|
| front | the picture's right | (same) |
| back | the picture's left | (same) |
| side | the far side, behind the body | the near side, toward the viewer |
| front_diagonal | the picture's right, on the far side | the picture's right, on the near side |
| back_diagonal | the picture's left, on the far side | the picture's left, on the near side |

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.
A walking character's far arm comes forward of the body with every step, and what its wrist or hand
wears shows then. An item there (`limb`: `SWINGING_ARM_PARTS`) is therefore drawn and filmed as
showing whenever that arm is out in front of the body, and the near arm stays bare; a walk or run
with one also says the arms swing (`ARMS_SWING_TEXT`). 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). Every other part (an ear, the
head, a tail, the body, a leg, a shoulder, the upper arm) keeps the 2.22.0 sentences: hidden on the far
side, and no arm sentence for it.
"""

from __future__ import annotations

from dataclasses import dataclass

from .facing import FACINGS

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")
# The one table of which parts get the arm sentences: the wrist and the parts around it, which a walking
# side view's far arm carries out in front of the body (the case filmed: a watch on the far wrist). A
# shoulder or an upper arm stays behind the body, and a leg's item showing as it steps forward was never
# filmed, so those keep the 2.22.0 sentences.
SWINGING_ARM_PARTS = frozenset({"wrist", "hand", "forearm", "elbow", "palm", "finger", "fingers", "thumb", "knuckles"})
# 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'"


@dataclass(frozen=True)
class Handed:
    """One asymmetric item: what it is, the character's own side it is on, and where on that side."""

    item: str
    side: str
    part: str = ""

    def where(self, side: str | None = None) -> str:
        side = side or self.side
        return f"{side} {self.part}" if self.part else f"{side} side"

    @property
    def other(self) -> str:
        return "right" if self.side == "left" else "left"


def limb(part: str) -> str | None:
    """"arm" when `part` is on the swinging end of an arm (`SWINGING_ARM_PARTS`: "wrist", "left hand"), else None
    (an ear, the head, a tail, a leg, a shoulder: on the far side these stay behind the body, and an item there
    gets no arm sentence)."""
    return "arm" if set(part.lower().split()) & SWINGING_ARM_PARTS 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:
        raise SystemExit(f"handedness: expected {SPEC_FORM}, got {spec!r}")
    item, rest = (s.strip() for s in spec.rsplit("=", 1))
    words = rest.split()
    if not item or not words or words[0].lower() not in SIDES:
        raise SystemExit(f"handedness: expected {SPEC_FORM}, got {spec!r}")
    return Handed(item=" ".join(item.split()), side=words[0].lower(), part=" ".join(words[1:]))


def parse_all(specs: list[str] | None) -> list[Handed]:
    return [parse(s) for s in (specs or [])]


def validate_view(view: str, facing: str | None) -> None:
    if view not in VIEWS:
        raise SystemExit(f"handedness: view must be one of {', '.join(VIEWS)}, got {view!r}")
    if view in LATERAL_VIEWS and facing not in FACINGS:
        raise SystemExit(f"handedness: the {view} view is turned right or left; say which (facing right|left)")


def placement(side: str, view: str, facing: str | None = None) -> dict[str, str | None]:
    """Where the character's own `side` is in `view`: `picture` (left / right of the picture, None in
    a side view) and `depth` (near / far from the viewer, None in a front or back view)."""
    if side not in SIDES:
        raise SystemExit(f"handedness: side must be left or right, got {side!r}")
    validate_view(view, facing)
    flip = {"left": "right", "right": "left"}
    # the own left side; the own right side is its mirror
    picture = {"front": "right", "front_diagonal": "right", "back": "left", "back_diagonal": "left"}.get(view)
    depth = None if view not in LATERAL_VIEWS else ("near" if facing == "left" else "far")
    if side == "right":
        picture = flip[picture] if picture else None
        depth = {"near": "far", "far": "near"}[depth] if depth else None
    return {"picture": picture, "depth": depth}


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, nearer the viewer, and {h.item} on it shows clearly.")
        lead = (f"Facing {facing}, the character's own {h.other} side is toward the viewer: the near {h.part or 'side'}, on the "
                f"side nearer the viewer, 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 "
                f"drawn at the {at['picture']} of the picture.")
    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}.")


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(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 arm in a walk or run (`gait`) shows what its wrist or hand wears each time it swings forward
    (`limb`), and the sentence says so: left unnamed, a watch on the far wrist was in no frame of the walk. The
    near arm 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 (any other part, 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":
        # "nearer the viewer", not "in front of the body": mid-stride, the far arm is the one in front of the body
        return f"The {part} nearer the viewer stays bare, exactly as in the image, for the whole clip." if other_bare else ""
    if view == "side":
        where = f"the {part} nearer the viewer"
    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},"
    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, 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 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:
        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) 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(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.")
    return " ".join(out)