Visionary - 快速开始

本文档将指导您搭建 Visionary 的开发环境，并运行 ShowcaseScene 演示案例。

演示案例说明：本示例将展示一个包含多模型轮播（Carousel）与单模型多机位运镜（Cinematic Camera）的混合渲染场景。

前置条件

Node.js: 版本 18 或更高。
Browser: 支持 WebGPU 的现代浏览器（例如 Chrome 121+、Edge 或 Chrome Canary）。如果 WebGPU 未启用，可能需要在 chrome://flags 中启用。

项目结构

请确保您的目录组织如下：

visionary/
├── models/                   # 在此处放置模型文件
│   └── onnx_dummy.onnx      # WebGPU 初始化所需文件
├── src/                      # 核心引擎逻辑
├── demo/                     # 演示示例
│   ├── showcase/            # [展示模块]
│   │   ├── scripts/
│   │   │   ├── ShowcaseScene.ts    # 核心逻辑：场景切换与渲染
│   │   │   ├── sceneConfigs.ts     # 场景模型与相机配置
│   │   │   ├── main.ts             # 启动入口：创建 ShowcaseScene 并绑定 UI
│   │   │   └── types.ts            # 类型定义
│   │   ├── styles/
│   │   │   └── showcase.css        # 样式
│   │   └── index.html              # 展示入口点
│   └── simple/              # 简单查看器示例
├── dist/                     # 构建输出
├── package.json
└── tsconfig.json

安装与设置

安装依赖 在根目录下运行以下命令：
```
npm install
```
准备资产 将您的 3D 模型文件放入 models/ 目录。 sceneConfigs.ts 中的当前配置引用了以下类型的模型：
- /models/*.glb（GLTF/GLB 模型）
- /models/*.ply（PLY 点云文件）
- /models/dyn/*.onnx（ONNX 4DGS 动态模型）
- /models/qiewu/*.onnx（ONNX 高斯点云模型）
您可以：
- 下载引用的模型并放置在 models/ 目录中
- 修改 sceneConfigs.ts 中的路径指向您自己的模型
启动开发服务器 启动本地开发环境：
```
npm run dev
```
访问展示页面 在浏览器中导航到特定路径：

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

（默认端口为 3000，在 vite.config.ts 中配置）

注意：若提示 WebGPU/ORT 相关跨域或 COOP/COEP 问题，请确保本地服务器返回合适的跨源隔离头；Vite 默认已开启。

自定义配置

所有模型自定义均在 demo/showcase/scripts/sceneConfigs.ts 和 demo/showcase/scripts/ShowcaseScene.ts 中处理。无论是向轮播添加项目还是更改主模型场景，方法都是一样的：只需更新 url（文件路径）和 type（文件格式）。

配置入口点

打开 demo/showcase/scripts/sceneConfigs.ts 来配置场景模型和相机设置。对于场景逻辑，修改 demo/showcase/scripts/ShowcaseScene.ts：

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

// ------------------------------------------------------------------
// 区域 A：轮播列表（多个对象）
// ------------------------------------------------------------------
// 要添加模型，请复制数组内的 { ... } 块并更新 url/type。
export const SCENE1_CAROUSEL_ITEMS: CarouselItemConfig[] = [
    { 
        type: 'file', 
        url: '/models/my_model_01.ply',        // 修改 1：您的模型路径
        loadOptions: { 
            type: 'ply' as const,                // 修改 2：匹配的文件类型
            name: 'Gallery Item A' 
        },
        scale: 2.5,                             // 可选：缩放因子
        transform: {                            // 可选：变换设置
            position: new THREE.Vector3(0, -1, 0),
            rotation: new THREE.Euler(0, 0, 0)
        }
    },
    // ... 复制并粘贴以添加更多项目
];

// ------------------------------------------------------------------
// 区域 B：场景配置
// ------------------------------------------------------------------
// 在同一文件中配置相机视图和模型设置
// 对于场景逻辑，修改 demo/showcase/scripts/ShowcaseScene.ts

请确保 type 字段与您的文件扩展名匹配，以避免加载错误。

重要提示

ORT WASM 路径：showcase 会自动使用默认 WASM 路径（/src/ort/）初始化 ORT。这些文件在运行 npm install 时会通过 postinstall 脚本自动复制到 src/ort/。若您单独部署 showcase，请同步拷贝 src/ort 到可访问位置，或在代码里改 wasmPaths。
模型路径：sceneConfigs.ts 中的所有模型路径使用 /models/ 前缀。请确保您的模型放置在项目根目录的 models/ 目录中（如果使用 Vite 的 public 目录，则放在 public/models/）。
变换选项：transform 字段是可选的，允许您为场景中的模型设置初始位置和旋转。

常见操作

更换模型

要替换模型，在 sceneConfigs.ts 中更新 url 和 loadOptions.type：

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

调整相机

在 sceneConfigs.ts 中修改相机设置：

场景 2：编辑 getScene2CameraViews() 来更改相机位置、目标、过渡时长和缓动函数
场景 3：调整 SCENE3_CAMERA_BASE（位置和目标）和 SCENE3_CAMERA_SWING（振幅、频率、时间缩放）

修改轮播

在 ShowcaseScene.ts 中调整轮播行为：

条目：修改 sceneConfigs.ts 中的 SCENE1_CAROUSEL_ITEMS
间距：更改 carouselSpacing 属性（默认：4.0）
速度：调整 carouselSpeed（移动速度）和 carouselRotationSpeed（旋转速度）

扩展展示场景

要添加自定义场景（例如 loadScene4）：

在 ShowcaseScene.ts 中添加新方法：

async loadScene4() {
    // 使用 loadUnifiedModel 加载您的模型
    // 在场景中布置它们
}

在 switchToScene 中添加分支调用 loadScene4
在 main.ts 或页面按钮中添加 UI 触发逻辑

为了配置更友好，也可以采用完全数据驱动的方式：

在 sceneConfigs.ts 中新增一个通用列表，比如 SCENE4_CONFIGS（包含模型 URL、变换、相机初始值）
在 ShowcaseScene 里按配置循环生成模型，减少硬编码