lungmask: trained lung segmentation for chest CT

A trained model set rather than a method to implement

lungmask provides trained U-net models for lung segmentation, and the README makes the point about why that matters in its subtitle: it is for automated lung segmentation in CT under the presence of severe pathologies.

That qualifier is the whole research contribution. A lung segmentation model that only works on healthy lungs is easy to train. One that still finds the lung when there is a large effusion, a tumour or severe fibrosis is not, and the paper the project asks you to cite explains why.

The citation is Hofmanninger and colleagues, Automatic lung segmentation in routine imaging is primarily a data diversity problem, not a methodology problem, published in European Radiology Experimental. The README describes that paper as containing a detailed description of the dataset used, a thorough evaluation of the R231 model and a comparison to reference methods.

The framing in the title is worth pausing on, because it says the hard part was the training data rather than the architecture. The main model was trained on a large and diverse dataset covering a wide range of visual variability, and the practical consequence for a user is that the model behaves like it was trained on real routine imaging rather than on curated examples.

So the package is a set of published weights with a small inference API around them. You are not implementing segmentation, you are applying a model that has already been evaluated in a journal.

The four models

Four models are available, and they differ in what they segment and what they cost.

The U-net with the R231 label is the default. It performs segmentation on individual slices, extracts the right and the left lung separately, and includes air pockets, tumours and effusions. The trachea is not included in the lung segmentation, which matters if you are computing lung volume and want to know what was excluded.

The U-net with LTRCLobes label was trained on a subset of the LTRC dataset from the National Heart, Lung and Blood Institute. It segments the individual lung lobes, but the README is honest about its limits, saying that it yields limited performance when dense pathologies are present or when fissures are not visible at every slice.

The fused model runs R231 and LTRCLobes and combines them. False negatives from LTRCLobes are filled by R231 predictions and mapped to a neighbouring label, and false positives from LTRCLobes are removed. The price is stated plainly: the fusing process is computationally intensive and can, depending on the data and the results, take up to several minutes per volume.

The fourth is R231CovidWeb, trained with additional COVID-19 data, which the README covers in its own section because of how it has to be used.

So the choice is between two labels and five labels, between speed and accuracy, and between the standard model and the COVID-19 variant.

What the labels mean

The output semantics are stated precisely, which matters more here than in most image processing tools because a label is a number in a file.

The two label models, the left and right ones, use label 1 for the right lung and label 2 for the left lung.

The five label models, the lobe ones, use label 1 for the left upper lobe, label 2 for the left lower lobe, label 3 for the right upper lobe, label 4 for the right middle lobe and label 5 for the right lower lobe.

Note what that means in practice. A left and right segmentation has two values, so it cannot tell you anything about lobes. A lobe segmentation has five values, so it cannot tell you left from right without consulting the label table, and its quality depends on fissures being visible, which the README identifies as one of the failure modes.

Both are integer label maps, and the tool writes them in ITK formats, which is the format SimpleITK reads and writes natively and the format most medical imaging pipelines already use.

Installing it and what it costs to run

There are three installation routes.

pip install lungmask

pip install git+https://github.com/JoHof/lungmask

conda install conda-forge::lungmask

On Windows, the README says that depending on your setup it may be necessary to install torch beforehand.

The runtime difference is the number to plan around. Using the GPU, processing a volume takes only several seconds, while CPU-only inference takes several minutes. To use the GPU you need a torch installation with CUDA support, and in case of CUDA out-of-memory errors you reduce the batch size to one with the optional batchsize argument.

That last point is worth reading as a workflow instruction rather than a footnote. On a large CT volume with a large field of view, the model can run out of memory on a card that is otherwise adequate, and the fix is a single flag. It is a reminder that the segment is the right size for the series, not a fixed size.

The dependencies are the usual medical imaging stack: pydicom for reading DICOM, numpy, torch, scipy, SimpleITK for the image format, tqdm, scikit-image, and two smaller ones for filling voids and for iteration helpers. The package requires Python 3.11 or later.

Using it from the shell and from Python

The command line takes an input and an output.

lungmask INPUT OUTPUT

If the input points to a file, the file is processed. If it points to a directory, the directory is searched for DICOM series, and the largest volume found in terms of number of voxels is used to compute the mask. The output is the output filename, and all ITK formats are supported.

That directory behaviour is a practical detail. A study folder often holds a reconstructed series and the source slices, and picking the largest volume by voxel count is a reasonable heuristic for finding the reconstruction, but it is a heuristic rather than an explicit choice.

The model is chosen with a flag, and the default is R231.

lungmask INPUT OUTPUT --modelname LTRCLobes

From Python, the entry point is an inferer object.

from lungmask import LMInferer
import SimpleITK as sitk

inferer = LMInferer()

input_image = sitk.ReadImage(INPUT)
segmentation = inferer.apply(input_image)  # default model is U-net(R231)

The input has to be a SimpleITK object, an alternative model is loaded with a modelname argument, and the fusing capability is reached by passing a fill model.

inferer = LMInferer(modelname='LTRCLobes', fillmodel='R231')

Since version 0.2.9, numpy arrays are accepted as input volumes as well, with an assumed axis order of slices first, then chest to back, then right to left. That is a detail to get wrong silently, so it is good that it is stated.

Limitations, and the images that are not CT

The README has a limitations section and a section about images that are not encoded in Hounsfield units, and both are worth reading before you trust an output.

The limitation is about geometry. The model works on full slices only. The slice to process has to show the full lung, and the lung has to be surrounded by tissue in order to be segmented. The model is described as quite stable to cases with a cropped field of view, as long as the lung is surrounded by tissue.

That is the fundamental trade of a slice-based model applied to a volume: it cannot recover what is not in the slice, and it needs a boundary to segment against.

The COVID-19 web model exists because the regular R231 model works very well for COVID-19 CT scans, but collections of slices and case reports from the web are often cropped, annotated or encoded in regular image formats, so the original Hounsfield unit values can only be estimated. The training data of R231CovidWeb was augmented with COVID-19 slices mapped back from regular imaging formats to Hounsfield units, with the data collected and prepared by MedSeg. The README says there may be cases where this model yields slightly improved segmentations, and that you have to map images back to Hounsfield units when using images from the web, or use the noHU tag.

And the section on JPG, PNG and non-Hounsfield images is marked as available only in versions between 0.2.5 and 0.2.14. It warns that the models were trained on proper CT scans encoded in Hounsfield units, so results on cropped, annotated and heavily intensity shifted images may not be reliable, and that with the noHU tag only single slices can be processed.

Editorial conclusion

lungmask suits a medical imaging researcher who needs lung masks on real clinical CT, where the labelled model includes air pockets, tumours and effusions rather than stopping at healthy tissue, and who would rather start from published weights than train their own segmentation network. It is the wrong choice if you need a definitive diagnostic output, since the README is explicit that the model works on full slices only and needs the lung surrounded by tissue, and the wrong choice for images that are not in Hounsfield units unless you accept the documented caveat. Verify first that your volumes are in Hounsfield units and are full slices, decide whether you need lobe labels or left and right separation, and check which release you install, because the non Hounsfield image support is documented as available only in a bounded range of versions.

Frequently asked questions

Official sources

1. Issues
2. JoHof/lungmask on GitHub
3. License: Apache-2.0
4. README
5. Releases