0.6.0 updates v3 (#124)

* instanseg

* intro and getting started

* Intro - concepts

* detailed release notes move

* todo removal

* hide instanseg and update extension manager images

* tips and tricks removal

* conflict resolve

* instanseg image removal

* Semantic line breaks, minor edits

* Minor edits

---------

Co-authored-by: Pete <[email protected]>

_static/css/custom.css

@@ -7,18 +7,52 @@
 }
 
 /* Prompt nav bar collapse at medium screen sizes to increase readability (https://stackoverflow.com/a/60217315/4539999) */
-@media screen and (max-width: 950px){
-	.wy-body-for-nav{background:#fcfcfc}
-	.wy-nav-top{display:block}
-	.wy-nav-side{left:-300px}
-	.wy-nav-side.shift{width:300px;left:0}
-	.wy-side-scroll{width:auto}
-	.wy-side-nav-search{width:auto}
-	.wy-menu.wy-menu-vertical{width:auto}
-	.wy-nav-content-wrap{margin-left:0}
-	.wy-nav-content-wrap
-	.wy-nav-content{padding:1.618em}
-	.wy-nav-content-wrap.shift{position:fixed;min-width:100%;left:300px;top:0;height:100%;overflow:hidden}
+@media screen and (max-width: 950px) {
+  .wy-body-for-nav {
+    background: #fcfcfc
+  }
+
+  .wy-nav-top {
+    display: block
+  }
+
+  .wy-nav-side {
+    left: -300px
+  }
+
+  .wy-nav-side.shift {
+    width: 300px;
+    left: 0
+  }
+
+  .wy-side-scroll {
+    width: auto
+  }
+
+  .wy-side-nav-search {
+    width: auto
+  }
+
+  .wy-menu.wy-menu-vertical {
+    width: auto
+  }
+
+  .wy-nav-content-wrap {
+    margin-left: 0
+  }
+
+  .wy-nav-content-wrap .wy-nav-content {
+    padding: 1.618em
+  }
+
+  .wy-nav-content-wrap.shift {
+    position: fixed;
+    min-width: 100%;
+    left: 300px;
+    top: 0;
+    height: 100%;
+    overflow: hidden
+  }
 }
 
 /* FIGURES */
@@ -29,6 +63,7 @@ figure {
 figcaption {
   margin-top: 10px;
 }
+
 p.caption {
   margin: 5px;
 }
@@ -104,7 +139,7 @@ p.caption {
   padding-top: 5%;
 }
 
-.video-divert .overlay p{
+.video-divert .overlay p {
   text-align: center;
 }
 
@@ -123,4 +158,4 @@ a:hover .overlay {
 
 .tool-icon {
   width: 3em;
-}
+}

docs/deep/index.md

@@ -5,6 +5,7 @@
 
 djl
 bioimage
+<!-- instanseg -->
 stardist
 wsinfer
 gpu

docs/deep/instanseg.md

@@ -0,0 +1,178 @@
+(instanseg-extension)=
+# InstanSeg
+
+The [InstanSeg QuPath extension](https://github.com/qupath/qupath-extension-instanseg) provides a new and improved way to perform segmentation of both cells and nuclei in QuPath using deep learning. It uses pre-trained models using the original [InstanSeg code](https://github.com/instanseg/instanseg).
+
+Developed by Thibaut Goldsborough and other members of the [QuPath group]() at The Edinburgh University.
+
+:::{admonition} Cite the paper!
+:class: warning
+If you use InstanSeg and/or this extension in a publication, please make sure to cite our paper.
+
+**For brighfield images:**
+
+Goldsborough, Thibaut, et al. InstanSeg: an embedding-based instance segmentation algorithm optimized for accurate, efficient and portable cell segmentation. *arXiv preprint* arXiv:2408.15954 (2024). <https://arxiv.org/abs/2408.15954>
+
+**For fluorescence images:**
+
+Goldsborough, Thibaut, et al. A novel channel invariant architecture for the segmentation of cells and nuclei in multiplexed images using InstanSeg. *bioRxiv* (2024): 2024-09. <https://www.biorxiv.org/content/10.1101/2024.09.04.611150v1>
+
+(And if you use it in combination with QuPath, be sure to [cite the QuPath paper too!](citing))
+:::
+
+## Requirements
+
+- QuPath [version 0.6](https://qupath.github.io/) (installation instructions [here](https://qupath.readthedocs.io/en/0.4/docs/intro/installation.html))
+- At least one whole slide image
+- [InstanSeg QuPath Extension](https://github.com/qupath/qupath-extension-instanseg)
+- Internet access to download models and pytorch if needed
+- - PyTorch (this can be downloaded while using the extension so don't worry about now)
+
+:::{tip}
+A GPU is not required but can dramatically speed up processing.
+If you have an NVIDIA GPU and want to use it with InstanSeg, you will need to install a version of CUDA compatible with PyTorch - please see {doc}`gpu`.
+:::
+
+## Set-up
+InstanSeg can be dragged and dropped into QuPath when its running. After this, restart QuPath and you should see the extension within the Extensions menu {menuselection}`Extensions --> InstanSeg`.
+The InstanSeg dialog will appear as shown below:
+
+:::{figure} images/instanseg.png
+:class: shadow-image small-image
+
+The InstanSeg user interface
+:::
+
+:::{note}
+Please note that you'll need internet access to start the extension and download the models and PyTorch if required.
+:::
+
+## Using InstanSeg
+
+### 1. Choose directory to store models
+
+Click on the folder icon to choose a directory to which either contains models you already have or just where you would like to save future download ones.
+
+### 2. Select a model
+
+Select the dropdown box to see the models available. Options with a cloud icon will need to be downloaded as they are not local to your machine. To do this select the model and click the download button to fetch them. If you have local models in your directory you can also select these from the dropdown box. Be sure to select the relevant model for the type of image you are working with (unless you are being experimental!). The model being used here is for brightfield images and is being used on a haematoxylin and dab stain but could be used on other stains.
+
+:::{note}
+Please note that internet in needed to download the models.
+:::
+
+### 3. Create or select an annotation
+
+Create an annotation or select a pre-existing annotations/tiles you wish to run the model on. It's recommended that if this is the first time running InstanSeg to keep the annotation smaller to test the processing speed before running it on a larger region. This might take some time, depending on your computers processing speed.
+
+### 4. Run the model
+
+When you select run, InstanSeg will check for PyTorch. If this is not on your machine it will download it for you (this may well be > 100 MB, so may take a while). Once this is done the model will run and you will see the results in the viewer.
+
+:::{figure} images/instanseg_running.png
+:class: shadow-image large-image
+
+The running the InstanSeg model
+:::
+
+### 5. Viewing Results
+
+The results will be displayed in the viewer. The cells detections can be turned on or off using the show/hide detection objects button in the toolbar. Additionally to help distinguished the cells an overlay can be placed over the cells using the fill/unfill detection objects button and the opacity adjusted using the slider also in the toolbar.
+
+:::{figure} images/instanseg_bf_results.png
+:class: shadow-image large-image
+
+The results of the InstanSeg model on a brightfield image.
+
+:::
+
+:::{figure} images/instanseg_fl_results.png
+:class: shadow-image large-image
+
+The results of the InstanSeg model on a fluorescence image.
+
+:::
+
+## Additional Options
+InstanSeg has quite a few options to adapt to your device and preferences. These can be seen below:
+
+:::{figure} images/instanseg_options.png
+:class: shadow-image small-image
+
+The additional options available in InstanSeg
+:::
+
+### Preferred Device
+The options available will depend upon your computer's capabilities (at least as far as they could be discerned by Deep Java Library):
+
+* **CPU**: This is generally the safest - and slowest - option, because it should be supported on all computers.
+* **MPS**: This stands for *Metal Performance Shaders*, and should be available on recent Apple silicon - it is the Mac version of GPU acceleration
+* **GPU**: This should appear if you have an NVIDIA GPU, CUDA... and a little bit of luck.
+
+If either MPS or GPU work for you, they should reduce the time required for inference by a *lot*.
+However configuration for GPU can be tricky, as it will depend upon other hardware and software on your computer - CUDA in particular.
+For more info, see {doc}`gpu`.
+
+:::{admonition} PyTorch & CUDA versions
+:class: tip
+
+The WSInfer extension is using Deep Java Library to manage its PyTorch installation.
+It won't automatically find any existing PyTorch you might have installed: Deep Java Library will download its own.
+
+If you have a compatible GPU, and want CUDA support, you'll need to ensure you have an appropriate CUDA installed *before* PyTorch is downloaded.
+:::
+
+### Threads
+
+This is the number of CPU/GPU threads to use to fetch and submit image tiles. 1 is usually to little and high numbers may not be beneficial. We suggest between 2-4 hence why this is the default.
+
+### Tile Size
+
+Large annotations are broken up into lots of tiles to be processed as doing it all at once may cause memory issues. Usually 512 or 1024 pixels is a good size.
+
+### Tile Padding
+
+When the tiles are created, they overlap each other by a certain amount to ensure the cells are not clipped between the boundaries. Tile padding allows you to choose how much to overlap by with small padding being faster but more likely to result in clipping. If this occurs then increase the value and run again.
+
+### Input Channels
+
+Quite simply the number of channels be used by the model. Some models have a fixed number and others dont care. Its possible to use a fluorescence model on a brightfield image by using color deconvolution "stains" as channels however results may vary.
+
+### Output
+
+This determined whether the model outputs nuclei or cell membranes or both. Some models allow for both and can be used in various combinations but others are specific to one or the other.
+
+### Make measurements
+
+Following detection some measurements are created for each nuclei/cell but this isn't always required so can be toggled off.
+
+### Random colors
+
+This will assign a random color to each detection object to help distinguish them which can be useful for distinguishing between neighbouring objects.
+
+## Scripting
+
+If you want to use InstanSeg in a script, you can use either use the [workflows to scripts](https://qupath.readthedocs.io/en/stable/docs/scripting/workflows_to_scripts.html) method if you have already run a model. 
+Alternatively, you can use the following script as a template:
+
+```groovy
+qupath.ext.instanseg.core.InstanSeg.builder()
+    .modelPath("/path/to/some/model")
+    .device("mps")
+    .nThreads(4)
+    .tileDims(512)
+    .interTilePadding(32)
+    .inputChannels([ColorTransforms.createChannelExtractor("Red"), ColorTransforms.createChannelExtractor("Green"), ColorTransforms.createChannelExtractor("Blue")])
+    .outputChannels()
+    .makeMeasurements(true)
+    .randomColors(false)
+    .build()
+    .detectObjects()
+```
+
+## Citing
+
+If you use this extension in any published work, we ask you to please cite
+
+1. At least one of the two InstanSeg preprints above (whichever is most relevant)
+2. The main QuPath paper - details [here](https://qupath.readthedocs.io/en/stable/docs/intro/citing.html)

docs/deep/wsinfer.md

@@ -121,13 +121,15 @@ If you have a compatible GPU, and want CUDA support, you'll need to ensure you h
 
 ## Using your own models
 
-In addition to models downloaded from the WSInfer zoo, you may also use your own models by putting them in a specific local directory called `user` or `local`. This in turn should be put into the model directory (the path can be seen in the WSI dialog) as a sibling of the `kaczmarj` directory that contains the downloaded models.
+In addition to models downloaded from the WSInfer zoo, you may also use your own models by putting them in a specific local directory called `user` or `local`.
+This in turn should be put into the model directory (the path can be seen in the WSI dialog) as a sibling of the `kaczmarj` directory that contains the downloaded models.
 
 Inside the local models directory, every model should be contained in a subdirectory. The subdirectory name becomes the model name in the model selection menu.
 Inside it, there will be:
 
 - the model in Torchscript format, with the name `torchscript_model.pt`, and
-- a `config.json` file, as explained [here](https://wsinfer.readthedocs.io/en/latest/user_guide.html#use-your-own-model). An example of config file is shown [here](https://github.com/SBU-BMI/wsinfer/issues/221).
+- a `config.json` file, as explained [here](https://wsinfer.readthedocs.io/en/latest/user_guide.html#use-your-own-model).
+An example of config file is shown [here](https://github.com/SBU-BMI/wsinfer/issues/221).
 
 Thus, the structure of the models directory could be as follows:
 

docs/intro/about.md

@@ -2,7 +2,7 @@
 
 **QuPath is open source software for bioimage analysis.**
 
-QuPath is often used for **digital pathology** applications because it offers a powerful set of tools for working with **whole slide images** - but it can be applied to lots of other kinds of image as well.
+QuPath is often used for **digital pathology in research** because it offers a powerful set of tools for working with **whole slide images** - but it can be applied to lots of other kinds of image as well.
 
 Features include:
 
@@ -12,5 +12,6 @@ Features include:
 - Compatibility with other popular open tools, including ImageJ, OpenCV, Java Topology Suite and OMERO
 - Support for many image formats through Bio-Formats and OpenSlide, including whole slide images and multiplexed data
 - Groovy scripting for customization and deeper data interrogation
+- A growing number of extensions from the QuPath devs and others - adding even more features, algorithms & tools
 
 To find out more, check out the [original publication introducing QuPath](https://doi.org/10.1038/s41598-017-17204-5) or {doc}`dive into the tutorials <../tutorials/index>` to see some of what it can do.

docs/intro/extensions.md

@@ -18,6 +18,7 @@ We don't yet have a central list for extensions.
 The main places to find out about them are:
 
 * These docs --- some examples include:
+  <!-- * [Instanseg](instanseg-extension) -->
   * [StarDist](stardist-extension)
   * [WSInfer](wsinfer-extension)
   * [OMERO](omero-extension)
@@ -46,7 +47,7 @@ from your web browser onto QuPath's main window.
 A prompt should appear asking if you want to proceed, and if you do, QuPath will download the extension and install it for you, including some necessary configuration along the way.
 
 Alternatively, if you know the owner and name of the GitHub repository housing an extension, you can enter these in the extension manager and click the download button.
-Again, QuPath will ask if you wish to download and install the extension.
+Again, QuPath will ask if you wish to download and install the extension and present you with the versions currently available for that extension.
 
 If you don't have a user directory, QuPath will prompt you to select a folder on your computer to use.
 You can change it later under {menuselection}`Edit --> Preferences...` if you want to.
@@ -57,7 +58,13 @@ You can change it later under {menuselection}`Edit --> Preferences...` if you wa
 Installing the Deep Java Library extension using the extension manager
 :::
 
-If neither of these options work, you can try downloading the extension manually.
+:::{figure} images/extension_manager_installing_version.png
+:class: shadow-image mini-image
+
+An example of extension version options for WSInfer
+:::
+
+If both of these extension installation options don't work, you can try downloading the extension manually.
 The extension itself is a (usually small) file with that ends with `.jar`, often available from the `Releases` section of the GitHub repository.
 If you drag this onto QuPath's main window, QuPath should copy it to your QuPath user directory.
 
@@ -85,7 +92,7 @@ This will probably only work if QuPath isn't running.
 At this point, it's best to close QuPath and delete whichever extension files you don't want.
 
 :::{admonition} Did I install that?!
-:class: warning 
+:class: warning
 
 QuPath comes with several built-in extensions (for ImageJ, OpenSlide, Bio-Formats and more). These are found in the main QuPath installation, and not the regular extensions directory.
 These are each identified in the extension manager as a "Core extension (part of QuPath)".

docs/intro/formats.md

@@ -133,6 +133,10 @@ Consequently, although OpenSlide and Bio-Formats support many TIFF files, it is
 Perhaps the most common reason for this is that the file does not contain pyramidal layers, or these layers cannot be automatically recognized.
 This is one reason why well-supported, open formats should generally be preferred (e.g. OME-TIFF).
 
+#### OME-Zarr
+QuPath version 0.6.0 introduced support for reading and writing [OME-Zarr](https://link.springer.com/article/10.1007/s00418-023-02209-1) images.
+This file type was developed by the OME team in collaboration with many individuals and institutes to address the need for a scalable and cloud-friendly large image format.
+
 ## Open URI
 
 QuPath is not limited to working with image files stored locally.

docs/reference/faqs.md

@@ -25,16 +25,19 @@ If not, use [the QuPath discussion forum at image.sc](http://forum.image.sc/tags
 :::{tip}
 The following tips will improve your chances of receiving a useful answer on the forum.
 
-- Make sure you **use the \*qupath\* tag** with your post
+- Make sure you **use the `qupath` tag** with your post
 
-- **Be specific!** Broad questions lead to lots of guesswork and back-and-forth discussion to try to ascertain what you really want. Try to already include the key information in your first post.
+- **Be specific!** Broad questions lead to lots of guesswork and back-and-forth discussion to try to ascertain what you really want.
+Try to already include the key information in your first post.
 
 - If your question is about how to analyze your images:
 
-  - **Include screenshots and example images!** If you are not able to share your own image (e.g. you don't have permission), you can link to similar images online. Otherwise the discussion can be very long as people trying to help have to guess how your images look, and may be completely wrong.
+  - **Include screenshots and example images!** If you are not able to share your own image (e.g. you don't have permission), you can link to similar images online.
+  Otherwise the discussion can be very long as people trying to help have to guess how your images look, and may be completely wrong.
   - **Mention the QuPath version you are using**
   - **Describe clearly what you have already tried**
-  - **Describe what you want to achieve at the end** - *not* just any specific step you are stuck with. There might be a better/more efficient way to achieve your end goal that you haven't considered, making the awkward step unnecessary.
+  - **Describe what you want to achieve at the end** - *not* just any specific step you are stuck with.
+  There might be a better/more efficient way to achieve your end goal that you haven't considered, making the awkward step unnecessary.
 :::
 
 ### How do I report a bug?