> For the complete documentation index, see [llms.txt](https://changkun.gitbook.io/leapmotion_v2_cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://changkun.gitbook.io/leapmotion_v2_cn/yu-yan/python/leap_overview.md). # API 综述 LeapMotion 是一种检测和跟踪手、手指及类似手指物品的工具。设备会对近距离的手或者手指进行高帧率高精度的跟踪，并提供离散的位置、手势及动作信息。 LeapMotion 控制器使用光学传感器和红外线。Leap可以检测当控制器处于标准操作位置时，沿 Y 轴向上处于控制器位置大约 150 度的视野。LeapMotion 的有效范围在处于设备上方时从大约 25 毫米到 600 毫米不等。 ![用户手位于 LeapMotion 视野内](https://3708604558-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LmAGnx6ThZjQnyNN4Sg%2F-LmAGpETZPiOMDijInN-%2F-LmAGyqT75QjqKpEKvjC%2FLeap_View.jpg?generation=1565704893470234\&alt=media) 当被追踪物体具有清晰、高对比度的轮廓时，传感器的检测和追踪能达到最佳工作状态。LeapMotion 软件结合传感器数据和其内建的人手模型来解决检测和追踪时的问题。 ## 坐标系 LeapMotion 使用一个右手笛卡尔坐标系，它的原点位于 LeapMotion 控制器的顶面中心点，X 轴与 Z 轴位于水平面，其中 X 轴与控制器的长边平行。Y轴垂直向上为正方向（这与绝大多数计算机图形系统的坐标轴是相反的，它们的正方向向下）。Z 轴的方向指向用户所处的位置。 ![LeapMotion 右手坐标系](https://3708604558-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LmAGnx6ThZjQnyNN4Sg%2F-LmAGpETZPiOMDijInN-%2F-LmAGzJXZn2j-L8T-qX_%2FLeap_Axes.png?generation=1565704856101393\&alt=media) LeapMotion API 测量的物理量如下： * 距离 - 毫米 * 时间 - 微秒（除非有特别说明） * 速度 - 毫米/秒 * 角度 - 弧度 ## 动作追踪数据 当 LeapMotion 控制器在视野范围内追踪内追踪手、手指和工具时，它以帧为单位更新一套数据。每个 [**Frame**](/leapmotion_v2_cn/yu-yan/python/api-can-kao/leap.frame.md) 对象代表一帧，其中包含检测的实体序列，比如手、手指、工具以及识别到的手势和描述场景中整体动作的因素。`Frame` 对象是 LeapMotion 数据模型的基础。 更多关于 `Frames` 的内容，请参考：[*Frames*](/leapmotion_v2_cn/yu-yan/python/api-can-kao/leap.frame.md) ### 手部 手模型提供了手部的各种信息，包括手的识别、位置及其他特征的检测，手部所连接手臂，以及手上的手指序列。 请参考 [Hand](/leapmotion_v2_cn/yu-yan/python/api-can-kao/leap.hand.md) 类。 ![手的 \`\`palm\_normal\`\` 和 \`\`direction\`\` 向量定义了手的朝向](https://3708604558-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LmAGnx6ThZjQnyNN4Sg%2F-LmAGpETZPiOMDijInN-%2F-LmAGz5Dhejff8ONgLbA%2FLeap_Palm_Vectors.png?generation=1565704849810210\&alt=media) LeapMotion 软件使用人的手部模型来提供可预测的追踪，即便当手仅仅只是部分可见时。手模型始终会给出五个手指的位置，但是只有在手和手指的轮廓是清晰可见时才能达到最佳效果。软件利用了手的可见部分、它的内建模型以及历史观测信息来计算不可见部分最有可能的位置信息。值得一提的是，手指的细微动作对于 LeapMotion 传感器来说可能不太能够被检测到。[Hand.confidence](/leapmotion_v2_cn/yu-yan/python/api-can-kao/leap.hand.md) 用于指示观测数据与内建模型的吻合度。 当每帧中存在不只一人的手或者类似手的物体时，手序列也可以出现超过两只手的对象，然而为了达到最佳的追踪效果，我们建议最多只让两只手出现在视野内比较合适。 ### 手臂 手臂（[Arm](/leapmotion_v2_cn/yu-yan/python/api-can-kao/leap.arm.md)）是骨骼类似物对象，它包括其指向、长度、宽度、手臂的端点。当肘部不在视野中时，LeapMotion 控制器会基于历史数据及人体参数来估计它出现的位置。 ### 手指 LeapMotion 控制器可以给出一只手上每一根手指的数据。如果某个手指的部分或者全部不可见，那么这根手指的特性同样会基于历史数据进行估计。手指通过名字来进行标识，即：`thumb`(大拇指)，`index`(食指)，`middle`(中指)，`ring`(无名指) 以及 `pinky`(小拇指)。 手指利用 [**Finger**](/leapmotion_v2_cn/yu-yan/python/api-can-kao/leap.finger.md) 类对象进行刻画，是一种 [**Pointable**](/leapmotion_v2_cn/yu-yan/python/api-can-kao/leap.pointable.md)(可指向) 对象。 ![手指的\`tip\_position\`和\`direction\`向量来表明指尖的位置和手指指向的大致方向](https://3708604558-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LmAGnx6ThZjQnyNN4Sg%2F-LmAGpETZPiOMDijInN-%2F-LmAGzBSqWAWs9Fay6bY%2FLeap_Finger_Model.png?generation=1565704850281883\&alt=media) 一个 Finger 对象包含了一个 Bone 对象，用于描述每个手指上的每个解剖学上的骨头位置和指向。 ![](https://3708604558-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LmAGnx6ThZjQnyNN4Sg%2F-LmAGpETZPiOMDijInN-%2F-LmAGz5aOkqFzPyrVXXW%2FFinger_Bone.png?generation=1565704890727966\&alt=media) 骨头分别是： * Metacarpal – the bone inside the hand connecting the finger to the wrist (except the thumb) * Proximal Phalanx – the bone at the base of the finger, connected to the palm * Intermediate Phalanx – the middle bone of the finger, between the tip and the base * Distal Phalanx – the terminal bone at the end of the finger 这个模型中的大拇指和标准解剖模型的命名不同。真实的大拇指比其他手指少一根骨头。但是为了编程的方便，LeapMotion 模型中的大拇指包含了一个长度为 0 的 Metacarpals，以便大拇指的骨头索引与其他手指相同。这样导致的结果是 在LeapMotion 模型中，大拇指的解剖学 Metacarpal 骨名被标注为 Proximal Phalanx，而解剖学上的 Proximal Phalanx 被标注为 Intermediate Phalanx。 （原始图形见：[Marianna Villareal](https://commons.wikimedia.org/wiki/File:Scheme_human_hand_bones-en.svg)） ### 工具 工具是一个类似铅笔的对象。 工具使用 Tool 类进行刻画，也一种[**Pointable**](/leapmotion_v2_cn/yu-yan/python/api-can-kao/leap.pointable.md)(可指向) 对象。 ![工具比手指更长、更细、更直](https://3708604558-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LmAGnx6ThZjQnyNN4Sg%2F-LmAGpETZPiOMDijInN-%2F-LmAGz5cNO0H2I3Y4WqI%2FLeap_Tool.png?generation=1565704853228677\&alt=media) 只有细且为圆柱体的物体才会被认为是工具。在 v2版本中，工具是与手相互独立的。 ### 手势 LeapMotion 软件能够识别特定运动模式的手势来表达用户的意图或者指令。每个手势都能对手指或工具都进行独立观测。LeapMotion 会如同返回其他运动追踪数据（比如手、手指）一样在每一帧里返回手势的检测信息。 手势通过 [Gesture](/leapmotion_v2_cn/yu-yan/python/api-can-kao/leap.gesture.md) 类及其子类 [CircleGesture](https://github.com/changkun/leapmotion_v2_cn/tree/7bc30e3330cee5b47b2724bd9233dd3adf7456d3/python/Leap.CircleGesture.md), [KeyTapGesture](/leapmotion_v2_cn/yu-yan/python/api-can-kao/leap.keytapgesture.md), [ScreenTapGesture](/leapmotion_v2_cn/yu-yan/python/api-can-kao/leap.screentapgesture.md), [SwipeGesture](/leapmotion_v2_cn/yu-yan/python/api-can-kao/leap.swipegesture.md) 进行刻画。 下面的运动模式能够被 LeapMotion 软件识别： ![Circle — 手指画圈](https://3708604558-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LmAGnx6ThZjQnyNN4Sg%2F-LmAGpETZPiOMDijInN-%2F-LmAGz1__J-zAM_y4UUk%2FLeap_Gesture_Circle.png?generation=1565704853804788\&alt=media) ![Swipe — 一个手或手指的长距离线性移动](https://3708604558-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LmAGnx6ThZjQnyNN4Sg%2F-LmAGpETZPiOMDijInN-%2F-LmAGz1bCUjZJSqF1m1M%2FLeap_Gesture_Swipe.png?generation=1565704852410362\&alt=media) ![Key Tap — 手指像敲击键盘一样的点击移动模式 ](https://3708604558-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LmAGnx6ThZjQnyNN4Sg%2F-LmAGpETZPiOMDijInN-%2F-LmAGz6zcJJcLeqnULr_%2FLeap_Gesture_Tap.png?generation=1565704852088912\&alt=media) ![Screen Tap — 想垂直点击屏幕一样的点击移动模式](https://3708604558-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LmAGnx6ThZjQnyNN4Sg%2F-LmAGpETZPiOMDijInN-%2F-LmAGz5kV8rK9qcIkRu_%2FLeap_Gesture_Tap2.png?generation=1565704874435744\&alt=media) **注意**：在你的应用程序中使用手势之前，你必须确保你要用的每一个手势都能够被识别。你需要使用 `Controller` 类中的 `enableGesture()` 方法使你想用的手势被识别到。 ### 动作 用户手部在某一段时间内的变化被定义为基本的动作种类，运动就是根据这些基本的动作种类被估计出来的。运动包括缩放、旋转、位移（位置变化）。 ![](https://3708604558-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LmAGnx6ThZjQnyNN4Sg%2F-LmAGpETZPiOMDijInN-%2F-LmAGz72fFZ3WECV4s2S%2FMotion_Graphic.png?generation=1565704855440742\&alt=media) 运动是在两帧之间被计算出来的。你可以从一个 [**Frame**](/leapmotion_v2_cn/yu-yan/python/api-can-kao/leap.frame.md) 对象里获得一个场景的全部运动因子。也可以从一个 [**Hand**](/leapmotion_v2_cn/yu-yan/python/api-can-kao/leap.hand.md) 对象里获得与单独一只手有关的运动因子。 你可以用返回的运动因子来为你的应用设计交互方式。比如，你可以计算两帧之间的缩放因素来让用户改变物体的大小，而不是很多帧的数据来追踪每一个手指的位置变化。 | **运动类型** | **帧** | **手** | | :-------------: | ---------------------------------------- | ------------------ | | Scale(缩放) | 帧的缩放反映了场景物体之间的靠近或远离的运动 | 手的缩放则反应了手指的开合变化。 | | Rotation(旋转) | 帧的旋转反映了场景内物体的运动差异。例如一只手抬起而另一只则放下 | 手的旋转反应了一只手朝向的变化情况。 | | Translation(平移) | 帧的平移反映了场景内所有物体的平均位置变化。比如两只手都同时向左、上、前方移动。 | 手的平移反应了手的位置变化。 | ### 传感器图像 获得追踪数据的同事你也能够获取 LeapMotion 摄像头所拍摄到的原始图像。 ![传感器原始图像即叠加的校准点](https://3708604558-files.gitbook.io/~/files/v0/b/gitbook-legacy-files/o/assets%2F-LmAGnx6ThZjQnyNN4Sg%2F-LmAGpETZPiOMDijInN-%2F-LmAGz74yoEPJdoZTcBm%2FLeap_Image_Raw.png?generation=1565704855688618\&alt=media) 图像数据包括测量的 IR 亮度值和用户修正镜头畸变的校准数据。你可以吧传感器图像用于增强现实，尤其是当 LeapMotion 与 VR 头盔设备进行协作时候。 更多信息请参考：[相机图像](/leapmotion_v2_cn/yu-yan/python/shi-yong-zhui-zong-api/leap_images.md)