You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: README.md
+124-44
Original file line number
Diff line number
Diff line change
@@ -56,25 +56,21 @@
56
56
57
57
<!-- ABOUT THE PROJECT -->
58
58
## Goal
59
+
The goal of this repository is to provide a seamless and efficient integration of your algorithm into the Grand Challenge platform. This repository offers a template for packaging your algorithm in a Docker container, ensuring compatibility with the input and output formats of the SynthRAD2023 challenge.
59
60
60
-
The source code for the participant algorithm container for
61
-
SynthRAD2023, generated with
62
-
evalutils version 0.3.1.
61
+
With this template, you can submit your algorithm (with minimal effort) to the test phases of the challenge (and optionally the validation phases). You can use the preliminary test phase to make sure everything is in order with your submission and get an initial estimate of your algorithms performance.
63
62
64
63
<!-- GETTING STARTED -->
65
64
## Getting Started
66
65
67
66
### Dependencies
68
67
69
-
The user should have access to Docker [https://docs.docker.com/].
70
-
The requirements, specified in `requirements.txt` are:
71
-
* evalutils v0.3.1
72
-
* scikit-learn v0.24.2
73
-
* scipy v1.6.3
74
-
* scikit-image v0.19.3
75
-
* SimpleITK
68
+
For building the algorithm for submission, the user should have access to Docker [https://docs.docker.com/] on their system. (Note: Submissions to the test phase are allowed only with docker containers)
76
69
77
-
### Installation
70
+
Please make sure to list the requirements for your algorithm in the `requirements.txt` file as this will be picked up when building the docker container.
Dummy data (randomly created scans) for testing the docker has already been provided in the `test` folder. It should be in the following format,
95
88
96
-
This will simulate the SynthRAD data structure with separate folders for`images`and`masks`,
97
-
each file has a naming convention of
89
+
```
90
+
algorithm-template
91
+
└── test
92
+
├── images
93
+
│ ├── body
94
+
│ │ └── 1BAxxx.nii.gz
95
+
│ └── mri
96
+
│ └── 1BAxxx.nii.gz
97
+
└── expected_output.json
98
+
```
98
99
99
-
`<Task><Region><Hospital><Id_number>.<Extension>`
100
+
`test/images` simulates the input data provided to the docker image while it is run on the test data by the Grand Challenge platform. `test/expected_output.json` is present to check if your algorithm provides the expected output on the inputs provided to it.
100
101
101
-
`Task`: 1 (mr to ct) or2 (cbct to ct)
102
102
103
-
`Region`: B (brain) or P (pelvis)
103
+
<!-- USAGE EXAMPLES -->
104
104
105
-
`Hospital`: A, B, C (Not allin every task/region)
105
+
## Usage
106
106
107
-
`Id_number`: 3 digits
107
+
First, run `test.sh`
108
108
109
-
`Extension`: `.nii.gz`
109
+
`test.sh` will build the docker container (which contains the algorithm), provide the `test` folder as input to the docker container and run the algorithm. The output of the algorithm will be placed in the `output` directory. Tests will also be run to check if the algorithm provides the expected output.
110
110
111
+
Note: It is recommended to run this before you integrate your own algorithm into the template.
111
112
112
-
<!--USAGEEXAMPLES-->
113
113
114
-
## Usage
114
+
### Using the template
115
+
To integrate your algorithm into this template, you need to modify the `predict` function of the `SynthradAlgorithm` in the `process.py` file.
You might need to load your models first before running the algorithm and this can be done in the `__init__` function of the `SynthradAlgorithm` class. For instance, to load a pytorch model,
Since the challenge contains two tasks, you will need to provide separate docker containers for each (even if you run the exact same algorithm on both). To configure which task your docker will be built for, we have provided a `.env` file. You can modify it before building the docker image and your docker will be built for the selected task.
142
+
```
143
+
TASK_TYPE="cbct" # Set to mri (Task 1) or cbct (Task 2)
144
+
INPUT_FOLDER="/input" # Do not change unless you want to test locally
145
+
```
146
+
147
+
Change the `TASK_TYPE` to "cbct" or "mri" depending on the task you want to make the submission for. Do not change the `INPUT_FOLDER` unless you are testing locally.
148
+
149
+
150
+
### Building and exporting the docker container with your new algorithm!
151
+
It is recommended to run `test.sh` first as it will ensure that your new algorithm always runs as expected.
115
152
116
-
1. Data is to be organized so that the input files to run the algorithm on are placed in the `test` folder in the same formatas the dummy generated data. Images are to be placed in the `images` folder and`masks` are to be placed in the masks folder. Corresponding image and mask should have the same name
153
+
1. Run the `export.sh` command. You can provide a name as the next argument to allow naming your docker containers.
154
+
Example: `./export.sh cbct_docker`
117
155
118
-
2. Run `test.sh`
156
+
2.You might need to wait a bit for this process to complete (depending on your model size and dependencies added by you) as it builds and saves the docker as `.tar.gz`. Once you have this `.tar.gz` file, you can submit it on the grand challenge portal in the SynthRAD submissions!
119
157
120
-
### Functions Descriptions
121
158
122
-
**test.sh**
159
+
Video will be uploaded very soon on how you can submit it on the GC portal!
123
160
124
-
description:
125
-
create the docker and run the algorithm-template
126
-
127
-
command line usage:
128
-
./test.sh
161
+
### Adding your own model files to the docker container
162
+
This step requires a bit of familiarity with the docker ecosystem as you will need to edit the `Dockerfile` to do so. The models will be embedded into the docker container allowing the docker to run independently on any system!
129
163
164
+
As a start, you can copy model files into the docker by adding something like this into the `Dockerfile`,
Once you do this, `your_model.pt` should be accessible in the `___init___` function as described above.
171
+
172
+
173
+
### Testing your algorithm locally.
174
+
In order to first test your algorithm locally (without the docker build process etc. - significantly speeds up over multiple iterations),
175
+
1. Configure `.env` for local mode by setting the `INPUT_FOLDER` to the path where you want to provide the inputs from. For instance, the `test` folder is a good starting place. But you could also provide your own data. (!!! NOTE: SET THE `INPUT_FOLDER` back to `/input` before your build the docker)
176
+
177
+
2. Run `python process.py` in an environment with all your dependencies installed.
178
+
179
+
180
+
This should run your algorithm locally and allow you to test different iterations before making a docker container.
130
181
131
182
183
+
### Reformatting your own data
184
+
In the `setup` folder, the `create_dummy_data.py` gives an example of how the dummy data is created for the docker container. You can reformat your own data in accordance to be run by the docker container.
185
+
186
+
For the MRI task, this is how the data should be organized.
0 commit comments