Die Azure Kinect-Wiedergabe-API

Artikel
06/01/2023

Das Sensor-SDK beinhaltet eine API, um Gerätedaten in einer Matroska-Datei (.mkv) zu erfassen. Im Matroska-Containerformat werden Videospuren, IME-Beispiele und die Gerätekalibrierung gespeichert. Aufzeichnungen können über das bereitgestellte Befehlszeilen-Hilfsprogramm k4arecorder generiert werden. Über die Aufnahme-API können diese Aufzeichnungen zudem angepasst und direkt erfasst werden.

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

Weitere Informationen zu den Spezifikationen des Matroska-Dateiformats finden Sie unter Format der Aufzeichnungsdatei.

Verwenden der Wiedergabe-API

Aufzeichnungsdateien können mit der Wiedergabe-API geöffnet werden. Die Wiedergabe-API bietet Zugriff auf Sensordaten im gleichen Format wie die übrigen Elemente des Sensor-SDKs.

Öffnen einer Aufzeichnungsdatei

Im folgenden Beispiel wird unter Verwendung von k4a_playback_open() eine Aufzeichnungsdatei geöffnet. Dann wird die Aufzeichnungslänge gedruckt und die Datei 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);

Lesen von Aufnahmen

Nachdem die Datei geöffnet wurde, können wir mit dem Lesen von Aufnahmen in der Aufzeichnung beginnen. Im nächsten Beispiel werden die einzelnen Aufnahmen 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

Sobald wir das Ende der Datei erreicht haben, kann es sinnvoll oder erforderlich sein, die Datei noch einmal zu lesen. Dazu können wir die Datei mit k4a_playback_get_previous_capture() rückwärts lesen. Dieser Vorgang kann abhängig von der Länge der Aufzeichnung jedoch sehr langsam sein. Stattdessen können wir mit der Funktion k4a_playback_seek_timestamp() zu einer bestimmten Stelle innerhalb der Datei wechseln.

In diesem Beispiel geben wir Zeitstempel in Mikrosekunden an, um zu verschiedenen Punkten in der Datei zu gehen.

// 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 zudem über verschiedene Metadaten verfügen (z. B. die Seriennummer des Geräts oder Firmwareversionen). Diese Metadaten werden in Aufzeichnungstags gespeichert, auf die über die Funktion k4a_playback_get_tag() 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");
}

In der nachfolgenden Liste sind alle Standardtags aufgeführt, 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 Funktion k4a_playback_get_record_configuration() gelesen werden.

Wenn ein Tag nicht vorhanden ist, wird vom Standardwert ausgegangen.

Tag-Name	Standardwert	Feld `k4a_record_configuration_t`	Notizen
`K4A_COLOR_MODE`	„OFF“	`color_format` / `color_resolution`	Mögliche Werte: „OFF“, „MJPG_1080P“, „NV12_720P“, „YUY2_720P“ usw.
`K4A_DEPTH_MODE`	„OFF“	`depth_mode` / `depth_track_enabled`	Mögliche Werte: „OFF“, „NFOV_UNBINNED“, „PASSIVE_IR“ usw.
`K4A_IR_MODE`	„OFF“	`depth_mode` / `ir_track_enabled`	Mögliche Werte: „OFF“, „ACTIVE“, „PASSIVE“
`K4A_IMU_MODE`	„OFF“	`imu_track_enabled`	Mögliche Werte: „ON“, „OFF“
`K4A_CALIBRATION_FILE`	„calibration.json“	–	Siehe `k4a_device_get_raw_calibration()`.
`K4A_DEPTH_DELAY_NS`	"0"	`depth_delay_off_color_usec`	Der Wert wird in Nanosekunden gespeichert. Die API gibt Werte in Mikrosekunden an.
`K4A_WIRED_SYNC_MODE`	„STANDALONE“	`wired_sync_mode`	Mögliche Werte: „STANDALONE“, „MASTER“, „SUBORDINATE“
`K4A_SUBORDINATE_DELAY_NS`	"0"	`subordinate_delay_off_master_usec`	Der Wert wird in Nanosekunden gespeichert. Die API gibt Werte in Mikrosekunden an.
`K4A_COLOR_FIRMWARE_VERSION`	""	–	Firmwareversion der Farbeinheit, z. B. „1.x.xx“
`K4A_DEPTH_FIRMWARE_VERSION`	""	–	Firmwareversion der Tiefeneinheit, z. B. „1.x.xx“
`K4A_DEVICE_SERIAL_NUMBER`	""	–	Aufzeichnung der Seriennummer des Geräts
`K4A_START_OFFSET_NS`	"0"	`start_timestamp_offset_usec`	Weitere Informationen finden Sie unter Synchronisieren von Zeitstempeln weiter unten.
`K4A_COLOR_TRACK`	Keine	–	Weitere Informationen finden Sie unter Format der Aufzeichnungsdatei – Identifizieren von Spuren.
`K4A_DEPTH_TRACK`	Keine	–	Weitere Informationen finden Sie unter Format der Aufzeichnungsdatei – Identifizieren von Spuren.
`K4A_IR_TRACK`	Keine	–	Weitere Informationen finden Sie unter Format der Aufzeichnungsdatei – Identifizieren von Spuren.
`K4A_IMU_TRACK`	Keine	–	Weitere Informationen finden Sie unter Format der Aufzeichnungsdatei – Identifizieren von Spuren.

Synchronisieren von Zeitstempeln

Beim Matroska-Format ist es erforderlich, dass Aufzeichnungen mit dem Zeitstempel 0 beginnen. Bei der externen Synchronisierung von Kameras kann der Zeitstempel der einzelnen Geräte einen anderen Wert als 0 aufweisen.

Um die ursprünglichen Zeitstempel der Geräte zwischen Aufzeichnung und Wiedergabe beizubehalten, wird in der Datei ein Versatz zum Anwenden der Zeitstempel gespeichert.

Das Tag K4A_START_OFFSET_NS wird zum Angeben eines Zeitstempelversatzes verwendet, um Dateien nach der Aufzeichnung erneut synchronisieren zu können. Dieser Zeitstempelversatz kann zu jedem Zeitstempel innerhalb der Datei hinzugefügt werden, um die ursprünglichen Zeitstempel der Geräte wiederherzustellen.

Der Startversatz ist auch in der k4a_record_configuration_t-Struktur verfügbar.