トラッキングプロトコル仕様
CinCraft Scenario SDK Lite 1.0.1
このページでは、SDK Lite トラッキングプロトコルについて説明します。このプロトコルは、ここからダウンロード可能なファイルとしても入手できます。
説明
SDK Lite は、CinCraft Scenario をデータソースとして利用する際のインターフェースを大幅に簡素化することを目的としています。
そのために、各フレームごとに必要な統合情報を単一の UDP パケットにまとめ、一定サイズ(MTU)の UDP 通信として送信します。これにより、サードパーティ製アプリケーションとの連携が容易になります。
通信方式は UDP ブロードキャストまたは UDP ユニキャストから選択可能であり、サーバータイプ、ポート番号、IP アドレスは CinCraft Scenario 上で設定できます。
送信される各パケットのサイズは一般的な Ethernet MTU(約1500バイト)未満に抑えられ、データ形式は SDK Lite Protocol の仕様に従います。
将来的には、シリアル通信対応を含むさらなる機能拡張も予定されています。
パケットフォーマット
2 文字の制御フラグ (0x0A、0x0D) の後、次の 8 バイトは、SDK Lite プロトコルのバージョンに関係なく常に固定されます。これらは、ストリーミングされるプロトコルのバージョンと動的セクションの長さをバイト単位で定義します。
# | サイズ | タイプ (x86_64) | データ |
|---|---|---|---|
0 | 2バイト | 文字 [2] | 制御フラグ [0x0A, 0x0D] |
次のセクションは静的で、8 バイトの固定サイズです | | | |
1 | 1バイト | uint8_t | チェックサム (2 の補数) |
2 | 3バイト | uint8_t [3] | SDK Lite バージョン [M, m, r] |
3 | 4バイト | uint32_t | 動的セクションのバイト単位の長さ |
ここから動的セクションが始まります | | | |
4 | 4バイト | uint32_t | パケット番号 |
5 | 4バイト | uint32_t | タイムコード |
6 | 12バイト | float [3] | 変換 [x, y, z] |
7 | 12バイト | float [3] | 回転 [ox, oy, oz] |
8 | 12バイト | float [3] | 正規化されたフォーカス、アイリス、ズーム |
9 | 12バイト | float [3] | マッピングされたフォーカス、アイリス、ズーム |
10 | 4バイト | float | 節点シフト (メートル) |
11 | 64バイト | float [16] | レンズパラメータ |
パケット受信時には、チェックサムによるデータ整合性の確認を行う必要があります。 検証方法は、チェックサム値自身を含めて、動的セクションの最終バイトまでの全バイトを int8_t(符号付き8ビット整数)として加算し、その合計値を求めます。動的セクションの長さは項目 #3 で定義されています。 加算結果が 0 になれば、そのパケットは正しいデータであるとみなされます。
パケットの合計サイズは 134 バイトです。 1080p60 ビデオ信号の場合、必要な帯域幅は 60x134 = 8040 バイト/秒なので、8KB/秒未満になります。
SDK Lite の情報を理解すると、次のようになります。
パケット番号
SDK Lite のストリーミング開始後から現在までに送信されたパケットの累積数を表すカウンター
タイムコード
SDI ソースのタイムコード。
単位変換
メートル単位への変換 vector[3]。
回転
回転では、コンパクトな vector[3] ロドリゲス表現が使用されます。
- 回転角度は入力ベクトルのモジュールによって与えられます。
- 回転軸は正規化された入力ベクトルによって与えられます。
OpenCV は、3x3 回転行列との間で変換するための便利な方法を提供します。
void Rodrigues(InputArray src, OutputArray dst, OutputArray jacobian=noArray())
正規化されたFIZ
フォーカス、アイリス、ズームのエンコーダー値は 0.0 と 1.0 の間で正規化されています。
マッピングされた FIZ
フォーカス (メートル単位)、アイリス (T ストップ単位)、およびズーム (mm 単位) のワールドスケール値。
ノードシフト
カメラセンサーの中心から節点までの距離 (mm)。
レンズパラメータ
これは 3 つの異なるセクションを持つ vector[16] です。
- 最初の 4 つの値はアフィン パラメータです。正規化された H 焦点、正規化された V 焦点、正規化された H 光学中心、および正規化された V 光学中心です。
- 続く 2 つは放射状歪みです: k1、k2
- 続く 2 つは放射状の歪み補正です: inv_k1、inv_k2
パケット逆シリアル化用の C++ 疑似コード
低レベルの読み取りヘルパー
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;
} 変換および調整ユーティリティ
// 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];
} パケット抽出の例
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;
} 1 フレームのデータのサンプル
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、 };