Sign Language Interpreter

本项目是一个孤立词手语识别原型，围绕 124 点 landmark 数据完成数据分析、时序预处理、几何归一化、S5 手语分类模型、单视频推理链路、Flask API 和静态前端 Demo。

当前主要支持上传单个手语视频，经过 MediaPipe landmark 提取、S2a/S2b 预处理和 S5 ChannelAttn_GRL 模型推理后，返回识别词条、置信度、Top-K 候选和输入质量信息。

文件架构

.
├── api/
│   └── app.py                         # Flask API，提供 /api/health 和 /api/translate
├── data/
│   ├── S1_data_analyse/               # Kaggle ASL landmark 数据分布分析代码、报告和图表
│   ├── S2a_duration/                  # 时序预处理：gap fill、motion trim、重采样到 64 帧
│   ├── S2b_normalization/             # 肩部锚点几何归一化与质量评估
│   ├── asl-signs/                     # 原始 Kaggle ASL 数据集，本地数据，不入库
│   └── selected-signs/                # 筛选后的 80 类 landmark 数据，本地数据，不入库
├── docs/
│   └── course_report/                 # 课程报告、技术报告和可视化插图
├── figure/                            # 汇总分析可视化图片
├── inference/
│   ├── infer_s5_video.py              # 单视频 CLI 推理入口
│   ├── mediapipe_extractor.py         # MediaPipe landmark 提取
│   ├── video_pipeline.py              # 视频到 S5 输入张量的预处理链路
│   └── s5_predictor.py                # S5 checkpoint 加载与预测封装
├── isolated_word_recognition/
│   ├── configs/                       # S5 训练/评估配置
│   ├── src/                           # 模型、训练、评估、数据集与工具代码
│   ├── splits/                        # 固定 train/val/test 划分
│   ├── preprocessing/                 # 归档的 S2b 预处理实现
│   ├── checkpoints/                   # 本地模型权重，不入库
│   └── runs/                          # 本地训练运行产物，不入库
├── ui/
│   ├── index.html                     # 项目首页
│   ├── demo.html                      # 视频上传识别 Demo
│   ├── technology.html                # 技术路线说明页
│   └── INTEGRATION.md                 # 前后端接口说明
├── tests/
│   ├── test_api_translate.py          # API 层测试
│   └── test_s5_predictor.py           # S5 推理封装测试
├── scripts/                           # 辅助分析脚本
├── agent_task/                        # 阶段任务说明
├── agent_report/                      # 阶段执行报告
├── outputs/                           # 推理输出和中间文件，本地生成，不入库
└── .gitignore                         # 忽略数据集、模型、缓存、视频和中间产物

主要工作

1. 数据分布分析

基于 Kaggle ASL landmark 数据，选取 80 个 gloss、21 个 signer、31,724 个样本进行分析。S1 阶段统计了缺失率、gloss/signer 覆盖、帧长分布、类内方差、signer 聚类和 raw feature 重叠情况。

核心结论：

• 手部缺失是结构性问题，左手和右手缺失率明显高于 pose/face。
• 数据集在 gloss 和 signer 覆盖上较均衡。
• signer 风格和空间偏差会影响 landmark 特征空间，是后续建模需要处理的因素。

相关文件：

• data/S1_data_analyse/reports/S1_data_distribution_report.md
• data/S1_data_analyse/src/
• data/S1_data_analyse/figures/

2. 时序预处理

S2a 阶段将不同长度的 landmark 序列统一为固定 64 帧，包含缺口填补、运动片段裁剪、重采样和质量统计。输出用于后续几何归一化和模型训练。

相关文件：

• data/S2a_duration/src/
• data/S2a_duration/configs/S2a_duration.yaml
• data/S2a_duration/figures/

3. 几何归一化

S2b 阶段实现 Robust Shoulder Anchor Normalization。方法使用左右肩点估计序列级 shoulder center 和 shoulder width，对有效 landmark 进行平移和尺度归一化，并保留无效点 mask。

阶段结果显示，归一化削弱了 signer 空间结构，同时提升了 gloss 的局部邻近关系，但 signer 信息仍然存在。

相关文件：

• data/S2b_normalization/reports/S2b_normalization_report.md
• data/S2b_normalization/src/
• data/S2b_normalization/figures/

4. 孤立词识别模型

isolated_word_recognition/ 保存 S5 ChannelAttn_GRL 模型及最小训练/评估代码。模型用于 80 类孤立词分类，并引入 signer adversarial 分支以削弱 signer 相关信息。

相关文件：

• isolated_word_recognition/src/models.py
• isolated_word_recognition/src/train.py
• isolated_word_recognition/src/evaluate.py
• isolated_word_recognition/configs/s5_channel_attn_grl.yaml

5. 单视频推理链路

inference/ 提供从视频到 JSON 结果的端到端 CLI：

视频 -> MediaPipe 124 点提取 -> S2a 时序预处理 -> S2b 几何归一化 -> S5 模型推理 -> JSON

入口文件：

• inference/infer_s5_video.py
• inference/video_pipeline.py
• inference/s5_predictor.py

6. Web API 与前端 Demo

api/app.py 提供 Flask API：

• GET /api/health：健康检查
• POST /api/translate：接收视频文件，调用真实推理链路，返回识别结果

ui/ 提供静态前端页面，其中 demo.html 已接入真实后端接口，可上传视频并展示识别结果、Top-K 候选、延迟和质量信息。

相关说明：

• ui/INTEGRATION.md
• agent_report/V2_api_integration_report.md

7. WLASL300 探索

项目还记录了 WLASL300 下载、预处理和 MediaPipe landmark 提取实验。由于 YouTube 反爬和大量源链接失效，WLASL300 当前主要作为探索记录，不是主推理链路的默认数据源。

相关报告：

• agent_report/WLASL300_download_report.md
• agent_report/WLASL300_mediapipe_raw_report.md

快速开始

建议使用已有 conda 环境：

source /home/lyx/miniconda3/etc/profile.d/conda.sh
conda activate SL_interuption

启动后端 API

python3 api/app.py

默认服务：

http://localhost:8000

健康检查：

curl http://localhost:8000/api/health

启动前端页面

python3 -m http.server 5173 -d ui

访问：

http://localhost:5173/index.html
http://localhost:5173/demo.html
http://localhost:5173/technology.html

CLI 推理

python3 inference/infer_s5_video.py \
  --video path/to/sign_language.mp4 \
  --device cpu \
  --top-k 5

默认 checkpoint：

isolated_word_recognition/checkpoints/S5_channel_attn_grl_best.pth

默认配置：

isolated_word_recognition/configs/s5_channel_attn_grl.yaml

数据与版本管理

仓库保留代码、配置、报告和分析可视化图片；不上传原始数据集、处理后样本、模型权重、训练运行目录、推理输出、视频和缓存。

保留上传的内容包括：

• data/**/reports/*.md
• data/**/src/*.py
• data/**/configs/*.yaml
• data/**/figures/**/*.png
• figure/**/*.png
• docs/course_report/figures/**/*.png

本地生成且不入库的内容包括：

• data/asl-signs/
• data/selected-signs/
• data/**/processed/
• data/**/tables/
• isolated_word_recognition/checkpoints/
• isolated_word_recognition/runs/
• outputs/
• *.npz, *.npy, *.parquet, *.pth, *.pt, *.mp4, *.webm

注意：如果某些大文件已经被 Git 跟踪，.gitignore 不会自动取消跟踪，需要另外用 git rm --cached 处理。

测试

API 层测试：

python3 -m pytest tests/test_api_translate.py -v --override-ini="addopts="

S5 推理封装测试：

python3 -m pytest tests/test_s5_predictor.py -v --override-ini="addopts="

已知限制

• 当前推理默认面向 80 类孤立词，不是连续句子级手语翻译。
• API 支持上传视频文件，不支持实时摄像头流式识别。
• MediaPipe 提取质量受视频角度、光照、遮挡和分辨率影响。
• S5 checkpoint 是本地大文件，默认不提交到 Git。
• outputs/ 中的推理中间文件和结果是运行时产物，默认不入库。

重要报告

• data/S1_data_analyse/reports/S1_data_distribution_report.md
• data/S2b_normalization/reports/S2b_normalization_report.md
• inference/README.md
• isolated_word_recognition/README.md
• ui/INTEGRATION.md
• docs/course_report/sign_language_interpreter_course_report.md
• agent_report/V2_api_integration_report.md