.. _workspaces:

Workspaces
==========

The Workspace feature allows for saving the existing state of the ImFusion Suite (such as loaded data and executed algorithms) in order to restore the session at a later point in time or automate the execution of a series of actions in a similar fashion as scripting.



Saving Workspaces
-----------------
In the ImFusion Suite you can click on the **Save Workspace** button in the top horizontal menu bar at any time.
This opens the save dialog in which you can specify where to store the workspace file and also configure what aspects of the current session should be stored and in which fashion.

.. figure:: workspaces-save-dialog.png
  :align: center

  Save Workspace Dialog


- **Workspace Type**: You can choose between two options:

  - A *Replay Workspace* will attempt to replay each algorithm that was executed in the ImFusion Suite based on the original input data. This approach is similar to scripting and no intermediate data is stored.
  - A *Snapshot Workspace* will instead not store any of the executed algorithms but only the final state of the current session. Therefore, the contents of the Data Widget are stored in a separate ``*.imf`` file next to the workspace file.

- **Remove Defaults on Save**: Configuration parameters that are equal to the default settings will be stripped from the workspace file.
- **Remove Empty Properties on Save**: Makes the resulting .iws file leaner by omitting empty sections.
- **Save Absolute Paths**: If this is disabled paths to files/directories will be stored as paths relative to the directory where the .iws file is stored. This enables you to move workspace files and data together to a different computer (as long as their relative position on the filesystem remains the same).
- **Save Display State**: Configures whether the display state such as windowing information, visible data, etc. should be stored or not.
- **Compose Workspaces on Save**: Nested workspaces (cf. :ref:`nested-workspaces`) will remain nested *(only applies to Replay Workspaces)*
- **Data Components**: Select which DataComponents (metadata) should be stored for each dataset in the workspace file. Since most DataComponents are created automatically when opening datasets, you should only select those that you actively changed, such as display option/windowing-related ones.

.. Warning::
  The Workspace format is limited in what it can achieve.
  Depending on the selected workspace type different aspects of the current session are captured and you may lose information.
  Loading a workspace file later may not restore all aspects in the exact same way!



Loading Workspaces
------------------
Loading a workspace file is as simple as clicking on the **Open** button in the top menu bar and selecting the file in the open dialog or alternatively using drag-and-drop.
Loading a workspace will **not** clear the current session before restoring the contents.
This is by design, as it allows for applying the scripting features of workspace files to an already existing session.



Editing Workspace Files
------------------------
Workspaces are stored in files with the ``*.iws`` extension and encoded in an XML scheme.
This enables advanced users to manually edit workspace files in order to customize those or fix issues in case the automatic recording was incomplete.

The following block shows an (incomplete) summary of the individual sections of a workspace file:

.. code-block:: xml

  <propertyfile version="1.1">
    <param name="workspaceVersion">16</param>

    <!-- List of algorithms that are created/executed sequentially on load -->
    <property name="Algorithms">
      <property name="[Algorithm Name]">
        <param name="inputUids">[Stringlist of input data UIDs]</param>
        <param name="outputUids">[Stringlist of output data UIDs]</param>
        <param name="execute">[0|1]</param>
        <param name="...">[Further algorithm-specific configuration]</param>
      </property>
      ...
    </property>

    <!-- Required when nesting multiple workspace files -->
    <property name="Interface">
      <param name="outputUids">[Stringlist of output data UIDs]</param>
      <param name="inputUids">[Stringlist of input data UIDs]</param>
    </property>

    <!-- Allows for restoring custom metadata for individual Data -->
    <!-- Applied after the Algorithm creating the corresonding data instance has finished -->
    <property name="Datasets">
      <property name="Data">
        <param name="uid">[String UID used for cross-referencing]</param>
        <param name="name">[Name in DataModel]</param>
        <param name="...">[Further optional per-data configuration]</param>
        <property name="Components">
          <!-- List of serialized DataComponent configuration (e.g. display options) -->
        </property>
      </property>
      ...
    </property>

    <!-- List of annotations (i.e. Annotation Widget content) and their properties -->
    <property name="Annotations">
      <property name="[Annotation Type]">
        <param name="parentDataUid">[Optional Parent Data UID]</param>
        <param name="referenceDataUid">[Optional Reference Data UID]</param>
        <param name="frame">[Optional attached frame]</param>
        <param name="...">[Further annotation-specific configuration]</param>
      </property>
    </property>

    <!-- Configuration of the Display Widget and its views -->
    <property name="Display">
      <param name="layoutMode">0</param>
      <param name="focusedView">1</param>
      <property name="Views">
        <!-- List of views and their configuration -->
      </property>
      <property name="VisibleData">
        <!-- UIDs of shown data for each view -->
      </property>
    </property>
  </propertyfile>


You can see that the information is stored in a hierarchical fashion and that many blocks need to cross-reference elements of other blocks in the same file.
Cross-referencing is done based on unique alpha-numeric identifiers (UID).
For instance, an algorithm may create one or multiple output images, which at this point will map to the UID(s) of the corresponding ``outputUids`` field.
After algorithm execution each newly created data will be assigned custom meta information as defined in the ``Datasets/Data`` section with the corresponding ``uid`` field.
Furthermore, a subsequently executed algorithm can then use them as input by specifying their UID(s) in the corresponding ``inputUids`` field.

.. Note::
  None of the blocks are mandatory, you can omit any that you do not need.


.. _nested-workspaces:

Nesting of Workspace Files
``````````````````````````

Very advanced use cases may benefit from a feature that allows for nesting of multiple workspace files (where each workspace forms an individual building block).
In order to have a parent workspace execute a child workspace you must add the special proxy Algorithm ``Run Workspace`` in the ``Algorithms`` section of the parent.

.. code-block:: xml

  <property name="Run Workspace">
      <param name="location">path/to/child-workspace.iws</param>
      <param name="inputUids">...</param>
      <param name="outputUids">...</param>
  </property>

The ``Interface`` block enables you to map the UIDs between parent and child (since they do not necessarily match) and offers additional safety checks in case parent and child get out of sync.

For instance, the child expects ``dataX`` while the parent refers to the same entity as ``dataY``.
In this case the parent workspace would put ``dataY`` in the ``Algorithms/Run Workspace/inputUids`` field while the child workspace has ``dataX`` in the ``Interface/inputUids`` field.
The outputs work in the same fashion.



Placeholders in Workspace files
-------------------------------

Workspace files allow the user to restore a session or automate the execution of a series of data loading and algorithms.
When parts of this process depends on a varying parameter or data location, placeholders can be used to avoid creating multiple copies of the workspace.


Defining Placeholders
`````````````````````

A placeholder is a sequence of characters in an .iws file that will be replaced at runtime by values indicated by the user.
Each placeholder is uniquely defined by its key and should be used within brackets preceded by a percent sign: ``%(MyKey)``.

For instance, resampling an image with varying resolutions and interpolation mode can be done with the following piece of workspace:

.. code-block:: xml

  <property name="Image Resampling">
      <param name="resamplingMode">2</param>
      <param name="targetSpacing">%(Spacing) %(Spacing) %(Spacing)</param>
      <param name="createNewImage">1</param>
      <param name="forceCPU">0</param>
      <param name="interpolationMode">%(InterpMode)</param>
      <param name="inputUids">data0</param>
      <param name="execute">1</param>
  </property>


If a workspace containing placeholders is loaded from the ImFusion Suite or the ImFusion Console the user will be prompted to define the value of each of these placeholders.
After such values have been entered the workspace will be executed.

.. figure:: workspaces-placeholder-dialog.png
  :align: center

  Dialog shown in the ImFusion Suite when opening a workspace with placeholders

The value of the placeholders can also automatically be defined though the command arguments, for instance: ``./ImFusionSuite MyWorkspace.iws Spacing=2.0 InterpMode=0``.
See :ref:`cmdline` for details.

It is also possible to manually add a section with placeholder definitions to a workspace file:

.. code-block:: xml

  <property name="Placeholders">
	  <param name="Spacing">1.5</param>
  </property>


Running Workspace Batches
`````````````````````````

In some cases, the user needs to execute a lot of times the same workspace with different placeholders values.
While it is always possible to create a script file that executes the ImFusion Suite with various command arguments, this method is not cross-platform.
An alternative is to directly load the .iws file from the ImFusion Suite and, when asked for the values of the placeholders, click on the button **Load Batch File...** and select a text file with the following structure

::

  InterpMode;Spacing
  0;1.0
  1;1.0
  0;2.0
  0;3.0

For each line of this file, the workspace will be executed with the specified placeholders values.
Note that the order of the placeholders is defined by the first header line.
This example is therefore equivalent to

.. code-block:: bash

  ./ImFusionSuite MyWorkspace.iws Spacing=1.0 InterpMode=0
  ./ImFusionSuite MyWorkspace.iws Spacing=1.0 InterpMode=1
  ./ImFusionSuite MyWorkspace.iws Spacing=2.0 InterpMode=0
  ./ImFusionSuite MyWorkspace.iws Spacing=3.0 InterpMode=0

In order to run the ImFusion Console with such a file, its path should be indicated as follows: ``./ImFusionConsole MyWorkspace.iws batch=BatchList.txt``
The optional parameter ``batchCase`` can be used to select a single entry from the batch file (the first valid entry is 1, a value of 0 or other will cause the GUI to prompt for a single case). It is also possible to add the batch file and case parameters to the Placeholders section of a workspace.

See also: :ref:`cmdline`.