OpenIGTLink/Protocol

<< OpenIGTLink

Overview

Every message transfered from a sender to a receiver through OpenIGTLink communication consists of the header byte array followed by the body.

The header contains type string and size of the body, which helps receiver to interpret the body.

The type string may be one of the names defined in OpenIGTLink protocol specification (this page) or a name defined by a user.

The sender does not need to care whether the receiver can interpret the data type, since the receiver can skip reading the body as long as the body size information in the header is correct.

The header also contains device name. This would be helpful when the sender sends same type of data acquired from multiple sources. For example, if the sender has multi-channel tracking device, sender can assign different name to each channel, then the receiver can recognize from which channel data has been acquired.

Details of the header and body structures are defined in following sections.

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.

Header Structure

 Bytes
 0   2                       14                                      34             42               50              58
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+.....
 | V |          TYPE         |              DEVICE_NAME              |   TIME_STAMP  |   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

Data type:

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

GET_CAPABILITY

Query for device capabilities.

CAPABILITY

Response from the device with description of the implemented protocols and functions available.

IMAGE

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

Descriptions:

Data	Type	Description
V	unsigned short	version number
T	8bit unsigned int	Image type (1: Scalar)
S	8bit unsigned int	Scalar type (2:int8 3:int8 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)
O	8bit unsigned int	image coordinate (1:RAS 2:LPS)
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
IMAGE_DATA	Binary image data ()	Image data (endian is determined by "E" field)

TRANSFORM

The transform data is 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      62      66      70      74      78      82      86      90      94      98     102     106
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 | (0,0) | (1,0) | (2,0) | (0,1) | (1,1) | (2,1) | (0,2) | (1,2) | (2,2) | (0,3) | (1,3) | (2,3) | 
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

POSITION

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      62      66      70      74      78       82
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 |   x   |   y   |   z   |   ox  |   oy  |   oz  |    W  |
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

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.

 Bytes (Body)
 58   60            68                           88
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+--+-+-+.....
 | C |  Sub Code   |       Status name           |   Status message (optional)
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+--+-+-+.....

Data	Type	Description
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", "Starting up" - 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

JHU BRP Robot protocol

JHU BRP Robot protocol description

• Set Workphase (Slicer -> Robot)
• Query and Command (Slicer -> Robot)
• Responses (Robot -> Slicer)

Open questions

1. What if the application receives hundreds of "position" packets?
   Should we have packet types?
   -keep only the last (position)
   - all important (command)
   - high priority (emergency)
   
2. Priority
3. Authentication (other than Unique Name) -- SSL
4. Compression?
5. Duplicate messages

Resources

• Slicer 3 Image Guided Therapy (IGT) suite
• BioImage Suite VVLink Tool (uses TCL/TK object streaming)
• Meetings concerning Open IGT Link