@3driseai/3drise-viewer 0.1.40 → 0.1.41

package/dist/components/image/core/relief.js

@@ -0,0 +1,94 @@
+// GENERATED from the lab (Claude outputs/gallery-lab/image/relief.mjs) by emit_image.mjs — change the lab and re-emit.
+// relief — an image variant (type 'image', config.type 'relief'). Material: MeshStandardMaterial (lit by the scene;
+// object effects attach).
+//
+// The picture is pressed into a sheet of paper: the surface is displaced by the picture's own local contrast — a
+// band-pass of its luminance (fine mip minus a coarse one), so edges and textures stand up as a low emboss and flat
+// areas stay flat (a plain luminance height would lift every sky). The scene's light rakes across the relief.
+// A change is a press travelling across the sheet: a soft crest lifts the paper along the front, the old
+// impression is pressed flat under it, the new one rises behind; the ink of the new picture lays down darks
+// first, then mids, then lights (it follows the crest, never a flat crossfade). The first picture is printed into
+// blank paper the same way. Idle: the sheet breathes — two slow, very low waves that move the highlights.
+// Cursor: `press` dents the paper under the cursor, `rake` deepens the relief around it (a loupe for texture).
+import * as THREE from 'three';
+import { baseUniforms, applyBase, setU, createPicture, stepPointer, patchMaterial, depthTwin } from './imageCore.js';
+export const POINTER_MODES = ['press', 'rake'];
+export const STRUCTURAL = ['imageUrls', 'detail'];
+export function createUniforms() {
+    return { ...baseUniforms(), uDepth: { value: 0.6 }, uCrest: { value: 0.6 }, uSelf: { value: 0.12 } };
+}
+export function applyConfig(u, c) {
+    applyBase(u, c, POINTER_MODES);
+    setU(u, 'uDepth', c.depth);
+    setU(u, 'uCrest', c.crest);
+    setU(u, 'uSelf', c.selfLight);
+    setU(u, 'uBlank', c.paperColor);
+}
+const pars = /* glsl */ `
+uniform float uDepth, uCrest, uSelf;
+varying vec2 vPic; varying float vL;
+// band-passed luminance: what stands up in the paper
+float bandA(vec2 uv){ return luma(picAL(uv, 1.0)) - luma(picAL(uv, 4.5)); }
+float bandB(vec2 uv){ return luma(picBL(uv, 1.0)) - luma(picBL(uv, 4.5)); }
+float heightAt(vec2 uv){
+  float l = localP(uv); float s = sstep(l); float bump = sin(PI * l);
+  vec2 xy = (uv - 0.5) * uSize;
+  float press = 1.0 - 0.85 * bump;                                  // the old impression is pressed flat under the crest
+  float h = mix(bandA(uv), bandB(uv), s) * press * uDepth * 0.12 * (1.0 + 0.04 * uBreathe * sin(uTime * 0.45));
+  h += uCrest * 0.09 * bump * bump * bump;                           // the crest
+  h += uBreathe * 0.004 * sin(xy.x * 1.3 + uTime * 0.37) * sin(xy.y * 1.9 - uTime * 0.29 + 1.0);
+  float pb = pointerBump(xy);
+  if (uPointerMode > -0.5 && uPointerMode < 0.5) h -= 0.07 * pb;                   // press
+  else if (uPointerMode > 0.5) h += mix(bandA(uv), bandB(uv), s) * uDepth * 0.12 * 2.5 * pb;   // rake
+  return h;
+}
+`;
+const vertex = /* glsl */ `
+  vec2 uv0 = position.xy + 0.5;
+  float e = 1.5 / 256.0;
+  float h0 = heightAt(uv0), hx = heightAt(uv0 + vec2(e, 0.0)), hy = heightAt(uv0 + vec2(0.0, e));
+  fxP = vec3(position.xy * uSize, h0);
+  fxN = normalize(vec3(-(hx - h0) / (e * uSize.x), -(hy - h0) / (e * uSize.y), 1.0));
+  vPic = uv0; vL = localP(uv0);
+`;
+const diffuse = /* glsl */ `
+  vec3 ca = picA(vPic), cb = picB(vPic);
+  float lb = luma(cb);
+  float crest = sin(PI * vL); crest *= crest;
+  vec3 pressed = mix(ca, uBlank, 0.55 * crest);                      // the old ink is lifted off under the crest
+  float inkB = smoothstep(lb * 0.45 + 0.3, lb * 0.45 + 0.55, vL);    // the new ink: darks first, lights last
+  vec3 pic = mix(pressed, cb, inkB);
+  diffuseColor.rgb = pic * uIntensity;
+  diffuseColor.a *= uOpacity;
+`;
+const emissive = /* glsl */ `
+  totalEmissiveRadiance += diffuseColor.rgb * uSelf;
+`;
+export function build(u, c) {
+    const object = new THREE.Group();
+    const segX = Math.max(16, c.detail | 0), segY = Math.round(segX * 0.65);
+    const geo = new THREE.PlaneGeometry(1, 1, segX, segY);
+    const P = { key: 'relief', uniforms: u, pars, vertex, diffuse, emissive };
+    const mat = patchMaterial(new THREE.MeshStandardMaterial({ roughness: c.roughness, metalness: 0, side: THREE.DoubleSide }), P);
+    const mesh = new THREE.Mesh(geo, mat);
+    mesh.castShadow = true;
+    mesh.receiveShadow = true;
+    mesh.frustumCulled = false;
+    mesh.customDepthMaterial = depthTwin(P);
+    object.add(mesh);
+    const cfg = { ...c };
+    const pic = createPicture(u, cfg);
+    const pst = {};
+    const api = {
+        object, materials: [mat, mesh.customDepthMaterial],
+        controls: { show: (t) => pic.show(t), get busy() { return pic.busy; }, pic },
+        apply(k) { Object.assign(cfg, k); applyConfig(u, k); if (k.roughness !== undefined)
+            mat.roughness = k.roughness; if (k.opacity !== undefined) {
+            mat.transparent = k.opacity < 1;
+            mat.depthWrite = k.opacity >= 1;
+        } },
+        update(dt, pointer) { dt = Math.min(dt, 0.1); u.uTime.value += dt; pic.step(dt); stepPointer(u, pointer, dt, pst); },
+        dispose() { geo.dispose(); mat.dispose(); mesh.customDepthMaterial.dispose(); pic.dispose(); },
+    };
+    return api;
+}

package/dist/components/image/core/roll.d.ts

@@ -0,0 +1,114 @@
+import * as THREE from 'three';
+export declare const POINTER_MODES: string[];
+export declare const STRUCTURAL: string[];
+export declare function createUniforms(): {
+    uRoll: {
+        value: number;
+    };
+    uSkew: {
+        value: number;
+    };
+    uBack: {
+        value: THREE.Color;
+    };
+    uSelf: {
+        value: number;
+    };
+    uTexA: {
+        value: any;
+    };
+    uTexB: {
+        value: any;
+    };
+    uFitA: {
+        value: THREE.Vector2;
+    };
+    uFitB: {
+        value: THREE.Vector2;
+    };
+    uP: {
+        value: number;
+    };
+    uHasA: {
+        value: number;
+    };
+    uSeq: {
+        value: number;
+    };
+    uSize: {
+        value: THREE.Vector2;
+    };
+    uTime: {
+        value: number;
+    };
+    uDir: {
+        value: THREE.Vector2;
+    };
+    uSpread: {
+        value: number;
+    };
+    uBlank: {
+        value: THREE.Color;
+    };
+    uIntensity: {
+        value: number;
+    };
+    uOpacity: {
+        value: number;
+    };
+    uBreathe: {
+        value: number;
+    };
+    uPointer: {
+        value: THREE.Vector3;
+    };
+    uPointerVel: {
+        value: THREE.Vector2;
+    };
+    uPointerActive: {
+        value: number;
+    };
+    uPointerMode: {
+        value: number;
+    };
+    uPointerStrength: {
+        value: number;
+    };
+    uPointerRadius: {
+        value: number;
+    };
+    uPointerColor: {
+        value: THREE.Color;
+    };
+};
+export declare function applyConfig(u: any, c: any): void;
+export declare function build(u: any, c: any): {
+    object: THREE.Group<THREE.Object3DEventMap>;
+    materials: any[];
+    controls: {
+        show: (t: any) => void;
+        readonly busy: boolean;
+        pic: {
+            st: {
+                A: any;
+                B: any;
+                aspA: number;
+                aspB: number;
+                p: number;
+                dir: number;
+                pending: any;
+                seq: number;
+                frame: number;
+            };
+            show: (tex: any) => void;
+            jump: (tex: any) => void;
+            step: (dt: any) => void;
+            readonly busy: boolean;
+            dispose(): void;
+        };
+    };
+    apply(k: any): void;
+    update(dt: any, pointer: any): void;
+    dispose(): void;
+};
+//# sourceMappingURL=roll.d.ts.map

package/dist/components/image/core/roll.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"roll.d.ts","sourceRoot":"","sources":["../../../../src/components/image/core/roll.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,eAAO,MAAM,aAAa,UAAoB,CAAC;AAC/C,eAAO,MAAM,UAAU,UAA0B,CAAC;AAElD,wBAAgB,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAE7B;AACD,wBAAgB,WAAW,CAAC,CAAC,KAAA,EAAE,CAAC,KAAA,QAG/B;AAsDD,wBAAgB,KAAK,CAAC,CAAC,KAAA,EAAE,CAAC,KAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAwBzB"}

package/dist/components/image/core/roll.js

@@ -0,0 +1,116 @@
+// GENERATED from the lab (Claude outputs/gallery-lab/image/roll.mjs) by emit_image.mjs — change the lab and re-emit.
+// roll — an image variant (type 'image', config.type 'roll'). Material: MeshStandardMaterial (double-sided; lit by
+// the scene; object effects attach).
+//
+// The picture is a print on paper, and a change is a slim paper roll travelling across it: ahead of the roll lies
+// the old print, which curls up around the roll's back and winds in; behind it the new print unwinds off the
+// roll's front and lies flat. Both sheets are the same subdivided plane bent in the vertex shader around a cylinder
+// of radius r at the roll position F (arc length preserved, tangent-continuous at the contact line), with material
+// past half a turn folded onto the roll's crest — so the picture never stretches and nothing pops. The printed
+// sides face inward on the roll, so from outside it is a clean paper tube catching the scene's light and casting a
+// soft shadow on the print. r grows from zero and returns to zero, so the roll appears and disappears in place.
+// Idle: the paper breathes (a very low swell). Cursor: `lift` — the paper lifts softly toward the cursor (air
+// under the sheet), `press` — it dents under it.
+import * as THREE from 'three';
+import { baseUniforms, applyBase, setU, createPicture, stepPointer, patchMaterial, depthTwin } from './imageCore.js';
+export const POINTER_MODES = ['lift', 'press'];
+export const STRUCTURAL = ['imageUrls', 'detail'];
+export function createUniforms() {
+    return { ...baseUniforms(), uRoll: { value: 1 }, uSkew: { value: 0.12 }, uBack: { value: new THREE.Color('#efebe3') }, uSelf: { value: 0.1 } };
+}
+export function applyConfig(u, c) {
+    applyBase(u, c, POINTER_MODES);
+    setU(u, 'uRoll', c.rollSize);
+    setU(u, 'uSkew', c.skew);
+    setU(u, 'uBack', c.paperColor);
+    setU(u, 'uSelf', c.selfLight);
+}
+const pars = /* glsl */ `
+uniform float uRoll, uSkew, uSelf, uWhich; uniform vec3 uBack;
+varying vec2 vPic; varying float vShade;
+float sheetH(vec2 xy){
+  float h = uBreathe * 0.005 * sin(xy.x * 1.4 + uTime * 0.33) * sin(xy.y * 1.8 - uTime * 0.27 + 0.7);
+  float pb = pointerBump(xy);
+  if (uPointerMode > -0.5 && uPointerMode < 0.5) h += 0.06 * pb; else if (uPointerMode > 0.5) h -= 0.05 * pb;
+  return h;
+}
+`;
+// s = coordinate along the travel; the roll line is s = F + skew * (coordinate across); A ahead (s > F), B behind.
+const vertex = /* glsl */ `
+  vec2 uv0 = position.xy + 0.5;
+  vec2 xy = position.xy * uSize;
+  vec2 dir = uDir, crossD = vec2(-uDir.y, uDir.x);
+  float ext = 0.5 * (abs(dir.x) * uSize.x + abs(dir.y) * uSize.y);
+  float extC = 0.5 * (abs(crossD.x) * uSize.x + abs(crossD.y) * uSize.y);
+  float s = dot(xy, dir), w = dot(xy, crossD);
+  float e = sstep(uP);
+  float skew = uSkew * ext * 0.5;
+  float F = mix(-ext - abs(skew), ext + abs(skew), e) + skew * (w / max(extC, 1e-3));
+  float r = max(uRoll * 0.07 * pow(sin(PI * uP), 0.6), 1e-4);
+  // which part of this sheet is wound: A behind the line (s < F), B ahead of it (s > F)
+  float d = uWhich < 0.5 ? (F - s) : (s - F);
+  float h = sheetH(xy);
+  if (d <= 0.0) {
+    float ee = 0.01;
+    float hx = sheetH(xy + vec2(ee, 0.0)), hy = sheetH(xy + vec2(0.0, ee));
+    fxP = vec3(xy, h);
+    fxN = normalize(vec3(-(hx - h) / ee, -(hy - h) / ee, 1.0));
+    vShade = 1.0 - 0.35 * exp(-abs(s - F) / (r * 1.2 + 1e-3)) * smoothstep(0.0, 0.02, r);   // contact shade at the roll
+  } else {
+    float th = min(d / r, PI);
+    float side = uWhich < 0.5 ? -1.0 : 1.0;                          // A winds up the back, B off the front
+    float ss = F + side * r * sin(th);
+    float zz = r - r * cos(th);
+    fxP = vec3(xy + dir * (ss - s), zz);
+    vec2 n = -vec2(side * sin(th), -cos(th));                         // printed side faces the roll's axis
+    fxN = normalize(vec3(dir * n.x, n.y));
+    vShade = 1.0;
+  }
+  vPic = uv0;
+`;
+const diffuse = /* glsl */ `
+  vec3 c = gl_FrontFacing ? (uWhich < 0.5 ? picA(vPic) : picB(vPic)) * uIntensity : uBack;
+  diffuseColor.rgb = c * vShade;
+  diffuseColor.a *= uOpacity;
+`;
+const emissive = /* glsl */ `
+  totalEmissiveRadiance += gl_FrontFacing ? diffuseColor.rgb * uSelf : vec3(0.0);
+`;
+export function build(u, c) {
+    const object = new THREE.Group();
+    const seg = Math.max(30, c.detail | 0);
+    const geo = new THREE.PlaneGeometry(1, 1, seg, Math.round(seg * 0.7));
+    const meshes = [], mats = [];
+    for (const which of [0, 1]) {
+        const uu = { ...u, uWhich: { value: which } };
+        const P = { key: 'roll', uniforms: uu, pars, vertex, diffuse, emissive };
+        const mat = patchMaterial(new THREE.MeshStandardMaterial({ roughness: c.roughness, metalness: 0, side: THREE.DoubleSide }), P);
+        const m = new THREE.Mesh(geo, mat);
+        m.castShadow = true;
+        m.receiveShadow = true;
+        m.frustumCulled = false;
+        m.customDepthMaterial = depthTwin(P);
+        meshes.push(m);
+        mats.push(mat);
+        object.add(m);
+    }
+    const cfg = { ...c };
+    const pic = createPicture(u, cfg);
+    const pst = {};
+    const api = {
+        object, materials: mats,
+        controls: { show: (t) => pic.show(t), get busy() { return pic.busy; }, pic },
+        apply(k) { Object.assign(cfg, k); applyConfig(u, k); for (const m of mats) {
+            if (k.roughness !== undefined)
+                m.roughness = k.roughness;
+            if (k.opacity !== undefined)
+                m.transparent = k.opacity < 1;
+        } },
+        update(dt, pointer) { dt = Math.min(dt, 0.1); u.uTime.value += dt; pic.step(dt); stepPointer(u, pointer, dt, pst); },
+        dispose() { geo.dispose(); for (const m of meshes) {
+            m.material.dispose();
+            m.customDepthMaterial.dispose();
+        } pic.dispose(); },
+    };
+    return api;
+}

package/dist/components/image/imageVariant.d.ts

@@ -0,0 +1,46 @@
+import React from 'react';
+import * as THREE from 'three';
+import type { AnimationOptions, MouseMoveDomain } from '@3driseai/3drise-core';
+import type { ObjectReadyProps } from '../../types/objectReady';
+export interface ImageVariantInstance {
+    object: THREE.Object3D;
+    apply(config: Record<string, unknown>): void;
+    update(dt: number, pointer: {
+        x: number;
+        y: number;
+        nx: number;
+        ny: number;
+    } | null, state?: unknown): void;
+    dispose(): void;
+    controls: {
+        show(tex: THREE.Texture): void;
+        readonly busy: boolean;
+        pic: {
+            jump(tex: THREE.Texture): void;
+        };
+    };
+}
+export interface ImageVariantModule {
+    POINTER_MODES: string[];
+    STRUCTURAL: string[];
+    createUniforms(): Record<string, THREE.IUniform>;
+    applyConfig(u: Record<string, THREE.IUniform>, c: Record<string, unknown>): void;
+    build(u: Record<string, THREE.IUniform>, c: Record<string, unknown>): ImageVariantInstance;
+}
+export interface ImageVariantProps<C> extends ObjectReadyProps {
+    config: C;
+    /** Scene object id: the live-edit handle is found by it. */
+    id?: string;
+    /** Keyframes on the config knobs (animations.image.animations). */
+    keyframes?: AnimationOptions[];
+    /** Pointer bindings on the config knobs (mouseMove.image). */
+    mouseMove?: MouseMoveDomain;
+}
+export declare function makeImageVariant<C extends {
+    imageUrls: string[];
+    interval: number;
+    enabled: boolean;
+}>(mod: ImageVariantModule, defaults: C, animatable: {
+    value: string;
+}[]): React.FC<ImageVariantProps<C>>;
+//# sourceMappingURL=imageVariant.d.ts.map

package/dist/components/image/imageVariant.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"imageVariant.d.ts","sourceRoot":"","sources":["../../../src/components/image/imageVariant.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAmE,MAAM,OAAO,CAAC;AACxF,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAE/B,OAAO,KAAK,EAAE,gBAAgB,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AAC/E,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAC;AAyBhE,MAAM,WAAW,oBAAoB;IACjC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC;IACvB,KAAK,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC7C,MAAM,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IAC5G,OAAO,IAAI,IAAI,CAAC;IAChB,QAAQ,EAAE;QAAE,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;QAAC,GAAG,EAAE;YAAE,IAAI,CAAC,GAAG,EAAE,KAAK,CAAC,OAAO,GAAG,IAAI,CAAA;SAAE,CAAA;KAAE,CAAC;CACjH;AACD,MAAM,WAAW,kBAAkB;IAC/B,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,cAAc,IAAI,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;IACjD,WAAW,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACjF,KAAK,CAAC,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,oBAAoB,CAAC;CAC9F;AACD,MAAM,WAAW,iBAAiB,CAAC,CAAC,CAAE,SAAQ,gBAAgB;IAC1D,MAAM,EAAE,CAAC,CAAC;IACV,4DAA4D;IAC5D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,mEAAmE;IACnE,SAAS,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC/B,8DAA8D;IAC9D,SAAS,CAAC,EAAE,eAAe,CAAC;CAC/B;AAqBD,wBAAgB,gBAAgB,CAAC,CAAC,SAAS;IAAE,SAAS,EAAE,MAAM,EAAE,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,OAAO,CAAA;CAAE,EAClG,GAAG,EAAE,kBAAkB,EAAE,QAAQ,EAAE,CAAC,EAAE,UAAU,EAAE;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,GACtE,KAAK,CAAC,EAAE,CAAC,iBAAiB,CAAC,CAAC,CAAC,CAAC,CAmGhC"}

package/dist/components/image/imageVariant.js

@@ -0,0 +1,128 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import * as THREE from 'three';
+import { useFrame } from '@react-three/fiber';
+import { withConfigDefaults } from '../../utils/configAnimations.js';
+import { useObjectReady } from '../../hooks/useObjectReady.js';
+import { useConfigDriver } from '../../hooks/useConfigDriver.js';
+import { usePointerField } from '../../utils/pointerField.js';
+import { usePictureCycle } from './pictureCycle.js';
+const loader = new THREE.TextureLoader();
+loader.setCrossOrigin('anonymous');
+function loadPicture(url) {
+    return new Promise((resolve, reject) => loader.load(url, (t) => {
+        t.colorSpace = THREE.SRGBColorSpace;
+        t.wrapS = t.wrapT = THREE.ClampToEdgeWrapping;
+        t.minFilter = THREE.LinearMipmapLinearFilter;
+        t.generateMipmaps = true; // the variants read soft mips (relief, focus, frost, flow fields)
+        t.anisotropy = 8;
+        resolve(t);
+    }, undefined, reject));
+}
+const _plane = new THREE.Plane();
+const _ray = new THREE.Raycaster();
+const _hit = new THREE.Vector3();
+const _n = new THREE.Vector3();
+const _o = new THREE.Vector3();
+export function makeImageVariant(mod, defaults, animatable) {
+    const STRUCTURAL = mod.STRUCTURAL;
+    const REBUILD = STRUCTURAL.filter((k) => k !== 'imageUrls');
+    const ANIMATABLE = new Set(animatable.map((p) => p.value));
+    const ImageVariant = ({ config, id, keyframes, mouseMove, onObjectReady, onObjectDispose }) => {
+        const rootRef = useRef(null);
+        useObjectReady(rootRef, config, onObjectReady, onObjectDispose);
+        const cfg = useMemo(() => withConfigDefaults(defaults, config), [config]);
+        const rebuildKey = REBUILD.map((k) => String(cfg[k])).join('|');
+        const shown = useRef(null); // the newest picture handed to the variant
+        const cache = useRef(new Map());
+        const loading = useRef('');
+        const built = useMemo(() => {
+            const u = mod.createUniforms();
+            mod.applyConfig(u, cfg);
+            const inst = mod.build(u, cfg);
+            inst.apply(cfg);
+            if (shown.current)
+                inst.controls.pic.jump(shown.current); // a rebuild lands on the current picture
+            inst.object.traverse((o) => { if (o.isMesh)
+                o.raycast = () => { }; });
+            const pick = new THREE.Mesh(new THREE.PlaneGeometry(1, 1), new THREE.MeshBasicMaterial({ visible: false }));
+            pick.name = 'imagePick';
+            inst.object.add(pick);
+            return { u, inst, pick };
+        }, [rebuildKey]); // eslint-disable-line react-hooks/exhaustive-deps
+        useEffect(() => () => {
+            built.inst.dispose();
+            built.pick.geometry.dispose();
+            built.pick.material.dispose();
+        }, [built]);
+        const instRef = useRef(built.inst);
+        instRef.current = built.inst;
+        /** Load a picture once (cached); a failed load is forgotten so it can be tried again. */
+        const load = useCallback((url) => {
+            let p = cache.current.get(url);
+            if (!p) {
+                p = loadPicture(url);
+                cache.current.set(url, p);
+                p.catch(() => cache.current.delete(url));
+            }
+            return p;
+        }, []);
+        /** The one door for a picture change: load, then the variant plays its change. A missing picture leaves the current one. */
+        const show = useCallback((url) => {
+            if (!url || url === loading.current)
+                return;
+            loading.current = url;
+            load(url).then((tex) => {
+                if (loading.current !== url)
+                    return; // superseded by a newer url
+                loading.current = '';
+                shown.current = tex;
+                instRef.current.controls.show(tex);
+            }).catch(() => { if (loading.current === url)
+                loading.current = ''; });
+        }, [load]);
+        const preload = useCallback((url) => { load(url).catch(() => { }); }, [load]);
+        const busy = useCallback(() => !!loading.current || instRef.current.controls.busy, []);
+        const { showExternal, feed } = usePictureCycle({ urls: cfg.imageUrls, interval: cfg.interval, show, preload, busy });
+        useEffect(() => {
+            const root = rootRef.current;
+            if (!root)
+                return;
+            root.userData.applyTexture = (url) => showExternal(url);
+            root.userData.feedImage = feed; // a gallery's feeds (gallery/kit/feeds.ts)
+            return () => { delete root.userData.applyTexture; delete root.userData.feedImage; };
+        }, [showExternal, feed]);
+        useEffect(() => () => { for (const p of cache.current.values())
+            p.then((t) => t.dispose(), () => { }); cache.current.clear(); }, []);
+        useLayoutEffect(() => { built.inst.apply(cfg); }, [built, cfg]);
+        const push = useCallback((merged) => { instRef.current.apply(merged); }, []);
+        useConfigDriver({ rootRef, id, family: 'image', base: cfg, structural: STRUCTURAL, allowed: ANIMATABLE, keyframes, mouseMove, push });
+        const pf = usePointerField();
+        useFrame((state, delta) => {
+            const dt = Math.min(delta, 0.1);
+            const { inst, u, pick } = built;
+            // the cursor on the picture's plane (the variant's object space)
+            let pointer = null;
+            if (pf.inside) {
+                const o = inst.object;
+                o.updateWorldMatrix(true, false);
+                _n.set(0, 0, 1).transformDirection(o.matrixWorld);
+                _o.setFromMatrixPosition(o.matrixWorld);
+                _plane.setFromNormalAndCoplanarPoint(_n, _o);
+                _ray.setFromCamera(pf.ndc, state.camera);
+                if (_ray.ray.intersectPlane(_plane, _hit)) {
+                    o.worldToLocal(_hit);
+                    pointer = { x: _hit.x, y: _hit.y, nx: pf.ndc.x, ny: pf.ndc.y };
+                }
+            }
+            inst.update(dt, pointer, state);
+            const size = u.uSize?.value;
+            if (size)
+                pick.scale.set(size.x, size.y, 1);
+        });
+        if (!cfg.enabled)
+            return null;
+        return (_jsx("group", { ref: rootRef, children: _jsx("primitive", { object: built.inst.object }) }));
+    };
+    return ImageVariant;
+}

package/dist/components/image/index.d.ts

@@ -0,0 +1,22 @@
+export {};
+export type { ShardsImageProps } from './ShardsImage';
+export { default as ShardsImage } from './ShardsImage';
+export type { ProjectorImageProps } from './ProjectorImage';
+export { default as ProjectorImage } from './ProjectorImage';
+export type { ReliefImageProps } from './ReliefImage';
+export { default as ReliefImage } from './ReliefImage';
+export type { PinscreenImageProps } from './PinscreenImage';
+export { default as PinscreenImage } from './PinscreenImage';
+export type { PrismImageProps } from './PrismImage';
+export { default as PrismImage } from './PrismImage';
+export type { LenticularImageProps } from './LenticularImage';
+export { default as LenticularImage } from './LenticularImage';
+export type { FrostImageProps } from './FrostImage';
+export { default as FrostImage } from './FrostImage';
+export type { RollImageProps } from './RollImage';
+export { default as RollImage } from './RollImage';
+export type { ContourImageProps } from './ContourImage';
+export { default as ContourImage } from './ContourImage';
+export type { EngravingImageProps } from './EngravingImage';
+export { default as EngravingImage } from './EngravingImage';
+//# sourceMappingURL=index.d.ts.map

package/dist/components/image/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/image/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC;AACV,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACtD,OAAO,EAAE,OAAO,IAAI,WAAW,EAAE,MAAM,eAAe,CAAC;AACvD,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAC7D,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AAC9D,OAAO,EAAE,OAAO,IAAI,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAC/D,YAAY,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,OAAO,IAAI,UAAU,EAAE,MAAM,cAAc,CAAC;AACrD,YAAY,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,OAAO,IAAI,SAAS,EAAE,MAAM,aAAa,CAAC;AACnD,YAAY,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,OAAO,IAAI,YAAY,EAAE,MAAM,gBAAgB,CAAC;AACzD,YAAY,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AAC5D,OAAO,EAAE,OAAO,IAAI,cAAc,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/components/image/index.js

@@ -0,0 +1,10 @@
+export { default as ShardsImage } from './ShardsImage.js';
+export { default as ProjectorImage } from './ProjectorImage.js';
+export { default as ReliefImage } from './ReliefImage.js';
+export { default as PinscreenImage } from './PinscreenImage.js';
+export { default as PrismImage } from './PrismImage.js';
+export { default as LenticularImage } from './LenticularImage.js';
+export { default as FrostImage } from './FrostImage.js';
+export { default as RollImage } from './RollImage.js';
+export { default as ContourImage } from './ContourImage.js';
+export { default as EngravingImage } from './EngravingImage.js';

package/dist/components/image/pictureCycle.d.ts

@@ -0,0 +1,15 @@
+export interface PictureCycleOptions {
+    urls: string[] | undefined;
+    interval: number;
+    /** Start the change to this picture (the variant's one door). */
+    show(url: string): void;
+    /** Load a picture ahead of time, without showing it. */
+    preload?(url: string): void;
+    /** True while a change plays or a picture loads: the clock waits. */
+    busy(): boolean;
+}
+export declare function usePictureCycle({ urls, interval, show, preload, busy }: PictureCycleOptions): {
+    showExternal: (url: string) => void;
+    feed: (url: string | null) => void;
+};
+//# sourceMappingURL=pictureCycle.d.ts.map

package/dist/components/image/pictureCycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pictureCycle.d.ts","sourceRoot":"","sources":["../../../src/components/image/pictureCycle.ts"],"names":[],"mappings":"AAqBA,MAAM,WAAW,mBAAmB;IAChC,IAAI,EAAE,MAAM,EAAE,GAAG,SAAS,CAAC;IAC3B,QAAQ,EAAE,MAAM,CAAC;IACjB,iEAAiE;IACjE,IAAI,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,wDAAwD;IACxD,OAAO,CAAC,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,qEAAqE;IACrE,IAAI,IAAI,OAAO,CAAC;CACnB;AAED,wBAAgB,eAAe,CAAC,EAAE,IAAI,EAAE,QAAQ,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,EAAE,mBAAmB;wBA+BjD,MAAM;gBAQd,MAAM,GAAG,IAAI;EAgB/C"}

package/dist/components/image/pictureCycle.js

@@ -0,0 +1,82 @@
+import { useCallback, useEffect, useRef } from 'react';
+import { useFrame } from '@react-three/fiber';
+export function usePictureCycle({ urls, interval, show, preload, busy }) {
+    const list = urls ?? [];
+    const key = list.join('\n');
+    const st = useRef({ idx: 0, t: 0, current: '', preloaded: '', held: false });
+    const live = useRef({ list, interval, show, preload, busy });
+    live.current = { list, interval, show, preload, busy };
+    // the list changed: keep the picture shown if it is still there, else go to the first
+    useEffect(() => {
+        const s = st.current, L = live.current.list;
+        if (!L.length || s.held)
+            return;
+        const at = s.current ? L.indexOf(s.current) : -1;
+        if (at >= 0) {
+            s.idx = at;
+            return;
+        }
+        s.idx = 0;
+        s.t = 0;
+        s.current = L[0];
+        live.current.show(L[0]);
+    }, [key]);
+    useFrame((_, delta) => {
+        const s = st.current, { list: L, interval: iv, preload: pre, busy: isBusy } = live.current;
+        const n = L.length;
+        if (s.held)
+            return;
+        if (n < 2 || !(iv > 0) || isBusy()) {
+            s.t = 0;
+            return;
+        }
+        const next = L[(s.idx + 1) % n];
+        if (pre && s.preloaded !== next) {
+            s.preloaded = next;
+            pre(next);
+        }
+        s.t += Math.min(delta, 0.1);
+        if (s.t < iv)
+            return;
+        s.t = 0;
+        s.idx = (s.idx + 1) % n;
+        s.current = L[s.idx];
+        live.current.show(s.current);
+    });
+    /** A picture sent from outside (displayImage): change to it, the cycle carries on from it. */
+    const showExternal = useCallback((url) => {
+        if (!url)
+            return;
+        const s = st.current, at = live.current.list.indexOf(url);
+        if (at >= 0)
+            s.idx = at;
+        s.t = 0;
+        s.current = url;
+        live.current.show(url);
+    }, []);
+    /** A gallery feeding this object (userData.feedImage): show its picture and hold the own cycle; null ends the feed. */
+    const feed = useCallback((url) => {
+        const s = st.current;
+        if (url) {
+            s.held = true;
+            s.t = 0;
+            if (s.current !== url) {
+                s.current = url;
+                live.current.show(url);
+            }
+            return;
+        }
+        if (!s.held)
+            return;
+        s.held = false;
+        s.t = 0;
+        const L = live.current.list;
+        if (!L.length)
+            return;
+        const own = L[Math.min(s.idx, L.length - 1)];
+        s.idx = L.indexOf(own);
+        s.current = own;
+        live.current.show(own);
+    }, []);
+    return { showExternal, feed };
+}

package/dist/components/index.d.ts

@@ -76,6 +76,8 @@ export { default as EnvironmentManager } from './EnvironmentManager';
 export { default as HdrEnvironment, isHdrActive } from './HdrEnvironment';
 export { default as EnvironmentObject } from './EnvironmentObject';
 export { default as TextGenerator } from './TextGenerator';
+export { default as ImageObject } from './ImageObject';
+export { default as GalleryObject } from './GalleryObject';
 export { default as Frame } from './Frame';
 export { FrameGeometry } from './FrameGeometry';
 export { FrameImage } from './FrameImage';
@@ -166,6 +168,8 @@ export { default as AdaptiveResolution } from './AdaptiveResolution';
 export { default as LandObject } from './LandObject';
 export * from './space';
 export * from './text';
+export * from './image';
+export * from './gallery';
 export * from './spotBeam';
 export * from './ledArray';
 export * from './fluorescentTube';