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, exemplos de IMU e calibragem de dispositivo. 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, confira k4a_record_create().

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

Usar a API de reprodução

Os arquivos da 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 restante do SDK do sensor.

Abrir um arquivo de gravação

No exemplo a seguir, vamos abrir uma gravação usando k4a_playback_open(), imprimir o tamanho da gravação e fechar 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);

Ler capturas

Quando o arquivo estiver aberto, podemos começar a ler as capturas da gravação. Este exemplo a seguir 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;
}

Buscar em uma gravação

Depois de atingirmos o final do arquivo, talvez queiramos voltar e ler novamente. Esse processo pode ser feito lendo versões anteriores com k4a_playback_get_previous_capture(), mas isso pode ser muito lento dependendo da duração da gravação. Em vez disso, podemos usar a função k4a_playback_seek_timestamp() para ir para um ponto específico no arquivo.

Neste exemplo, especificamos carimbos de data/hora em microssegundos para buscar 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 de marca

As gravações também podem conter vários metadados, como o número de série do dispositivo e as versões do firmware. Esses metadados são armazenados em marcas de gravação, que podem ser acessadas usando a função 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 marcas de gravação

Veja abaixo uma lista de todas as marcas padrão que podem ser incluídas em um arquivo de gravação. Muitos desses valores estão disponíveis como parte do struct k4a_record_configuration_t e podem ser lidos com a função k4a_playback_get_record_configuration().

Se a marca não existir, supõe-se que tenha o valor padrão.

Nome da marca Valor padrão Campo k4a_record_configuration_t Observações
K4A_COLOR_MODE "DESATIVADO" color_format / color_resolution Valores possíveis: "DESATIVADO", "MJPG_1080P", "NV12_720P", "YUY2_720P" e assim por diante
K4A_DEPTH_MODE "DESATIVADO" depth_mode / depth_track_enabled Valores possíveis: "OFF", "NFOV_UNBINNED", "PASSIVE_IR" e assim por diante
K4A_IR_MODE "DESATIVADO" depth_mode / ir_track_enabled Valores possíveis: "DESATIVADO", "ATIVO", "PASSIVO"
K4A_IMU_MODE "DESATIVADO" imu_track_enabled Valores possíveis: "ATIVADO", "DESATIVADO"
K4A_CALIBRATION_FILE "calibration.json" N/D 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 "AUTÔNOMO" wired_sync_mode Valores possíveis: "AUTÔNOMO", "MESTRE", "SUBORDINADO"
K4A_SUBORDINATE_DELAY_NS "0" subordinate_delay_off_master_usec Valor armazenado em nanossegundos; a API fornece microssegundos.
K4A_COLOR_FIRMWARE_VERSION "" N/D Versão do firmware de cores do dispositivo, por exemplo, "1.x.xx"
K4A_DEPTH_FIRMWARE_VERSION "" N/D Versão do firmware de profundidade do dispositivo, por exemplo, "1.x.xx"
K4A_DEVICE_SERIAL_NUMBER "" N/D Número de série do dispositivo de gravação
K4A_START_OFFSET_NS "0" start_timestamp_offset_usec Confira Sincronização de carimbo de data/hora abaixo.
K4A_COLOR_TRACK Nenhum N/D Confira Formato de arquivo de gravação – Identificação de faixas.
K4A_DEPTH_TRACK Nenhum N/D Confira Formato de arquivo de gravação – Identificação de faixas.
K4A_IR_TRACK Nenhum N/D Confira Formato de arquivo de gravação – Identificação de faixas.
K4A_IMU_TRACK Nenhum N/D Confira Formato de arquivo de gravação – Identificação de faixas.

Sincronização de carimbo de data/hora

O formato Matroska exige que as gravações comecem com um carimbo de data/hora igual a zero. Quando as câmeras são sincronizadas 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 marca K4A_START_OFFSET_NS é 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 do dispositivo original.

O deslocamento de início também está disponível no struct k4a_record_configuration_t.