# 3dgsSystem

**Repository Path**: winshengly/3dgs-system

## Basic Information

- **Project Name**: 3dgsSystem
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-03-26
- **Last Updated**: 2026-03-26

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 3D Gaussian Splatting - 可泛化扩展版

这是 **3D Gaussian Splatting** 项目，添加了**可泛化到新场景的3D重建**功能。

## 🎯 两套完整系统

### 1️⃣ 原始 3D Gaussian Splatting (场景特定优化)

**特点**: 每个场景需要独立优化训练，获得最高质量重建

**使用场景**: 高质量单场景重建，实时渲染

```bash
# 原始训练方式
python train.py -s <scene_path> -m <output_path>
```

**详细文档**: 查看 [README_ORIGINAL.md](README_ORIGINAL.md)

---

### 2️⃣ 可泛化 3DGS (新增功能) ⭐

**特点**: 跨场景泛化，无需对新场景优化

**使用场景**: 快速重建多个场景，实时新场景处理

```python
from models import Generalizable3DGS

# 创建模型
model = Generalizable3DGS(
    num_views=3,
    backbone='lightweight'
).cuda()

# 一次推理完成重建
gaussians = model(images, cameras)['gaussians']
```

**详细文档**: 查看 [README_GENERALIZABLE.md](README_GENERALIZABLE.md)

---

## 🚀 快速开始

### 安装

```bash
# 克隆项目 (包含子模块)
git clone --recursive https://github.com/graphdeco-inria/gaussian-splatting

# 安装依赖
pip install -r requirements.txt

# 编译CUDA扩展
pip install submodules/diff-gaussian-rasterization
pip install submodules/simple-knn
```

### 使用合成数据集快速测试

```bash
# 1. 数据集已生成在 data/synthetic/
# 2. 运行训练
python scripts/train_real.py --data_root ./data/synthetic --num_epochs 3

# 3. 测试推理
python -c "
from models import Generalizable3DGS
import torch

model = Generalizable3DGS(num_views=3).cuda()
print('✅ 模型加载成功')
"
```

## 📁 项目结构

```
3dgsSystemDev/
├── models/                    # ⭐ 新增: 可泛化3DGS模块
│   ├── __init__.py
│   ├── feature_extractor.py
│   ├── cost_volume.py
│   ├── geometry_encoder.py
│   ├── cross_view_transformer.py
│   ├── gaussian_predictor.py
│   ├── generalizable_3dgs.py
│   └── README.md
│
├── scripts/                   # ⭐ 训练脚本
│   ├── train_generalizable.py
│   ├── train_real.py
│   ├── prepare_dataset.py
│   └── process_realestate10k.py
│
├── data/                      # 数据集
│   └── synthetic/             # ⭐ 合成数据 (立即可用)
│       ├── train/ (180 scenes)
│       └── test/ (20 scenes)
│
├── scene/                     # 原始: 场景优化模块
├── gaussian_renderer/         # 原始: 渲染器
├── utils/                     # 原始: 工具函数
├── train.py                   # 原始训练脚本
└── render.py                  # 原始渲染脚本
```

## 📖 使用指南

### 场景1: 单场景高质量重建 (原始功能)

```bash
# 使用COLMAP处理你的图像
python convert.py -s <image_path> --colmap_executable <colmap_path>

# 训练场景
python train.py -s <output_path> --iterations 30000

# 渲染
python render.py -m <output_path> --skip_train
```

### 场景2: 快速多场景重建 (新增功能)

```python
import torch
from models import Generalizable3DGS

# 准备数据
images = torch.randn(3, 3, 512, 512).cuda()  # 3个视图
K = torch.eye(3).unsqueeze(0).repeat(3,1,1).cuda()
RT = torch.eye(4).unsqueeze(0).repeat(3,1,1).cuda()

# 创建模型
model = Generalizable3DGS(num_views=3).cuda()
model.eval()

# 推理 (一次前向传播!)
with torch.no_grad():
    output = model(images, {'intrinsics': K, 'extrinsics': RT})
    gaussians = output['gaussians']

print(f"生成了 {gaussians['mask'].sum().item()} 个有效高斯点")
```

### 场景3: 训练可泛化模型

```bash
# 使用合成数据集快速开始
python scripts/train_real.py \
    --data_root ./data/synthetic \
    --num_epochs 10 \
    --batch_size 2

# 或使用自定义数据
python scripts/train_generalizable.py \
    --data_root ./your_data \
    --dataset custom
```

## 🔧 API速查

### 可泛化模型

```python
from models import Generalizable3DGS, GeneralizableLoss

# 创建模型
model = Generalizable3DGS(
    num_views=3,              # 输入视图数
    feature_channels=128,     # 特征维度
    geometry_channels=64,      # 几何维度
    transformer_channels=256,  # Transformer维度
    depth_bins=64,            # 深度分箱
    backbone='resnet50'       # 'resnet50' 或 'lightweight'
)

# 前向传播
output = model(images, cameras, return_features=True)
# output['gaussians'] - 高斯属性
# output['features'] - 特征 (可选)
# output['geometry'] - 几何 (可选)

# 损失函数
loss_fn = GeneralizableLoss()
loss, losses = loss_fn(rendered, target_images, gaussians)
```

## 📊 性能对比

| 特性 | 原始3DGS | 可泛化3DGS |
|------|-----------|------------|
| 每场景优化 | ✅ 必需 | ❌ 不需要 |
| 新场景准备时间 | ~30分钟 | ~2秒 |
| 重建质量 | 最高 | 高 |
| 训练数据需求 | 单场景 | 多场景 |
| 推理速度 | 实时渲染 | 实时推理 |
| GPU显存 | ~24GB | ~8GB |

## 📚 文档索引

- **[README_GENERALIZABLE.md](README_GENERALIZABLE.md)** - 可泛化3DGS完整文档
- **[README_ORIGINAL.md](README_ORIGINAL.md)** - 原始3DGS文档
- **[models/README.md](models/README.md)** - 模块技术细节

## 🆕 新增功能

### 模块化架构

- `FeatureExtractor` - ResNet50 + FPN 特征提取
- `CostVolumeBuilder` - 多视图成本体积
- `GeometryEncoder3D` - 3D U-Net 几何编码
- `CrossViewTransformer` - 跨视图注意力
- `GaussianPredictor` - 高斯属性预测

### 数据集支持

- ✅ 合成数据集 (立即可用)
- ✅ 自定义多视图数据
- 🔄 DTU 数据集 (处理中)
- 🔄 RealEstate10K (需要下载视频)

## 🐛 常见问题

### Q: 如何选择使用哪个系统？

**A**:
- 单场景高质量重建 → 使用原始 `train.py`
- 多场景快速重建 → 使用可泛化 `scripts/train_real.py`
- 两者可以并存，不冲突

### Q: 合成数据集够用吗？

**A**: 合成数据集适合:
- 快速测试代码
- 学习API使用
- 验证训练流程

实际应用建议使用真实数据集（DTU、自定义数据）

### Q: 如何准备自己的数据？

**A**: 需要多视图图像和相机参数：

```bash
your_scene/
├── images/
│   ├── view_000.png
│   ├── view_001.png
│   └── view_002.png
└── cameras.json
```

`cameras.json` 格式：
```json
[
  {
    "id": 0,
    "image_name": "view_000.png",
    "intrinsics": [[fx, 0, cx], [0, fy, cy], [0, 0, 1]],
    "extrinsics": [[R00, R01, R02, tx], [R10, R11, R12, ty], [R20, R21, R22, tz], [0, 0, 0, 1]]
  }
]
```

## 📄 许可证

- 非商业研究和评估使用
- 详见 [LICENSE.md](LICENSE.md)

## 🙏 致谢

- 原始 3D Gaussian Splatting 团队
- Inria GRAPHDECO 研究所
- 所有贡献者

---

**文档版本**: v1.0
**最后更新**: 2024年3月
**状态**: ✅ 可用