169 lines
7.3 KiB
Plaintext
169 lines
7.3 KiB
Plaintext
================================================================
|
||
OpenDance Studio —— Windows 客户端 v0.1.0 使用说明
|
||
================================================================
|
||
|
||
摄像头跳舞评分系统的核心体验端：接收 Android 辅助 App 通过 WebSocket
|
||
推送的 33 点骨骼关键点，驱动 VRM 角色，并与 Web 服务端下发的参考动作
|
||
做实时 DTW 评分。
|
||
|
||
本客户端只接收关键点坐标，不接收、不存储任何视频画面。
|
||
|
||
----------------------------------------------------------------
|
||
一、快速开始
|
||
----------------------------------------------------------------
|
||
|
||
1. 解压后得到：
|
||
OpenDance.exe 主程序
|
||
OpenDance.pck 资源包（必须与 exe 同目录）
|
||
README.txt 本文件
|
||
THIRD_PARTY.md 开源声明
|
||
contracts/ 契约快照
|
||
|
||
2. 先启动 Web 管理服务端（opendance-web），确保能访问其 API。
|
||
|
||
3. 双击 OpenDance.exe 启动。
|
||
|
||
4. 在主界面确认「服务端地址」（默认 http://127.0.0.1:3000），
|
||
点击「保存并测试」；顶部应显示「服务端正常 ｜ DB ...」。
|
||
|
||
5. 点击「刷新目录」，左侧会出现已发布的曲目、动作与模型。
|
||
|
||
6. 在 Android 手机上启动「OpenDance 辅助 App」，填入本机显示在
|
||
主界面上的接收地址（形如 ws://192.168.x.x:8765/pose）并连接。
|
||
连接成功后主界面会提示「已连接 N 台设备」。
|
||
|
||
7. 依次选择曲目 → 动作 → 模型，点击「开始跟练」。
|
||
|
||
----------------------------------------------------------------
|
||
二、界面说明
|
||
----------------------------------------------------------------
|
||
|
||
主界面
|
||
- 三栏选择：曲目 / 动作（仅列出已完成预处理的动作）/ 模型（VRM 优先）
|
||
- 服务端地址：可修改并即时测试
|
||
- 接收地址：Android 端要连接的 WebSocket 地址
|
||
- 「刷新目录」重新拉取已发布资源
|
||
- 底部展示所选动作的**来源信息**（来源类型、名称、作者、许可、链接）
|
||
|
||
游戏界面
|
||
- 左侧 3D 视图：VRM 角色跟随关键点实时动作，相机自动框住模型
|
||
- 右侧 HUD：实时得分、等级、连击、动作进度、连接状态、来源信息
|
||
|
||
结算界面
|
||
- 等级（S/A/B/C/D）、平均分与最终分、动作完成度、最高单帧、最长连击
|
||
- 「再来一次」/「返回主菜单」/「开源声明」
|
||
|
||
关于页面
|
||
- 版本与契约版本、隐私说明、完整可滚动的第三方开源项目声明
|
||
|
||
----------------------------------------------------------------
|
||
三、配置文件
|
||
----------------------------------------------------------------
|
||
|
||
首次运行会在以下位置生成配置文件，可直接用文本编辑器修改：
|
||
|
||
Windows: %APPDATA%\Godot\app_userdata\OpenDance Studio\opendance.cfg
|
||
|
||
可配置项：
|
||
|
||
api_base_url Web 服务端地址（默认 http://127.0.0.1:3000）
|
||
listen_host WebSocket 监听地址（默认 0.0.0.0）
|
||
listen_port WebSocket 监听端口（默认 8765）
|
||
ws_subprotocol 子协议（默认 opendance.pose.v1）
|
||
dtw_band DTW 带宽，单位帧（默认 15 ≈ 0.5 秒抖动容忍）
|
||
score_tolerance 评分容差：平均每步代价达到该值即 0 分（默认 0.25）
|
||
mirror_preview 镜像预览
|
||
|
||
----------------------------------------------------------------
|
||
四、防火墙与网络
|
||
----------------------------------------------------------------
|
||
|
||
本客户端需要接受 Android 设备的入站连接：
|
||
|
||
- Windows 防火墙需放行 OpenDance.exe 的 **TCP 8765** 入站
|
||
- 手机与电脑需在同一局域网
|
||
- 手机端填写主界面显示的「接收地址」
|
||
|
||
若端口被占用，可修改 opendance.cfg 中的 listen_port 后重启。
|
||
|
||
----------------------------------------------------------------
|
||
五、评分说明
|
||
----------------------------------------------------------------
|
||
|
||
- 每帧特征 = 33 点 × (x,y,z) + 9 个关节角余弦 = 108 维
|
||
（与 Web 服务端预处理产物、Android 端推流结构完全一致）
|
||
- 置信度低于 0.5 的关键点不参与代价计算，避免遮挡导致误判
|
||
- 采用带约束 DTW（|i−j| ≤ band）对齐，能吸收一定的节奏快慢差异
|
||
- 得分 = clamp(1 − 平均代价 / 容差, 0, 1) × 100，并做指数平滑
|
||
- 等级：S ≥ 95，A ≥ 85，B ≥ 70，C ≥ 55，D 其余
|
||
|
||
----------------------------------------------------------------
|
||
六、从源码构建
|
||
----------------------------------------------------------------
|
||
|
||
前置：Godot 4.7.x + 对应版本的 export templates
|
||
|
||
# Linux 上直接导出 Windows 可执行文件（推荐）
|
||
GODOT_BIN=/path/to/godot bash build/export-windows.sh release
|
||
|
||
# Windows 上兜底导出
|
||
powershell -ExecutionPolicy Bypass -File build\export-windows.ps1
|
||
|
||
产物位于 build/windows/：OpenDance.exe + OpenDance.pck
|
||
（脚本会校验产物存在且为合法 PE 文件）
|
||
|
||
运行测试：
|
||
|
||
GODOT=/path/to/godot
|
||
$GODOT --headless --path . --import
|
||
$GODOT --headless --path . --script res://tests/run_tests.gd
|
||
$GODOT --headless --path . --quit-after 180
|
||
|
||
----------------------------------------------------------------
|
||
七、目录结构
|
||
----------------------------------------------------------------
|
||
|
||
project.godot 工程配置（autoload / 渲染 / 窗口）
|
||
export_presets.cfg 导出预设（必须在项目根目录）
|
||
project.yaml 任务清单与状态
|
||
DSH.md 本项目 DSH 执行约束
|
||
tasks/ 单任务说明书（T-WIN-001 ~ 011）
|
||
contracts/ 只读契约快照（来源 opendance-web v0.1.0）
|
||
scenes/main.tscn 根节点
|
||
src/autoload/ AppConfig / CatalogStore / PoseReceiver / ScoreService
|
||
src/net/ 239 字节编解码、WebSocket 服务、REST 客户端
|
||
src/model/ VRM 加载、humanoid 骨骼映射
|
||
src/anim/ 关键点 → 骨骼重定向
|
||
src/score/ 特征提取、DTW、评分规则
|
||
src/ui/ 主界面 / 游戏界面 / 结算 / 关于 / 来源展示
|
||
tests/ 无头测试框架与用例
|
||
build/ 导出脚本
|
||
|
||
----------------------------------------------------------------
|
||
八、常见问题
|
||
----------------------------------------------------------------
|
||
|
||
Q: 主界面显示「服务端不可达」
|
||
A: 检查 Web 服务端是否已启动，以及「服务端地址」是否正确（含端口）。
|
||
|
||
Q: 目录里没有可用的动作
|
||
A: 动作必须先在管理端完成「预处理」（BVH → 关键点序列）并「审核通过」，
|
||
才会出现在客户端。
|
||
|
||
Q: 模型加载失败 / 动作不完整
|
||
A: 游戏界面会显示「人形覆盖率」。低于 60% 说明模型的骨骼命名不被识别，
|
||
请换用标准 VRM（VRoid Studio 导出）模型。
|
||
|
||
Q: 连上了手机但分数一直是 0
|
||
A: 确认手机端已开始推流；主界面的「查看接收状态」会显示累计帧数与丢帧数。
|
||
|
||
Q: 关于页面的开源声明
|
||
A: 与 THIRD_PARTY.md、contracts/open-source-credits.md 三处保持一致。
|
||
|
||
----------------------------------------------------------------
|
||
九、许可
|
||
----------------------------------------------------------------
|
||
|
||
本客户端代码以 MIT 许可发布。第三方开源项目声明见 THIRD_PARTY.md。
|
||
未使用 SMPL 模型及其衍生拓扑，统一采用 MediaPipe 33 点拓扑。
|