Difference between revisions of "OpenIGTLink/Protocol"

From NAMIC Wiki
Jump to: navigation, search
 
(41 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
[[OpenIGTLink | << OpenIGTLink]]
 
[[OpenIGTLink | << OpenIGTLink]]
 +
 +
 +
<div class="redirectText">'''OpenIGTLink 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=
 
=Header Structure=
Line 23: Line 51:
 
|-
 
|-
 
| align="left" | TYPE
 
| align="left" | TYPE
| align="left" | char[8]
+
| align="left" | char[12]
 
| align="left" | Type name of data
 
| align="left" | Type name of data
 
|-
 
|-
Line 44: Line 72:
 
|}
 
|}
  
= Data types =
+
= Data types (Common across implementations) =
 
Data type:
 
Data type:
 
* Command (get position, get status, go to target, stop, start continuous push, stop push, ready)
 
* Command (get position, get status, go to target, stop, start continuous push, stop push, ready)
 
* Data (image, position, status)
 
* Data (image, position, status)
 
  
 
==IMAGE==
 
==IMAGE==
 
  Bytes
 
  Bytes
  58  60  62          68                     80                     92                     104                        118
+
  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  |
 
  | V |T|S|E|O|RI |RJ |RK |  TX  |  TY  |  TZ  |  SX  |  SY  |  SZ  |  NX  |  NY  |  NZ  |  PX  |  PY  |  PZ  |
 
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
 
    
 
    
  118        128         140
+
  118        124         130
 
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+....
 
  +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+....
 
  |DI |DJ |DK |DRI|DRJ|DRK|  IMAGE_DATA
 
  |DI |DJ |DK |DRI|DRJ|DRK|  IMAGE_DATA
Line 76: Line 103:
 
| align="left" | T
 
| align="left" | T
 
| align="left" | 8bit unsigned int
 
| align="left" | 8bit unsigned int
| align="left" | Image type (1: Scalar)
+
| align="left" | Image type (1: Scalar, 3: Vector)
 
|-
 
|-
 
| align="left" | S
 
| align="left" | S
 
| align="left" | 8bit unsigned int
 
| align="left" | 8bit unsigned int
| align="left" | Scalar type (2:int8 3:int8 4:int16 5:uint16 6:int32 7:uint32 10:float32 11:float64)
+
| 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" | E
 
| align="left" | 8bit unsigned int
 
| align="left" | 8bit unsigned int
| align="left" | Endian for image data (1:BIG 2:SMALL) (NOTE: values in image header is fixed to BIG endian)
+
| 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" | O
 
| align="left" | 8bit unsigned int
 
| align="left" | 8bit unsigned int
| align="left" | image coordinate (2:LPS 1:RAS )
+
| align="left" | image coordinate (1:RAS 2:LPS)
 
|-
 
|-
 
| align="left" | RI, RJ, RK
 
| align="left" | RI, RJ, RK
 
| align="left" | 16 bit unsigned int
 
| align="left" | 16 bit unsigned int
 
| align="left" | Number of pixels in each direction
 
| 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" | TX, TY, TZ
Line 109: Line 132:
 
| align="left" | 32 bit float
 
| 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" | Normal vector of image plane(direction for 'k' index) /  The length represents pixel size in 'z' direction or slice thickness
 +
|-
 +
| align="left" | PX, PY, PZ
 +
| align="left" | 32 bit float
 +
| align="left" | center position of the image <font color=red> * </font>
 
|-
 
|-
 
| align="left" | DI, DJ, DK
 
| align="left" | DI, DJ, DK
Line 120: Line 147:
 
| align="left" | IMAGE_DATA
 
| align="left" | IMAGE_DATA
 
| align="left" | Binary image data ()
 
| align="left" | Binary image data ()
| align="left" | Image data
+
| align="left" | Image data (endian is determined by "E" field)
 
|-
 
|-
 
|}
 
|}
 +
 +
<font color=red>* NOTE 1/10/11: There was a discrepancy between the protocol document and the library. Since the library has been used by most of OpenIGTLink software, the protocol document was modified to be consistent with the library.</font>
  
 
<!--
 
<!--
Line 166: Line 195:
 
| align="left" | <binary image data>
 
| align="left" | <binary image data>
 
| align="left" | Binary image data (<xsize>*<ysize>*<zsize>* (pixel size)
 
| align="left" | Binary image data (<xsize>*<ysize>*<zsize>* (pixel size)
| align="left" | Image data (endian is determined by "E" feild
+
| align="left" | Image data
 
|-
 
|-
 
|}
 
|}
Line 173: Line 202:
 
==TRANSFORM==
 
==TRANSFORM==
 
The transform data is upper three rows of 4x4 transformation matrix, where element (3,3) is assumed to be 1.
 
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)
 
   Bytes (Body)
Line 181: Line 212:
  
 
==POSITION==
 
==POSITION==
* 3D Position
+
Quaternion representation of position / orientation.
* Optional: Orientation
+
 
 +
Parameters (12 or 24 or 28 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_CAPABIL==
 +
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==
 
==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)
 
   Bytes (Body)
 
   58  60            68                          88
 
   58  60            68                          88
Line 207: Line 273:
 
| align="left" | Error name
 
| align="left" | Error name
 
| align="left" | char[20]
 
| align="left" | char[20]
| align="left" | "Error", "Ok", "Starting up" - can be anything, don't relay on this
+
| align="left" | "Error", "OK", "Warning" - can be anything, don't relay on this
 
|-
 
|-
 
| align="left" | Status Message (optional)
 
| align="left" | Status Message (optional)
Line 217: Line 283:
  
 
'''Status codes:'''<br />
 
'''Status codes:'''<br />
0 No Errors Found (use status 1 instead!)<br />
+
0 Invalid packet - 0 is not used<br />
 
1 OK (Default status)<br />
 
1 OK (Default status)<br />
 
2 Unknown error<br />
 
2 Unknown error<br />
Line 229: Line 295:
 
10 Configuration error<br />
 
10 Configuration error<br />
 
11 Not enough resource (memory, storage etc)<br />
 
11 Not enough resource (memory, storage etc)<br />
12 Illegal/Unknown instruction (or feature not implemented)<br />
+
12 Illegal/Unknown instruction (or feature not implemented / Unknown command received)<br />
 
13 Device not ready (starting up)<br />
 
13 Device not ready (starting up)<br />
 
14 Manual mode (device does not accept commands)<br />
 
14 Manual mode (device does not accept commands)<br />
Line 239: Line 305:
 
<br />
 
<br />
  
= Open questions =
+
* Back to [[OpenIGTLink]]
# What if the application receives hundreds of "position" packets? <br> Should we add "keep only the last" flag to the packet type?
 
# Authentication (other than Unique Name)
 
# Compression
 
# Priority
 
# Duplicate messages
 
 
 
= Resources =
 
* [[Slicer3:_Image_Guided_Therapy_(IGT) | Slicer 3 Image Guided Therapy (IGT) suite ]]
 
* [[Slicer/Features/Middleware | Middleware features discussion]]
 
* [http://www.cisst.org/wiki/MRI_robot/MIT_2007_06_27_Meeting Initial discussion about requirements]
 
* [http://www.bioimagesuite.org/public/VVLink.html BioImage Suite VVLink Tool] (uses TCL/TK object streaming)
 

Latest revision as of 20:33, 10 January 2011

Home < OpenIGTLink < Protocol

<< OpenIGTLink


OpenIGTLink protocol description

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

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 (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:

Data Type Description
V unsigned short version number
T 8bit unsigned int Image type (1: Scalar, 3: Vector)
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)
O 8bit unsigned int image coordinate (1:RAS 2:LPS)
RI, RJ, RK 16 bit unsigned int Number of pixels in each direction
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
PX, PY, PZ 32 bit float center position of the image *
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)

* NOTE 1/10/11: There was a discrepancy between the protocol document and the library. Since the library has been used by most of OpenIGTLink software, the protocol document was modified to be consistent with the library.


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 24 or 28 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)
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_CAPABIL

Query for device capabilities.

Parameters: none (BODY_SIZE=0)
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)
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)
 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+--+-+-+.....
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", "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