EarthGlobeSystem 🌐 3D交互式地球仪系统

📖 概述

EarthGlobeSystem 是一个跨平台的3D地球仪可视化框架，专为地理信息系统、机器人导航、军事仿真和教育应用设计。系统采用模块化架构，核心组件包括：

✨ 核心特性

• 真实地球渲染 — 高分辨率纹理贴图、法线映射、动态光照(Phong模型)。
• 交互式相机控制 — 球面坐标相机系统，支持平滑旋转/缩放/复位。
• 地理坐标系统 — 经纬度与3D坐标精确转换，支持大圆距离计算。
• 标记管理 — 彩色标记点，支持半径搜索、名称查找、JSON导入导出。
• 机器人仿真接口 — 多线程命令队列，状态回调，电池消耗模拟。
• TCP远程控制 — 内置RobotServer，支持Python/其他语言客户端。
• 可视化辅助 — 经纬线网格、线框模式、鼠标点击添加标记。
• 跨平台支持 — Linux/Windows/macOS，依赖库通过CMake自动查找。

⚡ 快速开始

最简单的运行方式：

# 克隆仓库
git clone https://github.com/example/EarthGlobeSystem.git
cd EarthGlobeSystem

# 创建构建目录
mkdir build && cd build

# 配置并编译
cmake .. -DCMAKE_BUILD_TYPE=Release
make -j4

# 运行程序 (确保纹理文件在正确位置)
./EarthGlobeSystem

📦 编译与依赖

Ubuntu/Debian 依赖安装

sudo apt update
sudo apt install build-essential cmake git \
    libglfw3-dev libglew-dev libopengl-dev \
    libopencv-dev libglm-dev nlohmann-json3-dev

CMake 配置选项

🏗️ 系统架构

系统采用分层架构，各模块职责清晰

🎨 渲染引擎 (GlobeRenderer)

核心渲染类，负责OpenGL初始化、球体网格生成、着色器编译和场景绘制。

初始化GLFW窗口、GLEW、创建球体网格、编译着色器、加载纹理。

每帧调用，清空缓冲区 → 更新投影/视图矩阵 → 渲染地球 → 渲染网格 → 渲染标记点。

修改相机方位角和仰角，实现地球旋转效果。

屏幕坐标转地理坐标(射线-球体相交，当前为简化实现)。

🎮 交互控制 (GlobeController)

封装GLFW回调，提供直观的交互体验。

鼠标控制

• 左键拖拽 — 旋转地球仪
• 右键拖拽 — 缩放视野
• 右键单击 — 添加标记点(通过回调实现)
• 滚轮 — 缩放

键盘快捷键

• W/S — 改变俯仰角
• A/D — 改变方位角
• R — 重置相机视角
• F — 切换线框模式
• G — 切换经纬网格
• ESC — 退出程序

📍 标记管理 (MarkerManager)

提供完整的地理标记生命周期管理。

添加新标记，返回自动生成的ID，同时保存到JSON文件。

按ID删除标记。

获取指定中心点半径范围内的所有标记，使用大圆距离计算。

从 markers.json 加载/保存标记数据。

JSON格式示例：

[
  {
    "id": 1,
    "name": "London",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "altitude": 0,
    "color": [255, 0, 0],
    "description": "Capital of UK"
  }
]

🤖 机器人接口 (RobotInterface)

仿真机器人运动控制与状态管理，支持多线程命令处理。

核心功能

• 运动仿真 — 匀速移动至目标经纬度，速度可配置(默认10°/秒)。
• 电池模拟 — 移动时消耗电量，可查询剩余电量。
• 命令队列 — 异步处理，支持 MOVE_TO_COORDINATE、ADD_MARKER、ROTATE_GLOBE 等。
• 状态回调 — 实时推送位置、移动状态、电池等信息。
• TCP服务器 — RobotServer 类提供远程控制接口(端口8080)。

发送移动命令，机器人开始向目标点移动。

注册状态变化回调，用于UI更新或日志记录。

🧰 工具类 (Utils)

提供地理坐标转换和几何计算。

经纬度转3D笛卡尔坐标(右手坐标系，Y轴向上)。

反向转换，返回经纬度。

计算两点间的大圆距离(单位: 公里)，基于Haversine公式。

数据结构：

• GeoCoordinate — 经纬度+海拔
• Point3D — 3D坐标
• Marker — 标记点聚合数据
• CameraParams — 球面相机参数

📚 API 参考摘要

GlobeRenderer 主要接口

void render();                           // 渲染一帧
void rotate(double deltaAz, double deltaEl); // 旋转相机
void zoom(double factor);                // 缩放
void addMarker(const Marker& marker);    // 添加标记点
void setWireframeMode(bool enabled);     // 线框模式
GeoCoordinate screenToGeo(int x, int y); // 屏幕坐标转地理坐标

MarkerManager 接口

int addMarker(...);
bool removeMarker(int id);
Marker* getMarker(int id);
std::vector<Marker> getMarkersInRange(const GeoCoordinate& center, double radiusKm);
bool saveToFile();

RobotInterface 接口

bool start();                            // 启动工作线程
void stop();                             // 停止
void moveToCoordinate(const GeoCoordinate& coord);
RobotStatus getStatus() const;
void setStatusCallback(std::function<void(const RobotStatus&)> callback);

💡 使用示例

1. 添加自定义标记

MarkerManager manager;
int id = manager.addMarker("Eiffel Tower", GeoCoordinate(48.8584, 2.2945), 
                            cv::Scalar(255, 255, 0), "Paris landmark");
renderer.addMarker(*manager.getMarker(id));

2. 控制机器人移动并监听状态

RobotInterface robot;
robot.start();
robot.setStatusCallback([](const RobotStatus& s) {
    std::cout << "Position: " << s.currentPosition.latitude 
              << ", " << s.currentPosition.longitude << std::endl;
});
robot.moveToCoordinate(GeoCoordinate(34.0522, -118.2437)); // 洛杉矶

3. Python远程控制

from robot_client import RobotClient
client = RobotClient()
client.connect()
client.move_to(35.6895, 139.6917)  # 东京
status = client.get_status()
print(status)
client.close()

⚙️ 配置文件

markers.json — 标记点数据，自动保存/加载，位于可执行目录。

earth_texture.jpg — 地球纹理图片，建议分辨率4096x2048或更高。

运行时参数 (可在代码中修改):

• 窗口尺寸: GlobeRenderer(1280, 720)
• 相机初始距离: CameraParams(3.0, 0, 30, 45)
• 机器人移动速度: RobotInterface(10.0, 30.0) (度/秒, 仿真频率Hz)
• TCP服务器端口: RobotServer(8080)

🔧 故障排除

⚖️ 许可证