The toolkit can be used with a wide range of hardware and software devices in various configurations. All configurable parameters are specified in a Device set configuration file, which describe the used devices, connection between devices, algorithms that operate on data provided by devices, and applications that use devices and algorithms.

Writing the correct configuration file is essential and it is important to devote sufficient time and attention to this task. The description on this page and the provided examples should help in creating the configuration file, but in case of any problems post a question on the message board and you will very likely to get an answer within a few hours.

Data collection devices

Most commonly, there is already a device set configuration file that just requires slight modifications in the Data collection configuration section. This section contains the list of all supported hardware and software devices. Common parameters and general description of the configuration file are provided in subsequent sections.

Ultrasound systems

Framegrabbers and cameras

Network imaging devices

Generic pose tracking devices

Inertial measurement units

Other tracking devices

Simulators

Data processors

Other data acquisition and control devices

ThorLabs compact spectrometer
Generic serial device - such as Arduino microcontroller
Optimet ConoProbe single-point measuring sensor

Data collection configuration

The data collector component acquires data from several physical or software devices simultaneously and processes and combines the acquired data.

Definitions

Device: An independent data acquisition or processing element. Each device has its own processing thread that runs in parallel with other devices and responsible for reading data from its inputs and providing data on its outputs.
Data source: Provides a single stream of data items, a stream can either consists of a sequence of transforms (tracker stream) or a sequence of two-dimensional images (video stream). The stream also contain metadata for each item: a timestamp and status (if the item is valid or not).
Channel: Bundles the output of multiple data sources. One channel can contain up to one video stream and any number of tracker streams.
Output channel: Devices usually provide data to other devices or to algorithms through an output channel. An output channel contains a circular buffer that stores the last N data items of all associated streams, which typically allows algorithms to access the data acquired in the last few seconds.
Input channel: A device may receive data from another device. This is specified by listing the data provider device's output channel(s) as input channel(s) in the data receiver device. One device can receive data from multiple other devices and one output channel can be connected to multiple device's input channel.

How to write the DataCollection section of the configuration file

The best way to get started is to find example configuration file(s) for the hardware device(s) that you would like to use. There are simple example configuration files in the installation package in the Config directory: PlusDeviceSet_Server_(some-hardware-device).xml. In the device set selector in Plus applications these configurations appear as "PlusServer: (some-hardware-device) device". Try to connect to each of device one-by-one and verify if the data collection is successful (no error messages in the log, data sent through OpenIGTLink is visualized correctly in 3D Slicer/SlicerIGT).

To collect data from multiple devices:

Add Device elements of all used hardware devices into the DataCollection element in the configuration file
Add a Virtual Mixer device to create a channel that contains information from the output of all hardware devices. Most often one mixer device is sufficient, but in case multiple different channels have to be constructed with different contents, multiple mixer devices can be added.
Use the output channel of the Virtual Mixer device in other devices (such as Virtual Capture and Virtual Volume Reconstructor) and in applications (for example: in fCal element's DefaultSelectedChannelId attribute; PlusOpenIGTLinkServer element's OutputChannelId attribute)

Common data collection settings

DataCollection
- StartupDelaySec The data collector waits for this amount of time before reporting that connection is established. This delay makes sure that all devices are fully initialized before the application starts to use them.
- DeviceSet
  - Name Device set name as it appears in the menu where the user can select it.
  - Description More detailed description about the device set.
- Device See Data collection devices page for a list of available devices. There can be multiple elements, each describes a physical or software device.
  - Type. Defines the name of device type used.
  - AcquisitionRate. Defines how many frames the device should acquire in a second. Depending on capabilities of the device the actual frame rate may differ from this requested frame rate. Optional, default is specified by the device.
  - LocalTimeOffsetSec. This value allows for compensating time lag of the data acquisition of the device. The value is typically determined by temporal calibration. Global time (common for all devices in the process) is computed from the device's local time (timestamps provided by the device) as: GlobalTime = LocalTime + LocalTimeOffset. Therefore, if local time is the time when the process receives the data from a device and it takes 0.5 sec for the device to acquire data and send to the process then the LocalTimeOffsetSec value will be -0.5. Optional. Default value is 0 sec.
  - MissingInputGracePeriodSec. This value defines for how long after initiating connection a device should not report missing inputs as error. After the grace period expires, the device will report missing inputs as errors or warnings. The value is typically used by devices that uses the output of other devices, such as disc capture or ultrasound simulator. Optional. Default is specified by the device.
  - ToolReferenceFrame. Reference frame name of the tools. Required for tracking devices.
  - ReportUnknownToolsOnceWhen data recording is attempted for an unknown tool it will be reported as an error on each attempt if this flag is FALSE. Othwerwise it is reported only once after each Connect.
  - InputChannels. List of input channels that the device requires (each input channel is connected to the output channel of another device).
    - InputChannel
      - Id . Identifier of the an OutputChannel of another device
  - DataSources. List of data streams that the device generates (e.g., by reading from a hardware device) and may provide on its output channels.
    - DataSource. Each data source corresponds to a tracked tool or imaging source. Attributes include:
      - Id. Identifier of the tool or image stream. For a tracking tool the transform name is constructed from this identifier as Id To ToolReferenceFrame.
      - Type. Type of the data source. Can be Tool or Video.
      - BufferSize. Specifies how many most recent data items the device should keep in memory. It is advisable to keep in memory at least the data that is acquired in the last couple of seconds, to allow synchronized retrieving of data from various devices with slightly different time offsets at the same time. The buffer also helps avoiding data loss when temporarily the process is busy with computations or input/output operations. Too high value results in large memory areas allocated to these buffers, thus reducing available memory for other operations, such as volume reconstruct. Required. Minimum recommended value is 5 times AcquisitionRate (last 5 sec data is kept in memory).
      - AveragedItemsForFiltering. Number of items used for timestamp jitter reduction filtering. Timestamp jitter filtering is only used if the device does not provide timestamps and so the data collector applies timestamps when it receives the data.
      - PortName. Port name is used to identify the tool among all the tools provided by the device.
      - PortUsImageOrientation. The orientation of the image outputted by the device. See detailed description at Ultrasound image orientation.
        
        US_IMG_ORIENT_UF image x axis = unmarked transducer axis, image y axis = far transducer axis.
        
        US_IMG_ORIENT_UN image x axis = unmarked transducer axis, image y axis = near transducer axis.
        
        US_IMG_ORIENT_MF image x axis = marked transducer axis, image y axis = far transducer axis.
        
        US_IMG_ORIENT_MN image x axis = marked transducer axis, image y axis = near transducer axis.
        
        US_IMG_ORIENT_FU image x axis = far transducer axis, image y axis = unmarked transducer axis (usually for RF frames).
        
        US_IMG_ORIENT_NU image x axis = near transducer axis, image y axis = unmarked transducer axis (usually for RF frames).
        
        US_IMG_ORIENT_FM image x axis = far transducer axis, image y axis = marked transducer axis (usually for RF frames).
        
        US_IMG_ORIENT_NM image x axis = near transducer axis, image y axis = marked transducer axis (usually for RF frames).
        
        US_IMG_ORIENT_UFA image same as 2D counterpart, with third axis in ascending direction
        
        US_IMG_ORIENT_UNA image same as 2D counterpart, with third axis in ascending direction
        
        US_IMG_ORIENT_MFA image same as 2D counterpart, with third axis in ascending direction
        
        US_IMG_ORIENT_MNA image same as 2D counterpart, with third axis in ascending direction
        
        US_IMG_ORIENT_UFD image same as 2D counterpart, with third axis in descending direction
        
        US_IMG_ORIENT_UND image same as 2D counterpart, with third axis in descending direction
        
        US_IMG_ORIENT_MFD image same as 2D counterpart, with third axis in descending direction
        
        US_IMG_ORIENT_MND image same as 2D counterpart, with third axis in descending direction
      - ImageType. The image type(B-mode, RF, ...) provided by the video source.
        
        BRIGHTNESS B-mode image.
        
        RF_REAL RF-mode image, signal is stored as a series of real values.
        
        RF_IQ_LINE RF-mode image, signal is stored as a series of I and Q samples in a line(I1, Q1, I2, Q2, ...).
        
        RF_I_LINE_Q_LINE RF-mode image, signal is stored as a series of I samples in a line, then Q samples in the next line(I1, I2, ..., Q1, Q2, ...).
        
        RGB_COLOR RGB24 color image.
      - ClipRectangleOrigin. Clipping rectangle origin for the grabber (in pixels). The first pixel position is "0 0 0" If any of the values is -1 then no clipping will be performed. For two-dimensional images the third component may need to be omitted.
        
        Default = "-1 -1 -1"
      - ClipRectangleSize. Clipping rectangle size for the grabber (in pixels). If any of the values is -1 then no clipping will be performed. For two-dimensional images the third component may need to be omitted.
        
        Default = "-1 -1 -1"
  - OutputChannels. List of output channels that the device provides. Most devices require the specification of a single output channel.
    - OutputChannel
      - Id Identifier of the OutputChannel. Must be a unique name across all devices.
      - VideoDataSourceId Identifier of the video DataSource that will be included in the output.
        
        DataSource An element for each tracking tool to be included in the output.
        
        Id Identifier of the tool DataSource.
      - RfProcessing For ultrasound imaging devices that are capable of acquiring RF data. If this element is specified then the output of the channel will be the processed RF image.

Device set configuration file

This XML configuration file describes all inputs that are needed by any Plus application. This file defines the device set, that is used in course of acquisition, the coordinate frames, the segmentation parameters, the phantom definition (properties, geometry, registration), and data elements for algorithms and applications. The file contains the following XML elements:

PlusConfiguration
- Version Major Plus toolkit version the configuration file is compatible with
- PlusRevision Detailed Plus toolkit version that created the configuration file
- Data collection configuration Definition of all devices used for collecting and processing data. See Data collection devices for list of supported devices.
- Coordinate systems definitions List of fixed transforms
- Application elements
  - Freehand calibration (fCal) settings
  - Plus server settings
- Algorithm elements