@logomarks/logo3d 0.0.0-stage → 0.1.1

package/src/geometry/profiles.js

@@ -0,0 +1,126 @@
+/**
+ * @module @logomarks/logo3d/geometry/profiles
+ *
+ * The edge profiles: the path a logo's side takes from its back face (z = 0) to its front face (z = depth), as
+ * points `(inset, z)`, inset measured inwards from the outline. Flat is a straight wall; chamfer a 45° cut on each
+ * edge; round a quarter circle on each edge; pillow one curve over the whole thickness, so thin strokes come out as
+ * tubes and wide parts as cushions.
+ */
+
+/** The profiles. */
+export const PROFILES = Object.freeze(['flat', 'chamfer', 'round', 'pillow']);
+
+/**
+ * @typedef {object} ProfilePoint
+ * @property {number} inset How far in from the outline.
+ * @property {number} z How far up from the back.
+ */
+
+/**
+ * @typedef {object} Profile
+ * @property {ProfilePoint[]} points From the back face's edge to the front face's.
+ * @property {boolean} smooth Whether the side is shaded smooth across the points (curves) or faceted (cuts).
+ */
+
+/**
+ * A quarter of an ellipse between two profile points: from (inset0, z0) curving to (inset1, z1).
+ *
+ * @param {number} b The bevel's width (inset).
+ * @param {number} t Its height (z).
+ * @param {number} z0 Where it starts up the side.
+ * @param {number} n Segments.
+ * @param {boolean} front The front edge (curving in towards the face) or the back (curving out from it).
+ * @returns {ProfilePoint[]} The points, the first included.
+ */
+function quarter(b, t, z0, n, front) {
+	/** @type {ProfilePoint[]} */
+	const out = [];
+	for (let k = 0; k <= n; k++) {
+		const a = (k / n) * (Math.PI / 2);
+		// the front edge: from the wall (inset 0) up and in to the face (inset b); the back mirrors it
+		out.push(front ? { inset: b * (1 - Math.cos(a)), z: z0 + t * Math.sin(a) } : { inset: b * (1 - Math.sin(a)), z: z0 + t * (1 - Math.cos(a)) });
+	}
+	return out;
+}
+
+/**
+ * A profile's points.
+ *
+ * @param {string} kind `'flat'`, `'chamfer'`, `'round'` or `'pillow'`.
+ * @param {{ depth: number, bevel: number, segments?: number }} o The depth, the bevel's width (already capped), and
+ *   the segments in each curve (round 5, pillow 8).
+ * @returns {Profile} The profile.
+ */
+export function profile(kind, { depth, bevel, segments }) {
+	const b = Math.max(0, bevel);
+	if (kind === 'flat' || b <= 0 || depth <= 0) return { points: [{ inset: 0, z: 0 }, { inset: 0, z: depth }], smooth: false };
+	if (kind === 'pillow') {
+		const n = segments ?? 8;
+		return { points: [...quarter(b, depth / 2, 0, n, false), ...quarter(b, depth / 2, depth / 2, n, true).slice(1)], smooth: true };
+	}
+	const t = Math.min(b, depth * 0.45);
+	if (kind === 'chamfer')
+		return {
+			points: [
+				{ inset: t, z: 0 },
+				{ inset: 0, z: t },
+				{ inset: 0, z: depth - t },
+				{ inset: t, z: depth },
+			],
+			smooth: false,
+		};
+	const n = segments ?? 5;
+	return { points: [...quarter(t, t, 0, n, false), ...quarter(t, t, depth - t, n, true)], smooth: true };
+}
+
+/**
+ * The bevel's width for a look: a share of the most a logo takes, which is under half its thinnest stroke and, but
+ * for the pillow, under half the depth.
+ *
+ * @param {string} kind The profile.
+ * @param {{ depth: number, bevel: number, halfStroke: number }} o The depth, the bevel as a share (0–1) of its most,
+ *   and half the logo's thinnest stroke.
+ * @returns {number} The width.
+ */
+export function bevelWidth(kind, { depth, bevel, halfStroke }) {
+	if (kind === 'flat') return 0;
+	const cap = 0.85 * halfStroke;
+	const most = kind === 'pillow' ? cap : Math.min(cap, depth * 0.45);
+	return Math.max(0, Math.min(1, bevel)) * most;
+}
+
+/**
+ * Each profile point's normal in the (out, up) plane: per segment for a faceted profile, averaged at the joins for a
+ * smooth one.
+ *
+ * @param {Profile} p The profile.
+ * @returns {{ rows: { k: number, n: [number, number] }[], bands: [number, number][] }} The rows (a profile point
+ *   and the normal it is shaded with; a faceted join is two rows) and, per segment, its first and last row.
+ */
+export function profileRows(p) {
+	const pts = p.points;
+	/** @type {[number, number][]} */
+	const seg = [];
+	for (let k = 0; k < pts.length - 1; k++) {
+		const di = pts[k + 1].inset - pts[k].inset, dz = pts[k + 1].z - pts[k].z;
+		const l = Math.hypot(di, dz) || 1;
+		seg.push([dz / l, di / l]);
+	}
+	/** @type {{ k: number, n: [number, number] }[]} */
+	const rows = [];
+	/** @type {[number, number][]} */
+	const bands = [];
+	if (p.smooth) {
+		pts.forEach((_, k) => {
+			const a = seg[Math.max(0, k - 1)], b = seg[Math.min(seg.length - 1, k)];
+			const x = a[0] + b[0], y = a[1] + b[1], l = Math.hypot(x, y) || 1;
+			rows.push({ k, n: [x / l, y / l] });
+		});
+		seg.forEach((_, k) => bands.push([k, k + 1]));
+	} else
+		seg.forEach((n, k) => {
+			rows.push({ k, n }, { k: k + 1, n });
+			bands.push([2 * k, 2 * k + 1]);
+		});
+	return { rows, bands };
+}

package/src/geometry/sides.js

@@ -0,0 +1,86 @@
+/**
+ * @module @logomarks/logo3d/geometry/sides
+ *
+ * The side of one ring: a band of quads for each segment of the profile, between the ring's inset levels. Normals
+ * follow the outline (smooth along curves, split at corners sharper than 35°) and the profile (smooth along a round
+ * edge, split at a chamfer's folds). U runs along the outline (its length, in logo units), V up the profile.
+ */
+
+import { edgeNormals } from './inset.js';
+
+/** Corners turning more than this are hard: the side is split there. */
+const HARD = Math.cos((35 * Math.PI) / 180);
+
+/**
+ * @typedef {object} Column
+ * @property {number} i The ring point.
+ * @property {[number, number]} n Its outward normal in the plane.
+ * @property {number} u Its distance along the outline.
+ */
+
+/**
+ * The side's columns: one per point along curves, two at hard corners (each edge's own normal), the first point
+ * repeated at the end so the texture has a seam rather than a jump.
+ *
+ * @param {readonly (readonly number[])[]} r The ring (open, the solid on its left).
+ * @returns {{ cols: Column[], edges: [number, number][] }} The columns, and each edge's first and last column.
+ */
+export function columns(r) {
+	const n = r.length;
+	const N = edgeNormals(r).map(([x, y]) => /** @type {[number, number]} */ ([-x, -y]));
+	/** @type {Column[]} */
+	const cols = [];
+	/** @type {number[]} */
+	const ins = [], outs = [];
+	let u = 0;
+	for (let i = 0; i <= n; i++) {
+		const p = i % n;
+		if (i) u += Math.hypot(r[p][0] - r[i - 1][0], r[p][1] - r[i - 1][1]);
+		const a = N[(p + n - 1) % n], b = N[p];
+		if (a[0] * b[0] + a[1] * b[1] < HARD) {
+			if (i > 0) ins.push(cols.push({ i: p, n: a, u }) - 1);
+			if (i < n) outs.push(cols.push({ i: p, n: b, u }) - 1);
+		} else {
+			const x = a[0] + b[0], y = a[1] + b[1], l = Math.hypot(x, y) || 1;
+			const c = cols.push({ i: p, n: [x / l, y / l], u }) - 1;
+			if (i > 0) ins.push(c);
+			if (i < n) outs.push(c);
+		}
+	}
+	/** @type {[number, number][]} */
+	const edges = [];
+	for (let e = 0; e < n; e++) edges.push([outs[e], ins[e]]);
+	return { cols, edges };
+}
+
+/**
+ * Adds a ring's side.
+ *
+ * @param {import('./buffer.js').MeshBuffer} mesh The mesh.
+ * @param {readonly (readonly number[])[]} ring The ring.
+ * @param {[number, number][][]} levels The ring inset to each profile point (same points, in order).
+ * @param {import('./profiles.js').Profile} profile The profile.
+ * @param {{ rows: { k: number, n: [number, number] }[], bands: [number, number][] }} shading The profile's rows.
+ * @param {number} z0 The back face's height.
+ */
+export function addSide(mesh, ring, levels, profile, shading, z0) {
+	const { cols, edges } = columns(ring);
+	const pts = profile.points;
+	/** @type {number[]} */
+	const vAt = [0];
+	for (let k = 1; k < pts.length; k++) vAt.push(vAt[k - 1] + Math.hypot(pts[k].inset - pts[k - 1].inset, pts[k].z - pts[k - 1].z));
+	const base = mesh.position.length / 3;
+	for (const row of shading.rows) {
+		const level = levels[row.k], z = z0 + pts[row.k].z;
+		for (const c of cols) {
+			const p = level[c.i];
+			mesh.vertex(p[0], p[1], z, c.n[0] * row.n[0], c.n[1] * row.n[0], row.n[1], c.u, vAt[row.k]);
+		}
+	}
+	const at = (/** @type {number} */ c, /** @type {number} */ r) => base + r * cols.length + c;
+	for (const [c0, c1] of edges)
+		for (const [r0, r1] of shading.bands) {
+			mesh.triangle(at(c0, r0), at(c1, r0), at(c1, r1));
+			mesh.triangle(at(c0, r0), at(c1, r1), at(c0, r1));
+		}
+}

package/src/index.d.ts

@@ -0,0 +1,17 @@
+export * from './shape/index.js';
+export * from './geometry/index.js';
+export { MOTIONS, PERIODS, REST, poseAt } from './motion/index.js';
+export type { Motion, Pose } from './motion/index.js';
+export { MATERIALS, DEFAULT_MATERIAL, FLAT_SIDES, materialById, shade, baseColor } from './materials/presets.js';
+export type { MaterialId, MaterialPreset } from './materials/presets.js';
+export { ENVIRONMENTS, DEFAULT_ENVIRONMENT, environmentById } from './scene/environments.js';
+export type { Environment, EnvironmentId } from './scene/environments.js';
+export { SOFTBOXES } from './scene/studio.js';
+export type { Softbox } from './scene/studio.js';
+export { BACKGROUNDS, sweepProfile } from './scene/backdrop.js';
+export type { Background } from './scene/backdrop.js';
+export { VIEWS, DEFAULT_VIEW, fitDistance, viewPosition } from './scene/camera.js';
+export type { ViewName } from './scene/camera.js';
+export { createBuilder } from './worker/client.js';
+export type { BuildRequest, BuildResult, Builder, WorkerLike } from './worker/client.js';
+export { makeBuild } from './worker/build.js';

package/src/index.js

@@ -0,0 +1,19 @@
+/**
+ * @module @logomarks/logo3d
+ *
+ * 3D logos from SVG, the parts that need no WebGL: reading a logo's SVG into colour layers (`readLogo`), extruding it
+ * with an edge profile capped by its thinnest stroke (`buildGeometry`), the motions as pure functions of time
+ * (`poseAt`), the material, environment, background and view tables, and the worker client (`createBuilder`). The
+ * three.js view, materials and exports are `@logomarks/logo3d/three`; the worker is `@logomarks/logo3d/worker`.
+ */
+
+export * from './shape/index.js';
+export * from './geometry/index.js';
+export { MOTIONS, PERIODS, REST, poseAt } from './motion/index.js';
+export { MATERIALS, DEFAULT_MATERIAL, FLAT_SIDES, materialById, shade, baseColor } from './materials/presets.js';
+export { ENVIRONMENTS, DEFAULT_ENVIRONMENT, environmentById } from './scene/environments.js';
+export { SOFTBOXES } from './scene/studio.js';
+export { BACKGROUNDS, sweepProfile } from './scene/backdrop.js';
+export { VIEWS, DEFAULT_VIEW, fitDistance, viewPosition } from './scene/camera.js';
+export { createBuilder } from './worker/client.js';
+export { makeBuild } from './worker/build.js';

package/src/materials/factory.d.ts

@@ -0,0 +1,11 @@
+import type * as THREE from 'three';
+import type { MaterialPreset } from './presets.js';
+
+/** The flat colour's sides: unlit, darker by which way they turn. */
+export function flatSides(three: typeof THREE, color: string): THREE.ShaderMaterial;
+/** One preset as a material for a part. */
+export function presetMaterial(three: typeof THREE, p: MaterialPreset, o: { color: string; depth: number; part: 'face' | 'side' | 'back' }): THREE.Material;
+/** Every material a logo's mesh needs, in its groups' order (each layer's face, side, back). */
+export function logoMaterials(three: typeof THREE, o: { face: string; side?: string; colors: string[]; depth: number }): THREE.Material[];
+/** A material as glTF can carry it. */
+export function exportable(three: typeof THREE, m: THREE.Material): THREE.Material;

package/src/materials/factory.js

@@ -0,0 +1,112 @@
+/**
+ * @module @logomarks/logo3d/materials/factory
+ *
+ * three.js materials from the presets: a physical material per preset (metals, glass through transmission, brushed
+ * steel through anisotropy), and the flat colour as an unlit face with sides shaded darker by which way they turn.
+ * Materials come in the geometry's group order (each layer's face, side and back), so one mesh draws every part.
+ * For glTF, `exportable` swaps the flat sides' shader for an unlit colour (KHR_materials_unlit); the physical
+ * materials go out as they are (KHR_materials_clearcoat, _transmission, _volume, _ior, _anisotropy).
+ */
+
+import { FLAT_SIDES, baseColor, materialById } from './presets.js';
+
+/**
+ * The flat colour's sides: unlit, the colour darkened by which way the side turns from a light up and to the left.
+ *
+ * @param {typeof import('three')} THREE three.js.
+ * @param {string} color The colour.
+ * @returns {import('three').ShaderMaterial} The material.
+ */
+export function flatSides(THREE, color) {
+	return new THREE.ShaderMaterial({
+		name: 'flat-sides',
+		uniforms: {
+			uColor: { value: new THREE.Color(color) },
+			uToward: { value: new THREE.Vector3(...FLAT_SIDES.toward).normalize() },
+			uDark: { value: FLAT_SIDES.dark },
+			uLight: { value: FLAT_SIDES.light },
+		},
+		vertexShader: `varying vec3 vWorldN;
+			void main() {
+				vWorldN = normalize(mat3(modelMatrix) * normal);
+				gl_Position = projectionMatrix * modelViewMatrix * vec4(position, 1.0);
+			}`,
+		fragmentShader: `uniform vec3 uColor; uniform vec3 uToward; uniform float uDark; uniform float uLight; varying vec3 vWorldN;
+			void main() {
+				float l = dot(normalize(vWorldN), uToward) * 0.5 + 0.5;
+				gl_FragColor = vec4(uColor * mix(uDark, uLight, l), 1.0);
+				#include <colorspace_fragment>
+			}`,
+	});
+}
+
+/**
+ * One preset as a material.
+ *
+ * @param {typeof import('three')} THREE three.js.
+ * @param {import('./presets.js').MaterialPreset} p The preset.
+ * @param {{ color: string, depth: number, part: 'face' | 'side' | 'back' }} o The logo's colour, its depth (glass's
+ *   thickness) and the part it's for.
+ * @returns {import('three').Material} The material.
+ */
+export function presetMaterial(THREE, p, { color, depth, part }) {
+	if (p.kind === 'flat') {
+		if (part === 'side') return flatSides(THREE, color);
+		return new THREE.MeshBasicMaterial({ name: 'flat', color, toneMapped: false });
+	}
+	const m = new THREE.MeshPhysicalMaterial({
+		name: p.id,
+		color: baseColor(p, color),
+		metalness: p.metalness,
+		roughness: p.roughness,
+		clearcoat: p.clearcoat ?? 0,
+		clearcoatRoughness: p.clearcoatRoughness ?? 0,
+		envMapIntensity: p.envIntensity ?? 1,
+	});
+	if (p.anisotropy) m.anisotropy = p.anisotropy;
+	if (p.transmission) {
+		m.transmission = p.transmission;
+		m.ior = p.ior ?? 1.5;
+		m.thickness = depth;
+		m.specularIntensity = 1;
+		// a soft tint through the glass: half way from white to the colour, so no colour of light is stopped dead
+		const tinted = p.takes === 'tint' && color.toLowerCase() !== '#ffffff';
+		m.attenuationColor = new THREE.Color('#ffffff').lerp(new THREE.Color(color), tinted ? 0.5 : 0);
+		m.attenuationDistance = tinted ? depth * 2 : Infinity;
+	}
+	return m;
+}
+
+/**
+ * Every material a logo's mesh needs, in its groups' order: for each layer, the face, side and back.
+ *
+ * @param {typeof import('three')} THREE three.js.
+ * @param {{ face: string, side?: string, colors: string[], depth: number }} o The face's preset, the sides' (the
+ *   face's when unset), each layer's colour, and the depth.
+ * @returns {import('three').Material[]} The materials.
+ */
+export function logoMaterials(THREE, { face, side, colors, depth }) {
+	const f = materialById(face);
+	const s = side ? materialById(side) : f;
+	return colors.flatMap((color) => {
+		const front = presetMaterial(THREE, f, { color, depth, part: 'face' });
+		const sides = presetMaterial(THREE, s, { color, depth, part: 'side' });
+		return [front, sides, front];
+	});
+}
+
+/**
+ * A material as glTF can carry it: the flat sides' shader becomes an unlit colour (their middle shade); anything else
+ * is returned as it is.
+ *
+ * @param {typeof import('three')} THREE three.js.
+ * @param {import('three').Material} m The material.
+ * @returns {import('three').Material} One the exporter writes.
+ */
+export function exportable(THREE, m) {
+	if (m instanceof THREE.ShaderMaterial) {
+		const c = /** @type {import('three').Color} */ (m.uniforms.uColor.value).clone().multiplyScalar((FLAT_SIDES.dark + FLAT_SIDES.light) / 2);
+		return new THREE.MeshBasicMaterial({ name: 'flat-sides', color: c });
+	}
+	return m;
+}

package/src/materials/presets.d.ts

@@ -0,0 +1,34 @@
+/** A material preset's id. */
+export type MaterialId = 'chrome' | 'black-chrome' | 'gold' | 'brushed-steel' | 'glass' | 'frosted-glass' | 'clay' | 'matte' | 'gloss' | 'flat';
+
+/** A material, as data. */
+export interface MaterialPreset {
+	id: MaterialId;
+	name: string;
+	/** A lit physical material, or the unlit flat colour. */
+	kind: 'physical' | 'flat';
+	/** What it takes from the logo's colour: its base colour, a tint through glass, or nothing. */
+	takes: 'color' | 'tint' | false;
+	color: string;
+	metalness: number;
+	roughness: number;
+	clearcoat?: number;
+	clearcoatRoughness?: number;
+	transmission?: number;
+	ior?: number;
+	anisotropy?: number;
+	envIntensity?: number;
+}
+
+/** The materials, in menu order. */
+export const MATERIALS: readonly MaterialPreset[];
+/** The material shown first. */
+export const DEFAULT_MATERIAL: MaterialId;
+/** How dark the flat colour's sides are. */
+export const FLAT_SIDES: Readonly<{ dark: number; light: number; toward: readonly [number, number, number] }>;
+/** A preset by id (the default for an unknown one). */
+export function materialById(id: string | undefined): MaterialPreset;
+/** A colour scaled towards black. */
+export function shade(hex: string, k: number): string;
+/** The colour a material is drawn in for a layer. */
+export function baseColor(preset: MaterialPreset, color: string): string;

package/src/materials/presets.js

@@ -0,0 +1,79 @@
+/**
+ * @module @logomarks/logo3d/materials/presets
+ *
+ * The materials, as data: minimal and modern finishes lit by what they reflect (a studio or a sky), never by
+ * highlight spots, and no novelty paints. Metals keep their own colour; clay, matte, gloss and the flat colour take
+ * the logo's; glass takes it as a tint through its depth. The house "flat colour" draws the face exactly the colour
+ * and the sides in darker shades of it, unlit.
+ */
+
+/**
+ * @typedef {object} MaterialPreset
+ * @property {string} id
+ * @property {string} name Its name in a menu.
+ * @property {'physical' | 'flat'} kind A lit physical material, or the unlit flat colour.
+ * @property {'color' | 'tint' | false} takes What it takes from the logo's colour: its base colour, a tint through
+ *   glass, or nothing (a metal's own colour).
+ * @property {string} color Its own colour (the base for metals; white for glass).
+ * @property {number} metalness
+ * @property {number} roughness
+ * @property {number} [clearcoat]
+ * @property {number} [clearcoatRoughness]
+ * @property {number} [transmission] Glass: how much light passes through.
+ * @property {number} [ior]
+ * @property {number} [anisotropy] Brushed metal: how far its highlights stretch along the grain.
+ * @property {number} [envIntensity] How strongly it reflects the environment (1).
+ */
+
+/** @type {readonly MaterialPreset[]} */
+export const MATERIALS = Object.freeze([
+	{ id: 'chrome', name: 'Chrome', kind: 'physical', takes: false, color: '#f4f5f7', metalness: 1, roughness: 0.04 },
+	{ id: 'black-chrome', name: 'Black chrome', kind: 'physical', takes: false, color: '#2b2c30', metalness: 1, roughness: 0.08 },
+	{ id: 'gold', name: 'Gold', kind: 'physical', takes: false, color: '#f2c66d', metalness: 1, roughness: 0.12 },
+	{ id: 'brushed-steel', name: 'Brushed steel', kind: 'physical', takes: false, color: '#cfd2d6', metalness: 1, roughness: 0.3, anisotropy: 0.85 },
+	{ id: 'glass', name: 'Clear glass', kind: 'physical', takes: 'tint', color: '#ffffff', metalness: 0, roughness: 0.02, transmission: 1, ior: 1.5 },
+	{ id: 'frosted-glass', name: 'Frosted glass', kind: 'physical', takes: 'tint', color: '#ffffff', metalness: 0, roughness: 0.42, transmission: 1, ior: 1.5 },
+	{ id: 'clay', name: 'Clay', kind: 'physical', takes: 'color', color: '#ece7df', metalness: 0, roughness: 0.92, envIntensity: 1.1 },
+	{ id: 'matte', name: 'Matte', kind: 'physical', takes: 'color', color: '#ff4f00', metalness: 0, roughness: 0.6 },
+	{ id: 'gloss', name: 'Gloss', kind: 'physical', takes: 'color', color: '#ff4f00', metalness: 0, roughness: 0.22, clearcoat: 1, clearcoatRoughness: 0.03 },
+	{ id: 'flat', name: 'Flat colour', kind: 'flat', takes: 'color', color: '#c8ff00', metalness: 0, roughness: 1 },
+]);
+
+/** The material shown first. */
+export const DEFAULT_MATERIAL = 'chrome';
+
+/**
+ * A preset by id (the default for an unknown one).
+ *
+ * @param {string | undefined} id The id.
+ * @returns {MaterialPreset} The preset.
+ */
+export const materialById = (id) => MATERIALS.find((m) => m.id === id) ?? /** @type {MaterialPreset} */ (MATERIALS.find((m) => m.id === DEFAULT_MATERIAL));
+
+/**
+ * How dark the flat colour's sides are: a share of the colour, by how far a side turns from a light up and to the
+ * left (0.38 facing away, 0.78 facing it).
+ */
+export const FLAT_SIDES = Object.freeze({ dark: 0.38, light: 0.78, toward: Object.freeze([-0.45, 0.75, 0.5]) });
+
+/**
+ * A colour scaled towards black, as `#rrggbb` (in sRGB, as the flat colour draws it).
+ *
+ * @param {string} hex `#rrggbb`.
+ * @param {number} k The share kept, 0–1.
+ * @returns {string} The darker colour.
+ */
+export function shade(hex, k) {
+	const n = parseInt(hex.replace('#', '').slice(0, 6).padEnd(6, '0'), 16);
+	const ch = (/** @type {number} */ v) => Math.round(Math.max(0, Math.min(255, v * k))).toString(16).padStart(2, '0');
+	return `#${ch((n >> 16) & 255)}${ch((n >> 8) & 255)}${ch(n & 255)}`;
+}
+
+/**
+ * The colour a material is drawn in for a layer.
+ *
+ * @param {MaterialPreset} preset The material.
+ * @param {string} color The logo's colour (or the layer's own).
+ * @returns {string} The base colour.
+ */
+export const baseColor = (preset, color) => (preset.takes === 'color' ? color : preset.color);

package/src/motion/index.d.ts

@@ -0,0 +1,23 @@
+/** A motion's name. */
+export type Motion = 'none' | 'turntable' | 'swing' | 'float' | 'light-sweep';
+
+/** Where the logo and the light are at one moment. */
+export interface Pose {
+	/** Radians about the vertical axis. */
+	turn: number;
+	/** Radians about the horizontal axis (positive leans the top away). */
+	tilt: number;
+	/** Up, as a share of the logo's longest side. */
+	lift: number;
+	/** Radians the environment has turned about the vertical axis. */
+	light: number;
+}
+
+/** The motions, in menu order. */
+export const MOTIONS: readonly Motion[];
+/** Each motion's loop, seconds. */
+export const PERIODS: Readonly<Record<Motion, number>>;
+/** The still pose. */
+export const REST: Readonly<Pose>;
+/** The pose at `t` seconds into the motion's loop; periodic, so `poseAt(m, period)` equals `poseAt(m, 0)`. */
+export function poseAt(motion: Motion | string, t: number, o?: { period?: number; amount?: number }): Pose;

package/src/motion/index.js

@@ -0,0 +1,56 @@
+/**
+ * @module @logomarks/logo3d/motion
+ *
+ * The motions, as pure functions of time: each gives the logo's turn (about the vertical axis), tilt (about the
+ * horizontal), lift, and the environment's turn, at `t` seconds into a loop of `period` seconds. Every one is
+ * periodic: the pose at `t = period` is the pose at `t = 0`, so a recorded loop joins without a jump.
+ */
+
+const TAU = Math.PI * 2;
+
+/** The motions, in menu order. */
+export const MOTIONS = Object.freeze(['none', 'turntable', 'swing', 'float', 'light-sweep']);
+
+/** Each motion's loop, seconds. */
+export const PERIODS = Object.freeze({ none: 6, turntable: 8, swing: 6, float: 6, 'light-sweep': 6 });
+
+/**
+ * @typedef {object} Pose
+ * @property {number} turn Radians about the vertical axis.
+ * @property {number} tilt Radians about the horizontal axis (positive leans the top away).
+ * @property {number} lift Up, as a share of the logo's longest side.
+ * @property {number} light Radians the environment has turned about the vertical axis.
+ */
+
+/** The still pose. */
+export const REST = Object.freeze({ turn: 0, tilt: 0, lift: 0, light: 0 });
+
+/**
+ * The pose at `t` seconds.
+ *
+ * @param {string} motion One of `MOTIONS` (an unknown one is still).
+ * @param {number} t Seconds.
+ * @param {{ period?: number, amount?: number }} [o] `period`: the loop (the motion's own); `amount`: how far it
+ *   moves, 0–1 (1).
+ * @returns {Pose} The pose.
+ */
+export function poseAt(motion, t, o = {}) {
+	const period = o.period ?? PERIODS[/** @type {keyof typeof PERIODS} */ (motion)] ?? 6;
+	const amount = o.amount ?? 1;
+	const u = (((t / period) % 1) + 1) % 1;
+	const a = TAU * u;
+	switch (motion) {
+		case 'turntable':
+			// a whole turn, so the loop ends where it began
+			return { ...REST, turn: a };
+		case 'swing':
+			return { ...REST, turn: 0.6 * amount * Math.sin(a), tilt: 0.05 * amount * Math.sin(2 * a) };
+		case 'float':
+			return { turn: 0.18 * amount * Math.sin(a), tilt: 0.08 * amount * Math.cos(a), lift: 0.025 * amount * Math.sin(a), light: 0 };
+		case 'light-sweep':
+			// the studio turns once round the logo: reflections run across it
+			return { ...REST, light: a };
+		default:
+			return { ...REST };
+	}
+}

package/src/scene/backdrop.d.ts

@@ -0,0 +1,20 @@
+import type * as THREE from 'three';
+
+/** A background's name. */
+export type Background = 'transparent' | 'solid' | 'sweep';
+/** The backgrounds. */
+export const BACKGROUNDS: readonly Background[];
+/** A sweep's profile, front to top, as (z, y). */
+export function sweepProfile(o?: { back?: number; cove?: number; front?: number; rise?: number }): [number, number][];
+/** The sweep mesh, its floor at y = 0, unlit in its colour. */
+export function sweepMesh(three: typeof THREE, color: string, width?: number): THREE.Mesh;
+/** What is behind the logo. */
+export interface Backdrop {
+	group: THREE.Object3D;
+	/** Whether the logo stands on a floor. */
+	standing: boolean;
+	apply(scene: THREE.Scene, renderer: THREE.WebGLRenderer): void;
+	dispose(): void;
+}
+/** A backdrop for a background, its colour, and the logo's bounding radius. */
+export function makeBackdrop(three: typeof THREE, o: { kind: string; color: string; size: number }): Backdrop;