# time_vault

**Repository Path**: JanuaryJIAN/time_vault

## Basic Information

- **Project Name**: time_vault
- **Description**: 提取旅途的点点滴滴，汇成时间的宝库
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-04-19
- **Last Updated**: 2026-05-05

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 🕰️ TimeShadow 时光剪影

> AI 驱动的个人时光记忆生成系统 — 自动整理照片，生成交互式地图 & 游记

## 快速开始

### 安装

```bash
git clone <repo-url> && cd time_vault
python -m venv venv && source venv/bin/activate
pip install -e .          # 核心功能
pip install -e ".[full]"  # 全部可选依赖（VLM/视频/HEIC等）
```

### 使用

```bash
# 🖥️ 交互控制台（推荐新手）
timeshadow console

# 🚀 命令行一键运行
timeshadow run ./my_photos -o ./output --auto --zip

# 📝 人工审核模式
timeshadow review --input ./my_photos

# ⚙️ 配置管理
timeshadow config show
```

### 命令一览

| 命令 | 说明 |
|------|------|
| `timeshadow console` | 启动 Gradio 交互控制台（选图+配置+运行） |
| `timeshadow run <input>` | 运行完整流水线 |
| `timeshadow review` | 启动人工审核界面 |
| `timeshadow config` | 查看/修改配置 |

### 常用选项

```bash
timeshadow run ./photos \
  --output ./result \          # 输出目录
  --auto \                     # 全自动（跳过审核）
  --vlm \                      # 启用 VLM 画面描述
  --diary-style poetic \       # 游记风格：formal/casual/poetic/xiaohongshu
  --zip                        # 输出 ZIP 包
```

## 项目结构

```
time_vault/
├── timeshadow_pkg/          # 核心包
│   ├── __main__.py          # CLI 入口
│   ├── config/              # 配置管理
│   ├── ingestion/           # 图片扫描 & EXIF 提取
│   ├── quality/             # 质量评分（NIMA/清晰度/审美）
│   ├── spatio/              # 时空聚类
│   ├── geocoding/           # 逆地理编码（高德/Nominatim/离线）
│   ├── vlm/                 # VLM 画面描述
│   ├── diary/               # 游记生成
│   ├── presentation/        # HTML 地图 & 打包
│   └── ui/                  # Gradio 控制台 & 审核界面
├── scripts/                 # 辅助脚本
│   ├── demo/                # 演示脚本
│   └── testing/             # 测试数据收集
├── tests/                   # 单元测试
├── pyproject.toml           # 构建配置
└── CHANGELOG.md             # 变更记录
```

## 流水线流程

```
照片目录 → 扫描&EXIF提取 → 质量评分 → 时空聚类 → 逆地理编码
        → [VLM描述] → 游记生成 → HTML地图 → ZIP打包
```

## 可选依赖

| 分组 | 包 | 功能 |
|------|-----|------|
| `[vlm]` | openai | VLM 画面描述 |
| `[video]` | ffmpeg-python, pyscenedetect | 视频抽帧 |
| `[nima]` | torch, transformers | NIMA 审美评分 |
| `[heic]` | pillow-heif | HEIC 格式支持 |
| `[maps]` | folium, geopy | 交互式地图 |
| `[gpx]` | gpxpy | GPX 轨迹解析 |
| `[full]` | 以上全部 | 一键安装 |

## 版本

当前版本 **v1.4.1** — 详见 [CHANGELOG.md](CHANGELOG.md)