Merge pull request #47 from BrainLesion/43-add-2024-inpainting-algori…

…thms

43 add 2024 inpainting algorithms

README.md

@@ -26,7 +26,7 @@ pip install brats
 > [!IMPORTANT]  
 > To run `brats` you require a Docker installation. <br>
 > Many algorithms also require GPU support (NVIDIA Docker). <br>
-> In case you do not have access to a Cuda-capable GPU, the overview tables in the [Algorithms](#algorithms) section indicate which algorithms are CPU compatible.
+> In case you do not have access to a Cuda-capable GPU, the overview tables in the [Available Algorithms and Usage](#available-algorithms-and-Usage) section indicate which algorithms are CPU compatible.
 
 
 
@@ -36,13 +36,19 @@ pip install brats
 - **Docker**: Installation instructions on the official [website](https://docs.docker.com/get-docker/)
 - **NVIDIA Container Toolkit**: Refer to the [NVIDIA install guide](https://docs.nvidia.com/datacenter/cloud-native/container-toolkit/latest/install-guide.html) and the official [GitHub page](https://github.com/NVIDIA/nvidia-container-toolkit)
 
-## Use Cases and Tutorials
 
-A minimal example to create a segmentation could look like this:
+## Available Algorithms and Usage
+
+### Segmentation
+<details open>
+
+<summary> <strong> Adult Glioma Segmentation </strong> </summary>
+<br>
+
 
 ```python
 from brats import AdultGliomaSegmenter
-from brats.utils.constants import AdultGliomaAlgorithms
+from brats.constants import AdultGliomaAlgorithms
 
 segmenter = AdultGliomaSegmenter(algorithm=AdultGliomaAlgorithms.BraTS23_1, cuda_devices="0")
 # these parameters are optional, by default the winning algorithm will be used on cuda:0
@@ -55,19 +61,10 @@ segmenter.infer_single(
 )
 ```
 
-For more examples and details please refer to our extensive Notebook tutorials here [NBViewer](https://nbviewer.org/github/BrainLesion/tutorials/blob/main/BraTS/tutorial.ipynb) ([GitHub](https://github.com/BrainLesion/tutorials/blob/main/BraTS/tutorial.ipynb)). For the best experience open the notebook in Colab.
-
-## Algorithms
-
-<details open>
-
-<summary> <strong> Adult Glioma Segmentation </strong> </summary>
-<br>
-
 **Class:** `brats.AdultGliomaSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/core/segmentation_algorithms.html#brats.core.segmentation_algorithms.AdultGliomaSegmenter))
 
-| Year | Rank | Author                            | Paper                                      | CPU Support | Key Enum |
-| ---- | ---- | --------------------------------- | ------------------------------------------ | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Year | Rank | Author                            | Paper                                      | CPU Support | Key Enum                                                                                                                   |
+| ---- | ---- | --------------------------------- | ------------------------------------------ | ----------- | -------------------------------------------------------------------------------------------------------------------------- |
 | 2023 | 1st  | _André Ferreira, et al._          | [Link](https://arxiv.org/abs/2402.17317v1) | &#x274C;    | [BraTS23_1](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.AdultGliomaAlgorithms.BraTS23_1) |
 | 2023 | 2nd  | _Andriy Myronenko, et al._        | N/A                                        | &#x274C;    | [BraTS23_2](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.AdultGliomaAlgorithms.BraTS23_2) |
 | 2023 | 3rd  | _Fadillah Adamsyah Maani, et al._ | N/A                                        | &#x274C;    | [BraTS23_3](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.AdultGliomaAlgorithms.BraTS23_3) |
@@ -78,10 +75,25 @@ For more examples and details please refer to our extensive Notebook tutorials h
 <summary> <strong> BraTS-Africa Segmentation </strong> </summary>
 <br>
 
+```python
+from brats import AfricaSegmenter
+from brats.constants import AfricaAlgorithms
+
+segmenter = AfricaSegmenter(algorithm=AfricaAlgorithms.BraTS23_1, cuda_devices="0")
+# these parameters are optional, by default the winning algorithm will be used on cuda:0
+segmenter.infer_single(
+    t1c="path/to/t1c.nii.gz",
+    t1n="path/to/t1n.nii.gz",
+    t2f="path/to/t2f.nii.gz",
+    t2w="path/to/t2w.nii.gz",
+    output_file="segmentation.nii.gz",
+)
+```
+
 **Class:** `brats.AfricaSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/core/segmentation_algorithms.html#brats.core.segmentation_algorithms.AfricaSegmenter))
 
-| Year | Rank | Author                     | Paper | CPU Support | Key Enum |
-| ---- | ---- | -------------------------- | ----- | ----------- | ------------------------------------------------------------------------------------------------------------------- |
+| Year | Rank | Author                     | Paper | CPU Support | Key Enum                                                                                                              |
+| ---- | ---- | -------------------------- | ----- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
 | 2023 | 1st  | _Andriy Myronenko, et al._ | TODO  | &#x274C;    | [BraTS23_1](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.AfricaAlgorithms.BraTS23_1) |
 | 2023 | 2nd  | _Alyssa R Amod, et al._    | N/A   | &#x274C;    | [BraTS23_2](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.AfricaAlgorithms.BraTS23_2) |
 | 2023 | 3rd  | _Ziyan Huang, et al._      | N/A   | &#x2705;    | [BraTS23_3](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.AfricaAlgorithms.BraTS23_3) |
@@ -92,10 +104,25 @@ For more examples and details please refer to our extensive Notebook tutorials h
 <summary> <strong> Meningioma Segmentation </strong> </summary>
 <br>
 
+```python
+from brats import MeningiomaSegmenter
+from brats.constants import MeningiomaAlgorithms
+
+segmenter = MeningiomaSegmenter(algorithm=MeningiomaAlgorithms.BraTS23_1, cuda_devices="0")
+# these parameters are optional, by default the winning algorithm will be used on cuda:0
+segmenter.infer_single(
+    t1c="path/to/t1c.nii.gz",
+    t1n="path/to/t1n.nii.gz",
+    t2f="path/to/t2f.nii.gz",
+    t2w="path/to/t2w.nii.gz",
+    output_file="segmentation.nii.gz",
+)
+```
+
 **Class:** `brats.MeningiomaSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/core/segmentation_algorithms.html#brats.core.segmentation_algorithms.MeningiomaSegmenter))
 
-| Year | Rank | Author                     | Paper | CPU Support | Key Enum |
-| ---- | ---- | -------------------------- | ----- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Year | Rank | Author                     | Paper | CPU Support | Key Enum                                                                                                                  |
+| ---- | ---- | -------------------------- | ----- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
 | 2023 | 1st  | _Andriy Myronenko, et al._ | N/A   | &#x274C;    | [BraTS23_1](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.MeningiomaAlgorithms.BraTS23_1) |
 | 2023 | 2nd  | _Ziyan Huang, et al._      | N/A   | &#x2705;    | [BraTS23_2](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.MeningiomaAlgorithms.BraTS23_2) |
 | 2023 | 3rd  | _Zhifan Jiang et al._      | N/A   | &#x274C;    | [BraTS23_3](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.MeningiomaAlgorithms.BraTS23_3) |
@@ -106,10 +133,25 @@ For more examples and details please refer to our extensive Notebook tutorials h
 <summary> <strong> Brain Metastases Segmentation </strong> </summary>
 <br>
 
+```python
+from brats import MetastasesSegmenter
+from brats.constants import MetastasesAlgorithms
+
+segmenter = MetastasesSegmenter(algorithm=MetastasesAlgorithms.BraTS23_1, cuda_devices="0")
+# these parameters are optional, by default the winning algorithm will be used on cuda:0
+segmenter.infer_single(
+    t1c="path/to/t1c.nii.gz",
+    t1n="path/to/t1n.nii.gz",
+    t2f="path/to/t2f.nii.gz",
+    t2w="path/to/t2w.nii.gz",
+    output_file="segmentation.nii.gz",
+)
+```
+
 **Class:** `brats.MetastasesSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/core/segmentation_algorithms.html#brats.core.segmentation_algorithms.MetastasesSegmenter))
 
-| Year | Rank | Author                     | Paper | CPU Support | Key Enum |
-| ---- | ---- | -------------------------- | ----- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
+| Year | Rank | Author                     | Paper | CPU Support | Key Enum                                                                                                                  |
+| ---- | ---- | -------------------------- | ----- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
 | 2023 | 1st  | _Andriy Myronenko, et al._ | N/A   | &#x274C;    | [BraTS23_1](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.MetastasesAlgorithms.BraTS23_1) |
 | 2023 | 2nd  | _Siwei Yang, et al._       | N/A   | &#x274C;    | [BraTS23_2](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.MetastasesAlgorithms.BraTS23_2) |
 | 2023 | 3rd  | _Ziyan Huang, et al._      | N/A   | &#x2705;    | [BraTS23_3](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.MetastasesAlgorithms.BraTS23_3) |
@@ -120,32 +162,66 @@ For more examples and details please refer to our extensive Notebook tutorials h
 <summary> <strong> Pediatric Segmentation </strong> </summary>
 <br>
 
+```python
+from brats import PediatricSegmenter
+from brats.constants import PediatricAlgorithms
+
+segmenter = PediatricSegmenter(algorithm=PediatricAlgorithms.BraTS23_1, cuda_devices="0")
+# these parameters are optional, by default the winning algorithm will be used on cuda:0
+segmenter.infer_single(
+    t1c="path/to/t1c.nii.gz",
+    t1n="path/to/t1n.nii.gz",
+    t2f="path/to/t2f.nii.gz",
+    t2w="path/to/t2w.nii.gz",
+    output_file="segmentation.nii.gz",
+)
+```
+
 **Class:** `brats.PediatricSegmenter` ([Docs](https://brats.readthedocs.io/en/latest/core/segmentation_algorithms.html#brats.core.segmentation_algorithms.PediatricSegmenter))
 
-| Year | Rank | Author                     | Paper | CPU Support | Key Enum |
-| ---- | ---- | -------------------------- | ----- | ----------- | ---------------------------------------------------------------------------------------------------------------------- |
+| Year | Rank | Author                     | Paper | CPU Support | Key Enum                                                                                                                 |
+| ---- | ---- | -------------------------- | ----- | ----------- | ------------------------------------------------------------------------------------------------------------------------ |
 | 2023 | 1st  | _Zhifan Jiang et al._      | N/A   | &#x274C;    | [BraTS23_1](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.PediatricAlgorithms.BraTS23_1) |
 | 2023 | 2nd  | _Andriy Myronenko, et al._ | N/A   | &#x274C;    | [BraTS23_2](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.PediatricAlgorithms.BraTS23_2) |
 | 2023 | 3rd  | _Yubo Zhou_                | N/A   | &#x274C;    | [BraTS23_3](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.PediatricAlgorithms.BraTS23_3) |
 
 </details>
 
----
+### Inpainting
 
 <details>
 <summary> <strong> Inpainting </strong> </summary>
 <br>
 
+```python
+from brats import Inpainter
+from brats.constants import InpaintingAlgorithms
+
+inpainter = Inpainter(algorithm=InpaintingAlgorithms.BraTS24_1, cuda_devices="0")
+inpainter.infer_single(
+    t1n="path/to/voided_t1n.nii.gz",
+    mask="path/to/mask.nii.gz",
+    output_file="inpainting.nii.gz",
+)
+```
+
 **Class:** `brats.Inpainter` ([Docs](https://brats.readthedocs.io/en/latest/core/inpainting_algorithms.html#brats.core.inpainting_algorithms.Inpainter))
 
-| Year | Rank | Author                  | Paper | CPU Support | Key Enum         |
-| ---- | ---- | ----------------------- | ----- | ----------- | ----------------------------------------------------------------------------------------------------------------------- |
-| 2023 | 1st  | _Juexin Zhang, et al._  | N/A   | &#x2705;    | [BraTS23_1](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.InpaintingAlgorithms.BraTS23_1) |
-| 2023 | 2nd  | _Alicia Durrer, et al._ | N/A   | &#x274C;    | [BraTS23_2](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.InpaintingAlgorithms.BraTS23_2) |
-| 2023 | 3rd  | _Jiayu Huo, et al._     | N/A   | &#x2705;    | [BraTS23_3](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.InpaintingAlgorithms.BraTS23_3) |
+| Year | Rank | Author                             | Paper | CPU Support | Key Enum                                                                                                                  |
+| ---- | ---- | ---------------------------------- | ----- | ----------- | ------------------------------------------------------------------------------------------------------------------------- |
+| 2024 | 1st  | _Ke Chen, Juexin Zhang, Ying Weng_ | N/A   | &#x2705;    | [BraTS24_1](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.InpaintingAlgorithms.BraTS24_1) |
+| 2024 | 2nd  | _André Ferreira, et al._           | N/A   | &#x274C;    | [BraTS24_2](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.InpaintingAlgorithms.BraTS24_2) |
+| 2024 | 3rd  | _Team SMINT_                       | N/A   | &#x274C;    | [BraTS24_3](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.InpaintingAlgorithms.BraTS24_3) |
+| 2023 | 1st  | _Juexin Zhang, et al._             | N/A   | &#x2705;    | [BraTS23_1](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.InpaintingAlgorithms.BraTS23_1) |
+| 2023 | 2nd  | _Alicia Durrer, et al._            | N/A   | &#x274C;    | [BraTS23_2](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.InpaintingAlgorithms.BraTS23_2) |
+| 2023 | 3rd  | _Jiayu Huo, et al._                | N/A   | &#x2705;    | [BraTS23_3](https://brats.readthedocs.io/en/latest/utils/utils.html#brats.utils.constants.InpaintingAlgorithms.BraTS23_3) |
 
 </details>
 
+>[!TIP]
+>For a full notebook example with more details please check here:  
+> [![nbviewer](https://raw.githubusercontent.com/jupyter/design/master/logos/Badges/nbviewer_badge.svg)](https://nbviewer.org/github/BrainLesion/tutorials/blob/main/BraTS/tutorial.ipynb)
+
 ## Citation
 
 If you use BraTS in your research, please cite it to support the development!

brats/utils/constants.py → brats/constants.py

@@ -81,16 +81,22 @@ class MetastasesAlgorithms(Algorithms):
 class InpaintingAlgorithms(Algorithms):
     """Constants for the available BraTS Inpainting algorithms."""
 
+    BraTS24_1 = "BraTS24_1"
+    """ BraTS24  Inpainting 1st place """
+    BraTS24_2 = "BraTS24_2"
+    """ BraTS24  Inpainting 2nd place """
+    BraTS24_3 = "BraTS24_3"
+    """ BraTS24  Inpainting 3rd place """
     BraTS23_1 = "BraTS23_1"
-    """BraTS23  Inpainting 1st place (GPU only)"""
+    """ BraTS23  Inpainting 1st place """
     BraTS23_2 = "BraTS23_2"
-    """BraTS23  Inpainting 2nd place (GPU only) (Very Slow)"""
+    """ BraTS23  Inpainting 2nd place (Very Slow) """
     BraTS23_3 = "BraTS23_3"
-    """BraTS23  Inpainting 3rd place (GPU only)"""
+    """ BraTS23  Inpainting 3rd place """
 
 
 # DIRECTORIES
-DATA_DIR = Path(__file__).parent.parent / "data"
+DATA_DIR = Path(__file__).parent / "data"
 META_DIR = DATA_DIR / "meta"
 PARAMETERS_DIR = DATA_DIR / "parameters"
 ADDITIONAL_FILES_FOLDER = DATA_DIR / "additional_files"

brats/core/brats_algorithm.py

@@ -10,7 +10,7 @@
 
 from brats.core.docker import run_container
 from brats.utils.algorithm_config import load_algorithms
-from brats.utils.constants import OUTPUT_NAME_SCHEMA, Algorithms, Task
+from brats.constants import OUTPUT_NAME_SCHEMA, Algorithms, Task
 from brats.utils.data_handling import InferenceSetup
 
 # Remove the default logger and add one with level INFO

brats/core/docker.py

@@ -15,7 +15,7 @@
 from rich.progress import Progress
 
 from brats.utils.algorithm_config import AlgorithmData
-from brats.utils.constants import DUMMY_PARAMETERS, PARAMETERS_DIR
+from brats.constants import DUMMY_PARAMETERS, PARAMETERS_DIR
 from brats.utils.exceptions import (
     AlgorithmNotCPUCompatibleException,
     BraTSContainerException,
@@ -231,7 +231,7 @@ def _observe_docker_output(container: docker.models.containers.Container) -> str
         # Wait for the container to finish
         exit_code = container.wait()
         container_output = "\n\r".join(
-            [line.decode("utf-8") for line in container_output]
+            [line.decode("utf-8", errors="replace") for line in container_output]
         )
         # Check if the container exited with an error
         if exit_code["StatusCode"] != 0:

brats/core/inpainting_algorithms.py

@@ -8,7 +8,7 @@
 from loguru import logger
 
 from brats.core.brats_algorithm import BraTSAlgorithm
-from brats.utils.constants import INPAINTING_ALGORITHMS, InpaintingAlgorithms, Task
+from brats.constants import INPAINTING_ALGORITHMS, InpaintingAlgorithms, Task
 from brats.utils.data_handling import input_sanity_check
 
 

brats/core/segmentation_algorithms.py

@@ -8,7 +8,7 @@
 from loguru import logger
 
 from brats.core.brats_algorithm import BraTSAlgorithm
-from brats.utils.constants import (
+from brats.constants import (
     ADULT_GLIOMA_SEGMENTATION_ALGORITHMS,
     AFRICA_SEGMENTATION_ALGORITHMS,
     MENINGIOMA_SEGMENTATION_ALGORITHMS,

brats/data/meta/inpainting.yml

@@ -1,5 +1,57 @@
 algorithms:
 
+  ######## 2024 Algorithms ########
+
+  BraTS24_1:
+    meta:
+      authors: Ke Chen, Juexin Zhang, Ying Weng
+      paper: N/A
+      challenge: BraTS24 Inpainting
+      rank: 1st
+      year: 2024
+    run_args:
+      docker_image: brainles/brats24_inpainting_ying_weng:latest
+      input_name_schema: "BraTS-GLI-{id:05d}-000"
+      requires_root: false
+      parameters_file: true
+      cpu_compatible: true
+    weights:
+      record_id: "14230865"
+      param_name: "checkpoint_path"
+
+  BraTS24_2:
+    meta:
+      authors: André Ferreira, et al.
+      paper: N/A
+      challenge: BraTS24 Inpainting
+      rank: 2nd
+      year: 2024
+    run_args:
+      docker_image: brainles/brats24_inpainting_faking_it:latest
+      input_name_schema: "BraTS-GLI-{id:05d}-000"
+      requires_root: false
+      parameters_file: false
+      shm_size: "4gb"
+
+  BraTS24_3:
+    meta:
+      authors: Team SMINT
+      paper: N/A
+      challenge: BraTS24 Inpainting
+      rank: 3rd
+      year: 2024
+    run_args:
+      docker_image: brainles/brats24_inpainting_smint:latest
+      input_name_schema: "BraTS-GLI-{id:05d}-000"
+      requires_root: false
+      parameters_file: true
+    weights:
+      record_id: "14231079"
+      param_name: "weights"
+      checkpoint_path: "savedmodel395000.pt"
+
+  ######## 2023 Algorithms ########
+
   BraTS23_1:
     meta:
       authors: Juexin Zhang, et al.
@@ -10,7 +62,7 @@ algorithms:
     run_args:
       docker_image: brainles/brats23_inpainting_ying_weng:latest
       input_name_schema: "BraTS-GLI-{id:05d}-000"
-      requires_root: true
+      requires_root: false
       parameters_file: true
       cpu_compatible: true
     weights: