Package: airway
AirwayAnatomical classification of human lung bronchus up to segmental/tertiary bronchi
based on high-resolution computed tomography (HRCT) image masks.
A rule-based approach is taken for classification, where the most cost-effective tree is found according
to their angle deviations by defined vectors.Here, a pipeline is implemented which, given a formatted input data structure, can create the anatomical segmentations, clusters of similar anatomy, and
the visualisations presented below.An example can be seen below, the 18 segments of the lung are automatically annotated in
the 3D voxel model.Example visualisation of split detection, rendered with Blender.This project currently uses masks created using Synapse 3D by Fujifilm,
which already segments the lobes, bronchus, arteries and veins in CT images.
However, this is not required. To use this project you only need a detailed segmentation of the bronchi.QuickstartInstall withpip install airwayRun the interactive tutorial withairway tutorial(this will guide you through a fake sample)Modify your own data so that you could use it withairway(described in the data section below)DataWe use a pipeline based approach to calculate the raw data. With the help ofairway_cli.pyyou are able to calculate each step (called stages).To get the pipeline to work you need to define and format the first input stage, which is then
used to create all other stages.
You have multiple options which stage you use as input, depending on which is simpler
for your use case:raw_datais the structure as created by Synapse 3D and cannot be
directly used as input. We used the script inscripts/separate-bronchus-files.shto createraw_airway. The format of it is still described in theDATADIRgraphic below for reference.raw_airwayis the same data asraw_data, but the directory structure has been reformatted. This was our
input stage for the pipeline. See theDATADIRgraphic below for more details on the file structure.
TheIMG\dfiles contain single slices for the CT scan, where -10000 was used for empty, and the rest
were various values between -1000 to 1000. We assumed -10000 to be empty, and everything else to be
a voxel of that type, as we already had segmented data.stage-01(recommended)can be used as an input stage as well, this may be considerably easier to compute
if you have a wildly different data structure. Only a single file needs to be created:model.npz.
It is a compressed numpy file where a single ~800×512×512 array is saved for the entire lung
(order is important, (transverse×sagittal×frontalplanes)).
The ~800 is variable and depends on the patient, the 512×512 is the slice dimension.
The array is of typenp.int8and
the array in the.npzfile is not named (it should be accessible asarr_0).
An encoding is used for each voxel to represent the 8 different classes as shown in the table below.
If you do not have some classes then you may ignore them, onlybronchus(encoded as1) is required,
as otherwise nothing will really work in the rest of the project. Empty or air should be encoded as0.
Seeairway/image_processing/save_images_as_npz.pyfor reference if you decide to use this stage as input.Note that the slice thickness for our data was 0.5 mm in all directions.
Currently, the pipeline assumes this is always the case.
It will work fairly well for different, but equal, thicknesses in all directions (e.g. 0.25 mm × 0.25 mm × 0.25 mm),
although some results may wary.
Different thicknesses in multiple directions (e.g. 0.8 mm × 0.8 mm × 3 mm) will likely not work well at all. In that case
we recommend to duplicate certain axes manually, so that the thickness is similar in all directions.CategoryEncodingEmpty0Bronchus1LeftLowerLobe2LeftUpperLobe3RightLowerLobe4RightMiddleLobe5RightUpperLobe6Vein7Artery8The directory structure for the data structure is described below. Note that if you usestage-01as input you do not needraw_dataorraw_airwayat all.DATADIR
    ├── raw_data                    🠔 This is an example of entirely unformatted raw data as we received them
    │   └── Ct_Thorax_3123156       🠔 Each patient has its own directory 
    │       └── DATA
    │           ├── Data.txt        🠔 This contained the paths for finding the various bronchus and lobes
    │           └── 3123156         🠔 Example patient ID
    │               └── 20190308         
    │                   └── 124101         
    │                       └── EX1         
    │                           ├── SE1         🠔 Each SE* folder contains a list of DICOM images 
    │                           │   ├── IMG1       named IMG1 through IMG642 (may be a different amount)
    │                           │   ├── ...        these represent the slices for that segmentation.
    │                           │   └── IMG642     E.g. SE4 is Bronchus, SE5 is the Right upper lobe.
    │                           ├── SE2            This is described in Data.txt for each patient.
    │                           ├── ...            
    │                           └── SE10           
    │                           └── SE11           
    │               
    ├── raw_airway                  🠔 Formatted data which will be used as input for stage-01
    │   └── 3123156                 🠔 Single patient folder, in total there are around 100 of these
    │       ├── Artery
    │       │   ├── IMG1            🠔 DICOM images, in our case 512x512 slices
    │       │   ├── IMG2            🠔 with 0.5 mm thickness in all directions
    │       │   ├── ...
    │       │   ├── IMG641          🠔 There generally are between 400 and 800 of these slices
    │       │   └── IMG642          🠔 So the number of slices is variable
    │       ├── Bronchus
    │       │   ├── IMG1            🠔 Same number and dimension of slices as above
    │       │   ├── ...
    │       │   └── IMG642         
    │       ├── LeftLowerLobe       🠔 All of these also share the same structure
    │       ├── LeftUpperLobe
    │       ├── RightLowerLobe
    │       ├── RightMiddleLobe
    │       ├── RightUpperLobe
    │       └── Vein
    │               
    ├── stage-01                    🠔 Each stage now has the same basic format
    │   ├── 3123156
    │   │   └── model.npz           🠔 See above for an explanation
    │   ├── 3123193
    │   │   └── model.npz
    │   └── ...
    ├── stage-02                    🠔 Each stage from here on will be created by the pipeline itself
    │   ├── 3123156                    so you do not need to handle this, each of them have different
    │   └── ...                        files depending on their use.
    ...Note that currently NIFTI images are not supported, allIMG\dfiles are DICOM images.InstallationAt least Python 3.6 is required for this project.pip3 install airwayThe open source 3D visualisation softwareBlenderis required for visualisation. This dependency is optional if you do not need the visualisation part. Install from the website above or via a package manager like this (pip does not have blender):apt install blenderTested with Blender versions 2.76, 2.79, 2.82 (recommended) and 2.92.Now configure the defaults, copy and renameconfigs/example_defaults.yamltoconfigs/defaults.yaml(in the root folder of the project) and change the path in the file to where you have put the data.
You may ignore the other parameters for now, although feel free to read the comments there and adjust
them as needed (especially number of workers/threads).StagesFor every calculated stageairwaycreates a new directory (stage-xx) and
subdirectories for each patient (e.g.3123156).Each stage has input stages, these are handled for you though, so you only need to specify which stages to create.
If you useraw_airwayas input stage, then calculatestage-01:airway stages 1You may add the-1flag to calculate a single patient for test purposes. Note that calculation ofstage-01may be really slow if you store your data on an HDD (multiple hours), as there are a lot of single small files with a large
overhead for switching between files.Or if you usestage-01as input you can calculatestage-02directly:airway stages 2If this works then great! You may continue to create all other stages as described below.
If it does not work, then make sure the data format is correct as described in theDatasection.
If you think everything is correct then please open an issue or message me, there may be bugs, or some stuff
may be naively hard-coded.You may list all stages with short descriptions by callingairway stageswithout any arguments,
or you can list all commands by using the--helpflag.Summary of the stages:Stages1 - 7use the raw data to create the tree splits used in the rest of the stages.Stages30 - 35analyse the tree structure, focusing mostly on the left upper lobe.Stages60 - 62are 3D visualisations, wherein .obj files of the lungs are exported.Stages70 - 72are plot visualisations of various stats.Stage90is the website which displays information for each patient including the 3D models.The airway pipeline checks if the stage already exists, if you need to overwrite
a stage you need to add the-f/--forceflag.You can now create all remaining stages like this:airway stages 2+It may take a couple of hours for everything, depending on how many patients you have.
If you don't have some dependencies installed you can still safely run it, and only those stages will crash.
Open the./logfile and search forSTDERRif you want to see the errors listed byairway.By default, eight patients will be calculated in parallel (8 workers are used).
If you have more CPU threads, simply increase the number of workers:airway stages 1 2 3 -w 32or change the default in the config file (defaults.yaml).To see the results you may open blender interactively like this:airway vis 1 -oThis loads the bronchus model with the correct materials for the segments.You can also see the various files created by the stages:stage-62: renders based on the lungstage-10: which contain.graphmlfiles describing the tree structure,
and the classifications created by the algorithm.stage-35: creates a pdf with renders for each patientstage-11: creates a pdf with the found clusters of the various structuresMore imagesExample trees for patient 3183090Credits & Thanks toAirway originated as an observation by Dr. Rolf Oerter at the University of Rostock
that certain structures in the lungs bronchus he has seen while operating have not been documented.
The first steps of the project were made as a student project at the University of Rostock
at the Department of Systems Biology organised by Mariam Nassar.It consisted of this team:Martin SteinbachBrutenis GliwaLukas GroßehagenbrockJonas MoesickeJoris ThieleAfter this, the project is being continued by me (Brutenis) as my bachelor thesis.
Thanks to Mariam Nassar, Dr. Rolf Oerter, Gundram Leifert and Prof. Olaf Wolkenhauer for supervision during this time.
And thanks to Planet AI for letting me write my thesis at their office.