@micrio/client 7.0.7 → 7.0.9

package/micrio.min.d.ts

@@ -1444,6 +1444,14 @@ declare module '@micrio/client' {
         #private;
         /** Possible .zoom() override for Book3D */
         _zoomOverride: ((n: number) => void) | undefined;
+        /** Possible override for Book3D */
+        _isZoomedInOverride: (() => boolean) | undefined;
+        /** Possible override for `_getXYDirect` for Book3D */
+        _getXYDirectOverride: ((x: number, y: number) => Float64Array) | undefined;
+        /** getMatrix book3d override */
+        _getMatrixOverride: ((x: number, y: number, scale: number, rotX?: number, rotY?: number, rotZ?: number, scaleX?: number, scaleY?: number, 
+        /** The element's content width in CSS pixels (used to convert `scale` to a world size). */
+        width?: number) => Float32Array) | undefined;
         /**
          * Gets the current image view rectangle [x0, y0, width, height].
          */
@@ -1547,7 +1555,9 @@ declare module '@micrio/client' {
          * @param x The image X coordinate (0-1).
          * @param y The image Y coordinate (0-1).
          * @param scale The object scale multiplier.
-         * @param radius The object radius (distance from center, default 10).
+         * @param radius The object radius (distance from center, default 10). For Book3D images
+         * this is used as the element's content width in CSS pixels, so `scale` stays a fraction
+         * of the page width.
          * @param rotX The object X rotation in radians.
          * @param rotY The object Y rotation in radians.
          * @param rotZ The object Z rotation in radians.
@@ -1771,6 +1781,490 @@ declare module '@micrio/client' {
         animateTo(idx: number): void;
     }
 
+    export class Vec3 {
+        #private;
+        _x: number;
+        _y: number;
+        _z: number;
+        constructor(_x?: number, _y?: number, _z?: number);
+        _clone(): Vec3;
+        _set(x: number, y: number, z: number): Vec3;
+        _copy(v: Vec3): Vec3;
+        _add(v: Vec3): Vec3;
+        _sub(v: Vec3): Vec3;
+        _length(): number;
+        _normalize(): Vec3;
+        _dot(v: Vec3): number;
+        _cross(v: Vec3): Vec3;
+    }
+
+    /** Thickness of a single paper page in world-space units */
+    export const PAGE_THICKNESS = 0.0012;
+    /** Default page aspect ratio (height / width) — √2 ≅ A4 paper */
+    export const DEFAULT_ASPECT: number;
+    /** Use each page's own aspect ratio from source images instead of the book-wide average */
+    export const USE_INDIVIDUAL_ASPECTS = false;
+    /** Whether the first/last pages are rendered as hard covers */
+    export const HARD_COVER = false;
+    /** Cover thickness relative to a regular paper page */
+    export const COVER_THICKNESS_MULTIPLIER = 16;
+    /** Cover face scale relative to paper face (1.04 = 4% larger on width) */
+    export const COVER_SCALE_X = 1.04;
+    /** Cover face scale relative to paper face on height axis (1.08 = 8% taller) */
+    export const COVER_SCALE_Y = 1.08;
+    /** Number of vertex columns in the paper/cover face grid */
+    export const GRID_COLS = 10;
+    /** Number of vertex rows in the paper/cover face grid */
+    export const GRID_ROWS = 14;
+    /** Total vertex count per face grid */
+    export const VERTEX_COUNT: number;
+    /** Flip speed multiplier (1.0 = baseline, higher = faster flip) */
+    export const FLIP_SPEED = 0.6;
+    /** How far from the top edge to grab the corner during a flip (0.0 = top, 1.0 = bottom) */
+    export const GRAB_ROW = 0.35;
+    /** Maximum random offset added to GRAB_ROW each flip, to make the transition more natural */
+    export const GRAB_ROW_MAX_OFFSET = 0.12;
+    /** Tighter max random offset used during rapid .goto() flips for a more uniform look */
+    export const GOTO_GRAB_ROW_MAX_OFFSET = 0.02;
+    /** Peak arc height of the flipped corner above the rest position */
+    export const ARC_PEAK = 0.7;
+    /** Base duration (seconds) for a full page flip at speed 1.0 */
+    export const BASE_FLIP_DURATION = 0.6;
+    /** Number of constraint solver iterations per substep */
+    export const SOLVER_ITERATIONS = 64;
+    /** Number of physics substeps per frame */
+    export const SOLVER_SUBSTEPS = 3;
+    /** Distance constraint compliance (0.0 = perfectly stiff) */
+    export const DISTANCE_COMPLIANCE = 0;
+    /** Bending constraint compliance (lower = stiffer) */
+    export const BENDING_COMPLIANCE = 0.000041;
+    /** Velocity damping per substep (0.92 = 8% velocity loss per substep) */
+    export const DAMPING = 0.975;
+    /** Damping used during rapid .goto() page-flip cascades (higher = faster settling) */
+    export const GOTO_DAMPING = 0.995;
+    /** Gravitational acceleration in world-space units */
+    export const GRAVITY = 9.81;
+    /** Whether gravity is active */
+    export const GRAVITY_ENABLED = true;
+    /** Minimum vertex position delta to consider a page still "active" — below this it goes idle */
+    export const DELTA_IDLE_THRESHOLD = 0.000001;
+    /** Margin around the book as a fraction of the smaller viewport dimension (0.05 = 5%) */
+    export const VIEWPORT_MARGIN_PCT = 0.05;
+    /** Default camera polar angle in radians (0 = side view, π/2 = directly overhead) */
+    export const DEFAULT_CAMERA_PHI: number;
+    /** RGB tint for the front face of each page */
+    export const FRONT_COLOR: [number, number, number];
+    /** RGB tint for the back face of each page */
+    export const BACK_COLOR: [number, number, number];
+    /** Base URL for IIIF image server */
+    export const IIIF_BASE_URL = "https://iiif.micr.io";
+    /** Base debounce before starting a download for the currently viewed spread (ms) */
+    export const IIIF_DEBOUNCE_BASE_MS = 500;
+    /** Additional debounce per page distance from the spread center (ms) */
+    export const IIIF_DEBOUNCE_PER_DISTANCE_MS = 2000;
+    /** Duration of the cross-fade from low-res to hi-res texture (ms) */
+    export const IIIF_CROSSFADE_DURATION = 500;
+    /** Spreads away from the current spread before hi-res textures are pre-loaded */
+    export const IIIF_PRELOAD_DISTANCE = 1;
+    /** Spreads away from the current spread before hi-res textures are evicted from GPU */
+    export const IIIF_GPU_EVICT_DISTANCE = 5;
+    /** Default camera radius (used as baseline for zoom-aware IIIF resolution choice) */
+    export const DEFAULT_CAMERA_RADIUS = 2.2;
+    /** Master toggle for the tilt-shift blur effect */
+    export const TILT_SHIFT_ENABLED = true;
+    /** Normalised screen-space Y coordinate of the in-focus band centre (0 = bottom, 1 = top) */
+    export const TILT_SHIFT_FOCUS_CENTER = 0.55;
+    /** Vertical height of the sharp in-focus band as a fraction of the viewport */
+    export const TILT_SHIFT_FOCUS_WIDTH = 0.25;
+    /** Maximum blur radius in screen pixels (applied at the furthest distance from the focus band) */
+    export const TILT_SHIFT_BLUR_RADIUS = 4;
+    /** Sharpness of the transition between in-focus and blurred regions (higher = sharper) */
+    export const TILT_SHIFT_BLUR_FALLOFF = 1;
+    /** Active lighting preset name. Available: 'daylight', 'incandescent', 'candlelight', 'rainy day', 'moonlight', 'fireplace', 'haunted' */
+    export const LIGHTING_PRESET = "daylight";
+
+    export { GRID_COLS, GRID_ROWS, VERTEX_COUNT } from "book/core/settings";
+    export interface EdgeConstraint {
+        _i: number;
+        _j: number;
+        _restLength: number;
+    }
+    export interface BendingConstraint {
+        _i: number;
+        _j: number;
+        _restLength: number;
+    }
+    export interface TriangleData {
+        _indices: [number, number, number];
+    }
+    export function buildIndexBuffer(triangles: TriangleData[]): Uint32Array;
+    export function computeVertexNormals(positions: Float32Array, triangles: TriangleData[], vertexCount: number): Float32Array;
+    export function addEdgeConstraint(i: number, j: number, restPositions: Float32Array, added: Set<string>, constrs: EdgeConstraint[]): void;
+    export function addGridConstraints(baseIdx: number, add: (i: number, j: number) => void): void;
+
+    export { GRID_COLS, GRID_ROWS, VERTEX_COUNT } from "book/core/settings";
+    export type { EdgeConstraint, BendingConstraint, TriangleData };
+    export class PaperMesh {
+        _restPositions: Float32Array;
+        _positions: Float32Array;
+        _velocities: Float32Array;
+        _invMasses: Float32Array;
+        _texCoords: Float32Array;
+        _triangles: TriangleData[];
+        _indexBuffer: Uint32Array;
+        _distanceConstraints: EdgeConstraint[];
+        _bendingConstraints: BendingConstraint[];
+        _boundLeft: number[];
+        readonly _yOffset: number;
+        readonly _paperWidth: number;
+        readonly _paperHeight: number;
+        constructor(yOffset?: number, paperWidth?: number, aspectRatio?: number);
+        protected _generateGrid(paperHeight: number): void;
+        protected _generateTexCoords(): void;
+        protected _generateTriangles(): void;
+        protected _generateDistanceConstraints(): void;
+        protected _generateBendingConstraints(): void;
+        protected _identifyBoundEdges(): void;
+        _reset(): void;
+        _setBinding(): void;
+        _computeNormals(): Float32Array;
+    }
+
+    export class CoverMesh extends PaperMesh {
+        #private;
+        readonly _coverThickness: number;
+        readonly _coverScale: number;
+        readonly _coverScaleY: number;
+        constructor(yOffset?: number, paperWidth?: number, aspectRatio?: number, coverThickness?: number, coverScale?: number, coverScaleY?: number);
+        protected _generateGrid(): void;
+        protected _generateTexCoords(): void;
+        protected _generateTriangles(): void;
+        protected _generateDistanceConstraints(): void;
+        protected _generateBendingConstraints(): void;
+        protected _identifyBoundEdges(): void;
+        _computeNormals(): Float32Array;
+    }
+
+    export class OrbitCamera {
+        #private;
+        _theta: number;
+        _phi: number;
+        _radius: number;
+        _target: Vec3;
+        _rotateSpeed: number;
+        _zoomSpeed: number;
+        _minRadius: number;
+        _maxRadius: number;
+        _panBoundsMin: Vec3 | null;
+        _panBoundsMax: Vec3 | null;
+        _freeCamMode: boolean;
+        _canPanLeft: boolean;
+        _canPanRight: boolean;
+        _canPanUp: boolean;
+        _canPanDown: boolean;
+        _manualZoomActive: boolean;
+        _isZoomedIn(): boolean;
+        _fov: number;
+        _setCanvasSize(w: number, h: number): void;
+        _initContainRadius(bounds: {
+            minX: number;
+            maxX: number;
+            minZ: number;
+            maxZ: number;
+        }, margin: number): void;
+        _snap(): void;
+        _update(dt: number): void;
+        _isMoving(): boolean;
+        _getEye(): Vec3;
+        _getViewMatrix(): Mat4;
+        _setFreeCamMode(on: boolean): void;
+        _rotate(deltaTheta: number, deltaPhi: number, clampPhi?: boolean): void;
+        _getPickRay(screenX: number, screenY: number): {
+            origin: Vec3;
+            direction: Vec3;
+        };
+        _zoom(delta: number, hitPoint?: Vec3): void;
+        _pan(deltaX: number, deltaY: number): void;
+        _clampViewport(screenBounds: {
+            minX: number;
+            maxX: number;
+            minY: number;
+            maxY: number;
+        }, viewportW: number, viewportH: number, margin: number): void;
+    }
+
+    export interface LightingParam {
+        key: string;
+        default: number;
+    }
+    export interface LightingPreset {
+        name: string;
+        isAnimated: boolean;
+        params: LightingParam[];
+    }
+    export interface LightingState {
+        _lightDir: [number, number, number];
+        _lightColor: [number, number, number];
+        _ambientColor: [number, number, number];
+        _numPointLights: number;
+        _pointLightPos: Float32Array;
+        _pointLightColor: Float32Array;
+        _pointLightIntensity: Float32Array;
+        _bumpStrength: number;
+    }
+    export function getPresets(): LightingPreset[];
+    export function getPreset(name: string): LightingPreset | undefined;
+    export function computeLighting(presetName: string, params: Record<string, number>, time: number): LightingState;
+
+    export function computeWeightFactor(progress: Float32Array, pageCount: number): number;
+    export function computePageSpineY(pageIndex: number, progress: number, weightFactor: number, totalStackHeight: number, pageCount: number, pageThickness: number): number;
+    export function computeAllPageFloors(progress: Float32Array, weightFactor: number, totalStackHeight: number, pageCount: number, pageThickness: number): Float32Array;
+    export function applySpineDelta(positions: Float32Array, delta: number): void;
+
+    export function compileShader(gl: WebGL2RenderingContext, type: number, src: string): WebGLShader;
+    export function createGLProgram(gl: WebGL2RenderingContext, vertSrc: string, fragSrc: string): WebGLProgram;
+    export function setupTextureParams(gl: WebGL2RenderingContext, tex: WebGLTexture): void;
+    export function createWhiteTexture(gl: WebGL2RenderingContext): WebGLTexture;
+
+    export class PaperRenderer {
+        #private;
+        _tiltShiftEnabled: boolean;
+        constructor(gl: WebGL2RenderingContext);
+        _initialize(meshes: PaperMesh[]): void;
+        _setPageTextures(pageIndex: number, frontBitmap: TexImageSource, backBitmap: TexImageSource): void;
+        _setPageHiResTexture(pageIdx: number, side: 0 | 1, slot: 0 | 1, bitmap: ImageBitmap): void;
+        _setPageBlend(pageIdx: number, frontBlendA: number, frontBlendB: number, backBlendA: number, backBlendB: number): void;
+        _evictPageHiRes(pageIdx: number, side: 0 | 1, slot: 0 | 1): void;
+        _getCanvas(): HTMLCanvasElement;
+        _setLightingPreset(name: string, params: Record<string, number>): void;
+        _isLightingAnimated(): boolean;
+        _resize(): void;
+        _updateVertexBuffer(meshIndex: number, mesh: PaperMesh): void;
+        _updateNormalBuffer(meshIndex: number, mesh: PaperMesh): void;
+        _getBoundingBoxCorners(): Float32Array | null;
+        _getCanvasSize(): {
+            width: number;
+            height: number;
+        };
+        /**
+         * Projects the 8 bounding box corners to screen CSS pixel coordinates.
+         * Returns { minX, maxX, minY, maxY } or null if no corners are visible.
+         */
+        _getBoundingBoxScreenBounds(viewProj: Mat4): {
+            minX: number;
+            maxX: number;
+            minY: number;
+            maxY: number;
+        } | null;
+        _setFlipProgress(progress: Float32Array): void;
+        _setBoundingBox(min: {
+            x: number;
+            y: number;
+            z: number;
+        }, max: {
+            x: number;
+            y: number;
+            z: number;
+        }): void;
+        _render(camera: OrbitCamera): void;
+    }
+
+    export class InputHandler {
+        #private;
+        _onPrevPage: (() => void) | null;
+        _onNextPage: (() => void) | null;
+        _onPageClick: ((x: number, y: number) => {
+            direction: 'prev' | 'next';
+            grabRow: number;
+        } | null) | null;
+        _lastClickGrabRow: number | null;
+        _onWheelZoom: ((screenX: number, screenY: number) => Vec3 | null) | null;
+        /** Override for the zoomed-in check, e.g. wired to the viewer's own viewport-fit logic. */
+        _isZoomedInFn: (() => boolean) | null;
+        _onPageDragStart: ((startX: number, startY: number) => void) | null;
+        _onPageDragMove: ((currentX: number, currentY: number) => void) | null;
+        _onPageDragEnd: (() => void) | null;
+        _operation: 'none' | 'orbit' | 'pan';
+        constructor(canvas: HTMLCanvasElement, camera: OrbitCamera, onActivity: () => void);
+    }
+
+    export class PageFlipAnimator {
+        #private;
+        _hardCoverPages: Set<number>;
+        get _animating(): boolean;
+        _isPageAnimating(pageIndex: number): boolean;
+        /** -1 = flipping back (left→right), +1 = flipping forward (right→left), 0 = idle/dragging. */
+        _getPageDirection(pageIndex: number): number;
+        _getPageProgress(pageIndex: number): number;
+        _setPageProgress(pageIndex: number, value: number): void;
+        _instantFlip(mesh: PaperMesh, pageIndex: number): void;
+        _initSlots(pageCount: number): void;
+        _flipLeft(pageIndex?: number, grabRow?: number): void;
+        _flipRight(pageIndex?: number, grabRow?: number): void;
+        _beginDrag(pageIndex: number, grabRow: number): void;
+        _setDragProgress(pageIndex: number, progress: number): void;
+        _endDrag(pageIndex: number, direction: number): void;
+        _isPageDragging(pageIndex: number): boolean;
+        _reset(meshes: PaperMesh[]): void;
+        _update(dt: number, meshes: PaperMesh[], selectedPage: number, totalStackHeight: number, pageCount: number, pageThickness: number): void;
+    }
+
+    /** Structure-of-arrays constraint layout for cache-friendly iteration. */
+    export interface ConstraintSet {
+        count: number;
+        i: Int32Array;
+        j: Int32Array;
+        restLength: Float32Array;
+    }
+    export interface SubstepParams {
+        dt: number;
+        solverIterations: number;
+        distanceCompliance: number;
+        bendingCompliance: number;
+        damping: number;
+        gravity: number;
+        gravityEnabled: boolean;
+    }
+    /** Flatten a mesh's {_i, _j, _restLength} constraint list into SoA buffers. */
+    export function buildConstraintSet(constraints: EdgeConstraint[] | BendingConstraint[]): ConstraintSet;
+    /**
+     * Run one XPBD substep over all vertices and constraints.
+     * Mutates `positions` / `velocities` in place and writes the start-of-step
+     * position backup into `prevPositions`.
+     */
+    export function runSubstep(positions: Float32Array, velocities: Float32Array, prevPositions: Float32Array, invMasses: Float32Array, N: number, distanceConstraints: ConstraintSet, bendingConstraints: ConstraintSet, distanceLambda: Float64Array, bendingLambda: Float64Array, params: SubstepParams, pageFloor: number): void;
+
+    export interface SolverSettings {
+        _solverIterations: number;
+        _substeps: number;
+        _distanceCompliance: number;
+        _bendingCompliance: number;
+        _damping: number;
+        _gravity: number;
+        _gravityEnabled: boolean;
+    }
+    export function isWasmReady(): boolean;
+    export function initWasmSolver(meshes: PaperMesh[], pageCount: number): Promise<void>;
+    export function dispatchSolve(subDt: number, activeIndices: number[], substeps: number, solverSettings: SolverSettings, meshes: PaperMesh[], progress: Float32Array, totalStackHeight: number, pageCount: number, pageThickness: number): void;
+
+    export class IIIFTextureManager {
+        #private;
+        /** Set by the host so the manager can request a redraw when it has something new to show. */
+        _onRequestFrame: (() => void) | null;
+        constructor(renderer: PaperRenderer, baseUrl?: string);
+        _init(images: Models.ImageInfo.ImageInfo[], pageCount: number, pageIdxes: number[][]): void;
+        _onFrame(now: number, spreadCenter: number, cameraRadius: number): boolean;
+        _hasPendingWork(): boolean;
+    }
+
+    export interface PageClickResult {
+        direction: 'prev' | 'next';
+        grabRow: number;
+    }
+    export interface PageDragResult {
+        pageIndex: number;
+        grabRow: number;
+        worldX: number;
+    }
+
+    export interface RayHit {
+        _t: number;
+        _point: Vec3;
+        _meshIndex: number;
+    }
+    export function rayIntersectMeshes(meshes: readonly PaperMesh[], origin: Vec3, direction: Vec3): RayHit | null;
+
+    export interface UvWorldResult {
+        /** Interpolated world-space position on the deformed mesh. */
+        _point: Vec3;
+        /** Interpolated (normalized) world-space surface normal at that point. */
+        _normal: Vec3;
+        /** World-space direction of increasing image u (not normalized). */
+        _tangentU: Vec3;
+        /** World-space direction of increasing image v (not normalized). */
+        _tangentV: Vec3;
+    }
+    /**
+     * Returns the world-space position, surface normal and UV tangents of a
+     * relative texture coordinate (u, v) on a page mesh, using the mesh's *current*
+     * (possibly animated/displaced) positions.
+     *
+     * `side` is the page side the image is displayed on:
+     *   0 = front face (sampled at uv directly),
+     *   1 = back face (sampled with the U axis mirrored on a single-grid PaperMesh,
+     *       or on the separate back-face grid of a CoverMesh).
+     *
+     * Returns null when (u, v) falls outside [0, 1].
+     */
+    export function uvToWorldPosition(mesh: PaperMesh, u: number, v: number, side: 0 | 1): UvWorldResult | null;
+    /**
+     * Like `uvToWorldPosition` but returns only the interpolated world-space
+     * position, skipping the surface normal and tangent computation.
+     */
+    export function sampleMeshPosition(mesh: PaperMesh, u: number, v: number, side: 0 | 1): Vec3 | null;
+    /**
+     * Projects a world-space point through the given view-projection matrix to CSS
+     * pixel coordinates relative to the canvas top-left. Returns null when the point
+     * is behind the camera.
+     */
+    export function projectWorldToScreen(point: Vec3, viewProj: Mat4, clientWidth: number, clientHeight: number): {
+        x: number;
+        y: number;
+    } | null;
+
+    export interface DrawnImage {
+        /** The micrio image id. */
+        id: string;
+        /**
+         * A rough axis-aligned rectangle `[u, v, w, h]` in the image's texture UV
+         * space (0..1) covering the part currently visible in the viewport. The
+         * full texture visible is `[0, 0, 1, 1]`.
+         */
+        bounds: [number, number, number, number];
+    }
+    export interface BookViewerOptions {
+        /** The WebGL2 canvas to render into. Must be present in the document and sized by its host. */
+        _canvas: HTMLCanvasElement;
+        /** The already-loaded book index JSON. */
+        _images: Models.ImageInfo.ImageInfo[];
+        /** Called whenever the current reading position changes. */
+        _onPageChange?: (pageIdx: number) => void;
+        /** Called whenever the camera moves (rotate/zoom/pan, including smoothing). */
+        _onViewChange?: (images: DrawnImage[]) => void;
+        /** Called after every frame that is drawn to the canvas, with the micrioIds of the images visible in the current spread (plus any page mid-flip), each with a rough `[u, v, w, h]` rectangle (in texture UV space 0..1) of the part visible in the viewport. */
+        _onDraw?: (images: DrawnImage[]) => void;
+        _hardCover?: boolean;
+        _tiltShift?: boolean;
+        _lightingPreset?: string;
+        _useIndividualAspects?: boolean;
+        _startPageIdx?: number;
+        /** Base URL for the IIIF image server (hi-res streaming). */
+        _iiifBaseUrl?: string;
+    }
+    export class BookViewer {
+        #private;
+        static _getPresets: typeof getPresets;
+        readonly _ready: Promise<void>;
+        constructor(options: BookViewerOptions);
+        goto(pageIdx: number): void;
+        zoom(delta: number): void;
+        /**
+         * Returns whether the camera is zoomed in beyond the fit view. This is the
+         * complement of "the whole spread fits the viewport": when every currently
+         * visible image shows its full texture (`[0, 0, 1, 1]` bounds) the view is
+         * zoomed out, and any image cut off by the viewport means it is zoomed in.
+         * Based on the last rendered frame's on-screen bounds, so it stays accurate
+         * after zooming back out.
+         */
+        isZoomedIn(): boolean;
+        setLightingPreset(name: string): void;
+        _getCurrentPage(): number;
+        _getPageCount(): number;
+        _nextPage(grabRow?: number): void;
+        _prevPage(grabRow?: number): void;
+        _hookImageBook3d(img: MicrioImage): void;
+    }
+
     /**
      * Manages the HTML `<canvas>` element used for WebGL rendering,
      * handles resizing, and provides viewport information.