Especificação do Protocolo de Rastreamento
CinCraft Scenario SDK Lite 1.0.1
Esta página descreve o protocolo de rastreamento SDK Lite, que também está disponível para download aqui:
Descrição
A ideia por trás do SDK Lite é fornecer nosso clientes com uma maneira muito mais simples de interagir com o CinCraft Scenario como fonte de dados.
Isso é alcançado por meio de uma conexão UDP consistente com um único MTU para cada quadro contendo todas as informações essenciais geralmente necessárias para integração com software de terceiros.
O tipo de servidor pode ser definido como UDP broadcast ou UDP unicast.
O tipo de servidor, a porta e o endereço IP podem ser modificados no CinCraft Scenario.
O tamanho total de cada mensagem/pacote será sempre menor que os típicos 1500 bytes em comunicações UDP e seu formato estará em conformidade com a especificação descrita pela versão do Protocolo SDK Lite.
Outras extensões estão planejadas. para o SDK Lite, incluindo uma implementação serial.
Formato do Pacote
Após um sinalizador de controle de 2 caracteres (0x0A, 0x0D), os próximos 8 bytes serão sempre fixos, independentemente da versão do protocolo SDK Lite. Eles definem a versão do protocolo que está sendo transmitida e o comprimento da seção dinâmica em bytes.
# | Tamanho | Tipo (x86_64) | Dados |
|---|---|---|---|
0 | 2 Bytes | char [2] | Sinalizador de Controle [0x0A, 0x0D] |
A próxima seção é estática e tem um tamanho fixo de 8 bytes | | | |
1 | 1 Byte | uint8_t | Soma de verificação (Complemento de dois) |
2 | 3 Bytes | uint8_t [3] | SDK Lite Versão [M, m, r] |
3 | 4 Bytes | uint32_t | Comprimento em bytes da seção dinâmica |
A seção dinâmica começa aqui | | | |
4 | 4 Bytes | uint32_t | Número do Pacote |
5 | 4 Bytes | uint32_t | Código de Tempo |
6 | 12 Bytes | float [3] | Translação [x, y, z] |
7 | 12 Bytes | float [3] | Rotação [ox, oy, oz] |
8 | 12 Bytes | float [3] | Foco, Íris e Zoom Normalizados |
9 | 12 Bytes | float [3] | Foco, Íris e Zoom Mapeados |
10 | 4 Bytes | float | Deslocamento Nodal em Metros |
11 | 64 Bytes | float [16] | Parâmetros da Lente |
Os pacotes devem ser verificados quanto ao seu checksum na chegada. Isso é feito calculando a soma de todos os bytes como int8_t, começando com o checksum e terminando com o último byte da seção dinâmica, cujo comprimento é dado por #3. Um pacote válido teria soma zero.
O tamanho total de um pacote é de 134 bytes. Para um sinal de vídeo 1080p60, a largura de banda necessária é de 60 x 134 = 8040 bytes/seg, portanto, menos de 8 KB/seg.
Entendendo as informações de SDK Lite:
Número do pacote
Um contador de pacotes enviados desde que SDK Lite começou a transmitir.
Código de tempo
O código de tempo da fonte SDI.
Translação
O vetor de translação em metros.
Rotação
A rotação utiliza uma representação de Rodrigues compacta vetorial[3]:
- O ângulo de rotação é dado pelo módulo do vetor de entrada.
- O eixo de rotação é dado pelo vetor de entrada normalizado.
O OpenCV fornece um método conveniente para converter de e para uma matriz de rotação 3x3:
void Rodrigues(InputArray src, OutputArray dst, OutputArray jacobian=noArray())
Normalizado FIZ
Valores do codificador de foco, íris e zoom normalizados entre 0,0 e 1,0.
Mapeado FIZ
Valores em escala mundial para foco (em metros), íris (em T-stops) e zoom (em mm).
Deslocamento Nodal
Distância do centro do sensor da câmera ao ponto nodal em mm.
Parâmetros da Lente
Este é um vetor[16] com 3 seções distintas:
- Os quatro primeiros valores são parâmetros afins: Focal H Normalizado, Focal V Normalizado, Centro Óptico H Normalizado e Centro Óptico V Normalizado.
- Os dois seguintes são distorções radiais: k1, k2
- Os dois seguintes são desdistorções radiais: inv_k1, inv_k2
Pseudocódigo C++ para Desserialização de Pacotes
Auxiliares de Leitura de Baixo Nível
uint8_t ReadUInt8(BYTE* data, uint32_t& pos, int maxLen = -1)
{
if (maxLen > -1 && static_cast<int>(pos) > maxLen)
{
return 0;
}
uint8_t ret = static_cast<uint8_t>(data[pos]);
pos += 1;
return ret;
}
uint32_t ReadUInt32(BYTE* data, uint32_t& pos, int maxLen = -1)
{
if (maxLen > -1 && static_cast<int>(pos + 3) > maxLen)
{
return 0;
}
uint32_t ret = static_cast<uint32_t>(data[pos]);
pos += 4;
return ret;
}
float ReadFloat32(BYTE* data, uint32_t& pos, int maxLen = -1)
{
if (maxLen > -1 && static_cast<int>(pos + 3) > maxLen)
{
return 0;
}
float ret;
uint8_t bytes[] = { data[pos], data[pos+1], data[pos+2], data[pos+3] };
memcpy(&ret, &bytes, sizeof(ret));
pos += 4;
return ret;
} Utilitários de Conversão e Coordenadas
// in degrees
float NormalizedFocalLengthToFov(float focalLengthNorm)
{
return (180.0 / M_PI) * 2.0 * atan2(1.0, 2 * focalLengthNorm);
}
// Zeiss SDK streams CameraFromWorld
Eigen::Vector3f GetPosition(float tX, float tY, float tZ, float rotX, float rotY, float rotZ)
{
Eigen::Vector3f rodriguesVec(rotX, rotY, rotZ); // read directly from SDK Lite
Eigen::AngleAxisf angleAxis(rodriguesVec.norm(), rodriguesVec.normalized());
Eigen::Matrix3f rotationMatrix = angleAxis.toRotationMatrix();
auto inverseRotation = rotationMatrix.transpose();
Eigen::Vector3f translationVec(tX, tY, tZ);
Eigen::Vector3f position = -inverseRotation * translationVec;
return position;
}
void rodriguesToEuler(float rotX, float rotY, float rotZ, float& panOut, float& tiltOut, float& rollOut)
{
Eigen::Vector3f rodriguesVec(rotX, rotY, rotZ); // read directly from SDK Lite
Eigen::AngleAxisf angleAxis(rodriguesVec.norm(), rodriguesVec.normalized());
Eigen::Matrix3f rotationMatrix = angleAxis.toRotationMatrix();
auto rotationMatrixInv = rotationMatrix.transpose();
// Choose the angle order as needed for the target system
Eigen::Matrix3f ZeissCS;
ZeissCS.setZero();
ZeissCS(0, 0) = 1.0;
ZeissCS(1, 1) = -1.0;
ZeissCS(2, 2) = -1.0;
const auto lRotation = ZeissCS * rotationMatrixInv;
Eigen::Vector3f eulerAngles = lRotation.eulerAngles(1, 0, 2);
panOut = eulerAngles[0] * -1;
tiltOut = eulerAngles[1];
rollOut = eulerAngles[2];
} Exemplo de Extração de Pacotes
void ExtractTrackdata(char* tsname, char* RxBuffer)
{
// Content of RxBuffer is expected to be checked before entering
// Control flags must be valid
// Checksum must also be valid
BYTE* data = (BYTE*)RxBuffer;
// =========
// Header
pos += 2; // control flag
// ==============
// Static section
pos += 1; // checksum
uint8_t version_major = ReadUInt8(data, pos);
uint8_t version_minor = ReadUInt8(data, pos);
uint8_t version_revision = ReadUInt8(data, pos);
uint32_t maxLen = ReadUInt32(data, pos) + pos; // maximum length of packet
// ==============
// Dynamic section
float packet_number = static_cast<float>(ReadUInt32(data, pos, maxLen));
float timecode = static_cast<float>(ReadUInt32(data, pos, maxLen));
float tX = ReadFloat32(data, pos, maxLen);
float tY = ReadFloat32(data, pos, maxLen);
float tZ = ReadFloat32(data, pos, maxLen);
float rotX = ReadFloat32(data, pos, maxLen);
float rotY = ReadFloat32(data, pos, maxLen);
float rotZ = ReadFloat32(data, pos, maxLen);
// Position of pinhole / projection center / non-parallax point in meters from world origin
// ZEISS uses a right-handed Y-up coordinate system
auto position = GetPosition(tX, tY, tZ, rotX, rotY, rotZ);
// Rotation in radians
float pan, tilt, roll;
rodriguesToEuler(rotX, rotY, rotZ, pan, tilt, roll);
// Rotation in degrees
pan = 180.f * pan / static_cast<float>(M_PI);
tilt = 180.f * tilt / static_cast<float>(M_PI);
roll = 180.f * roll / static_cast<float>(M_PI);
// Normalized FIZ values in [0, 1]
float focusNorm = ReadFloat32(data, pos, maxLen);
float irisNorm = ReadFloat32(data, pos, maxLen);
float zoomNorm = ReadFloat32(data, pos, maxLen);
// Mapped FIZ values
float focusMapped = ReadFloat32(data, pos, maxLen); // meters
float irisMapped = ReadFloat32(data, pos, maxLen); // T-stops
float zoomMapped = ReadFloat32(data, pos, maxLen); // mm
// Distance of the sensor from pinhole / projection center / non-parallax point
float nodalShift = ReadFloat32(data, pos, maxLen);
const float hFov = NormalizedFocalLengthToFov(ReadFloat32(data, pos, maxLen));
const float vFov = NormalizedFocalLengthToFov(ReadFloat32(data, pos, maxLen));
// ZEISS values are normalized relative to image width and height
// (0.0, 0.0) is top-left and (1.0, 1.0) is bottom-right
const float hCenter = ReadFloat32(data, pos, maxLen);
const float vCenter = ReadFloat32(data, pos, maxLen);
// Distortion values from Zeiss / Cinelens are normalized along the half diagonal of the sensor
// If values are normalized along the full diagonal, scale factors must be adjusted accordingly
float k1 = ReadFloat32(data, pos, maxLen) / 4.0f;
float k2 = ReadFloat32(data, pos, maxLen) / 16.0f;
// Inverse parameters
float k1Inv = ReadFloat32(data, pos, maxLen) / 4.0f;
float k2Inv = ReadFloat32(data, pos, maxLen) / 16.0f;
} Amostra para um quadro de dados
const uint8_t buf[] = { 0x0a, 0x0d, 0xb2, 0x01, 0x00, 0x01, 0x7c, 0x00, 0x00, 0x00, 0xec, 0xa4, 0x00, 0x00, 0x05, 0x47, 0x26, 0x08, 0x1d, 0x55, 0x14, 0x3f, 0x0b, 0x6d, 0x2f, 0x40, 0xd5, 0x23, 0x32, 0x3f, 0x10, 0x8b, 0xa4, 0x3f, 0xe7, 0x31, 0x6c, 0x3c, 0x8c, 0x2f, 0x93, 0xbd, 0x76, 0x90, 0x7e, 0x3f, 0x00, 0x00, 0x00, 0x00, 0x34, 0x28, 0x7f, 0x3f, 0x7b, 0x66, 0x1d, 0x41, 0x33, 0x33, 0xf3, 0x3f, 0x32, 0x34, 0x6e, 0x42, 0x93, 0xa6, 0x72, 0x3d, 0xf0, 0xac, 0xc5, 0x40, 0x35, 0xd9, 0x2f, 0x41, 0x6b, 0x66, 0x01, 0x3f, 0x1d, 0xe8, 0x05, 0x3f, 0x97, 0xf0, 0xd3, 0x3c, 0xf9, 0x8c, 0xcd, 0x38, 0x8b, 0x53, 0xd3, 0xbc, 0xd7, 0xc5, 0xdc, 0x3a, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0xff, 0xff, };