Partilhar via

A API de reprodução do Azure Kinect

  • Artigo

O SDK do sensor fornece uma API para gravar dados do dispositivo em um arquivo Matroska (.mkv). O formato de contêiner Matroska armazena faixas de vídeo, amostras de IMU e calibração de dispositivos. As gravações podem ser geradas usando o utilitário de linha de comando k4arecorder fornecido. As gravações também podem ser personalizadas e gravadas diretamente usando a API de gravação.

Para obter mais informações sobre a API de gravação, consulte k4a_record_create().

Para obter mais informações sobre as especificações de formato de arquivo Matroska, consulte a página Formato de arquivo de gravação.

Usar a API de reprodução

Os arquivos de gravação podem ser abertos usando a API de reprodução. A API de reprodução fornece acesso aos dados do sensor no mesmo formato que o resto do SDK do sensor.

Abrir um ficheiro de registo

No exemplo a seguir, abrimos uma gravação usando k4a_playback_open(), imprimimos o comprimento da gravação e fechamos o arquivo com 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);

Leituras de capturas

Uma vez que o arquivo está aberto, podemos começar a ler capturas da gravação. Este próximo exemplo lerá cada uma das capturas no arquivo.

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

Procurar dentro de uma gravação

Depois de chegarmos ao final do arquivo, podemos querer voltar e lê-lo novamente. Este processo pode ser feito lendo para trás com k4a_playback_get_previous_capture(), mas pode ser muito lento, dependendo da duração da gravação. Em vez disso, podemos usar a k4a_playback_seek_timestamp() função para ir a um ponto específico no arquivo.

Neste exemplo, especificamos carimbos de data/hora em microssegundos para procurar vários pontos no arquivo.

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

Ler informações da tag

As gravações também podem conter vários metadados, como o número de série do dispositivo e versões de firmware. Esses metadados são armazenados em tags de gravação, que podem ser acessadas usando a k4a_playback_get_tag() função.

// 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 marcas de registro

Abaixo está uma lista de todas as tags padrão que podem ser incluídas em um arquivo de gravação. Muitos desses valores estão disponíveis como parte da k4a_record_configuration_t estrutura e podem ser lidos com a k4a_playback_get_record_configuration() função.

Se uma tag não existir, presume-se que ela tenha o valor padrão.

Nome do Sinalizador Valor Predefinido k4a_record_configuration_t Domínio Notas
K4A_COLOR_MODE "DESLIGADO" color_format / color_resolution Valores possíveis: "OFF", "MJPG_1080P", "NV12_720P", "YUY2_720P" e assim por diante
K4A_DEPTH_MODE "DESLIGADO" depth_mode / depth_track_enabled Valores possíveis: "OFF, "NFOV_UNBINNED", "PASSIVE_IR", e assim por diante
K4A_IR_MODE "DESLIGADO" depth_mode / ir_track_enabled Valores possíveis: "OFF", "ATIVE", "PASSIVE"
K4A_IMU_MODE "DESLIGADO" imu_track_enabled Valores possíveis: "ON", "OFF"
K4A_CALIBRATION_FILE "calibration.json" N/A Veja k4a_device_get_raw_calibration()
K4A_DEPTH_DELAY_NS "0" depth_delay_off_color_usec Valor armazenado em nanossegundos, a API fornece microssegundos.
K4A_WIRED_SYNC_MODE "INDEPENDENTE" wired_sync_mode Valores possíveis: "STANDALONE", "MASTER", "SUBORDINATE"
K4A_SUBORDINATE_DELAY_NS "0" subordinate_delay_off_master_usec Valor armazenado em nanossegundos, a API fornece microssegundos.
K4A_COLOR_FIRMWARE_VERSION "" N/A Versão de firmware de cor do dispositivo, por exemplo "1.x.xx"
K4A_DEPTH_FIRMWARE_VERSION "" N/A Versão de firmware de profundidade do dispositivo, por exemplo "1.x.xx"
K4A_DEVICE_SERIAL_NUMBER "" N/A Número de série do dispositivo de gravação
K4A_START_OFFSET_NS "0" start_timestamp_offset_usec Consulte Sincronização de carimbo de data/hora abaixo.
K4A_COLOR_TRACK Nenhuma N/A Consulte Formato de arquivo de gravação - Identificação de faixas.
K4A_DEPTH_TRACK Nenhuma N/A Consulte Formato de arquivo de gravação - Identificação de faixas.
K4A_IR_TRACK Nenhuma N/A Consulte Formato de arquivo de gravação - Identificação de faixas.
K4A_IMU_TRACK Nenhuma N/A Consulte Formato de arquivo de gravação - Identificação de faixas.

Sincronização de carimbo de data/hora

O formato Matroska requer que as gravações comecem com um carimbo de data/hora de zero. Ao sincronizar câmeras externamente, o primeiro carimbo de data/hora de cada dispositivo pode ser diferente de zero.

Para preservar os carimbos de data/hora originais dos dispositivos entre a gravação e a reprodução, o arquivo armazena um deslocamento para aplicar aos carimbos de data/hora.

A K4A_START_OFFSET_NS tag é usada para especificar um deslocamento de carimbo de data/hora para que os arquivos possam ser ressincronizados após a gravação. Esse deslocamento de carimbo de data/hora pode ser adicionado a cada carimbo de data/hora no arquivo para reconstruir os carimbos de data/hora originais do dispositivo.

O deslocamento de k4a_record_configuration_t partida também está disponível na estrutura.