parvezamu commited on
Commit
dfb2159
·
verified ·
1 Parent(s): a10174c

Document pretrained stroke lesion model and Slicer NNUNet usage

Browse files
Files changed (1) hide show
  1. README.md +187 -0
README.md ADDED
@@ -0,0 +1,187 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # SlicerStrokeSegmentator
2
+
3
+ SlicerStrokeSegmentator is a 3D Slicer extension for automated chronic ischemic stroke lesion segmentation from T1-weighted brain MRI using nnU-Net v2.
4
+
5
+ The extension performs local inference using a five-fold ensemble of pretrained models and displays predicted lesion segmentations directly in 3D Slicer.
6
+
7
+ ![SlicerStrokeSegmentator screenshot](SlicerStrokeSegmentator/Resources/Screenshots/StrokeSegmentator.png)
8
+
9
+ ## Features
10
+
11
+ - Automated chronic ischemic stroke lesion segmentation.
12
+ - T1-weighted brain MRI input.
13
+ - Five-fold nnU-Net v2 ensemble.
14
+ - Local pretrained model directory selection.
15
+ - Automatic verification of model checkpoints.
16
+ - Model directory saved between Slicer sessions.
17
+ - Segmentation results displayed directly in 3D Slicer.
18
+ - CPU-based inference.
19
+
20
+ ## Requirements
21
+
22
+ - 3D Slicer (tested with version 5.12.4 on Linux).
23
+ - Compatible nnU-Net v2 installation in Slicer's Python environment.
24
+ - T1-weighted MRI registered to MNI152 1 mm isotropic space.
25
+ - Pretrained model weights obtained separately from the authors.
26
+ - Sufficient RAM and disk space for inference.
27
+
28
+ The extension currently uses CPU inference. Processing time depends on the computer hardware and input data.
29
+
30
+ ## Installation
31
+
32
+ The extension can be loaded into 3D Slicer from its source directory.
33
+
34
+ 1. Download or clone this repository.
35
+ 2. Open 3D Slicer.
36
+ 3. Load the SlicerStrokeSegmentator scripted module.
37
+ 4. Open the Stroke Segmentator module under Segmentation.
38
+ 5. Obtain the pretrained model weights from the authors.
39
+ 6. Extract the weights into a local directory.
40
+ 7. Click "Select Local Model Directory".
41
+ 8. Select the nnU-Net results root directory containing Dataset001_StrokeT1w.
42
+
43
+ The extension uses ~/stroke_model as its default model directory.
44
+
45
+ Installation through the Slicer Extension Manager is subject to acceptance into the Slicer ExtensionsIndex.
46
+
47
+ ## Model Directory Structure
48
+
49
+ The expected directory structure is:
50
+
51
+ stroke_model/
52
+ Dataset001_StrokeT1w/
53
+ nnUNetTrainerImprovedLossCheckpoints__nnUNetPlans__3d_fullres/
54
+ dataset.json
55
+ plans.json
56
+ fold_0/
57
+ checkpoint_final.pth
58
+ fold_1/
59
+ checkpoint_final.pth
60
+ fold_2/
61
+ checkpoint_final.pth
62
+ fold_3/
63
+ checkpoint_final.pth
64
+ fold_4/
65
+ checkpoint_final.pth
66
+
67
+ Select the stroke_model directory, not an individual trainer or fold directory.
68
+
69
+ ## Usage
70
+
71
+ 1. Open the Stroke Segmentator module.
72
+ 2. Load a T1-weighted MRI registered to MNI152 1 mm space.
73
+ 3. Select the MRI in the Input T1w selector.
74
+ 4. Select the local pretrained model directory if needed.
75
+ 5. Verify that all required model checkpoints are present.
76
+ 6. Click "Segment Stroke Lesion".
77
+ 7. Wait for inference to finish.
78
+ 8. The predicted lesion segmentation will appear in the Slicer scene.
79
+
80
+ The extension uses the custom nnU-Net trainer:
81
+
82
+ nnUNetTrainerImprovedLossCheckpoints
83
+
84
+ All five model folds are combined during prediction.
85
+
86
+ ## Public Testing Dataset - ATLAS v3.0 (629 Cases)
87
+
88
+ A collection of 629 publicly available ATLAS v3.0 T1-weighted brain MRI scans and their corresponding ground-truth stroke lesion masks is provided for testing SlicerStrokeSegmentator.
89
+
90
+ The collection includes:
91
+
92
+ - 329 newly released ATLAS v3.0 cases.
93
+ - 300 cases from the former ATLAS v2.0 validation dataset.
94
+
95
+ These 629 cases were not included in the original 655-case ATLAS v2.0 training dataset used to develop the segmentation model.
96
+
97
+ The images have been registered to MNI152 space for use with the segmentation pipeline. Users should verify that voxel spacing, image geometry, and preprocessing are compatible with the model.
98
+
99
+ ### Dataset Download
100
+
101
+ [Download ATLAS v3.0 - 629 Cases (Google Drive)](https://drive.google.com/drive/folders/1kgHygdB5PSDqj0ScFCj-nxuHOd5gPvXk?usp=sharing)
102
+
103
+ The dataset is organised into two folders:
104
+
105
+ ATLAS_v3.0/
106
+ input/
107
+ T1-weighted MRI scans
108
+ masks/
109
+ Ground-truth stroke lesion masks
110
+
111
+ The input folder contains the MRI scans, while the masks folder contains their corresponding reference lesion segmentations.
112
+
113
+ ### Testing Procedure
114
+
115
+ 1. Download a T1-weighted MRI from the input folder.
116
+ 2. Open 3D Slicer and select the Stroke Segmentator module.
117
+ 3. Load the MRI into Slicer.
118
+ 4. Select the pretrained model directory.
119
+ 5. Click "Segment Stroke Lesion".
120
+ 6. Wait until segmentation is complete.
121
+ 7. Load the corresponding ground-truth lesion mask from the masks folder.
122
+ 8. Compare the predicted segmentation with the reference mask.
123
+
124
+ Suggested evaluation metrics include:
125
+
126
+ - Dice similarity coefficient (DSC).
127
+ - Lesion-wise precision, recall, and F1-score.
128
+ - Hausdorff distance (HD95).
129
+ - Lesion volume difference.
130
+ - Segmentation failure rate.
131
+
132
+ These metrics require a separate evaluation procedure and are not automatically calculated by the extension.
133
+
134
+ ### Original Dataset Sources
135
+
136
+ ATLAS dataset download portal:
137
+ https://fcon_1000.projects.nitrc.org/indi/retro/atlas_download.html
138
+
139
+ ISLES'26 dataset information:
140
+ https://isles-26.grand-challenge.org/dataset/
141
+
142
+ The official ISLES'26 challenge evaluates algorithms using native-space MRI. The MNI152-registered testing collection described here is intended for testing this extension and is not an official ISLES'26 submission.
143
+
144
+ Users must comply with the original dataset's applicable access, attribution, and redistribution conditions.
145
+
146
+ ## Model Access
147
+
148
+ Pretrained model weights are not included in this repository.
149
+
150
+ The associated research manuscript is currently under preparation. Model weights may be provided to authorised researchers upon request, subject to applicable access conditions.
151
+
152
+ Contact:
153
+
154
+ - pahm409@aucklanduni.ac.nz
155
+ - parvezamu@gmail.com
156
+
157
+ The repository will be updated with information about model availability following publication arrangements.
158
+
159
+ ## Research and Clinical Use
160
+
161
+ This software is intended for research purposes only.
162
+
163
+ It is not established as a clinically validated diagnostic tool and should not be used independently for clinical diagnosis, treatment decisions, or patient management.
164
+
165
+ Segmentation accuracy may vary depending on MRI acquisition, preprocessing, registration quality, lesion characteristics, and differences between training and evaluation datasets.
166
+
167
+ ## Citation
168
+
169
+ Ahmad et al. Manuscript in preparation.
170
+
171
+ Auckland Bioengineering Institute,
172
+ University of Auckland,
173
+ New Zealand.
174
+
175
+ Please cite the associated publication when it becomes available and acknowledge the original ATLAS dataset publications when using the testing data.
176
+
177
+ ## Acknowledgements
178
+
179
+ HRC grant 21/144 IMPRESS.
180
+
181
+ ## License
182
+
183
+ The extension source code is released under the Apache License, Version 2.0.
184
+
185
+ See LICENSE.txt for the complete licence terms.
186
+
187
+ Pretrained model weights are distributed separately and may have different access and licensing conditions.