View source for OpenIGTLink/Protocol

[[OpenIGTLink | &lt;&lt; OpenIGTLink]]


<div class="redirectText">'''Open IGT Link protocol description'''</div>
<div class="floatright">__TOC__</div>

=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.

= Protocol extensions =
* [[OpenIGTLink/Protocol/JHUBRP | JHU MRI robot and encoders]]
* [[OpenIGTLink/Protocol/JHUTRUS | JHU TRUS robot]]

=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 [http://www.opengroup.org/onlinepubs/007908799/xns/htonl.html numerical values] (version, body size, crc). Unused spaces are padded with 0 (binary).

==Header Fields==
{| border="1" cellpadding="5" cellspacing="0" align="center"
|-
| align="left style="background:#e0e0e0;" | Data
| align="left style="background:#e0e0e0;" | Type
| align="left style="background:#e0e0e0;" | Description
|-
| align="left" | V
| align="left" | Unsigned short (16bit)
| align="left" | Version number (1)
|-
| align="left" | TYPE
| align="left" | char[12]
| align="left" | Type name of data
|-
| align="left" | DEVICE_NAME
| align="left" | char[20]
| align="left" | Unique device name
|-
| align="left" | TIME_STAMP
| align="left" | 64 bit unsigned int
| align="left" | [[OpenIGTLink/Timestamp | Timestamp]] or 0 if unused
|-
| align="left" | BODY_SIZE
| align="left" | 64 bit unsigned int
| align="left" | Size of body in bytes
|-
| align="left" | CRC
| align="left" | 64 bit unsigned int
| align="left" | 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)

==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:
{| border="1" cellpadding="5" cellspacing="0" align="center"
|-
| align="left style="background:#e0e0e0;" | Data
| align="left style="background:#e0e0e0;" | Type
| align="left style="background:#e0e0e0;" | Description
|-
| align="left" | V
| align="left" | unsigned short
| align="left" | version number
|-
| align="left" | T
| align="left" | 8bit unsigned int
| align="left" | Image type (1: Scalar, 3: Vector)
|-
| align="left" | S
| align="left" | 8bit unsigned int
| align="left" | Scalar type (2:int8 3:uint8 4:int16 5:uint16 6:int32 7:uint32 10:float32 11:float64)
|-
| align="left" | E
| align="left" | 8bit unsigned int
| align="left" | Endian for image data (1:BIG 2:LITTLE) (NOTE: values in image header is fixed to BIG endian)
|-
| align="left" | O
| align="left" | 8bit unsigned int
| align="left" | image coordinate (1:RAS 2:LPS)
|-
| align="left" | RI, RJ, RK
| align="left" | 16 bit unsigned int
| align="left" | Number of pixels in each direction
|-
| align="left" | PX, PY, PZ
| align="left" | 32 bit float
| align="left" | center position of the image
|-
| align="left" | TX, TY, TZ
| align="left" | 32 bit float
| align="left" | Transverse vector (direction for 'i' index) / The length represents pixel size in 'i' direction
|-
| align="left" | SX, SY, SZ
| align="left" | 32 bit float
| align="left" | Transverse vector (direction for 'j' index) / The length represents pixel size in 'j' direction
|-
| align="left" | NX, NY, NZ
| align="left" | 32 bit float
| align="left" | Normal vector of image plane(direction for 'k' index) /  The length represents pixel size in 'z' direction or slice thickness
|-
| align="left" | DI, DJ, DK
| align="left" | 16 bit unsigned int
| align="left" | Starting index of subvolume
|-
| align="left" | DRI, DRJ, DRK
| align="left" | 16 bit unsigned int
| align="left" | number of pixels of subvolume
|-
| align="left" | IMAGE_DATA
| align="left" | Binary image data ()
| align="left" | Image data  (endian is determined by "E" field)
|-
|}

<!--
Image data consists of ascii header information followed by binary image pixel data.
(Ascii header is used to maintain compatibility with SlicerDaemon connection)

 space right-anterior-superior\n
 dimensions <xsize> <ysize> <zsize>\n
 space_origin (<x>, <y>, <z>)\n
 space_directions (<tx>, <ty>, <tz>) (<sx>, <sy>, <sz>) (<nx>, <ny>, <nz>) \n
 kinds space space space\n
 components 1\n
 scalar_type <scalar type #>\n
 <binary image data>

Descriptions:
{| border="1" cellpadding="5" cellspacing="0" align="center"
|-
| align="left style="background:#e0e0e0;" | Data
| align="left style="background:#e0e0e0;" | Type
| align="left style="background:#e0e0e0;" | Description
|-
| align="left" | <xsize>, <ysize>, <zsize>
| align="left" | text number (real)
| align="left" | Center position of the image in RAS coordinate
|-
| align="left" | <tx>, <ty>, <tz>
| align="left" | text number (real)
| align="left" | Transverse vector (direction for 'i' index) / The length represents pixel size in 'i' direction
|-
| align="left" | <sx>, <sy>, <sz>
| align="left" | text number (real)
| align="left" | Transverse vector (direction for 'j' index) / The length represents pixel size in 'j' direction
|-
| align="left" | <nx>, <ny>, <nz>
| align="left" | text number (real)
| align="left" | Normal vector of image plane(direction for 'k' index) /  The length represents pixel size in 'z' direction or slice thickness
|-
| align="left" | <scalar type #>
| align="left" | Pixel scalar type number (Ascii)
| align="left" | 2:int8 3:int8 4:int16 5:uint16 6:int32 7:uint32 10:float32 11:float64
|-
| align="left" | <binary image data>
| align="left" | Binary image data (<xsize>*<ysize>*<zsize>* (pixel size)
| align="left" | Image data
|-
|}
-->

==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==
Quaternion representation of position / orientation.

Parameters (12 or 21 or 24 byte total):
* Vector of three 32 bit (3x4 byte) floats: position X, Y, Z
* Vector of 3 or 4, 32 bit each (3x3 or 3x4 byte) floats: orientation quaternion, normalized
The orientation is optional, if not used the values are (0,0,0,1)<br />
The W element of quaternion is also optional, defaults to 1.

  Bytes (Body)
  58      62      66      70      74      78       82
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
  |   x   |   y   |   z   |   ox  |   oy  |   oz  |    W  |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

==GET_CAPABILITY==
Query for device capabilities.

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


==CAPABILITY==
List of available TYPEs.

  Bytes (Body)
  58                     70
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+....-+-+-+-+-+-+-+-+-+-+-+-+-+
  |    TYPE (12bytes)     |    TYPE (12bytes)     |       |    TYPE (12bytes)     |
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+....-+-+-+-+-+-+-+-+-+-+-+-+-+

== GET_STATUS ==
Parameters: none (BODY_SIZE=0)<br />
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   60            68                           88
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+--+-+-+.....
  | C |  Sub Code   |       Status name           |   Status message (optional)
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+--+-+-+.....

{| border="1" cellpadding="5" cellspacing="0" 
|-
| align="left style="background:#e0e0e0;" | Data
| align="left style="background:#e0e0e0;" | Type
| align="left style="background:#e0e0e0;" | Description
|-
| align="left" | C
| align="left" | Unsigned short (16bit)
| align="left" | Status code groups: 1-Ok, 2-Generic Error, ... (see below)
|-
| align="left" | Sub Code
| align="left" | 64 bit integer
| align="left" | Sub code for the error (ex. 0x200 - file not found)
|-
| align="left" | Error name
| align="left" | char[20]
| align="left" | "Error", "OK", "Warning" - can be anything, don't relay on this
|-
| align="left" | Status Message (optional)
| align="left" | char[ BodySize - 30 ]
| align="left" | Optional (English) description (ex. "File C:\test.ini not found")
|-
|}


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

* Back to [[OpenIGTLink]]