API odtwarzania Azure Kinect

Zestaw SDK czujnika udostępnia interfejs API do rejestrowania danych urządzenia w pliku Matroska (.mkv). Format kontenera Matroska przechowuje ścieżki wideo, próbki IMU i kalibrację urządzenia. Nagrania można wygenerować przy użyciu dostarczonego narzędzia wiersza polecenia k4arecorder . Nagrania można również dostosowywać i nagrywać bezpośrednio przy użyciu API do nagrywania.

Aby uzyskać więcej informacji na temat interfejsu API nagrywania, zobacz k4a_record_create().

Aby uzyskać więcej informacji na temat specyfikacji formatu pliku Matroska, zobacz stronę Format pliku nagrywania .

Korzystanie z interfejsu API odtwarzania

Pliki nagrywania można otwierać przy użyciu interfejsu API odtwarzania. Interfejs API odtwarzania zapewnia dostęp do danych czujników w tym samym formacie co reszta zestawu SDK czujnika.

Otwieranie pliku rekordu

W poniższym przykładzie otwieramy nagranie przy użyciu k4a_playback_open(), wyświetlamy długość nagrania, a następnie zamykamy plik przy użyciu 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);

Przeglądaj przechwycenia

Po otwarciu pliku możemy odczytać przechwycone dane z nagrania. W następnym przykładzie odczytane zostaną wszystkie przechwyty w pliku.

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;
}

Wyszukiwanie w nagraniu

Po osiągnięciu końca pliku możemy chcieć wrócić i odczytać go ponownie. Ten proces można wykonać, odczytując wstecz z k4a_playback_get_previous_capture(), ale może to być bardzo powolne w zależności od długości nagrania. Zamiast tego możemy użyć funkcji k4a_playback_seek_timestamp(), aby przejść do określonego punktu w pliku.

W tym przykładzie określamy znaczniki czasu w mikrosekundach, aby wyszukiwać różne punkty w pliku.

// 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;
}

Odczytywanie informacji o tagach

Nagrania mogą również zawierać różne metadane, takie jak numer seryjny urządzenia i wersje oprogramowania układowego. Te metadane są przechowywane w tagach rejestrowania, do których można uzyskać dostęp przy użyciu funkcji 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");
}

Lista tagów danych

Poniżej znajduje się lista wszystkich tagów domyślnych, które mogą być zawarte w pliku nagrywania. Wiele z tych wartości jest dostępnych w ramach struktury k4a_record_configuration_t i można je odczytać za pomocą funkcji k4a_playback_get_record_configuration().

Jeśli tag nie istnieje, przyjmuje się, że ma wartość domyślną.

Synchronizacja sygnatur czasowych

Format Matroska wymaga, że nagrania muszą zaczynać się od znacznika czasu o wartości zero. Podczas zewnętrznej synchronizacji kamer pierwszy znacznik czasu z każdego urządzenia może być inny niż zero.

Aby zachować oryginalne znaczniki czasu z urządzeń między nagrywaniem a odtwarzaniem, plik przechowuje przesunięcie do zastosowania do znaczników czasu.

Tag K4A_START_OFFSET_NS służy do określania przesunięcia znacznika czasu, dzięki czemu pliki można ponownie zsynchronizować po nagraniu. To przesunięcie znacznika czasu można dodać do każdego znacznika czasu w pliku, aby odtworzyć oryginalne znaczniki czasu urządzenia.

Przesunięcie początkowe jest również dostępne w strukturze k4a_record_configuration_t.