# go-3dtiles

**Repository Path**: iluim/go-3dtiles

## Basic Information

- **Project Name**: go-3dtiles
- **Description**: No description available
- **Primary Language**: Go
- **License**: Not specified
- **Default Branch**: develop-v0.2.0
- **Homepage**: None
- **GVP Project**: No

## Statistics

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

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# Go 3DTiles

[![Go Version](https://img.shields.io/badge/Go-1.24+-00ADD8?style=flat&logo=go)](https://go.dev/)
[![License](https://img.shields.io/badge/License-Proprietary-red.svg)](LICENSE)
[![Platform](https://img.shields.io/badge/Platform-Linux%20%7C%20macOS%20%7C%20Windows-lightgrey)](https://github.com/jiaoyigui/3dtile)

**高性能 3D Tiles 转换工具** - 支持 11 种格式

---

## 🚀 快速开始

### 安装

```bash
# 下载预编译二进制
wget https://github.com/jiaoyigui/3dtile/releases/download/v1.0.0/3dtile-linux-amd64.tar.gz
tar -xzf 3dtile-linux-amd64.tar.gz
sudo mv 3dtile /usr/local/bin/

# 或从源码编译
git clone https://github.com/jiaoyigui/3dtile.git
cd 3dtile
./build.sh
```

### 基本使用

```bash
# 转换单个文件
3dtile convert -f obj -i building.obj -o output/ --progress

# 批量转换
3dtile batch convert -i "*.obj" -o output/ -f obj --workers 8

# Web 预览
3dtile serve output/ --port 3000
```

---

## 📊 支持格式

| 格式 | 扩展名 | 状态 | 说明 |
|------|--------|------|------|
| **Shapefile** | .shp | ✅ | 纯 Go |
| **GeoJSON** | .geojson | ✅ | 纯 Go |
| **KML/KMZ** | .kml, .kmz | ✅ | 纯 Go |
| **OBJ** | .obj | ✅ | 纯 Go |
| **STL** | .stl | ✅ | 纯 Go |
| **PLY** | .ply | ✅ | 纯 Go |
| **DAE** | .dae | ✅ | 纯 Go |
| **GEM/GOM/GTM** | .gem, .gom, .gtm | ✅ | 纯 Go |
| **glTF/GLB** | .gltf, .glb | ✅ | 纯 Go (转换为 GLB) |
| **B3DM** | .b3dm | ✅ | 纯 Go (B3DM ↔ GLB) |
| **OSGB** | .osgb | ⚠️ | CGO + OpenSceneGraph |
| **FBX** | .fbx | ⚠️ | CGO + FBX SDK |

---

## 🎯 核心功能

### 1. 高程处理

```bash
# 自动加载 DEM/DSM
3dtile convert -f geojson -i buildings.geojson -o output/

# 输出包含:
# - buildings.geojson (带高度信息)
# - tileset.json (3D Tiles)
```

**支持数据源**:
- ✅ GeoTIFF (.tif)
- ✅ SRTM HGT (.hgt)
- ✅ ASCII Grid (.asc)

**建筑高度计算**:
```
建筑高度 = DSM(地表) - DEM(地面)
楼层数 = 建筑高度 / 层高 (2.8-3.5m)
```

### 2. 批量处理

```bash
# 并发批量转换
3dtile batch convert \
  -i "./input/*.obj" \
  -o ./output/ \
  -f obj \
  --workers 8 \
  --progress \
  --stats

# 使用配置文件
3dtile batch convert \
  -i "*.obj" \
  -o output/ \
  -f obj \
  --config config.yaml
```

### 3. 进度显示

```
🚀 Starting conversion...
   Format: obj
   Input: building.obj
   Output: output/

🔺 Converting OBJ to 3D Tiles...
   Input: building.obj
   Output: output/
✅ OBJ conversion completed

✅ Conversion completed successfully!
```

---

## ⚙️ 配置示例

### config.yaml

```yaml
# 性能配置
performance:
  workers: 8              # 0=自动检测 CPU 核心
  memory_limit: 8192      # 8GB
  batch_size: 5000
  enable_cache: true
  cache_size: 2048        # 2GB

# 高程配置
elevation:
  dem_files: ./data/dem/*.tif
  dsm_files: ./data/dsm/*.tif
  interpolation: bilinear  # nearest, bilinear, bicubic

# 建筑配置
building:
  min_height: 2.5         # 最小高度 (米)
  max_height: 500.0       # 最大高度 (米)
  default_floor_height: 3.0
  max_floors: 150
  types:
    residential: { floor_height: 2.8, min_area: 0, max_area: 1000 }
    commercial: { floor_height: 3.5, min_area: 10000, max_area: 999999 }
    office: { floor_height: 3.2, min_area: 1000, max_area: 10000 }

# 瓦片集配置
tileset:
  root_geometric_error: 240.0
  refine_type: ADD
  max_level: 20
  enable_lod: true

# 日志配置
logging:
  level: info
  format: text           # text, json
  file: ./logs/3dtiles.log
  rotation:
    enabled: true
    max_size: 100        # MB
    max_backups: 5
    max_age: 30          # 天

# 质量检查
quality:
  enabled: true
  checks: [height_range, floor_count, coordinate_validity]
  auto_fix: true
  report_format: json
```

### 使用配置

```bash
# 使用配置文件
3dtile convert -f obj -i model.obj -o output/ \
  --config config.yaml

# CLI 参数覆盖配置
3dtile batch convert -i "*.obj" -o output/ -f obj \
  --config config.yaml \
  --workers 16  # 覆盖配置文件中的 workers
```

---

## 📈 性能基准

### 转换速度

| 规模 | 瓦片数 | 时间 | 速度 |
|------|--------|------|------|
| 小区 | 100 | 3s | 2000 瓦片/min |
| 社区 | 1,000 | 15s | 4000 瓦片/min |
| 城市 | 10,000 | 120s | 5000 瓦片/min |

**测试环境**: Intel Xeon E5-2680 v4 (14 核), 64GB RAM, NVMe SSD

### 资源消耗

| 场景 | 内存 | CPU | 磁盘 IO |
|------|------|-----|---------|
| 小区 | 500MB | 30% | 20MB/s |
| 社区 | 1GB | 50% | 50MB/s |
| 城市 | 4GB | 80% | 100MB/s |

---

## 🔧 编译选项

### CGO 模式 (完整功能)

```bash
# 需要 OpenSceneGraph
CGO_ENABLED=1 go build -tags 'cgo use_osg' -o 3dtile ./cmd/3dtile

# 或使用构建脚本
./build.sh
```

### 纯 Go 模式 (无 OSGB/FBX)

```bash
CGO_ENABLED=0 go build -o 3dtile ./cmd/3dtile

# 或使用构建脚本
./build.sh --no-cgo
```

---

## 📚 CLI 命令

### convert - 单个转换

```bash
3dtile convert -f <FORMAT> -i <INPUT> -o <OUTPUT> [选项]

# 选项:
--enable-lod           启用 LOD
--enable-simplify      启用网格简化
--progress             显示进度
--stats                显示统计
--config <FILE>        配置文件
```

### batch - 批量转换

```bash
3dtile batch convert -i <PATTERN> -o <OUTPUT> -f <FORMAT> [选项]

# 选项:
--workers <N>          并发 worker 数量 (默认 4)
--skip-errors          跳过错误继续
--progress             显示进度
--stats                显示统计
```

### serve - Web 预览

```bash
3dtile serve <DIRECTORY> [选项]

# 选项:
--port <PORT>          监听端口 (默认 3000)
--host <HOST>          监听地址 (默认 0.0.0.0)
```

---

## 🐛 故障排除

### 问题：内存不足

```bash
# 限制内存使用
3dtile convert -f obj -i model.obj -o output/ \
  --config <(echo "performance:\n  memory_limit: 4096")
```

### 问题：转换速度慢

```bash
# 增加并发
3dtile batch convert -i "*.obj" -o output/ -f obj --workers 16
```

### 问题：CGO 编译失败

```bash
# 使用纯 Go 模式
./build.sh --no-cgo

# 或安装 OpenSceneGraph
sudo apt-get install libopenscenegraph-dev
```

---

## 📞 支持

- **项目地址**: https://github.com/jiaoyigui/3dtile
- **Issue 反馈**: https://github.com/jiaoyigui/3dtile/issues

---

## 📄 许可证

专有许可证 - 禁止商业用途和二次销售

详见 [LICENSE](LICENSE) 文件。

**主要限制**:
- ❌ 禁止商业用途
- ❌ 禁止二次销售
- ❌ 禁止分发给第三方
- ✅ 允许个人学习和研究
- ✅ 允许企业内部使用
- ✅ 允许修改源码满足自身需求

如需商业授权，请联系版权所有者。

---

**版本**: v1.0.0
**最后更新**: 2026-03-27
**维护者**: jiaoyigui