open-bot-avatar 0.1.2 → 0.2.0

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.
@@ -0,0 +1,215 @@
1
+ /**
2
+ * The canvas renderer, the default for live avatars: paints flat avatar frames
3
+ * to one canvas, so an avatar costs one compositor layer and one small bitmap
4
+ * however many slices it shows. Equal geometry shares its parsed paths.
5
+ *
6
+ * The bitmap covers what the frames actually paint, plus slack, and only grows
7
+ * while the avatar's size and the pixel ratio stay the same. A GPU canvas that
8
+ * animates antialiased paths holds several times its bitmap in video memory,
9
+ * so covering every possible view up front (avatarExtent, kept as the upper
10
+ * bound) would cost about three times as much.
11
+ *
12
+ * The canvas sits in a wrapper at the host's content box, as the scene does,
13
+ * overhangs it by the avatar's reach and ignores the pointer.
14
+ */
15
+ import { avatarExtent } from '../render.ts';
16
+ import type { AvatarFrame, EyeMark, FramePath, Matrix } from '../render.ts';
17
+ import type { AvatarDefinition } from '../types.ts';
18
+
19
+ /** A square in viewBox units. */
20
+ export interface Square {
21
+ x: number;
22
+ y: number;
23
+ size: number;
24
+ }
25
+
26
+ /** An axis-aligned box in viewBox units; empty when x0 > x1. */
27
+ export interface Bounds {
28
+ x0: number;
29
+ y0: number;
30
+ x1: number;
31
+ y1: number;
32
+ }
33
+
34
+ /** Slack around a frame's bounds when the bitmap is laid out, viewBox units: idle motion and gaze stay inside it. */
35
+ export const FIT_SLACK = 8;
36
+ /** Margin a frame keeps from the bitmap's edge for antialiasing, viewBox units. */
37
+ export const FIT_PAD = 1;
38
+
39
+ /**
40
+ * The square to lay the bitmap out over: `prev` while it still holds `b`, else `prev` grown to
41
+ * hold `b` with slack. Never larger than `cap` unless `b` itself leaves `cap`.
42
+ */
43
+ export function fitSquare(prev: Square | null, b: Bounds, cap: Square): Square {
44
+ if (!(b.x0 <= b.x1 && b.y0 <= b.y1)) return prev ?? cap;
45
+ if (
46
+ prev &&
47
+ b.x0 - FIT_PAD >= prev.x &&
48
+ b.y0 - FIT_PAD >= prev.y &&
49
+ b.x1 + FIT_PAD <= prev.x + prev.size &&
50
+ b.y1 + FIT_PAD <= prev.y + prev.size
51
+ ) {
52
+ return prev;
53
+ }
54
+ let x0 = b.x0 - FIT_SLACK, y0 = b.y0 - FIT_SLACK, x1 = b.x1 + FIT_SLACK, y1 = b.y1 + FIT_SLACK;
55
+ if (prev) {
56
+ x0 = Math.min(x0, prev.x);
57
+ y0 = Math.min(y0, prev.y);
58
+ x1 = Math.max(x1, prev.x + prev.size);
59
+ y1 = Math.max(y1, prev.y + prev.size);
60
+ }
61
+ const size = Math.max(x1 - x0, y1 - y0);
62
+ const inCap = b.x0 >= cap.x && b.y0 >= cap.y && b.x1 <= cap.x + cap.size && b.y1 <= cap.y + cap.size;
63
+ if (size >= cap.size && inCap) return cap;
64
+ return { x: (x0 + x1 - size) / 2, y: (y0 + y1 - size) / 2, size };
65
+ }
66
+
67
+ interface Section {
68
+ path: Path2D;
69
+ rule: CanvasFillRule;
70
+ }
71
+
72
+ const MAX_SECTIONS = 4096;
73
+ const sections = new Map<string, Section>();
74
+
75
+ let supported: boolean | undefined;
76
+ /** Whether this environment can paint avatars: a 2D canvas and Path2D (jsdom has neither). */
77
+ export function canvasSupported(): boolean {
78
+ if (supported === undefined) {
79
+ // Path2D first: asking jsdom for a context logs a "not implemented" error.
80
+ supported = typeof Path2D !== 'undefined' && typeof document !== 'undefined' && !!document.createElement('canvas').getContext('2d');
81
+ }
82
+ return supported;
83
+ }
84
+
85
+ /**
86
+ * Each shape's matrix with the frame's root motion applied, and the bounds of everything the frame
87
+ * paints, in viewBox units. Pure.
88
+ */
89
+ export function framePlacement(frame: AvatarFrame): { matrices: Matrix[]; bounds: Bounds } {
90
+ const boxes = new Map(frame.paths.map((p) => [p.id, p.box]));
91
+ const [ra, rb, rc, rd, re, rf] = frame.root;
92
+ const bounds: Bounds = { x0: Infinity, y0: Infinity, x1: -Infinity, y1: -Infinity };
93
+ const add = (m: Matrix, x: number, y: number) => {
94
+ const X = m[0] * x + m[2] * y + m[4], Y = m[1] * x + m[3] * y + m[5];
95
+ if (X < bounds.x0) bounds.x0 = X;
96
+ if (X > bounds.x1) bounds.x1 = X;
97
+ if (Y < bounds.y0) bounds.y0 = Y;
98
+ if (Y > bounds.y1) bounds.y1 = Y;
99
+ };
100
+ const matrices = frame.shapes.map((shape) => {
101
+ const [a, b, c, d, e, f] = shape.matrix;
102
+ const m: Matrix = [ra * a + rc * b, rb * a + rd * b, ra * c + rc * d, rb * c + rd * d, ra * e + rc * f + re, rb * e + rd * f + rf];
103
+ const box = shape.kind === 'slice' ? boxes.get(shape.path) : eyeBox(shape.mark);
104
+ if (box) {
105
+ add(m, box.x, box.y);
106
+ add(m, box.x + box.w, box.y);
107
+ add(m, box.x, box.y + box.h);
108
+ add(m, box.x + box.w, box.y + box.h);
109
+ }
110
+ return m;
111
+ });
112
+ return { matrices, bounds };
113
+ }
114
+
115
+ function eyeBox(mark: EyeMark): FramePath['box'] {
116
+ if (mark.shape === 'pill') return { x: mark.x, y: mark.y, w: mark.width, h: mark.height };
117
+ // A quadratic arc lies within its points' hull; the stroke reaches half its width past it.
118
+ const n = (mark.d.match(/-?\d+(?:\.\d+)?/g) ?? []).map(Number);
119
+ const xs = n.filter((_, i) => i % 2 === 0), ys = n.filter((_, i) => i % 2 === 1);
120
+ const x = Math.min(...xs) - mark.strokeWidth, y = Math.min(...ys) - mark.strokeWidth;
121
+ return { x, y, w: Math.max(...xs) + mark.strokeWidth - x, h: Math.max(...ys) + mark.strokeWidth - y };
122
+ }
123
+
124
+ function eye(ctx: CanvasRenderingContext2D, mark: EyeMark) {
125
+ if (mark.shape === 'arc') {
126
+ ctx.lineWidth = mark.strokeWidth;
127
+ ctx.stroke(new Path2D(mark.d));
128
+ return;
129
+ }
130
+ const { x, y, width: w, height: h, radius: r } = mark;
131
+ ctx.beginPath();
132
+ if (typeof ctx.roundRect === 'function') ctx.roundRect(x, y, w, h, r);
133
+ else {
134
+ // Safari before 16 and Firefox before 112.
135
+ ctx.moveTo(x + r, y);
136
+ ctx.arcTo(x + w, y, x + w, y + h, r);
137
+ ctx.arcTo(x + w, y + h, x, y + h, r);
138
+ ctx.arcTo(x, y + h, x, y, r);
139
+ ctx.arcTo(x, y, x + w, y, r);
140
+ ctx.closePath();
141
+ }
142
+ ctx.fill();
143
+ }
144
+
145
+ /** A mounted canvas and the square and size its bitmap was last laid out at. */
146
+ export interface CanvasSurface {
147
+ key: string;
148
+ canvas: HTMLCanvasElement;
149
+ ctx: CanvasRenderingContext2D | null;
150
+ cap: Square;
151
+ fit: Square | null;
152
+ layout: string;
153
+ left: number;
154
+ top: number;
155
+ }
156
+
157
+ export function mountCanvas(el: HTMLElement, key: string, definition: AvatarDefinition, depth: number | undefined): CanvasSurface {
158
+ const cap = avatarExtent(definition, depth);
159
+ const wrap = document.createElement('div');
160
+ // In flow at the content box, like the scene's root, so the host's padding and border place it.
161
+ wrap.style.cssText = 'position:relative;width:100%;height:100%;pointer-events:none';
162
+ const canvas = document.createElement('canvas');
163
+ canvas.setAttribute('aria-hidden', 'true');
164
+ canvas.style.cssText = 'position:absolute';
165
+ wrap.append(canvas);
166
+ el.replaceChildren(wrap);
167
+ return { key, canvas, ctx: canvas.getContext('2d'), cap, fit: null, layout: '', left: 0, top: 0 };
168
+ }
169
+
170
+ /** Paint one frame `size` CSS pixels wide. `fill` and `ink` override the frame's colors with any canvas color. */
171
+ export function paintCanvas(surface: CanvasSurface, frame: AvatarFrame, size: number, fill = frame.color, ink = frame.ink) {
172
+ const { canvas, ctx } = surface;
173
+ if (!ctx || size <= 0) return;
174
+ const dpr = window.devicePixelRatio || 1;
175
+ const scale = (size / 100) * dpr;
176
+ const layout = `${size}|${dpr}`;
177
+ if (sections.size > MAX_SECTIONS) sections.clear();
178
+ for (const { id, d, evenOdd } of frame.paths) {
179
+ if (!sections.has(id)) sections.set(id, { path: new Path2D(d), rule: evenOdd ? 'evenodd' : 'nonzero' });
180
+ }
181
+ const { matrices, bounds } = framePlacement(frame);
182
+ const fit = fitSquare(surface.layout === layout ? surface.fit : null, bounds, surface.cap);
183
+ if (surface.layout === layout && fit === surface.fit) {
184
+ ctx.setTransform(1, 0, 0, 1, 0, 0);
185
+ ctx.clearRect(0, 0, canvas.width, canvas.height);
186
+ } else {
187
+ // Whole device pixels, so the bitmap is never resampled. Setting the width also clears it.
188
+ surface.layout = layout;
189
+ surface.fit = fit;
190
+ surface.left = Math.floor(fit.x * scale);
191
+ surface.top = Math.floor(fit.y * scale);
192
+ const bitmap = Math.ceil(fit.size * scale) + 1;
193
+ canvas.width = canvas.height = bitmap;
194
+ canvas.style.left = `${surface.left / dpr}px`;
195
+ canvas.style.top = `${surface.top / dpr}px`;
196
+ canvas.style.width = canvas.style.height = `${bitmap / dpr}px`;
197
+ }
198
+
199
+ ctx.lineCap = 'round';
200
+ ctx.strokeStyle = ink;
201
+ ctx.fillStyle = fill;
202
+ // Shapes run in the thousands per second across a page: one setTransform each beats save/restore.
203
+ for (let i = 0; i < frame.shapes.length; i++) {
204
+ const shape = frame.shapes[i], m = matrices[i];
205
+ ctx.setTransform(scale * m[0], scale * m[1], scale * m[2], scale * m[3], scale * m[4] - surface.left, scale * m[5] - surface.top);
206
+ if (shape.kind === 'slice') {
207
+ const section = sections.get(shape.path) as Section;
208
+ ctx.fill(section.path, section.rule);
209
+ } else {
210
+ ctx.fillStyle = ink;
211
+ eye(ctx, shape.mark);
212
+ ctx.fillStyle = fill;
213
+ }
214
+ }
215
+ }
package/src/index.ts CHANGED
@@ -9,7 +9,7 @@ export {
9
9
  DEFAULT_DEPTH,
10
10
  DEFAULT_EYE_COLOR,
11
11
  } from './render.ts';
12
- export type { AvatarFrame, EyeMark, FrameShape, Matrix, SceneFrame } from './render.ts';
12
+ export type { AvatarFrame, EyeMark, FramePath, FrameShape, Matrix, SceneFrame } from './render.ts';
13
13
  export { BASE_PITCH, BASE_YAW, blendPoses, computePose } from './motion.ts';
14
14
  export type { Pose, PoseInput } from './motion.ts';
15
15
  export { MOOD_MS, moodProgress, settleMood } from './mood.ts';
package/src/render.ts CHANGED
@@ -8,10 +8,12 @@
8
8
  * for any vector renderer.
9
9
  * - renderAvatarSvg: a standalone still, serialized from avatarFrame. Cross-sections of the stack that
10
10
  * faces the viewer are projected orthographically and painted back to front.
11
- * - renderAvatarScene + sceneFrame: a live CSS 3D scene. Every cross-section
12
- * is its own small SVG placed once with a 3D transform; animating, turning
13
- * and recoloring only change a few CSS transforms, and the browser's
14
- * compositor does projection and occlusion.
11
+ * - renderAvatarScene + sceneFrame: a CSS 3D scene. Every cross-section is its
12
+ * own small SVG placed once with a 3D transform; animating, turning and
13
+ * recoloring only change a few CSS transforms, and the browser's compositor
14
+ * does projection and occlusion. Each visible slice costs a compositor layer,
15
+ * so mountAvatar paints live avatars to one canvas by default and only uses
16
+ * the scene with `renderer: 'scene'`.
15
17
  */
16
18
  import { parseHex, toHex } from './color.ts';
17
19
  import type { Rgb } from './color.ts';
@@ -192,18 +194,38 @@ function rootMatrix(pose: Pose, b: Bounds): M {
192
194
 
193
195
  const pivotOf = (b: Bounds): Point => [(b.minX + b.maxX) / 2, (b.minY + b.maxY) / 2];
194
196
 
197
+ /** The hop and the share of a point's distance from the base that roll and squash can move it. */
198
+ const POSE_LIFT = 4;
199
+ const POSE_SWAY = 0.2;
200
+
201
+ /**
202
+ * A square of viewBox units that holds the avatar at every view and pose. Throws if invalid. The
203
+ * canvas renderer uses it only as an upper bound: it sizes each bitmap to what is actually painted.
204
+ */
205
+ export function avatarExtent(definition: AvatarDefinition, depth?: number): { x: number; y: number; size: number } {
206
+ const { vol } = prepare(definition, depthOption({ depth }));
207
+ const b = vol.bounds;
208
+ const [cx, cy] = pivotOf(b);
209
+ const radius = Math.hypot(b.maxX - b.minX, b.maxY - b.minY, Math.max(...vol.parts.map((part) => part.depth)) + 2 * EYE_LIFT) / 2;
210
+ const half = radius + POSE_LIFT + POSE_SWAY * (radius + b.maxY - cy);
211
+ return { x: cx - half, y: cy - half, size: 2 * half };
212
+ }
213
+
195
214
  /**
196
215
  * Every cross-section a view draws, with its projection: the stack facing the
197
216
  * viewer, minus z-slices hidden behind the core (they add nothing to the
198
217
  * silhouette or the paint). Their union is the silhouette on screen.
199
218
  */
200
- function drawnSlices(vol: Volume, v: ViewBasis, visit: (s: VolumeSlice, m: M, part: number, index: number) => void) {
219
+ function drawnSlices(p: Prepared, v: ViewBasis, size: number | undefined, visit: (s: VolumeSlice, m: M, part: number, index: number) => void) {
220
+ const { vol } = p;
201
221
  const stack = activeStack(v);
202
222
  const pivot = pivotOf(vol.bounds);
203
223
  const drawn = sliceCull(v);
224
+ const kept = sliceDetail(p, stack, size);
225
+ let k = 0;
204
226
  vol.parts.forEach((part, i) => {
205
227
  (stack === 'z' ? part.zSlices : part.xSlices).forEach((s, j) => {
206
- if (!drawn(s)) return;
228
+ if (!kept[k++] || !drawn(s)) return;
207
229
  visit(s, stack === 'z' ? planeMatrix(v, s.at, pivot) : sidePlaneMatrix(v, s.at, pivot), i, j);
208
230
  });
209
231
  });
@@ -290,6 +312,14 @@ export type FrameShape =
290
312
  }
291
313
  | { kind: 'eye'; key: 'eye-0' | 'eye-1'; matrix: Matrix; mark: EyeMark };
292
314
 
315
+ /** One cross-section outline, shared by every shape that draws it. */
316
+ export interface FramePath {
317
+ id: string;
318
+ d: string;
319
+ evenOdd: boolean;
320
+ box: { x: number; y: number; w: number; h: number };
321
+ }
322
+
293
323
  /**
294
324
  * One frame of the avatar flattened onto the screen: every cross-section the
295
325
  * view draws with its projection, and the visible eyes, sorted back to front.
@@ -302,8 +332,11 @@ export interface AvatarFrame {
302
332
  name: string;
303
333
  color: string;
304
334
  ink: string;
305
- /** Distinct cross-section paths this frame uses; ids are stable for equal geometry and depth. */
306
- paths: { id: string; d: string; evenOdd: boolean }[];
335
+ /**
336
+ * Distinct cross-section paths this frame uses; ids are stable for equal geometry and depth.
337
+ * `box` bounds `d` in its own coordinates, before a shape's matrix.
338
+ */
339
+ paths: FramePath[];
307
340
  /** 2D motion (hop, roll, squash) about the base of the body, applied to every shape. */
308
341
  root: Matrix;
309
342
  /** Back to front. */
@@ -312,6 +345,19 @@ export interface AvatarFrame {
312
345
 
313
346
  /** Compute one flat frame of a definition. Throws if the definition is invalid. */
314
347
  export function avatarFrame(definition: AvatarDefinition, options: RenderOptions = {}): AvatarFrame {
348
+ return flatFrame(definition, options, undefined);
349
+ }
350
+
351
+ /**
352
+ * avatarFrame for a live avatar drawn `options.size` CSS pixels wide: like the scene, it skips
353
+ * cross-sections that would sit less than a pixel apart. Internal to the live renderers, so
354
+ * `size` never changes what avatarFrame returns to custom renderers.
355
+ */
356
+ export function liveFrame(definition: AvatarDefinition, options: RenderOptions = {}): AvatarFrame {
357
+ return flatFrame(definition, options, options.size);
358
+ }
359
+
360
+ function flatFrame(definition: AvatarDefinition, options: RenderOptions, size: number | undefined): AvatarFrame {
315
361
  const p = prepare(definition, depthOption(options));
316
362
  const { vol } = p;
317
363
  const b = vol.bounds;
@@ -323,12 +369,12 @@ export function avatarFrame(definition: AvatarDefinition, options: RenderOptions
323
369
  const eyesMid: Point = [p.def.eyes.x, p.def.eyes.y];
324
370
 
325
371
  // Only the cross-sections this view draws are listed; ids are stable across frames.
326
- const paths = new Map<string, { id: string; d: string; evenOdd: boolean }>();
372
+ const paths = new Map<string, FramePath>();
327
373
  const items: { depth: number; shape: FrameShape }[] = [];
328
- drawnSlices(vol, v, (s, m, i, j) => {
374
+ drawnSlices(p, v, size, (s, m, i, j) => {
329
375
  let path = paths.get(s.d);
330
376
  if (!path) {
331
- path = { id: p.ids.get(s.d) as string, d: s.d, evenOdd: s.evenOdd };
377
+ path = { id: p.ids.get(s.d) as string, d: s.d, evenOdd: s.evenOdd, box: { ...s.box } };
332
378
  paths.set(s.d, path);
333
379
  }
334
380
  // Depth keys are taken under the eyes for the eye part, so only depth decides eye-vs-body order there.
package/src/validate.ts CHANGED
@@ -211,7 +211,7 @@ export function validateAvatar(input: unknown): ValidationResult {
211
211
  errors.push('name must be 1-40 printable characters without < or >');
212
212
  }
213
213
 
214
- let path = '';
214
+ let path: string | null = null;
215
215
  if (!isRecord(input.body)) errors.push('body must be an object { "path": "..." }');
216
216
  else {
217
217
  for (const k of Object.keys(input.body)) if (k !== 'path') errors.push(`unknown field "body.${k}" (only "path" is allowed)`);
@@ -238,7 +238,7 @@ export function validateAvatar(input: unknown): ValidationResult {
238
238
 
239
239
  let normalized = '';
240
240
  let body: BodyAnalysis | null = null;
241
- if (path) {
241
+ if (path !== null) {
242
242
  try {
243
243
  const segs = parsePath(path);
244
244
  normalized = serializePath(segs);