@altpsyche/maths 0.11.0 → 0.12.0

package/README.md

@@ -360,6 +360,31 @@ marks onto a two-dimensional canvas, which is what a recording needs, because an
 one surface. A test holds the two to emitting the same geometry and the same style for every
 mark.
 
+## Frames out
+
+`framesOf(figure, options)` walks a figure at a fixed step and hands back a frame at a time. A frame
+is its index, its time, its marks and the view those marks are painted through, read together at one
+moment. A consumer that asks for the marks and the view in two calls has two chances to pass different
+times, and a figure whose view moves then paints its marks through the matrix of some other moment:
+the flat demo's view is carried 312 across its own walk, in the units a 1080 by 600 surface counts in.
+
+Frames come back one at a time rather than as a list. Ten seconds at sixty frames a second is six
+hundred frames of every mark a figure draws, and a recorder encodes a frame and throws it away.
+`frameTimes` answers the times up front, since a recorder showing a reader how far along it is needs
+the total before it has drawn anything.
+
+The step is given as a rate or as a count, and the two are different questions. A recorder knows how
+fast the frames play and needs a step of exactly one over that, or the encoded video drifts from the
+figure's own clock. A strip knows how many pictures fit across a page and wants them spread over the
+whole figure. A walk stops strictly before the duration either way: the frame at the duration of a
+figure that loops is its own first frame, and a recording would show it twice. The rotation strip
+above is a walk of four frames over a six second turn, and it draws the same bytes as the four times
+that were written out by hand before it.
+
+Nothing here writes a file. Every frame of both demos is painted through `paintCanvas` and written by
+`svgMarkup` in the suite, which is the whole claim and needs no browser, and what a consumer does with
+a painted frame is the consumer's own.
+
 ## The way in
 
 `pathFromData` reads an SVG `d` attribute as a path, which is the inverse of what the SVG painter

package/dist/figure/frames.d.ts

@@ -0,0 +1,57 @@
+/**
+ * A figure walked at a fixed step, a frame at a time.
+ *
+ * A frame is the marks and the view read at one time, handed over together. A
+ * consumer that asked for them separately holds two calls it can pass different
+ * times, and a figure whose view moves then paints its marks through the matrix
+ * of some other moment.
+ *
+ * Frames come back one at a time rather than as a list. A ten second figure at
+ * sixty frames a second is six hundred frames of every mark it draws, and a
+ * recorder encodes a frame and throws it away.
+ */
+import { type Figure } from './figure.js';
+import type { Mark } from './mark.js';
+import type { Mat3 } from '../values/mat3.js';
+export interface Frame {
+    /** Its place in the walk, counting from nothing. */
+    index: number;
+    /** The time it was read at, in seconds. */
+    seconds: number;
+    marks: readonly Mark[];
+    /** The matrix a painter needs for these marks, built at this frame's own
+     * time. */
+    view: Mat3;
+}
+/**
+ * How the walk is stepped, as a rate or as a count.
+ *
+ * The two are different questions. A recorder knows how fast the frames play and
+ * needs a step of exactly one over that, or the encoded video drifts from the
+ * figure's own clock. A strip knows how many pictures fit across a page and wants
+ * them spread over the whole figure.
+ */
+export type FrameStep = {
+    fps: number;
+    frames?: never;
+} | {
+    frames: number;
+    fps?: never;
+};
+export type FramesOptions = FrameStep & {
+    /** The surface the view is built for, in whatever units a painter counts in. */
+    width: number;
+    height: number;
+};
+/**
+ * The times a walk reads, which a recorder needs before it has drawn anything to
+ * say how far along it is.
+ *
+ * A walk stops strictly before the duration. The frame at the duration of a
+ * figure that loops is its own first frame, and a recording would show it twice.
+ * A figure with no duration is one frame, since a picture that never moves still
+ * has a picture.
+ */
+export declare function frameTimes(figure: Figure, step: FrameStep): number[];
+/** A figure walked at a fixed step, a frame at a time. */
+export declare function framesOf(figure: Figure, options: FramesOptions): Generator<Frame>;

package/dist/figure/frames.js

@@ -0,0 +1,43 @@
+/**
+ * A figure walked at a fixed step, a frame at a time.
+ *
+ * A frame is the marks and the view read at one time, handed over together. A
+ * consumer that asked for them separately holds two calls it can pass different
+ * times, and a figure whose view moves then paints its marks through the matrix
+ * of some other moment.
+ *
+ * Frames come back one at a time rather than as a list. A ten second figure at
+ * sixty frames a second is six hundred frames of every mark it draws, and a
+ * recorder encodes a frame and throws it away.
+ */
+import { at, durationOf, viewAt } from './figure.js';
+/**
+ * The times a walk reads, which a recorder needs before it has drawn anything to
+ * say how far along it is.
+ *
+ * A walk stops strictly before the duration. The frame at the duration of a
+ * figure that loops is its own first frame, and a recording would show it twice.
+ * A figure with no duration is one frame, since a picture that never moves still
+ * has a picture.
+ */
+export function frameTimes(figure, step) {
+    const duration = durationOf(figure);
+    const count = step.fps === undefined
+        ? Math.max(1, Math.round(step.frames))
+        : Math.max(1, Math.round(duration * step.fps));
+    const gap = step.fps === undefined ? duration / count : 1 / step.fps;
+    return Array.from({ length: count }, (_, index) => index * gap);
+}
+/** A figure walked at a fixed step, a frame at a time. */
+export function* framesOf(figure, options) {
+    const times = frameTimes(figure, options);
+    for (let index = 0; index < times.length; index += 1) {
+        const seconds = times[index];
+        yield {
+            index,
+            seconds,
+            marks: at(figure, seconds),
+            view: viewAt(figure, seconds, options.width, options.height),
+        };
+    }
+}

package/dist/index.d.ts

@@ -70,6 +70,8 @@ export { lengthOf, pointAlong } from './figure/length.js';
 export { trimPath } from './figure/trim.js';
 export { alignPaths, lerpPath } from './figure/morph.js';
 export { at, durationOf, loops, sameMarks, viewAt } from './figure/figure.js';
+export { frameTimes, framesOf } from './figure/frames.js';
+export type { Frame, FrameStep, FramesOptions } from './figure/frames.js';
 export type { Figure, Values } from './figure/figure.js';
 export { pathData, paintSvg, svgElements, svgMarkup } from './paint/svg.js';
 export type { ElementMaker, PaintNode, PaintTarget, SvgElement } from './paint/svg.js';

package/dist/index.js

@@ -42,6 +42,7 @@ export { lengthOf, pointAlong } from './figure/length.js';
 export { trimPath } from './figure/trim.js';
 export { alignPaths, lerpPath } from './figure/morph.js';
 export { at, durationOf, loops, sameMarks, viewAt } from './figure/figure.js';
+export { frameTimes, framesOf } from './figure/frames.js';
 export { pathData, paintSvg, svgElements, svgMarkup } from './paint/svg.js';
 export { paintCanvas } from './paint/canvas.js';
 export { arrow, brace, bracePath, callout, dot } from './figure/annotate.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@altpsyche/maths",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "description": "The mathematics AltPsyche's figures are drawn from: vectors, matrices, curves, and a value walked over time.",
   "license": "MIT",
   "author": "Siva",