Freigeben über

Die Azure Kinect-Wiedergabe-API

  • Artikel

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

Liste der Aufzeichnungstags

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.