从控制点到可捕获的前端工具

01 / START UP

Start Up

安装包，传入屏幕坐标控制点，再用 CSS 定义它们的视觉反馈。

1. 安装

npm install vision-gesture-kit

2. 渲染控制点

import { GesturePointOverlay } from "vision-gesture-kit";

export function GestureLayer({ hands }) {
  const points = hands.flatMap((hand, handIndex) => [
    { id: `${handIndex}-index`, ...hand.index },
    { id: `${handIndex}-thumb`, ...hand.thumb }
  ]);

  return (
    <GesturePointOverlay
      points={points}
      pointClassName="gesture-point"
    />
  );
}

3. 添加样式

.gesture-point {
  border: 2px solid rgba(255, 255, 255, 0.85);
  border-radius: 50%;
  background: rgba(255, 255, 255, 0.18);
}

组件使用 fixed 定位，因此 x/y 应是相对于当前视口的像素坐标。运行页面后，数组中的每个点都会显示在页面最上层。

02 / INPUT

坐标与数据

识别模型通常返回 0 到 1 的归一化坐标。渲染前先映射到屏幕，并根据镜像摄像头决定是否翻转 x。

03 / REACT

GesturePointOverlay

一个透明、固定定位且不截获指针事件的覆盖层。它渲染控制点，并允许把滚动槽、章节轨道等自定义工具作为 children 放入同一顶层坐标空间。

04 / CORE

计算工具

框架无关函数可以在 React、Vue、Svelte 或原生 DOM 中直接使用，并同时支持 ESM 与 CJS。

import {
  distance2d,
  getPinchCenter,
  findNearestPointIndex,
  getAdaptiveRadius
} from "vision-gesture-kit";

05 / INTERACTION

推荐交互状态机

不要让 landmark 直接触发业务操作。先让输入点捕获一个可见工具，再由工具输出业务事件。

1. Idle没有手进入工具感应区。
2. Armed中点接近控制圆；锁定当前工具并扩大反馈范围。
3. Captured检测到从张开到闭合的捏合边沿；无论手移动到哪里都保持所有权。
4. Dragging把捏合中点投影到轨道，工具生成位置、方向和速度。
5. Released稳定检测到松开后解除锁定，并按需应用阻尼与惯性。

06 / DETECTOR

MediaPipe 接入

首页演示使用 @mediapipe/tasks-vision 的 HandLandmarker。将 landmark 8 作为食指尖、4 作为拇指尖，映射为屏幕坐标后传入覆盖层。建议使用张开/闭合双阈值和短暂释放延时，避免临界抖动。

07 / PRODUCTION

浏览器与部署

• 摄像头仅能在 HTTPS 或 localhost 安全上下文中使用。
• 首次启动必须由用户授予摄像头权限，并提供被占用或拒绝时的重试入口。
• 推理可完全留在浏览器；除非产品明确需要，不要上传摄像头帧。
• Vercel 可直接部署本仓库的 Next.js 站点，生产域名默认使用 HTTPS。
• 医疗、工业等高风险场景必须保留确认、审计日志与实体输入回退。