improved docs

docs/chapters/getting_started/quick_start.md

@@ -1,20 +1,20 @@
 # Quick Start
+There are three ways to use PlantSeg:
+* [Napari viewer](https://hci-unihd.github.io/plant-seg/chapters/plantseg_interactive_napari/) This is the most interactive way to use PlantSeg. It allows to run all the steps of the pipeline and visualize the results in a single using the [napari](https://napari.org/stable/) viewer. This is the recommended way to use PlantSeg on new data.
+* [Classic GUI](https://hci-unihd.github.io/plant-seg/chapters/plantseg_classic_gui/) This is the easiest way to use PlantSeg on large batches of data. It allows to configure and run all the steps of the pipeline. It is recommended to use this mode for high throughput processing and for running PlantSeg on a local machine.
+* [Command line](https://hci-unihd.github.io/plant-seg/chapters/plantseg_classic_cli/) This modality of using PlantSeg is particularly suited for high throughput processing and for running PlantSeg on a remote server. It allows to configure and run the pipeline using a configuration file.
 
-## Pipeline Usage (Napari viewer)
-PlantSeg app can also be started using napari as a viewer.
+## Quick start using the Napari viewer
 First, activate the newly created conda environment with:
 ```bash
 conda activate plant-seg
 ```
-
 then, start the plantseg in napari
 ```bash
 $ plantseg --napari
 ```
-A more in depth guide can be found in our [documentation (GUI)](https://hci-unihd.github.io/plant-seg/chapters/plantseg_interactive_napari/).
 
-## Pipeline Usage (GUI)
-PlantSeg app can also be started in a GUI mode, where basic user interface allows to configure and run the pipeline.
+## Quick start using the Classic GUI
 First, activate the newly created conda environment with:
 ```bash
 conda activate plant-seg
@@ -24,11 +24,8 @@ then, run the GUI by simply typing:
 ```bash
 $ plantseg --gui
 ```
-A more in depth guide can be found in our [documentation (Classic GUI)](https://hci-unihd.github.io/plant-seg/chapters/plantseg_classic_gui/).
-
-## Pipeline Usage (command line)
-Our pipeline is completely configuration file based and does not require any coding.
 
+## Quick start using the Command line
 First, activate the newly created conda environment with:
 ```bash
 conda activate plant-seg
@@ -37,6 +34,4 @@ then, one can just start the pipeline with
 ```bash
 plantseg --config CONFIG_PATH
 ```
-where `CONFIG_PATH` is the path to the YAML configuration file. See [config.yaml](examples/config.yaml) for a sample configuration
-file and our [documentation (CLI)](https://hci-unihd.github.io/plant-seg/chapters/plantseg_classic_cli/) for a
-detailed description of the parameters.
+where `CONFIG_PATH` is the path to the YAML configuration file. See [config.yaml](examples/config.yaml) for a sample configuration file.

docs/chapters/getting_started/steps.md

@@ -0,0 +1,25 @@
+# PlantSeg Pipeline Overview
+PlantSeg in a pipeline for 3D cell segmentation. At its core, PlantSeg implements a simple three-step pipeline:
+A pre-processing step, a CNN prediction step, and a segmentation step.
+
+## Pre-Processing
+The pre-processing step is used to prepare the input data for the CNN. There are two main operations that can be performed in the pre-processing step. The first is rescaling the input data to match the resolution of the data used for training the neural network. The second is filtering the input data to remove noise.
+
+## CNN Prediction
+The CNN prediction step uses a UNet architecture to predict boundaries. The UNet architecture is a popular architecture for image segmentation tasks. The UNet architecture is a fully convolutional network that is trained to predict boundaries. The UNet architecture is trained on a large dataset of images with known boundaries. The UNet architecture is trained to predict boundaries by minimizing the difference between the predicted boundaries and the true boundaries.
+
+## Segmentation
+The segmentation step implements powerful graph partitioning techniques to obtain a segmentation from the
+input stacks. If the predicted boundaries are not satisfactory, a raw image could be used (especially if the cell boundaries are very sharp, and the noise is low) but this usually does not yield satisfactory results.
+
+The **Algorithm** menu can be used to choose the segmentation algorithm. Available choices are:
+1. GASP (average): is a generalization of the classical hierarchical clustering. It usually delivers very
+reliable and accurate segmentation. It is the default in PlantSeg.
+2. MutexWS: Mutex Watershed is a derivative of the standard Watershed, where we do not need seeds for the
+    segmentation. This algorithm performs very well in certain types of complex morphology (like )
+3. MultiCut: in contrast to the other algorithms is not based on a greedy agglomeration but tries to find the
+optimal global segmentation. This is, in practice, very hard, and it can be infeasible for huge stacks.
+4. DtWatershed: is our implementation of the distance transform Watershed. From the input, we extract a distance map
+from the boundaries. Based this distance map, seeds are placed at local minima. Then those seeds are used for
+computing the Watershed segmentation. To speed up the computation of GASP, MutexWS, and MultiCut, an over-segmentation is obtained using Dt Watershed.
+5. Lifted Multicut: This method is based on the Multicut algorithm, but it uses a lifted edges to include addional priors from nuclei.

docs/chapters/plantseg_classic_cli/index.md

@@ -1,24 +1,22 @@
 # PlantSeg Classic CLI
 
 ## Guide to Custom Configuration File
+The configuration file is a YAML file that contains all the parameters needed to run the PlantSeg pipeline.
+Please refer to [config.yaml](../../../examples/config.yaml) for a sample pipeline configuration and a detailed explanation of all parameters. If you have any doubts on wha
 
-The configuration file defines all the operations in our pipeline together with the data to be processed.
-Please refer to [config.yaml](../../../examples/config.yaml) for a sample pipeline configuration and a detailed explanation
-of all parameters.
 
-## Main Keys/Steps
-* `path` attribute: is used to define either the file to process or the directory containing the data.
-* `preprocessing` attribute: contains a simple set of possible operations one would need to run on their data before calling the neural network.
-This step can be skipped if data is ready for neural network processing.
+### Configuration file structure
+The configuration file is divided into four main sections:
+* `path`: is used to define either the file to process or a directory. In the latter case, all files with a suitable extension will be processed.
+* `preprocessing`: in the preprocessing step, the input data is rescaled and filtered if needed. The rescaling factor can be computed as the resolution of the volume at hand divided by the resolution of the dataset used in training. Be careful, if the difference is too large check for a different model.
 Detailed instructions can be found at [Classic GUI (Data Processing)](https://hci-unihd.github.io/plant-seg/chapters/plantseg_classic_gui/data_processing.html).
-* `cnn_prediction` attribute: contains all parameters relevant for predicting with a neural network.
+* `cnn_prediction`: contains all parameters relevant for predicting with a neural network.
 Description of all pre-trained models provided with the package is described below.
 Detailed instructions can be found at [Classic GUI (Predictions)](https://hci-unihd.github.io/plant-seg/chapters/plantseg_classic_gui/cnn_predictions.html).
-* `segmentation` attribute: contains all parameters needed to run the partitioning algorithm (i.e., final Segmentation).
+* `segmentation`: contains all parameters needed to run the partitioning algorithm (i.e., final Segmentation).
 Detailed instructions can be found at [Classic GUI (Segmentation)](https://hci-unihd.github.io/plant-seg/chapters/plantseg_classic_gui/segmentation.html).
 
 ## Additional information
-
 The PlantSeg-related files (models, configs) will be placed inside your home directory under `~/.plantseg_models`.
 
 Our pipeline uses the PyTorch library for CNN predictions. PlantSeg can be run on systems without GPU, however
@@ -34,9 +32,10 @@ To use PlantSeg from command line mode, you will need to create a configuration
 
 Here is an example configuration:
 
-```
+```yaml
 path: /home/USERNAME/DATA.tiff # Contains the path to the directory or file to process
 
+# Step 1: Data Preprocessing
 preprocessing:
   # enable/disable preprocessing
   state: True
@@ -56,6 +55,7 @@ preprocessing:
     # sigma (gaussian) or disc radius (median)
     param: 1.0
 
+# Step 2: CNN Prediction
 cnn_prediction:
   # enable/disable UNet prediction
   state: True
@@ -73,6 +73,7 @@ cnn_prediction:
   # If "True" forces downloading networks from the online repos
   model_update: False
 
+# Step 2.5: CNN Postprocessing
 cnn_postprocessing:
   # enable/disable cnn post processing
   state: False
@@ -83,6 +84,7 @@ cnn_postprocessing:
   # spline order for rescaling
   order: 2
 
+# Step 3: Segmentation
 segmentation:
   # enable/disable segmentation
   state: True
@@ -108,6 +110,7 @@ segmentation:
   # set the minimum segment size in the final segmentation. (Not active for DtWatershed)
   post_minsize: 50
 
+# Step 3.5: Segmentation Postprocessing
 segmentation_postprocessing:
   # enable/disable segmentation post processing
   state: False
@@ -120,6 +123,7 @@ segmentation_postprocessing:
 ```
 This configuration can be found at [config.yaml](https://github.com/hci-unihd/plant-seg/blob/master/examples/config.yaml).
 
+
 ## Pipeline Usage (command line)
 To start PlantSeg from the command line:
 First, activate the newly created conda environment with:
@@ -132,7 +136,7 @@ plantseg --config CONFIG_PATH
 ```
 where `CONFIG_PATH` is the path to a YAML configuration file.
 
-## Results
+## Output directory structure
 
 The results are stored together with the source input files inside a nested directory structure.
 As an example, if we want to run PlantSeg inside a directory with two stacks, we will obtain the following

docs/chapters/plantseg_classic_gui/index.md

@@ -1,10 +1,5 @@
 # PlantSeg from GUI
-
-The graphical user interface is the easiest way to configure and run PlantSeg.
-Currently the GUI does not allow to visualize or interact with the data.
-We recommend using [MorphographX](https://www.mpipz.mpg.de/MorphoGraphX) or
-[Fiji](https://fiji.sc/) in order to assert the success and quality of the pipeline results.
-
+The graphical user interface is the easiest way to configure and run PlantSeg on multiple data.
 ![alt text](https://github.com/hci-unihd/plant-seg/raw/assets/images/plantseg_overview.png)
 
 ## File Browser Widget

docs/chapters/plantseg_classic_gui/segmentation.md

@@ -3,8 +3,7 @@
 The segmentation widget allows using very powerful graph partitioning techniques to obtain a segmentation from the
 input stacks.
 The input of this widget should be the output of the [CNN-predictions widget](https://hci-unihd.github.io/plant-seg/chapters/plantseg_classic_gui/cnn_predictions.html).
-If the boundary prediction stage fails for any reason, a raw image could be used (especially if the cell boundaries are
- very sharp, and the noise is low) but usually does not yield satisfactory results.
+If the boundary prediction stage fails for any reason, a raw image could be used (especially if the cell boundaries are very sharp, and the nose is low) but usually does not yield satisfactory results.
 
 * The **Algorithm** menu can be used to choose the segmentation algorithm. Available choices are:
     1. GASP (average): is a generalization of the classical hierarchical clustering. It usually delivers very

docs/chapters/plantseg_interactive_napari/index.md

@@ -1,3 +1,33 @@
 # PlantSeg Interactive - Napari
+The PlantSeg interactive mode is the most interactive way to use PlantSeg. It allows to run all the steps of the pipeline and visualize the results interactively using the [napari](https://napari.org/stable/) viewer. This is the recommended way to use PlantSeg on new data.
+
+## Overview
+In the Napari viewer, the PlantSeg pipeline is divided into 5 main tabs:
+1. **Input/Output**: This tab allows to load the input data and to save the results. Moreover contains a simple proofreading tool.
+2. **DataProcessing**: This tab allows to preprocess any layer of the input data. Contains all the standard preprocessing steps of PlantSeg, plus some additional steps such as cropping and merging layers.
+A detailed description of all the widgets in this tab can be found [here](https://hci-unihd.github.io/plant-seg/chapters/plantseg_interactive_napari/data_processing.md).
+3. **PlantSeg Main Workflow**: This tab contains the main PlantSeg pipeline. It allows to run the complete pipeline or to run any of the steps singularly.
+A detailed description of all the widgets in this tab can be found [here](https://hci-unihd.github.io/plant-seg/chapters/plantseg_interactive_napari/unet_gasp_workflow.md).
+4. **Extra Segmentation**: This tab contains additional segmentation algorithms that can be used in addition to the main pipeline.
+A detailed description of all the widgets in this tab can be found [here](https://hci-unihd.github.io/plant-seg/chapters/plantseg_interactive_napari/extra_seg.md).
+5. **Extra Predictions**: This tab contains a widget to add addiotional trained models to PlantSeg, and some experimental CNN predictions steps.
+A detailed description of all the widgets in this tab can be found [here](https://hci-unihd.github.io/plant-seg/chapters/plantseg_interactive_napari/extra_pred.md).
+
+## Quick start using the Napari viewer 
+First, activate the newly created conda environment with:
+```bash
+conda activate plant-seg
+```
+then, start the plantseg in napari
+```bash
+$ plantseg --napari
+```
+![alt text](https://github.com/hci-unihd/plant-seg/raw/assets/images/plantseg_napari.png)
+
+## Input/Output
+
+
+## Proofreading
+
+
 
-TODO