Initial commit: GasFlux project with core processing pipelines
This commit is contained in:
253
3DVIEW_README.md
Normal file
253
3DVIEW_README.md
Normal file
@ -0,0 +1,253 @@
|
||||
# 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月
|
||||
Reference in New Issue
Block a user