SwingLab Android is a public-safe repository for a native Android golf swing sensor product. It combines WT901 BLE ingestion, automatic calibration, swing-phase detection, club-speed estimation, trajectory visualization, and optional structured AI coaching.
| Item | Summary |
|---|---|
| Product form | Native Android app with BLE IMU integration |
| Sensor path | WT901-series IMU over BLE |
| Core functions | Calibration, swing segmentation, speed estimation, trajectory, history, AI summary |
| Supporting modules | Python reference algorithms and desktop visualization tools |
| Boundary | Sensor-derived estimates do not replace radar, high-speed cameras, or coaches |
SwingLab 是一个面向高尔夫训练的原生 Android 挥杆传感器应用。它通过 BLE 连接 WT901 系列 IMU，完成自动校准、有效挥杆识别、杆头速度估算、三维轨迹、速度时序、 历史记录、球员档案和按需 AI 训练建议。
当前仓库用于产品研发与技术交流。杆头速度、Carry、总距离和 AI 建议属于传感器数据 与模型推断结果，不能替代雷达、高速相机或专业教练结论。
- WT901 BLE 扫描、连接、通知订阅和自动重连
- 200 Hz 时间轴整理与 IMU 协议解析
- 重新安装传感器后的自动校准
- 自动识别上杆、下杆、击球和收杆阶段
- 杆头速度、Carry、总距离与释放时机估算
- 三阶段彩色轨迹与峰值校准速度曲线
- 多球员档案、历史记录、单杆详情和左右翻页
- 最近十杆的按需 AI 分析与严格结构化输出
- Android 与 Python 参考算法的回归测试
swinglab_android_app/ 原生 Android App（Java）
swinglab_ui/ 电脑端实时产品界面（React / Three.js）
wt9011dcl/ 电脑端 BLE、轨迹、速度和距离参考算法
swing_analysis/ 离线挥杆分析模块
tests/ 可公开运行的 Python 单元测试
examples/calibration/ 已脱敏的校准样本
docs/ 架构、状态与安全说明
imu_recorder.py macOS BLE 采集工具
swing_analyzer.py CSV 离线分析入口
live_swinglab.py 电脑端实时服务入口
live_trajectory.py 电脑端轨迹与算法调试入口
要求：Android Studio、JDK 17、Android SDK 36。
cd swinglab_android_app
cp local.properties.example local.properties编辑本机的 local.properties：
sdk.dir=/path/to/Android/sdk
YUNWU_API_KEY=不使用在线 AI 时，YUNWU_API_KEY 保持为空即可。随后运行：
./gradlew testDebugUnitTest assembleDebugDebug APK 位于：
swinglab_android_app/app/build/outputs/apk/debug/app-debug.apk
python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt
.venv/bin/python -m unittest discover -s tests -v扫描 WT901 BLE：
.venv/bin/python imu_recorder.py scan分析一份自行采集的 CSV：
.venv/bin/python swing_analyzer.py recordings/your_swing.csv电脑端实时产品界面：
cd swinglab_ui
npm ci
npm run build
cd ..
.venv/bin/python live_swinglab.py真实挥杆 CSV、App 历史、日志和设备标识不会提交到仓库。
测试构建支持从本机 local.properties 读取 OpenAI 兼容接口 Key；该文件已被 Git 忽略。
任何正式发布版本都应改为：
Android App → 自有 HTTPS 服务 → 模型供应商
不要把生产 API Key 写入 APK，也不要提交任何真实 Key。详见 SECURITY.md。
- 单个杆身 IMU直接观测的是加速度、角速度、姿态和时间序列。
- 杆头速度是经过校准的估算值。
- Carry 与总距离是基于球杆模型的推断值。
- 轨迹在传感器饱和、安装松动或校准失效时可能受限。
- AI 教练只使用结构化挥杆摘要，不应输出医疗诊断或保证性成绩预测。
Copyright © 2026 SwingLab. All rights reserved. 当前未授予复制、分发或商业使用许可。