Skip to content

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

feat(sway): the Sway layer on a cycle's frames at their own size (--frames, --out), on the breath (--breathe, --lag), a region moved whole (its flat share) and across apart from down (--gain-across); a cell no region moves is the cell as it was

Soohong Kim21ee376c8bf8
diff --git a/sprite_gen/cli.py b/sprite_gen/cli.py
index f105da8..5290791 100644
--- a/sprite_gen/cli.py
+++ b/sprite_gen/cli.py
@@ -382,7 +382,7 @@ COMMANDS: dict[str, tuple[str, Callable[[argparse.ArgumentParser], None], Callab
video_align.run,
),
"video-sway": (
- "The Sway layer: a soft part of a looping body sways with the body's motion, an ellipse of the strip moved as a damped mass on the body's own bob (after video-cycle-align). Old name video-follow, still run.",
+ "The Sway layer: a soft part of a looping body sways with the body's motion, an ellipse of the strip moved as a damped mass on the body's own bob (after video-cycle-align), or of a cycle's frames at their own size (--frames, --out); on the breath, late behind the Breathe layer's chest (--breathe). Old name video-follow, still run.",
video_sway.add_arguments,
video_sway.run,
),
diff --git a/sprite_gen/effects/anatomy.py b/sprite_gen/effects/anatomy.py
index 582f54f..8a8b2c0 100644
--- a/sprite_gen/effects/anatomy.py
+++ b/sprite_gen/effects/anatomy.py
@@ -94,6 +94,15 @@ class Anatomy:
"face": list(self.face) if self.face else None,
"warnings": list(self.warnings)}
+ @classmethod
+ def from_dict(cls, data: dict) -> "Anatomy":
+ """`as_dict` 가 쓴 한 벌을 다시 읽는다 (breathe.json 의 resolved.anatomy) — 잰 자리(`origin`, `neck_span`)는 실리지
+ 않으니 없다."""
+ keys = ("width", "height", "axis_x", "neck_row", "neck_source", "rigid_row", "rigid_source", "basis_row",
+ "torso_half", "max_half", "torso_source")
+ return cls(**{k: data[k] for k in keys}, face=tuple(data["face"]) if data.get("face") else None,
+ warnings=tuple(data.get("warnings") or ()))
+
# ── 실루엣 ──────────────────────────────────────────────────────────
diff --git a/sprite_gen/video/sway.py b/sprite_gen/video/sway.py
index 0e09b5a..35d786f 100644
--- a/sprite_gen/video/sway.py
+++ b/sprite_gen/video/sway.py
@@ -62,6 +62,26 @@ held, every region held refused; `--on-fold refuse` refuses). The record names t
What carries a region is the lay of the body's outline (`carry_basis`): whose pixels are inside the
carried ellipse is not read, and nothing here moves a region on a guess of it.
+
+A strip holds 64 cells and 32,000 px across at most, so a cycle of large frames is cut down to fit it. `--frames
+<folder> --out <new folder>` sways a cycle's frames themselves — a loop's `cycle/`, or what `sprite-gen breathe` wrote
+from it — at their own size and count, into a new folder of the same frames under the same names and `sway.json`, as
+`sprite-gen breathe` writes one. It is the same ask answered by the same code, cell for cell (`solve_cells`): a strip
+cut from those frames at scale 1 with none left out, its regions moved by its crop origin, moves its cells as these
+are moved, at the frame time its meta writes — rounded to hundredths of a ms, as `--fps` is read here.
+
+A breathing idle's head stays where it is and its body moves a pixel or two: read off the outline, that motion is
+whole-pixel steps, and the damped mass answers their jerks, not the breath. `--breathe <breathe.json>` sways the part
+on the breath instead: the Breathe layer's record of the breath the frames were given (`sprite-gen breathe` writes it
+beside them), its phases checked against those its config gives. The chest rises lift × w; the part rises as far, late
+by `--lag` of a breath (the time warp the Breathe layer's shoulders are late by), and lies the difference behind:
+offset = gain × lift × (w − w late), against the way the chest rises. Where the breath rests the offset is 0 — the first
+cell, and where the loop closes — and a cell whose every offset is 0 is the cell as it was, byte for byte.
+
+A region's fifth number, flat, is the share of the way from its centre to its rim that moves in full — the Breathe
+layer's chest weight (`breathe.flat_cos2`) — so a large part moves as one piece instead of pressed in at its middle;
+the fold rule and the floor read it by the radius left (1 − flat of it). `--gain-across` moves across by a gain of its
+own; a gain the fold rule or the floor lowers lowers both in proportion.
"""
from __future__ import annotations
@@ -83,6 +103,10 @@ from typing import Any
from PIL import Image
from sprite_gen._deps import np
+from sprite_gen.curate.curation import BREATHE_SMOOTH_SHAPE_RANGES, state_breathe
+from sprite_gen.effects import breathe as breathe_mod
+from sprite_gen.effects.anatomy import Anatomy
+from sprite_gen.frames import folder as folder_mod
from sprite_gen.spec.runio import atomic_write_text
from sprite_gen.util.gif_utils import save_clean_gif
from sprite_gen.video import loop as loop_mod
@@ -94,9 +118,15 @@ OLD_VERB = "video-follow" # the old name, kept: it runs this and says its own n
# what somebody saw under one way of reading is not taken for another's: a change that gives the same strip,
# regions and settings another carry, offset or picture takes a new name.
POLICY = "common-lay/damped-mass/cos2-bilinear/1"
+BREATH_POLICY = "common-lay/breath-late/cos2-bilinear/1" # the offset from the breath (`--breathe`), not the body's motion
FREQ_DEFAULT = 2.4 # Hz: a slow, soft part
ZETA_DEFAULT = 0.6 # damping ratio: it lags and settles, with no ringing
GAIN_DEFAULT = 2.5 # times the physical answer
+BREATH_GAIN_DEFAULT = 1.0 # times the breath's rise less the part's own, late by --lag: under the breath's own rise
+LAG_DEFAULT = 0.15 # of one breath: the part peaks this much of a breath after the chest
+LAG_MAX = 1 / math.pi # at it the late breath's time stops; past it, it runs backwards (breathe.smooth_shoulder_wave)
+FLAT_RANGE = BREATHE_SMOOTH_SHAPE_RANGES["chest_flat"] # a region's flat share: the Breathe layer's chest_flat, one weight
+FRAMES_RECORD = "sway.json" # beside the frames `--frames ... --out` writes
GAIN_MEASURED = 1.0 # the mass as measured: `--on-fold lower` does not go under it
GAIN_STEP = 0.01 # a lowered gain is a whole number of these, so the report's `gain` is the `--gain` to pass
ON_FOLD_MODES = ("refuse", "lower")
@@ -115,14 +145,43 @@ CARRY_BASIS = {"reading": "outline-lay", "region": "unverified"}
READ_ON = re.compile(r"[0-9a-f]{64}") # a strip's sha256, as `--read-on` names it
-def parse_region(text: str) -> tuple[float, float, float, float]:
+def parse_region(text: str) -> tuple[float, ...]:
+ try:
+ values = [float(v) for v in text.split(",")]
+ except ValueError as exc:
+ raise argparse.ArgumentTypeError(f"--region wants cx,cy,rx,ry[,flat] (four or five numbers), got {text!r}") from exc
+ if len(values) not in (4, 5):
+ raise argparse.ArgumentTypeError(f"--region wants cx,cy,rx,ry[,flat] (four or five numbers), got {text!r}")
try:
- cx, cy, rx, ry = (float(v) for v in text.split(","))
+ return region_of(values)
except ValueError as exc:
- raise argparse.ArgumentTypeError(f"--region wants cx,cy,rx,ry (four numbers), got {text!r}") from exc
- if rx <= 0 or ry <= 0:
- raise argparse.ArgumentTypeError(f"--region radii must be positive, got {text!r}")
- return cx, cy, rx, ry
+ raise argparse.ArgumentTypeError(f"--region {text!r}: {exc}") from exc
+
+
+def region_of(values) -> tuple[float, ...]:
+ """A region as the engine reads it: cx, cy, rx, ry, and its flat share where it has one. A flat share of 0 is no
+ flat share: the region is read, moved and recorded as one of four numbers."""
+ values = [float(v) for v in values]
+ if values[2] <= 0 or values[3] <= 0:
+ raise ValueError(f"radii must be positive, got {values[2]:g},{values[3]:g}")
+ if len(values) == 5:
+ if not FLAT_RANGE[0] <= values[4] <= FLAT_RANGE[1]: # a NaN is not
+ raise ValueError(f"flat is the share of the way from the centre to the rim that moves in full, "
+ f"{FLAT_RANGE[0]:g} to {FLAT_RANGE[1]:g}; got {values[4]:g}")
+ if values[4] == 0:
+ values = values[:4]
+ return tuple(values)
+
+
+def flat_of(region: tuple[float, ...]) -> float:
+ """A region's flat share: the share of the way from its centre to its rim that moves in full (0: none)."""
+ return region[4] if len(region) > 4 else 0.0
+
+
+def region_radius(region: tuple[float, ...]) -> float:
+ """The radius the fold rule reads a region by: its smaller radius, less its flat share — the weight falls from 1 to 0
+ over what is left, and steepest there."""
+ return min(region[2], region[3]) * (1 - flat_of(region))
def parse_read_on(text: str) -> str:
@@ -427,12 +486,13 @@ def lowered_gain(gain: float, reach_per_gain: float, radius: float) -> float:
return min(gain, round(steps * GAIN_STEP, 2))
-def stretch_per_gain(radii: tuple[float, float], across: np.ndarray, down: np.ndarray) -> tuple[float, int]:
+def stretch_per_gain(radii: tuple[float, float], across: np.ndarray, down: np.ndarray, flat: float = 0.0) -> tuple[float, int]:
"""How much of a pixel's area a region's move takes per unit of gain, at its worst cell, and that cell: the cos²
weight is steepest at π/2 over each radius, so a move (ox, oy) leaves 1 − (π/2)·hypot(ox/rx, oy/ry) of the area
- (`across`, `down`: the move at gain 1, per cell)."""
+ (`across`, `down`: the move at gain 1, per cell); a region with a flat share falls over what is left of each radius,
+ 1 − flat of it, and leaves 1 − (π/2)/(1 − flat)·hypot(ox/rx, oy/ry)."""
rx, ry = radii
- per_cell = (math.pi / 2) * np.hypot(across / rx, down / ry)
+ per_cell = (math.pi / 2) / (1 - flat) * np.hypot(across / rx, down / ry)
k = int(np.argmax(per_cell))
return float(per_cell[k]), k
@@ -460,13 +520,14 @@ def _sample(premultiplied: np.ndarray, sx: np.ndarray, sy: np.ndarray) -> np.nda
return (a * (1 - fx) + b * fx) * (1 - fy) + (c * (1 - fx) + d * fx) * fy
-def region_weight(xx: np.ndarray, yy: np.ndarray, region: tuple[float, float, float, float],
+def region_weight(xx: np.ndarray, yy: np.ndarray, region: tuple[float, ...],
shift: tuple[float, float]) -> np.ndarray:
"""Per pixel of a cell, how much of a region's move it takes: 1 at the centre of the ellipse carried by
- `shift`, 0 at its rim (cos²) and outside it. The pixels a region covers are those where this is over 0."""
- cx, cy, rx, ry = region
+ `shift` — and over its flat share of the way to the rim, where it has one — 0 at its rim (cos²) and outside it:
+ the Breathe layer's chest weight (`breathe.flat_cos2`). The pixels a region covers are those where this is over 0."""
+ cx, cy, rx, ry = region[:4]
r = np.sqrt(((xx - cx - shift[0]) / rx) ** 2 + ((yy - cy - shift[1]) / ry) ** 2)
- return np.where(r < 1, np.cos(r * math.pi / 2) ** 2, 0)
+ return breathe_mod.flat_cos2(r, flat_of(region))
def move_field(xx: np.ndarray, yy: np.ndarray, moves: list[tuple[list[tuple[float, float, float, float]], tuple[float, float]]],
@@ -494,7 +555,10 @@ def move_regions(cell: Image.Image, moves: list[tuple[list[tuple[float, float, f
The groups' offsets are one motion times their gains, so where regions of different groups
overlap the larger move wins: the move is the largest of the groups' weighted moves, which is
- nowhere steeper than the steepest group's own."""
+ nowhere steeper than the steepest group's own. Where every offset is 0 the cell is as it was, byte for
+ byte — the colour under its clear pixels too, which a move clears."""
+ if all(dx == 0 and dy == 0 for _, (dx, dy) in moves):
+ return cell.copy()
src = np.asarray(cell.convert("RGBA"), dtype=np.float32)
h, w = src.shape[:2]
yy, xx = np.mgrid[0:h, 0:w].astype(np.float32)
@@ -514,22 +578,154 @@ def move_regions(cell: Image.Image, moves: list[tuple[list[tuple[float, float, f
return Image.fromarray(out, "RGBA")
+@dataclass(frozen=True, eq=False)
+class Breath:
+ """The breath a sway follows (`--breathe`): the Breathe layer's record of it — `sprite-gen breathe` writes
+ breathe.json beside the frames it breathed — read and checked, and how late the part follows it (`--lag`)."""
+
+ path: Path
+ sha256: str # of the record's bytes
+ phases: list[float] # per cell, the breath's phase
+ beat: dict[str, Any] # the breath count, or the cell of each in-breath's peak
+ lift: float # px the chest rises at the top of an in-breath (breathe.smooth_lift)
+ heading: float # degrees from straight up the chest rises toward (its chest_dir)
+ lag: float # of one breath
+
+ def unit(self) -> tuple[np.ndarray, np.ndarray]:
+ """Per cell, the part's offset from where the breath carries it at gain 1, across and down: the chest rises
+ `lift` × w (breathe.smooth_wave), the part as far late by `lag` (the time warp the Breathe layer's shoulders are
+ late by, breathe.smooth_shoulder_wave), and the part lies the difference behind, against the way the chest
+ rises. 0 where the breath rests — its first cell, and where the loop closes."""
+ share = np.asarray([breathe_mod.smooth_wave(p) - breathe_mod.smooth_shoulder_wave(p, self.lag) for p in self.phases])
+ heading = math.radians(self.heading)
+ return self.lift * share * -math.sin(heading) + 0.0, self.lift * share * math.cos(heading)
+
+ def record(self) -> dict[str, Any]:
+ return {"kind": "breath", "breathe_sha256": self.sha256, "lag": self.lag, "lift_px": round(self.lift, 4),
+ "heading_deg": self.heading, **self.beat}
+
+
+def read_breath(path: Path, lag: float | None, *, verb: str = VERB) -> Breath:
+ """The breath of a Breathe layer's record (breathe.json): a smooth breath, whose phases are the ones its config
+ gives after the sidecar's checks (`state_breathe`, `breathe.fit_breathe_pattern`), whose chest rises as the anatomy it
+ was baked with says. A record written by hand for a breath made elsewhere is read alike and must say the same."""
+ lag = LAG_DEFAULT if lag is None else float(lag)
+ if not 0 < lag < LAG_MAX: # a NaN is not
+ raise SystemExit(f"{verb}: --lag is the share of a breath the part is late by, above 0 and under 1/π ({LAG_MAX:.4f}): at "
+ f"1/π the late breath stops, past it it runs backwards; got {lag:g}")
+ path = Path(path).expanduser()
+ try:
+ data = path.read_bytes()
+ report = json.loads(data.decode("utf-8"))
+ except (OSError, ValueError) as exc:
+ raise SystemExit(f"{verb}: --breathe {path}: not read ({exc})") from exc
+ if not (isinstance(report, dict) and isinstance(report.get("config"), dict) and isinstance(report.get("phases"), list)
+ and isinstance((report.get("resolved") or {}).get("anatomy"), dict)):
+ raise SystemExit(f"{verb}: --breathe {path}: not a Breathe layer's record — sprite-gen breathe writes config, phases "
+ "and resolved.anatomy into breathe.json")
+ mode = report["config"].get("mode") or "pixel"
+ if mode != "smooth":
+ raise SystemExit(f"{verb}: --breathe {path}: a {mode} breath — the part follows a smooth breath, which rests at the "
+ "first cell (a pixel breath's travelling wave moves it)")
+ try:
+ cfg = state_breathe({"states": {"frames": {"breathe": report["config"]}}}, "frames")
+ except SystemExit as exc:
+ raise SystemExit(f"{verb}: --breathe {path}: its config is refused as a sidecar's would be — {exc}") from exc
+ phases = report["phases"]
+ if report.get("frames") != len(phases):
+ raise SystemExit(f"{verb}: --breathe {path}: it says {report.get('frames')} frames and holds {len(phases)} phases")
+ if breathe_mod.fit_breathe_pattern(len(phases), cfg) != phases:
+ raise SystemExit(f"{verb}: --breathe {path}: its phases are not the ones its config gives for {len(phases)} cells "
+ "(breathe.fit_breathe_pattern) — the record was changed after it was written")
+ try:
+ anatomy = Anatomy.from_dict(report["resolved"]["anatomy"])
+ except (KeyError, TypeError) as exc:
+ raise SystemExit(f"{verb}: --breathe {path}: its resolved.anatomy is not one sprite-gen breathe writes ({exc})") from exc
+ beat = {"breath_peaks": list(cfg["breath_peaks"])} if cfg.get("breath_peaks") else {"breaths": cfg["breaths"]}
+ return Breath(path, hashlib.sha256(data).hexdigest(), [float(p) for p in phases], beat,
+ breathe_mod.smooth_lift(anatomy, cfg), float(cfg["chest_dir"]), lag)
+
+
+@dataclass(frozen=True, eq=False)
+class Ask:
+ """What a sway is asked, read and checked: the regions and how they move. What it is asked of — a loop's strip
+ (`Request`) or a folder of a cycle's frames (`sway_frames`) — is apart from it."""
+
+ regions: list[tuple[float, ...]]
+ gain: float
+ freq: float | None # the damped mass's; None on the breath
+ zeta: float | None
+ on_fold: str
+ read_on: str | None = None # the sha256 of the strip as cut the regions were read on; None: this strip's, as ever
+ stretch_floor: float | None = None # the least area a moved pixel keeps; None: the fold rule alone
+ gain_across: float | None = None # the gain across asked; None: --gain, across as down
+ breath: Breath | None = None # the breath the part follows; None: the body's motion, answered by the damped mass
+
+ @property
+ def across(self) -> float:
+ """The across move's gain over the down move's: `--gain-across` over `--gain`, 1 without it."""
+ return 1.0 if self.gain_across is None or self.gain == 0 else self.gain_across / self.gain
+
+ @property
+ def policy(self) -> str:
+ return POLICY if self.breath is None else BREATH_POLICY
+
+
+def read_ask(regions: list[tuple[float, ...]], *, gain: float | None = None, freq: float | None = None,
+ zeta: float | None = None, on_fold: str = "refuse", read_on: str | None = None,
+ stretch_floor: float | None = None, breathe: Path | None = None, lag: float | None = None,
+ gain_across: float | None = None, verb: str = VERB) -> Ask:
+ """A sway's ask, read and checked. A number left out (None) is its default: the damped mass's gain, freq and zeta,
+ or, on the breath (`breathe`), the breath's gain and lag."""
+ # The numbers go into the record, which is JSON, and into the cells' arithmetic: a numpy number from a
+ # caller (an int64 has no JSON form) is read as the float the command line gives, so every caller of the
+ # same numbers writes the same strip and record.
+ try:
+ regions = [region_of(region) for region in regions]
+ except ValueError as exc:
+ raise SystemExit(f"{verb}: --region {exc}") from exc
+ if not regions:
+ raise SystemExit(f"{verb}: at least one --region cx,cy,rx,ry")
+ if breathe is None and lag is not None:
+ raise SystemExit(f"{verb}: --lag is how late the part follows the breath; it needs --breathe")
+ if breathe is not None and (freq is not None or zeta is not None):
+ raise SystemExit(f"{verb}: --freq and --zeta are the damped mass's; on the breath (--breathe) the part is late by --lag")
+ gain = (GAIN_DEFAULT if breathe is None else BREATH_GAIN_DEFAULT) if gain is None else float(gain)
+ if breathe is None:
+ freq = FREQ_DEFAULT if freq is None else float(freq)
+ zeta = ZETA_DEFAULT if zeta is None else float(zeta)
+ if gain < 0 or (breathe is None and (freq <= 0 or not 0 < zeta)):
+ raise SystemExit(f"{verb}: --gain must be 0 or more, --freq and --zeta above 0")
+ if gain_across is not None:
+ gain_across = float(gain_across)
+ if not gain_across >= 0: # a NaN is not
+ raise SystemExit(f"{verb}: --gain-across must be 0 or more")
+ if gain == 0 and gain_across != 0:
+ raise SystemExit(f"{verb}: --gain 0 leaves the cells as they were, and --gain-across is read against it")
+ if on_fold not in ON_FOLD_MODES:
+ raise SystemExit(f"{verb}: unknown --on-fold {on_fold!r}; expected one of {', '.join(ON_FOLD_MODES)}")
+ if read_on is not None and not READ_ON.fullmatch(str(read_on)):
+ raise SystemExit(f"{verb}: --read-on wants the sha256 of the strip the regions were read on (64 lowercase "
+ f"hexadecimal digits), got {read_on!r}")
+ if stretch_floor is not None:
+ stretch_floor = float(stretch_floor)
+ if not 0 <= stretch_floor < 1: # a NaN is neither
+ raise SystemExit(f"{verb}: --stretch-floor is the least area a moved pixel keeps, at least 0 and under 1; got {stretch_floor:g}")
+ breath = None if breathe is None else read_breath(breathe, lag, verb=verb)
+ return Ask(regions, gain, freq, zeta, on_fold, None if read_on is None else str(read_on), stretch_floor, gain_across,
+ breath)
+
+
@dataclass(frozen=True, eq=False)
class Request:
- """A follow-through asked of a loop directory, read and checked; nothing is written by reading it."""
+ """A sway asked of a loop directory, read and checked; nothing is written by reading it."""
loop_dir: Path
name: str
meta_path: Path
meta_bytes: bytes
meta: dict[str, Any]
- regions: list[tuple[float, float, float, float]]
- gain: float
- freq: float
- zeta: float
- on_fold: str
- read_on: str | None = None # the sha256 of the strip as cut the regions were read on; None: this strip's, as ever
- stretch_floor: float | None = None # the least area a moved pixel keeps; None: the fold rule alone
+ ask: Ask
@property
def strip_path(self) -> Path:
@@ -540,15 +736,11 @@ class Request:
return self.loop_dir / SOURCE
-def read_request(loop_dir: Path, regions: list[tuple[float, float, float, float]], *, gain: float = GAIN_DEFAULT,
- freq: float = FREQ_DEFAULT, zeta: float = ZETA_DEFAULT, on_fold: str = "refuse", verb: str = VERB,
- read_on: str | None = None, stretch_floor: float | None = None) -> Request:
+def read_request(loop_dir: Path, regions: list[tuple[float, ...]], *, gain: float | None = None,
+ freq: float | None = None, zeta: float | None = None, on_fold: str = "refuse", verb: str = VERB,
+ read_on: str | None = None, stretch_floor: float | None = None, breathe: Path | None = None,
+ lag: float | None = None, gain_across: float | None = None) -> Request:
loop_dir = loop_dir.expanduser().resolve()
- # The numbers go into the record, which is JSON, and into the cells' arithmetic: a numpy number from a
- # caller (an int64 has no JSON form) is read as the float the command line gives, so every caller of the
- # same numbers writes the same strip and record.
- regions = [tuple(float(v) for v in region) for region in regions]
- gain, freq, zeta = float(gain), float(freq), float(zeta)
metas = sorted(loop_dir.glob("*.strip.json"))
if len(metas) != 1:
raise SystemExit(f"{verb}: {loop_dir}: expected one <name>.strip.json from video-loop, found {len(metas)}")
@@ -558,31 +750,19 @@ def read_request(loop_dir: Path, regions: list[tuple[float, float, float, float]
meta = json.loads(meta_bytes.decode("utf-8"))
if meta.get("kind") == "one-shot" or meta.get("loop") is False:
raise SystemExit(f"{verb}: a one-shot plays once; the follow-through is a loop's steady state")
- if not regions:
- raise SystemExit(f"{verb}: at least one --region cx,cy,rx,ry")
- if gain < 0 or freq <= 0 or not 0 < zeta:
- raise SystemExit(f"{verb}: --gain must be 0 or more, --freq and --zeta above 0")
- if on_fold not in ON_FOLD_MODES:
- raise SystemExit(f"{verb}: unknown --on-fold {on_fold!r}; expected one of {', '.join(ON_FOLD_MODES)}")
- if read_on is not None and not READ_ON.fullmatch(str(read_on)):
- raise SystemExit(f"{verb}: --read-on wants the sha256 of the strip the regions were read on (64 lowercase "
- f"hexadecimal digits), got {read_on!r}")
- if stretch_floor is not None:
- stretch_floor = float(stretch_floor)
- if not 0 <= stretch_floor < 1: # a NaN is neither
- raise SystemExit(f"{verb}: --stretch-floor is the least area a moved pixel keeps, at least 0 and under 1; got {stretch_floor:g}")
- return Request(loop_dir, name, meta_path, meta_bytes, meta, regions, gain, freq, zeta, on_fold,
- None if read_on is None else str(read_on), stretch_floor)
+ ask = read_ask(regions, gain=gain, freq=freq, zeta=zeta, on_fold=on_fold, read_on=read_on, stretch_floor=stretch_floor,
+ breathe=breathe, lag=lag, gain_across=gain_across, verb=verb)
+ return Request(loop_dir, name, meta_path, meta_bytes, meta, ask)
@dataclass(frozen=True, eq=False)
class Answer:
- """What a request comes to on a strip: the body's motion, each region's gain, and every cell's move.
+ """What an ask comes to on a cycle's cells: the body's motion, each region's gain, and every cell's move.
- `video-follow` writes it over the loop; `video-follow-inspect` writes it down and changes nothing. Both
- read the carry, the offsets and the moved cells here, and nowhere else."""
+ `video-sway` writes it over the loop or into a new folder of frames; `video-sway-inspect` writes it down and
+ changes nothing. All of them read the carry, the offsets and the moved cells here, and nowhere else."""
- request: Request
+ ask: Ask
cells: list[Image.Image]
cols: np.ndarray # per cell, how far its body lies from cell 0's: across
rows: np.ndarray # and down
@@ -601,7 +781,7 @@ class Answer:
dx: np.ndarray
dy: np.ndarray
reach: float
- groups: list[tuple[list[tuple[float, float, float, float]], tuple[np.ndarray, np.ndarray]]]
+ groups: list[tuple[list[tuple[float, ...]], tuple[np.ndarray, np.ndarray]]]
read_on: dict[str, Any] | None = None # how the strip the regions were read on stands to this one (`--read-on`)
stretch: dict[str, Any] | None = None # the floor asked, and what it did to each region (`--stretch-floor`)
@@ -612,24 +792,28 @@ class Answer:
return self.cols[k], self.rows[k]
return self.cols[k] - self.cols[0], self.rows[k] - self.rows[0]
- def moves_in(self, k: int) -> list[tuple[list[tuple[float, float, float, float]], tuple[float, float]]]:
+ def moves_in(self, k: int) -> list[tuple[list[tuple[float, ...]], tuple[float, float]]]:
"""Cell k's groups of regions, each with its offset in that cell."""
return [(group, (mx[k], my[k])) for group, (mx, my) in self.groups]
def moved(self, k: int) -> Image.Image:
return move_regions(self.cells[k], self.moves_in(k), self.carry(k))
- def record(self) -> dict[str, Any]:
- """The follow-through as the strip's meta records it; `video-follow` adds its animations' checks."""
- request, requested = self.request, self.requested
+ def record(self, source: str = SOURCE) -> dict[str, Any]:
+ """The sway as the strip's meta records it, `source` the strip as cut kept beside it (`video-sway` adds its
+ animations' checks); a frames folder's records it alike, the folder its source."""
+ ask, requested = self.ask, self.requested
+ drive = ({"freq_hz": ask.freq, "zeta": ask.zeta, "harmonics": HARMONICS} if ask.breath is None
+ else {"drive": ask.breath.record()})
+ across = ({} if ask.gain_across is None else
+ {"gain_across": round(self.gain * ask.across, 4), "gain_across_requested": ask.gain_across})
return {
- "regions": [list(r) for r in request.regions], "gain": self.gain, "freq_hz": request.freq, "zeta": request.zeta,
- "harmonics": HARMONICS,
- "source": SOURCE, "body_px": self.height0, "body_worn_px": self.worn,
+ "regions": [list(r) for r in ask.regions], "gain": self.gain, **across, **drive,
+ "source": source, "body_px": self.height0, "body_worn_px": self.worn,
"body_bob_px": [round(float(np.ptp(self.cols)), 2), round(float(np.ptp(self.rows)), 2)],
"dx_px": np.round(self.dx, 2).tolist(), "dy_px": np.round(self.dy, 2).tolist(),
"reach_px": round(self.reach, 2),
- "gain_requested": requested, "on_fold": request.on_fold,
+ "gain_requested": requested, "on_fold": ask.on_fold,
"fold": {
"lowered": any(g != requested for g in self.gains), "ratio": round(max(self.ratios), 3),
"reach_requested_px": round(self.reach_requested, 2), "reach_per_gain_px": round(self.reach_per_gain, 3),
@@ -647,43 +831,80 @@ class Answer:
def solve(request: Request, strip: Image.Image, *, strip_name: str, verb: str = VERB,
strip_sha256: str | None = None) -> Answer:
"""The answer to `request` on `strip`, the loop's strip as cut (an RGBA picture; `strip_name` names its file
- in a refusal, `strip_sha256` is its file's, read where the request names the strip its regions were read on).
- Reads nothing else and writes nothing."""
- meta, regions = request.meta, request.regions
- gain, freq, zeta, on_fold = request.gain, request.freq, request.zeta, request.on_fold
+ in a refusal, `strip_sha256` is its file's, read where the request names the strip its regions were read on): its
+ cells answered as any cycle's cells are (`solve_cells`), at the frame time its meta records. Reads nothing else and
+ writes nothing."""
+ meta, ask = request.meta, request.ask
n, w, h = int(meta["frames"]), int(meta["w"]), int(meta["h"])
if strip.size != (w * n, h):
raise SystemExit(f"{verb}: {strip_name} is {strip.size[0]}x{strip.size[1]}, the strip meta says {w * n}x{h}; "
"cut the loop again (video-loop)")
cells = _cells(strip, n, w, h)
read_on = None
- if request.read_on is not None:
+ if ask.read_on is not None:
if strip_sha256 is None:
raise ValueError("solve: a request with read_on needs the strip's sha256")
- read_on = {"sha256": request.read_on, "relation": read_on_relation(meta, strip_sha256, request.read_on, verb=verb)}
- for cx, cy, rx, ry in regions:
- if not (0 <= cx < w and 0 <= cy < h):
- raise SystemExit(f"{verb}: --region centre {cx:g},{cy:g} is outside the {w}x{h} cell")
- fps = 1000.0 / float(meta["delay_ms"])
- if read_on is not None and read_on["relation"] == "transported":
+ read_on = {"sha256": ask.read_on, "relation": read_on_relation(meta, strip_sha256, ask.read_on, verb=verb)}
+
+ def transported() -> tuple[np.ndarray, np.ndarray, int, list[int]]:
# The cut's own reading, cell for cell: the regions are where they were read, on the cut's cell 0, and the
# damped mass answers that motion in this loop's order, length and frame time.
- rows, cols, height0, worn, cut_cells = transported_motion(meta, cells, request.read_on, verb=verb)
- read_on |= {"policy": TRANSPORT_POLICY, "cut_cells": cut_cells}
+ rows, cols, height0, worn, cut_cells = transported_motion(meta, cells, ask.read_on, verb=verb)
+ read_on.update(policy=TRANSPORT_POLICY, cut_cells=cut_cells)
+ return rows, cols, height0, worn
+
+ carried = read_on is not None and read_on["relation"] == "transported"
+ return solve_cells(ask, cells, float(meta["delay_ms"]), verb=verb, read_on=read_on,
+ read_body=transported if carried else None)
+
+
+def _unit_move(ask: Ask, rows: np.ndarray, cols: np.ndarray, frame_ms: float | None) -> tuple[np.ndarray, np.ndarray]:
+ """Per cell, the part's offset at gain 1, across and down, the across times its share of the gain (`Ask.across`):
+ on the breath its offset from the breath (`Breath.unit`), or else the damped mass's answer to the body's motion at
+ the cells' frame time."""
+ if ask.breath is not None:
+ across, down = ask.breath.unit()
+ else:
+ fps = 1000.0 / frame_ms
+ across = sway_offsets(cols, fps, freq=ask.freq, zeta=ask.zeta, gain=1.0)
+ down = sway_offsets(rows, fps, freq=ask.freq, zeta=ask.zeta, gain=1.0)
+ return ask.across * across, down
+
+
+def solve_cells(ask: Ask, cells: list[Image.Image], frame_ms: float | None, *, verb: str = VERB,
+ read_on: dict[str, Any] | None = None, read_body: Any = None) -> Answer:
+ """The answer to `ask` on a cycle's cells (RGBA pictures of one size, in order; `frame_ms` one frame's time, which
+ the damped mass alone reads): a loop's strip cut into its cells (`solve`), or a folder of the cycle's frames
+ (`sway_frames`) — one answer, whatever the cells came from. The body's motion is read on the cells (`body_motion`)
+ unless `read_body` gives it (a reading carried from the cut, `--read-on`). Reads nothing else and writes nothing."""
+ regions, gain, on_fold = ask.regions, ask.gain, ask.on_fold
+ w, h = cells[0].size
+ for cx, cy, *_ in regions:
+ if not (0 <= cx < w and 0 <= cy < h):
+ raise SystemExit(f"{verb}: --region centre {cx:g},{cy:g} is outside the {w}x{h} cell")
+ if ask.breath is not None and len(ask.breath.phases) != len(cells):
+ raise SystemExit(f"{verb}: --breathe {ask.breath.path} breathes {len(ask.breath.phases)} cells and there are "
+ f"{len(cells)} to sway: the part follows the breath cell for cell")
+ if read_body is not None:
+ rows, cols, height0, worn = read_body()
else:
try:
rows, cols, height0, worn = body_motion(cells)
except ValueError as exc:
raise SystemExit(f"{verb}: {exc}") from exc
- dy = sway_offsets(rows, fps, freq=freq, zeta=zeta, gain=gain)
- dx = sway_offsets(cols, fps, freq=freq, zeta=zeta, gain=gain)
+ across, down = _unit_move(ask, rows, cols, frame_ms)
+
+ def move(g: float) -> tuple[np.ndarray, np.ndarray]:
+ """The offset per cell at gain g, across and down: g times the move at gain 1."""
+ return g * across, g * down
+
+ dx, dy = move(gain)
reach = float(np.max(np.hypot(dx, dy)))
- radii = [min(rx, ry) for _, _, rx, ry in regions]
+ radii = [region_radius(region) for region in regions]
smallest = min(radii)
requested, reach_requested = gain, reach
# The offset is the gain times the answer at gain 1, so one move decides every gain.
- reach_per_gain = float(np.max(np.hypot(sway_offsets(cols, fps, freq=freq, zeta=zeta, gain=1.0),
- sway_offsets(rows, fps, freq=freq, zeta=zeta, gain=1.0))))
+ reach_per_gain = float(np.max(np.hypot(across, down)))
gains, held = [requested] * len(regions), [False] * len(regions)
if fold_ratio(reach, smallest) >= 1:
if on_fold == "refuse":
@@ -705,35 +926,33 @@ def solve(request: Request, strip: Image.Image, *, strip_name: str, verb: str =
f"{reach_per_gain:.1f} px; the largest gain that does not fold is {gains[k]:g}); give the region larger radii")
gains = [0.0 if hold else g for g, hold in zip(gains, held)]
stretch = None
- if request.stretch_floor is not None:
- gains, held, stretch = _keep_floor(request, radii, gains, held, (sway_offsets(cols, fps, freq=freq, zeta=zeta, gain=1.0),
- sway_offsets(rows, fps, freq=freq, zeta=zeta, gain=1.0)), verb)
+ if ask.stretch_floor is not None:
+ gains, held, stretch = _keep_floor(ask, radii, gains, held, (across, down), verb)
# One move per gain: a region's offset is its gain times the answer at gain 1. The strip's `gain`
# is the largest any region moves by, and `dx_px`/`dy_px` and `reach_px` are that gain's.
- moves = {g: (sway_offsets(cols, fps, freq=freq, zeta=zeta, gain=g), sway_offsets(rows, fps, freq=freq, zeta=zeta, gain=g))
- for g, hold in zip(gains, held) if not hold}
- reaches = {g: float(np.max(np.hypot(*move))) for g, move in moves.items()}
+ moves = {g: move(g) for g, hold in zip(gains, held) if not hold}
+ reaches = {g: float(np.max(np.hypot(*offset))) for g, offset in moves.items()}
gain = max(moves)
dx, dy = moves[gain]
reach = reaches[gain]
ratios = [0.0 if hold else fold_ratio(reaches[g], radius) for radius, g, hold in zip(radii, gains, held)]
- groups = [([r for r, rg, hold in zip(regions, gains, held) if rg == g and not hold], move) for g, move in moves.items()]
- return Answer(request, cells, cols, rows, height0, worn, requested, reach_requested, reach_per_gain, radii, gains, held,
+ groups = [([r for r, rg, hold in zip(regions, gains, held) if rg == g and not hold], offset) for g, offset in moves.items()]
+ return Answer(ask, cells, cols, rows, height0, worn, requested, reach_requested, reach_per_gain, radii, gains, held,
ratios, moves, reaches, gain, dx, dy, reach, groups, read_on, stretch)
-def _keep_floor(request: Request, radii: list[float], gains: list[float], held: list[bool],
+def _keep_floor(ask: Ask, radii: list[float], gains: list[float], held: list[bool],
move: tuple[np.ndarray, np.ndarray], verb: str) -> tuple[list[float], list[bool], dict[str, Any]]:
"""The fold rule's gains (`gains`, 0 where `held`) lowered where a region's move would leave a pixel less than
`--stretch-floor` of its area (`move`: across and down per cell at gain 1), and the record of it. A region is never
raised; one the floor takes under GAIN_MEASURED is held as the fold rule holds one, and the strip is refused when
every region is — or, under `--on-fold refuse`, when the floor lowers any."""
- floor, requested = request.stretch_floor, request.gain
- per = [stretch_per_gain((rx, ry), *move) for _, _, rx, ry in request.regions]
+ floor, requested = ask.stretch_floor, ask.gain
+ per = [stretch_per_gain((region[2], region[3]), *move, flat=flat_of(region)) for region in ask.regions]
floored = [floor_gain(requested, q, floor) for q, _ in per]
lowered = [g if hold else min(g, f) for g, f, hold in zip(gains, floored, held)]
by_floor = [not hold and g < rule for g, rule, hold in zip(lowered, gains, held)]
- if any(by_floor) and request.on_fold == "refuse":
+ if any(by_floor) and ask.on_fold == "refuse":
least = min(1 - requested * q for (q, _), by in zip(per, by_floor) if by)
raise SystemExit(f"{verb}: --gain {requested:g} leaves a moved pixel {least:.3f} of its area, under --stretch-floor {floor:g}; "
"lower --gain, pass --on-fold lower or give the region larger radii")
@@ -752,12 +971,13 @@ def _keep_floor(request: Request, radii: list[float], gains: list[float], held:
}
-def sway_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]], *, gain: float = GAIN_DEFAULT,
- freq: float = FREQ_DEFAULT, zeta: float = ZETA_DEFAULT, board: Path | None = None,
+def sway_loop(loop_dir: Path, regions: list[tuple[float, ...]], *, gain: float | None = None,
+ freq: float | None = None, zeta: float | None = None, board: Path | None = None,
on_fold: str = "refuse", read_on: str | None = None, stretch_floor: float | None = None,
+ breathe: Path | None = None, lag: float | None = None, gain_across: float | None = None,
verb: str = VERB) -> dict[str, Any]:
request = read_request(loop_dir, regions, gain=gain, freq=freq, zeta=zeta, on_fold=on_fold, read_on=read_on,
- stretch_floor=stretch_floor, verb=verb)
+ stretch_floor=stretch_floor, breathe=breathe, lag=lag, gain_across=gain_across, verb=verb)
loop_dir, name, meta_path, meta = request.loop_dir, request.name, request.meta_path, request.meta
strip_path = request.strip_path
source = request.source_path
@@ -804,6 +1024,42 @@ def sway_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]],
return {"strip": str(strip_path), **record}
+def sway_frames(frames: Path, out: Path, regions: list[tuple[float, ...]], *, fps: float | None = None,
+ gain: float | None = None, freq: float | None = None, zeta: float | None = None,
+ board: Path | None = None, on_fold: str = "refuse", read_on: str | None = None,
+ stretch_floor: float | None = None, breathe: Path | None = None, lag: float | None = None,
+ gain_across: float | None = None, verb: str = VERB) -> dict[str, Any]:
+ """The sway of a folder of a cycle's frames — a loop's `cycle/`, or what `sprite-gen breathe` wrote from it — at their
+ own size and count, past the strip's caps on cells and width: the same frames under the same names, the regions
+ (in frame pixels) moved, and `sway.json` beside them, written whole into a new folder (`frames.folder`); the frames
+ folder is read and not written. Cell for cell it is the strip's sway (`solve_cells`): a strip cut from these frames
+ at scale 1, none left out, its regions moved by its crop origin, at the frame time its meta writes (`frame_ms` of
+ `--fps`), moves its cells as these are moved."""
+ ask = read_ask(regions, gain=gain, freq=freq, zeta=zeta, on_fold=on_fold, read_on=read_on, stretch_floor=stretch_floor,
+ breathe=breathe, lag=lag, gain_across=gain_across, verb=verb)
+ if ask.read_on is not None:
+ raise SystemExit(f"{verb}: --read-on names the strip as cut that the regions were read on; frames are read as they are")
+ if ask.breath is not None and fps is not None:
+ raise SystemExit(f"{verb}: --fps is the damped mass's frame time; on the breath (--breathe) the part keeps the breath's beat")
+ frames = Path(frames)
+ folder = folder_mod.open_frames(frames, Path(out), verb)
+ cells = folder.images
+ frame_ms = None
+ if ask.breath is None:
+ frame_ms = folder_mod.cycle_frame_ms(frames, len(cells), fps, verb)
+ if frame_ms is None:
+ raise SystemExit(f"{verb}: --frames {frames}: the damped mass answers the body's motion in time — give --fps (a "
+ "video-loop cycle/ folder has its own in the loop's strip meta), or sway on the breath (--breathe)")
+ answer = solve_cells(ask, cells, frame_ms, verb=verb)
+ moved = [answer.moved(k) for k in range(len(cells))]
+ record = {"frames": len(cells), "frame_ms": frame_ms, **answer.record(source=str(frames))}
+ folder_mod.publish(folder, moved, FRAMES_RECORD, record)
+ if board is not None:
+ _board(cells, moved, answer.dy, board)
+ record["board"] = str(board)
+ return {"out": str(folder.out), **record}
+
+
def _board(before: list[Image.Image], after: list[Image.Image], dy: np.ndarray, path: Path) -> None:
"""Before and after, side by side on white, at the frames where the part sits lowest and highest."""
picks = [int(np.argmax(dy)), int(np.argmin(dy))]
@@ -820,18 +1076,37 @@ def _board(before: list[Image.Image], after: list[Image.Image], dy: np.ndarray,
board.save(path)
-def add_request_arguments(parser: argparse.ArgumentParser) -> None:
- """What a sway is asked with; `video-sway-inspect` takes the same and is asked alike."""
- parser.add_argument("--loop-dir", required=True, type=Path, help="a video-loop output directory (after video-cycle-align, if the set is aligned)")
+LOOP_DIR_HELP = "a video-loop output directory (after video-cycle-align, if the set is aligned)"
+
+
+def add_request_arguments(parser: argparse.ArgumentParser, *, loop_dir: bool = True) -> None:
+ """What a sway is asked with; `video-sway-inspect` takes the same of a loop directory and is asked alike
+ (`video-sway` puts `--loop-dir` beside `--frames` itself)."""
+ if loop_dir:
+ parser.add_argument("--loop-dir", required=True, type=Path, help=LOOP_DIR_HELP)
parser.add_argument("--region", action="append", type=parse_region, required=True,
- help="cx,cy,rx,ry: an ellipse over the soft part in the strip's first cell, in cell pixels (repeatable)")
- parser.add_argument("--gain", type=float, default=GAIN_DEFAULT, help=f"times the physical answer (default {GAIN_DEFAULT:g}; 1 is the mass as measured, 0 leaves the strip as it was)")
+ help="cx,cy,rx,ry[,flat]: an ellipse over the soft part in the first cell, in cell pixels (repeatable); flat, "
+ f"{FLAT_RANGE[0]:g} to {FLAT_RANGE[1]:g}, is the share of the way from its centre to its rim that moves in "
+ "full, the Breathe layer's chest_flat (0 or left out: the weight falls from the centre)")
+ parser.add_argument("--gain", type=float, default=None,
+ help=f"times the physical answer (default {GAIN_DEFAULT:g}; 1 is the mass as measured, 0 leaves the strip as it "
+ f"was); on the breath (--breathe), times the breath's rise less the part's own (default {BREATH_GAIN_DEFAULT:g})")
+ parser.add_argument("--gain-across", type=float, default=None,
+ help="the gain across, apart from --gain, which is then the gain down (default: --gain); a region whose gain "
+ "--on-fold lower or --stretch-floor lowers moves across lowered in the same proportion")
parser.add_argument("--on-fold", choices=ON_FOLD_MODES, default="refuse",
help=f"a move that folds a region over itself: refuse (default), or lower — each region takes the largest gain that does "
f"not fold it, never under {GAIN_MEASURED:g} (the mass as measured): a region that would have to is held still and "
"named in the record, and the strip is refused only when every region is")
- parser.add_argument("--freq", type=float, default=FREQ_DEFAULT, help=f"the part's own frequency in Hz (default {FREQ_DEFAULT:g})")
- parser.add_argument("--zeta", type=float, default=ZETA_DEFAULT, help=f"damping ratio (default {ZETA_DEFAULT:g}: lags and settles, no ringing)")
+ parser.add_argument("--freq", type=float, default=None, help=f"the part's own frequency in Hz (default {FREQ_DEFAULT:g})")
+ parser.add_argument("--zeta", type=float, default=None, help=f"damping ratio (default {ZETA_DEFAULT:g}: lags and settles, no ringing)")
+ parser.add_argument("--breathe", type=Path, default=None, metavar="BREATHE.JSON",
+ help="sway on the breath: the record sprite-gen breathe writes beside the frames it breathed (smooth). The part "
+ "follows the chest's rise late by --lag instead of answering the body's motion as a damped mass: its offset is "
+ "gain x the chest's rise x (w - w late), against the way the chest rises, 0 where the breath rests (the "
+ "first cell). The record's phases must be the ones its config gives, one for each cell swayed")
+ parser.add_argument("--lag", type=float, default=None,
+ help=f"on the breath: the share of a breath the part peaks after the chest, above 0 and under 1/π (default {LAG_DEFAULT:g})")
parser.add_argument("--read-on", type=parse_read_on, default=None, metavar="SHA256",
help="the sha256 of the strip as cut (before any follow-through) the regions were read on: this loop's own is "
"read as without it (relation same); the cut this loop was aligned from (video-cycle-align records it) has "
@@ -845,7 +1120,17 @@ def add_request_arguments(parser: argparse.ArgumentParser) -> None:
def add_arguments(parser: argparse.ArgumentParser) -> None:
- add_request_arguments(parser)
+ where = parser.add_mutually_exclusive_group(required=True)
+ where.add_argument("--loop-dir", type=Path, help=LOOP_DIR_HELP)
+ where.add_argument("--frames", type=Path,
+ help="a folder of a cycle's frames (*.png in name order, one size: a video-loop cycle/, or what sprite-gen "
+ "breathe wrote from it), swayed at their own size and count into --out — past the strip's caps on cells "
+ "and width; the regions are in frame pixels")
+ parser.add_argument("--out", type=Path, help=f"with --frames: a new folder for the swayed frames (same names) and {FRAMES_RECORD}")
+ parser.add_argument("--fps", type=float, default=None,
+ help="with --frames: their rate, for the damped mass (a video-loop cycle/ folder has its own in the loop's strip "
+ "meta); a frame's time is rounded to hundredths of a ms, as a strip's meta writes it")
+ add_request_arguments(parser, loop_dir=False)
parser.add_argument("--board", type=Path, help="write a before/after picture at the frames where the part sits lowest and highest")
@@ -854,8 +1139,8 @@ def fold_notes(record: dict[str, Any], verb: str = VERB) -> list[str]:
fold, notes = record["fold"], []
if "stretch" in record: # a floor was asked: each region says what lowered it, the fold or the floor
floor = record["stretch"]["floor"]
- for (cx, cy, rx, ry), entry, folded in zip(record["regions"], record["stretch"]["regions"], fold["regions"]):
- name = f"--region {cx:g},{cy:g},{rx:g},{ry:g}"
+ for region, entry, folded in zip(record["regions"], record["stretch"]["regions"], fold["regions"]):
+ name = "--region " + ",".join(f"{v:g}" for v in region)
if entry["held"]:
why = (f"folds at --gain {folded['gain_limit']:g}" if entry["rule_gain"] == 0 else
f"keeps --stretch-floor {floor:g} only at --gain {entry['floor_gain']:g}")
@@ -865,8 +1150,8 @@ def fold_notes(record: dict[str, Any], verb: str = VERB) -> list[str]:
notes.append(f"{verb}: {name} moves at --gain {entry['gain']:g}, lowered from {record['gain_requested']:g} by {by}")
return notes
if "held" in fold["regions"][0]: # the regions took gains of their own
- for (cx, cy, rx, ry), entry in zip(record["regions"], fold["regions"]):
- name = f"--region {cx:g},{cy:g},{rx:g},{ry:g}"
+ for region, entry in zip(record["regions"], fold["regions"]):
+ name = "--region " + ",".join(f"{v:g}" for v in region)
if entry["held"]:
notes.append(f"{verb}: {name} folds at --gain {entry['gain_limit']:g}, under {GAIN_MEASURED:g} (the mass as measured): "
"it is held, and does not move")
@@ -881,17 +1166,28 @@ def fold_notes(record: dict[str, Any], verb: str = VERB) -> list[str]:
def run(**kwargs: object) -> int:
verb = str(kwargs.get("verb") or VERB)
- result = sway_loop(Path(str(kwargs["loop_dir"])), list(kwargs["region"]), verb=verb, # type: ignore[arg-type]
- gain=float(kwargs.get("gain", GAIN_DEFAULT)), freq=float(kwargs.get("freq", FREQ_DEFAULT)), # type: ignore[arg-type]
- zeta=float(kwargs.get("zeta", ZETA_DEFAULT)), board=kwargs.get("board"), # type: ignore[arg-type]
- on_fold=str(kwargs.get("on_fold") or "refuse"), read_on=kwargs.get("read_on"), # type: ignore[arg-type]
- stretch_floor=kwargs.get("stretch_floor")) # type: ignore[arg-type]
+ asked = {"gain": kwargs.get("gain"), "freq": kwargs.get("freq"), "zeta": kwargs.get("zeta"), "board": kwargs.get("board"),
+ "on_fold": str(kwargs.get("on_fold") or "refuse"), "read_on": kwargs.get("read_on"),
+ "stretch_floor": kwargs.get("stretch_floor"), "breathe": kwargs.get("breathe"), "lag": kwargs.get("lag"),
+ "gain_across": kwargs.get("gain_across")}
+ if kwargs.get("frames") is not None:
+ if kwargs.get("out") is None:
+ raise SystemExit(f"{verb}: --frames needs --out, a new folder for the swayed frames")
+ result = sway_frames(Path(str(kwargs["frames"])), Path(str(kwargs["out"])), list(kwargs["region"]), # type: ignore[arg-type]
+ fps=kwargs.get("fps"), verb=verb, **asked) # type: ignore[arg-type]
+ else:
+ for flag in ("out", "fps"):
+ if kwargs.get(flag) is not None:
+ raise SystemExit(f"{verb}: --{flag} goes with --frames; a loop directory is swayed where it is")
+ result = sway_loop(Path(str(kwargs["loop_dir"])), list(kwargs["region"]), verb=verb, **asked) # type: ignore[arg-type]
fold = result["fold"]
own = "held" in fold["regions"][0] # the regions took gains of their own
for note in fold_notes(result, verb):
print(note, file=sys.stderr)
- print(json.dumps({k: result[k] for k in ("strip", "regions", "gain", "gain_requested", "on_fold", "body_bob_px", "reach_px")}
+ where = "out" if "out" in result else "strip"
+ print(json.dumps({k: result[k] for k in (where, "regions", "gain", "gain_requested", "on_fold", "body_bob_px", "reach_px")}
| ({"region_gains": [entry["gain"] for entry in fold["regions"]]} if own else {})
+ | ({"drive": result["drive"]["kind"]} if "drive" in result else {})
| ({"read_on": result["read_on"]["relation"]} if "read_on" in result else {})
| ({"stretch_floor": result["stretch"]["floor"]} if "stretch" in result else {})
| ({"board": result["board"]} if "board" in result else {}), ensure_ascii=False, indent=2))
diff --git a/sprite_gen/video/sway_inspect.py b/sprite_gen/video/sway_inspect.py
index fc1c247..bda3bd0 100644
--- a/sprite_gen/video/sway_inspect.py
+++ b/sprite_gen/video/sway_inspect.py
@@ -57,6 +57,7 @@ from typing import Any
from PIL import Image
from sprite_gen._deps import np
+from sprite_gen.effects import breathe as breathe_mod
from sprite_gen.spec.runio import atomic_write_set
from sprite_gen.video import loop as loop_mod
from sprite_gen.video import sway
@@ -107,10 +108,11 @@ def _engine_version() -> str:
return "unknown"
-def policy() -> dict[str, Any]:
- """The way the motion is read and a region moved: its name and the numbers it is fixed by; the way a reading
- is carried from a cut (`--read-on`) and a floor kept (`--stretch-floor`), by name."""
- return {"name": sway.POLICY, "harmonics": sway.HARMONICS, "alpha_solid": sway.ALPHA_SOLID,
+def policy(ask: sway.Ask) -> dict[str, Any]:
+ """The way the motion is read and a region moved: its name (by the drive: the body's motion or the breath) and the
+ numbers it is fixed by; the way a reading is carried from a cut (`--read-on`) and a floor kept (`--stretch-floor`),
+ by name."""
+ return {"name": ask.policy, "harmonics": sway.HARMONICS, "alpha_solid": sway.ALPHA_SOLID,
"worn": [sway.WORN_FROM, sway.WORN_TO], "gain_measured": sway.GAIN_MEASURED, "gain_step": sway.GAIN_STEP,
"weight": "cos2", "transport": sway.TRANSPORT_POLICY, "stretch_floor": sway.STRETCH_POLICY}
@@ -119,15 +121,17 @@ def _degrees(slope: float) -> float:
return round(math.degrees(math.atan(slope)), DEGREES)
-def _weight_and_gradient(x: np.ndarray, y: np.ndarray, ellipse: tuple[float, float, float, float]) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
- """A region's weight at points (x, y) — cos² of the ellipse's own radius, 0 at its rim and outside — and the
- weight's gradient there, across and down."""
- cx, cy, rx, ry = ellipse
+def _weight_and_gradient(x: np.ndarray, y: np.ndarray, ellipse: tuple[float, ...]) -> tuple[np.ndarray, np.ndarray, np.ndarray]:
+ """A region's weight at points (x, y) — cos² of the ellipse's own radius, 1 over its flat share where it has one,
+ 0 at its rim and outside (`sway.region_weight`) — and the weight's gradient there, across and down."""
+ cx, cy, rx, ry = ellipse[:4]
+ flat = sway.flat_of(ellipse)
u, v = (x - cx) / rx, (y - cy) / ry
r = np.hypot(u, v)
inside = r < 1
- weight = np.where(inside, np.cos(r * math.pi / 2) ** 2, 0.0)
- slope = np.where(inside & (r > 0), -(math.pi / 2) * np.sin(math.pi * r) / np.where(r > 0, r, 1.0), 0.0)
+ weight = breathe_mod.flat_cos2(r, flat)
+ falling = r if flat == 0 else np.clip((r - flat) / (1 - flat), 0.0, None) # the way left, from the flat share to the rim
+ slope = np.where(inside & (falling > 0), -(math.pi / 2) * np.sin(math.pi * falling) / (1 - flat) / np.where(r > 0, r, 1.0), 0.0)
return weight, slope * u / rx, slope * v / ry
@@ -255,14 +259,17 @@ def _png(board: np.ndarray) -> bytes:
return data.getvalue()
-def inspect_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]], out_dir: Path, *,
- gain: float = sway.GAIN_DEFAULT, freq: float = sway.FREQ_DEFAULT, zeta: float = sway.ZETA_DEFAULT,
+def inspect_loop(loop_dir: Path, regions: list[tuple[float, ...]], out_dir: Path, *,
+ gain: float | None = None, freq: float | None = None, zeta: float | None = None,
on_fold: str = "refuse", scale: int = SCALE_DEFAULT, columns: int = COLUMNS_DEFAULT,
- read_on: str | None = None, stretch_floor: float | None = None, verb: str = VERB) -> dict[str, Any]:
+ read_on: str | None = None, stretch_floor: float | None = None, breathe: Path | None = None,
+ lag: float | None = None, gain_across: float | None = None, verb: str = VERB) -> dict[str, Any]:
"""The record of what `video-sway` asked the same way does to the loop, written with its two boards into
`out_dir`. The loop directory is read and not written."""
request = sway.read_request(loop_dir, regions, gain=gain, freq=freq, zeta=zeta, on_fold=on_fold, verb=verb,
- read_on=read_on, stretch_floor=stretch_floor)
+ read_on=read_on, stretch_floor=stretch_floor, breathe=breathe, lag=lag,
+ gain_across=gain_across)
+ ask = request.ask
out_dir = out_dir.expanduser().resolve()
if out_dir == request.loop_dir or request.loop_dir in out_dir.parents:
raise SystemExit(f"{verb}: --out-dir {out_dir} is in the loop directory; an inspection writes nothing there")
@@ -284,16 +291,16 @@ def inspect_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]
solid = before[..., 3] >= sway.ALPHA_SOLID
field = sway.move_field(xx, yy, answer.moves_in(k), carry)
area = None if field is None else jacobian(field[1], field[2])
- masks = [sway.region_weight(xx, yy, region, carry) > 0 for region in request.regions]
+ masks = [sway.region_weight(xx, yy, region, carry) > 0 for region in ask.regions]
entries, offsets = [], []
- for i, ((cx, cy, rx, ry), radius, g, hold, mask) in enumerate(zip(request.regions, answer.radii, answer.gains,
- answer.held, masks)):
+ for i, (region, radius, g, hold, mask) in enumerate(zip(ask.regions, answer.radii, answer.gains, answer.held, masks)):
+ cx, cy, rx, ry, *flat = region
dx, dy = (0.0, 0.0) if hold else (float(answer.moves[g][0][k]), float(answer.moves[g][1][k]))
offsets.append((dx, dy))
least, at = _least(area, mask)
bend = sway.fold_ratio(math.hypot(dx, dy), radius) # the move's steepest slope: G
entries.append({
- "index": i, "ellipse": [round(cx + float(carry[0]), 6), round(cy + float(carry[1]), 6), rx, ry],
+ "index": i, "ellipse": [round(cx + float(carry[0]), 6), round(cy + float(carry[1]), 6), rx, ry, *flat],
"offset_px": [round(dx, PLACES) + 0.0, round(dy, PLACES) + 0.0], "reach_px": round(math.hypot(dx, dy), PLACES),
"fold_ratio": round(bend, PLACES),
"jacobian_min": round(least, PLACES), "jacobian_min_at": at,
@@ -329,10 +336,12 @@ def inspect_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]
"meta": {"file": request.meta_path.name, "sha256": _sha256(request.meta_bytes), "bytes": len(request.meta_bytes),
"cut_sha256": cut_sha256, "follow_recorded": loop_mod.sway_recorded(meta)},
"cut": {"frames": n, "w": w, "h": h, "delay_ms": float(meta["delay_ms"])},
- "regions": [list(region) for region in request.regions],
- "settings": {"gain": request.gain, "on_fold": request.on_fold, "freq_hz": request.freq, "zeta": request.zeta,
- "read_on": request.read_on, "stretch_floor": request.stretch_floor},
- "policy": policy(),
+ "regions": [list(region) for region in ask.regions],
+ "settings": {"gain": ask.gain, "on_fold": ask.on_fold, "freq_hz": ask.freq, "zeta": ask.zeta,
+ "read_on": ask.read_on, "stretch_floor": ask.stretch_floor}
+ | ({} if ask.gain_across is None else {"gain_across": ask.gain_across})
+ | ({} if ask.breath is None else {"breathe_sha256": ask.breath.sha256, "lag": ask.breath.lag}),
+ "policy": policy(ask),
"engine": {"name": "sprite-gen", "version": _engine_version()},
}
input_id = _sha256(_canonical({
@@ -359,7 +368,7 @@ def inspect_loop(loop_dir: Path, regions: list[tuple[float, float, float, float]
"bend": max(cell["regions"][i]["bend"] for cell in cells), "bend_deg": max(cell["regions"][i]["bend_deg"] for cell in cells),
"changed_px": sum(cell["regions"][i]["changed_px"] for cell in cells),
"ring": list(RINGS[i % len(RINGS)]),
- } for i, (region, radius, g, hold) in enumerate(zip(request.regions, answer.radii, answer.gains, answer.held))],
+ } for i, (region, radius, g, hold) in enumerate(zip(ask.regions, answer.radii, answer.gains, answer.held))],
"seams": [pairs[key] for key in sorted(pairs)],
"cells": cells,
"boards": {
@@ -389,10 +398,12 @@ def run(**kwargs: object) -> int:
verb = str(kwargs.get("verb") or VERB)
out_dir = Path(str(kwargs["out_dir"]))
record = inspect_loop(Path(str(kwargs["loop_dir"])), list(kwargs["region"]), out_dir, # type: ignore[arg-type]
- gain=float(kwargs.get("gain", sway.GAIN_DEFAULT)), freq=float(kwargs.get("freq", sway.FREQ_DEFAULT)), # type: ignore[arg-type]
- zeta=float(kwargs.get("zeta", sway.ZETA_DEFAULT)), on_fold=str(kwargs.get("on_fold") or "refuse"), # type: ignore[arg-type]
+ gain=kwargs.get("gain"), freq=kwargs.get("freq"), zeta=kwargs.get("zeta"), # type: ignore[arg-type]
+ on_fold=str(kwargs.get("on_fold") or "refuse"),
scale=int(kwargs.get("scale", SCALE_DEFAULT)), columns=int(kwargs.get("columns", COLUMNS_DEFAULT)), # type: ignore[call-overload]
- read_on=kwargs.get("read_on"), stretch_floor=kwargs.get("stretch_floor"), verb=verb) # type: ignore[arg-type]
+ read_on=kwargs.get("read_on"), stretch_floor=kwargs.get("stretch_floor"), # type: ignore[arg-type]
+ breathe=kwargs.get("breathe"), lag=kwargs.get("lag"), gain_across=kwargs.get("gain_across"), # type: ignore[arg-type]
+ verb=verb)
for note in sway.fold_notes(record["follow"], verb):
print(note, file=sys.stderr)
out_dir = out_dir.expanduser().resolve()