# 3D轨迹可视化工具

一个用于将GPS轨迹数据转换为可交互3D可视化的Python工具。

## 功能特性

- 🎯 **多格式支持**: 支持CSV和Excel文件 (.csv, .xlsx, .xls)
- 📊 **3D交互式图表**: 基于Plotly的完全可交互3D可视化
- 🎨 **智能着色**: 按高程自动着色，颜色映射到海拔高度
- 🔧 **灵活配置**: 可自定义列索引、工作表等参数
- 📱 **响应式设计**: 生成的HTML可在任何现代浏览器中查看

## 数据格式要求

### 文件格式
- **CSV文件**: 逗号分隔值文件
- **Excel文件**: .xlsx 或 .xls 格式

### 数据列要求
文件至少需要包含4列数据，按以下顺序排列：

| 列索引 | 列名 | 数据类型 | 说明 |
|--------|------|----------|------|
| 0 | 经度 | 数值 | GPS经度坐标（原始格式） |
| 1 | 纬度 | 数值 | GPS纬度坐标（原始格式） |
| 2 | 高程 | 数值 | 飞行器高程（可选） |
| 3 | 融合高程 | 数值 | 融合后的高程数据 |

### 数据示例

**CSV格式**:
```csv
1157855289,403491370,500110,435.789
1157855290,403491371,500111,436.123
1157855291,403491372,500112,437.456
```

**Excel格式**:
- 第一行（如果有标题）将被忽略
- 数据从第二行开始读取

### 坐标转换
- 经纬度数据会自动除以 10^7 进行单位转换
- 这是因为原始GPS数据通常以放大整数形式存储

## 安装依赖

```bash
pip install pandas plotly openpyxl
```

## 使用方法

### 1. 命令行使用

#### 基本用法
```bash
# 处理CSV文件
python 3Dview.py data.csv

# 处理Excel文件
python 3Dview.py trajectory.xlsx

# 指定输出文件
python 3Dview.py data.csv -o my_visualization.html
```

#### 高级参数
```bash
# 自定义列索引
python 3Dview.py data.xlsx --lon-col 1 --lat-col 2 --alt-col 4

# 指定Excel工作表
python 3Dview.py data.xlsx --sheet-name "Flight_Data"

# 自定义标题
python 3Dview.py data.csv --title "无人机飞行轨迹"

# 组合使用
python 3Dview.py trajectory.xlsx \
    --lon-col 0 \
    --lat-col 1 \
    --alt-col 3 \
    --sheet-name 0 \
    --output flight_path.html \
    --title "2024年飞行数据"
```

### 2. Python代码调用

#### 基本调用
```python
from 3Dview import main

# 处理CSV文件
success = main('trajectory.csv')

# 处理Excel文件
success = main('flight_data.xlsx', sheet_name='Sheet1')
```

#### 完整参数调用
```python
from 3Dview import main

success = main(
    input_file='drone_trajectory.xlsx',
    output_file='visualization.html',
    lon_col=0,          # 经度列索引
    lat_col=1,          # 纬度列索引
    alt_col=3,          # 融合高程列索引
    sheet_name=0,       # Excel工作表索引
    title='无人机轨迹3D可视化'
)

if success:
    print("可视化生成成功！")
```

## 输出结果

### HTML文件内容
- **3D散点图**: 每个数据点在三维空间中的位置
- **颜色编码**: 点的颜色根据高程自动映射
- **交互功能**: 支持旋转、缩放、平移等操作

### 控制说明
- **鼠标左键拖拽**: 旋转视角
- **鼠标滚轮**: 缩放视图
- **鼠标右键拖拽**: 平移视图
- **双击**: 重置到初始视角
- **悬停**: 显示数据点的详细信息

## 参数说明

### 命令行参数

| 参数 | 简称 | 默认值 | 说明 |
|------|------|--------|------|
| `input_file` | - | 必需 | 输入文件路径 |
| `--output` | `-o` | `3d_view.html` | 输出HTML文件路径 |
| `--lon-col` | - | `0` | 经度列索引 |
| `--lat-col` | - | `1` | 纬度列索引 |
| `--alt-col` | - | `3` | 融合高程列索引 |
| `--sheet-name` | - | `0` | Excel工作表名称或索引 |
| `--delimiter` | - | `None` | CSV分隔符（自动检测） |
| `--title` | - | `3D轨迹可视化` | 图表标题 |

### 函数参数

```python
def main(
    input_file,           # 输入文件路径
    output_file='3d_view.html',     # 输出文件路径
    lon_col=0,            # 经度列索引
    lat_col=1,            # 纬度列索引
    alt_col=3,            # 高程列索引
    delimiter=None,       # CSV分隔符
    title='3D轨迹可视化', # 图表标题
    sheet_name=0          # Excel工作表
):
```

## 故障排除

### 常见问题

#### 1. 文件读取错误
```
错误：输入文件不存在: xxx
```
**解决**: 检查文件路径是否正确，文件是否存在

#### 2. 列数不足
```
数据文件至少需要4列，经度、纬度、高程、融合高程。当前只有X列。
```
**解决**: 检查数据文件格式，确保包含所需列

#### 3. Excel工作表不存在
```
Worksheet 'Sheet1' not found
```
**解决**: 检查Excel文件中的工作表名称，或使用索引（如0）

#### 4. 坐标转换问题
如果坐标显示不正确，检查：
- 经纬度数据格式是否正确
- 单位转换是否合适（除以10^7）

### 数据验证

运行脚本时会显示以下统计信息：
```
成功加载数据：XXX 个数据点
经度范围: XXX.XXXXXX - XXX.XXXXXX
纬度范围: XXX.XXXXXX - XXX.XXXXXX
高程范围: XXX.XX - XXX.XX 米
```

## 示例应用

### 无人机飞行轨迹
```python
from 3Dview import main

# 可视化无人机飞行路径
main(
    input_file='drone_flight.xlsx',
    output_file='drone_path_3d.html',
    title='无人机飞行轨迹3D可视化',
    sheet_name='GPS_Data'
)
```

### 地面车辆轨迹
```python
from 3Dview import main

# 可视化车辆行驶轨迹
main(
    input_file='vehicle_gps.csv',
    output_file='vehicle_path.html',
    title='车辆轨迹可视化',
    alt_col=2  # 如果没有高程数据，使用其他列
)
```

## 技术细节

### 依赖库
- **pandas**: 数据处理
- **plotly**: 3D可视化
- **openpyxl**: Excel文件读取

### 坐标系统
- 输入: 原始GPS坐标（通常为度×10^-7）
- 处理: 转换为标准经纬度坐标
- 显示: WGS84地理坐标系

### 性能考虑
- 大文件处理: 建议分批处理超大数据集
- 内存使用: 每个数据点占用约50-100字节内存
- 渲染性能: 浏览器对大量数据点的渲染有限制

## 许可证

本工具遵循与主项目相同的许可证。

---

**版本**: 1.0.0
**最后更新**: 2024年12月