Neuroterrain Atlas Server Network Protocols

Summary

Protocols

Transmission formats

Client options
Server options

Discussion

Server-side actions
Client-side actions
Mouse Tracking

Appendix

Server Response Message Layout
Client Request Message Layout

Summary

Protocols

The NeuroTerrain Atlas Server (NT-AS) uses two protocols for data transfer. One is intended primarily for control data, the other for display data. The data layout in each protocol is identical, the difference is in how they are processed on the server. The control data protocol ('acp ') is queued for processing at idle time, as some server latency is acceptable. The protocol for display data ('itp ') is handled at interrupt time, to provide minimum latency. Any command sent to the server via an 'itp ' transmission may also be sent via an 'acp ' transmission, but only a limited set of commands are accepted when sent via 'itp '.

Transmission formats

This protocol is designed to be embedded in TCP datagrams, to take advantage of the guaranteed delivery the TCP protocol provides. Image Transfer Protocol datagrams may be embedded inside this protocol, using options 'posn' and 'data' for client and server transmissions, respectively.

Data offset

Content

00

'acp ' format tag

04

Number of options

08

Option ID

12

Option length

16

Option data


Additional options

Multiple options may be included in one datagram.

Option length does not include id or length field.

Option data is padded to maintain 32-bit alignment.

 

Client options:

'atls'

Select atlas: Session establishment -- client selects atlas to browse. Server responds with data about atlas dimensions ('sess' option)

Option length = 8

Option data (with offsets):

0 Atlas reference number
4 session UDP port ID (not implemented - enter zero)

'axis'

Set atlas slicing axis: Sets axis along which to offset virtual knife. If the client is the active member of an active/passive pair, the server sends axis data to the passive client ('caxs' option).

Option length = 4

Option data (with offsets):

0 Axis id

'logI'

Log in: Session establishment -- client initiates session. Server sends a list of available atlases to the client ('alst' option).

Option length = variable

Option data (with offsets):

0 client name string (Pascal style, padded if necessary)

"logQ'

Log in quiet: Session establishment -- client initiates a connection with no further communication with the server until an active client logs in and is linked with the passive client it specifies. (Used to drive the client display from a second, remote client.)

Option length = variable

Option data (with offsets):

0 client name string (Pascal style, padded if necessary)

'logR'

Log in remote: Session establishment for control data -- client initiates a session, with control data going to the initiator, and image data being sent to a specified remote client. A list of available atlases is sent to the client ('alst' option) even if the requested passive client has not yet logged in.

Option length = variable

Option data (with offsets):

0 client name string (Pascal style, padded if necessary)
nn passive client id encoding style (numeric or text)

0 == ip name or text encoded as a dotted-decimal number (pascal-style string)
1 == 32-bit ip number

nn+4 passive client ip name (as Pascal string) or number

'logO'

Log out: Session termination -- client terminates session, connection is broken down (The server does not do anything intelligent with this option, but it should be used by the client.)

Option length = 0

Option data (with offsets):

none

'posn'

Set slice position: (See Client Image Transfer Protocol, above). Server slices the selected atlas and sends the slice in itp-format blocks.

Option length = 28

Option data (with offsets):

00 Sequence number
04 Number format
08 unused
12 X rotation
16 Y rotation
20 Z rotation
24 Slice offset

'vdrw'

VOI Drawing toggle: Toggles drawing of VOIs on and off. Server provides no response.

Option length = 0

Option data (with offsets):

none

'vnam'

VOI name: List VOI names. Server responds with a list of VOI names, abbreviations, current display colors and states. (The server may send multiple blocks with data in response to this request. Each block will contain a header with option information, and serialization information)

Option length = 0

Option data (with offsets):

none

'vsel'

VOI select: Select indicated VOIs for display. It is not necessary for the client to return information on any VOI which has not been changed. If more than one block is needed, multiple transmissions may be sent. No serialization is needed, as the data is acted on as received. Server provides no response.

Option length = variable

VOI count = variable (the number of VOIs being sent in this message block)

Option data (with offsets):

00 VOI reference number
04 Sub option length (including the VOI reference number - 24 bytes, if all VOI elements sent)*
08 VOI display options

0x00000001 Dim display (bright if cleared)
0x00000002 Display (not displayed if cleared)

(Above are masks, form complete option by anding these masks)

12 VOI color, red component
16 color, green component
20 VOI color, blue component

* Color information is optional. If it is not included, the default colors for that VOI are used.

'vmlq'

VOI enclosing mouse location query. Requests the name of the VOI that encloses the point provided in the option data.

Option length = 20

Option data (with offsets):

00 Sequence number
04 Number format
08 X rotation
12 Y rotation
16 Z rotation

'zoom'

Request to zoom the current atlas data set under view.  The client indicates a viewing window as well, so as to provide some control on the absolute amount of zoomed data sent on each knife request.

Option length = 20 (4 if no window sent)

Option data (with offsets):

00 Zoom Factor (type: float; range: 0.10 - 10.0)
04 window centroid X-component (type: float)
08 window centroid Y-component (type: float)
12 window X-dimension (type: float)
16 window Y-dimension (type: float)

* Server returns an atlas parameter block giving new atlas dimensions (see 'sess' message below).

Server Options:

'alst'

Atlas listing: List of atlases available for browsing on this server

Option length = variable

Option data (with offsets):

00 Number of atlases
04 Atlas reference number
08 Atlas name as Pascal string (pad to 32-bit boundary)
nn additional atlas numbers and names.

'busy'

Server busy: Server can not open any more sessions at this time.

Option length = 0

Option data (with offsets):

none

'caxs'

Confirm set axis: The active partner in an active/passive client pair sent a set axis option ('axis'). The passive partner is notified of this by the server.

Option length = 12

Option data (with offsets):

0 New slicing axis
4 Horizontal dimension of the image frame
8 Vertical dimension

'data'

Data transmission: Image data being transmitted in response to 'posn' or 'axis' option from client. (See Server Image Transfer Protocol, above)

Option length = variable

Option data (with offsets):

00 Frame sequence number
04 Image data length
08 Data offset in frame
12 Image data (with pad as needed)

(note: sequence numbers 0xFFFFFFFF and 0xFFFFFFFE are sent as start and end of burst markers, for throughput measurements. The end-of-burst mark contains the number of bytes sent in the burst in place of the data offset in frame field.)

'err '

Server message An error message sent by the server.

Option length = variable

Option data (with offsets):

0 Error message string length
0 Error message string

'mess'

Server message An informational message sent by the server.

Option length = variable

Option data (with offsets):

0 Informational message string length
0 Informational message string

'sess'

Session establishment: Server response to client's selecting of atlas

Option length = 8

Option data (with offsets):

00 Server UDP mouse tracking port (not yet implemented)
04 Atlas X-dimension (as 32-bit integer)
08 Atlas Y-dimension
12 Atlas Z-dimension

'slic'

Slice rate: Sent after a reslice, this option gives information on how fast the server is able to slice atlas and VOI data. (Note that this is overall slice rate expressed per mb data, not per frame.) This is only used during testing and development.

Option length = 8

Option data (with offsets):

0 Number format (see number format under itp options)
4 Slice rate expressed as mb/sec.

'time'

Time out: Sent when client has been inactive for longer than timeout period. Results in session termination. (Not implemented yet)

Option length = 0

Option data (with offsets):

none

'vlst'

VOI listing: Listing of VOIs associated with session atlas. Since there may be more VOIs associated with an atlas than will fit in a single transmission block, data for this option may travel in more than one block. (Each block will contain a header with the option info.)

(Note: there is an error in the software at this point, in that the option length should not be included here.)

Option length = variable

Option data (with offsets):

00 Total length of data sent (over all blocks and headers)
04 VOIs included in the current block
08 Number of transmissions needed for entire set
12 Position of this block in the set

repeated data:
16 VOI reference number
20 VOI display options

0x00000001 Dim display (bright if cleared)
0x00000002 Display (not displayed if cleared)

(Above are masks, form complete option by anding these masks)

24 VOI color, red component
28 VOI color, green component
32 VOI color, blue component
36 VOI abbreviation as 0-terminated string, with pad
36+n VOI name as 0-terminated string,with pad to 32-bit boundary

'vmli'

ID of VOI enclosing point. The name of the Volume of Interest that encloses the specified in the matching 'vmlq' message.

Option length = variable

Option data (with offsets):

0 Sequence number
4 Informational message string length
8 Informational message string

Discussion

Server-side actions

At startup, the server opens a TCP listener (currently port 4444) and waits for client connection attempts. When a connection is accepted, the server creates an instance of a server object, and waits for the client to attempt a login ('logI', 'logQ', 'logR' options). A successful login attempt will result in the server sending a list of available atlases in an 'alst' option, except in the case of a 'logQ' attempt,. This option is used by the passive member of an active/passive client pair, and in this case the server simply adds the connection to a list of passive clients awaiting an active client. (If an active client is already logged in and waiting to pair with a client from the host now logging in as passive, the connection will be made right away, and a 'sess' option followed by a 'data' option will be sent immediately.)

Server responses to specific client options:

'logI', 'logR': Client login attempt. Server responds with an 'alst' option.

'atls': Client's selection of an atlas to browse. Server responds with a 'sess' option,

'posn': Client specifies a virtual knife location. Server responds with a resliced image.

'axis': Client specifies an axis along which to move the virtual knife. If the client is an active client, the server sends an axis-changed message to the passive client, using a 'caxs' option.

'vnam': Client requests a list of available VOIs associated with the atlas. Server responds with the VOIs in one or more 'vlst' option blocks.

Any other client options are acted upon by the server, but no response is sent.

Client-side actions

The client initiates a session by actively opening a TCP connection with a server, and sends an ACP datagram with the 'logI' or 'logR' option. If the session is established successfully, the server sends a list of available atlases (ACP option 'alst'). The client responds to this by selecting an atlas and sending another ACP datagram with the 'atls' option. This option also specifies a UDP port id on the server for further communications during mouse tracking (not yet implemented). At the same time, the client establishes a port for UDP datagrams, (again for mouse tracking, but not yet implemented) and sends them along with the atlas selection.

If the client initiates a session with a "Quiet" login ('logQ' option), the server will not respond initially, except to open a connection. Once a corresponding connection has been made with an active client, communication from the server will resume with a 'sess' option.

At the end of a session (when the client window containing the atlas image is closed, for example) the client terminates the session by sending a datagram with the 'logO' option.

Client uses these additional options to control atlas display

'posn' Sets the position of the virtual slice. Sending a datagram with this option to the server results in the server responding with a 'data' datagram (or many datagrams) containing image data.

'axis' Sets the slicing axis. In general the client will include the 'posn' option after the 'axis' option in a datagram, as the position of the virtual slice would otherwise be undefined.

'vnam' Requests a list of VOIs contained in the atlas. The server responds with a list of VOI names, including reference numbers (used by the server to specify the VOIs) abbreviations and names.

'vsel' Instructs the server to set the visibility attributes (on/off, bright/dim) and colors of the VOIs. VOIs are referred to by number, and visibility attributes must be specified. If color is not specified, the default in the atlas will be used.

'stri' If the client computer is equipped with multiple network hardware ports, data may be striped to the client for higher throughput if the backbone is capable. The server will attempt to send portions of data to all IP addresses, including the one used to establish the session. (Not yet implemented)

Mouse tracking:

Client-sided processes

Mouse tracking is handled in an asynchronous manner.The client should continually send 'posn' requests to the server. These requests will be handled in a LIFO manner, so the serialization of requests should result in only the most recent request being honored. Slice images returned by the server should be handled immediately as received, either by a notifier, or a high-priority task or process.

Currently, the client should use acp-protocol datagrams at all times, including mouse tracking. The server will eventually be fixed to accept itp-protocol datagrams during mouse tracking. (More information in Server-sided processes, below.)

At the end of mouse-tracking, the client should send an additional 'posn' to ensure a clean display.

It is also possible to continually send mouse location data (X,Y,Z coordinates) and have VOI names returned, via the 'vmlq'/'vmli' pair.

Server-sided processes

The server queues all acp-protocol datagrams for processing during idle time. Requests are handled on a LIFO basis, and 'posn' options are serialized, so only the most recent on the queue are handled. Earlier 'posn' options will be discarded as they are encountered. Response to 'posn' options are sent in the form of itp-protocol datagrams, which are handled immediately. Future iterations of the server will likely support itp-protocol 'posn' options.

Slice images are serialized and indexed, so if segments are received out of order, they can be handled appropriately. Stale image data should be discarded, as fresher data is either on the way, or has already arrived.

Once UDP transport has been enabled, the server will respond to 'posn' options using the protocol used for the option - The idea here is that UDP has a lower overhead, and will provide a higher throughput, even though some segments may be lost. Tracking can be finalized with a last request via TCP, which should ensure that the entire image arrives.


Appendix