# 3DGSConvertTool

**Repository Path**: playertk/3dgsconvert-tool

## Basic Information

- **Project Name**: 3DGSConvertTool
- **Description**: gsbox 界面版本
- **Primary Language**: Unknown
- **License**: GPL-3.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-12-03
- **Last Updated**: 2026-01-09

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 3D高斯点云格式转换器

一个基于 Flet 和 gsbox 的现代化 3D 高斯点云格式转换工具，提供友好的图形界面来转换各种 3D 高斯点云格式。

<div align="center">
  <img src="./img/app.jpg" width="480"/>
</div>

## 🌟 功能特性

### 🎯 核心功能
- **多格式支持**: 支持 PLY、SPLAT、SPX、SPZ、KSPLAT、SOG 等主流 3D 高斯点云格式
- **双向转换**: 支持所有格式之间的相互转换
- **批量处理**: 支持多个文件的批量转换
- **实时预览**: 转换过程中实时显示进度和日志
- **参数自定义**: 丰富的转换参数配置选项

### 🔧 高级功能
- **实时转换进度显示**: 可视化进度条和详细状态信息
- **详细的日志输出**: 完整的转换过程记录
- **输出文件自动命名**: 智能文件命名和路径管理
- **磁盘空间检查**: 转换前自动检查可用空间
- **文件验证和安全检查**: 确保输入文件的有效性和安全性
- **模型信息查看**: 查看 3D 模型的详细信息
- **模型合并**: 支持将多个模型合并为单个文件

### 🎨 用户界面
- **现代化界面**: 基于 Flet 的响应式用户界面
- **直观操作**: 拖拽式文件选择和清晰的参数配置
- **实时反馈**: 即时的操作反馈和状态更新
- **多语言支持**: 支持中英文界面切换

## 📋 系统要求

### 必需依赖
- **Python**: 3.8 或更高版本
- **gsbox**: 3D 高斯点云处理工具
- **操作系统**: Windows 10/11、Linux、macOS

### Python 包依赖
```
flet>=0.28.3
flet-core>=0.28.3
flet-runtime>=0.28.3
pyinstaller>=6.16.0
```

### 确保包含所有必要的资源文件

### 硬件要求
- **内存**: 至少 4GB RAM (推荐 8GB+)
- **存储**: 至少 1GB 可用磁盘空间
- **处理器**: 支持 SSE2 指令集的处理器

## 🚀 安装和运行

### 系统要求
- Python 3.8+
- Windows 7+ (推荐 Windows 10+)
- gsbox 工具 (已包含在项目中)

### 安装步骤

1. **克隆项目**
   ```bash
   git clone <repository-url>
   cd first-flet-app
   ```

2. **安装依赖**
   ```bash
   uv sync
   ```

3. **运行应用程序**
   ```bash
   cd src
   python main.py
   ```

### 打包和分发

我们提供了完整的打包解决方案，可以将应用程序打包成独立的可执行文件：

```bash
# 自动打包（推荐）
python build.py

# 手动打包
pyinstaller main.spec
```

打包完成后，会在 `dist/` 目录下生成：
- **主要程序**: `3D高斯点云格式转换器/3D高斯点云格式转换器.exe`
- **便携版本**: `3D高斯点云格式转换器-便携版/3D高斯点云格式转换器.exe`

详见 [打包指南](PACKAGING_GUIDE.md) 获取详细信息。

## 📁 项目结构

```
first-flet-app/
├── src/                          # 源代码目录
│   ├── main.py                   # 主应用入口
│   ├── components/               # UI 组件模块
│   │   ├── file_manager.py       # 文件管理器
│   │   ├── command_builder.py    # 命令构建器
│   │   ├── executor.py           # 命令执行器
│   │   └── output_viewer.py      # 输出查看器
│   ├── models/                   # 数据模型
│   │   ├── conversion_types.py   # 转换类型定义
│   │   └── parameters.py         # 参数定义
│   └── utils/                    # 工具函数
│       ├── color_utils.py        # 颜色工具
│       ├── validators.py         # 验证器
│       ├── icon_utils.py         # 图标工具
│       └── helpers.py            # 辅助函数
├── test/                         # 测试目录
│   ├── unit/                     # 单元测试
│   ├── integration/              # 集成测试
│   ├── ui/                       # UI测试
│   ├── tools/                    # 工具测试
│   └── run_tests.py              # 测试运行器
├── gsbox/                        # gsbox 工具目录
├── storage/                      # 存储目录
├── output/                       # 输出目录
├── requirements.txt              # Python 依赖
├── pyproject.toml               # 项目配置
└── main.spec                    # PyInstaller 打包配置
```

## 🎯 支持的转换类型

### PLY 格式转换
- PLY ↔ SPLAT、SPX、SPZ、SOG
- PLY → PLY (过滤/变换)

### SPLAT 格式转换
- SPLAT ↔ PLY、SPX、SPZ、SOG

### SPX 格式转换
- SPX ↔ PLY、SPLAT、SPZ、SOG

### SPZ 格式转换
- SPZ ↔ PLY、SPLAT、SPX、SOG

### KSPLAT 格式转换
- KSPLAT ↔ PLY、SPLAT、SPX、SPZ、SOG

### SOG 格式转换
- SOG ↔ PLY、SPLAT、SPX、SPZ

### 其他操作
- **printsplat**: 打印 SPLAT 数据到文本文件
- **join**: 合并多个模型文件
- **info**: 查看模型文件详细信息

## ⚙️ 转换参数

### 质量参数
- **quality**: 转换质量 (0-100)
- **comment**: 注释信息
- **output_version**: 输出版本

### SPX/SPZ/SOG 专用参数
- **compression_type**: 压缩类型配置
  - **gzip**: 使用 GZIP 压缩（参数值: 0）
  - **xz**: 使用 XZ 压缩（参数值: 1）
  - 对应 gsbox 参数: `-ct <value>`
- **alpha**: Alpha 通道值 (0-255)，对应 `-a <value>`
- **sh_degree**: 球谐函数阶数 (0-3)，对应 `-sh <value>`
- **block_size**: 块大小，默认 65536，对应 `-bs <value>`
- **block_format**: 块格式 (22, 220)，对应 `-bf <value>`

### 变换参数（可选）
- **transform_order**: 变换顺序 (RST, RTS, SRT, STR, TRS, TSR)
- **rotate_x/y/z**: 坐标轴旋转角度 (度)
- **scale**: 缩放因子
- **translate_x/y/z**: 坐标轴平移距离

### K-means 参数（可选）
- **kmeans_iterations**: K-means 迭代次数 (5-50)
- **kmeans_nearest_nodes**: 最近节点数 (10-200)

## 🧪 测试

项目包含完整的测试套件，覆盖单元测试、集成测试、UI 测试和工具测试。

### 运行所有测试
```bash
python test/run_tests.py
```

### 运行特定类型测试
```bash
python test/run_tests.py unit          # 单元测试
python test/run_tests.py integration   # 集成测试
python test/run_tests.py ui            # UI测试
python test/run_tests.py tools         # 工具测试
```

详细测试文档请参考 [测试指南](test/TESTING_GUIDE.md)。

## 📦 打包和分发

### 创建可执行文件
```bash
python build.py --single-exe
```

### 打包注意事项
- 确保包含所有必要的资源文件
- 配置正确的图标和元数据
- 测试打包后的应用程序

## 🔧 开发指南

### 代码风格
- 遵循 PEP 8 Python 编码规范
- 使用类型提示
- 添加适当的文档字符串

### 添加新功能
1. 在相应的模块中实现功能
2. 添加必要的测试用例
3. 更新文档和 README
4. 验证所有测试通过

### 调试技巧
- 使用 `test/tools/` 目录下的调试工具
- 查看详细的日志输出
- 使用断点和调试器

## 🐛 常见问题

### Q: 应用程序无法启动？
A: 检查 Python 版本是否符合要求，确保所有依赖项已正确安装。

### Q: 转换失败？
A: 验证输入文件格式是否正确，检查 gsbox 是否已正确安装，查看详细错误日志。

### Q: 界面显示异常？
A: 尝试更新显卡驱动，检查系统 DPI 设置，确保 Flet 版本兼容。

### Q: 如何处理大文件？
A: 确保有足够的磁盘空间，考虑分批处理，监控系统资源使用情况。

## 🤝 贡献指南

1. Fork 项目
2. 创建功能分支 (`git checkout -b feature/amazing-feature`)
3. 提交更改 (`git commit -m 'Add some amazing feature'`)
4. 推送到分支 (`git push origin feature/amazing-feature`)
5. 创建 Pull Request

## 📄 许可证

### 项目许可证
本项目采用 **GNU General Public License v3.0 (GPL-3.0)** 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

### 第三方依赖许可证
- **gsbox**：3D 高斯点云处理工具，采用 GPL-3.0 许可证
- **Flet**：现代化 UI 框架，采用 Apache 2.0 许可证

### 许可证说明
由于本项目集成了 GPL-3.0 许可的 gsbox 插件，根据 GPL-3.0 的传染性原则，本项目整体必须采用 GPL-3.0 许可证。这意味着：
- 任何基于本项目的衍生作品必须同样采用 GPL-3.0 许可证
- 对外分发包含本项目的软件时，必须提供完整的源代码
- 纯个人使用或者非商业性目的（不对外分发）的场景不受此限制

详细的许可证条款请查看 [GNU GPL v3.0 官方文档](https://www.gnu.org/licenses/gpl-3.0.html)。

## 👥 联系方式

- **作者**: MarcoTin
- **B站**: [https://space.bilibili.com/74228375](https://space.bilibili.com/74228375)
- **项目地址**: [项目GitHub地址](https://gitee.com/playertk/3dgsconvert-tool)

## 🙏 致谢

- 感谢 [gsbox](https://github.com/gotoeasy/gsbox) 开发团队提供的优秀 3D 高斯点云处理工具
- 感谢 [Flet](https://github.com/flet-dev/flet) 框架提供的现代化 UI 解决方案
- 感谢所有贡献者和测试者的支持

---

**⭐ 如果这个项目对你有帮助，请给个 Star 支持一下！**