# 3dgs-demo

**Repository Path**: li-zhengyang2023/3dgs-demo

## Basic Information

- **Project Name**: 3dgs-demo
- **Description**: 3DGS模型上传与展示网站
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-07-28
- **Last Updated**: 2025-07-30

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 3DGS 三维高斯溅射模型渲染系统

本项目基于 Luma AI 的 LumaSplatsThree 库实现了三维高斯溅射（3D Gaussian Splatting）模型的渲染功能。

## 网页开发框架：Vue 3 + Vite

This template should help get you started developing with Vue 3 in Vite. The template uses Vue 3 `<script setup>` SFCs, check out the [script setup docs](https://v3.vuejs.org/api/sfc-script-setup.html#sfc-script-setup) to learn more.

Learn more about IDE Support for Vue in the [Vue Docs Scaling up Guide](https://vuejs.org/guide/scaling-up/tooling.html#ide-support).

## 功能特性

- ✅ 支持 `.splat` 和 `.ply` 格式的3DGS模型文件
- ✅ 支持传统的 `.glb`、`.gltf`、`.obj` 模型文件
- ✅ 实时渲染和交互控制
- ✅ 自动相机位置调整
- ✅ 粒子显示动画效果
- ✅ 键盘和鼠标控制

## 安装依赖

```bash
npm install @lumaai/luma-web --legacy-peer-deps
```

注意：使用 `--legacy-peer-deps` 参数来解决 Three.js 版本兼容性问题。

## 使用方法

### 1. 文件上传

在网页界面中点击"选择文件"按钮，选择以下格式的文件：
- `.splat` - Luma AI 3DGS模型文件
- `.ply` - 点云文件（支持3DGS格式）
- `.glb` / `.gltf` - 传统3D模型文件
- `.obj` - Wavefront OBJ文件

### 2. 交互控制

- **鼠标拖拽**: 旋转视角
- **鼠标滚轮**: 缩放
- **WASD键**: 移动相机位置
  - W: 向前移动
  - S: 向后移动
  - A: 向左移动
  - D: 向右移动

### 3. 代码集成

```javascript
import { loadModel } from './utils/loaders/plyLoader'
import { use3DScene } from './composables/use3DScene'

// 加载3DGS模型
const model = await loadModel(file)
const { addModel } = use3DScene()

// 添加到场景
addModel(model)
```

## 技术实现

### 模型加载器 (`src/utils/loaders/plyLoader.js`)

- 自动检测文件格式
- 使用 `LumaSplatsThree` 加载3DGS模型
- 支持传统模型的加载和材质处理

### 场景管理器 (`src/composables/use3DScene.js`)

- 3D场景初始化和渲染
- 相机和控制器管理
- 3DGS模型的特殊处理
- 自动边界框计算和相机定位

### 文件上传组件 (`src/components/FileUpload.vue`)

- 支持多种文件格式
- 文件验证和错误处理
- 加载状态反馈

## 测试

运行开发服务器：

```bash
npm run dev
```

或者直接打开 `test-3dgs.html` 文件进行测试。

## 注意事项

1. **浏览器兼容性**: 需要支持 WebGL 2.0 的现代浏览器
2. **文件大小**: 3DGS模型文件可能较大，加载时间取决于网络速度
3. **性能**: 复杂场景可能需要较高的GPU性能
4. **CORS**: 本地文件需要通过HTTP服务器访问

## 故障排除

### 依赖冲突问题

如果遇到 Three.js 版本冲突，可以：

1. 使用 `--legacy-peer-deps` 安装
2. 或者降级 Three.js 到兼容版本：
   ```bash
   npm install three@0.157.0 @types/three@0.157.2
   ```

### 模型加载失败

1. 检查文件格式是否正确
2. 确认文件完整性
3. 查看浏览器控制台错误信息
4. 尝试使用示例文件测试

### 渲染性能问题

1. 降低模型复杂度
2. 调整渲染器设置
3. 使用更强大的GPU
4. 优化场景光照设置

## 示例文件

项目包含一个测试页面 `test-3dgs.html`，可以直接在浏览器中打开测试3DGS功能。

## 许可证

本项目基于 MIT 许可证开源。