---
title: Especificacion Del Protocolo De Tracking
slug: scenario-esp/especificacion-del-protocolo-de-tracking
createdAt: 2026-06-08T08:22:11.776Z
---

# CinCraft Scenario SDK Lite 1.0.1

Esta página describe el protocolo de seguimiento SDK Lite; también está disponible como archivo descargable aquí:

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

## Descripción

La idea detrás de SDK Lite es brindar a nuestros clientes una forma mucho más sencilla de interactuar con CinCraft Scenario como fuente de datos.

Esto se logra mediante una conexión UDP consistente con una única MTU para cada trama que contiene toda la información esencial que normalmente se necesita para la integración con software de terceros.

El tipo de servidor se puede configurar en transmisión UDP o unidifusión UDP.

El tipo de servidor, el puerto y la dirección IP se pueden modificar en CinCraft Scenario.

El tamaño total de cada mensaje/paquete siempre será menor que los 1500 Bytes típicos en comunicaciones UDP y su formato se ajustará a la especificación descrita por la versión del Protocolo SDK Lite.

Están previstas más ampliaciones para el SDK Lite, incluida una implementación en serie.

## Formato de paquete

Después de un indicador de control de 2 caracteres (0x0A, 0x0D), los siguientes 8 bytes siempre serán fijos cualquiera que sea la versión del protocolo SDK Lite. Definen la versión del protocolo que se transmite y la longitud de la sección dinámica en bytes.

| **#**                                                                    | **Tamaño** | **Tipo (x86\_64)** | **Datos**                                |
| ------------------------------------------------------------------------ | ---------- | ------------------ | ---------------------------------------- |
| ***0***                                                                  | 2 bytes    | carácter \[2]      | Bandera de control \[0x0A, 0x0D]         |
| ***La siguiente sección es estática y tiene un tamaño fijo de 8 bytes*** |            |                    |                                          |
| ***1***                                                                  | 1 byte     | uint8\_t           | Suma de comprobación (complemento a dos) |
| ***2***                                                                  | 3 bytes    | uint8\_t\[3]       | SDK Lite Versión \[M, m, r]              |
| ***3***                                                                  | 4 bytes    | uint32\_t          | Longitud en bytes de la sección dinámica |
| ***La sección dinámica comienza aquí***                                  |            |                    |                                          |
| ***4***                                                                  | 4 bytes    | uint32\_t          | Número de paquete                        |
| ***5***                                                                  | 4 bytes    | uint32\_t          | Código de tiempo                         |
| ***6***                                                                  | 12 bytes   | flotador \[3]      | Traducción \[x, y, z]                    |
| ***7***                                                                  | 12 bytes   | flotador \[3]      | Rotación \[ox, oy, oz]                   |
| ***8***                                                                  | 12 bytes   | flotador \[3]      | Enfoque normalizado, iris y zoom         |
| ***9***                                                                  | 12 bytes   | flotador \[3]      | Enfoque mapeado, iris y zoom             |
| ***10***                                                                 | 4 bytes    | flotador           | Desplazamiento nodal en metros           |
| ***11***                                                                 | 64 bytes   | flotador \[16]     | Parámetros de la lente                   |

Los paquetes deben comprobarse con su suma de control a su llegada. Esto se logra calculando la suma de todos los bytes como int8\_t comenzando con la suma de verificación y terminando con el último byte de la sección dinámica cuya longitud viene dada por #3. Un paquete válido sumaría cero.

El tamaño total de un paquete es de 134 bytes. Para una señal de vídeo de 1080p60, el ancho de banda requerido es 60x134 = 8040 Bytes/s, por lo que es inferior a 8 KB/s.

## Dar sentido a la información del SDK Lite:

### Número de paquete

Un contador de paquetes enviados desde que el SDK Lite comenzó a transmitir.

### Código de tiempo

El código de tiempo de la fuente SDI.

### Traducción

La traducción *vector\[3]* en metros.

### Rotación

La rotación utiliza una representación compacta *vector\[3]* de Rodrigues:

\- El ángulo de rotación viene dado por el módulo del vector de entrada.

\- El eje de rotación viene dado por el vector de entrada normalizado.

OpenCV proporciona un método conveniente para convertir hacia y desde una matriz de rotación *3x3*:

void Rodrigues(InputArray src, OutputArray dst, OutputArray jacobian=noArray())

## Normalizado FIZ

Valores del codificador de enfoque, iris y zoom normalizados entre *0,0* y *1,0*.

### Mapeado FIZ

Valores de escala mundial para Focus (en metros), Iris (en T-stops) y Zoom (en mm).

### Desplazamiento nodal

Distancia desde el centro del sensor de la cámara al punto nodal en mm.

### Parámetros de la lente

Este es un *vector\[16]* con 3 secciones distintas:

- Los primeros cuatro valores son parámetros afines: Focal H normalizado, Focal V normalizado, Centro óptico H normalizado y Centro óptico V normalizado.
- Los dos que siguen son distorsión radial: *k1, k2*
- Los dos siguientes son sin distorsión radial: inv\_*k1, inv\_k2*

# Pseudocódigo C++ para deserialización de paquetes

## Ayudantes de lectura de bajo nivel

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

## Conversiones y utilidades de 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]; 
} 
```

## Ejemplo de extracción de paquetes

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

# Muestra para un marco de datos

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