Initial version

.gitattributes

@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
 *.zip filter=lfs diff=lfs merge=lfs -text
 *.zst filter=lfs diff=lfs merge=lfs -text
 *tfevents* filter=lfs diff=lfs merge=lfs -text
+models/model.ts filter=lfs diff=lfs merge=lfs -text

README.md

@@ -0,0 +1,45 @@
+---
+tags:
+- monai
+- medical
+library_name: monai
+license: unknown
+---
+
+# 3 Label Ventricular Segmentation
+
+This network segments cardiac ventricle in 2D short axis MR images. The left ventricular pool is class 1, left ventricular myocardium class 2, and right ventricular pool class 3. Full cycle segmentation with this network is possible although much of the training data is composed of segmented end-diastole images. The input to the network is single 2D images thus segmenting whole time-dependent volumes consists of multiple inference operations.
+
+The network and training scheme are essentially identical to that described in:
+
+`Kerfoot E., Clough J., Oksuz I., Lee J., King A.P., Schnabel J.A. (2019) Left-Ventricle Quantification Using Residual U-Net. In: Pop M. et al. (eds) Statistical Atlases and Computational Models of the Heart. Atrial Segmentation and LV Quantification Challenges. STACOM 2018. Lecture Notes in Computer Science, vol 11395. Springer, Cham. https://doi.org/10.1007/978-3-030-12029-0_40`
+
+## Data
+
+The dataset used to train this network unfortunately cannot be made public as it contains unreleased image data from King's College London. Existing public datasets such as the[Sunnybrook Cardiac Dataset](http://www.cardiacatlas.org/studies/sunnybrook-cardiac-data/) and [ACDC Challenge](https://www.creatis.insa-lyon.fr/Challenge/acdc/) set can be used to train a similar network.
+
+The `train.json` configuration assumes all data is stored in a single npz file with keys "images" and "segs" containing respectively the raw image data and their accompanying segmentations. The given network was training with stored volumes with shapes `(9095, 256, 256)` thus other data of differing spatial dimensions must be cropped to `(256, 256)` or zero-padded to that size. For the training data this was done as a preprocessing step but the original pixel values are otherwise unchanged from their original forms.
+
+## Training
+
+The network is trained with this data in conjunction with a series of augmentations for regularisation and robustness. Many of the original images are smaller than the expected size of `(256, 256)` and so were zero-padded, the network can thus be expected to be robust against large amounts of empty space in the inputs. Rotation and zooming is also applied to force the network to learn different sizes and orientations of the heart in the field of view.
+
+Free-form deformation is applied to vary the shape of the heart and its surrounding tissues which mimics to a degree deformation like what would be observed through the cardiac cycle. This of course does not replicate the heart moving through plane during the cycle or represent other observed changes but does provide enough variation that full-cycle segmentation is generally acceptable.
+
+Smooth fields are used to vary contrast and intensity in localised regions to simulate some of the variation in image quality caused by acquisition artefacts. Guassian noise is also added to simulate poor quality acquisition. These together force the network to learn to deal with a wider variation of image quality and partially to account for the difference between scanner vendors.
+
+Training is invoked with the following command line:
+
+```sh
+python -m monai.bundle run training --meta_file configs/metadata.json --config_file configs/train.json --logging_file configs/logging.conf --bundle_root .
+```
+
+The dataset file is assumed to be `allimages3label.npz` but can be changed by setting the `dataset_file` value to your own file.
+
+## Inference
+
+An example notebook [visualise.ipynb](./visualise.ipynb) demonstrates using the network directly with input images. Inference of 3D volumes only can be accomplished with the `inference.json` configuration:
+
+```sh
+python -m monai.bundle run evaluating --meta_file configs/metadata.json --config_file configs/inference.json --logging_file configs/logging.conf --dataset_dir dataset --output_dir ./output/ --bundle_root .
+```

configs/inference.json

@@ -0,0 +1,124 @@
+{
+    "imports": [
+        "$import glob"
+    ],
+    "device": "$torch.device('cuda:0' if torch.cuda.is_available() else 'cpu')",
+    "ckpt_path": "$@bundle_root + '/models/model.pt'",
+    "dataset_dir": "/workspace/data",
+    "output_dir": "./output",
+    "datalist": "$list(sorted(glob.glob(@dataset_dir + '/*.nii*')))",
+    "network_def": {
+        "_target_": "UNet",
+        "spatial_dims": 2,
+        "in_channels": 1,
+        "out_channels": 4,
+        "channels": [
+            16,
+            32,
+            64,
+            128,
+            256
+        ],
+        "strides": [
+            2,
+            2,
+            2,
+            2
+        ],
+        "num_res_units": 2
+    },
+    "network": "$@network_def.to(@device)",
+    "preprocessing": {
+        "_target_": "Compose",
+        "transforms": [
+            {
+                "_target_": "LoadImaged",
+                "keys": "image"
+            },
+            {
+                "_target_": "EnsureChannelFirstd",
+                "keys": "image"
+            },
+            {
+                "_target_": "ScaleIntensityd",
+                "keys": "image"
+            },
+            {
+                "_target_": "EnsureTyped",
+                "keys": "image",
+                "device": "@device"
+            }
+        ]
+    },
+    "dataset": {
+        "_target_": "Dataset",
+        "data": "$[{'image': i} for i in @datalist]",
+        "transform": "@preprocessing"
+    },
+    "dataloader": {
+        "_target_": "DataLoader",
+        "dataset": "@dataset",
+        "batch_size": 1,
+        "shuffle": false,
+        "num_workers": 0
+    },
+    "inferer": {
+        "_target_": "SliceInferer",
+        "roi_size": [
+            256,
+            256
+        ],
+        "spatial_dim": 2
+    },
+    "postprocessing": {
+        "_target_": "Compose",
+        "transforms": [
+            {
+                "_target_": "Activationsd",
+                "keys": "pred",
+                "softmax": true
+            },
+            {
+                "_target_": "Invertd",
+                "keys": "pred",
+                "transform": "@preprocessing",
+                "orig_keys": "image",
+                "meta_key_postfix": "meta_dict",
+                "nearest_interp": false,
+                "to_tensor": true
+            },
+            {
+                "_target_": "AsDiscreted",
+                "keys": "pred",
+                "argmax": true
+            },
+            {
+                "_target_": "SaveImaged",
+                "keys": "pred",
+                "meta_keys": "pred_meta_dict",
+                "output_dir": "@output_dir"
+            }
+        ]
+    },
+    "handlers": [
+        {
+            "_target_": "CheckpointLoader",
+            "load_path": "@ckpt_path",
+            "load_dict": {
+                "model": "@network"
+            }
+        }
+    ],
+    "evaluator": {
+        "_target_": "SupervisedEvaluator",
+        "device": "@device",
+        "val_data_loader": "@dataloader",
+        "network": "@network",
+        "inferer": "@inferer",
+        "postprocessing": "@postprocessing",
+        "val_handlers": "@handlers"
+    },
+    "evaluating": [
+        "$@evaluator.run()"
+    ]
+}

configs/logging.conf

@@ -0,0 +1,21 @@
+[loggers]
+keys=root
+
+[handlers]
+keys=consoleHandler
+
+[formatters]
+keys=fullFormatter
+
+[logger_root]
+level=INFO
+handlers=consoleHandler
+
+[handler_consoleHandler]
+class=StreamHandler
+level=INFO
+formatter=fullFormatter
+args=(sys.stdout,)
+
+[formatter_fullFormatter]
+format=%(asctime)s - %(name)s - %(levelname)s - %(message)s

configs/metadata.json

@@ -0,0 +1,62 @@
+{
+    "schema": "https://github.com/Project-MONAI/MONAI-extra-test-data/releases/download/0.8.1/meta_schema_20220324.json",
+    "version": "0.1.0",
+    "changelog": {
+        "0.1.0": "Initial version"
+    },
+    "monai_version": "0.9.0",
+    "pytorch_version": "1.10.2",
+    "numpy_version": "1.21.2",
+    "optional_packages_version": {
+        "nibabel": "3.2.1",
+        "pytorch-ignite": "0.4.8"
+    },
+    "task": "Segments the left and right ventricle in 2D short axis MR images",
+    "description": "This network segments full cycle short axis images of the ventricles, labelling LV pool separate from myocardium and RV pool",
+    "authors": "Eric Kerfoot",
+    "copyright": "Copyright (c) Eric Kerfoot, KCL",
+    "license": "See license.txt",
+    "network_data_format": {
+        "inputs": {
+            "image": {
+                "type": "image",
+                "format": "magnitude",
+                "modality": "MR",
+                "num_channels": 1,
+                "spatial_shape": [
+                    256,
+                    256
+                ],
+                "dtype": "float32",
+                "value_range": [],
+                "is_patch_data": false,
+                "channel_def": {
+                    "0": "image"
+                }
+            }
+        },
+        "outputs": {
+            "pred": {
+                "type": "image",
+                "format": "segmentation",
+                "num_channels": 4,
+                "spatial_shape": [
+                    256,
+                    256
+                ],
+                "dtype": "float32",
+                "value_range": [
+                    0,
+                    3
+                ],
+                "is_patch_data": false,
+                "channel_def": {
+                    "0": "background",
+                    "1": "lv_pool",
+                    "2": "myocardium",
+                    "3": "rv_pool"
+                }
+            }
+        }
+    }
+}

configs/train.json

@@ -0,0 +1,306 @@
+{
+    "imports": [
+        "$from functools import partial",
+        "$import numpy as np",
+        "$import torch",
+        "$from ignite.engine import Events"
+    ],
+    "device": "$torch.device('cuda:0' if torch.cuda.is_available() else 'cpu')",
+    "ckpt_path": "$@bundle_root + '/models/model.pt'",
+    "dataset_file": "./allimages3label.npz",
+    "network_def": {
+        "_target_": "UNet",
+        "spatial_dims": 2,
+        "in_channels": 1,
+        "out_channels": 4,
+        "channels": [
+            16,
+            32,
+            64,
+            128,
+            256
+        ],
+        "strides": [
+            2,
+            2,
+            2,
+            2
+        ],
+        "num_res_units": 2
+    },
+    "network": "$@network_def.to(@device)",
+    "npz": {
+        "_target_": "NPZDictItemDataset",
+        "npzfile": "$@dataset_file",
+        "keys": {
+            "images": "image",
+            "segs": "label"
+        }
+    },
+    "partitions": "$monai.data.partition_dataset(np.arange(len(@npz)),(8,2), shuffle=True)",
+    "train_sub": "$torch.utils.data.Subset(@npz,@partitions[0])",
+    "eval_sub": "$torch.utils.data.Subset(@npz,@partitions[1])",
+    "im_shape": "$@train_sub[0]['image'].shape",
+    "both_keys": [
+        "image",
+        "label"
+    ],
+    "rand_prob": 0.5,
+    "train_transforms": {
+        "_target_": "Compose",
+        "transforms": [
+            {
+                "_target_": "CastToTyped",
+                "keys": "@both_keys",
+                "dtype": "$(np.float32, np.int32)"
+            },
+            {
+                "_target_": "ScaleIntensityd",
+                "keys": "image"
+            },
+            {
+                "_target_": "AddChanneld",
+                "keys": "@both_keys"
+            },
+            {
+                "_target_": "RandAxisFlipd",
+                "keys": "@both_keys",
+                "prob": "@rand_prob"
+            },
+            {
+                "_target_": "RandRotate90d",
+                "keys": "@both_keys",
+                "prob": "@rand_prob"
+            },
+            {
+                "_target_": "RandSmoothDeformd",
+                "keys": "@both_keys",
+                "prob": "@rand_prob",
+                "spatial_size": "@im_shape",
+                "rand_size": [
+                    3,
+                    3
+                ],
+                "pad": 2,
+                "def_range": 0.1,
+                "field_mode": "$monai.utils.InterpolateMode.BICUBIC",
+                "grid_mode": "$(monai.utils.GridSampleMode.BICUBIC, monai.utils.GridSampleMode.NEAREST)",
+                "align_corners": true
+            },
+            {
+                "_target_": "RandAffined",
+                "keys": "@both_keys",
+                "prob": "@rand_prob",
+                "rotate_range": 0.5,
+                "translate_range": 50,
+                "scale_range": 0.25,
+                "padding_mode": "$monai.utils.GridSamplePadMode.ZEROS",
+                "mode": "$(monai.utils.GridSampleMode.BILINEAR,monai.utils.GridSampleMode.NEAREST)",
+                "as_tensor_output": false
+            },
+            {
+                "_target_": "RandSmoothFieldAdjustContrastd",
+                "keys": "image",
+                "prob": "@rand_prob",
+                "spatial_size": "@im_shape",
+                "rand_size": [
+                    8,
+                    8
+                ],
+                "gamma": [
+                    0.25,
+                    3
+                ],
+                "mode": "$monai.utils.InterpolateMode.BICUBIC",
+                "align_corners": true
+            },
+            {
+                "_target_": "RandSmoothFieldAdjustIntensityd",
+                "keys": "image",
+                "prob": "@rand_prob",
+                "spatial_size": "@im_shape",
+                "rand_size": [
+                    5,
+                    5
+                ],
+                "gamma": [
+                    0.1,
+                    1
+                ],
+                "mode": "$monai.utils.InterpolateMode.BICUBIC",
+                "align_corners": true
+            },
+            {
+                "_target_": "RandGaussianNoised",
+                "keys": "image",
+                "prob": "@rand_prob",
+                "std": 0.05
+            },
+            {
+                "_target_": "ScaleIntensityd",
+                "keys": "image"
+            },
+            {
+                "_target_": "CastToTyped",
+                "keys": "@both_keys",
+                "dtype": "$(np.float32, np.int32)"
+            },
+            {
+                "_target_": "EnsureTyped",
+                "keys": "@both_keys"
+            }
+        ]
+    },
+    "eval_transforms": {
+        "_target_": "Compose",
+        "transforms": [
+            {
+                "_target_": "CastToTyped",
+                "keys": "@both_keys",
+                "dtype": "$(np.float32, np.int32)"
+            },
+            {
+                "_target_": "ScaleIntensityd",
+                "keys": "image"
+            },
+            {
+                "_target_": "AddChanneld",
+                "keys": "@both_keys"
+            },
+            {
+                "_target_": "EnsureTyped",
+                "keys": "@both_keys"
+            }
+        ]
+    },
+    "train_dataset": {
+        "_target_": "CacheDataset",
+        "data": "@train_sub",
+        "transform": "@train_transforms"
+    },
+    "eval_dataset": {
+        "_target_": "CacheDataset",
+        "data": "@eval_sub",
+        "transform": "@eval_transforms"
+    },
+    "train_no_aug_dataset": {
+        "_target_": "CacheDataset",
+        "data": "@train_sub",
+        "transform": "@eval_transforms"
+    },
+    "num_iters": 400,
+    "batch_size": 200,
+    "num_epochs": 50,
+    "num_substeps": 5,
+    "sampler": {
+        "_target_": "torch.utils.data.WeightedRandomSampler",
+        "weights": "$torch.ones(len(@train_dataset))",
+        "replacement": true,
+        "num_samples": "$@num_iters*@batch_size"
+    },
+    "train_dataloader": {
+        "_target_": "ThreadDataLoader",
+        "dataset": "@train_dataset",
+        "batch_size": "@batch_size",
+        "repeats": "@num_substeps",
+        "num_workers": 8,
+        "sampler": "@sampler"
+    },
+    "eval_dataloader": {
+        "_target_": "DataLoader",
+        "dataset": "@eval_dataset",
+        "batch_size": "@batch_size",
+        "num_workers": 4
+    },
+    "lossfn": {
+        "_target_": "DiceLoss",
+        "include_background": false,
+        "to_onehot_y": true,
+        "softmax": true
+    },
+    "optimizer": {
+        "_target_": "torch.optim.Adam",
+        "params": "$@network.parameters()",
+        "lr": 0.001
+    },
+    "post_transform": {
+        "_target_": "Compose",
+        "transforms": [
+            {
+                "_target_": "Activationsd",
+                "keys": "pred",
+                "softmax": true
+            },
+            {
+                "_target_": "AsDiscreted",
+                "keys": [
+                    "pred",
+                    "label"
+                ],
+                "argmax": [
+                    true,
+                    false
+                ],
+                "to_onehot": 4
+            }
+        ]
+    },
+    "evaluator": {
+        "_target_": "SupervisedEvaluator",
+        "device": "@device",
+        "val_data_loader": "@eval_dataloader",
+        "network": "@network",
+        "postprocessing": "@post_transform",
+        "key_val_metric": {
+            "val_mean_dice": {
+                "_target_": "MeanDice",
+                "include_background": false,
+                "output_transform": "$monai.handlers.from_engine(['pred', 'label'])"
+            }
+        },
+        "val_handlers": [
+            {
+                "_target_": "StatsHandler",
+                "output_transform": "$lambda x: None"
+            }
+        ]
+    },
+    "handlers": [
+        {
+            "_target_": "ValidationHandler",
+            "validator": "@evaluator",
+            "epoch_level": true,
+            "interval": 1
+        },
+        {
+            "_target_": "CheckpointSaver",
+            "save_dir": "$@bundle_root + '/models'",
+            "save_dict": {
+                "model": "@network"
+            },
+            "save_interval": 1,
+            "save_final": true,
+            "epoch_level": true
+        },
+        {
+            "_target_": "StatsHandler",
+            "tag_name": "train_loss",
+            "output_transform": "$monai.handlers.from_engine(['loss'], first=True)"
+        }
+    ],
+    "trainer": {
+        "_target_": "SupervisedTrainer",
+        "max_epochs": "@num_epochs",
+        "device": "@device",
+        "train_data_loader": "@train_dataloader",
+        "network": "@network",
+        "loss_function": "@lossfn",
+        "optimizer": "@optimizer",
+        "postprocessing": "@post_transform",
+        "key_train_metric": null,
+        "train_handlers": "@handlers"
+    },
+    "training": [
+        "$@trainer.run()"
+    ]
+}

docs/README.md

@@ -0,0 +1,38 @@
+
+# 3 Label Ventricular Segmentation
+
+This network segments cardiac ventricle in 2D short axis MR images. The left ventricular pool is class 1, left ventricular myocardium class 2, and right ventricular pool class 3. Full cycle segmentation with this network is possible although much of the training data is composed of segmented end-diastole images. The input to the network is single 2D images thus segmenting whole time-dependent volumes consists of multiple inference operations.
+
+The network and training scheme are essentially identical to that described in:
+
+`Kerfoot E., Clough J., Oksuz I., Lee J., King A.P., Schnabel J.A. (2019) Left-Ventricle Quantification Using Residual U-Net. In: Pop M. et al. (eds) Statistical Atlases and Computational Models of the Heart. Atrial Segmentation and LV Quantification Challenges. STACOM 2018. Lecture Notes in Computer Science, vol 11395. Springer, Cham. https://doi.org/10.1007/978-3-030-12029-0_40`
+
+## Data
+
+The dataset used to train this network unfortunately cannot be made public as it contains unreleased image data from King's College London. Existing public datasets such as the[Sunnybrook Cardiac Dataset](http://www.cardiacatlas.org/studies/sunnybrook-cardiac-data/) and [ACDC Challenge](https://www.creatis.insa-lyon.fr/Challenge/acdc/) set can be used to train a similar network.
+
+The `train.json` configuration assumes all data is stored in a single npz file with keys "images" and "segs" containing respectively the raw image data and their accompanying segmentations. The given network was training with stored volumes with shapes `(9095, 256, 256)` thus other data of differing spatial dimensions must be cropped to `(256, 256)` or zero-padded to that size. For the training data this was done as a preprocessing step but the original pixel values are otherwise unchanged from their original forms.
+
+## Training
+
+The network is trained with this data in conjunction with a series of augmentations for regularisation and robustness. Many of the original images are smaller than the expected size of `(256, 256)` and so were zero-padded, the network can thus be expected to be robust against large amounts of empty space in the inputs. Rotation and zooming is also applied to force the network to learn different sizes and orientations of the heart in the field of view.
+
+Free-form deformation is applied to vary the shape of the heart and its surrounding tissues which mimics to a degree deformation like what would be observed through the cardiac cycle. This of course does not replicate the heart moving through plane during the cycle or represent other observed changes but does provide enough variation that full-cycle segmentation is generally acceptable.
+
+Smooth fields are used to vary contrast and intensity in localised regions to simulate some of the variation in image quality caused by acquisition artefacts. Guassian noise is also added to simulate poor quality acquisition. These together force the network to learn to deal with a wider variation of image quality and partially to account for the difference between scanner vendors.
+
+Training is invoked with the following command line:
+
+```sh
+python -m monai.bundle run training --meta_file configs/metadata.json --config_file configs/train.json --logging_file configs/logging.conf --bundle_root .
+```
+
+The dataset file is assumed to be `allimages3label.npz` but can be changed by setting the `dataset_file` value to your own file.
+
+## Inference
+
+An example notebook [visualise.ipynb](./visualise.ipynb) demonstrates using the network directly with input images. Inference of 3D volumes only can be accomplished with the `inference.json` configuration:
+
+```sh
+python -m monai.bundle run evaluating --meta_file configs/metadata.json --config_file configs/inference.json --logging_file configs/logging.conf --dataset_dir dataset --output_dir ./output/ --bundle_root .
+```

docs/SC-N-2-3-0.npy

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:03c7fae03f14710b9b1e6709d1d4d101b8569a94f3781376ac92f659483d6f16
+size 524416

docs/license.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) [year] [fullname]
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

models/model.pt

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:464ca796028831f6c9e2b1cdaebe9af002fc1d7f494f7a89a63f2079e38837a1
+size 6533160

models/model.ts

@@ -0,0 +1,3 @@
+version https://git-lfs.github.com/spec/v1
+oid sha256:27d5532401fa6c1883872fa21635adbb7615981e7f385d0c58dd75b355e340b3
+size 6631889