niklr / animated-medical-imaging

Streamlines the process of generating an optimal subset representing a multi-dimensional medical image and combining the subset to an animated sequence.

Animated Medical Imaging (AMI) is a container-based solution to streamline the process of generating an optimal subset representing a multi-dimensional medical image and combining the subset to an animated sequence. Despite the focus being on containers tailored for a microservice infrastructure, it is also possible to process medical images directly in the command line.

The container-based solution consists of two services called AMI.API and AMI.Website:

• AMI.API
  • A REST-based application programming interface (API)
  • For a live demonstration please visit
    • https://ami-api.smir.ch
  • Can be deployed as Linux-based Docker container
    • https://hub.docker.com/r/niklr/ami-api
• AMI.Website
  • A web-based user interface to interact with the API
  • For a live demonstration please visit
    • https://ami.smir.ch
  • Can be deployed as Linux-based Docker container
    • https://hub.docker.com/r/niklr/ami-website

The command-line solution distinguishes between AMI.CLI and AMI.Portable:

• AMI.CLI
  • A cross-platform command line interface (CLI)
  • Status is still experimental. Breaking changes are to be expected in this project.
• AMI.Portable
  • A portable executable for 32b & 64b Windows
  • Compiled releases can be found and downloaded here:
    • https://github.com/niklr/animated-medical-imaging/releases

Supported file formats:

• Analyze (.hdr, .img)
• MetaImage (.mha, .mhd, .raw)
• Single-frame and multi-frame DICOM (.dcm)
• Nifti (.nii)

Table of Content:

• Installation
• Usage
• Configuration
• Output
• Debug
• Build

Examples

The first example [1] is part of the BRATS 2015: Brain Tumor Image Segmentation Challenge dataset hosted on the SMIR platform [3]. It has been generated with the following command:

AMI.Portable.exe --SourcePath SMIR.Brain.XX.O.MR_Flair.36620.mha --DestinationPath temp

The second example [2] is part of the ISLES 2018: Ischemic Stroke Lesion Segmentation Challenge dataset hosted on the SMIR platform [3]. It has been generated with the following command:

AMI.Portable.exe --SourcePath SMIR.Brain.XX.O.CT.346124.nii --DestinationPath temp

[1] SMIR.Brain.XX.O.MR_Flair.36620.mha: BRATS 2015 - Training - HGG - tcia_pat499_0001

[2] SMIR.Brain.XX.O.CT.346124.nii: ISLES 2018 - Training - Train_52_A

[3] SICAS Medical Image Repository

The third example shows how to interact with the graphical user interface AMI.Website to achieve a similar result as above. First, the settings can be defined which will be used to process the image uploaded in the second step. Finally, the extracted result can be directly viewed in the web browser.

Installation

Easiest is to obtain the latest AMI.Portable executable from GitHub. This compressed archive contains the exectuable, required third-party binaries and configuration files.

Other dependencies:

• Microsoft .NET Framework 4.6.1

Usage

AMI.Portable.exe --help

• --OutputSize The size of the output images in pixels. (Default is 250)
• --AmountPerAxis The amount of images to be extracted per axis. (Default is 10)
• --SourcePath The path of the source image.
• --DestinationPath The path of the destination where the output should be written.
• --Grayscale Whether the images should be converted to grayscale. (Default is 1)
• --OpenCombinedGif Whether the combined gif should be opened after creation. (Default is 0)
• --help Display this help screen.
• --version Display version information.

Configuration

logging.json

{
  "Logging": {
    "LogLevel": {
      "Default": "Debug",
      "System": "Information",
      "Microsoft": "Information"
    },
    "Console": {
      "IncludeScopes": "true"
    }
  }
}

The Logging property can have LogLevel and log provider properties (Console is shown).

The LogLevel property under Logging specifies the minimum level to log for selected categories. In the example, System and Microsoft categories log at Information level, and all others log at Debug level.

Other properties under Logging specify logging providers. The example is for the Console provider. If a provider supports log scopes, IncludeScopes indicates whether they're enabled. A provider property (such as Console in the example) may also specify a LogLevel property. LogLevel under a provider specifies levels to log for that provider.

Unit tests

Change the default processor architecture in Visual Studio under Test > Test Settings > Default Processor Architecture > x64 to prevent NUnit error messages such as:

NUnit failed to load ...\AMI.NetFramework.Tests\bin\Debug\AMI.NetFramework.Tests.dll

Output

Each successful execution will generate an output.json file in addition to an optimal subset representing a multi-dimensional medical image. This json file consists of models described below.

ProcessResultModel

• labelCount (number) The amount of labels in the image.
• size (array of numbers) The amount of pixels the image has in each dimension (X, Y, Z).
• images (array of PositionAxisContainerModel) A list of extracted images.
• gifs (array of AxisContainerModel) A list of created GIFs.
• combinedGif (string) The filename of the combined GIF (contains all requested axis types).
• version (string) The version number of the application.
• jsonFilename (string) The name of the JSON file.

PositionAxisContainerModel

• position (number) The position of the extracted image on the respective axis.
• axisType (string / enum) The respective axis of the coordinate system.
• entity (string) The filename of the extracted image.

AxisContainerModel

• axisType (string / enum) The respective axis of the coordinate system.
• entity (string) The filename of the extracted image.

AxisType (enum)

• X The x-axis of the coordinate system.
• Y The y-axis of the coordinate system.
• Z The z-axis of the coordinate system.

Debug

In order to debug the application, you will need the following tools:

• Visual Studio 2017
• Microsoft .NET Framework 4.6.1
• .NET Core SDK 2.1

The optional SwitchStartupProject extension for Visual Studio can be used to quickly select startup projects from a dropdown. Additionally, this extension enables to switch between multi-project startup configurations e.g. to start AMI.API and AMI.Website together.

Last but not least, the special dependency SimpleITK needs to be installed:

1. Download & extract 32bit or 64bit version.
2. Copy the following DLLs to the lib folder.
   • SimpleITKCSharpManaged.dll
   • SimpleITKCSharpNative.dll

Caution: The build process described below will overwrite those DLLs depending on the specified platform.

Build

The build process makes use of cake (C# make) a cross-platform build automation system with a C# DSL for tasks such as compiling code, copying files and folders, running unit tests, compressing files and building NuGet packages.

Open up a Powershell prompt and execute the bootstrapper script for the respective platform:

x64 (win64)

PS> .\build.ps1 -ScriptArgs '-platformArg="x64"'

Builds the solution into:

• src\AMI.Portable\bin\x64\Release

x86 (win32)

PS> .\build.ps1 -ScriptArgs '-platformArg="x86"'

Builds the solution into:

• src\AMI.Portable\bin\x86\Release