@lovelace_lol/embody 0.0.7 → 0.0.8

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

@@ -0,0 +1,73 @@
+/**
+ * Self-contained DOM controls for DPthreeCameraController
+ * No React dependencies - vanilla DOM manipulation
+ */
+export interface DOMControlRegion {
+    name: string;
+    parent?: string;
+    children?: string[];
+}
+export interface DOMControlsConfig {
+    /** Container element to append controls to */
+    container: HTMLElement;
+    /** Callback when user selects a region */
+    onRegionSelect: (name: string) => void;
+    /** Initial list of regions */
+    regions: DOMControlRegion[];
+    /** Currently selected region */
+    currentRegion?: string;
+    /** Initial annotation-marker visibility */
+    markersVisible?: boolean;
+    /** Callback when the Markers checkbox is toggled */
+    onMarkersVisibleChange?: (visible: boolean) => void;
+}
+/** Temporary AU preview regions must never appear in the View dropdown. */
+export declare const RUNTIME_ANNOTATION_REGION_PREFIX = "runtime:annotation:";
+export declare function isRuntimeAnnotationRegionName(name: string): boolean;
+export declare function filterCameraViewRegions<T extends {
+    name: string;
+}>(regions: T[]): T[];
+export declare function buildRegionDisplayOptions(regions: DOMControlRegion[]): Array<{
+    name: string;
+    label: string;
+}>;
+/**
+ * CameraDOMControls - Self-contained DOM UI for region selection
+ */
+export declare class CameraDOMControls {
+    private container;
+    private wrapper;
+    private select;
+    private markersCheckbox;
+    private onRegionSelect;
+    private onMarkersVisibleChange?;
+    constructor(config: DOMControlsConfig);
+    /**
+     * Populate select options
+     */
+    private populateSelect;
+    /**
+     * Update available regions
+     */
+    updateRegions(regions: DOMControlRegion[], current?: string): void;
+    /**
+     * Sync Markers checkbox with controller visibility state.
+     */
+    setMarkersVisible(visible: boolean): void;
+    /**
+     * Set current region (updates select value)
+     */
+    setCurrentRegion(name: string): void;
+    /**
+     * Show/hide controls
+     */
+    setVisible(visible: boolean): void;
+    /**
+     * Check if controls are visible
+     */
+    isVisible(): boolean;
+    /**
+     * Cleanup and remove from DOM
+     */
+    dispose(): void;
+}

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

@@ -0,0 +1,113 @@
+import * as THREE from 'three';
+import { DPthreeCameraController } from './DPthreeCameraController';
+import type { CharacterConfig, DPthreeCameraControllerConfig, MarkerStyle, LineConfig, MarkerStyleOverrides, ExpandAnimation, ExpandedRegionState } from './types';
+/**
+ * DPthree Configuration
+ */
+export interface DPthreeConfig {
+    /** Three.js scene */
+    scene: THREE.Scene;
+    /** Three.js camera */
+    camera: THREE.PerspectiveCamera;
+    /** Canvas or container element */
+    domElement: HTMLElement;
+    /** Marker style: '3d' (default) or 'html' */
+    markerStyle?: MarkerStyle;
+    /** Show DOM controls dropdown. Default: false */
+    showControls?: boolean;
+    /** Callback when a region is selected */
+    onRegionSelect?: (name: string) => void;
+    /** Camera controller options */
+    cameraOptions?: Partial<DPthreeCameraControllerConfig>;
+}
+/**
+ * DPthree - Camera & Marker System for Three.js
+ *
+ * Factory class that creates and manages camera controller and markers.
+ *
+ * @example
+ * ```typescript
+ * const dp = new DPthree({
+ *   scene,
+ *   camera,
+ *   domElement: canvas,
+ *   markerStyle: '3d',
+ * });
+ *
+ * dp.setModel(model);
+ * await dp.loadCharacter(config);
+ * dp.focus('head');
+ *
+ * // In render loop
+ * dp.update();
+ * ```
+ */
+export declare class DPthree {
+    private readonly cameraController;
+    private markerStyle;
+    private model;
+    constructor(options: DPthreeConfig);
+    setModel(model: THREE.Object3D): this;
+    loadCharacter(config: CharacterConfig): Promise<this>;
+    focus(regionName: string, duration?: number): Promise<void>;
+    getRegions(): string[];
+    getCurrentRegion(): string | null;
+    setMarkerStyle(style: MarkerStyle): this;
+    setMarkersVisible(visible: boolean): this;
+    setControlsVisible(visible: boolean): this;
+    getCameraState(): import("./types").CameraState;
+    setCameraState(position: [number, number, number], target: [number, number, number], _animate?: boolean): this;
+    get controller(): DPthreeCameraController;
+    update(): void;
+    expandRegion(name: string, duration?: number): this;
+    collapseRegion(name: string, duration?: number): this;
+    toggleRegion(name: string, animation?: ExpandAnimation, duration?: number): this;
+    getExpandedRegions(): ExpandedRegionState[];
+    soloMarker(name: string | null): this;
+    getSoloedMarker(): string | null;
+    setRegionLineStyle(name: string, line: Partial<LineConfig>): this;
+    setRegionStyle(name: string, style: Partial<MarkerStyleOverrides>): this;
+    dispose(): void;
+    /**
+     * Validate a loaded character model against expected bone/morph mappings
+     * @param expectedBones - Map of semantic bone names to actual bone names
+     * @param expectedMorphs - List of expected morph target names
+     * @returns Validation result with found/missing bones and morphs
+     */
+    validateCharacter(expectedBones?: Record<string, string>, expectedMorphs?: string[]): CharacterValidationResult;
+    /**
+     * Get all bone names in the loaded model
+     */
+    getBoneNames(): string[];
+    /**
+     * Get all morph target names in the loaded model
+     */
+    getMorphNames(): string[];
+    /**
+     * Get all mesh names in the loaded model
+     */
+    getMeshNames(): string[];
+}
+export interface ValidationItem {
+    name: string;
+    semantic?: string;
+}
+export interface ValidationCategory {
+    found: ValidationItem[];
+    missing: ValidationItem[];
+    unexpected: ValidationItem[];
+}
+export interface CharacterValidationResult {
+    valid: boolean;
+    bones: ValidationCategory;
+    morphs: ValidationCategory;
+    meshes: {
+        found: string[];
+        total: number;
+    };
+    summary: string;
+}
+export { DPthreeCameraController as CameraController } from './DPthreeCameraController';
+export { DPthree3DMarkers as Markers3D } from './DPthree3DMarkers';
+export { DPthreeHTMLMarkers as MarkersHTML } from './DPthreeHTMLMarkers';
+export { CameraDOMControls as Controls } from './DOMControls';

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

@@ -0,0 +1,319 @@
+import * as THREE from 'three';
+import type { Region, CharacterConfig, MarkerStyleOverrides, LineConfig, ExpandAnimation, ExpandedRegionState } from './types';
+interface MarkerConfig {
+    markerRadius?: number;
+    markerColor?: number;
+    lineColor?: number;
+    lineLength?: number;
+    labelColor?: string;
+    labelBackground?: string;
+    labelFontSize?: number;
+    labelScale?: number;
+}
+export declare function shouldShow3DMarker(params: {
+    name: string;
+    hiddenChildren: Set<string>;
+    soloedMarker: string | null;
+    markerAngle?: number;
+    currentCameraAngle?: number;
+}): boolean;
+export declare function resolveViewportConstrainedLineScale(params: {
+    startClip: THREE.Vector4;
+    endClip: THREE.Vector4;
+    safeX: number;
+    safeY: number;
+    minLengthRatio?: number;
+}): {
+    visible: boolean;
+    lineScale: number;
+};
+export declare function resolveViewportSafeBounds(params: {
+    labelScaleX: number;
+    labelScaleY: number;
+    projectionXScale: number;
+    projectionYScale: number;
+    viewportWidth: number;
+    viewportHeight: number;
+    edgePaddingPx?: number;
+}): {
+    safeX: number;
+    safeY: number;
+};
+/**
+ * Pure 3D visual markers for annotations.
+ *
+ * SIMPLE RULE: Lines always point AWAY from model center.
+ * - Horizontal: left annotations go left, right go right
+ * - Vertical: high annotations go up, low go down
+ */
+export declare class DPthree3DMarkers {
+    private scene;
+    private camera;
+    private domElement;
+    private model;
+    private regions;
+    private currentRegion;
+    private onSelect;
+    private config;
+    private markerGroup;
+    private markerMeshes;
+    private lineMeshes;
+    private lineEndpoints;
+    private labelSprites;
+    private labelScales;
+    private originalLineLengths;
+    private boneRefs;
+    private localOffsets;
+    private modelCenter;
+    private modelSize;
+    private modelMeshes;
+    private regionLoadHasFreshMatrices;
+    private isZoomedIn;
+    private zoomThreshold;
+    private autoCollapseThreshold;
+    private lastCameraDistance;
+    private visibilityAnimationActive;
+    private readonly visibilityAnimationScheduler;
+    private visibilityAnimationStates;
+    private activeMarkerVisibilityAnimations;
+    private markerVisibilityAnimationStates;
+    private markerTargetVisibility;
+    private markerAngleGateVisibility;
+    private markerViewportVisibility;
+    private hasCameraAngleUpdateSnapshot;
+    private lastCameraAngleUpdatePosition;
+    private lastCameraAngleUpdateQuaternion;
+    private raycaster;
+    private mouse;
+    private scratchClipStart;
+    private scratchClipEnd;
+    private readonly scratchClipStartValues;
+    private readonly scratchClipEndValues;
+    private scratchWorldEnd;
+    private scratchConstrainedEnd;
+    private tempSurfacePoint;
+    private scratchArrowDirection;
+    private scratchArrowQuaternion;
+    private arrowUp;
+    private charLineDefaults;
+    private charMarkerDefaults;
+    private resolvedStyles;
+    private expandedRegions;
+    private parentChildIndex;
+    private childParentIndex;
+    private hiddenChildren;
+    private soloedMarker;
+    private markerGroups;
+    private groupVisibility;
+    private arrowMeshes;
+    private characterConfig;
+    private laterality;
+    private regionLoadGeneration;
+    constructor(inputConfig: {
+        scene: THREE.Scene;
+        camera: THREE.PerspectiveCamera;
+        domElement: HTMLElement;
+        onSelect: (name: string) => void;
+        markerConfig?: MarkerConfig;
+    });
+    /** Preserve marker state while a scene replaces its renderer canvas. */
+    setDomElement(element: HTMLElement): void;
+    setModel(model: THREE.Object3D): void;
+    loadRegions(config: CharacterConfig, options?: {
+        sliceSurfaceQueries?: boolean;
+    }): Promise<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 (marker, line, label, bone refs)
+     */
+    private removeMarkerComponents;
+    updateRegionMeshes(regionName: string, meshNames: string[]): void;
+    /**
+     * Reposition an existing marker to a new position.
+     * This moves the marker, line, and label without recreating them.
+     *
+     * @param regionName - Name of the region to reposition
+     * @param newPosition - New world position for the marker
+     */
+    repositionMarker(regionName: string, newPosition: THREE.Vector3): void;
+    /**
+     * Get the current position of a marker
+     */
+    getMarkerPosition(regionName: string): THREE.Vector3 | null;
+    /**
+     * Resolve the effective style for a region by merging:
+     * global defaults -> character defaults -> region style
+     */
+    private resolveRegionStyle;
+    /**
+     * Resolve a named direction or custom vector to a THREE.Vector3.
+     * For 'camera' direction, returns direction from position toward current camera.
+     */
+    private resolveLineDirection;
+    /**
+     * Create a bezier curve between two points.
+     */
+    private createBezierCurve;
+    /**
+     * Create an arc curve between two points.
+     */
+    private createArcCurve;
+    private unpackCurvePoints;
+    /**
+     * Create a styled line with support for dashed/dotted, curves, and arrow heads.
+     */
+    private createStyledLine;
+    /**
+     * Create an arrow head cone mesh.
+     */
+    private createArrowHead;
+    setCurrentRegion(name: string | null): void;
+    /**
+     * Create a marker for an annotation.
+     *
+     * Algorithm:
+     * 1. Find annotation center from bones/meshes
+     * 2. Determine best outward direction based on annotation type, cameraAngle, or style.lineDirection
+     * 3. Raycast from outside toward annotation center to find surface point
+     * 4. Line extends outward from surface with configured styling
+     *
+     */
+    private resolveMarkerPlacement;
+    private createMarker;
+    private createMarkerInSlices;
+    private renderMarker;
+    /**
+     * Embody Rust owns endpoint layout; the Three adapter applies the returned positions
+     * to its Three.js marker geometry and labels.
+     */
+    private separateOverlappingMarkers;
+    /**
+     * Determine the outward direction for marker placement based on annotation type.
+     *
+     * This uses semantic knowledge about body parts:
+     * - Face/eyes/mouth: forward (positive Z)
+     * - Back: backward (negative Z)
+     * - Left/right parts: semantic side, resolved against model laterality
+     * - Feet: down (negative Y)
+     * - If cameraAngle is specified, use that angle
+     * - Default: direction from model center to annotation center
+     */
+    private getOutwardDirection;
+    /**
+     * Find surface point by raycasting from OUTSIDE toward the annotation center.
+     * This ensures we hit the outer surface facing the outward direction.
+     */
+    private findSurfacePoint;
+    private findSurfacePointInSlices;
+    private getSuffixPattern;
+    /**
+     * Get center point and bounding box of annotation's bones/meshes.
+     * Uses fuzzy matching to handle bone names with numeric suffixes.
+     */
+    private getRegionCenterAndBox;
+    private formatLabelText;
+    private buildLabelTexture;
+    private createLabelSprite;
+    private updateLabelSprite;
+    private updateMarkerStyles;
+    private getResolvedLineConfig;
+    private getViewportSafeBounds;
+    private updateMarkerGeometry;
+    private updateMarkerLineLayout;
+    private onClick;
+    /**
+     * Update marker positions to follow animated bones.
+     * Uses stored bone references and local offsets for efficiency.
+     */
+    private updateMarkerPositions;
+    /**
+     * Find the primary bone for a region (for animation tracking).
+     */
+    private findPrimaryBone;
+    /**
+     * Per-frame update: distance-based scaling + explicit cameraAngle visibility.
+     * Markers scale continuously with camera distance to maintain consistent screen size.
+     * Occlusion is handled by the GPU via depth testing (depthTest: true).
+     */
+    update(): void;
+    private refreshLaterality;
+    /**
+     * Apply zoom-based scaling to all markers, lines, and labels.
+     * Only called when crossing the zoom threshold (not every frame).
+     */
+    private applyZoomScale;
+    setVisible(visible: boolean): void;
+    private readObjectOpacity;
+    private setObjectOpacity;
+    private captureVisibilityAnimationStates;
+    private getVisibilityAnimationFactors;
+    private applyVisibilityAnimationStates;
+    private restoreVisibilityAnimationStates;
+    private stopAllMarkerVisibilityAnimations;
+    private stopMarkerVisibilityAnimation;
+    private getMarkerTargetVisibility;
+    private setMarkerObjectsVisible;
+    private getMarkerFallbackOpacity;
+    private getMarkerBaseLabelScale;
+    private captureMarkerVisibilityAnimationState;
+    private animateMarkerVisibility;
+    private stopVisibilityAnimation;
+    private animateVisibility;
+    clear(): void;
+    /**
+     * Solo a specific marker - hide all others.
+     * Pass null to unsolo.
+     */
+    setSoloMarker(regionName: string | null): void;
+    /**
+     * Get currently soloed marker name.
+     */
+    getSoloedMarker(): string | null;
+    /**
+     * Expand a parent region to show its children.
+     */
+    expandRegion(regionName: string, animation?: ExpandAnimation, duration?: number): Promise<void>;
+    /**
+     * Collapse a parent region to hide its children.
+     */
+    collapseRegion(regionName: string, duration?: number): Promise<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;
+    /**
+     * Animate a child marker in place using the same visibility curve as regular markers.
+     */
+    private animateMarkerIn;
+    /**
+     * Animate a child marker out in place using the same visibility curve as regular markers.
+     */
+    private animateMarkerOut;
+    /**
+     * Update line style for a specific region at runtime.
+     */
+    updateLineStyle(regionName: string, lineConfig: Partial<LineConfig>): void;
+    /**
+     * Update marker style for a specific region at runtime.
+     */
+    updateMarkerStyle(regionName: string, styleOverrides: Partial<MarkerStyleOverrides>): void;
+    dispose(): void;
+}
+export {};