Start Using MONAI Label with Sample Apps:
Tutorial 1 - Radiology¶
This example covers the annotation use-case for radiology using the sample MONAILabel App - radiology. MONAI Label server currently supports the annotation of local datasets via 3D Slicer, such as unlabeled images residing on disk, and remote data residing on DICOMweb-enabled PACS systems via both 3D Slicer and OHIF.
DeepEdit Annotation with 3D Slicer¶
Deploy MONAI Label Server¶
On the local machine follow the commands listed below to install MONAI Label, download a sample application (Radiology), download a sample dataset (MSD heart MRI), and deploy the sample app and standard dataset on the MONAI Label server.
# install MONAI Label pip install monailabel # download Radiology sample app to local directory monailabel apps --name radiology --download --output . # download Task 2 MSD dataset monailabel datasets --download --name Task09_Spleen --output . # start the Radiology app in MONAI label server # and start annotating the downloaded images using deepedit model monailabel start_server --app radiology --studies Task09_Spleen/imagesTr --conf models deepedit
Install MONAI Label Plugin in 3D Slicer¶
Install 3D Slicer Preview Version with in-built MONAI Label plugin
Download and Install 3D Slicer Viewer version 5.0 or later.
Start 3D Slicer
On the menu bar navigate View -> Extension Manager -> Active Learning -> MONAI Label
Install MONAI Label plugin (click “Install”)
Restart 3D Slicer (click “Restart” in the same dialog box)
To add the MONAI Label icon shortcut on the 3D Slicer toolbar
Navigate Edit -> Application Settings
Under the Modules panel drag MONAI Label into Favorite Modules
Restart 3D Slicer
Look for the MONAI Label module icon in the 3D Slicer toolbar
DeepEdit Annotation in 3D Slicer¶
To connect 3D Slicer to MONAI Label Server
Click on the MONAI Label module icon
Click the refresh icon near next to the MONAI Label server input field
If the MONAI Label server is running locally to 3D Slicer you do not need to enter the server address
To annotate the downloaded heart MR images using DeepEdit
Click Next Sample under Strategy to retrieve an image from the heart dataset along with a segmentation result generated by DeepEdit
We can now start making adjustments to the initial segmentation provided by adding foreground and background points using the tools in the SmartEdit section
For example, click on the foreground button and start clicking on the image panel to start seeing how foreground points affect the segmentation
Once we are satisfied with the segmentation we can Submit Label
We repeat the last four steps until our dataset is annotated
Annotating a Custom Dataset¶
To annotate a custom dataset using DeepEdit, we can download the DeepEdit app as above,
however, the dataset directory need not be populated. Follow the commands below to setup
custom dataset annotation using the empty local directory
my_dataset as the image and
label storage location.
# install MONAI Label pip install monailabel # download DeepEdit sample app to local directory monailabel apps --name radiology --download --output . # create an empty folder for the custom dataset mkdir my_dataset # start the DeepEdit app in MONAI label server # on the empty dataset folder monailabel start_server --app radiology --studies my_dataset --conf models deepedit
We can follow the instructions in the previous section to install and connect 3D Slicer to MONAI Label Server, however, in this scenario we will instead load a file into MONAI Label Server through 3D Slicer.
Load an image file by navigating the menu bar File -> Add Data
Click the referesh button under MONAI Label Server to connect to the server
Click the Upload Volume button to upload the new image onto the server
Now, all DeepEdit functions should be available to use and we use foreground and background clicks
DeepEdit Annotation Using OHIF¶
As of version
0.2.0, MONAI Label server supports connectivity to a remote DICOM server via DICOMweb. All we need
when starting MONAI Label server is to specify the URL of the DICOMweb service in the
studies argument (and optionally
password for DICOM servers that require them).
Setup Development DICOM Server¶
Orthanc is an open-source lightweight DICOM server for medical imaging. To setup an instance of Orthanc on your machine of choice follow the guides below.
# Install orthanc and dicomweb plugin sudo apt-get install orthanc orthanc-dicomweb -y # stop the existing Orthanc instance if there is one sudo service orthanc stop # setup and upgrade Orthanc libraries sudo wget https://lsb.orthanc-server.com/orthanc/1.9.7/Orthanc --output-document /usr/sbin/Orthanc sudo rm -f /usr/share/orthanc/plugins/*.so sudo wget https://lsb.orthanc-server.com/orthanc/1.9.7/libServeFolders.so --output-document /usr/share/orthanc/plugins/libServeFolders.so sudo wget https://lsb.orthanc-server.com/orthanc/1.9.7/libModalityWorklists.so --output-document /usr/share/orthanc/plugins/libModalityWorklists.so sudo wget https://lsb.orthanc-server.com/plugin-dicom-web/1.6/libOrthancDicomWeb.so --output-document /usr/share/orthanc/plugins/libOrthancDicomWeb.so # start sudo service orthanc restart
Download and Install Orthanc from https://www.orthanc-server.com/download.php.
The Orthanc DICOM server on the chosen machine. You can check if the server is running
by navigating to http://127.0.0.1:8042 or using the remote machine’s address and entering
The DICOMweb service for Orthanc runs on http://127.0.0.1:8042/dicom-web by default. You can check if the DICOMweb endpoint is active by issuing the following command
curl -X GET -v http://127.0.0.1:8042/dicom-web
You may encounter a
401 Unauthorized response when username and password are required.
When trying to access Orthanc remotely, please make sure you update the default configuration to allow for remote connections, by opening
/etc/orthanc/orthanc.json and setting
Adding Data to Development DICOM Server¶
If you do not have access to DICOM data to upload to the DICOM server you can convert from the NIFTI available via MONAI Label.
# install MONAI Label (if you have not already) pip install monailabel # Install `plastimatch` NIFTI to DICOM converter sudo apt-get install plastimatch -y # download Task 2 MSD dataset monailabel datasets --download --name Task09_Spleen --output . # convert one of the NIFTI images to DICOM plastimatch convert --patient-id patient1 --input Task09_Spleen/imagesTs/spleen_10.nii.gz --output-dicom dicom_output
Now, we can upload the DICOM series in
dicom_output using the upload link in Orthanc.
You may use
plastimatch to convert more NIFTI files to DICOM to keep populating the development DICOM server.
DeepEdit Annotation in OHIF¶
We follow a very similar set of commands as in Deploy MONAI Label Server, however, we use the DICOMweb
endpoint of our DICOM server, which based on the last section is
# install MONAI Label (if you have not already) pip install monailabel # download DeepEdit sample app to local directory monailabel apps --name radiology --download --output . # start the DeepEdit app in MONAI label server # and start annotating images in our DICOM server monailabel start_server --app radiology --studies http://locahost:8042/dicom-web --conf models deepedit --username orthanc --password orthanc
At this point OHIF can be used to annotate the data in the DICOM server via the MONAI Label server
(e.g. via http://127.0.0.1:8000/ohif).
Here, user may also perform annotation using 3D Slicer by following the same instructions as in section DeepEdit Annotation in 3D Slicer.
Tutorial 2 - Bundle App Tutorial and Use Cases¶
Customized Networks for MONAI Label¶
This tutorial introduces the usage of the Bundle app in MONAILabel - monai bundle.
The Bundle App empowers MONAILabel with customized models, pre- and post-processing, and any anatomies for labeling tasks. The Bundle App supports various bundle based training / inference pipelines within the Model Zoo Release.
Learn more about MONAI Bundle.
Highlights and Features:
Supporting customized models and networks such as SwinUNETR, AutoML, etc.
Advancing heterogeneous dataset (e.g., CT, MRI, Pathology, etc) with corresponding pre- and post-processing modules.
Ready-to-Use inference of hundreds of anatomies (e.g., multi-organ abdominal segmentation, whole-brain segmentation) with trained model checkpoints.
Deploying robust interactive labeling tools such as DeepEdit.
Model Zoo for MONAI Label¶
MONAI Model Zoo hosts a collection of medical imaging models in the MONAI Bundle format. All source code of models (bundles) are tracked in models/, and for each distinct version of a bundle, it will be archived as a .zip file (named in the form of bundle_name_version.zip) and stored in Releases.
The MONAI Bundle defines the model package and supports building python-based workflows via structured configurations
Self-contained model package with all the necessary information.
Structured config that easy to override or reconstruct the workflow.
Config provides good readability and usability by separating parameter settings from the python code.
Config describes flexible workflow and components, allows for different low-level python implementations.
Currently available bundles: Model-Zoo.
1. Install MONAI Label and 3D Slicer¶
For detailed setups of MONAILabel and 3D Slicer, refer to the installation steps guide if MONAILabel is not installed yet.
2. Add MONAI Label Plugin in 3D Slicer¶
Add 3D Slicer with in-built MONAI Label plugin if not setup yet. Refer to Step 3 in installation guide.
Use Case 1: Bundle for SwinUNETR Multi-Organ Segmentation¶
On the local machine follow the commands listed below to install MONAI Label, and deploy the bundle app and standard dataset on the MONAI Label server.
Step 1: Install and start MONAI Label server with the Bundle app.
# install MONAI Label pip install monailabel # download Bundle sample app to local directory monailabel apps --name monaibundle --download --output . # download a local study images, sample dataset such as spleen: monailabel datasets --download --name Task09_Spleen --output . # start the bundle app in MONAI label server # and start annotating the images using bundle with the Swin UNETR bundle monailabel start_server --app monaibundle --studies Task09_Spleen/imagesTr --conf models swin_unetr_btcv_segmentation_v0.1.0
Step 2: Start 3D Slicer.
Step 3: Start the SwinUNETR bundle and follow clicks.
On the menu bar navigate click MONAI Label
Check the Model Zoo loading, MONAI Bundle app, and load study image
Select bundle models and obtain automatic labels
Now get the automatic inference of the trained SwinUNETR model!
Submit refined labels and train to fine-tune the model
Use Case 2: Bundle with Customized Scripts for Renal Substructure Segmentation¶
This use case provides an instruction on using bundle model with customized scripts.
Prerequisite: Check Model Zoo Release.
# install MONAI Label pip install monailabel # download Bundle sample app to local directory monailabel apps --name monaibundle --download --output . # download a local study images, sample dataset such as spleen: monailabel datasets --download --name Task09_Spleen --output . # download the bundle move the downloaded ZIP file to the MONAILable/sample-apps/monaibundle/model and unzip # and save to the monaibundle/model and direct to the customized bundle folder cd <path to the bundle model>/renalStructures_UNEST_segmentation_v0.1.0 # add customized scripts in the downloaded bundle export PYTHONPATH=$PYTHONPATH:"'/monaibundle/model/renalStructures_UNEST_segmentation_v0.1.0/scripts" # start the bundle app in MONAI label server monailabel start_server --app <full path to the monaibundle app/monaibundle> --studies <path to the local dataset/Task09_Spleen/imagesTr> --conf models renalStructures_UNEST_segmentation_v0.1.0
Start 3D Slicer and follow same MONAI Label plugin process MONAI Label
Select the customized bundle and inference with pre-trained model for renal structure segmentation
Get inferred label with renal cortex, medulla, and collecting system.