VolleyEdge PRO 技术文档

基于 MediaPipe BlazePose 33 关键点实时姿态检测与 Gemini AI 大模型智能反馈的浏览器端排球训练虚拟指导与动作评估系统，含 192 项分位置分级训练课程。

🏐发球训练 AI 判定

🧱对墙垫球训练

🤖Gemini AI 教练评分

📚192 项分级课程

进入系统 →

技术文档

技术原理与算法说明

系统流程图

Stage 1: 摄像头采集（WebRTC getUserMedia）

↓

MediaPipe BlazePose 推理
33 关键点 · CPU 推理 · ≥30 FPS

↓

Canvas 骨骼叠加可视化
骨骼连线 + 关键点 + 参考线

↓

动作指标实时计算
肘/膝角度 · 前倾 · 手腕高度 · 肩髋倾斜

↓

违规判定 + 评分
合规区间比对 → 实时评分 + 提示

↓

Stage 2: Gemini AI 教练
关键点序列 → 5 维评分 + 改进建议

↓

训练数据记录（LocalStorage）

图1：VolleyEdge PRO 姿态检测与智能反馈流程

系统流程描述

用户点击"开启摄像头"后，浏览器通过 WebRTC getUserMedia 以 1280×720 分辨率采集画面，MediaPipe BlazePose 模型在 CPU 端逐帧推理（节流至约 15-20 FPS 保证稳定性），输出 33 个三维关键点坐标（x, y, z 及可见度）并在 Canvas 上叠加骨骼连线可视化。系统内置 3 个 CDN 源自动切换容灾（npmmirror / unpkg / jsdelivr），全部加载失败时降级为模拟演示模式。系统根据训练模式（对墙垫球 / 发球 / 综合）实时计算关键生物力学指标：肘关节角度、膝关节角度、身体前倾角、手腕相对肩部高度、肩/髋倾斜角，与合规区间比对后实时更新评分条与违规提示。训练结束后点击"AI 智能反馈"，系统将动作关键帧序列与标准模板比对，调用 Gemini 1.5 Flash 从发力顺序、击球点高度、身体平衡、重心转移、动作幅度 5 个维度生成结构化评分与改进建议（免费额度 1500 次/天）。训练进度、成就徽章与比赛技术统计（对手、比分、扣杀/失误/发球得分/救球/拦网）全部存储于浏览器 LocalStorage，绝不上传服务器。

项目基本信息

项目名称	VolleyEdge PRO — 专业排球智能训练平台（排球发球及对墙训练虚拟指导与AI智能判定系统）
适用场景	排球发球训练、对墙垫球训练、分位置分级课程教学与比赛数据管理
技术架构	纯前端 SPA（HTML5/CSS3/JS），无后端依赖，nginx 静态托管
姿态检测	MediaPipe BlazePose，33 关键点，CPU 推理，≥30 FPS
AI 教练	Google Gemini 1.5 Flash，端到端响应 ≤2s，5 维评分
训练课程	3 位置（主攻/二传/自由人）× 4 等级 = 192 项训练科目
视频教学	YouTube IFrame API + Data API v3，内置 ≥30 条精选教学视频
数据存储	LocalStorage（训练进度 / 成就徽章 / 比赛统计），无服务器上传
容灾机制	3 CDN 源自动切换，全部失败降级模拟演示模式

关键模块说明

1. 实时姿态检测引擎（BlazePose 33 关键点）

MediaPipe BlazePose 采用两阶段检测架构：先由轻量级躯干检测器定位人体 ROI，再由全量关键点模型在该区域推理 33 个三维关键点（含鼻、眼、耳、肩、肘、腕、髋、膝、踝、脚跟、脚尖，覆盖全身动力链）。纯 CPU 推理（WebAssembly + SIMD 加速），标准光照下关键点定位精度 ≥95%。处理管线采用单循环守卫 + 推理挂起锁，防止相机重启产生的多循环叠加与帧队列堆积；Canvas 仅在视频分辨率变化时重新分配位图，避免每帧重绘导致的画面闪烁。

2. 动作指标计算与合规判定（Biomechanics Metrics）

基于关键点坐标的三维向量计算核心生物力学指标：① 肘关节角度 — 肩-肘-腕三点夹角（余弦定理），对墙垫球要求 ≥160° 手臂伸直；② 膝关节角度 — 髋-膝-踝夹角，合规区间 130°-155°；③ 身体前倾角 — 肩-髋连线与垂直轴夹角，≤15° 合规；④ 手腕相对高度 — 腕点与肩点 y 坐标差，发球时要求高于肩部 20-30cm；⑤ 肩/髋倾斜角 — 双肩/双髋连线与水平轴夹角，≤5°/≤8° 合规。每个指标实时映射到红黄绿三色状态卡，并叠加在 Canvas 上绘制参考线（1.4m 标志线、1.5m 踩线基准、42° 最佳击球角辅助线）。

3. Gemini AI 智能教练（Stage 2）

用户完成一轮动作后，系统将动作关键帧的关键点坐标序列（含时序信息）与标准动作模板发送至 Google Gemini 1.5 Flash 大模型。模型从 5 个维度结构化评分：发力顺序（动力链传导是否正确）、击球点高度（是否在最佳击球区）、身体平衡（重心稳定性）、重心转移（前后移动效率）、动作幅度（关节活动范围）。返回 JSON 结构化评分与针对性文字建议，端到端延迟 ≤2 秒，免费额度 1500 次/天（Google AI Studio API Key）。API 调用失败时自动降级为本地规则评分。

4. 分位置训练课程体系（192 项）

按排球竞技结构设计 3 位置 × 4 等级递进课程：主攻手（扣球/发球技术链）、二传手（传球/组织战术）、自由人（防守/接发球专项），共 192 项训练科目。每项包含视频演示 + 分步讲解 + 关键技巧提示。用户通过"课程"菜单按等级选择训练项，在"AI 教练"模式完成练习，进度与成就徽章自动记录于 LocalStorage；"生涯"页面可视化展示解锁成就与发展路径。

5. 训练模式与场景规则引擎

三种训练模式对应不同检测规则集：对墙垫球模式 — 检测手臂伸直度（≥160°）、膝关节角度、身体前倾、击球面倾角，规则约束距墙 1.5m、标志线高 1.4m、踩线违规；发球训练模式 — 检测挥臂轨迹、肘关节高度、手腕速度、身体协调性，目标最佳击球角度 42°、手腕高于肩部 20-30cm；综合训练模式 — 全维度姿势分析、动力链评估、关节角速度监测。违规判定（如踩线、手臂严重弯曲 <130°）实时触发提示并计入评分。

6. 视频教学与比赛数据管理

集成 YouTube IFrame API 实现应用内视频播放（点击缩略图弹窗），内置 ≥30 条精选排球教学视频，支持按位置（主攻/二传/自由人）筛选；集成 YouTube Data API v3 关键词搜索扩展视频库。比赛记录模块存储技术统计字段：对手、比分、扣杀、失误、发球得分、救球、拦网，历史记录可回溯分析。

技术指标汇总

阶段	目标	主要指标	阈值/目标	关键参数
Stage 1	实时姿态检测	检测帧率	≥30 FPS	33 landmarks · CPU 推理 · 3 CDN 容灾
Stage 1	骨骼可视化	关键点定位精度	≥95%	BlazePose · Canvas 叠加
Stage 2	AI 评分反馈	Gemini 响应延迟	≤2s	Gemini 1.5 Flash · 5 维评分
Stage 2	免费调用额度	每日请求次数	1500 次/天	Google AI Studio API Key
Stage 3	课程体系	训练科目总数	192 项	3 位置 × 4 等级
Stage 3	进度追踪	数据持久化	LocalStorage	成就徽章系统
Stage 4	视频教学	内置视频数	≥30 条	YouTube IFrame + Data API v3
Stage 4	比赛记录	技术统计字段	5 项	扣杀/失误/发球得分/救球/拦网

动作合规判定阈值

指标	计算方式	合规（绿）	警告（黄）	违规（红）
肘关节角度	肩-肘-腕三点夹角	≥160°	130°-160°	<130°
膝关节角度	髋-膝-踝三点夹角	130°-155°	100°-130°	<100° 或 >155°
身体前倾角	肩-髋连线 vs 垂直轴	≤15°	15°-25°	>25°
手腕相对高度	腕点 vs 肩点 y 差	高于肩 20-30cm	0-20cm	低于肩部
肩部倾斜角	双肩连线 vs 水平轴	≤5°	5°-10°	>10°
髋部倾斜角	双髋连线 vs 水平轴	≤8°	8°-15°	>15°
击球角度（发球）	挥臂轨迹切线角	≈42°	—	偏离 >±10°
踩线判定	踝点 y 坐标 vs 基准线	线后	—	越线违规

系统架构

┌─────────────────────────────────────────────────────────────────┐ │ 浏览器 (SPA) │ │ ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌───────────────┐ │ │ │ 摄像头 │ │ MediaPipe│ │ Canvas │ │ LocalStorage │ │ │ │ WebRTC │→ │BlazePose │→ │ 骨骼叠加 │ │ 训练/比赛数据 │ │ │ │ getUser │ │33关键点 │ │ 实时显示 │ │ 进度/成就 │ │ │ │ Media │ │CPU推理 │ │ │ │ │ │ │ └──────────┘ └────┬─────┘ └──────────┘ └───────────────┘ │ │ │ │ │ ┌───────────────────┴──────────────────────────────────────┐ │ │ │ 应用逻辑层：训练模式 │ 课程管理 │ 视频搜索 │ 比赛记录 │ │ │ └───────────────────┬──────────────────────────────────────┘ │ │ │ HTTPS 请求 │ └──────────────────────┼──────────────────────────────────────────┘ │ ┌──────────┴──────────┐ │ nginx 静态托管 │ │ cdqtech.online │ └──────────┬──────────┘ │ ┌────────────┴────────────┐ │ 外部 AI 服务层 │ │ ┌────────────────┐ │ │ │ Gemini 1.5 │ │ │ │ Flash AI Coach│ │ │ └────────────────┘ │ │ ┌────────────────┐ │ │ │ YouTube Data │ │ │ │ API v3 │ │ │ └────────────────┘ │ └─────────────────────────┘ 部署方式: nginx 静态文件托管 ────→ https://cdqtech.online/volleyedge/ MediaPipe 模型资源 ────→ 3 CDN 自动容灾（npmmirror / unpkg / jsdelivr）

核心算法实现

关节角度计算（余弦定理）

/**
 * 三点夹角计算：肘关节 = 肩-肘-腕，膝关节 = 髋-膝-踝
 * @param {Object} a - 端点A {x, y}
 * @param {Object} b - 顶点B（关节位置）
 * @param {Object} c - 端点C
 * @returns {number} 角度（度，0-180）
 */
function angle3(a, b, c) {
    const ba = { x: a.x - b.x, y: a.y - b.y };
    const bc = { x: c.x - b.x, y: c.y - b.y };
    const dot = ba.x * bc.x + ba.y * bc.y;
    const mag = Math.sqrt(ba.x*ba.x + ba.y*ba.y)
             * Math.sqrt(bc.x*bc.x + bc.y*bc.y);
    if (mag < 0.0001) return 0;
    // 反余弦，钳位避免浮点越界
    return Math.acos(Math.max(-1, Math.min(1, dot/mag))) * 180/Math.PI;
}

帧处理管线（防抖动核心）

// 单循环守卫 + 推理挂起锁 — 防止相机重启产生多重循环
let _rafRunning = false;
let _inferencePending = false;
let _lastFrameTime = 0;

function processFrame() {
    if (!S.camStarted) { _rafRunning = false; return; }
    if (_rafRunning) return;
    _rafRunning = true;

    const vid = $('cam-vid');
    if (!vid || vid.readyState < 2) {
        _rafRunning = false;
        requestAnimationFrame(processFrame);
        return;
    }
    // 节流 ~15fps，保证稳定性
    const now = Date.now();
    if (now - _lastFrameTime < 66) {
        _rafRunning = false;
        requestAnimationFrame(processFrame);
        return;
    }
    _lastFrameTime = now;
    if (_poseProcessor && vid.videoWidth > 0 && !_inferencePending) {
        _inferencePending = true;  // 挂起锁：防止帧队列堆积
        _poseProcessor.send({ image: vid });
    }
    _rafRunning = false;
    requestAnimationFrame(processFrame);
}

// 结果回调：解锁 + 仅在分辨率变化时重建 Canvas 位图
function onPoseResults(results) {
    _inferencePending = false;
    if (cv.width !== vid.videoWidth || cv.height !== vid.videoHeight) {
        cv.width = vid.videoWidth;
        cv.height = vid.videoHeight;
    }
    // ... 绘制骨骼 + 参考线 + 指标计算
}

CDN 容灾加载链

// MediaPipe 脚本加载：4 级容灾，全部失败降级模拟演示
const CDNS = [
    'https://registry.npmmirror.com/@mediapipe/pose/0.5.1675469404/files/pose.js',
    './mediapipe/pose.js',                                        // 本地
    'https://unpkg.com/@mediapipe/pose@0.5.1675469404/pose.js',
    'https://cdn.jsdelivr.net/npm/@mediapipe/pose@0.5.1675469404/pose.js',
];

function tryLoad() {
    if (cdnIdx >= CDNS.length) { // 全部失败
        runFallbackTracking();   // 降级为模拟演示模式
        return;
    }
    const script = document.createElement('script');
    script.src = CDNS[cdnIdx];
    script.onload = () => initRealPose();
    script.onerror = () => { cdnIdx++; tryLoad(); };  // 自动切换下一源
    document.head.appendChild(script);
}