Difference between revisions of "OpenIGTLink/ProtocolV2"

From NAMIC Wiki
Jump to: navigation, search
Line 27: Line 27:
 
==Common rules for data fields==
 
==Common rules for data fields==
 
===Floating point data===
 
===Floating point data===
Floating point values in the data must comply the IEEE 754-1985 standard.
+
Floating point values in the data must comply with the IEEE 754-1985 standard.
  
 
===Character string data===
 
===Character string data===

Revision as of 22:20, 15 July 2008

Home < OpenIGTLink < ProtocolV2

<< OpenIGTLink

 !! PLEASE NOTE that this is a draft for protocol version 2, and might be changed a lot!!

Open IGT Link Protocol (Ver. 2) description

Introduction

Overview

The Open IGT Link protocol is a simple but extensible data format to transfer various types of data among software and devices used in image-guided therapy (IGT) scene e.g. surgical navigation software, tracking device, robotic device, imaging scanner. The protocol can handle image, tracking data, transform, device control and monitoring command, and other user-defined data types. It is designed to work in the application layer of the TCP/IP stack, but not limited to it; developers can use this protocol with UDP/IP or other network protocol models.

The objective of providing this open network protocol is to make system integration for IGT application easier. To achieve this objective, we have the following rules to design the protocol:

  • Open. It is important to invite the IGT developers as many as possible to make the protocol more universal, compatible and reliable. It is also important to allow commercial use without any fee, to increase the number of commercial softwares and devices compatible with Open IGT Link, which contributes interoperativity in the IGT scene.
  • Simple. In IGT environment, wide variety of architectures are used, from embedded systems to high-performance computers. It is difficult to support all of them by providing a single open-source library, thus the developers sometime have to implement the interface by themselves.
  • Extensible. Type of data transfered in the IGT scene varies by clinical applications. The protocol must have mechanism for the developers to define their own data types.
  • Reliable. The protocol should provides a mechanism to verify data integrity. This is extremely important for the saftware to get approved and commercialized.

Protocol extensions

Client - Server

A device (scanner, tracker) exposing functionality and executing commands is usually the Server. Once started will stand by listening for connection requests.

A Client (for ex. a PC) usually connects to multiple devices and coordinates the whole process.

Common rules for data fields

Floating point data

Floating point values in the data must comply with the IEEE 754-1985 standard.

Character string data

Character string (array) should end with '\0' (NULL), unless the string length is same as the length of the data field. For example when the length of the data field is 10 bytes:

               0   1   2   3   4   5   6   7   8   9  
             +---+---+---+---+---+---+---+---+---+---+
"MONKEY"     | M | O | N | K | E | Y |\0 |   |   |   |
             +---+---+---+---+---+---+---+---+---+---+
         
               0   1   2   3   4   5   6   7   8   9  
             +---+---+---+---+---+---+---+---+---+---+
"CHIMPANZEE" | C | H | I | M | P | A | N | Z | E | E |
             +---+---+---+---+---+---+---+---+---+---+


Header Structure

 Bytes
 0   2                       14                                      34             42
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 | V |          TYPE         |              DEVICE_NAME              |   TIME_STAMP  |		  
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 
 42              50              58	  
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+.....
 |   BODY_SIZE   |     CRC64     |   BODY    
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+.....

Byte Order

Big endian should be used for all numerical values (version, body size, crc). Unused spaces are padded with 0 (binary).

Header Fields

Data Type Description
V Unsigned short (16bit) Version number (1)
TYPE char[12] Type name of data
DEVICE_NAME char[20] Unique device name
TIME_STAMP 64 bit unsigned int Timestamp or 0 if unused
BODY_SIZE 64 bit unsigned int Size of body in bytes
CRC 64 bit unsigned int 64 bit CRC for body data


Data types (Common across implementations)

Data type:

  • Command (get position, get status, go to target, stop, start continuous push, stop push, ready)
  • Data (image, position, status)

POSITION

Quaternion representation of position / orientation.

Parameters (24 byte total):

  • Vector of three 32 bit (3x4 byte) floats: position X, Y, Z
  • Vector of four 32 bit (3x4 byte) floats: orientation quaternion, normalized

The orientation is optional, if not used the values are (0,0,0,1)

 Bytes (Body)
 58  60      64      68      72      76      80      84      88
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |V|O|   X   |   Y   |   Z   |   OX  |   OY  |   OZ  |   W   |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+


Data Type Description
V 8-bit unsigned int Format version number
O 8-bit unsigned int Coordinate system (1: RAS, 2:LPS)
X, Y, Z 32-bit floating point 3D poisition
OX, OY, OZ, W 32-bit floating point Orientation (in quaternion expression)


LTRANSFORM

This data type represents 4x4 linear transformation matrix. The message contains upper three rows of 4x4 transformation matrix, where element (3,3) is assumed to be 1.

Each element is a 4 byte (32 bit) float, 12x4 = 48 byte in total.

 Bytes (Body)
 58  60      64      68      72      76      80      84      88      92      96      100     104     108
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |V|O|m(0,0) |m(1,0) |m(2,0) |m(0,1) |m(1,1) |m(2,1) |m(0,2) |m(1,2) |m(2,2) |m(0,3) |m(1,3) |m(2,3) | 
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Data Type Description
V 8-bit unsigned int Format version number
O 8-bit unsigned int Coordinate system (1: RAS, 2:LPS)
m(i,j) 32-bit floating point Elements of 4x4 linear transformation matrix


IMAGE

For normal scalar and vector images:

Bytes
58  60  62  64          70                      82                      94                     106
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|V|O|T|S|E|R|RI |RJ |RK |  TX   |  TY   |  TZ   |  SX   |  SY   |  SZ   |  NX   |  NY   |  NZ   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  
106                    118         124         130
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+....
|  PX   |  PY   |  PZ   |DI |DJ |DK |DRI|DRJ|DRK|   IMAGE_DATA
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+....

For color-map images

Bytes
58  60  62  64          70                      82                      94                     106
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|V|O|T|S|E|R|RI |RJ |RK |  TX   |  TY   |  TZ   |  SX   |  SY   |  SZ   |  NX   |  NY   |  NZ   |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  
106                    118         124         130                                     150
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|  PX   |  PY   |  PZ   |DI |DJ |DK |DRI|DRJ|DRK|       COLOR_TABLE_NAME                |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

150
+-+-+-+-+-+-+-+-+....	
|  IMAGE_DATA	
+-+-+-+-+-+-+-+-+....


Data Type Description
V 8-bit unsigned int Format version number
O 8bit unsigned int image coordinate (1:RAS 2:LPS)
T 8bit unsigned int Image type (1: Scalar, 3: Vector, 17: Color-mapped Scalar, 19: RGB)
S 8bit unsigned int Scalar type (2:int8 3:uint8 4:int16 5:uint16 6:int32 7:uint32 10:float32 11:float64)
E 8bit unsigned int Endian for image data (1:BIG 2:LITTLE) (NOTE: values in image header is fixed to BIG endian)
R 8bit unsigned int Reserved
RI, RJ, RK 16 bit unsigned int Number of pixels in each direction
PX, PY, PZ 32 bit float center position of the image
TX, TY, TZ 32 bit float Transverse vector (direction for 'i' index) / The length represents pixel size in 'i' direction
SX, SY, SZ 32 bit float Transverse vector (direction for 'j' index) / The length represents pixel size in 'j' direction
NX, NY, NZ 32 bit float Normal vector of image plane(direction for 'k' index) / The length represents pixel size in 'z' direction or slice thickness
DI, DJ, DK 16 bit unsigned int Starting index of subvolume
DRI, DRJ, DRK 16 bit unsigned int number of pixels of subvolume
COLOR_TABLE_NAME char[20] (applicable if T == 17) Name of color table. This field exists only when color-mapped scalar type is specified.
IMAGE_DATA Binary image data () Image data (endian is determined by "E" field)


COLORTABLE

The COLORTABLE data type is used to transfer a table to convert scalar data to colored image. Color table data is transferred separately from image data; the receiver stores color tables with their names in the DEVICE_NAME fields of the generic headers. When receiver receives IMAGE data with color-mapped image option (T=17), it applies color table specified in the COLOR_TABLE_NAME field in the IMAGE message.

Bytes
58  60  62  
+-+-+-+-+-+-+-+-+-+-+...
|V|R|I|M|    TABLE
+-+-+-+-+-+-+-+-+-+-+...
  
Data Type Description
V 8-bit unsigned int Format version number
R 8-bit unsigned int Reserved
I 8-bit unsigned int Index Type (3:uint8 5:uint16)
M 8-bit unsigned int Map Type (3:uint8 5:uint16 19: RGB color)
TABLE Array of 8-bit unsigned int Color index table

The size of the TABLE field can be calculated by the following formula:

   <size of TABLE> = <number of indices> * <pixel data size>
  
 where
 
       <number of indices> : 256 (if I=3)  or 65536 (if I=5)
       <pixel data size>     : 1 (if M=3), 2 (if M=5) or 3 (if M=19)
 


GET_CAPABILITY

Query for device information and capabilities.

Parameters: none (BODY_SIZE=0)
Response: one CAPABILITY packet for each implemented device

CAPABILITY

List of available TYPEs.

 Bytes (Body)
 58  60  62                      74  76                    88
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+....-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |V|R|V|R|    TYPE (12bytes)     |V|R|  TYPE (12bytes)     |     |V|R|    TYPE (12bytes)     |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+....-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Data Type Description
V 8-bit unsigned int Format version number
R 8-bit unsigned int Reserved
TYPE ASCII string (12 bytes) Device Type name


GET_STATUS

Parameters: none (BODY_SIZE=0)
Response: one STATUS packet for each implemented device


STATUS

Any STATUS that's not 1 (OK) should be logged by the receiver.

The uniform error reporting allows easy logging and can be the base of exception class in libraries.

 Bytes (Body)
 58      62              70                            90
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+.....
 |V|R| C |  Sub Code     |       Status name           |   Status message (optional)
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+.....


Data Type Description
V Unsigned short (8bit) Version number
R Unsigned short (8bit) Reserved.
C Unsigned short (16bit) Status code groups: 1-Ok, 2-Generic Error, ... (see below)
Sub Code 64 bit integer Sub code for the error (ex. 0x200 - file not found)
Error name char[20] "Error", "OK", "Warning" - can be anything, don't relay on this
Status Message (optional) char[ BodySize - 30 ] Optional (English) description (ex. "File C:\test.ini not found")


Status codes:
0 Invalid packet - 0 is not used
1 OK (Default status)
2 Unknown error
3 Panic mode (emergency)
4 Not found (file, configuration, device etc)
5 Access denied
6 Busy
7 Time out / Connection lost
8 Overflow / Can't be reached
9 Checksum error
10 Configuration error
11 Not enough resource (memory, storage etc)
12 Illegal/Unknown instruction (or feature not implemented / Unknown command received)
13 Device not ready (starting up)
14 Manual mode (device does not accept commands)
15 Device disabled
16 Device not present
17 Device version not known
18 Hardware failure
19 Exiting / shut down in progress


User-defined Data Types

Developers can define their own type of data. As long as the general header contains correct size information, OpenIGTLink-compliant software and hardware can at least skip the data and interpret following data correctly.