Karawun

Introduction

Karawun converts the results of a diffusion MRI tractography study, as might be used for surgical planning, to a form that is readable by the Brainlab software suite.

The planning results will consist of a set of co-registered nifti images (for example T1, FA, contrast enhanced T1 etc) and associated tract files created using the mrtrix3 tools. Karawun converts the nifti images to dicom images and the tck files to the dicom object format used by Brainlab to represent tracts produced by the internal tracking tool.

Tracts generated by mrtrix3 can thus be used in Brainlab in the same way as tracts generated by Brainlab. This allows you to experiment with your favourite diffusion sequence or post processing method and visualize the results in the planning suite.

Mask or label images can also be converted to a dicom segmentation format compatible with Brainlab. There are currently 30 predfined colours that are selected based on the mask value. Multiple label values are allowed per image. Mask/label images must have a matching "raw" image in the nifti set. For example, if you wish to include a tumour mask drawn over a contrast enhanced scan, then the raw scan must also be converted. Note that images with many labels can be take a while to be interpreted by Brainlab.

Karawun is a grass used as a source of fibre by Aboriginal tribes in south-eastern Australia.

Quick Installation

Karawun is a python package that can be installed using various standard python options. It is recommended that some form of virtual environment is used to isolate karawun and its dependencies from other packages. Installation with miniconda is illustrated below:

Pip

pip install karawun

Conda

conda config --append channels conda-forge --append channels anaconda --append channels SimpleITK
conda create --name KarawunEnv python=3.8 karawun

Installation from source

Miniconda

Install miniconda for python 3.7

Subsequent commands need to be entered in a commandline shell - either the anaconda shell under windows or the terminal under Linux or Mac.

Add package channels:

conda config --append channels conda-forge --append channels anaconda --append channels SimpleITK

For Windows:
```
conda install git
```

Create a conda environment (using a name of your own choice) and install the dependencies:

conda create --name KarawunEnv --file https://github.com/DevelopmentalImagingMCRI/karawun/raw/master/requirements.txt

Activate the environment:
```
conda activate KarawunEnv
```

Install karawun (internet access required)

pip install git+https://github.com/DevelopmentalImagingMCRI/karawun.git@master

Test the installation by running the main script:
```
importTractography -h
```
This will produce the help information if the installation was successful.

Subsequent uses of karawun only require the conda activate KarawunEnv step.

See below for recommended testing procedure.

Using

The simplest way of using karawun is via the importTractograpy command, as follows:

importTractography --dicom-template path/to/a/dicom --nifti T1.nii.gz fa.nii.gz --tract-files left_cst.tck right_cst.tck -o path/to/output/folder

or, with label images

importTractography --dicom-template path/to/a/dicom --nifti T1.nii.gz fa.nii.gz --tract-files left_cst.tck right_cst.tck --label-files lesion.nii.gz white_matter.nii.gz  -o path/to/output/folder

Explanation

The dicom template is a dicom file from which dicom tags are copied, including all patient information. Ideally this dicom file should be one of the originals from which the nifti files were derived. All patient, physician and institutional details are copied from this template. A single dicom template file is required. A single, anonymised, dicom is provided with the testing data (see below), that may be appropriate for other testing purposes, if you do not have original dicoms available.

The nifti files are the volume images that will be converted to dicom images. They are assumed to be co-registered, as would typically be the case for multiple nifti files used in a common image processing pipeline. The conversion process creates a dicom "frame of reference" to which all volume images belong. Brainlab requires that the user accept this registration.

The tract files are the mrtrix .tck files that need to be displayed in Brainlab. The conversion of these files creates the dicom fibre object format that can be viewed as a 3D object in Brainlab.

The converted dicoms are placed in the output folder. Separate subfolders are created for each nifti file and each tck file.

The input file names are used in various dicom description tags.

The frame of reference is based on the first nifti file in the argument list. Thus the Brainlab "quick viewer" will only allow tracts to be overlaid on that image. Accepting the registration will allow all display combinations.

Typical workflow

A typical workflow involves extracting dicom images from the scanner system, converting them to nifti formats and peforming image processing steps using a range of approaches. Examples include co-registration, tissue classification, brain extraction, activation detection, distortion correction, etc with tools like FSL, FreeSurfer and SPM as well as diffusion tractography using mrtrix. The resulting dataset is then converted to dicom ready for import.

We do not attempt to make the new dicoms align with the original dicoms from which the nifti were derived. Always treat the images derived from the external workup as a new and independent set of data.

We anonymise dicoms before import to Brainlab (using gdcm ) to avoid any chance of overwriting other patient data. In theory, copying tags from an original dicom will make the converted dicoms appear to derive from the correct patient. Please test very thoroughly before relying on this facility.

Longer install, with testing (recommended)

Create and activate an environment, as above, then download the package sources OR fetch via git:
```
git clone https://github.com/DevelopmentalImagingMCRI/karawun.git
```

Install the dependencies

cd karawun
conda install --name KarawunEnv --file requirements.txt

Run the test:
```
python -m pytest -s tests/
```

This test uses some data distributed with the package. A successful result is indicated by 1 passed and 1 skipped test. Success means that the dicom files created on your system are identical to those created on the development system. The test destination is displayed as the test is run.

Problems/Requests

Please use the github issue tracker to ask questions or report problems.

Shoutouts indicating that you are using Karawun are also appreciated.

Licensing

Karawun is distributed under the Apache License 2.0

Developer Notes

Documentation is stored in the gh-pages-source branch. A github action (BuildGHPages in docpages_action.yaml) builds the html documentation using sphinx and force pushes the results to the gh-pages branch for github to display.

The master branch is protected, requiring CI tests to pass and a review or admin permission for merging. Testing is performed on pull request to master, release and dev branches and push to any branch.

The test matrix is covering python version 3.6, 3.7, 3.8 and 3.9 and ubuntu-latest, windows-latest and macos-latest.

PyPI publication

The master branch should be merged manually with release by an administrator, using the command line as follows:

git fetch --all
git checkout release
git merge --ff-only upstream/master
git push

A release can then be made via the github interface, including a new semantic tag of the form v0.2.5.2.

The release branch should be chosen as the target for the release, and a new tag created.

Publishing a release triggers the action (same as used for pull requests etc), but additional steps will be run to publish the package on pypi.org.

Contributors

Richard Beare, Joseph Yang, Chris Adamson, Andrew Perry.

DevelopmentalImagingMCRI / karawun