Tennis Stroke Analysis System: Technical Documentation

1. 项目概览 (Project Overview)

本项目旨在针对长时间网球比赛监控数据，构建一套自动化的击球动作识别与可视化系统。系统通过解析 YOLO 轨迹日志，利用深度学习模型（LSTM）精准定位击球瞬间，并生成带有可视化轨迹和状态标记的复盘视频。

核心能力

• 高精度清洗：自动修复原始日志中的丢帧（Frame Drops）问题，还原真实物理轨迹。
• 智能识别：基于 LSTM 的时序分类模型，能够在毫秒级内识别击球动作。
• 可视化复盘：生成带有轨迹拖尾、击球高亮、数据面板的 1080P 复盘视频。

---

2. 目录结构说明 (Directory Structure)

Tennis-Stroke-Analysis-System/
├── a.log/                  # 原始日志源 (A机位)
│   └── a.log
├── b.log/                  # 原始日志源 (B机位)
│   └── b.log
├── models/                 # 模型仓库
│   └── stage1_coord_model_continuous.pth  # 训练好的 LSTM 权重
├── output/                 # 数据产出目录
│   ├── full_replay_demo.mp4    # 最终生成的复盘视频
│   ├── parsed_a.csv            # A机位清洗后的全量数据
│   ├── parsed_b.csv            # B机位清洗后的全量数据
│   └── training_segment.csv    # 用于训练的标注数据集
├── README/                 # 模块说明文档
│   ├── 1_parse_logs.md
│   ├── 2_prepare_data.md
│   ├── 3_trajectory_labeler.md
│   ├── 4_train_stage1.md
│   └── 5_full_replay.md
├── 1_parse_logs.py         # [ETL] 日志解析器
├── 2_prepare_data.py       # [ETL] 训练数据截取与预处理
├── 3_trajectory_labeler.py # [Tool] 交互式打标工具
├── 4_train_stage1.py       # [Train] 模型训练器
├── 5_full_replay.py        # [Infer] 视频生成器
├── left.jpg                # A机位背景图 (1920x1080)
└── right.jpg               # B机位背景图 (1920x1080)

---

3. 工作流详解 (Workflow)

Phase 1: 数据清洗 (ETL)

• 脚本: 1_parse_logs.py
• 输入: 原始非结构化日志 a.log。
• 逻辑: 使用正则表达式提取 JSON，筛选 is_main: true 的主球数据，按帧号排序去重。
• 输出: 标准化 CSV parsed_a.csv。

Phase 2: 数据集构建 (Data Preparation)

• 脚本: 2_prepare_data.py
• 逻辑:
  1. 从全量 Log 中截取一段连续的比赛数据（如 10 分钟）。
  2. 核心算法 - 插值补全: 检测轨迹中的断点（丢帧），使用线性插值 (Linear Interpolation) 补全缺失坐标，防止模型因坐标瞬移产生误判。
• 输出: 待标注数据集 training_segment.csv。

Phase 3: 人工标注 (Annotation)

• 脚本: 3_trajectory_labeler.py
• 功能: 一个基于 OpenCV 的 GUI 工具。
  • 动态回放: 在静态背景上绘制球的飞行轨迹。
  • 交互操作: 支持 Space 暂停，A/D 逐帧微调，1 键标记击球点。
  • 状态保存: 实时写入 CSV，支持断点续传。
• 产出: 包含 is_hit 和 hit_frame_global 标签的黄金数据集。

Phase 4: 模型训练 (Model Training)

• 脚本: 4_train_stage1.py
• 模型架构: CoordinateLSTM (轻量级)。
  • Input: 11 帧 $(x, y)$ 坐标序列。
  • Backbone: LSTM (Hidden=64, Layer=1)。
  • Heads: 双头输出 (Hit Classification + Frame Regression)。
• 策略:
  • Sliding Window: 对轨迹进行全覆盖切片，生成大量样本。
  • Weighted Sampling: 平衡正负样本比例，解决击球稀疏问题。
• 产出: 权重文件 stage1_coord_model_continuous.pth。

Phase 5: 全量推理与可视化 (Inference & Visualization)

• 脚本: 5_full_replay.py
• 逻辑:
  1. 加载训练好的模型。
  2. 对指定时间段（或全量）数据进行分批推理 (Batch Inference)。
  3. 利用 OpenCV 绘制轨迹视频：
     • 平滑轨迹: 灰色点显示历史路径。
     • 击球高亮: 检测到击球时，球体变红并显示 "HIT!" 警告，持续 0.5 秒。
• 产出: full_replay_demo.mp4。

---

4. 关键技术指标 (Key Metrics)

指标	说明	状态
坐标归一化	所有坐标均归一化至 1280x720 基准分辨率，推理时自动适配图片比例 (Scale 1.5)。	✅
丢帧鲁棒性	通过插值算法，成功解决 YOLO 漏检导致的轨迹断裂问题。	✅
推理速度	采用 Mini-Batch 策略，支持在低显存设备上进行每秒数千帧的高速推理。	✅
标注精度	工具支持逐帧级微调，标注误差控制在 ±1 帧以内。	✅

---

5. 快速启动 (Quick Start)

1. 环境准备: 确保安装 pytorch, pandas, opencv-python, tqdm。
2. 数据解析: 运行 1_parse_logs.py 生成基础数据。
3. 准备训练集: 运行 2_prepare_data.py 截取片段。
4. 开始打标: 运行 3_trajectory_labeler.py 进行人工标注。
5. 训练模型: 运行 4_train_stage1.py 启动训练。
6. 生成视频: 运行 5_full_replay.py 查看最终效果。