framesheet 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
framesheet/timing.py ADDED
@@ -0,0 +1,118 @@
1
+ """Duration detection and sample-time planning."""
2
+
3
+ from __future__ import annotations
4
+
5
+ from functools import reduce
6
+ import math
7
+ from typing import Any
8
+
9
+ from framesheet.models import AnimationTiming, DurationInfo
10
+
11
+
12
+ FALLBACK_SECONDS = 3.0
13
+ MAX_SECONDS = 60.0
14
+ LCM_FACTOR = 4
15
+ """Use the LCM of loop periods only if it is at most this many times the longest period."""
16
+ EPSILON = 1 / 60
17
+ """One 60 fps frame: the last tile and the loop probe sit this far before the cycle end."""
18
+
19
+
20
+ def parse_timings(raw: list[dict[str, Any]]) -> list[AnimationTiming]:
21
+ return [AnimationTiming.model_validate(item) for item in raw]
22
+
23
+
24
+ def _lcm(periods: list[float]) -> float:
25
+ ticks = [max(1, round(p * 100)) for p in periods] # 10 ms resolution
26
+ return reduce(math.lcm, ticks) / 100
27
+
28
+
29
+ def detect_duration(
30
+ animations: list[AnimationTiming], override: float | None = None
31
+ ) -> DurationInfo:
32
+ """Pick the time span to sample.
33
+
34
+ * Infinite animations contribute their loop period (``duration``, doubled for
35
+ ``alternate``). Several periods are combined with their least common multiple if
36
+ that stays reasonable, otherwise the longest period wins.
37
+ * A positive start (``begin``/``delay``) of a looping animation is added, so the
38
+ warm-up before the first iteration is visible.
39
+ * Finite animations contribute their end time (delay + duration x iterations).
40
+ """
41
+ infinite = [a for a in animations if a.iterations is None]
42
+ finite = [a for a in animations if a.iterations is not None and a.end is not None]
43
+ looping = bool(infinite)
44
+ if override is not None:
45
+ return DurationInfo(
46
+ seconds=override,
47
+ method="override",
48
+ looping=looping,
49
+ detail=f"--duration {override:g}s",
50
+ animations=animations,
51
+ )
52
+ if not animations:
53
+ return DurationInfo(
54
+ seconds=FALLBACK_SECONDS,
55
+ method="fallback",
56
+ looping=False,
57
+ detail=f"no SMIL/CSS/Web Animations found; sampled the {FALLBACK_SECONDS:g}s "
58
+ "fallback (pass --duration for JS-driven animation)",
59
+ )
60
+ parts: list[str] = []
61
+ seconds = 0.0
62
+ if infinite:
63
+ periods = sorted({round(a.period, 3) for a in infinite})
64
+ cycle = _lcm(periods)
65
+ if len(periods) == 1:
66
+ parts.append(f"loop period {periods[0]:g}s")
67
+ elif cycle <= LCM_FACTOR * periods[-1] and cycle <= MAX_SECONDS:
68
+ parts.append(f"LCM of loop periods {', '.join(f'{p:g}s' for p in periods)}")
69
+ else:
70
+ cycle = periods[-1]
71
+ parts.append(
72
+ f"longest of loop periods {', '.join(f'{p:g}s' for p in periods)} "
73
+ "(no short common multiple)"
74
+ )
75
+ seconds = cycle
76
+ warmup = max(max(a.start for a in infinite), 0.0)
77
+ if warmup > 0:
78
+ seconds = max(seconds, warmup + cycle)
79
+ parts.append(f"+ {warmup:g}s positive begin/delay before the first loop")
80
+ if finite:
81
+ last_end = max(a.end or 0.0 for a in finite)
82
+ if last_end > seconds:
83
+ seconds = last_end
84
+ parts.append(f"finite animations end at {last_end:g}s")
85
+ kinds = sorted({a.kind for a in animations})
86
+ detail = f"{'; '.join(parts)} ({len(animations)} animation(s): {', '.join(kinds)})"
87
+ if seconds > MAX_SECONDS:
88
+ detail += f"; capped at {MAX_SECONDS:g}s"
89
+ seconds = MAX_SECONDS
90
+ if seconds <= 0:
91
+ seconds = FALLBACK_SECONDS
92
+ detail += f"; zero-length, using {FALLBACK_SECONDS:g}s"
93
+ return DurationInfo(
94
+ seconds=round(seconds, 3),
95
+ method="detected",
96
+ looping=looping,
97
+ detail=detail,
98
+ animations=animations,
99
+ )
100
+
101
+
102
+ def sample_times(duration: float, frames: int) -> list[float]:
103
+ """Evenly spaced times over ``[0, duration]``.
104
+
105
+ The last sample is taken one 60 fps frame *before* the end: at exactly ``t=end`` an
106
+ infinite animation has already wrapped to its first frame, which would make every
107
+ loop look seamless.
108
+ """
109
+ if frames < 2: # noqa: PLR2004
110
+ return [0.0]
111
+ times = [round(duration * i / (frames - 1), 4) for i in range(frames)]
112
+ times[-1] = round(duration - epsilon(duration), 4)
113
+ return times
114
+
115
+
116
+ def epsilon(duration: float) -> float:
117
+ """The probe offset for loop checks: one 60 fps frame, or 1% of very short cycles."""
118
+ return min(EPSILON, duration / 100)
@@ -0,0 +1,219 @@
1
+ Metadata-Version: 2.4
2
+ Name: framesheet
3
+ Version: 0.1.0
4
+ Summary: Frame-accurate contact sheets and motion maps for animated SVG and HTML, for humans and AI agents
5
+ Keywords:
6
+ Author: Philipp Temminghoff
7
+ Author-email: Philipp Temminghoff <philipptemminghoff@googlemail.com>
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Classifier: Development Status :: 4 - Beta
11
+ Classifier: Framework :: Pydantic
12
+ Classifier: Framework :: Pydantic :: 2
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: OS Independent
15
+ Classifier: Programming Language :: Python :: 3
16
+ Classifier: Programming Language :: Python :: 3 :: Only
17
+ Classifier: Programming Language :: Python :: 3.13
18
+ Classifier: Programming Language :: Python :: 3.14
19
+ Classifier: Topic :: Software Development
20
+ Classifier: Topic :: Utilities
21
+ Classifier: Typing :: Typed
22
+ Requires-Dist: pillow>=11.0.0
23
+ Requires-Dist: playwright>=1.50.0
24
+ Requires-Dist: pydantic
25
+ Requires-Dist: schemez
26
+ Requires-Dist: typer>=0.15.0
27
+ Requires-Python: >=3.13
28
+ Project-URL: Code coverage, https://app.codecov.io/gh/phil65/framesheet
29
+ Project-URL: Documentation, https://phil65.github.io/framesheet/
30
+ Project-URL: Issues, https://github.com/phil65/framesheet/issues
31
+ Project-URL: Source, https://github.com/phil65/framesheet
32
+ Description-Content-Type: text/markdown
33
+
34
+ # framesheet
35
+
36
+ [![PyPI License](https://img.shields.io/pypi/l/framesheet.svg)](https://pypi.org/project/framesheet/)
37
+ [![Package status](https://img.shields.io/pypi/status/framesheet.svg)](https://pypi.org/project/framesheet/)
38
+ [![Monthly downloads](https://img.shields.io/pypi/dm/framesheet.svg)](https://pypi.org/project/framesheet/)
39
+ [![Distribution format](https://img.shields.io/pypi/format/framesheet.svg)](https://pypi.org/project/framesheet/)
40
+ [![Wheel availability](https://img.shields.io/pypi/wheel/framesheet.svg)](https://pypi.org/project/framesheet/)
41
+ [![Python version](https://img.shields.io/pypi/pyversions/framesheet.svg)](https://pypi.org/project/framesheet/)
42
+ [![Implementation](https://img.shields.io/pypi/implementation/framesheet.svg)](https://pypi.org/project/framesheet/)
43
+ [![Releases](https://img.shields.io/github/downloads/phil65/framesheet/total.svg)](https://github.com/phil65/framesheet/releases)
44
+ [![Github Contributors](https://img.shields.io/github/contributors/phil65/framesheet)](https://github.com/phil65/framesheet/graphs/contributors)
45
+ [![Github Forks](https://img.shields.io/github/forks/phil65/framesheet)](https://github.com/phil65/framesheet/forks)
46
+ [![Github Issues](https://img.shields.io/github/issues/phil65/framesheet)](https://github.com/phil65/framesheet/issues)
47
+ [![Github Issues](https://img.shields.io/github/issues-pr/phil65/framesheet)](https://github.com/phil65/framesheet/pulls)
48
+ [![Github Watchers](https://img.shields.io/github/watchers/phil65/framesheet)](https://github.com/phil65/framesheet/watchers)
49
+ [![Github Stars](https://img.shields.io/github/stars/phil65/framesheet)](https://github.com/phil65/framesheet/stars)
50
+ [![Github Repository size](https://img.shields.io/github/repo-size/phil65/framesheet)](https://github.com/phil65/framesheet)
51
+ [![Github last commit](https://img.shields.io/github/last-commit/phil65/framesheet)](https://github.com/phil65/framesheet/commits)
52
+ [![Github release date](https://img.shields.io/github/release-date/phil65/framesheet)](https://github.com/phil65/framesheet/releases)
53
+ [![Github language count](https://img.shields.io/github/languages/count/phil65/framesheet)](https://github.com/phil65/framesheet)
54
+ [![Github commits this month](https://img.shields.io/github/commit-activity/m/phil65/framesheet)](https://github.com/phil65/framesheet)
55
+ [![Package status](https://codecov.io/gh/phil65/framesheet/branch/main/graph/badge.svg)](https://codecov.io/gh/phil65/framesheet/)
56
+ [![PyUp](https://pyup.io/repos/github/phil65/framesheet/shield.svg)](https://pyup.io/repos/github/phil65/framesheet/)
57
+
58
+ [Read the documentation!](https://phil65.github.io/framesheet/)
59
+
60
+ **framesheet** renders an animated SVG or HTML page at exact, evenly spaced points in
61
+ virtual time and turns them into images you (or an AI agent) can check at a glance.
62
+
63
+ An agent can only look at still images, and one screenshot shows one moment. A dot that
64
+ sits at `(0,0)` for the first second, a label that overflows its card, a box that flies
65
+ off the canvas halfway through, a loop that jumps back at the end: none of these show up
66
+ reliably in a single screenshot. framesheet captures the whole cycle, frame-accurately
67
+ and deterministically (same input, same PNG bytes), and adds numbers to back it up.
68
+
69
+ ## What you get
70
+
71
+ For every input, in the output directory:
72
+
73
+ | File | Use it for |
74
+ | --- | --- |
75
+ | `full.png` | One full-resolution frame (default `t=0`, `--at SECONDS`): layout, text, margins. |
76
+ | `sheet.png` | Contact sheet: N frames (default 12) over one cycle, each labelled `t=0.50s`. The last tile is one 60 fps frame before the cycle end, so you can judge the loop against the first tile. |
77
+ | `heatmap.png` | Motion heatmap: every pixel that changes at any time, coloured over a dimmed first frame. Shows what moves at all, including things that should not. |
78
+ | `report.json` | Detected duration and how it was found, static findings, per-frame changed-pixel ratios, bounding boxes of animated elements, elements outside the viewBox or at `(0,0)`, loop seamlessness. |
79
+
80
+ A short summary is printed to stdout (`--json` prints the report instead).
81
+
82
+ Contact sheet of [`tests/fixtures/pipeline.svg`](tests/fixtures/pipeline.svg) (SMIL dots,
83
+ a pulsing CSS hub and a spinning badge; detected cycle: LCM of 2s and 4s):
84
+
85
+ ![Contact sheet: 12 frames of the pipeline fixture](https://raw.githubusercontent.com/phil65/framesheet/main/docs/assets/pipeline_sheet.png)
86
+
87
+ Its motion heatmap:
88
+
89
+ ![Motion heatmap of the pipeline fixture](https://raw.githubusercontent.com/phil65/framesheet/main/docs/assets/pipeline_heatmap.png)
90
+
91
+ And a buggy one, [`tests/fixtures/parked_dot.svg`](tests/fixtures/parked_dot.svg):
92
+ `<animateMotion begin="1s">` leaves the dot parked in the top-left corner for a second.
93
+ Tiles 1-4 show it, the heatmap marks the corner, and the report says
94
+ `parked-at-origin: circle#dot sits at the SVG origin (0,0) at t=0.00s, 0.27s, 0.55s, 0.82s`.
95
+
96
+ ![Contact sheet of the parked-dot fixture](https://raw.githubusercontent.com/phil65/framesheet/main/docs/assets/parked_dot_sheet.png)
97
+
98
+ ![Motion heatmap of the parked-dot fixture](https://raw.githubusercontent.com/phil65/framesheet/main/docs/assets/parked_dot_heatmap.png)
99
+
100
+ ## Install
101
+
102
+ ```bash
103
+ uv tool install framesheet # or: pip install framesheet
104
+ framesheet install-browser # downloads Playwright's Chromium (once)
105
+ ```
106
+
107
+ `framesheet install-browser` runs `python -m playwright install chromium` in framesheet's
108
+ own environment, so the browser matches the installed Playwright version. In a project
109
+ environment, `uv run playwright install chromium` does the same. On a bare Linux CI
110
+ runner add `--with-deps` (`uv run playwright install --with-deps chromium`).
111
+
112
+ ## CLI
113
+
114
+ ```bash
115
+ framesheet inspect banner.svg # writes to a new temp dir, prints it
116
+ framesheet inspect banner.svg --out /tmp/check # choose the output dir
117
+ framesheet inspect banner.svg -n 16 --at 1.25 # 16 tiles, full.png at t=1.25s
118
+ framesheet inspect page.html --size 1440x900 --scale 2
119
+ framesheet inspect canvas.html --duration 4 # JS-driven: give the cycle length
120
+ framesheet inspect a.svg b.svg --out /tmp/all # one subdirectory per input
121
+ cat snippet.svg | framesheet inspect - # SVG or HTML snippet on stdin
122
+ framesheet inspect https://example.com/anim.html
123
+ framesheet inspect banner.svg --json | jq .loop
124
+ ```
125
+
126
+ Options: `--frames/-n`, `--duration`, `--at`, `--size WxH`, `--scale`, `--out/-o`,
127
+ `--tile`, `--columns`, `--keep-frames` (also write every frame to `frames/`), `--dark`
128
+ (`prefers-color-scheme: dark`), `--json`. The exit code is 1 if an error-level finding
129
+ was reported (for example malformed XML or a broken `#id` reference), 2 for usage
130
+ problems or a missing browser, 0 otherwise.
131
+
132
+ Example summary:
133
+
134
+ ```text
135
+ framesheet: tests/fixtures/non_seamless.svg (svg, 400x200 @1x)
136
+ duration: 3s detected: loop period 3s (1 animation(s): css-animation) [looping]
137
+ frames: 12 at t=0.00..2.98s; max change 2.8% at t=2.45s
138
+ loop: NOT seamless (last frame -> first frame changes 4.73% of pixels, one normal step changes 0.40%)
139
+ animated elements: circle#runner
140
+ findings: 0 error(s), 1 warning(s), 0 info
141
+ WARN [render] non-seamless-loop: The loop jumps at the cycle end: ...
142
+ images:
143
+ full /tmp/framesheet-x1y2/full.png (t=0s: layout, text, margins)
144
+ sheet /tmp/framesheet-x1y2/sheet.png (motion over one cycle)
145
+ heatmap /tmp/framesheet-x1y2/heatmap.png (what moves at all)
146
+ report /tmp/framesheet-x1y2/report.json
147
+ ```
148
+
149
+ ## Python API
150
+
151
+ ```python
152
+ import framesheet
153
+
154
+ result = framesheet.inspect("banner.svg", frames=12, out="/tmp/check")
155
+ print(result.summary())
156
+ print(result.duration.seconds, result.duration.detail)
157
+ print(result.loop.seamless, result.images.sheet)
158
+ for finding in result.findings:
159
+ print(finding.severity, finding.code, finding.element, finding.times)
160
+
161
+ # Markup strings work too (anything starting with "<").
162
+ framesheet.inspect('<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 10 10">...</svg>')
163
+ ```
164
+
165
+ `inspect()` returns an `InspectionResult` (pydantic model): image paths, `duration`,
166
+ `times`, `frames` (per-frame metrics), `elements` (per-frame boxes of animated elements),
167
+ `loop`, `findings` and `console_errors`. It uses Playwright's sync API, so call it
168
+ outside a running asyncio loop (or in a worker thread).
169
+
170
+ ## The agent loop
171
+
172
+ 1. Run `framesheet inspect FILE --out DIR`.
173
+ 2. Read the summary, fix every `ERROR` and `WARN`.
174
+ 3. Look at `full.png` for layout: text clipping, cramped margins, connectors meeting
175
+ card edges, contrast.
176
+ 4. Look at `sheet.png` for motion: does every tile look intentional? Do the first and
177
+ last tile join up for a loop?
178
+ 5. Look at `heatmap.png` for unexpected movement: anything coloured that should be still?
179
+ 6. Use `report.json` for numbers (boxes per frame, changed-pixel ratios, seam ratio).
180
+ 7. Re-run until clean.
181
+
182
+ ## How time is controlled
183
+
184
+ framesheet never takes wall-clock screenshots. Everything runs on a virtual clock:
185
+
186
+ - **SMIL**: `pauseAnimations()` + `setCurrentTime(t)` on every outermost `<svg>`.
187
+ - **CSS animations/transitions and Web Animations**: every `document.getAnimations()`
188
+ entry is paused and its `currentTime` set to `t`.
189
+ - **JavaScript** (`requestAnimationFrame`, canvas, `Date`, `performance.now`, timers):
190
+ Playwright's fake clock is installed before the page loads and only advances when
191
+ framesheet moves to the next sample time, firing every due timer and rAF callback.
192
+
193
+ The cycle length is detected from SMIL `begin`/`dur`/`repeatCount` and CSS/Web Animation
194
+ timing (delay + duration x iterations, alternate = 2x duration, several loops = least
195
+ common multiple when short enough). Override it with `--duration`; with no declarative
196
+ animation framesheet samples 3 seconds and tells you so.
197
+
198
+ ## Checks
199
+
200
+ Static checks (ported from the `svg-animation` skill's `verify_svg.py`): malformed XML,
201
+ missing `xmlns`/`viewBox`/title, `<script>`, `on*` handlers, external URLs and fonts,
202
+ `<foreignObject>`, duplicate ids, broken `#id`/`url(#id)` references, positive
203
+ `<animateMotion begin>`, missing `prefers-reduced-motion`, CSS transforms without
204
+ `transform-box`, large files.
205
+
206
+ Render checks (from geometry at every sampled frame): `parked-at-origin`,
207
+ `outside-bounds`, `text-overflow` (SVG text vs. the rect under it; HTML text larger than
208
+ its box), `svg-transform-box` (CSS transform animation pivoting around the SVG origin),
209
+ `non-seamless-loop`, `js-driven-motion`, `console-error`.
210
+
211
+ ## Limitations
212
+
213
+ - Chromium only. Fonts are whatever the machine has, so text widths can differ from
214
+ macOS/Windows; leave slack in text containers.
215
+ - Animations created by script after load are timed from the sample at which framesheet
216
+ first sees them (accurate to one sample step).
217
+ - JS clocks run about 17 ms (one frame) ahead of SMIL/CSS time so that rAF content has
218
+ painted at `t=0`.
219
+ - Content outside the viewBox is clipped in the images; the report still lists it.
@@ -0,0 +1,18 @@
1
+ framesheet/__init__.py,sha256=GYpe8Wa2JWLgn_O98MNmt9dtSXjNe4PsnGIyEeb-HJU,1023
2
+ framesheet/analysis.py,sha256=EwP1BFzBZzs6LVPeRLw1o51R17GrQgm3hzdw6bplrNk,13688
3
+ framesheet/checks.py,sha256=SYHE3VqOWcpotsAHcoaxrq5rCCU24fxCmYqP3LaUcmM,9033
4
+ framesheet/cli.py,sha256=Ll-Vlv8kvV8Tft5Y5w5L7HDXU8FqIwXzHO4CCMjrY9o,3933
5
+ framesheet/compose.py,sha256=j4C0y8HSzn8HB62gvTQWMHjAyIK0SqaZaDOUyH5cBSU,9384
6
+ framesheet/core.py,sha256=tbH-evzGypUFifxIfQC7Uw16uFspZ1SWtymzFm4Qf9k,12130
7
+ framesheet/log.py,sha256=5ByNEIcJHwD-ayvcpngVV2m556IUWDKTf_-9lE-6dq8,582
8
+ framesheet/models.py,sha256=JD0XG7itZFZ59MlDroFv5StSs7IuGeHYrWQOu6LlA-I,6790
9
+ framesheet/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
10
+ framesheet/render.py,sha256=7DIxdEKIzEQmLF2RfUAaA0cUt36LxsEii0Fdna3hG-A,6870
11
+ framesheet/runtime.js,sha256=YOd3jIIkEFZiIGPm525-fmYhn0HfE_R0dEI3WQ98xSA,12368
12
+ framesheet/sources.py,sha256=o52Vk2FZzgTHLb376f1f5fILP21WjfuMg0iXK6e2Yfk,4841
13
+ framesheet/timing.py,sha256=1ruEa3OtFvXIh0XZzq_ZHjQcyXqvaTVD0qRn4fb-frI,4413
14
+ framesheet-0.1.0.dist-info/licenses/LICENSE,sha256=AteGCH9r177TxxrOFEiOARrastASsf7yW6MQxlAHdwA,1078
15
+ framesheet-0.1.0.dist-info/WHEEL,sha256=3OmCxFA0ffBIsX4x0o8CdfSvZAOvO3mzEG8U_z5TvV4,80
16
+ framesheet-0.1.0.dist-info/entry_points.txt,sha256=0Civuzga4xRVDA-3HOfGqQIOQHcRAeJYl-ukwIKs19M,52
17
+ framesheet-0.1.0.dist-info/METADATA,sha256=cIsA_o0Er3T1QDpPbAKWMSncSJpwb3e2OCcODkw2b8M,12173
18
+ framesheet-0.1.0.dist-info/RECORD,,
@@ -0,0 +1,4 @@
1
+ Wheel-Version: 1.0
2
+ Generator: uv 0.13.8
3
+ Root-Is-Purelib: true
4
+ Tag: py3-none-any
@@ -0,0 +1,3 @@
1
+ [console_scripts]
2
+ framesheet = framesheet.cli:main
3
+
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2024, Philipp Temminghoff
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
22
+