codimate 0.1.0__cp39-abi3-win_amd64.whl

codimate/__init__.py

@@ -0,0 +1,87 @@
+"""Codimate — turn a running algorithm into an explainer video.
+
+You write four things, and never a keyframe:
+
+    algorithm   your normal code, with emit() where something happens
+    view        what one moment looks like
+    motion      how things travel between moments
+    timing      how long each moment lasts
+
+Codimate pairs shapes between moments **by name** and turns the differences
+into movement. Everything per-frame — diffing, interpolation, drawing,
+encoding — happens in Rust (ADR 0008).
+
+## What your algorithm did
+
+- `trace` — mark a function so Codimate can watch it run
+- `emit` — say that something worth showing just happened
+- `items` — a list whose entries keep their identity when they move
+- `Item`, `Event`, `Trace`, `Frame` — what your view is handed
+
+## What a moment looks like
+
+- `Scene` — one picture: `rect`, `circle`, `polygon`, `arrow`, `text`, `line`, `formula`
+- `ngon`, `star` — corners for a polygon, so you do not compute them
+- `Group` — several shapes that move together
+- `Handle` — what a shape call returns: `.fill()`, `.round()`, `.turn()`,
+  `.grow()`, `.on()`, `.write()`, chained
+
+## Where things sit
+
+- `canvas`, `width`, `height` — the frame
+- `row`, `column`, `Slot` — divide it up, without coordinates
+- `measure`, `measure_math` — how big text or a formula will actually be
+
+## How it moves, and for how long
+
+- `Rule` — the path a shape travels
+- `Timing` — how long each event lasts
+- `ease` — the curve the Engine uses, if you need to draw it
+
+## Running it
+
+- `explain` — gather algorithm, view, motion and timing
+- `Explanation.render` — write the video
+"""
+
+from __future__ import annotations
+
+from .explain import Explanation, Rule, Timing, ease, explain
+from .layout import (Place, Slot, at, canvas, column, height, measure, measure_math,
+                     ngon, row, star, width)
+from .scene import Group, Handle, Scene
+from .trace import Event, Frame, Item, Trace, emit, items, trace
+
+__all__ = [
+    # what happened
+    "emit",
+    "trace",
+    "items",
+    "Item",
+    "Event",
+    "Trace",
+    "Frame",
+    # what it looks like
+    "Scene",
+    "Group",
+    "Handle",
+    # where things sit
+    "canvas",
+    "measure",
+    "measure_math",
+    "width",
+    "height",
+    "Slot",
+    "Place",
+    "at",
+    "row",
+    "column",
+    "ngon",
+    "star",
+    # putting it together
+    "Rule",
+    "Timing",
+    "ease",
+    "explain",
+    "Explanation",
+]

codimate/explain.py

@@ -0,0 +1,269 @@
+"""Putting it together: motion rules, timing, and the render call."""
+
+from __future__ import annotations
+
+from .layout import height, width
+from .scene import Scene, _key
+from typing import Callable
+
+from .trace import Event, Frame, Trace
+
+
+View = Callable[[Frame], Scene]
+
+PATHS = ("straight", "linear", "fall", "lift_carry_drop")
+
+
+class Rule:
+    """How things matching ``pattern`` travel. First matching rule wins.
+
+        cm.Rule("*", position="lift_carry_drop", clearance=90)
+
+    ``pattern`` matches a shape's full name with ``*`` and ``?``. A shape
+    inside a group is named ``group/child``, so ``"3/*"`` targets one group and
+    ``"*"`` targets everything.
+
+    Paths:
+
+    * ``straight`` — a straight line, easing in and out. The default, and what
+      you want when each event is a distinct step.
+    * ``linear`` — a straight line at constant speed. Use it when a thing is
+      mid-journey at every event, like something turning: easing would make it
+      accelerate and stop inside each segment.
+    * ``fall`` — a parabola: sideways at a constant rate, downwards
+      accelerating. What a dropped thing does, and what each hop of a falling
+      ball needs, since an eased path would settle gently instead of arriving.
+    * ``lift_carry_drop`` — arcs up and over, then falls. Takes ``clearance``.
+    """
+
+    def __init__(self, pattern, position: str = "straight", **options: float) -> None:
+        if position not in PATHS:
+            raise ValueError(
+                f"unknown path {position!r} — use one of {', '.join(PATHS)}")
+        self.pattern = _key(pattern) if isinstance(pattern, tuple) else str(pattern)
+        self.position = position
+        self.options = {k: float(v) for k, v in options.items()}
+
+    def _payload(self):
+        return (self.pattern, self.position, self.options)
+
+    def __repr__(self):
+        return f"Rule({self.pattern!r}, position={self.position!r}, **{self.options})"
+
+
+class Timing:
+    """How long each event lasts, in seconds."""
+
+    def __init__(
+        self,
+        *,
+        default: float = 0.6,
+        events: "dict[str, float] | None" = None,
+        opening: float = 0.8,
+        final_hold: float = 1.2,
+    ) -> None:
+        self.default = default
+        self.events = events or {}
+        self.opening = opening
+        self.final_hold = final_hold
+
+    def for_event(self, event: Event) -> float:
+        """How long ``event`` lasts: its own entry, or ``default``.
+
+        A name with no entry takes ``default`` silently — which is what a
+        default is for, but it means a misspelled event name costs you the
+        default duration rather than an error.
+        """
+        return self.events.get(event.name, self.default)
+
+
+def ease(t: float) -> float:
+    """The easing curve the Engine applies between two moments.
+
+        cm.ease(0.5)  ->  0.5
+
+    This calls into the Engine, so it is the same curve your animation is
+    actually using — not a copy of it.
+    """
+    from . import _codimate
+
+    return _codimate.ease(float(t))
+
+
+class Explanation:
+    """A trace, a view and a timing, ready to render.
+
+    Built by :func:`explain` rather than directly. Holds one Scene per Trace
+    Event and the gap between each pair; :meth:`render` hands all of it to the
+    Engine once, and everything per-frame happens in there.
+    """
+    def __init__(
+        self,
+        *,
+        trace: Trace,
+        view: View,
+        motion: "list[Rule] | None" = None,
+        timing: "Timing | None" = None,
+    ) -> None:
+        self.timing = timing or Timing()
+        self.motion = motion or []
+        self.trace = trace
+
+        # The view runs once per event, not per frame — this is the whole
+        # reason Python is fast enough to be the authoring language.
+        self.scenes = [view(Frame(state=trace.initial, event=None))]
+        for event in trace.events:
+            self.scenes.append(view(Frame(state=event.state, event=event)))
+
+        self.durations = [self.timing.for_event(e) for e in trace.events]
+
+        # A held opening and a held ending, expressed as segments that go
+        # nowhere. No special case in the Engine.
+        self.scenes.insert(0, self.scenes[0])
+        self.durations.insert(0, self.timing.opening)
+        self.scenes.append(self.scenes[-1])
+        self.durations.append(self.timing.final_hold)
+
+    @property
+    def duration(self) -> float:
+        return sum(self.durations)
+
+    def render(self, output: str, *, fps: float = 30, scale: float = 1.0) -> str:
+        """Draw every frame and write the video.
+
+        Coordinates always mean what `cm.canvas()` says — `scale` only changes
+        how many pixels each one becomes, so nothing in your view has to move:
+
+            .render("out.mp4", fps=60, scale=1.5)   # 1080p60 from the default
+
+        Frames are rasterized at the larger size rather than upscaled
+        afterwards, so 1080p is genuinely drawn at 1080p.
+
+        The folder is created if it does not exist, so `render("results/x.mp4")`
+        works on a fresh clone.
+        """
+        from pathlib import Path
+
+        from . import _codimate  # imported here so the pure Python is testable
+
+        _find_encoder()
+        Path(output).expanduser().resolve().parent.mkdir(parents=True, exist_ok=True)
+
+        _codimate.render(
+            scenes=[s._payload() for s in self.scenes],
+            cameras=[s._camera() for s in self.scenes],
+            rules=[r._payload() for r in self.motion],
+            durations=self.durations,
+            output=output,
+            width=width(),
+            height=height(),
+            fps=float(fps),
+            scale=float(scale),
+        )
+        return output
+
+    def frame_at(self, seconds: float, output: str = "frame.png",
+                 scale: float = 1.0) -> str:
+        """Save a single moment as a PNG, without rendering the video.
+
+            cm.explain(...).frame_at(12.5, "check.png")
+
+        The same scenes, timing and arithmetic as :meth:`render`, resolved at
+        one instant. Checking a frame by rendering the whole video and seeking
+        into it costs a minute to look at one second.
+
+        ``scale`` matches ``render``'s, so the debug frame is rasterized the
+        way the video is — worth passing when you are checking text, which is
+        the thing that has historically differed between the two.
+        """
+        from pathlib import Path
+
+        from . import _codimate
+
+        Path(output).expanduser().resolve().parent.mkdir(parents=True, exist_ok=True)
+        _codimate.render_frame_png(
+            scenes=[s._payload() for s in self.scenes],
+            cameras=[s._camera() for s in self.scenes],
+            rules=[r._payload() for r in self.motion],
+            durations=self.durations,
+            seconds=float(seconds),
+            output=output,
+            width=width(),
+            height=height(),
+            scale=float(scale),
+        )
+        return output
+
+    def timeline(self) -> "list[tuple[float, float, str]]":
+        """Every beat as ``(start, duration, event name)``, in seconds.
+
+            for start, length, name in cm.explain(...).timeline():
+                print(f"{start:6.2f}  {length:4.2f}  {name}")
+
+        What is on screen at 0:42, and how long each beat actually lasts —
+        the two questions you have when a video feels wrong. Pair it with
+        :meth:`frame_at` to look at the moment you find.
+        """
+        # Read from `durations`, which already carries the held opening and
+        # ending, rather than recomputing them — a second copy of that
+        # arithmetic is how a timeline starts disagreeing with the video.
+        names = ["(opening)"] + [e.name for e in self.trace.events] + ["(final hold)"]
+        out, at = [], 0.0
+        for name, length in zip(names, self.durations):
+            out.append((round(at, 3), length, name))
+            at += length
+        return out
+
+
+def _find_encoder() -> None:
+    """Make sure the engine can find an ffmpeg to run.
+
+    Rendering needs ffmpeg, which pip cannot install. Rather than let
+    `pip install codimate` succeed and then fail on someone's first render —
+    the worst moment to learn about a prerequisite — fall back to the static
+    build that ships with `imageio-ffmpeg`.
+
+    A system ffmpeg is preferred: it is usually newer, hardware-accelerated,
+    and the one the author already expects to be used. The bundled copy is a
+    safety net, not the default.
+
+    Silent when nothing is found; the engine raises its own error naming both
+    the install and the override.
+    """
+    import os
+    import shutil
+
+    if os.environ.get("CODIMATE_FFMPEG") or shutil.which("ffmpeg"):
+        return
+
+    try:
+        import imageio_ffmpeg
+    except ImportError:
+        return
+
+    try:
+        os.environ["CODIMATE_FFMPEG"] = imageio_ffmpeg.get_ffmpeg_exe()
+    except Exception:  # noqa: BLE001 — a broken fallback must not mask the real error
+        pass
+
+
+def explain(
+    *,
+    trace: Trace,
+    view: View,
+    motion: "list[Rule] | None" = None,
+    timing: "Timing | None" = None,
+) -> Explanation:
+    """Gather an algorithm, a view and a timing into something renderable.
+
+    ``trace`` is what a ``@cm.trace()``-marked function returns: the moments
+    your algorithm passed through. ``view`` is called once per moment and
+    returns the picture of it. ``motion`` and ``timing`` are optional —
+    without them every shape travels in a straight line and every event lasts
+    the same.
+
+        cm.explain(trace=flip(tally), view=view).render("results/coins.mp4")
+
+    Nothing is computed here; the work happens in :meth:`Explanation.render`.
+    """
+    return Explanation(trace=trace, view=view, motion=motion, timing=timing)

codimate/layout.py

@@ -0,0 +1,308 @@
+"""Where things sit: the canvas, Slots, and the helpers that divide it up."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+# ponytail: module-level so a view function can lay out without being handed a
+# canvas. `render()` reads the same values, so there is one source of truth.
+_CANVAS = [1280.0, 720.0]
+
+
+def measure(text: str, size: float = 16.0) -> tuple[float, float]:
+    """How wide and tall ``text`` will be at ``size``: ``(w, h)``.
+
+    For drawing a box around a label without guessing::
+
+        w, h = cm.measure(label, size=30)
+        scene.rect("box", x=x, y=y, w=w + 24, h=h + 12, radius=6)
+        scene.text("label", label, x=x, y=y, size=30)
+
+    Measured by the engine with the real fonts, including fallback, so it is
+    right for Khmer and anything else that is not plain ASCII — which is why
+    estimating ``len(text) * size * k`` is not good enough.
+
+    The height is the line height, the same for "cat" and "Qgy", so a row of
+    boxes lines up instead of jittering with whatever letters it holds.
+    """
+    from . import _codimate  # imported here so the pure Python is testable
+
+    return _codimate.measure(str(text), float(size))
+
+
+def ngon(sides: int, r: float, at=(0.0, 0.0), turn: float = 0.0) -> list:
+    """The corners of a regular polygon, for :meth:`Scene.polygon`.
+
+        scene.polygon("tri", cm.ngon(3, r=60, at=(640, 360)))
+
+    A triangle is three sides, a hexagon six. ``turn`` rotates it in degrees —
+    the first corner otherwise points straight up.
+
+    Returns points rather than drawing, so it composes: you can shift them,
+    hand them to `polygon`, or measure them yourself.
+    """
+    import math
+
+    if sides < 3:
+        raise ValueError(f"a polygon needs at least 3 sides, got {sides}")
+    step = 2 * math.pi / sides
+    start = math.radians(turn) - math.pi / 2
+    return [
+        (at[0] + r * math.cos(start + step * i), at[1] + r * math.sin(start + step * i))
+        for i in range(sides)
+    ]
+
+
+def star(points: int, r: float, inner: float = None, at=(0.0, 0.0),
+         turn: float = 0.0) -> list:
+    """The corners of a star, for :meth:`Scene.polygon`.
+
+        scene.polygon("s", cm.star(5, r=80, at=(640, 360)), color="yellow")
+
+    ``inner`` is the radius of the valleys; it defaults to a proportion that
+    looks like a star rather than a gear.
+    """
+    import math
+
+    inner = r * 0.42 if inner is None else inner
+    step = math.pi / points
+    start = math.radians(turn) - math.pi / 2
+    return [
+        (
+            at[0] + (r if i % 2 == 0 else inner) * math.cos(start + step * i),
+            at[1] + (r if i % 2 == 0 else inner) * math.sin(start + step * i),
+        )
+        for i in range(points * 2)
+    ]
+
+
+def measure_math(latex: str, size: float = 16.0) -> tuple[float, float]:
+    """How wide and tall a LaTeX formula will be at ``size``: ``(w, h)``.
+
+    The counterpart of :func:`measure`, so a formula can be laid out beside
+    words — a caption that mixes prose and mathematics needs both.
+    """
+    from . import _codimate
+
+    return _codimate.measure_formula(str(latex), float(size))
+
+
+def canvas(w: float, h: float) -> None:
+    """Set the size of the video. Defaults to 1280x720."""
+    _CANVAS[:] = [float(w), float(h)]
+
+
+def width() -> float:
+    """The canvas width. ``cm.width() / 2`` is the horizontal centre."""
+    return _CANVAS[0]
+
+
+def height() -> float:
+    """The canvas height."""
+    return _CANVAS[1]
+
+
+@dataclass(frozen=True)
+class Place:
+    """Where a shape goes, as one value.
+
+    Built by :func:`at`. Exists so a shape takes one placement argument
+    instead of six — the six were one idea wearing a disguise.
+    """
+
+    x: "float | None" = None
+    y: "float | None" = None
+    top: "float | None" = None
+    bottom: "float | None" = None
+
+
+def at(x=None, y=None, top=None, bottom=None) -> Place:
+    """A place, for a shape's ``at=``.
+
+        scene.rect("bar", h=40, at=cm.at(bottom=0))
+        scene.text("l", "hi", at=cm.at(x=col, top=y + 22))
+
+    Give one value per axis: ``x`` or nothing for horizontal, and ``y``,
+    ``top`` or ``bottom`` for vertical. A plain ``(x, y)`` or a `Slot` works
+    wherever a Place does, so you only need this for edges.
+    """
+    if y is not None and (top is not None or bottom is not None):
+        raise ValueError("give one of y=, top= or bottom=")
+    return Place(x=x, y=y, top=top, bottom=bottom)
+
+
+@dataclass(frozen=True)
+class Slot:
+    """A place to put something. Not a shape — nothing draws a Slot.
+
+    `row` and `column` hand you these; you rarely build one.
+
+    - `x`, `y` — its centre
+    - `w`, `h` — its size
+    - `left`, `right`, `top`, `bottom` — its edges
+    - `anchor` — which edge things placed here line up on
+    """
+
+    x: float
+    y: float
+    w: float
+    h: float
+    anchor: str = "center"
+
+    @property
+    def left(self) -> float:
+        return self.x - self.w / 2
+
+    @property
+    def right(self) -> float:
+        return self.x + self.w / 2
+
+    @property
+    def top(self) -> float:
+        return self.y - self.h / 2
+
+    @property
+    def bottom(self) -> float:
+        return self.y + self.h / 2
+
+    def point(self, anchor: "str | None" = None) -> "tuple[float, float]":
+        """The single point this Slot anchors things at."""
+        anchor = anchor or self.anchor
+        if anchor == "center":
+            return (self.x, self.y)
+        if anchor == "bottom":
+            return (self.x, self.bottom)
+        if anchor == "top":
+            return (self.x, self.top)
+        raise ValueError(f"unknown anchor {anchor!r} — use center, top or bottom")
+
+
+def _within(box) -> "Slot":
+    """The region a run of Slots divides up — the whole canvas by default."""
+    if box is not None:
+        return box
+    return Slot(x=width() / 2, y=height() / 2, w=width(), h=height())
+
+
+def _spread(items, gap, size, extent, centre):
+    """Evenly space things of `size` along one axis, centred on `centre`.
+
+    The shared half of `row` and `column`: normalise the input, pick a default
+    size that fills most of `extent`, and lay out the positions.
+    """
+    sequence = list(range(items)) if isinstance(items, int) else list(items)
+    count = len(sequence)
+    if count == 0:
+        return [], [], 0.0
+
+    if size is None:
+        # Fill 70% of the canvas by default, so a run always looks deliberate.
+        size = max((extent * 0.7 - gap * (count - 1)) / count, 1.0)
+
+    span = count * size + (count - 1) * gap
+    first = centre - span / 2 + size / 2
+    return sequence, [first + i * (size + gap) for i in range(count)], size
+
+
+def _size(size):
+    """A Slot size: one number for both sides, or `(w, h)`."""
+    if size is None:
+        return None, None
+    if isinstance(size, (int, float)):
+        return float(size), None
+    return size
+
+
+def row(
+    items,
+    *,
+    gap: float = 40.0,
+    size=None,
+    at: "Place | None" = None,
+    within: "Slot | None" = None,
+):
+    """One Slot per item, evenly spaced and centred on the canvas.
+
+        for slot, item in cm.row(values, gap=40, size=190):
+            ...
+
+    ``size`` is one number for the Slot's width (its height follows), or
+    ``(w, h)`` for both.
+
+    A row lays things out on a shared baseline, so its Slots anchor at
+    bottom-centre — hand one straight to ``scene.group()``.
+
+    Pass ``within=slot`` to divide up part of the canvas instead of all of it,
+    so a chart can live in its own corner without any arithmetic of yours.
+
+    Yields ``(slot, item)`` pairs, or bare Slots if you passed a count.
+    """
+    box = _within(within)
+    place = at or Place()
+    w, h = _size(size)
+    sequence, xs, w = _spread(items, gap, w, box.w, box.x)
+    if h is None:
+        h = w
+    # A row sits on a baseline near the bottom of its box unless told otherwise.
+    floor = box.bottom - box.h * 0.22 if place.bottom is None else place.bottom
+    y = place.y if place.y is not None else floor - h / 2
+
+    for x, item in zip(xs, sequence):
+        slot = Slot(x=x, y=y, w=w, h=h, anchor="bottom")
+        yield slot if isinstance(items, int) else (slot, item)
+
+
+def column(
+    items,
+    *,
+    gap: float = 40.0,
+    size=None,
+    at: "Place | None" = None,
+    within: "Slot | None" = None,
+):
+    """One Slot per item, stacked vertically and centred on the canvas.
+
+        for slot in cm.column(4, gap=40, at=cm.at(x=640)):
+            ...
+
+    A column stacks things around a centre line, so its Slots anchor at their
+    centre. ``x`` places the column horizontally; it defaults to mid-canvas.
+
+    Pass ``within=slot`` to stack inside part of the canvas instead of all
+    of it.
+
+    Yields ``(slot, item)`` pairs, or bare Slots if you passed a count.
+    """
+    box = _within(within)
+    place = at or Place()
+    w, h = _size(size)
+    centre = box.y if place.y is None else place.y
+    sequence, ys, h = _spread(items, gap, h, box.h, centre)
+    if w is None:
+        w = h
+    x = box.x if place.x is None else place.x
+
+    for cy, item in zip(ys, sequence):
+        slot = Slot(x=x, y=cy, w=w, h=h, anchor="center")
+        yield slot if isinstance(items, int) else (slot, item)
+
+
+_UNSET = object()
+
+
+def _resolve(given, half, names, default=_UNSET):
+    """Turn whichever anchor was given into a centre coordinate."""
+    centre, low, high = given
+    given = [v for v in given if v is not None]
+    if len(given) > 1:
+        raise ValueError(f"give only one of {', '.join(f'{n}=' for n in names)}")
+    if not given:
+        if default is _UNSET:
+            raise ValueError(f"give one of {', '.join(f'{n}=' for n in names)}")
+        return float(default)
+    if centre is not None:
+        return float(centre)
+    if low is not None:
+        return float(low) + half
+    return float(high) - half