Adding a new reconstruction mode to YarraServer involves two steps:
It is strongly recommended to use the Yarra WebGUI for defining and editing reconstruction modes. If the Yarra WebGUI cannot be installed, a graphical login to the Ubuntu server should be used to simplify the editing. If the server is in a remote location, this can be done using remote access tools, such as X2Go.
It is usually the easiest way to start with an existing .mode file (from the yarra/modes subfolder), to create a copy of the file, and to modify this files using the WebGUI (recommended) or a Linux editor such as gedit or nano. 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:
;## YarraServer -- Reconstruction Mode Definition
;##
;## Information for Yarra client ##
[ClientConfig]
Name=GRASP Hematuria (3T/1.5T)
Tag=_YH
RequiresACC=TRUE
RequiresAdjScans=FALSE
ConfirmationMail=
SortIndex=1
Disabled=false
;## Definition of module chain ##
[PreProcessing]
Bin1=%bd/IniPatch
Args1=%mc %md/NUFFT.ini %rid/settings.ini %vparam
[Reconstruction]
Bin=%bd/GraspR_r331
Args=%rid/%rif %rid/settings.ini %rod %tmp %vacc
[PostProcessing]
[Transfer]
Bin=%bd/DriveTransfer
Args=%mc %td %vuid
;## Additional options ##
[Options]
KeepRawdata=true
NightTask=false
;## Module-specific settings ##
[IniPatch]
PatchKey1=Preprocessing/SpokesPerFrame1
PatchKey2=Preprocessing/SlidingWindowSize
PatchKey3=Preprocessing/SpokesPerTimestep
[DriveTransfer]
TargetPath=/media/networkshare/yarra_out
The first part of the file contains information that is used by the Yarra client (see section below). The second part defines the module chain executed on the YarraServer, 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 location (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 processing steps by adding:
DisableMemKill=true
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 be used only if necessary because excessive memory usage might lead to heavy memory swapping that can make the server unresponsive. In addition to checking the memory, YarraServer measures the duration how long a module does not create any output. If the threshold of 1800 sec without output is exceeded, the module will be terminated because it is assumed that the modules hangs. The threshold value (in seconds) can be overwritten for each module by adding the following statement to the corresponding section:
MaxOutputIdle=7200
The third part of the mode file 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 last part 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) |
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.
The YarraWebGUI 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:
[ClientConfig]
Name=GRASP Hematuria (3T/1.5T)
Tag=_YH
RequiresACC=TRUE
RequiresAdjScans=FALSE
ConfirmationMail=
SortIndex=1
Disabled=false
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):
| Entry | 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 number (needed for sending DICOMs into PACS or to workstations) |
| 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 parameter should be requested by the client: Label for the parameter |
| ParamDescription | If a parameter should be requested by the client: Text description of the parameter |
| ParamDefault | If a parameter should be requested by the client: Default value (integer) |
| ParamMin | If a parameter should be requested by the client: Minimum value (integer) |
| ParamMax | If a 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.
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:
chmod 640 queue/YarraModes.cfg
gedit queue/YarraModes.cfg
After the file has been edited, the permission should be set to read-only again:
chmod 440 queue/YarraModes.cfg
The file YarraModes.cfg has the following structure:
;## Ordered list of available modes
[Modes]
0=GRASP_Body
1=GRASP_Prostate_15T
2=GRASP_Manual_PACS
3=GRASP_Manual_Net
;## Description of modes
[GRASP_Body]
Name=GRASP Body Liver Kidney
Tag=_YB
RequiresACC=TRUE
RequiresAdjScans=FALSE
ConfirmationMail=tobias.block@nyumc.org
[GRASP_Prostate_15T]
Name=GRASP Prostate (Mobiles)
Tag=_YPM
RequiresACC=TRUE
RequiresAdjScans=FALSE
ConfirmationMail=tobias.block@nyumc.org
[GRASP_Manual_Net]
Name=Manual GRASP (to NewRaw)
Tag=_YMN
RequiresACC=FALSE
RequiresAdjScans=FALSE
ConfirmationMail=
ParamLabel=Spokes
ParamDefault=21
ParamMin=5
ParamMax=9999
ParamDescription=The GRASP reconstruction requires to select the number of spokes per frame.
[GRASP_Manual_PACS]
Name=Manual GRASP (to PACS)
Tag=_YMP
RequiresACC=TRUE
RequiresAdjScans=FALSE
ConfirmationMail=
ParamLabel=Spokes
ParamDefault=21
ParamMin=5
ParamMax=9999
ParamDescription=The GRASP reconstruction requires to select the number of spokes per frame.
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.