Azure Kinect の再生 API

Sensor SDK には、デバイス データを Matroska (.mkv) ファイルに記録するための API が用意されています。 Matroska コンテナー形式では、ビデオ トラック、IMU サンプル、デバイス較正が格納されます。 記録は、提供されている k4arecorder コマンド ライン ユーティリティを使用して生成できます。 記録はまた、記録 API を使用して直接カスタマイズして記録することもできます。

記録 API の詳細については、「k4a_record_create()」を参照してください。

Matroska ファイル形式の仕様の詳細については、ファイル形式の記録に関するページを参照してください。

再生 API を使用する

記録ファイルは、再生 API を使用して開くことができます。 再生 API を使用すると、Sensor 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() 関数を使用して読み取ることができます。

タグが存在しない場合は、既定値が設定されていると見なされます。

タグ名	Default value	k4a_record_configuration_t のフィールド	Notes
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	なし	該当なし	ファイル形式の記録 - トラックの識別に関するページを参照してください。
K4A_DEPTH_TRACK	なし	該当なし	ファイル形式の記録 - トラックの識別に関するページを参照してください。
K4A_IR_TRACK	なし	該当なし	ファイル形式の記録 - トラックの識別に関するページを参照してください。
K4A_IMU_TRACK	なし	該当なし	ファイル形式の記録 - トラックの識別に関するページを参照してください。

タイムスタンプの同期

Matroska 形式では、記録が 0 のタイムスタンプから始まる必要があります。 カメラを外部と同期している場合は、各デバイスからの最初のタイムスタンプは 0 以外でもかまいません。

デバイスからの元のタイムスタンプを記録と再生の間で保持するために、ファイルには各タイムスタンプに適用されるオフセットが格納されます。

K4A_START_OFFSET_NS タグは、記録の後にファイルを再同期できるようにタイムスタンプ オフセットを指定するために使用されます。 このタイムスタンプ オフセットをファイル内の各タイムスタンプに追加すると、元のデバイス タイムスタンプを再構成できます。

この開始オフセットは、k4a_record_configuration_t 構造体でも使用できます。