Tango 开发指南(3) — Pose

获取 Pose
方法一
方法二
状态
状态的生命周期
使用 Pose 状态
原文链接：https://developers.google.com/tango/overview/poses

TangoPoseData Java API

As your device moves through 3D space, it calculates where it is (position) and how it’s rotated (orientation) up to 100 times per second. A single instance of this combined calculation is called the device’s pose. The pose is an essential concept when working with motion tracking, area learning, or depth perception.

Pose概念
当 Tango 设备在 3D 空间中移动时，它会以 100次/秒的频率计算出自己当前的位置信息以及旋转状态。这两种数据的集合，我们称之为 pose。在跟三种核心技术打交道的过程中，pose 是个很重要的概念。

To calculate the poses, you must choose base and target frames of reference , which may use different coordinate systems. You can view a pose as the translation and rotation required to transform vertices from the target frame to the base frame.

为了计算出 pose，开发者必须选定基础参考帧和目标参考帧，二者可能使用的是不同的坐标系。你可以把 pose 看成是一种转换和旋转，用来将目标参考帧中的坐标点转换成基础参考帧中的坐标点。

Here is a simplified version of a Tango pose struct in C:
下面是简化版的 pose 数据结构的 C 语言描述：

struct PoseData {
    double orientation[4];
    double translation[3];
}

The two key components of a pose are:

A quaternion that defines the rotation of the target frame with respect to the base frame.
A 3D vector that defines the translation of the target frame with respect to the base frame.
An actual pose struct contains other fields, such as a timestamp and a copy of the frame pair, as you’ll see below.
Note: The examples on this page use the C API, but function calls and data structures are similar for Java. In Unity, there are prefabs which handle a lot of these details for you.
pose 结构体中的两个关键元素分别是：

四元组，描述目标帧相对于其基础帧的旋转信息；
三维向量，描述目标帧和基础帧之间的转换关系；
实际的 pose 结构体中还包含其他字段，比如时间戳和帧对（frame pair）的拷贝，这些我们后面会看到。

注意：本文中的例子使用 C 语言描述的，但是函数调用和数据结构与 Java 很像。在 Unity 中，会有对应的 API 来处理这些细节。
获取 Pose

You can request pose data in two ways:
有两种方法得到 pose 数据：

方法一

Poll for poses using TangoService_getPoseAtTime(). This returns the pose closest to a given timestamp from the base to the target frame. Here is the code for this function in the C API:
TangoService_getPoseAtTime()，该方法返回某时间戳对应时刻的 pose 数据，C 语言用法为：

TangoErrorType TangoService_getPoseAtTime(
    double timestamp,
     TangoCoordinateFramePair frame_pair,
     TangoPoseData* pose);

The TangoCoordinateFramePair struct specifies the base frame and the target frame.
TangoCoordinateFramePair 参数是指定的基础帧和目标帧。

Note: If you are making an augmented reality app, we recommend that you use TangoService_getPoseAtTime() or TangoSupport_getPoseAtTime() because, in addition to polling for poses, they allow you to align the pose timestamps with the video frames.
注意：如果你在开发AR应用，我们建议你使用TangoService_getPoseAtTime()或者TangoSupport_getPoseAtTime()，因为这两个方法不仅可以返回 pose 数据，还能让你对齐 pose 时间戳和视频帧。

The following code gets a pose of the device frame with respect to the start-of-service frame:
下面的代码获取的pose数据对应帧对是TANGO_COORDINATE_FRAME_DEVICE和 TANGO_COORDINATE_FRAME_START_OF_SERVICE：

TangoPoseData pose_start_service_T_device;
TangoCoordinateFramePair frame_pair;
frame_pair.base = TANGO_COORDINATE_FRAME_START_OF_SERVICE;
frame_pair.target = TANGO_COORDINATE_FRAME_DEVICE;
TangoService_getPoseAtTime(
    timestamp,
    frame_pair,
    &pose_start_service_T_device);

In this example, including the names of the base and target frames in the pose variable name makes the name more descriptive:
上述例子中，注意 pose 变量的命名，变量名中同时包含了基础和目标帧的类型，这种命名更有可读性：

TangoPoseData pose_start_service_T_device;

方法二

Receive pose updates as they become available. To do so, attach an onPoseAvailable() callback to TangoService_connectOnPoseAvailable(). This sample is from our hello_motion_tracking example project and can be found in the tango_handler.cc file:
如果你想在 pose 数据就绪是立即得到它，可以给 TangoService_connectOnPoseAvailable() 方法添加一个回调：onPoseAvailable()。下面的代码示例来自hello_motion_tracking中的 tango_handler.cc：

TangoCoordinateFramePair pair;
pair.base = TANGO_COORDINATE_FRAME_START_OF_SERVICE;
pair.target = TANGO_COORDINATE_FRAME_DEVICE;
if (TangoService_connectOnPoseAvailable(1, &pair, onPoseAvailable) !=
    TANGO_SUCCESS) {
  LOGE("TangoHandler::ConnectTango, connectOnPoseAvailable error.");
  std::exit(EXIT_SUCCESS);

列表内容

In both cases, you receive a TangoPoseData struct:
通过上述两种方法，你都能获得一个叫 TangoPoseData 的结构体：

typedef struct TangoPoseData {
  int version;
  double timestamp;                // In milliseconds
  double orientation[4];           // As a quaternion
  double translation[3];           // In meters
  TangoPoseStatusType status_code;
  TangoCoordinateFramePair frame;
  int confidence;                  // Currently unused
  float accuracy;                  // Currently unused
} TangoPoseData;

状态

TangoPoseData contains a state, denoted by the TangoPoseStatusType enum, which provides information about the status of the pose estimation system. The available TangoPoseStatusType members are:
TangoPoseData 包含一个 state 字段，是一个 TangoPoseStatusType 的枚举类型，通过该字段我们能得知当前 pose 的状态。TangoPoseStatusType 具体成员如下：

typedef enum {
  TANGO_POSE_INITIALIZING = 0,
  TANGO_POSE_VALID,
  TANGO_POSE_INVALID,
  TANGO_POSE_UNKNOWN
} TangoPoseStatusType;

INITIALIZING: The motion tracking system is either starting or recovering from an invalid state, and the pose data should not be used.
VALID: The system believes the poses being returned are valid and should be used.
INVALID: The system has encountered difficulty of some kind, so pose estimations are likely incorrect.
UNKNOWN: The system is in an unknown state.

INITIALIZING：运动追踪系统正在启动或者正在从 INVALID 状态恢复，不应使用此时的 pose 数据；
VALID：合法的 pose 数据，可以使用；
INVALID：系统遇到问题，此时的 pose 数据很可能是不正确的；
UNKNOWN：系统处于未知状态；

状态的生命周期

Figure 1: Tango Pose data lifecycle
The TANGO_POSE_INITIALIZING status code indicates that the Tango framework is initializing and pose data is not yet available. If you are using callbacks, you will receive only one pose update with the status code set to TANGO_POSE_INITIALIZING while the framework is initializing.

图1：pose 数据生命周期

如果你得到TANGO_POSE_INITIALIZING状态，说明系统证在初始化，尚无法得到pose数据。如果此时你使用了回调，回调依然会执行，只不过你得到的pose数据里面status字段值是TANGO_POSE_INITIALIZING。

After initialization finishes, poses are in the TANGO_POSE_VALID state. If you are using callbacks, you will receive updates as frequently as they are available.
初始化完成后，pose 数据就处于 TANGO_POSE_VALID 状态了。如果此时你在使用回调，一旦数据就绪你就会得到通知。

If the system encounters difficulty and enters the TANGO_POSE_INVALID state, recovery depends on your configuration during initialization. If config_enable_auto_recovery is set to True, the system immediately resets the motion tracking system and enters the TANGO_POSE_INITIALIZING state. If config_enable_auto_recovery is set to False, pose data remains in the TANGO_POSE_INVALID state and no updates are received until you call TangoService_resetMotionTracking().
如果系统遇到问题并进入了 TANGO_POSE_INVALID 状态，是否能恢复则取决于你的配置。如果配置中 config_enable_auto_recovery=true，系统会立即重启运动追踪系统并进入TANGO_POSE_INITIALIZING状态。如果config_enable_auto_recovery = false，pose 数据会停留在TANGO_POSE_INVALID状态，而且你不会接收到数据更新，除非显式的调用TangoService_resetMotionTracking()。

使用 Pose 状态

Your application should React to the status being returned within the pose data. For example, wait until the pose data you are interested in becomes valid before starting interactions in your application. If the pose becomes invalid, pause interactions until after the system recovers. Depending on your application, what you do after the system recovers will vary. If you are using motion tracking alone, you can simply resume your application. If you are using area learning or ADFs, instruct your user to move around until the device can localize itself.
开发者的应用应当时刻关注 pose 数据状态的变化并作出处理。例如，你应当一直等到 pose 变成 VALID 状态时才能允许应用的交互操作。如果 pose 变成了 INVALID 状态，应当停止交互直到系统恢复正常。应用不同，系统恢复后你要做的事情也不同。如果你只是使用运动追踪功能，继续运行应用就可以了。如果你在使用区域学习或 ADF，你得提示用户四处走动直到设备能够定位自己。

一些术语：

1. VIO，visual-inertial odometry，视觉惯性里程计，用现在所处的位置去对比设备起始点的位置。而这个位置的移动是通过tango的广角（鱼眼）镜头所看到的视觉特征（features）判断出来的；
2. IMU，inertial measurement unit，惯性测量单元是测量物体三轴姿态角以及加速度的装置。一般的，一个IMU内会装有三轴的陀螺仪和三个方向的加速度计，来测量物体在三维空间中的角速度和加速度，并以此解算出物体的姿态。为了提高可靠性，还可以为每个轴配备更多的传感器；
3. ADF，area description file