API de reproducción de Azure Kinect

  • Artículo

El SDK del sensor proporciona una API para grabar los datos del dispositivo en un archivo Matroska (.mkv). El formato de contenedor Matroska almacena pistas de vídeo, muestras de IMU e información de calibración del dispositivo. Las grabaciones se pueden generar mediante la utilidad de línea de comandos (k4arecorder) proporcionada. Las grabaciones también se pueden personalizar y registrar directamente con la API de grabación.

Para más información sobre la API de grabación, consulte k4a_record_create().

Para más información sobre las especificaciones de formato de archivo Matroska, consulte la página Formato de archivo de grabación.

Uso de la API de reproducción

Los archivos de grabación pueden abrirse mediante la API de reproducción. La API de reproducción proporciona acceso a los datos del sensor en el mismo formato que el resto del SDK del sensor.

Apertura de un archivo de grabación

En el ejemplo siguiente, se abre una grabación mediante k4a_playback_open(), se imprime la longitud de la grabación y, luego, se cierra el archivo 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);

Lectura de las capturas

Una vez abierto el archivo, podemos empezar a leer las capturas de la grabación. En el siguiente ejemplo se leerá cada una de las capturas del archivo.

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

Búsqueda en una grabación

Una vez que se llega al final del archivo, es posible que quiera retroceder y leerlo de nuevo. Este proceso puede realizarse leyendo hacia atrás con k4a_playback_get_previous_capture(), pero podría ser muy lento en función de la longitud de la grabación. Puede usar mejor la función k4a_playback_seek_timestamp() para desplazarse a un punto específico del archivo.

En este ejemplo, se especifican las marcas de tiempo en microsegundos para buscar varios puntos en el archivo.

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

Lectura de la información de etiqueta

Las grabaciones también pueden contener varios metadatos, como el número de serie y las versiones de firmware del dispositivo. Estos metadatos se almacenan en etiquetas de grabación, a las que se puede acceder con la función 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 de etiquetas de grabación

A continuación, se muestra una lista de todas las etiquetas predeterminadas que se pueden incluir en un archivo de grabación. Muchos de estos valores están disponibles como parte de la estructura k4a_record_configuration_t y se pueden leer con la función k4a_playback_get_record_configuration().

Si no existe una etiqueta, se supone que tiene el valor predeterminado.

Nombre de etiqueta Valor predeterminado k4a_record_configuration_t Campo Notas
K4A_COLOR_MODE "OFF" color_format / color_resolution Valores posibles: "OFF", "MJPG_1080P", "NV12_720P", "YUY2_720P", etc.
K4A_DEPTH_MODE "OFF" depth_mode / depth_track_enabled Valores posibles: "OFF, "NFOV_UNBINNED", "PASSIVE_IR", etc.
K4A_IR_MODE "OFF" depth_mode / ir_track_enabled Valores posibles: "OFF", "ACTIVE", "PASSIVE"
K4A_IMU_MODE "OFF" imu_track_enabled Valores posibles: "ON", "OFF"
K4A_CALIBRATION_FILE "calibration.json" N/D Vea k4a_device_get_raw_calibration().
K4A_DEPTH_DELAY_NS "0" depth_delay_off_color_usec Valor almacenado en nanosegundos; la API proporciona microsegundos.
K4A_WIRED_SYNC_MODE "STANDALONE" wired_sync_mode Valores posibles: "STANDALONE", "MASTER", "SUBORDINATE"
K4A_SUBORDINATE_DELAY_NS "0" subordinate_delay_off_master_usec Valor almacenado en nanosegundos; la API proporciona microsegundos.
K4A_COLOR_FIRMWARE_VERSION "" N/D Versión de firmware del color del dispositivo, por ejemplo "1.x.xx".
K4A_DEPTH_FIRMWARE_VERSION "" N/D Versión de firmware de la profundidad del dispositivo, por ejemplo "1.x.xx".
K4A_DEVICE_SERIAL_NUMBER "" N/D Número de serie del dispositivo de grabación.
K4A_START_OFFSET_NS "0" start_timestamp_offset_usec Consulte a continuación Sincronización de las marcas de tiempo.
K4A_COLOR_TRACK None N/D Consulte Formato del archivo de grabación: identificación de las pistas.
K4A_DEPTH_TRACK None N/D Consulte Formato del archivo de grabación: identificación de las pistas.
K4A_IR_TRACK None N/D Consulte Formato del archivo de grabación: identificación de las pistas.
K4A_IMU_TRACK None N/D Consulte Formato del archivo de grabación: identificación de las pistas.

Sincronización de las marcas de tiempo

El formato Matroska requiere que las grabaciones comiencen con una marca de tiempo de cero. Al sincronizar las cámaras de forma externa, la primera marca de tiempo de cada dispositivo puede ser distinta de cero.

Para conservar las marcas de tiempo originales de los dispositivos entre grabación y reproducción, el archivo almacena un desplazamiento que se aplica a las marcas de tiempo.

La etiqueta K4A_START_OFFSET_NS se usa para especificar un desplazamiento de la marca de tiempo de forma que los archivos se puedan volver a sincronizar después de la grabación. Este desplazamiento se puede agregar a cada marca de tiempo del archivo para reconstruir las marcas de tiempo del dispositivo originales.

El desplazamiento inicial también está disponible en la estructura k4a_record_configuration_t.