@lovelace_lol/embody 0.0.7 → 0.0.8

package/dist/three/annotations/DPthreeCameraController.d.ts

@@ -0,0 +1,414 @@
+import * as THREE from 'three';
+import { OrbitControls } from 'three/examples/jsm/controls/OrbitControls.js';
+import type { DPthreeCameraControllerConfig, CharacterConfig, CameraState, RegionChangeCallback, MarkerStyle, AnnotationAnchoredRegion, RuntimeAnnotationOptions, RuntimeAnnotationRegionSummary } from './types';
+export declare function resolveFocusCameraDirection(model: THREE.Object3D | null, effectiveAngle: number, cameraAngle: number | undefined, angleSpace?: 'model' | 'world'): THREE.Vector3;
+export declare function resolveAutoCloseupAngle(horizontalOffset: number, focusSize: THREE.Vector3, modelSize: THREE.Vector3): number | undefined;
+export type MarkerStateSnapshot = {
+    style: MarkerStyle;
+    visible: boolean;
+};
+/**
+ * DPthreeCameraController - A unified camera controller for character viewers
+ *
+ * Features:
+ * - OrbitControls wrapper for smooth camera interaction
+ * - Focus on specific bones, meshes, or named regions
+ * - Smart bounding box calculation with size-based padding
+ * - Smooth animated transitions between views
+ * - Self-contained DOM controls for region selection
+ *
+ * Designed for future NPM packaging - no React dependencies.
+ */
+export declare class DPthreeCameraController {
+    readonly camera: THREE.PerspectiveCamera;
+    readonly controls: OrbitControls;
+    readonly scene: THREE.Scene;
+    private readonly resolveCharacterConfig;
+    private readonly selectRegion;
+    private config;
+    private controlsContainer;
+    private model;
+    private regions;
+    private currentRegion;
+    private characterConfig;
+    private runtimeAnnotationRegionNames;
+    private timerAnimationFallbackToken;
+    private cameraRequestGeneration;
+    private regionLoadGeneration;
+    private disposed;
+    private pendingAnimation;
+    private domControls;
+    private markers;
+    private currentMarkerStyle;
+    private markersLoaded;
+    private markersVisible;
+    private markerStateListeners;
+    private domElement;
+    private renderer;
+    private renderFrame;
+    private resizeRenderer;
+    private onRenderError;
+    private renderingSuspended;
+    private unbindRendering;
+    private renderingFailure;
+    private framePending;
+    private frameCompletion;
+    private modelPreparation;
+    private renderFailed;
+    private resizeObserver;
+    private boundResizeHandler;
+    private laterality;
+    private onRegionChangeCallbacks;
+    constructor(inputConfig: DPthreeCameraControllerConfig);
+    /**
+     * Start the render loop (only when renderer is provided)
+     */
+    private startRenderLoop;
+    private handleRenderError;
+    /**
+     * Stop the render loop
+     */
+    private stopRenderLoop;
+    private shouldDriveTimerAnimationFallback;
+    private getTimerAnimationFallbackDelay;
+    private scheduleTimerAnimationFallback;
+    /**
+     * Set up resize handling for the renderer
+     * Uses ResizeObserver for container size changes
+     */
+    private setupResizeHandling;
+    /**
+     * Clean up resize handling
+     */
+    private cleanupResizeHandling;
+    /**
+     * Prepare the currently visible material variants before first reveal.
+     * Borrows model/renderer; callers retain them until this promise settles,
+     * including after cancellation or controller disposal.
+     */
+    prepareModelForRender(model: THREE.Object3D, options?: {
+        signal?: AbortSignal;
+    }): Promise<void>;
+    private cancelModelPreparation;
+    /**
+     * Set the model to use for bone/mesh lookups
+     * Must be called after model loads
+     */
+    setModel(model: THREE.Object3D): void;
+    /** Release model references before the host disposes it, under a rendering lease. */
+    clearModel(): void;
+    /**
+     * Load region config for a character
+     */
+    loadRegions(config: CharacterConfig): Promise<void>;
+    /**
+     * Prime an already-resolved runtime config before the character becomes visible.
+     * Marker construction is intentionally separate so startup can defer the expensive
+     * per-region marker geometry/DOM work until after the first visible frame.
+     */
+    prepareRegionsForReveal(config: CharacterConfig): void;
+    /**
+     * Prepare marker geometry while the character loading overlay is still up,
+     * then start the intro camera transition after that work has completed.
+     */
+    prepareRegionsAndMarkersForReveal(config: CharacterConfig, beforeReveal?: () => Promise<boolean>): Promise<void>;
+    private prepareRegionState;
+    private startPreparedCameraTransition;
+    /**
+     * Build marker objects for the current character config.
+     * This is separated from prepareRegionsForReveal so callers can defer the
+     * expensive marker construction until after the first visible frame.
+     */
+    loadMarkersForCurrentRegions(sliceSurfaceQueries?: boolean): Promise<void>;
+    /**
+     * Focus on a named region from the loaded config
+     */
+    focusRegion(name: string, duration?: number): Promise<void>;
+    private resolveRegionFocusPosition;
+    private resolveLegacyRegionFocusPosition;
+    private resolveFocusTargetObjects;
+    /**
+     * Focus on specific bones by name
+     */
+    focusBones(boneNames: string[], duration?: number): Promise<void>;
+    /**
+     * Focus on specific meshes by name
+     */
+    focusMeshes(meshNames: string[], duration?: number): Promise<void>;
+    /**
+     * Focus on the full body (entire model bounding box)
+     */
+    focusFullBody(duration?: number): Promise<void>;
+    /**
+     * Focus on arbitrary objects
+     */
+    focusObjects(objects: THREE.Object3D[], duration?: number): Promise<void>;
+    /**
+     * Play intro animation: orbit around the character, then settle into a tight
+     * left-eye hero closeup when the character provides a left-eye region.
+     * @param orbitDuration - Duration of the 360° orbit in ms (default: 3000)
+     * @param zoomDuration - Duration of the final zoom in ms (default: 1500)
+     */
+    playIntroAnimation(orbitDuration?: number, zoomDuration?: number): Promise<void>;
+    /**
+     * Animate a smooth 360° orbit around a center point
+     * Animation is driven by the update() method which is called from the render loop.
+     */
+    private animateOrbit;
+    /**
+     * Get list of available region names
+     */
+    getRegionNames(): string[];
+    /**
+     * Get current region name
+     */
+    getCurrentRegion(): string | null;
+    /**
+     * Get loaded character config
+     */
+    getCharacterConfig(): CharacterConfig | null;
+    /**
+     * Get current camera state
+     */
+    getCameraState(): CameraState;
+    /**
+     * Set camera state directly (no animation)
+     */
+    setCameraState(state: CameraState): void;
+    /**
+     * Animate to camera state
+     */
+    animateToCameraState(state: CameraState, duration?: number): Promise<void>;
+    /**
+     * Show/hide region markers
+     */
+    setMarkersVisible(visible: boolean): void;
+    /**
+     * Get current markers visibility state
+     */
+    getMarkersVisible(): boolean;
+    /**
+     * Clear all markers and reset region state
+     */
+    clearMarkers(): void;
+    /**
+     * Get current marker style
+     */
+    getMarkerStyle(): MarkerStyle;
+    /**
+     * Set marker style (html or 3d) - recreates markers with new style
+     */
+    setMarkerStyle(style: MarkerStyle): void;
+    private setMarkerStyleState;
+    private ensureMarkersForCurrentStyle;
+    subscribeMarkerState(listener: (state: MarkerStateSnapshot) => void): () => void;
+    private getMarkerState;
+    private emitMarkerState;
+    /**
+     * Solo a marker - show only this marker, hide all others
+     * @param regionName - Region to solo (null to unsolo all)
+     */
+    soloMarker(regionName: string | null): void;
+    /**
+     * Get currently soloed marker name (or null)
+     */
+    getSoloedMarker(): string | null;
+    /**
+     * Expand a region to show its children
+     * @param regionName - Name of the parent region to expand
+     * @param duration - Animation duration in ms (default: 400)
+     */
+    expandRegion(regionName: string, duration?: number): void;
+    /**
+     * Collapse a region to hide its children
+     * @param regionName - Name of the parent region to collapse
+     * @param duration - Animation duration in ms (default: 300)
+     */
+    collapseRegion(regionName: string, duration?: number): void;
+    /**
+     * Toggle expand/collapse state of a region
+     * @param regionName - Name of the parent region to toggle
+     * @param animation - Animation style: 'outward' or 'staggered'
+     * @param duration - Animation duration in ms
+     */
+    toggleRegion(regionName: string, animation?: 'outward' | 'staggered', duration?: number): void;
+    /**
+     * Get current expanded state of all regions
+     */
+    getExpandedRegions(): {
+        regionName: string;
+        isExpanded: boolean;
+        children: string[];
+    }[];
+    /**
+     * Update line style for a specific region at runtime
+     */
+    setRegionLineStyle(regionName: string, lineConfig: {
+        style?: 'solid' | 'dashed' | 'dotted';
+        curve?: 'straight' | 'bezier' | 'arc';
+        arrowHead?: boolean;
+        thickness?: number;
+        length?: number;
+    }): void;
+    /**
+     * Update marker style for a specific region at runtime
+     */
+    setRegionStyle(regionName: string, style: {
+        markerColor?: number;
+        markerRadius?: number;
+        lineColor?: number;
+        labelColor?: string;
+        labelBackground?: string;
+        labelFontSize?: number;
+        opacity?: number;
+    }): void;
+    /**
+     * Update the face mesh configuration for a region and recalculate its position.
+     * This is called when the user selects a different face mesh in the wizard.
+     *
+     * @param regionName - Name of the region to update (e.g., 'face')
+     * @param meshNames - Array of mesh names to use for positioning
+     */
+    updateRegionMeshes(regionName: string, meshNames: string[]): void;
+    /**
+     * Reposition an existing marker to a new position.
+     *
+     * @param regionName - Name of the region to reposition
+     * @param position - New world position { x, y, z }
+     */
+    repositionMarker(regionName: string, position: {
+        x: number;
+        y: number;
+        z: number;
+    }): void;
+    /**
+     * Get the current position of a marker
+     */
+    getMarkerPosition(regionName: string): {
+        x: number;
+        y: number;
+        z: number;
+    } | null;
+    /**
+     * Get the current model reference
+     */
+    getModel(): THREE.Object3D | null;
+    /**
+     * Remove an annotation region from the active runtime config and marker set.
+     *
+     * Persistence still happens through the canonical profile annotation overrides
+     * saved by the authoring UI; this only keeps the live scene in sync.
+     */
+    removeAnnotationRegion(regionName: string): void;
+    /**
+     * Update an annotation region's configuration without reloading the character.
+     * This updates the region's bones, meshes, or other properties and recalculates
+     * the marker position automatically.
+     *
+     * @param regionName - Name of the region to update (e.g., 'face', 'left_eye')
+     * @param update - Partial region config to merge with existing config
+     */
+    updateAnnotationRegion(regionName: string, update: Partial<AnnotationAnchoredRegion>): void;
+    /**
+     * Get the current configuration for a specific region
+     */
+    getAnnotationRegion(regionName: string): AnnotationAnchoredRegion | undefined;
+    /**
+     * Get all annotation regions
+     */
+    getAnnotationRegions(): AnnotationAnchoredRegion[];
+    private buildRuntimeAnnotationRegionName;
+    private buildRuntimeBoneAnnotationRegion;
+    private buildRuntimeMeshAnnotationRegionName;
+    private buildRuntimeMeshAnnotationRegion;
+    private upsertRuntimeBoneAnnotationRegion;
+    private upsertRuntimeMeshAnnotationRegion;
+    private clearRuntimeAnnotationsForTarget;
+    private clearRuntimeAnnotationsExcept;
+    /**
+     * Show a temporary annotation marker for a bone. Runtime annotations are
+     * ordinary regions with explicit bone marker/focus anchors, tracked separately
+     * so they can be cleared without modifying saved character annotations.
+     */
+    showRuntimeBoneAnnotation(boneName: string, options?: RuntimeAnnotationOptions): RuntimeAnnotationRegionSummary;
+    /**
+     * Show temporary annotation markers for every bone binding used by an AU.
+     * The optional profile override lets remote-control callers use the active
+     * Embody engine profile, while normal controller consumers can rely on the
+     * loaded character config.
+     */
+    showRuntimeAUAnnotations(auId: string | number, profileOverride?: unknown, options?: RuntimeAnnotationOptions, morphTargetsByMesh?: unknown): RuntimeAnnotationRegionSummary[];
+    /**
+     * Remove all temporary runtime annotations created through the AU/bone API.
+     */
+    clearRuntimeAnnotations(): string[];
+    /**
+     * Show/hide built-in DOM controls
+     */
+    setDOMControlsVisible(visible: boolean): void;
+    /**
+     * Update DOM controls to reflect current regions
+     */
+    updateDOMControls(): void;
+    /**
+     * Register callback for region changes
+     */
+    onRegionChange(callback: RegionChangeCallback): () => void;
+    /**
+     * Update loop - call in animation frame (from render loop)
+     * This drives camera animations and marker updates
+     */
+    update(): void;
+    /**
+     * Cleanup and dispose
+     */
+    dispose(): void;
+    private initDOMControls;
+    private notifyRegionChange;
+    /**
+     * Resolve region definition to actual Object3D instances
+     */
+    private resolveRegionObjects;
+    /**
+     * Find objects by name with optional type filter.
+     * Uses fuzzy matching to handle bone names with numeric suffixes
+     * (e.g., "CC_Base_Head_038" matches "CC_Base_Head").
+     */
+    private findObjectsByNames;
+    /**
+     * Get bounding box of vertices influenced by a bone from skinned meshes
+     * This finds the actual geometry size around a bone for proper framing
+     *
+     * For skinned meshes, we need to compute the actual skinned vertex positions,
+     * not just the bind pose positions.
+     */
+    private getBoneInfluencedBoundingBox;
+    /**
+     * Calculate optimal camera position to frame objects
+     * @param objects - Objects to focus on
+     * @param overridePadding - Optional padding factor override
+     * @param cameraAngle - Camera angle in degrees around Y axis (0 = front, 180 = back)
+     */
+    private calculateFocusPosition;
+    private calculatePointFocusPosition;
+    private resolvePointFocusSize;
+    private getFallbackFocusPosition;
+    private isFullBodyRegion;
+    private isLeftEyeRegion;
+    private findIntroLeftEyeRegion;
+    private resolveIntroLeftEyePadding;
+    private calculateIntroLeftEyeFocusPosition;
+    private applyIntroLeftEyeCompositionBias;
+    private calculateFullBodyFocusPosition;
+    private refreshLaterality;
+    /** Resolver and paint continuations belong to one model/configuration load. */
+    private isRegionLoadCurrent;
+    /** Await Wasm once per request and abandon requests superseded during initialization. */
+    private beginCameraRequest;
+    private isCameraRequestCurrent;
+    private cancelCameraAnimation;
+    private applyCameraPose;
+    private runCameraAnimation;
+    /** Sample the shared Rust flight from update(), alongside the renderer. */
+    private animateCamera;
+}

package/dist/three/annotations/DPthreeHTMLMarkers.d.ts

@@ -0,0 +1,131 @@
+import type { Region, CharacterConfig, ExpandAnimation, ExpandedRegionState } from './types';
+import * as THREE from 'three';
+/**
+ * HTML overlay markers with GPU-based occlusion via 3D proxy points.
+ *
+ * Architecture:
+ * 1. Each HTML marker has a corresponding invisible 3D mesh in the scene
+ * 2. The 3D mesh uses onBeforeRender callback to notify visibility
+ * 3. When the mesh renders (passes depth test), it updates the HTML marker position
+ * 4. When occluded, the callback doesn't fire, so we track "was rendered this frame"
+ *
+ * Performance: No per-frame visibility calculations - GPU depth testing determines
+ * visibility, and we only update HTML when the 3D proxy actually renders.
+ */
+export declare class DPthreeHTMLMarkers {
+    private scene;
+    private camera;
+    private domElement;
+    private model;
+    private regions;
+    private currentRegion;
+    private onSelect;
+    private characterConfig;
+    private labelsContainer;
+    private markers;
+    private occlusionGroup;
+    private occlusionMeshes;
+    private renderedThisFrame;
+    private frameId;
+    private markerFrameIds;
+    private visibilityAnimationActive;
+    private readonly visibilityAnimationScheduler;
+    private visibilityAnimationToken;
+    private modelCenter;
+    private modelSize;
+    private autoCollapseThreshold;
+    private lastCameraDistance;
+    private viewportSize;
+    private resizeObserver;
+    private expandedRegions;
+    private parentChildIndex;
+    private childParentIndex;
+    private hiddenChildren;
+    private faceCenterCache;
+    private laterality;
+    constructor(config: {
+        scene: THREE.Scene;
+        camera: THREE.PerspectiveCamera;
+        domElement: HTMLElement;
+        onSelect: (name: string) => void;
+    });
+    /** Keep labels/selection while rebinding viewport observation to a new canvas. */
+    setDomElement(element: HTMLElement): void;
+    setModel(model: THREE.Object3D): void;
+    loadRegions(config: CharacterConfig): void;
+    setCurrentRegion(name: string | null): void;
+    /**
+     * Update a region's configuration and recreate its marker.
+     * This is the general method for updating any region properties.
+     *
+     * @param regionName - Name of the region to update
+     * @param update - Partial region config to merge with existing config
+     */
+    updateRegion(regionName: string, update: Partial<Region>): void;
+    removeRegion(regionName: string): void;
+    /**
+     * Remove all marker components for a region
+     */
+    private removeMarkerComponents;
+    updateRegionMeshes(regionName: string, meshNames: string[]): void;
+    /**
+     * Reposition an existing marker to a new position.
+     */
+    repositionMarker(regionName: string, newPosition: THREE.Vector3): void;
+    /**
+     * Get the current position of a marker.
+     */
+    getMarkerPosition(regionName: string): THREE.Vector3 | null;
+    private updateViewportSize;
+    private getViewportSize;
+    private setMarkerDisplay;
+    private setMarkerScale;
+    private setMarkerScreenPosition;
+    private createMarker;
+    /**
+     * Called when a 3D proxy mesh is about to render.
+     * This means it passed frustum culling and depth test - it's visible!
+     */
+    private onProxyRendered;
+    private getSuffixPattern;
+    /**
+     * Get center point of a region's bones/meshes.
+     * Uses fuzzy matching to handle bone names with numeric suffixes.
+     * For face regions, uses resolveFaceCenter with auto-detection by morph count.
+     */
+    private getRegionCenter;
+    private updateMarkerStyles;
+    /**
+     * Call at start of each frame to reset state and update positions.
+     * The onBeforeRender callbacks handle showing visible markers.
+     * This method hides markers that didn't render.
+     */
+    update(): void;
+    setVisible(visible: boolean): void;
+    private stopVisibilityAnimation;
+    private animateVisibility;
+    clear(): void;
+    /**
+     * Expand a parent region to show its children.
+     */
+    expandRegion(regionName: string, animation?: ExpandAnimation, duration?: number): void;
+    /**
+     * Collapse a parent region to hide its children.
+     */
+    collapseRegion(regionName: string, duration?: number): void;
+    /**
+     * Toggle expand/collapse state.
+     */
+    toggleRegion(regionName: string, animation?: ExpandAnimation, duration?: number): void;
+    /**
+     * Get expanded state of all regions.
+     */
+    getExpandedRegions(): ExpandedRegionState[];
+    /**
+     * Collapse all currently expanded regions.
+     * Called automatically when zooming out past threshold.
+     */
+    private collapseAllRegions;
+    dispose(): void;
+    private refreshLaterality;
+}

package/dist/three/annotations/DPthreeMarkers.d.ts

@@ -0,0 +1,52 @@
+import * as THREE from 'three';
+import type { CharacterConfig } from './types';
+/**
+ * 3D visual markers for regions that can be clicked
+ */
+export declare class DPthreeMarkers {
+    private scene;
+    private camera;
+    private domElement;
+    private markers;
+    private labels;
+    private labelsContainer;
+    private raycaster;
+    private onSelect;
+    private model;
+    private regions;
+    private characterConfig;
+    private currentRegion;
+    constructor(config: {
+        scene: THREE.Scene;
+        camera: THREE.PerspectiveCamera;
+        domElement: HTMLElement;
+        onSelect: (name: string) => void;
+    });
+    setModel(model: THREE.Object3D): void;
+    loadRegions(config: CharacterConfig): void;
+    setCurrentRegion(name: string | null): void;
+    private createMarker;
+    private getRegionCenter;
+    private formatName;
+    private updateMarkerStyles;
+    private onClick;
+    /**
+     * Update label positions - call this in render loop
+     *
+     * Occlusion: Uses efficient dot product check - if marker is on opposite side
+     * of model from camera (dot product < 0), hide it. O(1) per marker.
+     */
+    update(): void;
+    /**
+     * Show/hide all markers
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Clear all markers
+     */
+    clear(): void;
+    /**
+     * Dispose and cleanup
+     */
+    dispose(): void;
+}