Documentation updates (#562)

Documenation updates and final changes

Author: constantinpape

build_doc.py

@@ -1,6 +1,8 @@
 import argparse
 import glob
 import os
+import warnings
+
 from subprocess import run
 
 
@@ -16,7 +18,7 @@ def check_docs_completeness():
     all_doc_files = markdown_doc_files + rst_doc_files
     missing_from_docs = [f for f in all_doc_files if os.path.basename(f) not in micro_sam.__doc__]
     if len(missing_from_docs) > 0:
-        raise RuntimeError(
+        warnings.warn(
             "Documentation files missing! Please add include statements "
             "to the docstring in micro_sam/__init__.py for every file, eg:"
             "'.. include:: ../doc/filename.md'. "

doc/annotation_tools.md

@@ -8,31 +8,20 @@ of mitochondria in volume EM (middle) and interactive tracking of cells (right).
 <img src="https://github.com/computational-cell-analytics/micro-sam/assets/4263537/dfca3d9b-dba5-440b-b0f9-72a0683ac410" width="256">
 <img src="https://github.com/computational-cell-analytics/micro-sam/assets/4263537/aefbf99f-e73a-4125-bb49-2e6592367a64" width="256">
 
-The annotation tools can be started from the `micro_sam` GUI, the command line or from python scripts. The `micro_sam` GUI can be started by
-```
-$ micro_sam.annotator
-```
+The annotation tools can be started from the napari plugin menu, the command line or from python scripts.
+They are built as napari plugin and make use of existing napari functionality wherever possible. If you are not familiar with napari yet, [start here](https://napari.org/stable/tutorials/fundamentals/quick_start.html).
+The `micro_sam` tools mainly use [the point layer](https://napari.org/stable/howtos/layers/points.html), [shape layer](https://napari.org/stable/howtos/layers/shapes.html) and [label layer](https://napari.org/stable/howtos/layers/labels.html).
 
-They are built using [napari](https://napari.org/stable/) and [magicgui](https://pyapp-kit.github.io/magicgui/) to provide the viewer and user interface.
-If you are not familiar with napari yet, [start here](https://napari.org/stable/tutorials/fundamentals/quick_start.html).
-The `micro_sam` tools use [the point layer](https://napari.org/stable/howtos/layers/points.html), [shape layer](https://napari.org/stable/howtos/layers/shapes.html) and [label layer](https://napari.org/stable/howtos/layers/labels.html).
+The annotation tools are explained in detail below. We also provide [video tutorials](TODO).
 
-The annotation tools are explained in detail below. In addition to the documentation here we also provide [video tutorials](https://www.youtube.com/watch?v=ket7bDUP9tI&list=PLwYZXQJ3f36GQPpKCrSbHjGiH39X4XjSO).
+The annotation tools can be started from the napari plugin menu:
+<img src="https://raw.githubusercontent.com/computational-cell-analytics/micro-sam/master/doc/images/napari-plugin.png">
 
 
-## Starting via GUI
-
-The annotation toools can be started from a central GUI, which can be started with the command `$ micro_sam.annotator` or using the executable [from an installer](#from-installer).
-
-In the GUI you can select with of the four annotation tools you want to use:
-<img src="https://raw.githubusercontent.com/computational-cell-analytics/micro-sam/master/doc/images/micro-sam-gui.png">
-
-And after selecting them a new window will open where you can select the input file path and other optional parameter. Then click the top button to start the tool. **Note: If you are not starting the annotation tool with a path to pre-computed embeddings then it can take several minutes to open napari after pressing the button because the embeddings are being computed.**
-
 ## Annotator 2D
 
 The 2d annotator can be started by
-- clicking `2d annotator` in the `micro_sam` GUI.
+- clicking `Annotator 2d` in the plugin menu.
 - running `$ micro_sam.annotator_2d` in the command line. Run `micro_sam.annotator_2d -h` for details.
 - calling `micro_sam.sam_annotator.annotator_2d` in a python script. Check out [examples/annotator_2d.py](https://github.com/computational-cell-analytics/micro-sam/blob/master/examples/annotator_2d.py) for details. 
 
@@ -56,14 +45,13 @@ It contains the following elements:
 
 Note that point prompts and box prompts can be combined. When you're using point prompts you can only segment one object at a time. With box prompts you can segment several objects at once.
 
-Check out [this video](https://youtu.be/ket7bDUP9tI) for a tutorial for the 2d annotation tool.
+Check out [this video](TODO) for a tutorial for the 2d annotation tool.
 
-We also provide the `image series annotator`, which can be used for running the 2d annotator for several images in a folder. You can start by clicking `Image series annotator` in the GUI, running `micro_sam.image_series_annotator` in the command line or from a [python script](https://github.com/computational-cell-analytics/micro-sam/blob/master/examples/image_series_annotator.py).
 
 ## Annotator 3D
 
 The 3d annotator can be started by
-- clicking `3d annotator` in the `micro_sam` GUI.
+- clicking `Annotator 3d` in the plugin menu.
 - running `$ micro_sam.annotator_3d` in the command line. Run `micro_sam.annotator_3d -h` for details.
 - calling `micro_sam.sam_annotator.annotator_3d` in a python script. Check out [examples/annotator_3d.py](https://github.com/computational-cell-analytics/micro-sam/blob/master/examples/annotator_3d.py) for details.
 
@@ -81,12 +69,13 @@ Most elements are the same as in [the 2d annotator](#annotator-2d):
 
 Note that you can only segment one object at a time with the 3d annotator.
 
-Check out [this video](https://youtu.be/PEy9-rTCdS4) for a tutorial for the 3d annotation tool.
+Check out [this video](TODO) for a tutorial for the 3d annotation tool.
+
 
 ## Annotator Tracking
 
 The tracking annotator can be started by
-- clicking `Tracking annotator` in the `micro_sam` GUI.
+- clicking `Annotator Tracking` in the plugin menu.
 - running `$ micro_sam.annotator_tracking` in the command line. Run `micro_sam.annotator_tracking -h` for details.
 - calling `micro_sam.sam_annotator.annotator_tracking` in a python script. Check out [examples/annotator_tracking.py](https://github.com/computational-cell-analytics/micro-sam/blob/master/examples/annotator_tracking.py) for details. 
 
@@ -105,7 +94,20 @@ Most elements are the same as in [the 2d annotator](#annotator-2d):
 
 Note that the tracking annotator only supports 2d image data, volumetric data is not supported.
 
-Check out [this video](https://youtu.be/Xi5pRWMO6_w) for a tutorial for how to use the tracking annotation tool.
+Check out [this video](TODO) for a tutorial for how to use the tracking annotation tool.
+
+
+## Image Series Annotator
+
+TODO
+
+We also provide the `image series annotator`, which can be used for running the 2d annotator for several images in a folder. You can start by clicking `Image series annotator` in the GUI, running `micro_sam.image_series_annotator` in the command line or from a [python script](https://github.com/computational-cell-analytics/micro-sam/blob/master/examples/image_series_annotator.py).
+
+
+## Finetuning Tool
+
+TODO
+
 
 ## Tips & Tricks
 

doc/images/2d-annotator-menu.png

@@ -2,8 +2,8 @@
 
 There are three ways to install `micro_sam`:
 - [From mamba](#from-mamba) is the recommended way if you want to use all functionality.
-- [From source](#from-source) for setting up a development environment to use the latest version and be able to change and contribute to our software.
-- [From installer](#from-installer) to install without having to use mamba (supported platforms: Windows and Linux, only for CPU users). 
+- [From source](#from-source) for setting up a development environment to use the development version and to change and contribute to our software.
+- [From installer](#from-installer) to install it without having to use mamba (supported platforms: Windows and Linux, only for CPU users). 
 
 ## From mamba
 
@@ -17,21 +17,15 @@ You can follow the instructions [here](https://mamba.readthedocs.io/en/latest/in
 ```
 $ mamba install -c conda-forge micro_sam
 ```
-or you should create a new environment (here called `micro-sam`) via:
+or you can create a new environment (here called `micro-sam`) with it via:
 ```
 $ mamba create -c conda-forge -n micro-sam micro_sam
 ```
 if you want to use the GPU you need to install PyTorch from the `pytorch` channel instead of `conda-forge`. For example:
 ```
 $ mamba create -c pytorch -c nvidia -c conda-forge micro_sam pytorch pytorch-cuda=12.1
 ```
-You may need to change this command to install the correct CUDA version for your computer, see [https://pytorch.org/](https://pytorch.org/) for details.
-
-You also need to install napari to use the annotation tool:
-```
-$ mamba install -c conda-forge napari pyqt
-```
-(We don't include napari in the default installation dependencies to keep the choice of rendering backend flexible.)
+You may need to change this command to install the correct CUDA version for your system, see [https://pytorch.org/](https://pytorch.org/) for details.
 
 
 ## From source
@@ -64,32 +58,16 @@ $ mamba activate sam
 $ pip install -e .
 ```
 
-**Troubleshooting:**
-
-- Installation on MAC with a M1 or M2 processor:
-    - The pytorch installation from `environment_cpu.yaml` does not work with a MAC that has an M1 or M2 processor. Instead you need to:
-        - Create a new environment: `mamba create -c conda-forge python pip -n sam`
-        - Activate it va `mamba activate sam`
-        - Follow the instructions for how to install pytorch for MAC via conda from [pytorch.org](https://pytorch.org/).
-        - Install additional dependencies: `mamba install -c conda-forge napari python-elf tqdm`
-        - Install SegmentAnything: `pip install git+https://github.com/facebookresearch/segment-anything.git`
-        - Install `micro_sam` by running `pip install -e .` in this folder.
-    - **Note:** we have seen many issues with the pytorch installation on MAC. If a wrong pytorch version is installed for you (which will cause pytorch errors once you run the application) please try again with a clean `mambaforge` installation. Please install the `OS X, arm64` version from [here](https://github.com/conda-forge/miniforge#mambaforge).
-    - Some MACs require a specific installation order of packages. If the steps layed out above don't work for you please check out the procedure described [in this github issue](https://github.com/computational-cell-analytics/micro-sam/issues/77).
-
-
 ## From installer
 
 We also provide installers for Linux and Windows:
-- [Linux](https://owncloud.gwdg.de/index.php/s/hM1bQ108YmcwyDn)
-- [Windows](https://owncloud.gwdg.de/index.php/s/T1weJclOiYUUULE)
+- [Linux](TODO)
+- [Windows](TODO)
 <!---
 - [Mac](https://owncloud.gwdg.de/index.php/s/7YupGgACw9SHy2P)
 -->
 
-**The installers are still experimental and not fully tested.** Mac is not supported yet, but we are working on also providing an installer for it.
-
-If you encounter problems with them then please consider installing `micro_sam` via [mamba](#from-mamba) instead.
+The installers will not enable you to use a GPU, so if you have one then please consider installing `micro_sam` via [mamba](#from-mamba) instead. They will also not enable using the python library.
 
 **Linux Installer:**
 
@@ -102,6 +80,15 @@ To use the installer:
 - After the installation you can start the annotator with the command `.../micro_sam/bin/micro_sam.annotator`.
     - To make it easier to run the annotation tool you can add `.../micro_sam/bin` to your `PATH` or set a softlink to `.../micro_sam/bin/micro_sam.annotator`.
 
+**Windows Installer:**
+
+- Unpack the zip file you have downloaded.
+- Run the installer by double clicking on it.
+- Choose installation type: `Just Me(recommended)` or `All Users(requires admin privileges)`.
+- Choose installation path. By default it will be installed in `C:\Users\<Username>\micro_sam` for `Just Me` installation or in `C:\ProgramData\micro_sam` for `All Users`.
+	- The installer will unpack all micro_sam files to the installation directory.
+- After the installation you can start the annotator by double clicking on `.\micro_sam\Scripts\micro_sam.annotator.exe` or  with the command `.\micro_sam\Scripts\micro_sam.annotator.exe` from the Command Prompt.
+
 <!---
 **Mac Installer:**
 
@@ -112,12 +99,3 @@ https://www.makeuseof.com/how-to-disable-gatekeeper-mac/
 
 TODO detailed instruction
 -->
-
-**Windows Installer:**
-
-- Unpack the zip file you have downloaded.
-- Run the installer by double clicking on it.
-- Choose installation type: `Just Me(recommended)` or `All Users(requires admin privileges)`.
-- Choose installation path. By default it will be installed in `C:\Users\<Username>\micro_sam` for `Just Me` installation or in `C:\ProgramData\micro_sam` for `All Users`.
-	- The installer will unpack all micro_sam files to the installation directory.
-- After the installation you can start the annotator by double clicking on `.\micro_sam\Scripts\micro_sam.annotator.exe` or  with the command `.\micro_sam\Scripts\micro_sam.annotator.exe` from the Command Prompt.

doc/images/3d-annotator-menu.png

@@ -2,45 +2,41 @@
 
 Segment Anything for Microscopy implements automatic and interactive annotation for microscopy data. It is built on top of [Segment Anything](https://segment-anything.com/) by Meta AI and specializes it for microscopy and other bio-imaging data.
 Its core components are:
-- The `micro_sam` tools for interactive data annotation with [napari](https://napari.org/stable/).
+- The `micro_sam` tools for interactive data annotation, built as [napari](https://napari.org/stable/) plugin.
 - The `micro_sam` library to apply Segment Anything to 2d and 3d data or fine-tune it on your data.
-- The `micro_sam` models that are fine-tuned on publicly available microscopy data.
+- The `micro_sam` models that are fine-tuned on publicly available microscopy data and that are available on [BioImage.IO](https://bioimage.io/#/).
 
-Our goal is to build fast and interactive annotation tools for microscopy data, like interactive cell segmentation from bounding boxes:
+Based on these components `micro_sam` enables fast interactive and automatic annotation for microscopy data, like interactive cell segmentation from bounding boxes:
 
 ![box-prompts](https://github.com/computational-cell-analytics/micro-sam/assets/4263537/d04cb158-9f5b-4460-98cd-023c4f19cccd)
 
-`micro_sam` is under active development, but our goal is to keep the changes to the user interface and the interface of the python library as small as possible.
-On our roadmap for more functionality are:
-- Providing an installer for running `micro_sam` as a standalone application.
-- Releasing more and better finetuned models as well as the code for fine-tuning.
-- Integration of the finetuned models with [bioimage.io](https://bioimage.io/#/)
-- Implementing a napari plugin for `micro_sam`.
+`micro_sam` is now available as stable version 1.0 and we will not change its user interface significantly in the foreseeable future.
+We are still working on improving and extending its functionality. The current roadmap includes:
+- Releasing more and better finetuned models.
+- Integrating parameter efficient training and compressed models for faster fine-tuning.
+- Improving the 3D segmentation and tracking functionality.
 
-If you run into any problems or have questions please open an issue on Github or reach out via [image.sc](https://forum.image.sc/) using the tag `micro-sam` and tagging @constantinpape.
+If you run into any problems or have questions please [open an issue]() or reach out via [image.sc](https://forum.image.sc/) using the tag `micro-sam`.
 
 
 ## Quickstart
 
-You can install `micro_sam` via conda:
+You can install `micro_sam` via mamba:
 ```
-$ conda install -c conda-forge micro_sam napari pyqt
+$ mamba install -c conda-forge micro_sam
 ```
-We also provide experimental installers for all operating systems.
-For more details on the available installation options check out [the installation section](#installation).
+We also provide installers for Windows and Linux. For more details on the available installation options check out [the installation section](#installation).
 
-After installing `micro_sam` you can run the annotation tool via `$ micro_sam.annotator`, which opens a menu for selecting the annotation tool and its inputs.
-See [the annotation tool section](#annotation-tools) for an overview and explanation of the annotation functionality.
+After installing `micro_sam` you can start napari and select the annotation tool you want to use from `Plugins->Segment Anything for Microscopy`. Check out the [quickstart tutorial video](TODO) for a short introduction and  [the annotation tool section](#annotation-tools) for details.
 
-The `micro_sam` python library can be used via
+The `micro_sam` python library can be imported via
 ```python
 import micro_sam
 ```
-It is explained in more detail [here](#how-to-use-the-python-library).
-
-Our support for finetuned models is still experimental. We will soon release better finetuned models and host them on zenodo.
-For now, check out [the example script for the 2d annotator](https://github.com/computational-cell-analytics/micro-sam/blob/master/examples/sam_annotator_2d.py#L62) to see how the finetuned models can be used within `micro_sam`.
+It is explained in more detail [here](#using-the-python-library).
 
+We provide different finetuned models for microscopy that can be used within our tools or any other tool that supports Segment Anything. See [finetuned models](#finetuned-models) for details on the available models.
+You can also train models on your own data, see [here for details](#training-your-own-model).
 
 ## Citation