Die Azure Kinect-Wiedergabe-API

Das Sensor-SDK stellt eine API zum Aufzeichnen von Gerätedaten in eine Matroska -Datei (mkv) bereit. Das Matroska-Containerformat speichert Videospuren, IMU-Beispiele und Gerätekalibrierungen. Aufzeichnungen können mithilfe des bereitgestellten Befehlszeilenprogramms k4arecorder generiert werden. Aufzeichnungen können auch direkt mithilfe der Datensatz-API angepasst und aufgezeichnet werden.

Weitere Informationen zur Aufzeichnungs-API finden Sie unter k4a_record_create().

Weitere Informationen zu den Matroska-Dateiformatspezifikationen finden Sie auf der Seite "Aufzeichnungsdateiformat ".

Verwenden der Wiedergabe-API

Aufzeichnungsdateien können mithilfe der Wiedergabe-API geöffnet werden. Die Wiedergabe-API bietet Zugriff auf Sensordaten im selben Format wie der Rest des Sensor-SDK.

Öffnen einer Datensatzdatei

Im folgenden Beispiel wird eine Aufzeichnung mit k4a_playback_open()geöffnet, die Aufzeichnungslänge gedruckt und dann mit k4a_playback_close()geschlossen.

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

Leseaufzeichnungen

Sobald die Datei geöffnet ist, können wir mit dem Lesen von Aufzeichnungen beginnen. Im nächsten Beispiel werden alle Aufzeichnungen in der Datei gelesen.

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

Suchen innerhalb einer Aufzeichnung

Nachdem wir das Ende der Datei erreicht haben, möchten wir möglicherweise zurückkehren und es erneut lesen. Dieser Vorgang kann durch Rückwärtslesen mit k4a_playback_get_previous_capture()durchgeführt werden, kann aber je nach Länge der Aufzeichnung sehr langsam sein. Stattdessen können wir die k4a_playback_seek_timestamp()-Funktion verwenden, um zu einem bestimmten Punkt in der Datei zu wechseln.

In diesem Beispiel geben wir Zeitstempel in Mikrosekunden an, um verschiedene Punkte in der Datei zu suchen.

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

Lesen von Taginformationen

Aufzeichnungen können auch verschiedene Metadaten enthalten, z. B. die Seriennummer des Geräts und Firmwareversionen. Diese Metadaten werden in Aufzeichnungstags gespeichert, auf die mithilfe der k4a_playback_get_tag()-Funktion zugegriffen werden kann.

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

Eintrags-Tag-Liste

Nachfolgend finden Sie eine Liste aller Standardtags, die in einer Aufzeichnungsdatei enthalten sein können. Viele dieser Werte sind als Teil der k4a_record_configuration_t Struktur verfügbar und können mit der k4a_playback_get_record_configuration()-Funktion gelesen werden.

Wenn ein Tag nicht existiert, wird angenommen, dass der Standardwert angenommen wird.

Zeitstempelsynchronisierung

Das Matroska-Format erfordert, dass Aufzeichnungen mit einem Zeitstempel von Null beginnen müssen. Wenn Kameras extern synchronisiert werden, kann der erste Zeitstempel von jedem Gerät aus ungleich Null sein.

Um die ursprünglichen Zeitstempel von den Geräten zwischen Aufzeichnung und Wiedergabe beizubehalten, speichert die Datei einen Offset, der auf die Zeitstempel angewendet werden soll.

Das K4A_START_OFFSET_NS-Tag wird verwendet, um einen Timestamp-Offset anzugeben, damit Dateien nach der Aufzeichnung erneut synchronisiert werden können. Dieser Zeitstempeloffset kann jedem Zeitstempel in der Datei hinzugefügt werden, um die ursprünglichen Gerätezeitstempel zu rekonstruieren.

Der Anfangsoffset ist auch in der k4a_record_configuration_t Struktur verfügbar.