Get a PDF version of this manual

Preamble

Dafne is a program for the segmentation of medical images, specifically MR images, that includes advanced deep learning models for an automatic segmentation. The user has the option of refining the automated results, and the software will learn from the improvements and modify its internal models accordingly. In order to continuously improve the performance, the deep learning modules are stored in a central server location (see section Deep Learning below)

License

Dafne is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.

Authorship

Dafne has been developed in a joint effort by the University of Basel, the Basel University Hospital, and the Mondino Foundation. See the About page for detailed authorship information.

The main developers currently are: Francesco Santini, Jakob Wasserthal, and Abramo Agosti.

The project is supported by the Swiss National Science Foundation, Spark Project #CRSK-3_196515

Third-party code

Dafne depends on a number of third-party libraries, released under GPL or compatible licenses. For a full list of dependencies, please refer to the requirements.txt and the README.md files in the github repository.

Download and installation

Dafne is written in pure Python, and is thus multi-platform. The code and the distributable binaries are accessible on Github.

Source code installation

The Dafne repository can be cloned with the command:

git clone --recurse-submodules https://github.com/dafne-imaging/dafne.git

This will always obtain the latest version of the repository. To run, it will require a recent version of Python (3.8+), and a number of dependencies that are listed in the file requirements.txt.

In order to use the full functionality, the SimpleElastix package is required. This package is not available on pip, so you should either compile it from source, or you can find some precompiled modules here.

Before installing the other dependencies, you will also need to install tensorflow. Install it with

pip install tensorflow

or

pip install tensorflow-gpu

according to your system compatibility.

Afterwards, install the other dependencies with

pip install -r requirements.txt

and execute the program with

python dafne.py

Note: Dafne requires pypotrace, which is cumbersome to compile under Windows. See this repository for help on how to compile it for Windows, or use the precompiled package pypotrace_cp38_win64.zip included in the dafne repository.

Windows 10 binary installation

In the Github releases page, an installer for Windows generated with PyInstaller and InnoSetup is provided. The installation package is created under Windows 10 version 20H2 and might not work with earlier versions of Windows. Before installing, please make sure that the Visual C Runtime is installed. If unsure, you can download and install it directly from this page (direct link to the installer)

Mac OS binary installation

In the Github releases page, a packaged version for Mac OS (Catalina x64) generated with PyInstaller is available.

This version is distributed as a zip file. Unpack the zip file and execute the file dafne from the extracted folder.

Important note for Mac users: if you download the zip file from github, the system will ask to enter security exceptions for every binary file included in the distribution, because the binaries are not signed. This is too much to do by hand. Either install Dafne from source, or temporarily disable the access control with the following procedure:

  1. Open a terminal window.
  2. Run the command sudo spctl --master-disable (it will ask for your password).
  3. Run Dafne once by executing the dafne file.
  4. Run the calc_transforms command as well.
  5. Re-enable the protection by running the following command in a terminal: sudo spctl --master-enable

Main interface

The main interface of Dafne is composed of two windows:

  • the Toolbox, where the menus and the commands are;

  • the Image Window, where the dataset is visualized.

Image loading and viewing

Open a dataset from the menu File -> Load data… To open a DICOM dataset, navigate to the folder and click on any dicom file. The entire folder will be loaded. After selecting a dataset, a popup window will ask to choose the classification for this dataset, which will determine which deep learning model to use for the automatic segmentation. If no appropriate deep learning model is available, choose None. You will be able to change this afterwards, also on a per-slice basis.

Once the dataset is open, window the image by using the right mouse button. You can scroll through the images with the scroll wheel or with the arrow keys.

Use the buttons Pan and Zoom in the interface to adjust the magnification.

Deep learning

The main feature of Dafne is the possibility of doing automatic segmentation using deep learning models.

Dafne uses incremental learning and federated learning to continuously adapt the models to the need of our users. This means that when you perform a segmentation, initially it will not be perfect. You will then have the chance to refine it. When you are satisfied with your dataset, you will export your ROI masks (see below). During this export procedure, the software automatically learns from your refined segmentation and sends the updated model back to our servers. This is why the export procedure takes some time. We will automatically integrate your updated model with the models of our other users, so you will always receive the most accurate predictor. You can also manually perform the incremental learning from the Tools menu (see below)

It is important to say that your data never leave your computer (unless you explicitly want to), so you don’t have to worry about privacy and data safety.

Currently, we offer two deep learning models:

  1. The thigh model, which identifies 12 muscles of the thigh.

  2. The leg model, which identifies 6 muscles of the leg.

Both models are pretrained on axial proton-density-weighted in-phase gradient echo images (in the picture, an example). Best results will be achieved with similar protocols; however, the model will adapt in the future depending on the user base.

In order to use the deep learning models, you will have to obtain a personalized API key that gives you access to the server. See the “Get Dafne” page to obtain it. Once you have the key, you will have to open the preferences (from Tools->Preferences…) and set the relevant parameters: model location to Remote and your API key in the provided space.

Another relevant setting is the checkbox “Separate L/R in autosegment”. When checked, the left and right limb will generate different ROIs; otherwise, the same muscle on the two different sides will belong to the same ROI.

The toolbox

The tools available in Dafne are displayed in the Segmentation Toolbox window. This window changes according to the current edit mode (mask mode and contour mode, which we’ll see in a moment). However, there is some common functionality to the two modes, which we can see in this image.

Toolbox main

The top box shows the classification of the current slice. It can be changed by simply changing the content of the dropdown box. The button “All” sets the classification for all the slices in the dataset.

The ROI box shows the currently active ROI, with a button to add a new ROI and another to delete the current ROI. Beware! Deleting a ROI will delete it from ALL the slices in the dataset!

In contour edit mode, each ROI is divided in subrois, because each ROI mask can be divided into multiple contours. Adding or deleting a subroi will only affect the current slice.

Below the ROI box, the Autosegment button will perform automatic segmentation using the deep learning model (see above). A dialog will open to allow you to perform the segmentation on a set of slices.

At the bottom of the toolbox, there is a registration section (which is only visible if SimpleITK with the SimpleElastix extension is present, see https://simpleelastix.github.io/ or here for precompiled packages). From this section, propagation of the current ROI to the next/previous slice is performed, by means of nonrigid registration. Calculating the registration across the slices can be time consuming, but the registration information is stored automatically in your image folder (in a file named transforms.p), so subsequent operations will be faster. We suggest you use Calculate transforms to precalculate the transforms for the whole dataset. It will take some time, but it will speed up subsequent operations. Please notice that you will not be able to interact with Dafne while the calculation is in progress. As an alternative, you can use the offline transform calculator, also provided with Dafne and accessible either from the menu, or as a separate program (see below).

Edit modes

Dafne has two edit modes to modify ROIs: the mask mode and the contour mode. In the mask mode, you can “paint” on the image with a brush, whereas in contour mode you can define a contour through control points. We suggest the use of mask mode to refine autosegmented datasets, and contour mode to define new ROIs; however, different options are available in different modes. You can easily switch from one mode to the other in the segmentation toolbox.

Mask edit mode

In mask edit mode, you can paint on your image as you would in an image editing program like Photoshop. The active ROI is shown in red, while non-active ones are shown in blue. If you right-click on the image, the ROIs disappear so you can better see the boundaries (all these settings are customizable in the preferences).

Mask Edit

Clicking on Paint or Erase allows you to add or remove bits to the current ROI. The Brush shape and size determines how the painting is done. You will see a patch of color where the mouse pointer is to show the portion of the image that will be affected. In Erase mode, a checkbox allows you to affect all the ROIs in the image, for example to remove spurious elements outside the overall region of interest. Note: if the patch is not visible, make sure that a) paint or erase are selected b) you are not in zoom/pan mode c) the image window is active by clicking on it.

As a shorthand for paint/erase, you can hold your shift or control button respectively.

Lastly, you can also grow or shrink the mask by clicking on the appropriate buttons on the toolbox.

Contour edit mode

In contour edit mode, you can draw contours by defining handle points, and the software will interpolate between them. This is useful for accurately defining borders of new ROIs. In this mode, the same ROI may have different subROIs. This means that the different closed contours will then be merged to calculate the mask. When contours overlap, the difference is taken (technically, it’s a XOR operation). The active subroi is depicted in red, other subrois belonging to the same ROI (which will be merged) are depicted in yellow, and other ROIs are depicted in blue.

Contour Edit

The small red circles are the handles of the contour. Similarly to paint and erase in mask mode, Add/Move and Remove modify the handles accordingly. Clear removes all the handles from the current subroi (while leaving the subroi acitve). Conversely the - button next to the subroi menu deletes the subroi altogether.

The Translate mode allows moving the whole contour, while Rotate allows rotation around the center of mass.

Menus

Dafne has three main menus: the File menu, the Tools menu, and the ROI menu.

The File menu

This menu contains the input/output options.

File Menu

  • Load Data will load a new dataset. Currently, Dicom and Numpy formats are supported. Nifti support is in the works but not enabled yet.
  • Import/Export ROI file will load or save ROI information in an internal Dafne format (with extension .p). A ROI file can only be used with the same dataset used for its creation or with an identical dataset (in terms of size and orientation). This is in contrast to the mask import (see below) Note that Dafne will periodically save files in this format in the data directory. Make sure to clean the directory periodically, as they can grow large.
  • Import masks will import binary masks from dicom or numpy files. If the imported masks are DICOM, the software will attempt to align the dataset with the currently loaded one, so it is a way to transfer ROIs across different acquisitions. It might take some time especially if the currently loaded dataset is a 2D multislice dataset. When loading multiple masks saved as DICOM, you can choose the Import multiple masks functionality. You can then select the folder containing all the ROI subfolders and they will be loaded at the same time. This is much more efficient than loading a single ROI one by one.
  • Save masks will export the ROIs to disk, in numpy or DICOM format. In case of DICOM format, the same dicom headers of the loaded dataset will be used, and new folders with ROI names will be created. Note: this is a very important operation, because the model learns every time masks are exported. Without exporting masks, no model improvement is performed. This is also the reason why this operation takes some time (depending on the performance of your computer).
  • Upload data will send the current loaded data with the ROI information to our servers. !!Use with extreme care!! You don’t need to send your data to us, but you might wish to do so to help us improve the program. Make sure that you have the right to do so! We take no responsibility for any breach of local regulations that you might incur.

The Tools menu

In the tools menu, statistics calculation and the preference editor are located.

Tools Menu

  • Improve model will perform an automatic model improvement step using the already-segmented data, so that subsequent segmentations are more accurate. A minimum of 5 slices are required for this step to work.

  • Calculate statistics will produce a csv (tabular) data file with some statistics regarding the drawn ROIs. What is saved is:

    • The ROI name
    • The number of slices in which the ROI is defined
    • The total number of voxels in the ROI
    • The average value of the image in the ROI
    • The standard deviation
    • The 0th percentile (minimum value)
    • The 25th percentile
    • The 50th percentile (median)
    • The 75th percentile
    • The 100th percentile (maximum)

Stats

  • PyRadiomics will produce a csv file with texture analysis features from the Pyradiomics package (if available).

  • Open transform calculator will open a tool that allows an offline calculation of the nonrigid transforms between slices, in order to speed up subsequent propagation operations. A screenshot of the tool is shown below. Select a folder with DICOM files and click on “Calculate transforms” to start the calculation. The transforms will be stored at the end in an internal Dafne format, in the same folder as the dicom files. For performance reasons, we suggest you to start this tool directly as a separate executable (calc_transforms.py in the source installation, or calc_transforms.exe in the windows compiled installation)

Offline transform calculator

  • Preferences will open the preference editor.
  • Restore factory settings will restore the default Dafne preferences.

The ROI menu

This menu allows some operations on ROIs.

ROI menu

  • Copy/Rename will make a copy of a ROI, or change its name. A copy is performed unless the Make copy checkbox is unchecked.

Copy/Rename

  • Combine will perform boolean operations over two ROIs. The output ROI will be replaced with the result of the operation. If you wish to create a new ROI, select Specify a different name in the Output ROI field and write the name in the text box. The available operations are:
    • Union: The two ROIs are combined (OR)
    • Subtraction: The second ROI is subtracted from the first (AND NOT)
    • Intersection: The common area between two ROIs is retained (AND)
    • Exclusion: The non-overlapping portions of the two ROIs are retained (XOR)

Combine

  • Multiple combine allows boolean operations on multiple ROIs at the same time.

  • Remove overlap will remove the overlap between the current ROI and the others by deleting the overlapping areas of the other ROIs. It is useful when correcting misassignment of areas of the image to the wrong ROI.

Keyboard shortcuts

Some keyboard shortcuts are available for convenience.

Command Key(s)
Previous Image [Left Arrow], [Up Arrow]
Next Image [Right Arrow], [Down Arrow]
Paint/Add/Move [Shift]
Erase/Delete [Ctrl], [Cmd]
Propagate Forward n
Propagate Back b
Reduce Brush Size -, y, z
Increase Brush Size +, x
Remove ROI Overlap r