Merge pull request #162 from computational-cell-analytics/more-doc-updates

constantinpape · web-flow · commit cad7c8f344f0 · 2023-08-23T12:56:26.000+02:00
More doc updates
diff --git a/README.md b/README.md
@@ -27,6 +27,7 @@ conda install -c conda-forge micro_sam napari pyqt
 ```
 You can then start the `micro_sam` tools by running `$ micro_sam.annotator` in the command line.
 
+For an introduction in how to use the napari based annotation tools check out [the video tutorials](https://www.youtube.com/watch?v=ket7bDUP9tI&list=PLwYZXQJ3f36GQPpKCrSbHjGiH39X4XjSO&pp=gAQBiAQB).
 Please check out [the documentation](https://computational-cell-analytics.github.io/micro-sam/) for more details on the installation and usage of `micro_sam`.
 
 
diff --git a/doc/annotation_tools.md b/doc/annotation_tools.md
@@ -13,9 +13,22 @@ The annotation tools can be started from the `micro_sam` GUI, the command line o
 $ micro_sam.annotator
 ```
 
-They are built with [napari](https://napari.org/stable/) to implement the viewer and user interaction.
+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` applications are mainly based on [the point layer](https://napari.org/stable/howtos/layers/points.html), [the shape layer](https://napari.org/stable/howtos/layers/shapes.html) and [the label layer](https://napari.org/stable/howtos/layers/labels.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. In addition to the documentation here we also provide [video tutorials](https://www.youtube.com/watch?v=ket7bDUP9tI&list=PLwYZXQJ3f36GQPpKCrSbHjGiH39X4XjSO).
+
+
+## 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
 
@@ -44,7 +57,7 @@ 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/DfWE_XRcqN8) for an example of how to use the interactive 2d annotator.
+Check out [this video](https://youtu.be/ket7bDUP9tI) 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).
 
@@ -69,7 +82,7 @@ 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/5Jo_CtIefTM) for an overview of the interactive 3d segmentation functionality.
+Check out [this video](https://youtu.be/PEy9-rTCdS4) for a tutorial for the 3d annotation tool.
 
 ## Annotator Tracking
 
@@ -93,7 +106,7 @@ 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/PBPW0rDOn9w) for an overview of the interactive tracking functionality.
+Check out [this video](https://youtu.be/Xi5pRWMO6_w) for a tutorial for how to use the tracking annotation tool.
 
 ## Tips & Tricks
 
diff --git a/doc/images/micro-sam-gui.png b/doc/images/micro-sam-gui.png
diff --git a/doc/installation.md b/doc/installation.md
@@ -1,6 +1,11 @@
 # Installation
 
-`micro_sam` requires the following dependencies:
+We provide three different ways of installing `micro_sam`:
+- [From conda](#from-conda) is the recommended way if you want to use all functionality.
+- [From source](#from-source) for setting up a development environment to change and potentially contribute to our software.
+- [From installer](#from-installer) to install without having to use conda. This mode of installation is still experimental! It only provides the annotation tools and does not enable model finetuning.
+
+Our software requires the following dependencies:
 - [PyTorch](https://pytorch.org/get-started/locally/)
 - [SegmentAnything](https://github.com/facebookresearch/segment-anything#installation)
 - [elf](https://github.com/constantinpape/elf)
@@ -14,7 +19,7 @@
 $ conda install -c conda-forge micro_sam
 ```
 
-This command will only install the `micro_sam` library without the required dependencies for the annotation functionality and training.
+This command will not install the required dependencies for the annotation tools and for training / finetuning.
 To use the annotation functionality you also need to install `napari`:
 ```
 $ conda install -c conda-forge napari pyqt
@@ -27,40 +32,6 @@ $ conda install -c conda-forge torch_em
 In case the installation via conda takes too long consider using [mamba](https://mamba.readthedocs.io/en/latest/).
 Once you have it installed you can simply replace the `conda` commands with `mamba`.
 
-## From installer
-
-We also provide installers for Linux, Mac and Windows:
-- [Linux](https://owncloud.gwdg.de/index.php/s/Cw9RmA3BlyqKJeU)
-- [Mac](https://owncloud.gwdg.de/index.php/s/7YupGgACw9SHy2P)
-- [Windows](https://owncloud.gwdg.de/index.php/s/1iD1eIcMZvEyE6d)
-
-Note that these installers are stil experimental and not yet fully tested.
-If you encounter problems with them then please consider installing `micro_sam` via [conda](#from-conda) instead.
-
-**Linux Installer:**
-
-To use the installer:
-- Unpack the you have downloaded.
-- Make the installer executable: `$ chmod +x micro_sam-0.2.0post1-Linux-x86_64.sh`
-- Run the installer: `$./micro_sam-0.2.0post1-Linux-x86_64.sh$` 
-    - You can select where to install `micro_sam` during the installation. By default it will be installed in `$HOME/micro_sam`.
-    - The installer will unpack all `micro_sam` files to the installation directory.
-- 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`.
-
-**Mac Installer:**
-
-To use the Mac installer you will need to enable installing unsigned applications. Please follow [the instructions for 'Disabling Gatekeeper for one application only' here](https://disable-gatekeeper.github.io/).
-<!---
-Alternative link on how to disable gatekeeper.
-https://www.makeuseof.com/how-to-disable-gatekeeper-mac/
--->
-
-TODO detailed instruction
-
-**Windows Installer:**
-
-TODO
 
 ## From source
 
@@ -105,3 +76,48 @@ $ pip install -e .
         - 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 Linuxand Windows:
+- [Linux](https://owncloud.gwdg.de/index.php/s/Cw9RmA3BlyqKJeU)
+- [Windows](https://owncloud.gwdg.de/index.php/s/1iD1eIcMZvEyE6d)
+<!---
+- [Mac](https://owncloud.gwdg.de/index.php/s/7YupGgACw9SHy2P)
+-->
+
+**The installers are stil 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 [conda](#from-conda) instead.
+
+**Linux Installer:**
+
+To use the installer:
+- Unpack the zip file you have downloaded.
+- Make the installer executable: `$ chmod +x micro_sam-0.2.0post1-Linux-x86_64.sh`
+- Run the installer: `$./micro_sam-0.2.0post1-Linux-x86_64.sh$` 
+    - You can select where to install `micro_sam` during the installation. By default it will be installed in `$HOME/micro_sam`.
+    - The installer will unpack all `micro_sam` files to the installation directory.
+- 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`.
+
+<!---
+**Mac Installer:**
+
+To use the Mac installer you will need to enable installing unsigned applications. Please follow [the instructions for 'Disabling Gatekeeper for one application only' here](https://disable-gatekeeper.github.io/).
+
+Alternative link on how to disable gatekeeper.
+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.
