neuropoly · maxradx · Nov 14, 2024 · Nov 14, 2024 · Nov 14, 2024 · Nov 14, 2024
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -19,3 +19,6 @@ Wish to contribute to the development of this 3D Slicer module/extension? As a t
 
   * [PEP8 style guide official documentation](https://peps.python.org/pep-0008/)
   * [Polytechnique Montreal Home-Made Guide for programming style (in French)](https://github.com/INF1007-Gabarits/Guide-codage-python)
+
+[GO on Documentation Welcome Page](./SlicerCART/documentation/welcome.md). 
+[GO on README.md Page](README.md).
diff --git a/README.md b/README.md
@@ -2,105 +2,31 @@
 ![](SlicerCART/src/Resources/Icons/SlicerCART.png)
 SlicerCART: Configurable Annotation and Review Tool. 
 
-## Description
+This is a 3D Slicer extension aimed to improve workflow in manual 
+segmentation, classification and revision tasks. For example, SlicerCART 
+enables to 
+quickly load specific volumes of a dataset and navigate through them, 
+perform manual segmentation of medical images (e.g. annotating 
+multiple sclerosis lesions on MRI) or compare different segmentation 
+versions (e.g. lesion segmentation generated by a deep learning-based model).
 
-* 3D Slicer extension
-* Adapted from code of Dr. Laurent Létourneau-Guillon and his team in [ICH_SEGMENTER_V2](https://github.com/laurentletg/ICH_SEGMENTER_V2), [SlicerCART](https://github.com/laurentletg/SlicerCART), and [Brain_Extraction](https://github.com/MattFr56/CT_Brain_Extraction/blob/main/Brain_Extraction/Brain_Extraction/Brain_Extraction.py). This is an effort to create a unified code for a configurable 3D Slicer extension. 
-* Inspired from [Neuropoly](https://neuro.polymtl.ca/)'s workflow. 
-* This tool is made to improve manual segmentation and classification workflows across different teams. 
+###### [Installation](./SlicerCART/documentation/installation.md)
 
-**Keywords:** medical imaging, manual segmentation, manual correction, workflow, ground-truth segmentation, quality control
+###### [QuickStart](./SlicerCART/documentation/quickstart.md)
 
-**Abbreviations:**
+##### [See Documentation](./SlicerCART/documentation/welcome.md)
 
-- MRI - Magnetic Resonance Imaging
-- CT - Computed Tomography
-- BIDS - Brain Imaging Data Structure
-- GUI - Graphical User Interface
-- QC - Quality Control
 
-**Rationale:**
-
-* Manual segmentation and classification tasks are required in the research setting related to medical imaging artificial intelligence tool development
-* An open-source solution for such tasks would better benefit the research setting
-* Actual open-source solutions that enable imaging viewing and annotation are not optimal from an end-user standpoint (especially from various background), increasing the already high burden of manual segmentation and classification tasks
-* A workflow aimed to efficiently navigate through a dataset while performing manual segmentation / correction, including revision steps and robust annotation consistency assessment is crucial for handling large amount of data and provide the best ground-truth references segmentation as possible. 
-
-**Module specific functions (in details)**
-
-This module has been adapted to perform several tasks. Among other things, it allows the user to:
-
-* Customize configuration preferences (see below for details)
-* Customize keyboard shortcuts
-* Identify the name, degree and revision step related to the human annotator
-* Select folder of interest where volumes are saved (and possibly impose BIDS)
-* Select the output folder where processing and work is preferred to be saved
-* Select a ground-truth folder where references studies can be used for iterative self-assessment
-* Display in the GUI a case list of all the studies of interests for the segmentation task (*from a site directory or a customized list)
-* Select from the GUI case list any volume of interest to display
-* Navigate through case list from next and previous buttons
-* Load automatically the first remaining case for segmentation in a customized list
-* Create automatically all required segments that may be used according to the project configuration each time a volume is displayed
-* Toggle interpolation of the volume loaded
-* Execute multiple automated functions when saving segmentation masks for a given volume. Indeed, the automated functions:
-  * Save segmentation masks in the selected output folder with volume file hierarchy
-  * Track the different versions (save the following version if previous version(s) already exist(s)) **N.B. limitation to 99 versions for a single volume*
-  * Save a .csv file with segmentation statistics (e.g. subject, annotator's name and degree, revision step, date and time, total duration, duration of each label annotation)
-  * Save a .csv file with classification statistics (e.g. subject, annotator's name and degree, revision step, date and time, checkboxes / dropdown / free text fields)
-  * Go to the next remaining case and make it ready to segment without any further action
-* Load a pre-existing segmentation for further modification (will be saved as a new version of the segmentation)
-
-### Requirements
-
-* MacOS Sonoma or Sequoia is recommended 
-* A working version of [3D Slicer](https://download.slicer.org).
-  * N.B. The version currently used to develop this module is the version 5.6.2 (most stable release as of 2024-10-22). The version 5.2.2 has also been used.
-
-This module has been developed on:
-
-* MacOS Sonoma version 14.1.1 and Sequoia 15.0.1
-* 3D Slicer version 5.6.2
-
-Although it may work on other versions and/or operating system, please note that it has not been tested.
-
-## Installation steps
-
-If previous version of Slicer ---» delete the app. If on MacOS, you can do it by doing right lick on the app in the application folder --- move to trash --- go to trash --- empty the trash --- restart your computer.
-
-
-1. Install [3D Slicer](https://download.slicer.org).  
-2. Clone this repository in the location of your choice.
-3. Then, go in the finder --- find the file SlicerCART.py file, and copy the pathname.
-4. Open 3D Slicer.
-5. Activate the checkbox `Enable developer mode` in `Edit -> Application Settings -> Developer -> Enable developer mode`. 
-6. Add the path of the `SlicerCART.py` file in `Edit -> Application Settings -> Modules -> Additional module paths`.(N.B. 1) You must have the file: if it is the folder path, then the module will not work; 2) in the Additional modul path section, the path copied might be shown to the folder: this is a Slicer thing, and should not affect working property of the module if it was the file that you copied).
-7. The module can be found under `Examples -> SlicerCART`: the module should now be opened (N.B. 1) If first use, you may have additional requirements to install. A pop-up window from Slicer advertising you should pop-up if so: just click ok).
-8. (Optional) Set the SlicerCART module to launch at 3DSlicer startup. To do so, go to `Edit -> Application Settings -> Modules -> Default startup module`
-9. There might be errors. These would be seen in the Python Console: if any errors, we highly recommend you to fix them before any further use!
-
-### Trouble shooting 
-
-* Qt might need to be installed. The first five steps of the following procedure might be useful for this: [procedure](https://web.stanford.edu/dept/cs_edu/resources/qt/install-mac). 
-
-### Other extensions that could be useful
-* `SlicerJupyter` to be able to use Jupyter Notebooks connected to 3D Slicer.
-
-### Documentation
-TODO (after sufficient development has been made)
-
-### Video tutorials 
-TODO (after sufficient development has been made)
+### Contributors
 
-### Other resources
-* [3D Slicer Tutorials](https://www.youtube.com/watch?v=QTEti9aY0vs&)
-* [3D Slicer Documentation](https://www.slicer.org/wiki/Documentation/Nightly/Training)
+1. Adapted from code of Dr. Laurent Létourneau-Guillon and his team in [ICH_SEGMENTER_V2](https://github.com/laurentletg/ICH_SEGMENTER_V2), [SlicerCART](https://github.com/laurentletg/SlicerCART), and [Brain_Extraction](https://github.com/MattFr56/CT_Brain_Extraction/blob/main/Brain_Extraction/Brain_Extraction/Brain_Extraction.py). This is an effort to create a unified code for a configurable 3D Slicer extension.
+2. Inspired from [Neuropoly](https://neuro.polymtl.ca/)'s workflow. 
 
-### Contributors
-[![Contributors](https://img.shields.io/github/contributors/neuropoly/slicer-manual-annotation/graphs/contributors)](https://github.com/neuropoly/slicer-manual-annotation/graphs/contributors), including:
+1. [![Contributors](https://img.shields.io/github/contributors/neuropoly/slicer-manual-annotation/graphs/contributors)](https://github.com/neuropoly/slicer-manual-annotation/graphs/contributors), including:
 
-* Laurent Létourneau-Guillon
-* Emmanuel Montagnon
-* An Ni Wu
-* Maxime Bouthillier
-* Delphine Pilon
-* Neuropoly Team
+   * Laurent Létourneau-Guillon
+   * Emmanuel Montagnon
+   * An Ni Wu
+   * Maxime Bouthillier
+   * Delphine Pilon
+   * Neuropoly Team
diff --git a/SlicerCART/documentation/functionalities.md b/SlicerCART/documentation/functionalities.md
@@ -0,0 +1,83 @@
+# SlicerCART Functionalities
+
+This section lists the functionalities of SlicerCART. If the function you 
+are looking for is not found below, it is likely that SlicerCART does not have 
+yet 
+this feature: you are invited to open an issue on the [Github Repository](https://github.com/neuropoly/slicer-manual-annotation/issues) to 
+request the functionality you are looking for.
+
+**Specific functions (in details)**
+
+This module has been adapted to perform several tasks. Among other things, it allows the user to:
+
+* Customize configuration preferences for optimizing workflow for
+  segmentation or classification tasks, including:
+  * Task Selection (Segmentation and/or Classification)
+  * Modality to be viewed/process/annotated (CT or MRI)
+    * (Must one or the other for now. Does not currently take DICOM images)
+  * Brain Imaging Data Structure (BIDS) format imposition (test quickly if a 
+    dataset respects the BIDS convention through a BIDS-validator script: 
+    makes unable to load a dataset if it does not respect BIDS format)
+  * View to be displayed by default in the Slicer viewer (e.g. 
+    axial, sagittal, etc.)
+  * Interpolation of images (by default, Slicer images that are displayed 
+    get "interpolated" (i.e. smoother): with SlicerCART, you can select this 
+    option that can be relevant for segmentation tasks)
+  * For CT-Scans:
+    * Specify the range of Houndsfield units for which a segmentation mask 
+      will be feasible (e.g. 45 to 90): otherwise, segmentation mask will 
+      not be created.
+  * Customize keyboard shortcuts
+  * Customize mouse button functions
+  * Configure from the GUI the segmentation labels, 
+    including:
+    * Label name
+    * Label value
+    * Color
+    * Adding/Removal of labels
+  * Select if timer should be displayed during segmentation task
+  * Configure from the GUI the classification labels, 
+    including adding/Removal of:
+    * Labels 
+    * Checkbox 
+    * DropDown Menu with choice selection
+    * Text field
+  * (Specify to save all segments to one file or multiple files)TO DO
+* Identify the name, degree and revision step related to the human annotator
+* Select folder of interest where volumes are saved (and possibly impose BIDS)
+  * Displays automatically the PATH of the loaded volume
+* Select the output folder where processing and work is preferred to be saved
+* (Select a ground-truth folder where references studies can be used for 
+  iterative self-assessment)TO COME
+* Display in the GUI a case list of all the studies of interests for the segmentation task (*from a site directory or a customized list)
+* Select from the GUI case list any volume of interest to display
+* Navigate through case list from next and previous buttons
+* (Load automatically the first remaining case for segmentation in a 
+  customized list)TO COME
+* Create automatically all required segments that may be used according to the project configuration each time a volume is displayed
+* From the Segmentation window:
+  * Open quickly the Segment Editor
+  * Start Painting for the first label
+  * Erase any part of visible masks
+  * Select Lasso Paint (fills the space of a contour-based geometrical 
+    annotation)
+  * (Place a measurement line) TO COMPLETE
+* Toggle interpolation of the volume loaded
+* Execute multiple automated functions when saving segmentation masks for a given volume. Indeed, the automated functions:
+  * Save segmentation masks in the selected output folder with volume file hierarchy
+  * Track the different versions (save the following version if previous version(s) already exist(s)) **N.B. limitation to 99 versions for a single volume*
+  * Save a .csv file with segmentation statistics (e.g. subject, annotator's name and degree, revision step, date and time, total duration, duration of each label annotation)
+  * Save a .csv file with classification statistics (e.g. subject, annotator's name and degree, revision step, date and time, checkboxes / dropdown / free text fields)
+  * (Go to the next remaining case and make it ready to segment without any 
+    further action)TO COME
+* Load a pre-existing segmentation for further modification (will be saved as a new version of the segmentation)
+* Compare different versions of segmentation TO COMPLETE
+  * Specify versions to be loaded at the same time
+  * Display multiple versions of segmentation masks at the same time
+  * Modify specific segments of different versions
+  * Save all segments displayed +- modified on the viewer as a version += 1 
+    of segments in the output folder
+
+[GO BACK on Documentation Welcome Page](welcome.md).
+[Go BACK to User Guide](userguide.md).
+[CONTINUE to Purpose](purpose.md). 
diff --git a/SlicerCART/documentation/images/continue_segmentation.png b/SlicerCART/documentation/images/continue_segmentation.png
diff --git a/SlicerCART/documentation/images/example_loading_cases_ui.png b/SlicerCART/documentation/images/example_loading_cases_ui.png
diff --git a/SlicerCART/documentation/images/folder_and_name_to_use.png b/SlicerCART/documentation/images/folder_and_name_to_use.png
diff --git a/SlicerCART/documentation/images/module_filepath.png b/SlicerCART/documentation/images/module_filepath.png
diff --git a/SlicerCART/documentation/images/perform_segmentation.png b/SlicerCART/documentation/images/perform_segmentation.png
diff --git a/SlicerCART/documentation/images/save_segmentation.png b/SlicerCART/documentation/images/save_segmentation.png
diff --git a/SlicerCART/documentation/images/select_configuration_module.png b/SlicerCART/documentation/images/select_configuration_module.png
diff --git a/SlicerCART/documentation/images/select_configuration_popup.png b/SlicerCART/documentation/images/select_configuration_popup.png
diff --git a/SlicerCART/documentation/images/select_output_folder.png b/SlicerCART/documentation/images/select_output_folder.png
diff --git a/SlicerCART/documentation/images/select_volume_to_segment.png b/SlicerCART/documentation/images/select_volume_to_segment.png
diff --git a/SlicerCART/documentation/images/start_segmentation.png b/SlicerCART/documentation/images/start_segmentation.png
diff --git a/SlicerCART/documentation/installation.md b/SlicerCART/documentation/installation.md
@@ -0,0 +1,71 @@
+# SlicerCART Installation
+
+## Requirements
+
+* MacOS Sonoma or Sequoia (15.0.1) is recommended 
+* A working version of [3D Slicer](https://download.slicer.org) (version 5.6.2).
+* Qt: might need to be installed.
+  * The first five steps of the following procedure might be useful for this: [procedure](https://web.stanford.edu/dept/cs_edu/resources/qt/install-mac).
+  * You can try importing Qt in the Slicer python console (e.g. `import slicer ` then `from slicer.util import Qt`)
+
+*Although it may work on other versions and/or operating system, please note 
+that it has not been tested.
+
+If 3D Slicer has not been already installed, you can follow these steps: 
+1. Install [3D Slicer](https://download.slicer.org):
+2. Make sure that you are able to open and use the 3D Slicer software before 
+   trying installing any extension/module. 
+3. If you encounter some problems, you are encouraged to refer to:
+   * [3D Slicer Documentation](https://slicer.readthedocs.io/en/latest/)
+   * [3D Slicer forum](https://discourse.slicer.org/) (very active community)
+
+## Installation Steps
+
+1. Clone the [SlicerCART repository](https://github.com/neuropoly/slicer-manual-annotation) in the location of your choice.
-1. Clone the [SlicerCART repository](https://github.com/neuropoly/slicer-manual-annotation) in the location of your choice.
+1. Open a terminal and clone the [SlicerCART repository](https://github.com/neuropoly/slicer-manual-annotation) by taping the following command: 
+```bash 
+git clone https://github.com/neuropoly/slicer-manual-annotation.git
-1. Clone the [SlicerCART repository](https://github.com/neuropoly/slicer-manual-annotation) in the location of your choice.
+1. Open a terminal and clone the [SlicerCART repository](https://github.com/neuropoly/slicer-manual-annotation) by taping the following command: 
+```bash 
+git clone https://github.com/neuropoly/slicer-manual-annotation.git
+2. Open 3D Slicer. 
+3. Activate the checkbox `Enable developer mode` in `Edit 
+   -> Application 
+    Settings -> Developer -> Enable developer mode`. 
+4. Open Finder (on macOS). Go to the location of the SlicerCART Repository. 
+   Go to the location of the python file `SlicerCART.py` (_should only have one 
+   FILE of that name. Note that if you add the path of the folder SlicerCART,
+   it will not work: you MUST add the path of SlicerCART.py FILE_)  in `Edit -> Application Settings 
+   -> Modules -> Additional module paths`. See image example below:
-4. Open Finder (on macOS). Go to the location of the SlicerCART Repository. 
-   Go to the location of the python file `SlicerCART.py` (_should only have one 
-   FILE of that name. Note that if you add the path of the folder SlicerCART,
-   it will not work: you MUST add the path of SlicerCART.py FILE_)  in `Edit -> Application Settings 
-   -> Modules -> Additional module paths`. See image example below:
+4. Open Finder (on macOS). Go to the location of the slicer-manual-annotation Repository (where you cloned the github). 
+   Then find the file  `SlicerCART.py` under `slicer-manual-annotation/SlicerCART/src/SlicerCART.py. 
+   After that open in Slicer 3D  `Edit -> Application Settings 
+   -> Modules ` and drag and drop SlicerCART.py in the `Additional module paths` box. See image example below:
-4. Open Finder (on macOS). Go to the location of the SlicerCART Repository. 
-   Go to the location of the python file `SlicerCART.py` (_should only have one 
-   FILE of that name. Note that if you add the path of the folder SlicerCART,
-   it will not work: you MUST add the path of SlicerCART.py FILE_)  in `Edit -> Application Settings 
-   -> Modules -> Additional module paths`. See image example below:
+4. Open Finder (on macOS). Go to the location of the slicer-manual-annotation Repository (where you cloned the github). 
+   Then find the file  `SlicerCART.py` under `slicer-manual-annotation/SlicerCART/src/SlicerCART.py. 
+   After that open in Slicer 3D  `Edit -> Application Settings 
+   -> Modules ` and drag and drop SlicerCART.py in the `Additional module paths` box. See image example below:
+![](images/module_filepath.png)
+
+(N.B. 1- You must drag the file SlicerCART.py in the additionnal module path section: 
+   if you drag the folder path (SlicerCART folder), then the module will not work; 2- in the 
+   Additional modul path section, you will see the module folder path and not the SlicerCART.py file path: this is a 
+Slicer thing, and should not affect working property of 
+   the module if it was the file that you copied).
+
+5. The Application will ask to Restart: click Ok.
+![](images/example_restart.png)
+
+6. The module can be found under `Examples -> SlicerCART`: the module should 
+   now be opened (N.B. If first use, you may have additional requirements 
+   to install. A pop-up window from Slicer advertising you should pop-up if so: just click ok).
+![](images/example_slicercart.png)
+
+
+8. (Optional) Set the SlicerCART module to launch at 3DSlicer startup. To do so, go to `Edit -> Application Settings -> Modules -> Default startup module`
+9. There might be errors. These would be seen in the Python Console: if any errors, we highly recommend you to fix them before any further use!
+
+**In Summary:**
+
+Install 3D Slicer --- Enable Developer Mode --- Add the PATH of SlicerCART.
+py file in the modules list --- (Optional) Select to launch SlicerCART at 3D 
+Slicer --- restart 3D Slicer --- READY FOR USE!
+
+![](images/module_filepath.png)
+
+
+### Troubleshooting 
+
+* Qt might need to be installed. The first five steps of the following procedure might be useful for this: [procedure](https://web.stanford.edu/dept/cs_edu/resources/qt/install-mac).
+
+### Other extensions that could be useful
+* `SlicerJupyter` to be able to use Jupyter Notebooks connected to 3D Slicer.
+
+[GO BACK on Documentation Welcome Page](welcome.md). 
+[CONTINUE to QuickStart](quickstart.md).
diff --git a/SlicerCART/documentation/purpose.md b/SlicerCART/documentation/purpose.md
@@ -0,0 +1,16 @@
+# SlicerCART Purpose
+
+This section explains the rationale behind SlicerCART and its purpose.
+
+
+**Rationale:**
+
+* Manual segmentation and classification tasks are required in the research setting related to medical imaging artificial intelligence tool development
+* An open-source solution for such tasks would better benefit the research setting
+* Actual open-source solutions that enable imaging viewing and annotation are not optimal from an end-user standpoint (especially from various background), increasing the already high burden of manual segmentation and classification tasks
+* A workflow aimed to efficiently navigate through a dataset while performing manual segmentation / correction, including revision steps and robust annotation consistency assessment is crucial for handling large amount of data and provide the best ground-truth references segmentation as possible. 
+
+[GO BACK on Documentation Welcome Page](welcome.md). 
+[GO BACK on List of Functionalities Page](functionalities.md). 
+[CONTINUE to Developer Guide](../../CONTRIBUTING.md).
+