@logomarks/logo3d 0.0.0-stage → 0.1.1

package/src/scene/backdrop.js

@@ -0,0 +1,128 @@
+/**
+ * @module @logomarks/logo3d/scene/backdrop
+ *
+ * What is behind the logo: nothing (a transparent PNG), one flat colour, or a seamless paper sweep (a floor curving up
+ * into a wall, as a product studio hangs one) that the logo stands on, with a soft contact shadow under it. The sweep
+ * is drawn in its own colour, unlit, a shade darker up the wall, so its colour is the colour asked for; the shadow
+ * comes from a light that casts shadows and lights nothing (the logo is lit only by what it reflects).
+ */
+
+/** The backgrounds. */
+export const BACKGROUNDS = Object.freeze(['transparent', 'solid', 'sweep']);
+
+/**
+ * A sweep's profile, front to top, in (z, y): a straight floor, a quarter circle, a straight wall.
+ *
+ * @param {{ back?: number, cove?: number, front?: number, rise?: number }} [o] Where the cove starts behind the
+ *   origin (1.2), its radius (1.4), how far the floor runs forwards (10) and the wall up (10).
+ * @returns {[number, number][]} The profile.
+ */
+export function sweepProfile({ back = 1.2, cove = 1.4, front = 10, rise = 10 } = {}) {
+	/** @type {[number, number][]} */
+	const out = [];
+	for (let i = 0; i <= 6; i++) out.push([front - ((front + back) * i) / 6, 0]);
+	for (let i = 1; i <= 16; i++) {
+		const a = (i / 16) * (Math.PI / 2);
+		out.push([-back - Math.sin(a) * cove, cove - Math.cos(a) * cove]);
+	}
+	for (let i = 1; i <= 6; i++) out.push([-back - cove, cove + (rise * i) / 6]);
+	return out;
+}
+
+/**
+ * The sweep: its profile swept across, coloured a shade darker as it rises.
+ *
+ * @param {typeof import('three')} THREE three.js.
+ * @param {string} color The paper's colour.
+ * @param {number} [width] How wide it is (30).
+ * @returns {import('three').Mesh} The mesh, its floor at y = 0.
+ */
+export function sweepMesh(THREE, color, width = 30) {
+	const prof = sweepProfile();
+	const pos = [];
+	const col = [];
+	const index = [];
+	const base = new THREE.Color(color);
+	for (const [z, y] of prof) {
+		const k = 1 - 0.14 * Math.min(1, y / 4);
+		for (const x of [-width / 2, width / 2]) {
+			pos.push(x, y, z);
+			col.push(base.r * k, base.g * k, base.b * k);
+		}
+	}
+	for (let i = 0; i < prof.length - 1; i++) index.push(2 * i, 2 * i + 1, 2 * i + 3, 2 * i, 2 * i + 3, 2 * i + 2);
+	const geo = new THREE.BufferGeometry();
+	geo.setAttribute('position', new THREE.Float32BufferAttribute(pos, 3));
+	geo.setAttribute('color', new THREE.Float32BufferAttribute(col, 3));
+	geo.setIndex(index);
+	return new THREE.Mesh(geo, new THREE.MeshBasicMaterial({ vertexColors: true, toneMapped: false, side: THREE.DoubleSide }));
+}
+
+/**
+ * @typedef {object} Backdrop
+ * @property {import('three').Object3D} group What to add to the scene.
+ * @property {boolean} standing Whether the logo stands on a floor (the sweep).
+ * @property {(scene: import('three').Scene, renderer: import('three').WebGLRenderer) => void} apply Sets the scene's
+ *   background and the renderer's shadows for it.
+ * @property {() => void} dispose Frees it.
+ */
+
+/**
+ * A backdrop.
+ *
+ * @param {typeof import('three')} THREE three.js.
+ * @param {{ kind: string, color: string, size: number }} o The background, its colour, and the logo's size (its
+ *   bounding sphere's radius), to fit the shadow to.
+ * @returns {Backdrop} The backdrop.
+ */
+export function makeBackdrop(THREE, { kind, color, size }) {
+	const group = new THREE.Group();
+	if (kind !== 'sweep') {
+		return {
+			group,
+			standing: false,
+			apply(scene, renderer) {
+				scene.background = kind === 'solid' ? new THREE.Color(color) : null;
+				renderer.shadowMap.enabled = false;
+			},
+			dispose() {},
+		};
+	}
+	const sweep = sweepMesh(THREE, color);
+	group.add(sweep);
+	// the contact shadow: a shadow catcher on the floor, from a light high above and a little in front
+	const catcher = new THREE.Mesh(new THREE.PlaneGeometry(8 * size, 8 * size), new THREE.ShadowMaterial({ opacity: 0.32, color: 0x000000 }));
+	catcher.rotation.x = -Math.PI / 2;
+	catcher.position.y = 0.0005;
+	catcher.receiveShadow = true;
+	group.add(catcher);
+	const light = new THREE.DirectionalLight(0xffffff, 0);
+	light.position.set(0.3 * size, 6 * size, 1.4 * size);
+	light.castShadow = true;
+	light.shadow.mapSize.set(1024, 1024);
+	light.shadow.radius = 10;
+	light.shadow.blurSamples = 16;
+	light.shadow.bias = -0.0005;
+	const cam = light.shadow.camera;
+	cam.left = cam.bottom = -2 * size;
+	cam.right = cam.top = 2 * size;
+	cam.near = 0.1;
+	cam.far = 12 * size;
+	group.add(light, light.target);
+	return {
+		group,
+		standing: true,
+		apply(scene, renderer) {
+			scene.background = new THREE.Color(color);
+			renderer.shadowMap.enabled = true;
+			renderer.shadowMap.type = THREE.VSMShadowMap;
+		},
+		dispose() {
+			sweep.geometry.dispose();
+			/** @type {import('three').Material} */ (sweep.material).dispose();
+			catcher.geometry.dispose();
+			/** @type {import('three').Material} */ (catcher.material).dispose();
+			light.dispose();
+		},
+	};
+}

package/src/scene/camera.d.ts

@@ -0,0 +1,10 @@
+/** A view's name. */
+export type ViewName = 'front' | 'angle' | 'low' | 'high';
+/** The views: degrees turned round the logo and tilted down onto it. */
+export const VIEWS: Readonly<Record<ViewName, Readonly<{ name: string; turn: number; tilt: number }>>>;
+/** The view shown first. */
+export const DEFAULT_VIEW: ViewName;
+/** How far the camera stands for a sphere to fill a share of the frame. */
+export function fitDistance(radius: number, fov: number, aspect: number, fill?: number): number;
+/** A camera's position for a view. */
+export function viewPosition(name: string, o: { radius: number; aspect: number; fov: number; target: [number, number, number]; fill?: number }): [number, number, number];

package/src/scene/camera.js

@@ -0,0 +1,51 @@
+/**
+ * @module @logomarks/logo3d/scene/camera
+ *
+ * Where the camera stands: a few named views round the logo (straight on, a three-quarter turn, from below, from
+ * above), each placed at the distance that fits the logo's bounding sphere in the frame, whatever its aspect, so a
+ * turning logo never leaves the frame.
+ */
+
+const DEG = Math.PI / 180;
+
+/** The views: degrees turned round the logo and tilted down onto it. */
+export const VIEWS = Object.freeze({
+	front: Object.freeze({ name: 'Front', turn: 0, tilt: 0 }),
+	angle: Object.freeze({ name: 'Three-quarter', turn: -28, tilt: 10 }),
+	low: Object.freeze({ name: 'Low', turn: -16, tilt: -12 }),
+	high: Object.freeze({ name: 'High', turn: 0, tilt: 32 }),
+});
+
+/** The view shown first. */
+export const DEFAULT_VIEW = 'angle';
+
+/**
+ * How far the camera stands for a sphere to fill a share of the frame.
+ *
+ * @param {number} radius The sphere's radius.
+ * @param {number} fov The lens's vertical field of view, degrees.
+ * @param {number} aspect The frame's width over its height.
+ * @param {number} [fill] The share of the frame's shorter side the sphere spans (0.9).
+ * @returns {number} The distance.
+ */
+export function fitDistance(radius, fov, aspect, fill = 0.9) {
+	const v = (fov * DEG) / 2;
+	const h = Math.atan(Math.tan(v) * aspect);
+	const half = Math.min(v, h);
+	return radius / Math.sin(Math.atan(Math.tan(half) * fill));
+}
+
+/**
+ * A camera's position for a view.
+ *
+ * @param {string} name The view (`VIEWS`; the default for an unknown one).
+ * @param {{ radius: number, aspect: number, fov: number, target: [number, number, number], fill?: number }} o The
+ *   logo's bounding radius, the frame's aspect, the lens, where to look, and how much of the frame to fill.
+ * @returns {[number, number, number]} Where the camera goes.
+ */
+export function viewPosition(name, { radius, aspect, fov, target, fill }) {
+	const v = VIEWS[/** @type {keyof typeof VIEWS} */ (name)] ?? VIEWS[DEFAULT_VIEW];
+	const d = fitDistance(radius, fov, aspect, fill);
+	const turn = v.turn * DEG, tilt = v.tilt * DEG;
+	return [target[0] + d * Math.cos(tilt) * Math.sin(turn), target[1] + d * Math.sin(tilt), target[2] + d * Math.cos(tilt) * Math.cos(turn)];
+}

package/src/scene/environments.d.ts

@@ -0,0 +1,22 @@
+import type * as THREE from 'three';
+
+/** An environment's id. */
+export type EnvironmentId = 'studio' | 'softbox' | 'sky';
+/** What the logo reflects. */
+export interface Environment {
+	id: EnvironmentId;
+	name: string;
+	/** The HDRI's file in `assets/hdri/`, or null for the built studio. */
+	file: string | null;
+	intensity: number;
+	rotation: number;
+	credit: string;
+}
+/** The environments, in menu order. */
+export const ENVIRONMENTS: readonly Environment[];
+/** The environment shown first. */
+export const DEFAULT_ENVIRONMENT: EnvironmentId;
+/** An environment by id (the default for an unknown one). */
+export function environmentById(id: string | undefined): Environment;
+/** Loads environments on demand and keeps each prefiltered. `urls`: each HDRI file's URL by file name. */
+export function environmentCache(three: typeof THREE, renderer: THREE.WebGLRenderer, urls: Record<string, string>): { get(id: string): Promise<THREE.Texture>; dispose(): void };

package/src/scene/environments.js

@@ -0,0 +1,94 @@
+/**
+ * @module @logomarks/logo3d/scene/environments
+ *
+ * What the logo reflects: our own studio (soft boxes in a dim room, built as a scene, no download), and two CC0 HDRIs
+ * from Poly Haven, self-hosted at 1k (`assets/hdri/`): a small photo studio and an open sky. Each is prefiltered once
+ * (PMREM) and kept, so switching back is instant.
+ */
+
+import { studioScene } from './studio.js';
+
+/**
+ * @typedef {object} Environment
+ * @property {string} id
+ * @property {string} name Its name in a menu.
+ * @property {string | null} file The HDRI's file in `assets/hdri/`, or null for the built studio.
+ * @property {number} intensity How bright it is on the logo.
+ * @property {number} rotation Radians it is turned by to start, so its brightest light falls well.
+ * @property {string} credit Where it is from.
+ */
+
+/** @type {readonly Environment[]} */
+export const ENVIRONMENTS = Object.freeze([
+	{ id: 'studio', name: 'Studio', file: null, intensity: 1.15, rotation: 0, credit: 'Built in code (scene/studio.js)' },
+	{ id: 'softbox', name: 'Softbox', file: 'studio_small_09_1k.hdr', intensity: 1, rotation: 0.6, credit: 'Studio Small 09 by Sergej Majboroda, Poly Haven (CC0)' },
+	{ id: 'sky', name: 'Open sky', file: 'kloofendal_48d_partly_cloudy_puresky_1k.hdr', intensity: 0.9, rotation: 1.2, credit: 'Kloofendal 48d Partly Cloudy (Pure Sky) by Greg Zaal and Jarod Guest, Poly Haven (CC0)' },
+]);
+
+/** The environment shown first. */
+export const DEFAULT_ENVIRONMENT = 'studio';
+
+/**
+ * An environment by id (the default for an unknown one).
+ *
+ * @param {string | undefined} id The id.
+ * @returns {Environment} The environment.
+ */
+export const environmentById = (id) => ENVIRONMENTS.find((e) => e.id === id) ?? /** @type {Environment} */ (ENVIRONMENTS[0]);
+
+/**
+ * Loads environments on demand and keeps each prefiltered.
+ *
+ * @param {typeof import('three')} THREE three.js.
+ * @param {import('three').WebGLRenderer} renderer The renderer.
+ * @param {Record<string, string>} urls Each HDRI file's URL (by file name), as the page serves it.
+ * @returns {{ get(id: string): Promise<import('three').Texture>, dispose(): void }} The cache.
+ */
+export function environmentCache(THREE, renderer, urls) {
+	const pmrem = new THREE.PMREMGenerator(renderer);
+	/** @type {Map<string, Promise<import('three').Texture>>} */
+	const done = new Map();
+	/** @type {import('three').Texture[]} */
+	const made = [];
+	/**
+	 * The environment, prefiltered.
+	 *
+	 * @param {Environment} e The environment.
+	 * @returns {Promise<import('three').Texture>} The prefiltered texture.
+	 */
+	async function prefiltered(e) {
+		if (!e.file) {
+			const studio = studioScene(THREE);
+			const env = pmrem.fromScene(studio.scene, 0.035).texture;
+			studio.dispose();
+			return env;
+		}
+		const url = urls[e.file];
+		if (!url) throw new Error(`logo3d: no URL for ${e.file}`);
+		const { HDRLoader } = await import('three/addons/loaders/HDRLoader.js');
+		const src = await new HDRLoader().loadAsync(url);
+		src.mapping = THREE.EquirectangularReflectionMapping;
+		const env = pmrem.fromEquirectangular(src).texture;
+		src.dispose();
+		return env;
+	}
+	return {
+		get(id) {
+			const e = environmentById(id);
+			let p = done.get(e.id);
+			if (!p) {
+				p = prefiltered(e).then((env) => {
+					made.push(env);
+					return env;
+				});
+				p.catch(() => done.delete(e.id));
+				done.set(e.id, p);
+			}
+			return p;
+		},
+		dispose() {
+			for (const t of made) t.dispose();
+			pmrem.dispose();
+		},
+	};
+}

package/src/scene/studio.d.ts

@@ -0,0 +1,12 @@
+import type * as THREE from 'three';
+
+/** A soft box: its centre, size and brightness. */
+export interface Softbox {
+	at: [number, number, number];
+	size: [number, number];
+	power: number;
+}
+/** The studio's soft boxes. */
+export const SOFTBOXES: readonly Softbox[];
+/** The studio as a scene, for `PMREMGenerator.fromScene`. */
+export function studioScene(three: typeof THREE): { scene: THREE.Scene; dispose(): void };

package/src/scene/studio.js

@@ -0,0 +1,81 @@
+/**
+ * @module @logomarks/logo3d/scene/studio
+ *
+ * A product studio for a logo to reflect, built as a small three.js scene and prefiltered like an HDRI: a dim room
+ * with a lighter floor, a broad soft key above and in front, a tall strip light either side, a low card in front and
+ * two thin rims behind.
+ * Chrome and glass pick these up as the long, clean highlights of a product photo; there are no point lights, so
+ * there are no highlight spots.
+ */
+
+/**
+ * @typedef {object} Softbox
+ * @property {[number, number, number]} at Its centre.
+ * @property {[number, number]} size Width and height.
+ * @property {number} power Its brightness (1 is white).
+ * @property {number} [fade] Its brightness at the bottom, as a share of the top's (1: even).
+ */
+
+/** The soft boxes, round a logo at the origin facing +z: a broad key overhead in front, a tall strip either side, a
+ * low card in front for the lower edges, two thin rims behind, and a wide card behind the camera fading from light to
+ * dark, which a face turned to the camera shows as a smooth gradient. The dark gaps between them are what draw
+ * chrome's crisp lines. */
+export const SOFTBOXES = Object.freeze(
+	/** @type {Softbox[]} */ ([
+		{ at: [0, 4.2, 3.4], size: [7, 2.6], power: 6 },
+		{ at: [-0.6, -1.1, 6.6], size: [12, 3.4], power: 1.5, fade: 0.04 },
+		{ at: [-4.6, 0.8, 1.8], size: [1.3, 6.5], power: 4.5 },
+		{ at: [4.6, 0.4, 2.2], size: [1.1, 6.5], power: 3.4 },
+		{ at: [0, -2.2, 4.6], size: [6, 1.1], power: 1.6 },
+		{ at: [-3.2, 1, -4.4], size: [0.6, 6], power: 2.6 },
+		{ at: [3.4, 1, -4.2], size: [0.6, 6], power: 2.6 },
+	]),
+);
+
+/**
+ * A unit panel whose brightness runs from 1 at the top to `fade` at the bottom (vertex colours).
+ *
+ * @param {typeof import('three')} THREE three.js.
+ * @param {number} fade The bottom's brightness.
+ * @returns {import('three').PlaneGeometry} The panel.
+ */
+function panelGeometry(THREE, fade) {
+	const g = new THREE.PlaneGeometry(1, 1, 1, 8);
+	const pos = g.attributes.position;
+	const col = [];
+	for (let i = 0; i < pos.count; i++) {
+		const k = fade + (1 - fade) * (pos.getY(i) + 0.5);
+		col.push(k, k, k);
+	}
+	g.setAttribute('color', new THREE.Float32BufferAttribute(col, 3));
+	return g;
+}
+
+/**
+ * The studio as a scene, for `PMREMGenerator.fromScene`.
+ *
+ * @param {typeof import('three')} THREE three.js.
+ * @returns {{ scene: import('three').Scene, dispose(): void }} The scene, and how to free it.
+ */
+export function studioScene(THREE) {
+	const scene = new THREE.Scene();
+	/** @type {{ dispose(): void }[]} */
+	const owned = [];
+	const keep = /** @type {<T extends { dispose(): void }>(t: T) => T} */ ((t) => (owned.push(t), t));
+	const room = new THREE.Mesh(keep(new THREE.BoxGeometry(14, 10, 14)), keep(new THREE.MeshBasicMaterial({ color: 0x232326, side: THREE.BackSide })));
+	room.position.y = 2;
+	scene.add(room);
+	// the floor a little lighter than the walls, as a studio's floor catches the key
+	const floor = new THREE.Mesh(keep(new THREE.PlaneGeometry(14, 14)), keep(new THREE.MeshBasicMaterial({ color: 0x55555a })));
+	floor.rotation.x = -Math.PI / 2;
+	floor.position.y = -2.9;
+	scene.add(floor);
+	for (const b of SOFTBOXES) {
+		const m = new THREE.Mesh(keep(panelGeometry(THREE, b.fade ?? 1)), keep(new THREE.MeshBasicMaterial({ color: new THREE.Color(1, 1, 1).multiplyScalar(b.power), vertexColors: true, side: THREE.DoubleSide })));
+		m.scale.set(b.size[0], b.size[1], 1);
+		m.position.set(...b.at);
+		m.lookAt(0, 0, 0);
+		scene.add(m);
+	}
+	return { scene, dispose: () => owned.forEach((o) => o.dispose()) };
+}

package/src/scene/view.d.ts

@@ -0,0 +1,69 @@
+import type * as THREE from 'three';
+import type { LogoGeometry } from '../geometry/index.js';
+import type { Pixels } from '../export/still.js';
+
+/** How the logo looks. */
+export interface Look {
+	/** The face's material (`MATERIALS`). */
+	material: string;
+	/** The sides' material, or null for the face's. */
+	side: string | null;
+	/** The logo's colour, `#rrggbb` (for materials that take one). */
+	color: string;
+	/** The environment (`ENVIRONMENTS`). */
+	environment: string;
+	/** `'transparent'`, `'solid'` or `'sweep'`. */
+	background: string;
+	backgroundColor: string;
+	/** The view (`VIEWS`). */
+	view: string;
+	/** The motion (`MOTIONS`). */
+	motion: string;
+}
+
+/** How a view is made. */
+export interface ViewOptions {
+	/** Each HDRI file's URL, by file name (`studio_small_09_1k.hdr`, …), as the page serves them. */
+	hdri?: Record<string, string>;
+	/** The canvas's pixel ratio (the device's, up to 2). */
+	pixelRatio?: number;
+	/** Whether a drag turns the logo (true). */
+	drag?: boolean;
+}
+
+/** A live view. */
+export interface LogoView {
+	readonly canvas: HTMLCanvasElement;
+	readonly renderer: THREE.WebGLRenderer;
+	readonly scene: THREE.Scene;
+	readonly camera: THREE.PerspectiveCamera;
+	readonly mesh: THREE.Mesh;
+	/** The look as it stands. */
+	readonly look: Look;
+	/** Shows a geometry; `colors`: its layers' own colours (null for the ink). */
+	setGeometry(g: LogoGeometry, colors?: (string | null)[]): void;
+	/** Changes the look; resolves once its environment is loaded. */
+	setLook(next: Partial<Look>): Promise<void>;
+	/** Undoes any drag. */
+	resetDrag(): void;
+	/** Draws a frame (at `t` seconds into the motion, or the current time). */
+	render(t?: number): void;
+	/** The motion's loop, seconds. */
+	period(): number;
+	/** A still, drawn off screen: RGBA pixels. `transparent` only applies on a transparent background. */
+	still(o: { width: number; height: number; transparent?: boolean; t?: number }): Pixels;
+	/** A still as a PNG. */
+	png(o: { width: number; height: number; transparent?: boolean; t?: number }): Promise<Blob>;
+	/** The logo as a binary glTF. */
+	glb(): Promise<Blob>;
+	/** A frame source for a video encoder: draws the frame at `t` seconds onto a canvas, at the size given. */
+	frames(o: { width: number; height: number }): (t: number, canvas: HTMLCanvasElement) => void;
+	dispose(): void;
+}
+
+/** The look a view starts with. */
+export const DEFAULT_LOOK: Readonly<Look>;
+/** Each layer's colour: one-colour logos take the look's; several keep their own, ink layers taking the look's. */
+export function colorsFor(layerColors: (string | null)[], color: string): string[];
+/** A live view on a canvas. */
+export function createView(canvas: HTMLCanvasElement, o?: ViewOptions): LogoView;