Defining Reconstruction Modes

Adding a new reconstruction mode to the Yarra server involves two steps:

  1. A new .mode file needs to be create in the yarra/modes directory, named according to the internal ID of the reconstruction mode.
  2. The mode needs to be added to the list of available modes, read by the Yarra clients from the file yarra/queue/YarraModes.cfg. With the recent version of Yarra, this step is normally done automatically by the YarraWebGUI.
It is recommended to use the YarraWebGUI for defining and editing reconstruction modes. If the YarraWebGUI cannot be installed for some reason, it a graphical login to the Ubuntu server should be used. If the server is in a remote location, this can be done using remote access tools, such as RDP or NoMachine (FreeNX).


1. Creating Mode Files

It is usually the easiest way to start with an existing .mode file (from the yarra/modes subfolder), create a copy of the file, and to modify this files using the WebGUI (recommended) or a Linux editor such as gedit. The name of the .mode file is important, as this name is internally used as ID for the reconstruction mode. Note: The file name of the .mode file is case sensitive.

Below you can see an example mode file, which can be used as template:

The first section of the file defines the module chain, i.e. the modules that are sequentially executed when a dataset is processed using this reconstruction mode. In each of the sections [PreProcessing], [Reconstruction], [PostProcessing], and [Transfer] modules can be specified by setting the binary path (Bin=…) and the arguments for calling the module (Args=…). Because multiple pre- and post-processing modules can be set, the entry names in the sections [PreProcessing] and [PostProcessing] have an index at the end, running from 1 to a maximum of 20 (Bin1, Bin2, … , Bin20). As additional parameter, it is possible to disable the memory monitoring for each of the modules by adding

to each of these sections (this entry does not have an index value). If set to true, YarraServer will not terminate the module when the memory usage threshold is exceeded. This should used only is necessary, because excessive memory usage might lead to heavy memory swapping that might make the server unresponsive.

The second section defines general options of the reconstruction mode. If KeepRawdata is set to true, the submitted measurements files will be moved to the yarra/finished directory after the reconstruction. This setting needs to be used if the data should archived for later reprocessing (e.g., for additional research studies). If the setting is false (this is the default setting), the raw data files will be deleted and cannot be recovered after the reconstruction has been completed successfully. If the setting NightTask is set to true, all reconstruction tasks that are submitted with this for this mode will be processed with night priority (i.e. during night time). This can be useful for certain reconstruction techniques that are known to run over a longer period of time, so that clinical reconstructions would be blocked if processed during normal working hours.

Finally, the third section of the .mode file contains module-specific settings. By convention, these settings are written into a section with a name equal to the corresponding module. Which module-specific settings exist as well as which arguments should be used for the function calls can be seen in the documentation of the individual modules (see here for the modules that come with YarraServer).

A number of macros are available that can be used to write the binary paths and calling arguments. The following macros are currently available:

Macro Meaning
%rif Name of the input file (TWIX file), including extension (.dat)
%rid Path of the input file (normally yarra/work) without trailing “/”
%rin Name of the input file without extension
%rit Name if the task file, including the extension (.task, .task_prio, .task_night)
%rod Output directory for the reconstruction module
%pid For post-processing modules: Path with the input files
%pod For post-processing modules: Output path
%td For transfer modules: Path with the input files that should be transferred
%bd Directory where the binaries of the modules are located (usually yarra/modules)
%md Path to the mode files (usually yarra/modes)
%mf Name of the mode file of the current reconstruction mode
%mc Name of the mode file including the path (%md/%mc)
%tmp Path where modules can create temporary files (deleted after each step)
%vacc Submitted accession number
%vparam Submitted free parameter value (if provided by mode)
%vuid Unique task ID (incl processing time stamp)
%vtid Task ID without time stamp (not unique if task sent twice)
%hq Quote mark character (needed for nested Matlab calls with arguments)
%hmb Matlab binary including path (as defined in server configuration)


 2. Updating the List of Available Modes

The .mode file describes what the YarraServer should do if a reconstruction task of this kind is received. In order that the Yarra clients know what reconstruction modes are available, they need to be listed in the file queue/YarraModes.cfg.


2.1 Generating the Mode List with YarraWebGUI

The YarraWebGUI now provides a convenient mechanism to automatically generate the file queue/YarraModes.cfg from information provided in the .mode files. This has the advantage that all information about a reconstruction mode, i.e. the information that the server needs as well as the information that the clients need, are contained in only a single file. To provide the client information in the .mode files, a section called [ClientConfig] needs to be added to the .mode file:

The entries SortIndex and Disabled are optional. SortIndex allows to specify at what position the mode should appear in the list as displayed in the UI. Disabled can be used to temporarily remove a mode from the list without deleting the mode file. The mode list can then be created by pressing the button “Generate Mode List” on the Configuration page of the WebGUI. The WebGUI will afterwards show an overview of all modes written into the mode list.

The following entries can be defined in the individual section for each reconstruction mode (Name, Tag, and RequiresACC are required entries):

Macro Meaning
Name Readable name of the reconstruction mode (can be long), e.g. “GRASP Prostate 3T”
Tag Protocol tag, used to automatically assign the reconstruction mode to scans, e.g. “_YP”
RequiresACC Set to true of the Yarra client should request an ACC # (needed for sending DICOMs into PACS)
RequiresAdjScans Set to true if adjustment scans, such as prescan normalize, should be sent with the measurement data (only relevant for the VB software line)
ConfirmationMail Email addresses that always should get notification emails (multiple addresses can be separated by comma)
ParamLabel If a user parameter should be requested by the client: Label for the parameter
ParamDescription If a user parameter should be requested by the client: Text description of the parameter
ParamDefault If a user parameter should be requested by the client: Default value (integer)
ParamMin If a user parameter should be requested by the client: Minimum value (integer)
ParamMax If a user parameter should be requested by the client: Maximum value (integer)
It is currently not possible to use comma characters “,” in the “Name= …” entries. If a comma is used, the name of the reconstruction mode might disappear in the ORT and SAC clients.


2.2 Manually Editing the Mode List using a Linux Shell

If the WebGUI is not available, the files can be edited by logging into the Linux server using the account yarraserver and opening a command shell. The mode file is usually set to read-only permissions. To edit the file, it is first necessary to change the file permission:

After the file has been edited, the permission should be set to read-only again:

The file YarraModes.cfg has the following structure:

The section [Modes] defines which reconstruction modes are available and in which order they should be shown in the UI (when using manual assignment). The index of the entries must start with 0 and increase by 1 for each mode. The name listed behind the equal sign must be identical with the name of the .mode with in the modes directory. Be aware that the names are case sensitive.

Each reconstruction mode must also have an individual section in the YarraModes.cfg file with additional information that is needed for the Yarra client. Make sure that the spelling of the section name is identical to the entry in the [Modes] section and identical to the file name of the .mode file.