Azure Kinect 播放 API

项目
06/26/2019

传感器 SDK 提供一个 API 用于将设备数据记录到 Matroska (.mkv) 文件。 Matroska 容器格式可存储视频篇目、IMU 样本和设备校准结果。可以使用随附的 k4arecorder 命令行实用工具生成录制内容。还可以直接使用录制 API 录制内容以及自定义录制的内容。

有关录制 API 的详细信息，请参阅 k4a_record_create()。

有关 Matroska 文件格式规范的详细信息，请参阅录制文件格式页。

使用播放 API

可以使用播放 API 打开录制文件。通过播放 API 可以访问格式与其他传感器 SDK 相同的传感器数据。

打开录制文件

在以下示例中，我们将使用 k4a_playback_open() 打开一个录制文件，输出录制长度，然后使用 k4a_playback_close() 关闭该文件。

k4a_playback_t playback_handle = NULL;
if (k4a_playback_open("recording.mkv", &playback_handle) != K4A_RESULT_SUCCEEDED)
{
    printf("Failed to open recording\n");
    return 1;
}

uint64_t recording_length = k4a_playback_get_last_timestamp_usec(playback_handle);
printf("Recording is %lld seconds long\n", recording_length / 1000000);

k4a_playback_close(playback_handle);

读取捕获

打开文件后，可以开始读取录制内容中的捕获。以下示例将读取文件中的每个捕获。

k4a_capture_t capture = NULL;
k4a_stream_result_t result = K4A_STREAM_RESULT_SUCCEEDED;
while (result == K4A_STREAM_RESULT_SUCCEEDED)
{
    result = k4a_playback_get_next_capture(playback_handle, &capture);
    if (result == K4A_STREAM_RESULT_SUCCEEDED)
    {
        // Process capture here
        k4a_capture_release(capture);
    }
    else if (result == K4A_STREAM_RESULT_EOF)
    {
        // End of file reached
        break;
    }
}
if (result == K4A_STREAM_RESULT_FAILED)
{
    printf("Failed to read entire recording\n");
    return 1;
}

在录制内容中查找

到达文件末尾后，我们可能需要返回并再次读取。若要完成此过程，可以使用 k4a_playback_get_previous_capture() 进行回读，但根据录制内容的长度，这种做法可能非常缓慢。我们可以改用 k4a_playback_seek_timestamp() 函数转到文件中的特定点。

在此示例中，我们以微秒为单位指定了时间戳，以定位到文件中的各个点。

// Seek to the beginning of the file
if (k4a_playback_seek_timestamp(playback_handle, 0, K4A_PLAYBACK_SEEK_BEGIN) != K4A_RESULT_SUCCEEDED)
{
    return 1;
}

// Seek to the end of the file
if (k4a_playback_seek_timestamp(playback_handle, 0, K4A_PLAYBACK_SEEK_END) != K4A_RESULT_SUCCEEDED)
{
    return 1;
}

// Seek to 10 seconds from the start
if (k4a_playback_seek_timestamp(playback_handle, 10 * 1000000, K4A_PLAYBACK_SEEK_BEGIN) != K4A_RESULT_SUCCEEDED)
{
    return 1;
}

// Seek to 10 seconds from the end
if (k4a_playback_seek_timestamp(playback_handle, -10 * 1000000, K4A_PLAYBACK_SEEK_END) != K4A_RESULT_SUCCEEDED)
{
    return 1;
}

读取标记信息

录制内容还可能包含各种元数据，例如设备序列号和固件版本。此元数据存储在录制标记中，可以使用 k4a_playback_get_tag() 函数来访问。

// Print the serial number of the device used to record
char serial_number[256];
size_t serial_number_size = 256;
k4a_buffer_result_t buffer_result = k4a_playback_get_tag(playback_handle, "K4A_DEVICE_SERIAL_NUMBER", &serial_number, &serial_number_size);
if (buffer_result == K4A_BUFFER_RESULT_SUCCEEDED)
{
    printf("Device serial number: %s\n", serial_number);
}
else if (buffer_result == K4A_BUFFER_RESULT_TOO_SMALL)
{
    printf("Device serial number too long.\n");
}
else
{
    printf("Tag does not exist. Device serial number was not recorded.\n");
}

下面是可以包含在录制文件中的所有默认标记的列表。其中的许多值可用作 k4a_record_configuration_t 结构的一部分，可以使用 k4a_playback_get_record_configuration() 函数来读取。

如果某个标记不存在，则假设采用默认值。

标记名称	默认值	`k4a_record_configuration_t` 字段	备注
`K4A_COLOR_MODE`	"OFF"	`color_format` / `color_resolution`	可能的值："OFF"、"MJPG_1080P"、"NV12_720P"、"YUY2_720P" 等
`K4A_DEPTH_MODE`	"OFF"	`depth_mode` / `depth_track_enabled`	可能的值："OFF"、"NFOV_UNBINNED"、"PASSIVE_IR" 等
`K4A_IR_MODE`	"OFF"	`depth_mode` / `ir_track_enabled`	可能的值："OFF"、"ACTIVE"、"PASSIVE"
`K4A_IMU_MODE`	"OFF"	`imu_track_enabled`	可能的值："ON"、"OFF"
`K4A_CALIBRATION_FILE`	"calibration.json"	不适用	请参见`k4a_device_get_raw_calibration()`
`K4A_DEPTH_DELAY_NS`	"0"	`depth_delay_off_color_usec`	值以纳秒为单位存储，API 以微秒为单位。
`K4A_WIRED_SYNC_MODE`	"STANDALONE"	`wired_sync_mode`	可能的值："STANDALONE"、"MASTER"、"SUBORDINATE"
`K4A_SUBORDINATE_DELAY_NS`	"0"	`subordinate_delay_off_master_usec`	值以纳秒为单位存储，API 以微秒为单位。
`K4A_COLOR_FIRMWARE_VERSION`	%>	不适用	设备颜色固件版本，例如 "1.x.xx"
`K4A_DEPTH_FIRMWARE_VERSION`	%>	不适用	设备深度固件版本，例如 "1.x.xx"
`K4A_DEVICE_SERIAL_NUMBER`	%>	不适用	录制设备序列号
`K4A_START_OFFSET_NS`	"0"	`start_timestamp_offset_usec`	请参阅下面的时间戳同步。
`K4A_COLOR_TRACK`	None	不适用	请参阅录制文件格式 - 识别篇目。
`K4A_DEPTH_TRACK`	None	不适用	请参阅录制文件格式 - 识别篇目。
`K4A_IR_TRACK`	None	不适用	请参阅录制文件格式 - 识别篇目。
`K4A_IMU_TRACK`	None	不适用	请参阅录制文件格式 - 识别篇目。

时间戳同步

Matroska 格式要求录制内容必须以时间戳 0 开头。在外部同步相机时，每个设备中的第一个时间戳可以不为 0。

为了在录制和播放之间切换时保留设备的原始时间戳，该文件会存储一个要应用到时间戳的偏移量。

K4A_START_OFFSET_NS 标记用于指定时间戳偏移量，以便在录制后可以重新同步文件。可将此时间戳偏移量添加到文件中的每个时间戳，以重新构造原始设备时间戳。

起始偏移量也会在 k4a_record_configuration_t 结构中提供。

通过