API воспроизведения Azure Kinect

Пакет 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	Нет	Н/Д	См. Запись формата файла — определение дорожек.
K4A_DEPTH_TRACK	Нет	Н/Д	См. Запись формата файла — определение дорожек.
K4A_IR_TRACK	Нет	Н/Д	См. Запись формата файла — определение дорожек.
K4A_IMU_TRACK	Нет	Н/Д	См. Запись формата файла — определение дорожек.

Синхронизация меток времени

Для формата Matroska необходимо, чтобы записи начинались с нулевой метки времени. При внешней синхронизации камер первая метка времени каждого устройства может быть не равна нулю.

Чтобы сохранить исходные метки времени с устройств между записью и воспроизведением, в файле хранится смещение, применяемое к отметкам времени.

K4A_START_OFFSET_NSТег используется для указания смещения отметки времени, чтобы файлы можно было повторно синхронизировать после записи. Это смещение отметки времени может быть добавлено к каждой метке времени в файле для восстановления исходных меток времени для устройств.

Начальное смещение также доступно в структуре k4a_record_configuration_t.