Visionary - Quick Start

This document guides you through setting up the Visionary development environment and running the ShowcaseScene demo.

About the Demo: This example demonstrates a hybrid rendering scene that features a multi-model carousel and cinematic camera movements across multiple viewpoints for a single model.

Prerequisites

Node.js: v18 or higher.
Browser: A modern browser with WebGPU support enabled (e.g., Chrome 121+, Edge, or Chrome Canary). You may need to enable WebGPU in chrome://flags if it's not already enabled.

Project Structure

Ensure your directory is organized as follows:

visionary/
├── models/                   # Place model files here
│   └── onnx_dummy.onnx      # Required for WebGPU initialization
├── src/                      # The core engine logic
├── demo/                     # Demo examples
│   ├── showcase/            # [Showcase Module]
│   │   ├── scripts/
│   │   │   ├── ShowcaseScene.ts    # Core logic: scene switching and rendering
│   │   │   ├── sceneConfigs.ts     # Scene models and camera configuration
│   │   │   ├── main.ts             # Entry point: creates ShowcaseScene and binds UI
│   │   │   └── types.ts            # Type definitions
│   │   ├── styles/
│   │   │   └── showcase.css        # Styles
│   │   └── index.html              # Showcase entry point
│   └── simple/              # Simple viewer example
├── dist/                     # Build output
├── package.json
└── tsconfig.json

Installation & Setup

Install Dependencies Run the following command in the root directory:
```
npm install
```
Prepare Assets Place your 3D model files into the models/ directory. The current configuration in sceneConfigs.ts references models like:
- /models/*.glb (GLTF/GLB models)
- /models/*.ply (PLY point cloud files)
- /models/dyn/*.onnx (ONNX 4DGS dynamic models)
- /models/qiewu/*.onnx (ONNX Gaussian Splatting models)
You can either:
- Download the referenced models and place them in the models/ directory
- Modify the paths in sceneConfigs.ts to point to your own models
Start Development Server Launch the local development environment:
```
npm run dev
```
Access the Showcase Navigate to the specific path in your browser:

http://localhost:3000/demo/showcase/

(Default port is 3000 as configured in vite.config.ts)

Note: If you encounter WebGPU/ORT related CORS or COOP/COEP issues, ensure your local server returns appropriate cross-origin isolation headers. Vite enables these by default.

Customization

All model customization is handled in demo/showcase/scripts/sceneConfigs.ts and demo/showcase/scripts/ShowcaseScene.ts. Whether you are adding items to the carousel or changing the main hero scene, the method is the same: simply update the url (file path) and the type (file format).

Configuration Entry Point

Open demo/showcase/scripts/sceneConfigs.ts to configure scene models and camera settings. For scene logic, modify demo/showcase/scripts/ShowcaseScene.ts:

// In demo/showcase/scripts/sceneConfigs.ts
import * as THREE from 'three/webgpu';
import { CarouselItemConfig } from './types';

// ------------------------------------------------------------------
// Area A: Carousel List (Multiple Objects)
// ------------------------------------------------------------------
// To add a model, copy a { ... } block inside the array and update the url/type.
export const SCENE1_CAROUSEL_ITEMS: CarouselItemConfig[] = [
    { 
        type: 'file', 
        url: '/models/my_model_01.ply',        // Edit 1: Your model path
        loadOptions: { 
            type: 'ply' as const,              // Edit 2: Matching file type
            name: 'Gallery Item A' 
        },
        scale: 2.5,                            // Optional: Scale factor
        transform: {                           // Optional: Transform settings
            position: new THREE.Vector3(0, -1, 0),
            rotation: new THREE.Euler(0, 0, 0)
        }
    },
    // ... Copy and paste to add more items
];

// ------------------------------------------------------------------
// Area B: Scene Configuration
// ------------------------------------------------------------------
// Configure camera views and model settings in the same file
// For scene logic, modify demo/showcase/scripts/ShowcaseScene.ts

Ensure the type field matches your file extension to avoid loading errors.

Important Notes

ORT WASM Paths: The showcase automatically initializes ORT with default WASM paths (/src/ort/). These files are automatically copied to src/ort/ during npm install via the postinstall script. If you deploy the showcase separately, copy src/ort/ to an accessible location or modify wasmPaths in the code.
Model Paths: All model paths in sceneConfigs.ts use /models/ prefix. Ensure your models are placed in the models/ directory at the project root (or public/models/ if using Vite's public directory).
Transform Options: The transform field is optional and allows you to set initial position and rotation for models in the scene.

Common Operations

Changing Models

To replace a model, update the url and loadOptions.type in sceneConfigs.ts:

{ 
    type: 'file', 
    url: '/models/your_model.ply',
    loadOptions: { type: 'ply' as const, name: 'Your Model' },
    scale: 2.5
}

Adjusting Camera

Modify camera settings in sceneConfigs.ts:

Scene 2: Edit getScene2CameraViews() to change camera positions, targets, transition durations, and easing functions
Scene 3: Adjust SCENE3_CAMERA_BASE (position and target) and SCENE3_CAMERA_SWING (amplitude, frequency, timeScale)

Modifying Carousel

Adjust carousel behavior in ShowcaseScene.ts:

Items: Modify SCENE1_CAROUSEL_ITEMS in sceneConfigs.ts
Spacing: Change carouselSpacing property (default: 4.0)
Speed: Adjust carouselSpeed (movement) and carouselRotationSpeed (rotation)

Extending the Showcase

To add a custom scene (e.g., loadScene4):

Add a new method in ShowcaseScene.ts:

async loadScene4() {
    // Load your models using loadUnifiedModel
    // Arrange them in the scene
}

Add a branch in switchToScene to call loadScene4
Add UI triggers in main.ts or page buttons

For better configuration management, you can also fully data-driven approach:

Add a generic config list like SCENE4_CONFIGS in sceneConfigs.ts (containing model URLs, transforms, camera initial values)
Loop through the config in ShowcaseScene to generate models, reducing hardcoding