threedviewer 2.0.1 → 2.2.0

package/README.md

@@ -132,7 +132,7 @@ function App() {
       ...defaultOptions.helpers,
       grid: true,
       axes: true,
-      addGizmo: true, // New gizmo option
+      gizmo: true, // Enable viewport gizmo
     },
    threeBaseRefs: {
       scene: sceneRef,
@@ -285,10 +285,8 @@ const defaultOptions: SimpleViewerOptions = {
    },
    helpers: {
       grid: true,
-      gridColor: '#333333',
       axes: false,
-      object3DHelper: false,
-      addGizmo: false, // new Gizmo control is disabled by default
+      gizmo: false, // Viewport gizmo is disabled by default
    },
    threeBaseRefs: {
       mountPoint: {current: null},
@@ -316,6 +314,29 @@ const defaultOptions: SimpleViewerOptions = {
 };
 ```
 
+### Viewport Gizmo
+
+ThreeDViewer includes an optional viewport gizmo for easy camera orientation control:
+
+```javascript
+const options = {
+  helpers: {
+    gizmo: true, // Enable with default settings
+    // Or configure with options:
+    gizmo: {
+      placement: 'top-right', // 'top-left', 'top-right', 'bottom-left', 'bottom-right'
+      size: 128 // Size in pixels
+    }
+  }
+};
+```
+
+The gizmo provides:
+- Interactive 3D orientation indicator
+- Click to snap camera to axis views
+- Visual feedback for current camera orientation
+- Synchronized with main viewport controls
+
 ### Path Tracing
 
 ThreeDViewer now supports path tracing for high-quality rendering with customizable settings:

package/dist/SimpleViewerWrapper.d.ts

@@ -0,0 +1,24 @@
+import { default as React } from 'react';
+import { SimpleViewerProps } from './types';
+import { ControlsInstance } from './types/CommonTypes';
+import { TypedEventEmitter } from './events/EventEmitter';
+import { ViewerEventMap } from './events/ViewerEvents';
+import * as THREE from 'three';
+export interface SimpleViewerHandle {
+    scene: THREE.Scene | null;
+    camera: THREE.Camera | null;
+    renderer: THREE.WebGLRenderer | null;
+    controls: ControlsInstance | null;
+    events: TypedEventEmitter<ViewerEventMap>;
+    loadModel?: (url: string) => Promise<void>;
+    startRendering?: () => void;
+    stopRendering?: () => void;
+    captureScreenshot?: () => Promise<string>;
+    dispose?: () => void;
+}
+/**
+ * SimpleViewer component using clean architecture
+ * This is now the main export replacing the legacy implementation
+ */
+declare const SimpleViewerWrapper: React.ForwardRefExoticComponent<SimpleViewerProps & React.RefAttributes<SimpleViewerHandle>>;
+export default SimpleViewerWrapper;

package/dist/core/ViewerCore.d.ts

@@ -0,0 +1,114 @@
+import { IRenderer, IRendererOptions, IScene, IModelLoader, ICamera, IControls, IObject3D, Result } from './interfaces';
+import { ViewerState } from './entities/ViewerState';
+import { TypedEventEmitter } from '../events/EventEmitter';
+import { ViewerEventMap } from './events/ViewerEvents';
+import { SimpleViewerOptions } from '../types/SimpleViewerOptions';
+import { IPathTracingService } from './services/IPathTracingService';
+import { IEnvironmentService } from './services/IEnvironmentService';
+import { ISceneSetupService } from './services/ISceneSetupService';
+import { IFloorAlignmentService } from './services/IFloorAlignmentService';
+export interface ViewerDependencies {
+    renderer: IRenderer;
+    scene: IScene;
+    camera: ICamera;
+    controls: IControls;
+    modelLoader: IModelLoader;
+    options: SimpleViewerOptions;
+    rendererOptions?: IRendererOptions;
+    pathTracingService?: IPathTracingService;
+    environmentService?: IEnvironmentService;
+    sceneSetupService?: ISceneSetupService;
+    floorAlignmentService?: IFloorAlignmentService;
+}
+/**
+ * Core business logic for the 3D viewer
+ * Independent of UI framework and rendering engine
+ */
+export declare class ViewerCore {
+    private state;
+    private readonly events;
+    private readonly renderLoopManager;
+    private lastFrameTime;
+    private frameCount;
+    private stateChangeCallback?;
+    private pathTracingStartTime?;
+    private screenshotElement;
+    private isShowingScreenshot;
+    private screenshotResizeHandler?;
+    private serializedSceneState?;
+    private lastModelUrl?;
+    private pathTracingCompleteHandled;
+    private disposed;
+    private readonly renderer;
+    private readonly scene;
+    private readonly camera;
+    private readonly controls;
+    private readonly modelLoader;
+    private readonly options;
+    private readonly rendererOptions?;
+    private readonly sceneSetupService?;
+    private environmentService?;
+    private pathTracingService?;
+    private readonly floorAlignmentService?;
+    constructor(dependencies: ViewerDependencies);
+    /**
+     * Initialize the viewer
+     */
+    initialize(): Promise<Result<void>>;
+    /**
+     * Load a 3D model
+     */
+    loadModel(source: string | IObject3D): Promise<Result<void>>;
+    /**
+     * Start the render loop
+     */
+    private startRenderLoop;
+    /**
+     * Stop the render loop
+     */
+    private stopRenderLoop;
+    /**
+     * Render a single frame
+     */
+    private renderFrame;
+    /**
+     * Resize the renderer
+     */
+    resize(width: number, height: number): void;
+    /**
+     * Get current state
+     */
+    getState(): ViewerState;
+    /**
+     * Subscribe to state changes
+     */
+    onStateChange(callback: (state: ViewerState) => void): () => void;
+    /**
+     * Get event emitter
+     */
+    getEvents(): TypedEventEmitter<ViewerEventMap>;
+    /**
+     * Get renderer DOM element
+     */
+    getDomElement(): HTMLCanvasElement;
+    /**
+     * Replace the 3D scene with a screenshot
+     */
+    private replaceWithScreenshot;
+    /**
+     * Restore the 3D scene from screenshot
+     */
+    private restoreFromScreenshot;
+    /**
+     * Dispose scene resources while keeping the screenshot
+     */
+    private disposeSceneResources;
+    /**
+     * Recursively dispose of an object and its children
+     */
+    private disposeObject;
+    /**
+     * Dispose of all resources
+     */
+    dispose(): void;
+}

package/dist/core/entities/ViewerState.d.ts

@@ -0,0 +1,44 @@
+import { IObject3D } from '../interfaces/IObject3D';
+import { ThreeViewerError } from '../../errors/ThreeViewerError';
+export type ViewerStatus = 'idle' | 'loading' | 'loaded' | 'error' | 'rendering' | 'disposed';
+export interface ViewerStateData {
+    status: ViewerStatus;
+    currentModel: IObject3D | null;
+    error: ThreeViewerError | null;
+    isInitialized: boolean;
+    loadProgress: number;
+    renderInfo: RenderInfo;
+}
+export interface RenderInfo {
+    frameCount: number;
+    fps: number;
+    lastRenderTime: number;
+    averageRenderTime: number;
+}
+/**
+ * Immutable state class for the viewer
+ * Implements state machine pattern for viewer states
+ */
+export declare class ViewerState {
+    private readonly data;
+    constructor(data?: Partial<ViewerStateData>);
+    get status(): ViewerStatus;
+    get currentModel(): IObject3D | null;
+    get error(): ThreeViewerError | null;
+    get isInitialized(): boolean;
+    get loadProgress(): number;
+    get renderInfo(): RenderInfo;
+    setInitialized(): ViewerState;
+    startLoading(): ViewerState;
+    updateLoadProgress(progress: number): ViewerState;
+    setLoaded(model: IObject3D): ViewerState;
+    setError(error: ThreeViewerError): ViewerState;
+    startRendering(): ViewerState;
+    updateRenderInfo(info: Partial<RenderInfo>): ViewerState;
+    dispose(): ViewerState;
+    canLoad(): boolean;
+    canRender(): boolean;
+    isLoading(): boolean;
+    hasError(): boolean;
+    toJSON(): ViewerStateData;
+}

package/dist/core/events/ViewerEvents.d.ts

@@ -0,0 +1,49 @@
+import { ThreeViewerError } from '../../errors';
+import { IObject3D } from '../interfaces/IObject3D';
+import { ICamera } from '../interfaces/ICamera';
+import { IControls } from '../interfaces/IControls';
+export interface ViewerEventMap {
+    'initialized': {
+        viewer: unknown;
+    };
+    'disposed': {
+        viewer: unknown;
+    };
+    'model:loading': {
+        url: string;
+    };
+    'model:loaded': {
+        model: IObject3D;
+        loadTime: number;
+    };
+    'model:error': {
+        error: ThreeViewerError;
+        url?: string;
+    };
+    'render:start': {
+        frame: number;
+    };
+    'render:complete': {
+        frame: number;
+        renderTime: number;
+        samples?: number;
+    };
+    'pathtracing:complete': {
+        samples: number;
+        totalTime: number;
+    };
+    'screenshot:captured': {
+        dataUrl: string;
+    };
+    'controls:change': {
+        type?: string;
+        camera?: ICamera;
+        controls?: IControls;
+    };
+    'object:selected': {
+        object: IObject3D;
+    };
+    'error': {
+        error: ThreeViewerError;
+    };
+}

package/dist/core/interfaces/ICamera.d.ts

@@ -0,0 +1,27 @@
+import { IObject3D, IVector3 } from './IObject3D';
+import { IRendererExtension } from './IRendererExtension';
+/**
+ * Core interface for cameras, independent of rendering engine
+ */
+export interface ICamera extends IObject3D, IRendererExtension {
+    type: 'perspective' | 'orthographic';
+    near: number;
+    far: number;
+    lookAt(target: IVector3): void;
+    updateProjectionMatrix(): void;
+    getWorldDirection(target: IVector3): void;
+}
+export interface IPerspectiveCamera extends ICamera {
+    type: 'perspective';
+    fov: number;
+    aspect: number;
+}
+export interface IOrthographicCamera extends ICamera {
+    type: 'orthographic';
+    left: number;
+    right: number;
+    top: number;
+    bottom: number;
+    zoom: number;
+}
+export type CameraType = IPerspectiveCamera | IOrthographicCamera;

package/dist/core/interfaces/IControls.d.ts

@@ -0,0 +1,38 @@
+import { IVector3 } from './IObject3D';
+/**
+ * Core interface for camera controls, independent of implementation
+ */
+export interface IControls {
+    enabled: boolean;
+    enableDamping: boolean;
+    dampingFactor: number;
+    enableZoom: boolean;
+    enableRotate: boolean;
+    enablePan: boolean;
+    zoomSpeed: number;
+    minDistance: number;
+    maxDistance: number;
+    rotateSpeed: number;
+    minPolarAngle: number;
+    maxPolarAngle: number;
+    minAzimuthAngle: number;
+    maxAzimuthAngle: number;
+    panSpeed: number;
+    screenSpacePanning: boolean;
+    target: IVector3;
+    update(): boolean;
+    reset(): void;
+    dispose(): void;
+    connect(domElement: HTMLElement): void;
+    disconnect(): void;
+}
+export interface IOrbitControls extends IControls {
+    type: 'orbit';
+    autoRotate: boolean;
+    autoRotateSpeed: number;
+}
+export interface IMapControls extends IControls {
+    type: 'map';
+    screenSpacePanning: true;
+}
+export type ControlsType = IOrbitControls | IMapControls;

package/dist/core/interfaces/IModelLoader.d.ts

@@ -0,0 +1,46 @@
+import { Result } from '../../utils/Result';
+import { IObject3D } from './IObject3D';
+/**
+ * Core interface for model loaders, independent of file format
+ */
+export interface IModelLoader {
+    /**
+     * Load a 3D model from a URL
+     */
+    load(url: string): Promise<Result<IModel>>;
+    /**
+     * Check if this loader supports the given URL/file type
+     */
+    supports(url: string): boolean;
+}
+export interface IModel {
+    scene: IObject3D;
+    animations?: IAnimation[];
+    cameras?: IModelCamera[];
+    userData?: Record<string, unknown>;
+}
+export interface IAnimation {
+    name: string;
+    duration: number;
+    tracks: IAnimationTrack[];
+}
+export interface IAnimationTrack {
+    name: string;
+    type: 'vector' | 'quaternion' | 'number' | 'boolean';
+    times: Float32Array;
+    values: Float32Array;
+}
+export interface ILoadingManager {
+    onStart?: (url: string, itemsLoaded: number, itemsTotal: number) => void;
+    onProgress?: (url: string, itemsLoaded: number, itemsTotal: number) => void;
+    onLoad?: () => void;
+    onError?: (url: string) => void;
+}
+export interface IModelCamera {
+    name: string;
+    type: string;
+    fov?: number;
+    aspect?: number;
+    near: number;
+    far: number;
+}

package/dist/core/interfaces/IObject3D.d.ts

@@ -0,0 +1,36 @@
+import { Result } from '../../utils/Result';
+/**
+ * Core interface for 3D objects, independent of Three.js
+ */
+export interface IObject3D {
+    id: string;
+    name: string;
+    visible: boolean;
+    position: IVector3;
+    rotation: IVector3;
+    scale: IVector3;
+    add(child: IObject3D): Result<void>;
+    remove(child: IObject3D): Result<void>;
+    traverse(callback: (object: IObject3D) => void): void;
+    clone(): IObject3D;
+    dispose(): void;
+}
+export interface IVector3 {
+    x: number;
+    y: number;
+    z: number;
+    set(x: number, y: number, z: number): void;
+    copy(v: IVector3): void;
+    add(v: IVector3): void;
+    multiply(v: IVector3): void;
+    normalize(): void;
+    length(): number;
+}
+export interface IBoundingBox {
+    min: IVector3;
+    max: IVector3;
+    setFromObject(object: IObject3D): void;
+    getCenter(target: IVector3): void;
+    getSize(target: IVector3): void;
+    isEmpty(): boolean;
+}

package/dist/core/interfaces/IRenderer.d.ts

@@ -0,0 +1,44 @@
+import { Result } from '../../utils/Result';
+import { IScene } from './IScene';
+import { ICamera } from './ICamera';
+import { IRendererExtension } from './IRendererExtension';
+/**
+ * Core interface for renderers, independent of rendering engine
+ * Extends IRendererExtension to allow controlled access to internal implementation
+ */
+export interface IRenderer extends IRendererExtension {
+    id: string;
+    initialize(options: IRendererOptions): Result<void>;
+    render(scene: IScene, camera: ICamera): Result<void>;
+    setSize(width: number, height: number): void;
+    setPixelRatio(ratio: number): void;
+    getDomElement(): HTMLCanvasElement;
+    getContext(): WebGLRenderingContext | WebGL2RenderingContext | null;
+    dispose(): void;
+    capabilities: IRendererCapabilities;
+}
+export interface IRendererOptions {
+    antialias?: boolean;
+    alpha?: boolean;
+    premultipliedAlpha?: boolean;
+    preserveDrawingBuffer?: boolean;
+    powerPreference?: 'high-performance' | 'low-power' | 'default';
+    pixelRatio?: number;
+    shadowMap?: {
+        enabled: boolean;
+        type?: 'basic' | 'pcf' | 'pcfsoft' | 'vsm';
+    };
+    toneMapping?: {
+        type: 'none' | 'linear' | 'reinhard' | 'cineon' | 'aces';
+        exposure: number;
+    };
+}
+export interface IRendererCapabilities {
+    maxTextureSize: number;
+    maxCubemapSize: number;
+    maxAttributes: number;
+    maxVertexUniforms: number;
+    maxFragmentUniforms: number;
+    maxSamples: number;
+    isWebGL2: boolean;
+}

package/dist/core/interfaces/IRendererExtension.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Interface for renderer extensions that need access to the underlying renderer
+ * This allows features like path tracing while maintaining clean architecture
+ */
+export interface IRendererExtension<T = unknown> {
+    /**
+     * Get the internal renderer implementation
+     * Returns null if not available or not of expected type
+     */
+    getInternalRenderer(): T | null;
+}
+/**
+ * Type guard for checking if an object implements IRendererExtension
+ */
+export declare function hasInternalRenderer<T>(obj: unknown): obj is IRendererExtension<T>;

package/dist/core/interfaces/IScene.d.ts

@@ -0,0 +1,36 @@
+import { Result } from '../../utils/Result';
+import { IObject3D } from './IObject3D';
+import { IRendererExtension } from './IRendererExtension';
+/**
+ * Core interface for 3D scenes, independent of rendering engine
+ */
+export interface IScene extends IRendererExtension {
+    id: string;
+    name: string;
+    add(object: IObject3D): Result<void>;
+    remove(object: IObject3D): Result<void>;
+    clear(): void;
+    traverse(callback: (object: IObject3D) => void): void;
+    background: IColor | ITexture | null;
+    fog: IFog | null;
+    environment: ITexture | null;
+}
+export interface IColor {
+    r: number;
+    g: number;
+    b: number;
+    setHex(hex: number): void;
+    setRGB(r: number, g: number, b: number): void;
+    getHex(): number;
+}
+export interface ITexture {
+    id: string;
+    image: HTMLImageElement | ImageData | HTMLCanvasElement | HTMLVideoElement | null;
+    needsUpdate: boolean;
+    dispose(): void;
+}
+export interface IFog {
+    color: IColor;
+    near: number;
+    far: number;
+}

package/dist/core/interfaces/index.d.ts

@@ -0,0 +1,7 @@
+export * from './IObject3D';
+export * from './IScene';
+export * from './IRenderer';
+export * from './ICamera';
+export * from './IModelLoader';
+export * from './IControls';
+export { Result } from '../../utils/Result';

package/dist/core/services/IEnvironmentService.d.ts

@@ -0,0 +1,34 @@
+import { Result } from '../../utils/Result';
+import { IScene, ITexture } from '../interfaces/IScene';
+import { IRenderer } from '../interfaces/IRenderer';
+export interface IEnvironmentService {
+    /**
+     * Initialize the environment service
+     */
+    initialize(options: IEnvironmentOptions): Promise<Result<void>>;
+    /**
+     * Load environment map from URL
+     */
+    loadEnvironmentMap(url: string): Promise<Result<ITexture>>;
+    /**
+     * Apply environment to scene
+     */
+    applyToScene(scene: IScene, texture: ITexture): Result<void>;
+    /**
+     * Create studio environment
+     */
+    createStudioEnvironment(options?: IStudioEnvironmentOptions): Result<ITexture>;
+    /**
+     * Dispose of resources
+     */
+    dispose(): void;
+}
+export interface IEnvironmentOptions {
+    renderer: IRenderer;
+    autoDispose?: boolean;
+}
+export interface IStudioEnvironmentOptions {
+    intensity?: number;
+    groundColor?: string;
+    skyColor?: string;
+}

package/dist/core/services/IFloorAlignmentService.d.ts

@@ -0,0 +1,11 @@
+import { IObject3D } from '../interfaces/IObject3D';
+import { Result } from '../../utils/Result';
+/**
+ * Service interface for aligning objects to floor
+ */
+export interface IFloorAlignmentService {
+    /**
+     * Align an object to the floor (y=0)
+     */
+    alignToFloor(object: IObject3D): Result<void>;
+}

package/dist/core/services/IPathTracingService.d.ts

@@ -0,0 +1,81 @@
+import { Result } from '../../utils/Result';
+import { IRenderer } from '../interfaces/IRenderer';
+import { IScene } from '../interfaces/IScene';
+import { ICamera } from '../interfaces/ICamera';
+import { TypedEventEmitter } from '../../events/EventEmitter';
+export interface IPathTracingService {
+    /**
+     * Event emitter for path tracing events
+     */
+    readonly events: TypedEventEmitter<{
+        'pathtracing:paused': {
+            samples: number;
+        };
+    }>;
+    /**
+     * Initialize path tracing with given options
+     */
+    initialize(options: IPathTracingOptions): Promise<Result<void>>;
+    /**
+     * Enable or disable path tracing
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Update path tracing settings
+     */
+    updateSettings(settings: Partial<IPathTracingSettings>): void;
+    /**
+     * Render a frame with path tracing
+     */
+    render(scene: IScene, camera: ICamera): Promise<Result<void>>;
+    /**
+     * Get current sample count
+     */
+    getSampleCount(): number;
+    /**
+     * Check if path tracing is currently enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Check if path tracer has been disposed
+     */
+    isPathTracerDisposed(): boolean;
+    /**
+     * Reset accumulation
+     */
+    reset(): void;
+    /**
+     * Dispose of resources
+     */
+    dispose(): void;
+    /**
+     * Check if path tracing is supported
+     */
+    isSupported(): boolean;
+    /**
+     * Get the base64 image generated when pausing at the final sample
+     * @returns The base64 encoded PNG image or null if not available
+     */
+    getPausedFrameBase64(): string | null;
+    /**
+     * Check if an image overlay is currently displayed
+     */
+    hasImageOverlay(): boolean;
+    /**
+     * Remove the image overlay without disposing other resources
+     */
+    removeImageOverlay(): void;
+}
+export interface IPathTracingOptions {
+    enabled: boolean;
+    renderer: IRenderer;
+}
+export interface IPathTracingSettings {
+    samples: number;
+    bounces: number;
+    transmissiveBounces?: number;
+    renderScale: number;
+    lowResScale: number;
+    dynamicLowRes: boolean;
+    enablePathTracing: boolean;
+}