hand-tracking

手部追踪

用途

此技能利用计算机视觉算法，在 AR/VR 环境中实时检测和追踪手势，可无缝集成到虚拟交互或基于手势的控制等应用中。

使用时机

构建需要手势输入的 AR/VR 应用时使用此技能，例如游戏中的手势控制界面、远程协作工具，或虚拟现实头显中的无障碍功能。在需要低延迟追踪的实时摄像头画面场景中使用，例如实时操控物体。

主要功能

• 使用 MediaPipe Hands 等预训练模型实时估算手部姿态，每只手最多可检测 21 个关键点。
• 识别常见动作（如捏合、挥手、滑动），并可配置准确度阈值。
• 支持多种输入源，包括网络摄像头画面或 AR/VR 设备摄像头，帧率最高可达 60 FPS。
• 输出格式包括手部关键点的 JSON 数据，以及检测到手势时触发的事件。
• 可通过配置文件自定义模型，例如指定最低置信度（如检测置信度为 0.5）。

使用模式

始终使用输入源和身份验证来初始化此技能。首先设置 API 访问所需的环境变量，例如 export OPENCLAW_API_KEY=your_api_key。使用命令行时，通过管道从摄像头设备输入数据。在代码中，将此技能作为模块导入，并在循环中调用追踪函数。处理异步操作，以免阻塞主线程。集成到 AR/VR 时，将其与渲染循环结合，根据手部位置更新虚拟对象。

常用命令/API

快速原型开发可使用 CLI 工具，以编程方式访问则可使用 REST API。身份验证需要 $OPENCLAW_API_KEY 环境变量。

• CLI 命令：

  • 运行追踪：claw hand-track --input /dev/video0 --model mediapipe --confidence 0.7
    • 标志：--input 指定摄像头设备（如 /dev/video0），--model 选择追踪模型（如 mediapipe 或 custom），--confidence 设置检测阈值。
  • 保存输出：claw hand-track --input file.mp4 --output results.json --gestures pinch,wave
    • 此命令会处理视频文件，并将检测到的手势输出到 JSON 文件。

• API 端点：

  • 向 /api/hand-track 发送 POST 请求，并附上 JSON 载荷 { "input": "camera", "model": "mediapipe", "confidence": 0.7 }，以启动追踪。
    • 响应示例：{ "hand_landmarks": [ [x1,y1,z1], ... ], "gestures": ["pinch"] }。
  • GET /api/hand-track/status：检查当前会话状态；需要在请求头中提供 Authorization: Bearer $OPENCLAW_API_KEY。

• 代码片段：

  • Python（使用 OpenClaw SDK）：

    import openclaw
    client = openclaw.Client(api_key=os.environ['OPENCLAW_API_KEY'])
    results = client.hand_track(input_source='camera', model='mediapipe')
    print(results['gestures'])
    

  • JavaScript（Node.js）：

    const openclaw = require('openclaw');
    const client = new openclaw.Client(process.env.OPENCLAW_API_KEY);
    client.handTrack({ input: 'camera', confidence: 0.7 }).then(data => console.log(data.hand_landmarks));
    

• 配置格式：

  • 使用 JSON 配置：{ "model": "mediapipe", "gestures": ["pinch", "wave"], "confidence": 0.7 }。
  • 通过 CLI 加载：claw hand-track --config path/to/config.json。

集成说明

将此技能封装在 AR/VR 框架的事件循环中进行集成。对于 Unity，使用 OpenClaw Unity 插件订阅手部事件。在 Web 应用中，将其与 WebRTC 配合使用，以获取摄像头画面。始终验证输入源是否兼容（例如，确保摄像头分辨率至少为 640x480）。如果使用自定义模型，请通过 API 端点 /api/hand-track/models 以 multipart 表单上传。投入生产前，请使用模拟数据进行测试，以应对不同的光照条件。

错误处理

检查常见错误，例如无效的 API 密钥或摄像头访问问题。在代码片段中使用 try-catch 代码块。对于 CLI，错误会返回退出码（例如，身份验证失败时返回 1）。具体情况：

• 如果缺少 $OPENCLAW_API_KEY，API 会响应 401 Unauthorized；运行前通过 export OPENCLAW_API_KEY=your_key 设置该变量。
• 对于输入错误（例如摄像头不可用），捕获 InputNotFoundError 等异常，并回退到默认来源。
• 通过设置最低阈值并记录警告来处理低置信度检测，例如，在代码中：if results['confidence'] < 0.5: raise ValueError("Low confidence detection")。
• 在 API 调用中，通过指数退避重试暂时性错误（例如网络问题）。

具体用法示例

1. 示例 1：AR 应用中的实时手势控制

   • 场景：构建一个通过手势移动虚拟对象的 AR 应用。
   • 步骤：导出 OPENCLAW_API_KEY，运行 claw hand-track --input camera --gestures pinch，然后在 Python 中：

     import openclaw
     client = openclaw.Client(os.environ['OPENCLAW_API_KEY'])
     while True: results = client.hand_track(); if 'pinch' in results['gestures']: move_object(results['hand_landmarks'])
     

     • 这会检测捏合手势并实时更新对象位置。

2. 示例 2：用于手势检测的视频分析

   • 场景：分析录制的视频，检测用于训练数据的挥手动作。
   • 步骤：使用 CLI：claw hand-track --input video/sample.mp4 --output gestures.log --gestures wave。
   • 在代码中：向 /api/hand-track 发送包含 { "input": "file.mp4", "gestures": ["wave"] } 的 POST 请求，然后处理响应，记录检测到挥手动作的时间戳。
     • 代码片段示例：

       fetch('/api/hand-track', { method: 'POST', headers: { 'Authorization': `Bearer ${process.env.OPENCLAW_API_KEY}` }, body: JSON.stringify({ input: 'file.mp4' }) })
         .then(res => res.json()).then(data => console.log(data.gestures));
       

图关系

• 相关内容：ar-vr（集群）、gesture-detection（标签）、camera-access（用于输入处理的技能）。
• 依赖项：computer-vision（核心技术），需要通过 API 密钥进行身份验证。
• 关联内容：object-tracking（用于扩展到全身追踪），与 rendering-engine 集成（用于 AR/VR 可视化）。