L'API di riproduzione di Azure Kinect

  • Articolo

L'SDK del sensore fornisce un'API per registrare i dati dei dispositivi in un file Matroska (.mkv). Il formato contenitore Matroska archivia tracce video, esempi di IMU e calibrazione del dispositivo. Le registrazioni possono essere generate usando l'utility di riga di comando k4arecorder fornita. Le registrazioni possono anche essere personalizzate e registrate direttamente usando l'API di registrazione.

Per ulteriori informazioni sull'API di registrazione, vedere k4a_record_create().

Per ulteriori informazioni sulle specifiche del formato di file Matroska, vedere la pagina Formato di file di registrazione.

Usare l'API di riproduzione

È possibile aprire i file di registrazione usando l'API di riproduzione. L'API di riproduzione fornisce l'accesso ai dati del sensore nello stesso formato del resto dell'SDK del sensore.

Aprire un file di registrazione

L'esempio seguente mostra come aprire una registrazione usando k4a_playback_open(), stampare la lunghezza della registrazione e chiudere il file con 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);

Leggere le acquisizioni

Una volta aperto il file, è possibile iniziare a leggere le acquisizioni dalla registrazione. Nell'esempio successivo viene letta ciascuna delle acquisizioni nel file.

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

Cercare all'interno di una registrazione

Dopo aver raggiunto la fine del file, è possibile tornare indietro e leggerlo di nuovo. Questo processo può essere eseguito leggendo a ritroso con k4a_playback_get_previous_capture(), ma potrebbe risultare molto lento in base alla lunghezza della registrazione. È invece possibile usare la funzione k4a_playback_seek_timestamp() per andare a un punto specifico nel file.

In questo esempio si specificano timestamp in microsecondi per cercare vari punti nel file.

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

Leggere le informazioni sul tag

Le registrazioni possono contenere anche vari metadati, ad esempio il numero di serie del dispositivo e le versioni del firmware. Questi metadati vengono archiviati nei tag di registrazione, a cui è possibile accedere usando la funzione 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");
}

Elenco di tag di registrazione

Di seguito è riportato un elenco di tutti i tag predefiniti che possono essere inclusi in un file di registrazione. Molti di questi valori sono disponibili come parte dello struct k4a_record_configuration_t e possono essere letti con la funzione k4a_playback_get_record_configuration().

Se un tag non esiste, si presuppone che abbia il valore predefinito.

Nome del tag Valore predefinito Campo k4a_record_configuration_t Note
K4A_COLOR_MODE "OFF" color_format / color_resolution Valori possibili: "OFF", "MJPG_1080P", "NV12_720P", "YUY2_720P" e così via
K4A_DEPTH_MODE "OFF" depth_mode / depth_track_enabled Valori possibili: "OFF", "NFOV_UNBINNED", "PASSIVE_IR" e così via
K4A_IR_MODE "OFF" depth_mode / ir_track_enabled Valori possibili: "OFF", "ACTIVE", "PASSIVE"
K4A_IMU_MODE "OFF" imu_track_enabled I valori possibili sono: "ON", "OFF"
K4A_CALIBRATION_FILE "calibration.json" N/D Vedere k4a_device_get_raw_calibration()
K4A_DEPTH_DELAY_NS "0" depth_delay_off_color_usec Valore archiviato in nanosecondi; l'API fornisce microsecondi.
K4A_WIRED_SYNC_MODE "STANDALONE" wired_sync_mode Valori possibili: "STANDALONE", "MASTER", "SUBORDINATE"
K4A_SUBORDINATE_DELAY_NS "0" subordinate_delay_off_master_usec Valore archiviato in nanosecondi; l'API fornisce microsecondi.
K4A_COLOR_FIRMWARE_VERSION "" N/D Versione del firmware a colori del dispositivo, ad esempio "1.x.xx"
K4A_DEPTH_FIRMWARE_VERSION "" N/D Versione del firmware di profondità del dispositivo, ad esempio "1.x.xx"
K4A_DEVICE_SERIAL_NUMBER "" N/D Registrare il numero di serie del dispositivo
K4A_START_OFFSET_NS "0" start_timestamp_offset_usec Vedere Sincronizzazione timestamp di seguito.
K4A_COLOR_TRACK None N/D Vedere Formato di file di registrazione - Identificazione delle tracce.
K4A_DEPTH_TRACK None N/D Vedere Formato di file di registrazione - Identificazione delle tracce.
K4A_IR_TRACK None N/D Vedere Formato di file di registrazione - Identificazione delle tracce.
K4A_IMU_TRACK None N/D Vedere Formato di file di registrazione - Identificazione delle tracce.

Sincronizzazione timestamp

Il formato Matroska richiede che le registrazioni inizino con un timestamp pari a zero. Quando si sincronizzano le fotocamere esternamente, il primo timestamp di ogni dispositivo può essere diverso da zero.

Per mantenere i timestamp originali dei dispositivi tra registrazione e riproduzione, il file archivia un offset da applicare ai timestamp.

Il tag K4A_START_OFFSET_NS viene usato per specificare un offset di timestamp in modo che i file possano essere risincronizzati dopo la registrazione. Questo offset di timestamp può essere aggiunto a ogni timestamp nel file per ricostruire i timestamp originali del dispositivo.

L'offset iniziale è disponibile anche nello struct k4a_record_configuration_t.