Frame类（Leap::Frame）

Frame类（Leap::Frame）

这个类代表了在一个单独的帧中检测到的一系列手和手指的跟踪数据。Leap Motion软件在跟踪数据中检测手、手指、工具，报告它们在帧中的位置、方向、姿势和运动。下面是个通过Controller类来访问Frame对象的示例：
if (controller.isConnected()) //controller is a Controller object
{
Leap::Frame frame=controller.frame(); //The latest frame
Leap::Frame previous=controller.frame(1); //The previous frame
}
当一个新的Frame对象可用的时候，用一个Listener子类来返回一个回调事件。
float currentFramesPerSecond(): 表示瞬时帧速率，即Leap Motion软件提供数据帧的速率，会根据可用的计算资源、设备视线内活动、软件跟踪设置和其他因素发生波动。
用法：float instantaneousFrameRate=frame. currentFramesPerSecond();
void deserialize(const std::string & str): 解码字节字符串来代替这个对象的属性。一个Controller对象必须要为这个函数实例化，但是不需要连接。注意，当某一帧并行化时，调用把另一个Frame对象作为参数的函数时的行为是未定义的。比如说，在并行化的一帧中调用gestures(sinceFrame)或者用并行化的一帧做参数，不能返回在这两帧中所有的手势。运动函数，比如scaleFactor(startFrame)，更可能是返回合理的结果，但在某些情况下会返回异常值。
说明：Leap::Controller controller; //An instance must exist
std::ifsream inputFile(“frame.data”);
std::stringframeData((std::istreambuf_iterator(inputFile)),std::istreambuf_iterator());
Leap::Frame reconstructedFrame;
reconstructedFrame. deserialize(frameData);
Finger finger(int32_t id): 表示在这帧中带特有ID的Finger对象。用这个函数可以用一个ID值从这帧中重新得到这个Finger对象，这个ID值是从上一帧中得到的。如果现在没有带有那个特有ID值的手指，则会返回一个无效的Finger对象。注意，这个ID值是跨帧不变的，直到跟踪失败。如果手指的跟踪丢了之后又重新得到，则代表那个手指的新的Finger对象会带有不同的ID。
用法：Leap::Finger fingerOfinterest=frame.finger(fingerID);
FingerList fingers(): 代表这帧中检测到的Finger对象的列表（任意顺序）。如果没有检测到手指，则该列表为空。可以用PointableList::extended()从列表中移除无法扩展的手指。
用法：Leap::FingerList fingerInFrame=frame.fingers();
Frame(): 构造一个Frame对象。通过调用Controller::frame()函数来得到有效的Frame对象。是在并行化串行帧数据之前用这个构造函数，调用Frame::deserialize(string)来重新创建一个保存的Frame对象。
用法：Leap::Frame current=controller.frame();
Leap::Frame previous=controller.frame(1);
Gesture gesture(int32_t id): 表示在这帧中带特有ID的Gesture对象。用这个函数可以用一个ID值从这帧中重新得到这个Gesture对象，这个ID值是从上一帧中得到的。如果现在没有带有那个特有ID值的手势，则会返回一个无效的Gesture对象。
用法：Leap::Gesture gestureOfinterest=frame.gesture(gestureID);
GestureList gestures(): 在这帧中识别或继续的手势。画圈和挥动手势每帧中都更新，而点击手势只在单独帧的列表中出现。
用法：Leap::GestureList gestureInFrame=frame.gestures();
GestureList gestures(const Frame & sinceFrame): 返回一个GestureList对象，这个列表汇总包含了自某个指定帧开始出现的所有手势。
用法：Leap::GestureList gestureSinceFrame=frame.gestures(lastProcessedFrame);
Hand hand(int32_t id): 表示这一帧中具有特定ID的Hand对象。用这个函数可以用一个ID值从这帧中重新得到这个Hand对象，这个ID值是从上一帧中得到的。如果现在没有带有那个特有ID值的手，则会返回一个无效的Hand对象。这个ID值是跨帧不变的，直到跟踪失败。如果手的跟踪丢了之后又重新得到，则代表那个手的新的Hand对象会带有不同的ID。
用法：Leap::Hand handOfInterest=frame.hand(handID);
HandList hands(): 代表这帧中检测到的Hand对象的列表（任意顺序）。如果没有检测到手，则该列表为空。
用法：Leap::HandList handsInFrame=frame.hands();
int64_t id(): 代表这帧中独特的ID。Leap Motion处理的连续帧具有连续增加的值，可以用这个帧ID来避免处理同样的Frame对象两次，也可以确保处理了每一帧。
ImageList images(): 从Leap Motion相机得到的图片列表。
InteractionBox interactionBox(): 当前帧的InteractionBox对象。具体看这个类的介绍。
bool isValid(): 判断这个对象是否有效。如果这个对象是由包含了所有检测实体的跟踪数据的Leap::Controller对象生成，则被认为是有效的。如果是有效的Frame对象，返回True。
bool operator!=(const Frame &): 比较Frame对象是否不相等。如果两个对象都是有效的，在同一帧中有且仅有这两个对象表示同样的实体，则这两个对象相等。
用法：thisFrame!=thatFrame;
bool operator==(const Frame &): 比较Frame对象是否相等。如果两个对象都是有效的，在同一帧中有且仅有这两个对象表示同样的实体，则这两个对象相等。
用法：thisFrame==thatFrame;
Pointable pointable(int32_t id): 表示这一帧中具有特定ID的Pointable对象。用这个函数可以用一个ID值从这帧中重新得到这个Pointable对象，这个ID值是从上一帧中得到的。如果现在没有带有那个特有ID值的手指或工具，则会返回一个无效的Pointable对象。这个ID值是跨帧不变的，直到跟踪失败。如果手指或工具的跟踪丢了之后又重新得到，则代表那个手指或工具的新的Pointable对象会带有不同的ID。
用法：Leap::Pointable pointableOfinterest=frame.pointable(pointableID);
PointableList pointables(): 代表这帧中检测到的Pointable对象的列表（任意顺序）。如果没有检测到手指或工具，则该列表为空。
用法：Leap:: PointableList pointablesInFrame=frame. pointables ();
float rotationAngle(const Frame & sinceFrame): 表示环绕从当前帧到指定帧整体旋转运动中形成的旋转轴的旋转角度。返回的角度是从开始帧到结束帧顺时针旋转的弧度（用右手定则），这个值总是在0到pi之间。如果这一帧或者sinceFrame是无效的Frame对象，则旋转角度是0.
用法：参数sinceFrame是计算相对旋转的开始帧，axis是衡量旋转的轴
float rotationInFrame=frame.rotationAngle(startFrame);
float rotationAngle(const Frame & sinceFrame,const Vector & axis): 表示环绕从当前帧到指定帧整体旋转运动中形成的指定的轴的旋转角度。返回的角度是从开始帧到结束帧顺时针旋转的弧度（用右手定则），这个值总是在-pi到pi之间。如果这一帧或者sinceFrame是无效的Frame对象，则旋转角度是0.（注意与上一个函数的区别，参数上）
用法：参数sinceFrame是计算相对旋转的开始帧，axis是衡量旋转的轴
float rotationAroundXAxis=frame.rotationAngle(startFrame,Leap::Vector::xAxis());
Vector rotationAxis(const Frame & sinceFrame): 表示环绕从当前帧到指定帧整体旋转运动中形成的旋转轴的旋转角度。返回的方向向量是归一化的。
用法：参数sinceFrame是计算相对旋转的开始帧。
Leap::Vector axisOfRotation=frame. rotationAxis(startFrame);

Matrix rotationMatrix(const Frame & sinceFrame): 描述从当前帧到指定帧整体旋转运动的转换矩阵。
用法：参数sinceFrame是计算相对旋转的开始帧。
Leap::Matrix rotationTransform=frame. rotationMatrix(startFrame);
float rotationProbability(const Frame & sinceFrame): 从当前帧到指定帧整体运动被认为是一种旋转运动的概率。
用法：参数sinceFrame是计算相对旋转的开始帧。
float rotationDominance=frame. rotationProbability (startFrame);
float scaleFactor(const Frame & sinceFrame): 表示从当前帧到指定帧整体旋转运动中的缩放因子。缩放因子总是正的，值1表示没有发生尺度变化，0到1之间表示收缩，大于1表示放大。
用法：参数sinceFrame是计算相对尺度的开始帧。
float ZoomFactor=frame. scaleFactor (startFrame);

float scaleProbability(const Frame & sinceFrame): 从当前帧到指定帧整体运动被认为是一种尺度运动的概率。
用法：参数sinceFrame是计算相对尺度的开始帧。
float scaleDominance=frame. scaleProbability (startFrame);
std::string serialize(): 表示把这个Frame对象编码成字节字符串。返回串行的字符串。
说明：std::ofstream outputFile(“frame.data”);
const std::string serializedFrame=frame.serialize();
outputFile<< serializedFrame;
outputFile.close();
int64_t timestamp(): 从过去一个任意时间点开始帧捕获时间的标记（以微秒为单位）。
用法：float framePeriod=frame.timestamp()-controller.frame(1).timestamp();
Tool tool(int32_t id): 表示这一帧中具有特定ID的Tool对象。用这个函数可以用一个ID值从这帧中重新得到这个Tool对象，这个ID值是从上一帧中得到的。如果现在没有带有那个特有ID值的工具，则会返回一个无效的Tool对象。这个ID值是跨帧不变的，直到跟踪失败。如果工具的跟踪丢了之后又重新得到，则代表那个工具的新的Tool对象会带有不同的ID。
用法：Leap::Tool toolOfinterest=frame.tool(toolID);
ToolList tools(): 代表这帧中检测到的Tool对象的列表（任意顺序）。如果没有检测到工具，则该列表为空。
用法：Leap:: ToolList toolsInFrame=frame. tools ();
std::string toString(): 一个包含简略描述该Frame对象的字符串。
TrackedQuad trackedQuad(): 这个类仅仅是内部使用，返回画面中检测到的Quad的信息。
Vector translation(const Frame & sinceFrame): 表示当前帧和指定帧之间线性运动位置的变化。返回的平移向量提供了移动的大小和方向（毫米为单位）。
用法：Leap::Vector linearMovement=frame.translation(startFrame);

float translationProbability(const Frame & sinceFrame): 从当前帧到指定帧整体运动被认为是一种平移运动的概率。
用法：float translationDominance=frame. translationProbability (startFrame);
const Frame & invalid(): 返回一个无效的Frame对象。还是用来判断对象是否有效。

译自：https://developer.leapmotion.com/documentation/cpp/api/Leap.Frame.html