Leap::Frame Class Reference 帧类参考

简要说明（由于本人英语水平真的很烂，文里漏洞百出，欢迎批评指正）

点击查看原文

帧类代表了在一个帧中检测到的手和手指的跟踪数据的集合。

继承 Leap::Interface

公有成员函数

               float        currentFramesPerSecond () const

                             瞬时帧速率

             Finger        finger (int32_t id) const

                             具有在这个帧中特定ID的Finger手指对象

        FingerList        fingers () const

                             以任意的顺序返回，这个帧中检测到的手指对象的列表

                             Frame ()

                             构造一个帧对象         

          Gesture        gesture (int32_t id) const

                            具有在这个帧中特定ID的Gesture手势对象

     GestureList        gestures () const

                            在这个帧中识别到的或连续的手势

     GestureList        gestures (const Frame &sinceFrame) const

                            返回一个手势列表对象，包含返回自从某一帧以来发生的所有的手势

             Hand        hand (int32_t id) const

                            具有在这个帧中特定ID的Hand手对象

        HandList        hands () const

                           以任意的顺序返回，这个帧中检测到的手对象的列表

         int64_t        id () const

                           这个帧的唯一的ID

InteractionBox        interactionBox () const

                           这个帧的当前的InteractionBox       

             bool         isValid () const

                           报告这个帧实例是否有效

            bool          operator!= (const Frame &) const

                           比较帧对象不同

            bool          operator== (const Frame &) const

                           比较帧对象相同

     Pointable          pointable (int32_t id) const

                           具有在这个帧中特定ID的尖端物体对象

 PointableList         pointables () const

                           以任意的顺序返回，这个帧中检测到的尖端物体对象（手指或者工具）的列表

           float         rotationAngle (const Frame &sinceFrame) const

                          从当前帧和特定的帧之间的所有旋转运动中围绕着旋转轴的旋转角度大小

           float         rotationAngle (const Frame &sinceFrame, const Vector &axis) const

                          从当前帧和特定的帧之间的所有旋转运动中围绕某一指定旋转轴的旋转角度大小

        Vector          rotationAxis (const Frame &sinceFrame) const

                          从当前帧和特定的帧之间的所有旋转运动中的旋转坐标

        Matrix          rotationMatrix (const Frame &sinceFrame) const

                          表达从当前帧和特定的帧之间的所有旋转运动的旋转的变换矩阵

           float          rotationProbability (const Frame &sinceFrame) const

                           从当前帧和指定的帧之间的所有的动作被确定为是一个旋转动作的估计概率

           float         scaleFactor (const Frame &sinceFrame) const

                          从当前帧和特定的帧之间的所有运动的缩放因子

           float         scaleProbability (const Frame &sinceFrame) const

                          从当前帧和指定的帧之间的所有的动作被确定为是一个缩放动作的估计概率

       int64_t          timestamp () const

                          以微秒为单位从Leap开始之后的帧的捕获时间

          Tool           tool (int32_t id) const

                          具有在这个帧中特定ID的工具对象

     ToolList           tools () const

                          以任意的顺序返回，这个帧中检测到的工具对象的列表

 std::string           toString () const

                          一个包含简短的、可读的对这个帧对象的描述的字符串

       Vector          translation (const Frame &sinceFrame) const

                          从当前帧和指定的帧之间的所有线性动作的位置变化

        float           translationProbability (const Frame &sinceFrame) const

                         从当前帧和指定的帧之间的所有的动作被确定为是一个平移动作的估计概率

静态公有成员函数

static  const  Frame&  invalid()

                              返回一个无效的帧对象

友元函数

std::ostream &  operator<< (std::ostream &, const Frame &)

                      打印一个包含简短的、可读的对这个帧对象的描述到输出流中

---

详细描述

帧类代表了在一个帧中检测到的手和手指的跟踪数据的集合。

Leap Motion软件在可跟踪区域内检测手、手指和工具，报告它们的位置、方向、手势和运动，以Leap Motion的帧率。

访问帧对象通过Controller类的实例。

if( controller.isConnected()) //controller is a Controller object
    {
        Frame frame = controller.frame(); //The latest frame
        Frame previous = controller.frame(1); //The previous frame
    }

当一个新帧可获得时，实现一个Listener子类来接收回调事件。

Since

1.0

---

构造函数和析构函数文档

Leap::Frame::Frame()

构造一个帧对象。

使用这个函数构造的帧实例是无效的。通过调用Controller::frame()函数来获得有效的帧对象。

Frame current = controller.frame();

Frame previous = controller.frame(1);

Since

1.0

---

成员函数文档

float Leap::Frame::currentFramesPerSecond()const

瞬时帧率。

Leap Motion 软件提供帧数据的速率（帧/秒）。帧速率可能是波动的，这取决于可利用的计算机资源，在视场之内的活动，软件跟踪设置，以及其他的因素。

float instantaneousFrameRate = frame.currentFramesPerSecond();

返回：

Leap Motion 控制器的一个估计的帧率。

Since

1.0

Finger Leap::Frame::finger(int32_t id)const

具有在这个帧中特定ID的Finger手指对象.

使用Frame::finger()函数从帧中来检索手指对象，使用从前一帧中获得到的ID值。这个函数经常返回一个手指对象，但是如果当前没有这个ID的手指，一个无效的手指对象将被返回。

Finger fingerOfinterest = frame.finger(fingerID);

注意;这个ID值在多帧之间保留，直到跟踪的这个特殊对象丢失了。如果跟踪的一个手指对象丢失了但是稍后又获得了，代表同一个实际手指的这个新的手指对象可能会和之前的帧中的手指对象具有不同的ID。

参数：

id   从前一帧中获取的手指对象的ID

返回：

匹配这个ID的手指对象，如果在这一帧中不存在，那么返回一个无效的手指对象。

Since

1.0

FingerList Leap::Frame::fingers()const

以任意的顺序返回，这个帧中检测到的手指对象的列表

如果没有检测到手指，那么这个列表是空的。

FingerList fingersInFrame = frame.fingers();

返回：

在帧中检测到的所有手指对象的手指列表

Since

1.0

Gesture Leap::Frame::gesture(int32_t id)const

具有在这个帧中特定ID的Gesture手势对象

使用Frame::gesture()函数从帧中来检索手势对象，使用从前一帧中获得到的ID值。这个函数经常返回一个手势对象，但是如果当前帧中没有这个手势的更新，一个无效的手势对象将被返回。

Gesture gestureOfInterest = frame.gesture(gestureID);

所有的手势对象表示拥有这个ID的相同的识别出的运动。

参数:

id   从前一帧中获取的手势对象的ID

返回：

匹配这个ID的手势对象，如果在这一帧中不存在，那么返回一个无效的手势对象。

Since

1.0

GestureList Leap::Frame::gestures()const

在这个帧中识别到的或持续的手势

GestureList gesturesInFrame = frame.gestures();

圆圈和滑动手势在每一帧中更新。点击手势值在列表中的一个单独的帧中出现。

返回：

手势列表

Since

1.0

GestureList Leap::Frame::gestures(const Frame & sinceFrame)const

返回一个手势列表对象，包含返回自从某一帧以来发生的所有的手势.

GestureList gesturesSinceFrame = frame.gestures(lastProcessedFrame);

参数：

sinceFrame   一个之前的帧对象。开始帧必须仍然在历史帧缓存中，默认的历史帧长度是60.

返回:

GestureList    从特定的帧开始发生的手势对象的列表。

Since

1.0

 Hand Leap::Frame::hand(int32_t id)const

 具有在这个帧中特定ID的Hand手对象

 使用Frame::hand()函数从帧中来检索手对象，使用从前一帧中获得到的ID值。这个函数经常返回一个手对象，但是如果当前帧中没有具有这个ID这个手对象，那么一个无效的手对象将被返回。

Hand handOfInterest = frame.hand(handID);

注意：这个ID值在多帧之间保留，直到跟踪的这个特殊对象丢失了。如果跟踪的一个手对象丢失了但是稍后又获得了，代表同一个实际手的这个新的手对象可能会和之前的帧中的手对象具有不同的ID。

参数：

id   从前一帧中获取的手对象的ID

返回：

匹配这个ID的手对象，如果在这一帧中不存在，那么返回一个无效的手对象。

Since

1.0

 HandList Leap::Frame::hands()const

 以任意的顺序返回，这个帧中检测到的手对象的列表。

 如果没有手对象检测到，那么这个列表是空的。

HandList handsInFrame = frame.hands();

返回:

在帧中检测到的包含所有手对象的手列表。

Since

1.0

int64_t Leap::Frame::id()const

表示这个帧的唯一的ID。

Leap Motion 软件处理的相邻帧拥有连续的增加值。你可以使用帧ID来避免处理同一个帧对象两次。

int64_t lastFrameID = 0;
    void processFrame( Leap::Frame frame )
    {
        if( frame.id() == lastFrameID ) return;
        //...
        lastFrameID = frame.id();
    }

同时也要保证你的应用程序处理了每一帧。

int64_t lastProcessedFrameID = 0;
    void nextFrame( Leap::Controller controller )
    {
        int64_t currentID = controller.frame().id();
        for( int history = 0; history < currentID - lastProcessedFrameID; history++)
        {
            processFrame( controller.frame(history) );
        }
        lastProcessedFrameID = currentID;
    }
    void processNextFrame( Leap::Frame frame )
    {
        if( frame.isValid() )
        {
            //...
        }
    }

返回：

帧的ID

Since

1.0

InteractionBox Leap::Frame::interactionBox()const

这个帧的当前的InteractionBox。

查看InteractionBox类文档上  更多的介绍来了解如何使用这个类。

InteractionBox box = frame.interactionBox();

返回：

当前的InteractionBox对象。

Since

1.0

static const Frame& Leap::Frame::invalid()

返回一个无效的帧对象。

你可以使用这个函数返回的实例来比较测试是否一个给定的帧实例是有效的还是无效的。（你也可以使用Frame::isValid() 函数）

//Average a finger position for the last 10 frames
    int count = 0;
    Leap::Vector average = Leap::Vector();
    Leap::Finger fingerToAverage = frame.fingers()[0];
    for( int i = 0; i < 10; i++ )
    {
        Leap::Finger fingerFromFrame = controller.frame(i).finger(fingerToAverage.id());
        if( fingerFromFrame.isValid() )
        {
            average += fingerFromFrame.tipPosition();
            count++;
        }
    }
    average /= count;

返回：

无效的帧实例

Since

1.0

bool Leap::Frame::isValid()const

报告这个帧是否是有效的。

一个有效的帧是由Leap::Controller对象产生的，它包含所有检测到的实体的跟踪数据。一个无效的帧不包含实际的跟踪数据，但是你可以调用它的函数而不会产生空指针异常的风险。这个无效的帧机制使在历史帧中跟踪个体数据更加方便。例如，你可以调用：

Finger finger = controller.frame(n).finger(fingerID);

对于一个任意的帧历史值，“n”，没有事先检测是否frame(n)返回了一个有效帧对象。（你可以仍然检查一个返回的帧对象是否有效）

返回;

True，如果这个帧是有效的，否则返回false。

Since

1.0

bool Leap::Frame::operator!=(const Frame & )const

比较帧是否不同。

thisFrame != thatFrame;

帧对象是相同的，当且仅当这两个帧对象代表的正是同一个帧的跟踪数据，并且帧对象是有效的。

Since

1.0

bool Leap::Frame::operator==(const Frame & )const

比较帧是否相同。

thisFrame == thatFrame;

帧对象是相同的，当且仅当这两个帧对象代表的正是同一个帧的跟踪数据，并且帧对象是有效的。

Since

1.0

Pointable Leap::Frame::pointable(int32_t id)const

具有在这个帧中特定ID的尖端物体对象。

使用Frame::pointable()函数从帧中来检索尖端物体对象，使用从前一帧中获得到的ID值。这个函数经常返回一个尖端物体对象，但是如果当前帧中没有具有这个ID这个手指或者工具对象，那么一个无效的尖端物体对象将被返回。

Pointable pointableOfInterest = frame.pointable(pointableID);

注意：这个ID值在多帧之间保留，直到跟踪的这个特殊对象丢失了。如果跟踪的一个手指或者工具对象丢失了但是稍后又获得了，代表同一个实际手指或者工具的这个新的尖端物体对象可能会和之前的帧中的尖端物体对象具有不同的ID。

参数：

id   从前一帧中获取的尖端物体对象的ID

返回：

匹配这个ID的尖端物体对象，如果在这一帧中不存在，那么返回一个无效的尖端物体对象。

Since

1.0

PointableList Leap::Frame::pointables()const

以任意的顺序返回，这个帧中检测到的尖端物体对象（手指或者工具）的列表。

如果没有手指或者工具被检测到，那么这个列表会是空的。

PointableList pointablesInFrame = frame.pointables();

返回：

包含在帧中检测到的所有尖端物体对象的列表

Since

1.0

float Leap::Frame::rotationAngle(const Frame & sinceFrame)const

从当前帧和特定的帧之间的所有旋转运动中围绕着旋转轴的旋转角度大小.

被返回的角度是在开始和结束帧之间以顺时针方向围绕着旋转轴的弧度法表示的（使用右手规则）。这个值一般是在0和pi弧度之间（0和180度）。

float rotationInFrame = frame.rotationAngle(startFrame);

Leap Motion软件从在视场中检测到的所有的对象的位置和方向的相对变化中获得帧角度。

如果这个帧或者起始帧有一个是无效的对象，那么这个角度值是0.

参数：

sinceFrame   计算相对角度的起始帧。

返回：

一个正数值，描述了从参数指定的帧到当前帧的测定的角度变化。

Since

1.0

float Leap::Frame::rotationAngle(const Frame&sinceFrame,const Vector & axis) const

从当前帧和特定的帧之间的所有旋转运动中围绕某一指定旋转轴的旋转角度大小.

被返回的角度是在开始和结束帧之间以顺时针方向围绕着旋转轴的弧度法表示的（使用右手规则）。这个值一般是在-pi和pi弧度之间（-180和180度）。

float rotationAroundXAxis = frame.rotationAngle(startFrame, Vector::xAxis());

Leap Motion软件从在视场中检测到的所有的对象的位置和方向的相对变化中获得帧角度。

如果这个帧或者起始帧有一个是无效的对象，那么这个角度值是0.

参数：

sinceFrame   计算相对角度的起始帧。

axis    测定围绕旋转的轴

返回：

一个值，描述了从参数指定的帧到当前帧的测定的围绕着指定的轴的角度变化。

Since

1.0

Vector Leap::Frame::rotationAxis(const Frame & sinceFrame)const

从当前帧和特定的帧之间的所有旋转运动中的旋转坐标。

返回的方向向量是正规化的。

Vector axisOfRotation = frame.rotationAxis(startFrame);

Leap Motion软件从在视场中检测到的所有的对象的位置和方向的相对变化中获得帧角度。

如果这个帧或者起始帧有一个是无效的对象，或者这两个帧之间没有检测到旋转，那么返回一个零向量.

参数：

sinceFrame   计算旋转坐标的起始帧。

返回：

一个正规化的方向向量，描述了从参数指定的帧到当前帧的测定的旋转变化的轴。

Since

1.0

Matrix Leap::Frame::rotationMatrix(const Frame & sinceFrame)const

表达从当前帧和特定的帧之间的所有旋转运动的旋转的变换矩阵。

Matrix rotationTransform = frame.rotationMatrix(startFrame);

Leap Motion软件从在视场中检测到的所有的对象的位置和方向的相对变化中获得帧角度。

如果这个帧或者起始帧有一个是无效的对象，那么这个函数返回一个单位矩阵.

参数：

sinceFrame   计算相对旋转的起始帧。

返回：

一个旋转矩阵，描述了从参数指定的帧到当前帧的测定的旋转变化。

Since

1.0

float Leap::Frame::rotationProbability(const Frame & sinceFrame)const

从当前帧和指定的帧之间的所有的动作被确定为是一个旋转动作的估计概率。

float rotationDominance = frame.rotationProbability(startFrame);

如果这个帧或者起始帧有一个是无效的对象，那么这个函数返回0.

参数：

sinceFrame   计算相对旋转的起始帧。

返回：

在0和1之间的一个值，描述了从当前帧和指定的帧之间的所有的动作被确定为是一个旋转动作的估计概率。

Since

1.0

float Leap::Frame::scaleFactor(const Frame & sinceFrame)const

从当前帧和特定的帧之间的所有运动的缩放因子

缩放因子一般是正值。1.0表示没有缩放发生。0.0和1.0之间的值表示收缩，比1.0大的值表示放大。

float zoomFactor = frame.scaleFactor(startFrame);

Leap Motion 软件从视场中检测到的所有物体的相对向内和向外的运动检测缩放（和平移、旋转是独立的）。

如果这个帧或者起始帧有一个是无效的对象，那么这个函数返回1.0.

参数：

sinceFrame   计算相对缩放的起始帧。

返回：

一个正数值，描述了从当前帧和指定的帧之间的所有的动作被检测到的缩放率。

Since

1.0

 float Leap::Frame::scaleProbability(const Frame & sinceFrame)const

 从当前帧和指定的帧之间的所有的动作被确定为是一个旋转动作的估计概率。

float scaleDominance = frame.scaleProbability(startFrame);

如果这个帧或者起始帧有一个是无效的对象，那么这个函数返回0.

参数：

sinceFrame   计算相对缩放的起始帧。

返回：

在0和1之间的一个值，描述了从当前帧和指定的帧之间的所有的动作被确定为是一个缩放动作的估计概率。

Since

1.0

 int64_t Leap::Frame::timestamp()const

 以微秒为单位从Leap开始之后的帧的捕获时间。

float framePeriod = frame.timestamp() - controller.frame(1).timestamp();

返回：

以微妙为单位的时间戳。

Sicne

1.0

Tool Leap::Frame::tool(int32_t id)const

具有在这个帧中特定ID的工具对象.

使用Frame::tool()函数从帧中来检索工具对象，使用从前一帧中获得到的ID值。这个函数经常返回一个工具对象，但是如果当前帧中没有具有这个ID这个工具对象，那么一个无效的工具对象将被返回。

Tool toolOfInterest = frame.tool(toolID);

注意：这个ID值在多帧之间保留，直到跟踪的这个特殊对象丢失了。如果跟踪的一个工具对象丢失了但是稍后又获得了，代表同一个实际工具的这个新的工具对象可能会和之前的帧中的工具对象具有不同的ID。

参数：

id   从前一帧中获取的工具对象的ID

返回：

匹配这个ID的工具对象，如果在这一帧中不存在，那么返回一个无效的工具对象。

Since

1.0

 ToolList Leap::Frame::tools()const

 以任意的顺序返回，这个帧中检测到的工具对象的列表。

 如果没有工具对象检测到，那么这个列表是空的。

ToolList toolsInFrame = frame.tools();

返回:

在帧中检测到的包含所有工具对象的工具列表。

Since

1.0

std::string Leap::Frame::toString()const

一个包含简短的、可读的对这个帧对象的描述的字符串。

返回:

一个描述帧的字符串

Since

1.0

Vector Leap::Frame::translation(const Frame & sinceFrame)const

从当前帧和指定的帧之间的所有线性动作的位置变化.

返回的平移向量提供了以毫米为单位的运动大小和方向。

Vector linearMovement = frame.translation(startFrame);

Leap Motion软件从在视场中检测到的所有物体的线性运动中获得帧平移。

如果这个帧或者起始帧有一个是无效的帧对象，那么这个函数返回0向量.

参数：

sinceFrame   计算相对平移的起始帧。

返回：

一个向量，描述了从当前帧和指定的帧之间的所有的对象的变化的位置。

Since

1.0

 float Leap::Frame::translationProbability(const Frame & sinceFrame)const

 从当前帧和指定的帧之间的所有的动作被确定为是一个平移动作的估计概率。

float translationDominance = frame.translationProbability(startFrame);

如果这个帧或者起始帧有一个是无效的对象，那么这个函数返回0.

参数：

sinceFrame   计算平移运动的起始帧。

返回：

在0和1之间的一个值，描述了从当前帧和指定的帧之间的所有的动作被确定为是一个平移动作的估计概率。

Since

1.0

---

友元函数和相关函数文档

std::ostream& operator<<(std::ostream &, const Frame &)

打印一个包含简短的、可读的对这个帧对象的描述到输出流中

std::cout << frame << std::endl;

Since

1.0