Share via

A API de reprodução do Azure Kinect

  • Artigo

O SDK do sensor fornece uma API para gravar dados do dispositivo num ficheiro Matroska (.mkv). O formato de contentor Matroska armazena faixas de vídeo, exemplos de IMU e calibragem de dispositivos. As gravações podem ser geradas com o utilitário de linha de comandos k4arecorder fornecido. As gravações também podem ser personalizadas e gravadas diretamente com a API de registos.

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 ficheiro Matroska, consulte a página Formato de Ficheiro de Gravação .

Utilizar a API de reprodução

Os ficheiros de gravação podem ser abertos com 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 seguinte, abrimos uma gravação com k4a_playback_open(), imprime o comprimento da gravação e, em seguida, fechamos o ficheiro 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);

Capturas de leitura

Assim que o ficheiro estiver aberto, podemos começar a ler capturas da gravação. Este exemplo seguinte irá ler cada uma das capturas no ficheiro.

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 numa gravação

Assim que chegarmos ao fim do ficheiro, poderemos querer voltar atrás e lê-lo novamente. Este processo pode ser feito ao ler para trás com k4a_playback_get_previous_capture(), mas pode ser muito lento consoante o comprimento da gravação. Em vez disso, podemos utilizar a k4a_playback_seek_timestamp() função para aceder a um ponto específico no ficheiro.

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

// 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 etiqueta

As gravações também podem conter vários metadados, como o número de série do dispositivo e versões de firmware. Estes metadados são armazenados em etiquetas de gravação, que podem ser acedidas com 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 etiquetas de registo

Segue-se uma lista de todas as etiquetas predefinidas que podem ser incluídas num ficheiro de gravação. Muitos destes 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 não existir uma etiqueta, assume-se que tem o valor predefinido.

Nome da Etiqueta Valor Predefinido k4a_record_configuration_t Campo Notas
K4A_COLOR_MODE "DESATIVADO" color_format / color_resolution Valores possíveis: "OFF", "MJPG_1080P", "NV12_720P", "YUY2_720P" e assim sucessivamente
K4A_DEPTH_MODE "DESATIVADO" depth_mode / depth_track_enabled Valores possíveis: "OFF, "NFOV_UNBINNED", "PASSIVE_IR" e assim sucessivamente
K4A_IR_MODE "DESATIVADO" depth_mode / ir_track_enabled Valores possíveis: "OFF", "ACTIVE", "PASSIVE"
K4A_IMU_MODE "DESATIVADO" imu_track_enabled Valores possíveis: "ON", "OFF"
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 de firmware de cores do dispositivo, por exemplo "1.x.xx"
K4A_DEPTH_FIRMWARE_VERSION "" N/D Versão de firmware de profundidade do dispositivo, por exemplo "1.x.xx"
K4A_DEVICE_SERIAL_NUMBER "" N/D Gravar o número de série do dispositivo
K4A_START_OFFSET_NS "0" start_timestamp_offset_usec Veja Sincronização do Carimbo de Data /Hora abaixo.
K4A_COLOR_TRACK Nenhuma N/D Veja Gravação de Formato de Ficheiro – Identificar faixas.
K4A_DEPTH_TRACK Nenhuma N/D Veja Gravação de Formato de Ficheiro – Identificar faixas.
K4A_IR_TRACK Nenhuma N/D Veja Gravação de Formato de Ficheiro – Identificar faixas.
K4A_IMU_TRACK Nenhuma N/D Veja Gravação de Formato de Ficheiro – Identificar faixas.

Sincronização do carimbo de data/hora

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

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

A K4A_START_OFFSET_NS etiqueta é utilizada para especificar um desvio de carimbo de data/hora para que os ficheiros possam ser ressincronizados após a gravação. Este desvio de carimbo de data/hora pode ser adicionado a cada carimbo de data/hora no ficheiro para reconstruir os carimbos de data/hora originais do dispositivo.

O desvio de início também está disponível na k4a_record_configuration_t estrutura.