OpenIGTLink/Protocol

From NAMIC Wiki
Jump to: navigation, search
Home < OpenIGTLink < Protocol

<< OpenIGTLink

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[8] 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)


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. 

 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

  • 3D Position
  • Optional: Orientation

STATUS

 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 No Errors Found (use status 1 instead!)
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)
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

Includes:

  • Set workphase (Slicer -> Robot)
  • Query (Slicer -> Robot)
  • Responses (Robot -> Slicer)

Open questions

  1. What if the application receives hundreds of "position" packets?
    Should we add "keep only the last" flag to the packet type?
  2. Authentication (other than Unique Name)
  3. Compression
  4. Priority
  5. Duplicate messages

Resources

Retrieved from "https://www.na-mic.org/w/index.php?title=OpenIGTLink/Protocol&oldid=21765"