cozyclay 1.2.0 → 1.5.0

package/src/scene-objects.js

@@ -31,9 +31,14 @@ export const SCENE_VERSION = 1;
 const EULER_ORDER = "XYZ";
 const DEG = Math.PI / 180;
 
-/** Room half-extent; matches the plan board's ROOM_LIMIT. */
-const ROOM_LIMIT = 11;
-const CEILING = 6;
+/** Stage half-extent; matches the plan board's ROOM_LIMIT. The set is an
+ * open 500 m deck now, so the clamp is a guard against runaway coordinates,
+ * not a wall — it stops just inside the floor's edge. */
+const ROOM_LIMIT = 240;
+// Headroom, not a ceiling: the walls (and the 6.2 m room they implied) are
+// gone, so this only stops a runaway coordinate. A rocket, a crane or a
+// skyline piece all have to fit under it.
+const CEILING = 240;
 const SCALE_MIN = 0.1;
 const SCALE_MAX = 100;
 
@@ -72,10 +77,71 @@ export const OBJECT_LIBRARY = [
  * inspector. */
 export const OBJECT_COLORS = ["#e2e5e6", GREY_BOX, "#9aa1a5", "#767d81", "#d9b18c", "#8fae9b"];
 
+/**
+ * A cutout is a standee: an imported image standing on a card. Its size is NOT
+ * library data — the height is measured by the user and the width follows the
+ * picture's own aspect — so the record carries `assetId`, `aspect` and
+ * `height`, and the footprint is DERIVED from them. Deriving rather than
+ * storing is what stops a card persisting a width its picture disagrees with.
+ */
+export const CUTOUT_KIND = "cutout";
+/** Card thickness in metres: thin enough to read as flat, thick enough that
+ * the plan board and dropToSurfacePatch still have a rectangle to work on. */
+export const CUTOUT_THICKNESS = 0.02;
+/** A fresh cutout stands as tall as the figure it blocks against
+ * (SUBJECT_HEIGHT_M), so the first thing you see is honest scale. */
+export const CUTOUT_DEFAULT_HEIGHT = 1.8;
+const CUTOUT_HEIGHT_MIN = 0.05;
+const CUTOUT_ASPECT_MIN = 0.02;
+const CUTOUT_ASPECT_MAX = 50;
+/** Cutouts carry their own colour: unlike a primitive, the card IS the thing
+ * it depicts, so it is tinted white and multiplies the image untouched. */
+const CUTOUT_TINT = "#ffffff";
+const CUTOUT_ENTRY = {
+	kind: CUTOUT_KIND,
+	label: "Cutout",
+	group: "Images",
+	footprint: { width: 1, depth: CUTOUT_THICKNESS },
+	height: CUTOUT_DEFAULT_HEIGHT,
+	color: CUTOUT_TINT,
+};
+
+/** Every kind that can exist in a scene: the catalogue you can create from,
+ * plus the kinds that arrive by import and so are deliberately absent from the
+ * "Add object" menu (a cutout without an image has nothing to draw). */
 function objectLibraryEntry(kind) {
+	if (kind === CUTOUT_KIND) return CUTOUT_ENTRY;
 	return OBJECT_LIBRARY.find((entry) => entry.kind === kind) ?? null;
 }
 
+const cutoutHeight = (value) => Math.max(CUTOUT_HEIGHT_MIN, value);
+const cutoutAspect = (value) => clamp(value, CUTOUT_ASPECT_MIN, CUTOUT_ASPECT_MAX);
+
+/** How far a card may be pulled off the picture's own proportions. */
+export const CUTOUT_STRETCH_MIN = 0.1;
+export const CUTOUT_STRETCH_MAX = 10;
+export const cutoutStretch = (value) => {
+	const n = Number(value);
+	return Number.isFinite(n) ? clamp(n, CUTOUT_STRETCH_MIN, CUTOUT_STRETCH_MAX) : 1;
+};
+
+/**
+ * The plan-board rectangle a card of this height and picture aspect occupies.
+ * `aspect` is the image's width / height.
+ *
+ * `stretch` is how far the card has been pulled off those proportions: 1 is the
+ * picture undistorted. It is kept as its own factor rather than folded into
+ * `aspect` so the photograph's true proportions survive every edit — a re-cut
+ * recomputes `aspect` from the trimmed image, and a card that had been widened
+ * would otherwise silently lose or compound that widening.
+ */
+export function cutoutFootprint(height, aspect, stretch = 1) {
+	return {
+		width: cutoutHeight(height) * cutoutAspect(aspect) * cutoutStretch(stretch),
+		depth: CUTOUT_THICKNESS,
+	};
+}
+
 export function sceneObjectHierarchyId(id) {
 	return `object:${id}`;
 }
@@ -90,6 +156,9 @@ export function sceneObjectIdFromHierarchy(hierarchyId) {
  * camera); everything else starts neutral so the first drag is predictable.
  */
 export function createSceneObject(kind, existing = [], placement = {}) {
+	// Cutouts come from an import, never from the catalogue: without an asset
+	// id the record has nothing to draw. `createCutoutObject` is their door.
+	if (kind === CUTOUT_KIND) return null;
 	const entry = objectLibraryEntry(kind);
 	if (!entry) return null;
 	const names = new Set(existing.map((object) => object.name));
@@ -112,11 +181,93 @@ export function createSceneObject(kind, existing = [], placement = {}) {
 		scaleY: 1,
 		scaleZ: 1,
 		color: entry.color,
+		parent: null,
 		footprint: { ...entry.footprint },
 		height: entry.height,
 	};
 }
 
+/**
+ * A fresh cutout for an imported image. `assetId` addresses the picture in the
+ * asset store — the record never carries the bytes, which is what keeps a
+ * scene small enough to live in localStorage — and `aspect` is the image's
+ * width / height so the card can be sized by height alone.
+ *
+ * `name` seeds the display name (the file's own name is the obvious caller
+ * choice); everything else starts neutral, exactly like a catalogue object.
+ */
+export function createCutoutObject({ assetId, aspect = 1, height = CUTOUT_DEFAULT_HEIGHT, name = "", sourceAssetId, matteAssetId, matteScale, stretch } = {}, existing = [], placement = {}) {
+	if (typeof assetId !== "string" || !assetId) return null;
+	const pictureAspect = cutoutAspect(Number(aspect));
+	const cardHeight = cutoutHeight(Number(height));
+	if (!Number.isFinite(pictureAspect) || !Number.isFinite(cardHeight)) return null;
+	// A duplicate hands the lineage in so the copy stays re-editable: the
+	// picture it renders, the photograph it came from, the selection mask,
+	// the trim factor and the stretch. A fresh import passes none, so the
+	// defaults below leave it as its own unmasked original — exactly the
+	// record an untouched card has always carried.
+	const cardStretch = cutoutStretch(stretch);
+	const base = typeof name === "string" && name.trim() ? name.trim() : CUTOUT_ENTRY.label;
+	const names = new Set(existing.map((object) => object.name));
+	let displayName = base;
+	for (let n = 2; names.has(displayName); n += 1) displayName = `${base} ${n}`;
+	const ids = new Set(existing.map((object) => object.id));
+	let id = CUTOUT_KIND;
+	for (let n = 2; ids.has(id); n += 1) id = `${CUTOUT_KIND}-${n}`;
+	return {
+		id,
+		name: displayName,
+		renderer: CUTOUT_KIND,
+		x: clamp(Number(placement.x) || 0, -ROOM_LIMIT, ROOM_LIMIT),
+		y: 0,
+		z: clamp(Number(placement.z) || 0, -ROOM_LIMIT, ROOM_LIMIT),
+		rot: wrapAngle(Number(placement.rot) || 0),
+		rotX: 0,
+		rotZ: 0,
+		scaleX: 1,
+		scaleY: 1,
+		scaleZ: 1,
+		color: CUTOUT_TINT,
+		parent: null,
+		// Key order matches what `normalizeSceneObject` writes, so a record
+		// survives a storage round trip byte-for-byte.
+		assetId,
+		// A picture nobody has cut is its own original, with no purple on it;
+		// a duplicate passes the lineage through so the copy stays re-editable.
+		sourceAssetId: typeof sourceAssetId === "string" && sourceAssetId ? sourceAssetId : assetId,
+		matteAssetId: typeof matteAssetId === "string" ? matteAssetId : "",
+		matteScale: Number.isFinite(Number(matteScale)) ? Number(matteScale) : 1,
+		aspect: pictureAspect,
+		// A new card wears the picture's own proportions; a widened one carries
+		// its factor through so the copy keeps the shape it was pulled to.
+		stretch: cardStretch,
+		footprint: cutoutFootprint(cardHeight, pictureAspect, cardStretch),
+		height: cardHeight,
+	};
+}
+
+/**
+ * The option bundle a cutout duplicate hands to `createCutoutObject`. A copy
+ * is minted through the same door an import is, so it must carry the picture
+ * it renders AND the photograph it came from, the selection mask, the trim
+ * factor and the stretch — otherwise the matte is silently reset and the
+ * duplicate is no longer re-editable. Kept as its own pure helper so the
+ * duplicate path and its test speak the very same option-building, not a
+ * hand-rolled copy.
+ */
+export function duplicateCutoutOptions(object) {
+	return {
+		assetId: object.assetId,
+		aspect: object.aspect,
+		height: object.height,
+		name: object.name,
+		sourceAssetId: object.sourceAssetId,
+		matteAssetId: object.matteAssetId,
+		matteScale: object.matteScale,
+		stretch: object.stretch,
+	};
+}
+
 /** Every writable transform channel and the rule that keeps it in the room. */
 const TRANSFORM_LIMITS = {
 	x: (value) => clamp(value, -ROOM_LIMIT, ROOM_LIMIT),
@@ -130,10 +281,60 @@ const TRANSFORM_LIMITS = {
 	scaleZ: (value) => clamp(value, SCALE_MIN, SCALE_MAX),
 };
 
+/** Every object that hangs off `id`, at any depth. A cycle cannot form because
+ * setParent refuses one, but the seen-set keeps this total even if data is
+ * hand-edited into a loop. */
+export function descendantsOf(objects, id) {
+	const out = [];
+	const seen = new Set([id]);
+	let frontier = [id];
+	while (frontier.length) {
+		const next = [];
+		for (const object of objects) {
+			if (object.parent && frontier.includes(object.parent) && !seen.has(object.id)) {
+				seen.add(object.id);
+				out.push(object);
+				next.push(object.id);
+			}
+		}
+		frontier = next;
+	}
+	return out;
+}
+
 export function updateSceneObject(objects, id, patch) {
 	let changed = false;
+	const target = objects.find((object) => object.id === id);
+	// A parent carries its children: the group is dragged, nudged and dropped as
+	// one body. Only translation rides along — rotating or scaling a group would
+	// have to orbit and rescale every child about the parent's origin, which is a
+	// different feature and is deliberately not pretended at here.
+	const carried = target ? descendantsOf(objects, id) : [];
+	const delta = { x: 0, y: 0, z: 0 };
+	if (target) {
+		for (const axis of ["x", "y", "z"]) {
+			if (patch[axis] === undefined) continue;
+			const value = Number(patch[axis]);
+			if (!Number.isFinite(value)) continue;
+			delta[axis] = TRANSFORM_LIMITS[axis](value) - target[axis];
+		}
+	}
+	const moving = new Set(carried.map((object) => object.id));
+	const shifts = delta.x || delta.y || delta.z;
+
 	const next = objects.map((object) => {
-		if (object.id !== id) return object;
+		if (object.id !== id) {
+			if (!shifts || !moving.has(object.id)) return object;
+			const update = {};
+			for (const axis of ["x", "y", "z"]) {
+				if (!delta[axis]) continue;
+				const bounded = TRANSFORM_LIMITS[axis](object[axis] + delta[axis]);
+				if (bounded !== object[axis]) update[axis] = bounded;
+			}
+			if (!Object.keys(update).length) return object;
+			changed = true;
+			return { ...object, ...update };
+		}
 		const update = {};
 		for (const [key, limit] of Object.entries(TRANSFORM_LIMITS)) {
 			if (patch[key] === undefined) continue;
@@ -147,6 +348,51 @@ export function updateSceneObject(objects, id, patch) {
 			if (typeof patch[key] !== "string" || !patch[key] || patch[key] === object[key]) continue;
 			update[key] = patch[key];
 		}
+		// A cutout is sized in metres — you measure something in the picture and
+		// type its height — so `height` and `aspect` are writable where every
+		// other kind takes them from the library. The footprint is DERIVED here
+		// and never patched: one owner for the card's width is what keeps it
+		// from disagreeing with its own image.
+		if (object.renderer === CUTOUT_KIND) {
+			// The picture itself is writable: cutting the background out stores a
+			// NEW asset (different bytes, different id) and points the card at it,
+			// which is what makes the cut undoable — the original stays addressed
+			// by the history entry before it.
+			// Three ids, because a cut card is not one picture: `assetId` is what
+			// the set renders, `sourceAssetId` is the photograph it came from and
+			// keeps being edited from, and `matteAssetId` is the purple itself.
+			// Keeping all three is what makes the cut re-editable instead of
+			// destructive — the original is never replaced, only masked.
+			for (const key of ["assetId", "sourceAssetId", "matteAssetId"]) {
+				if (typeof patch[key] === "string" && patch[key] && patch[key] !== object[key]) update[key] = patch[key];
+			}
+			// How much of the original frame the trimmed card is. Stored so a
+			// second edit can work out the height the card would have at full
+			// frame instead of compounding one trim onto the last.
+			if (Number.isFinite(Number(patch.matteScale))) {
+				const scale = clamp(Number(patch.matteScale), 0.01, 1);
+				if (scale !== object.matteScale) update.matteScale = scale;
+			}
+			const patchedHeight = patch.height === undefined ? NaN : cutoutHeight(Number(patch.height));
+			const patchedAspect = patch.aspect === undefined ? NaN : cutoutAspect(Number(patch.aspect));
+			const height = Number.isFinite(patchedHeight) ? patchedHeight : object.height;
+			const aspect = Number.isFinite(patchedAspect) ? patchedAspect : object.aspect;
+			const previousStretch = cutoutStretch(object.stretch);
+			// A width in metres is what the inspector and the drag both speak, so it
+			// is accepted directly and kept as the factor the record stores.
+			const patchedStretch =
+				patch.width !== undefined && Number.isFinite(Number(patch.width))
+					? cutoutStretch(Number(patch.width) / (height * aspect))
+					: patch.stretch === undefined
+						? previousStretch
+						: cutoutStretch(patch.stretch);
+			if (height !== object.height || aspect !== object.aspect || patchedStretch !== previousStretch) {
+				update.height = height;
+				update.aspect = aspect;
+				update.stretch = patchedStretch;
+				update.footprint = cutoutFootprint(height, aspect, patchedStretch);
+			}
+		}
 		if (!Object.keys(update).length) return object;
 		changed = true;
 		return { ...object, ...update };
@@ -154,9 +400,33 @@ export function updateSceneObject(objects, id, patch) {
 	return changed ? next : objects;
 }
 
+/**
+ * Attach `id` to `parentId` (or detach with null). Refuses the two shapes that
+ * would corrupt the tree: an object parented to itself, and a cycle formed by
+ * parenting an object to one of its own descendants.
+ */
+export function setSceneObjectParent(objects, id, parentId) {
+	if (id === parentId) return objects;
+	if (parentId !== null && !objects.some((object) => object.id === parentId)) return objects;
+	if (parentId !== null && descendantsOf(objects, id).some((object) => object.id === parentId)) return objects;
+	let changed = false;
+	const next = objects.map((object) => {
+		if (object.id !== id) return object;
+		const parent = parentId ?? null;
+		if ((object.parent ?? null) === parent) return object;
+		changed = true;
+		return { ...object, parent };
+	});
+	return changed ? next : objects;
+}
+
 export function removeSceneObject(objects, id) {
 	const next = objects.filter((object) => object.id !== id);
-	return next.length === objects.length ? objects : next;
+	if (next.length === objects.length) return objects;
+	// Deleting a parent must not leave its children pointing at a ghost: they
+	// are promoted to top level rather than vanishing with it, because a group
+	// is an editing convenience and never an owner of the parts.
+	return next.map((object) => (object.parent === id ? { ...object, parent: null } : object));
 }
 /* -------------------------------------------------- persistence ---- */
 
@@ -173,6 +443,11 @@ export function normalizeSceneObject(record) {
 	const entry = objectLibraryEntry(record.renderer);
 	if (!entry) return null;
 	if (typeof record.id !== "string" || !record.id) return null;
+	// A cutout addresses its picture by id. A record without one has nothing to
+	// draw, so it is dropped rather than restored as a blank card — the same
+	// rule an unknown renderer already gets.
+	const isCutout = entry.kind === CUTOUT_KIND;
+	if (isCutout && (typeof record.assetId !== "string" || !record.assetId)) return null;
 	// Defensive import fallback, not a migration: hand-authored or external
 	// payloads may carry one `scale` (the pre-split record shape). It fans
 	// out to all three axes only when no axis is present — an explicit
@@ -198,8 +473,34 @@ export function normalizeSceneObject(record) {
 		scaleY: TRANSFORM_LIMITS.scaleY(pick(record.scaleY, scaleFallback)),
 		scaleZ: TRANSFORM_LIMITS.scaleZ(pick(record.scaleZ, scaleFallback)),
 		color: typeof record.color === "string" && record.color ? record.color : entry.color,
-		footprint: { ...entry.footprint },
-		height: entry.height,
+		// Group membership. null is a top-level object; the id of another object
+		// makes this one ride along when that object moves.
+		parent: typeof record.parent === "string" && record.parent ? record.parent : null,
+		// Library kinds take their size from the library — a stored footprint is
+		// stale data, not a fact. A cutout is the exception: its size IS
+		// per-instance, so height and aspect are repaired from the record and
+		// the footprint is rebuilt from the pair.
+		...(isCutout
+			? {
+					assetId: record.assetId,
+					// An older record (or a hand-authored one) has no source: the
+					// picture it points at IS the original, because nothing has
+					// been cut from it yet.
+					sourceAssetId: typeof record.sourceAssetId === "string" && record.sourceAssetId ? record.sourceAssetId : record.assetId,
+					matteAssetId: typeof record.matteAssetId === "string" ? record.matteAssetId : "",
+					matteScale: clamp(pick(record.matteScale, 1), 0.01, 1),
+					aspect: cutoutAspect(pick(record.aspect, 1)),
+					// A record written before cards could be stretched has none, and
+					// 1 is exactly what it meant: the picture's own proportions.
+					stretch: cutoutStretch(pick(record.stretch, 1)),
+					footprint: cutoutFootprint(
+						pick(record.height, CUTOUT_DEFAULT_HEIGHT),
+						pick(record.aspect, 1),
+						pick(record.stretch, 1),
+					),
+					height: cutoutHeight(pick(record.height, CUTOUT_DEFAULT_HEIGHT)),
+				}
+			: { footprint: { ...entry.footprint }, height: entry.height }),
 	};
 }