---
title: Especificação do Protocolo de Rastreamento
slug: portugues-brasil/especificacao-do-protocolo-de-rastreamento
createdAt: 2026-06-08T08:22:11.776Z
---

# 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:

::File{src="https://api.archbee.com/api/presign/Qn0sdcVrDcDbwMFmH0oYn/ze1AhMVmmZt2kYX1Lup3X-20260608-083029.pdf" label="ZEISS CinCraft Scenario SDK Lite 1.0.1.pdf"}

## 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

```cpp
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

```cpp
// 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

```cpp
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,
};
