Segment kidneys from MRI data
Project description
Renal Segmentor
An application and Python package to segment kidneys from renal MRI data using a convolutional neural network (CNN).
Using the segmentor
The easiest way to make use of the segmentor is to download the windows executable, this allows you to mask data with a stand-alone application. The executable can either be run as a GUI or a command line application allowing it to be integrated into bash scripts.
Alternatively, the methods used by the segmentor are available as a Python package and can be integrated into existing Python pipelines. Instructions for making use of the segmentor via each method are given below.
As a Graphical User Interface (GUI)
- Download the latest release
- Double click
renal_segmentor.exe
. The GUI takes quite a long time to load (~30 sec) and doesn't have a splash screen so be patient. - Once the GUI has loaded, click
Browse
and select all the raw data you want to segment. You can select multiple files at once. Supported file types are.PAR/.REC
,.nii
,.nii.gz
and.img/.hdr
, other file types supported by nibable may work but are untested. - If you want the mask to be just 0s and 1s tick the
binary
check box, if you want the CNNs probability that the voxel is a kidney, leave it unchecked. - Post-processing can be applied, this discards all but the two largest connected regions in the mask in theory retaining only the two kidneys and removing any erroneous unconnected regions. It should be noted that because post-processing keeps only two regions, care should be taken if using this application with transplant patients as they may have three kidneys.
- Tick the
raw
checkbox if you want the raw image data to be saved as a.nii.gz
file in the same location as the mask (can be useful if you're using.PAR/REC
as your input). - If you would like a
.csv
file containing the Total Kidney Volume (TKV), Left Kidney Volume (LKV) and Right Kidney Volume (RKV) for each image that was segmented tick theExport Kidney Volumes
box. - The masks are output from the segmentor as
.nii.gz
with_mask
added to the original file name e.g. the mask ofsub_01.PAR
issub_01_mask.nii.gz
. By default, the mask is output to the same place as the raw data, if you would like the masks to be output to a different directory clickBrowse
underOutput Directory
and select the folder you wish the masks to go to. - Click start.
- The application will run and a few seconds later a box will appear saying the program completed successfully. The first time you run a segmentation will take a little longer as the latest algorithm weights are downloaded from the internet at this point.
- If you want to segment some more data click the
edit
button on the bottom of the finished screen, if you're done, clickclose
.
Via a Command Line Interface (CLI)
- Download the latest release
- Run the
renal_segmentor.exe -h
to generate a list of available parameters. The application runs via a command line if any input arguments are specified, if not, it opens as a GUI.
As a Python package
- Activate the python environment you want to install the package on and run
pip install renalsegmentor
. If you want to install the additional dependencies required for the GUI, runpip install renalsegmentor[gui]
however to use the segmentor as a python package, these are not required. - The example code snippet below will generate a mask of
T2w.nii.gz
as a numpy array and print the TKV to the terminal.
from segment import Tkv
segmentation = Tkv('T2w.nii.gz')
mask = segmentation.get_mask()
print(f'Total Kidney Volume = {segmentation.tkv:.2f} ml')
Citing Renal Segmentor
If you have made use of renal segmentor for your work, please cite Daniel AJ, et al. Automated renal segmentation in healthy and chronic kidney disease subjects using a convolutional neural network. Magnetic Resonance in Medicine 2021;86:1125–1136 doi: https://doi.org/10.1002/mrm.28768. Alternatively if you wish to cite a specific software version, each release has an individual DOI on Zenodo, the DOI for the latest release can be found here.
How it works
The methods used in this software are outlined in Daniel AJ, et al. Automated renal segmentation in healthy and chronic kidney disease subjects using a convolutional neural network. Magnetic Resonance in Medicine 2021;86:1125–1136 doi: https://doi.org/10.1002/mrm.28768.
The dataset used to train this network is freely available on Zenodo, doi: https://doi.org/10.5281/zenodo.5153567.
Contributing
Feel free to open a pull request if you have a feature you want to develop or drop me an email to discuss things further.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for renalsegmentor-1.3.9-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 68ebecccc6fdb7409d83c39b1dba2cc44373adbffcc54e586aee48441d1c9779 |
|
MD5 | c324fdbfca7bd803f10d8fcca2f83941 |
|
BLAKE2b-256 | fc9add8ca2e38cc549de1a56c55006836a40aaaa13712b789e5b1a600a144546 |