Skip to content

Commit fd7f1fe

Browse files
authored
Update README.md
1 parent ca09cad commit fd7f1fe

1 file changed

Lines changed: 46 additions & 21 deletions

File tree

README.md

Lines changed: 46 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -168,11 +168,11 @@ Or you can download the [Spotiflow_detection_template.groovy](src/main/resources
168168

169169
> [!IMPORTANT]
170170
> Lines starting with `//` are commented out and are not used. To enable those parameters, delete the `//`. To disable a parameter, add `//` at the start of the line.
171-
> Some exmaples as provided in the [announcement forum post](https://forum.image.sc/t/qupath-extension-spotiflow-is-now-available/115646)
172171
173172
### Getting all available arguments
174173

175174
All builder options that are implemented are documented [in the Javadoc](https://biop.github.io/qupath-extension-spotiflow/qupath/ext/biop/spotiflow/SpotiflowBuilder.html).
175+
Examples are provided in the [announcement forum post](https://forum.image.sc/t/qupath-extension-spotiflow-is-now-available/115646).
176176
You can pass additional options to `spotiflow` by adding `.addParameter()` before the `.build()` line.
177177

178178
To get the available additional arguments, call the help from the `spotiflow` object using `spotiflow.helpPredict()`
@@ -220,15 +220,14 @@ def pretrainedModel = 'hybiss'
220220
def spotiflow = Spotiflow.builder()
221221
.setPretrainedModelName(pretrainedModel)
222222
```
223-
<!--
223+
224224
## Training custom models
225225

226226
**Requirements**:
227227
A QuPath project with rectangles of class "Training" and "Validation" inside which the ground truth objects have been painted as annotations with no class.
228-
![Example Annotations for Training](files/cellpose-qupath-training-example.png)
229228

230229
> [!IMPORTANT]
231-
> Training requires _dense_ annotations. This means you cannot just annotate a few objects per Training and Valudation rectanble. You must annotate **ALL relevant objects** within each of those regions!
230+
> Training requires _dense_ annotations. This means you cannot just annotate a few objects per Training and Validation rectangle. You must annotate **ALL relevant objects** within each of those regions!
232231
233232
We typically create a standalone QuPath project for training only. This project will contain the training images along with the ground truth annotations drawn in QuPath.
234233
Here are some reasons we do it this way:
@@ -240,9 +239,9 @@ Here are some reasons we do it this way:
240239

241240
1. In your QuPath project create at least **2** rectangle annotations.
242241
2. In the Annotations tab, add new classes name "Training" and "Validation" and assign your rectangles to each of them. You do not need an equal number of Training and Validation rectangles.
243-
3. Lock the rectangles (right click > Annotations > Lock).
244-
4. Draw your ground truth annotations within all of the rectangles. You can also select each rectangle and run the `Cellpose detection script template` with the `.createAnnotations()` line
245-
not commented out in the builder (see *Prediction* instructions above) to use a pre-trained cellpose model as a start, but make sure you manually correct it to get proper ground truth!
242+
3. Lock the rectangles (`right click > Annotations > Lock`).
243+
4. Draw your ground truth annotations within all of the rectangles. <!--You can also select each rectangle and run the `Spotiflow detection script template` with the `.createAnnotations()` line
244+
not commented out in the builder (see *Prediction* instructions above) to use a pre-trained cellpose model as a start, but make sure you manually correct it to get proper ground truth!-->
246245

247246
> [!IMPORTANT]
248247
> Any ground truth annotations must have **no classes** assigned.
@@ -252,24 +251,29 @@ Here are some reasons we do it this way:
252251
> [!WARNING]
253252
> All images with Training or Validation annotations in the project will be used for the training.
254253
255-
Once you have your labeled Training and Validation rectangles with ground truth annotations, make sure you save your project! Then you can run the Cellpose training template script in
256-
`Extensions > Cellpose > Cellpose training script template`
254+
Once you have your labeled Training and Validation rectangles with ground truth annotations, make sure you save your project! Then you can run the Spotiflow training template script in
255+
`Extensions > Spotiflow > Spotiflow training script template`
257256

258-
Or you can download [Cellpose_training_template.groovy](src/main/resources/scripts/Cellpose_training_template.groovy) from this repo and run it from the script editor.
257+
Or you can download [Spotiflow_training_template.groovy](src/main/resources/scripts/Spotiflow_training_script_template.groovy) from this repo and run it from the script editor.
259258

259+
> [!IMPORTANT]
260+
> Lines starting with `//` are commented out and are not used. To enable those parameters, delete the `//`. To disable a parameter, add `//` at the start of the line.
261+
262+
<!--
260263
> [!NOTE]
261264
> In the line `def cellpose = Cellpose2D.builder("cyto")` you can choose to fine-tune a pre-trained model (e.g. cyto), train from scratch (enter "None"),
262265
> or start with a custom model (see below). Please see the *Prediction* instructions above for information regarding the other builder parameters.
266+
-->
263267

264-
The first thing the script will do is create a sub-folder in your project called `cellpose-training` containing sub-folders `test` and `train`, followed by exporting the image(s)
265-
that will be processed by `cellpose`. The `train` folder will contain images of your training rectangles and your annotations converted to masks. The `test` folder will contain the
266-
Validation data, which is also used by the `QC` script. If your Validation is not what you expect, you can check that the exported image(s) represent what you intended for `cellpose` to train on.
268+
The first thing the script will do is create a sub-folder in your project called `spotiflow-training` containing sub-folders `val` and `train`, followed by exporting the image(s)
269+
that will be processed by `spotiflow`. The `train` folder will contain images of your training rectangles and your annotations converted to masks. The `val` folder will contain the
270+
Validation data, which is also used by the `QC` script. If your Validation is not what you expect, you can check that the exported image(s) represent what you intended for `spotiflow` to train on.
267271

268272
Once the script successfully completes training, you will have a `models` sub-folder within your Project folder, which will contain your custom model, as well as a `QC` sub-folder with the output
269273
of the QC script.
270274

271275
Once you are happy with your training script, you should save the edited copy to your Project (or another scripts folder) for re-use!
272-
276+
<!--
273277
### Training a custom model
274278
To train using your custom model, you need to provide the path to the model to the `Cellpose2D.builder`. Just replace the name of the pre-trained model (e.g. `cyto`)
275279
with the path to your model, for example:
@@ -293,28 +297,49 @@ def cellpose = Cellpose2D.builder( pathModel )
293297
have not been transferred.
294298
295299
In case that this might be of use to you, please [open an issue](https://github.com/BIOP/qupath-extension-cellpose/issues).
300+
-->
301+
302+
### Getting all available training options
303+
304+
All builder options that are implemented are documented [in the Javadoc](https://biop.github.io/qupath-extension-spotiflow/qupath/ext/biop/spotiflow/SpotiflowBuilder.html).
305+
Examples are provided in the [announcement forum post](https://forum.image.sc/t/qupath-extension-spotiflow-is-now-available/115646).
306+
You can pass additional options to `spotiflow` by adding `.addParameter()` before the `.build()` line.
307+
308+
To get the available additional arguments, call the help from the `spotiflow` object using `spotiflow.helpTrain()`
309+
```
310+
def spotiflow = Spotiflow.builder()...build()
311+
spotiflow.helpTrain()
312+
```
313+
314+
### Fine-tuning a pre-trained models
315+
To fine-tune a pre-trained model, provide the name of this model to the `Spotiflow.builder` using `.setModelToFineTune()`
316+
```
317+
def pretrainedModel = 'general'
318+
def spotiflow = Spotiflow.builder()
319+
.setModelToFineTune(general)
320+
```
321+
296322

297323
### Training validation
298-
You can find a [run-cellpose-qc.py](QC/run-cellpose-qc.py) python script in the `QC` folder of this repository. This is
299-
an adaptation of the Quality Control part of a [ZeroCostDL4Mic Notebook that was made for cellpose](https://colab.research.google.com/github/HenriquesLab/ZeroCostDL4Mic/blob/master/Colab_notebooks/Beta%20notebooks/Cellpose_2D_ZeroCostDL4Mic.ipynb).
324+
You can find a [run-spotiflow-qc.py](QC/run-spotiflow-qc.py) python script in the `QC` folder of this repository.
300325

301326
Basically, when you train using this extension:
302327
1. It will first train your model as expected
303-
2. It will then run your newly trained cellpose model on your "Validation" images
304-
3. At the end, it will run the [run-cellpose-qc.py](QC/run-cellpose-qc.py) python script to output validation metrics.
328+
2. It will then run your newly trained spotiflow model on your "Validation" images
329+
3. At the end, it will run the [run-spotiflow-qc.py](QC/run-spotiflow-qc.py) python script to output validation metrics.
305330
4. The validation metrics will be saved into a folder called `QC` in your QuPath Project
306331

307332

308333
### Saving training results for publication purposes
309334

310335
In order to be as reproducible and sure of your results as possible, especially when it comes to publishing, these are
311336
our current guidelines:
312-
1. Use `saveBuilder()` which saves a JSON file of your CellposeBuilder, which can be reused with `CellposeBuilder(File builderFile)`. That way you will not lose the setting your did
313-
2. Save the `cellpose-training`, `QC` and `models` folders at the end of your training somewhere. This will contain everything that was made during training.
337+
1. Use `saveBuilder()` which saves a JSON file of your SpotiflowBuilder, which can be reused with `SpotiflowBuilder(File builderFile)`. That way you will not lose the setting your did
338+
2. Save the `spotiflow-training`, `QC` and `models` folders at the end of your training somewhere. This will contain everything that was made during training.
314339
3. Save the training script as well.
315340

316341

317-
-->
342+
318343
# Building
319344

320345
You can build the QuPath Spotiflow extension from source with

0 commit comments

Comments
 (0)