Earth Exploration Diary 项目 README

Earth Exploration Diary

一个创新的交互式足迹相册应用，结合了3D地球可视化、手势识别和多媒体管理技术，为用户提供全新的旅行记录与回忆整理方式。

📋 项目简介

Earth Exploration Diary 旨在通过3D地球界面让用户的旅行足迹变得直观可见。用户可以通过自然的手势操作在虚拟地球上浏览不同国家的相册，上传照片和文字记录，创建属于自己的个人旅行地图。

✨ 核心功能

🌍 3D地球交互界面

• 基于PyVista的实时3D地球渲染
• 支持流畅的旋转和缩放操作
• 高精度的国家边界显示
• 沉浸式的视觉体验

👋 智能手势控制

• 张开手掌：实现地球的左右滑动旋转
• 伸出食指：精准选择目标国家
• 准星停留机制：停留450ms自动触发国家选择
• 实时状态反馈：显示当前手势识别状态

📸 多媒体相册管理

• 支持照片上传，自动提取EXIF元数据
• 支持纯文字记录上传
• 手动输入拍摄时间功能
• 按地理位置自动分类整理
• 最近上传记录快速访问

🔄 多模式操作

• 图文模式：上传照片和文案
• 总结模式：记录旅行随笔
• 查看模式：浏览相册内容

🛠️ 技术栈

前端

• 框架：React + TypeScript
• 构建工具：Vite
• 手势识别：MediaPipe Hands
• 实时通信：WebSocket

后端

• Web框架：FastAPI
• ORM：SQLModel
• 数据库：SQLite
• 3D可视化：PyVista
• 图像处理：Pillow + EXIF读取

🚀 快速开始

环境要求

• Python 3.10+
• Node.js 18+
• npm 9+

安装步骤

1. 克隆仓库

git clone https://github.com/Maoxinyi237/Earth-Exploration-Diary.git
cd Earth-Exploration-Diary

2. 安装后端依赖

# 创建并激活虚拟环境（可选）
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate

# 安装依赖
pip install -r FootprintAlbum/requirements.txt

3. 安装前端依赖

cd FootprintAlbum/frontend
npm install

运行项目

1. 启动后端服务器

# 在 FootprintAlbum 目录下
uvicorn app:app --reload

后端服务将在 http://127.0.0.1:8000 运行

2. 启动前端开发服务器

# 在 FootprintAlbum/frontend 目录下
npm run dev

前端服务将在 http://localhost:5173 运行

构建生产版本

# 在 FootprintAlbum/frontend 目录下
npm run build

构建产物将生成在 dist 目录

📁 项目结构

Earth-Exploration-Diary/
├── FootprintAlbum/              # 主项目目录
│   ├── data/                    # 数据目录
│   │   ├── albums/              # 相册文件存储
│   │   └── ne_110m_admin_0_countries.*  # 国家边界地理数据
│   ├── frontend/                # 前端代码
│   │   ├── public/              # 静态资源
│   │   ├── src/                 # 源代码
│   │   │   ├── components/      # 组件
│   │   │   │   ├── AlbumModal.tsx    # 相册弹窗
│   │   │   │   ├── GlobeStream.tsx   # 地球流
│   │   │   │   └── HandController.tsx # 手势控制器
│   │   │   ├── App.tsx          # 主应用
│   │   │   └── main.tsx         # 入口文件
│   │   ├── package.json         # 前端依赖
│   │   └── vite.config.ts       # Vite配置
│   ├── album_controller.py      # 相册控制器
│   ├── app.py                   # 后端主应用
│   ├── country_picker.py        # 国家选择器
│   ├── db.py                    # 数据库操作
│   ├── exif_utils.py            # EXIF工具
│   ├── globe_engine.py          # 地球引擎
│   ├── models.py                # 数据模型
│   └── requirements.txt         # 后端依赖
└── README.md                    # 项目说明

🎯 使用指南

基本操作

1. 启动应用：打开前端页面 http://localhost:5173
2. 浏览地球：张开手掌，在屏幕上左右移动，控制地球旋转
3. 选择国家：伸出食指，将准星对准目标国家，停留450ms
4. 上传内容：点击左上角的 "Upload photo" 按钮
   • 选择国家（或从地球直接进入）
   • 选择上传模式（图文/总结）
   • 上传照片和/或填写文案
   • 可选择手动输入拍摄时间
   • 点击 "Upload" 完成上传

功能说明

• 图文模式：适合上传带照片的记录，会自动提取照片的拍摄时间和位置信息
• 总结模式：适合纯文字记录，记录旅行随笔或感悟
• 查看模式：浏览已上传的所有内容，按时间倒序排列

🤝 贡献指南

1. Fork 本仓库
2. 创建新分支 (git checkout -b feature/AmazingFeature)
3. 提交更改 (git commit -m 'Add some AmazingFeature')
4. 推送到分支 (git push origin feature/AmazingFeature)
5. 打开 Pull Request

📞 联系方式

• 项目链接：https://github.com/Maoxinyi237/Earth-Exploration-Diary

🎉 致谢

• MediaPipe：提供高精度的手势识别技术
• PyVista：提供强大的3D可视化能力
• FastAPI：高性能的异步Web框架
• React：构建响应式用户界面

🌟 感谢使用 Earth Exploration Diary！希望它能为你的旅行记录增添乐趣和意义。