updated docs

Author: C-Achard

docs/index.rst

@@ -28,9 +28,11 @@ Welcome to napari-cellseg-3d's documentation!
     res/code/interface
     res/code/plugin_base
     res/code/plugin_review
+    res/code/launch_review
     res/code/plugin_dock
     res/code/plugin_crop
-    res/code/launch_review
+    res/code/plugin_convert
+    res/code/plugin_metrics
     res/code/model_framework
     res/code/model_workers
     res/code/model_instance_seg

docs/res/code/plugin_convert.rst

@@ -0,0 +1,21 @@
+plugin_convert.py
+==================================
+
+
+Class : ConvertUtils
+------------------------------------------
+
+.. important::
+    Inherits from : :doc:`plugin_base`
+
+Methods
+**********************
+.. autoclass:: napari_cellseg_3d.plugin_convert::ConvertUtils
+    :members:  __init__, build, folder_to_semantic, layer_to_semantic, folder_to_instance, layer_to_instance, layer_remove_small, folder_remove_small ,check_ready_folder, check_ready_layer    :noindex:
+    :noindex:
+
+Attributes
+*********************
+
+.. autoclass:: napari_cellseg_3d.plugin_convert::ConvertUtils
+   :members:  _viewer

docs/res/code/plugin_metrics.rst

@@ -0,0 +1,22 @@
+plugin_metrics.py
+==================================
+
+
+Class : MetricsUtils
+------------------------------------------
+
+.. important::
+    Inherits from : :doc:`plugin_base`
+
+Methods
+**********************
+
+.. autoclass:: napari_cellseg_3d.plugin_metrics::MetricsUtils
+   :members:  __init__, build, plot_dice, remove_plots, compute_dice
+   :noindex:
+
+Attributes
+*********************
+
+.. autoclass:: napari_cellseg_3d.plugin_metrics::MetricsUtils
+   :members:  _viewer, layout, canvas, plots

docs/res/guides/convert_module_guide.rst

@@ -15,4 +15,17 @@ You can :
     This will convert instance labels with unique IDs per object into 0/1 semantic labels, for example for training.
 
 * Remove small objects :
-    You can specify a size threshold in pixels; all objects smaller than this size will be removed in the image.
+    You can specify a size threshold in pixels; all objects smaller than this size will be removed in the image.
+
+
+Source code
+-------------------------------------------------
+
+* :doc:`../code/plugin_base`
+* :doc:`../code/plugin_convert`
+
+
+
+
+
+

docs/res/guides/inference_module_guide.rst

@@ -8,50 +8,61 @@ to automatically label cells.
 
 Currently, the following pre-trained models are available :
 
-===========   ================================================================================================
-Model         Link to original paper
-===========   ================================================================================================
-VNet          `Fully Convolutional Neural Networks for Volumetric Medical Image Segmentation`_
-SegResNet     `3D MRI brain tumor segmentation using autoencoder regularization`_
-TRAILMAP      An emulation in Pytorch of the `TRAILMAP project on GitHub`_
-===========   ================================================================================================
+==============   ================================================================================================
+Model            Link to original paper
+==============   ================================================================================================
+VNet             `Fully Convolutional Neural Networks for Volumetric Medical Image Segmentation`_
+SegResNet        `3D MRI brain tumor segmentation using autoencoder regularization`_
+TRAILMAP_test     An emulation of the `TRAILMAP project on GitHub`_ using a custom copy in Pytorch
+TRAILMAP          An emulation of the `TRAILMAP project on GitHub`_ using `3DUnet for Pytorch`_
+==============   ================================================================================================
 
 .. _Fully Convolutional Neural Networks for Volumetric Medical Image Segmentation: https://arxiv.org/pdf/1606.04797.pdf
 .. _3D MRI brain tumor segmentation using autoencoder regularization: https://arxiv.org/pdf/1810.11654.pdf
 .. _TRAILMAP project on GitHub: https://github.com/AlbertPun/TRAILMAP
+.. _3DUnet for Pytorch: https://github.com/wolny/pytorch-3dunet
 
 Interface and functionalities
 --------------------------------
 
 .. image:: ../images/inference_plugin_layout.png
     :align: right
+    :scale: 40%
 
-* Loading data : When launching the module, you will be asked to provide an image folder containing all the volumes you'd like to be labeled.
-  All images with the chosen (**.tif** or **.tiff** currently supported) extension in this folder will be labeled.
-  You can then choose an output folder, where all the results will be saved.
+* **Loading data** :
 
+  | When launching the module, you will be asked to provide an image folder containing all the volumes you'd like to be labeled.
+  | All images with the chosen (**.tif** or **.tiff** currently supported) extension in this folder will be labeled.
+  | You can then choose an output folder, where all the results will be saved.
 
 
-* Model choice : You can then choose one of the selected models above, which will be used for inference.
+* **Model choice** :
 
+  | You can then choose one of the provided models above, which will be used for inference.
+  | You may also choose to load custom weights rather than the pre-trained ones, simply ensure they are compatible (e.g. produced from the training module for the same model)
 
 
-* Anisotropy :If you want to see your results without anisotropy when you have anisotropic images, you can specify that you have anisotropic data
-  and set the resolution of your image in micron, this wil save & show the results without anisotropy.
+* **Anisotropy** :
 
+  | If you want to see your results without anisotropy when you have anisotropic images, you can specify that you have anisotropic data
+  | and set the resolution of your image in micron, this wil save and show the results without anisotropy.
 
 
-* Thresholding : You can perform thresholding to binarize your labels, all values beneath the confidence threshold will be set to 0 using this.
-  If you wish to use instance segmentation it is recommended to use threshlding.
+* **Thresholding** :
 
-* Instance segmentatin : You can convert the semantic segmentation into instance labels by using either the watershed or connected components method.
-  You can set the probability threshhold from which a pixel is considered as a valid instance, as well as the minimum size in pixels for objects. All smaller objects will be removed.
-  Instance labels will be saved (and shown if applicable) separately from other results.
+  | You can perform thresholding to binarize your labels, all values beneath the confidence threshold will be set to 0 using this.
+  | If you wish to use instance segmentation it is recommended to use thresholding.
 
-* Viewing results : You can also select whether you'd like to see the results in napari afterwards; by default the first image processed will be displayed,
-  but you can choose to display up to ten at once. You can also request to see the originals.
+* **Instance segmentation** :
 
+  | You can convert the semantic segmentation into instance labels by using either the watershed or connected components method.
+  | You can set the probability threshold from which a pixel is considered as a valid instance, as well as the minimum size in pixels for objects. All smaller objects will be removed.
+  | Instance labels will be saved (and shown if applicable) separately from other results.
 
+* **Viewing results** :
+
+  | You can also select whether you'd like to see the results in napari afterwards.
+  | By default the first image processed will be displayed, but you can choose to display up to ten at once. You can also request to see the originals.
 
 
 When you are done choosing your parameters, you can press the **Start** button to begin the inference process.
@@ -65,6 +76,7 @@ On the left side, a progress bar and a log will keep you informed on the process
     |    ``{original_name}_{model}_{date & time}_pred{id}.file_ext``
     | For example, using a VNet on the third image of a folder, called "somatomotor.tif" will yield the following name :
     |   *somatomotor_VNet_2022_04_06_15_49_42_pred3.tif*
+    | Instance labels will have the "Instance_seg" prefix appened to the name.
 
 
 .. hint::

docs/res/guides/metrics_module_guide.rst

@@ -25,4 +25,15 @@ Pairs with a low score will be displayed on the viewer for checking, ground trut
 .. note::
     Due to changes in orientation of images after running inference, the utility will rotate and flip images to find the best Dice coefficient
     to compensate. If you have small images with a very large number of labels, this can lead to an inexact metric being computed.
-    Images with a low score might be in the wrong orientation as well when displayed for comparison.
+    Images with a low score might be in the wrong orientation as well when displayed for comparison.
+
+
+Source code
+-------------------------------------------------
+
+* :doc:`../code/plugin_base`
+* :doc:`../code/plugin_metrics`
+
+
+
+

docs/res/guides/review_module_guide.rst

@@ -11,21 +11,23 @@ and correct them if needed. It then saves the status of each file in a csv, for
 Launching the review process
 ---------------------------------
 
-First, you will be asked to load your images and labels; you can use the checkbox above the Open buttons to
-choose whether you want to load a single 3D **.tif** image or a folder of 2D images as a 3D stack.
-Folders can be stacks of either **.png** or **.tif** files, ideally numbered with the index of the slice at the end.
+* Data paths :
+    First, you will be asked to load your images and labels; you can use the checkbox above the Open buttons to
+    choose whether you want to load a single 3D **.tif** image or a folder of 2D images as a 3D stack.
+    Folders can be stacks of either **.png** or **.tif** files, ideally numbered with the index of the slice at the end.
 
 .. note::
     Only single .tif files or folder of several .png or .tif are supported.
 
-You can then provide a model name, which will be used in the csv file recording the status of each slice.
+* Model name :
+    You can then provide a model name, which will be used to name the csv file recording the status of each slice.
 
-If a corresponding csv file exists already, it will be used. If not, a new one will be created.
+    If a corresponding csv file exists already, it will be used. If not, a new one will be created.
+    If you choose to create a new dataset, a new csv will be created no matter what,
+    with a trailing number if several copies of it already exists.
 
-If you choose to create a new dataset, a new csv will be created no matter what,
-with a trailing number if several copies of it already exists.
-
-Once you are ready, you can press **Run** to start the review process.
+* Start :
+    Once you are ready, you can press **Start reviewing** to start the review process.
 
 .. note::
     You can find the csv file containing the annotation status **in the same folder as the labels**

docs/res/guides/training_module_guide.rst

@@ -6,37 +6,56 @@ Training module guide
 This module allows you to train pre-defined Pytorch models for cell segmentation.
 Pre-defined models are stored in napari-cellseg-3d/models.
 
+Currently, the following pre-defined models are available :
+
+==============   ================================================================================================
+Model            Link to original paper
+==============   ================================================================================================
+VNet             `Fully Convolutional Neural Networks for Volumetric Medical Image Segmentation`_
+SegResNet        `3D MRI brain tumor segmentation using autoencoder regularization`_
+TRAILMAP_test     An emulation of the `TRAILMAP project on GitHub`_ using a custom copy in Pytorch
+TRAILMAP          An emulation of the `TRAILMAP project on GitHub`_ using `3DUnet for Pytorch`_
+==============   ================================================================================================
+
+.. _Fully Convolutional Neural Networks for Volumetric Medical Image Segmentation: https://arxiv.org/pdf/1606.04797.pdf
+.. _3D MRI brain tumor segmentation using autoencoder regularization: https://arxiv.org/pdf/1810.11654.pdf
+.. _TRAILMAP project on GitHub: https://github.com/AlbertPun/TRAILMAP
+.. _3DUnet for Pytorch: https://github.com/wolny/pytorch-3dunet
+
 .. important::
-    The machine learning models used by this program require all images of a dataset to all be of the same size.
+    The machine learning models used by this program require all images of a dataset to be of the same size.
     Please ensure that all the images you are loading are of the **same size**, or to use the **"extract patches" (in augmentation tab)** with an appropriately small size
-    to ensure all images being used are of a proper size.
+    to ensure all images being used by the model are of a workable size.
 
 The training module is comprised of several tabs.
 
 
-1) The first one, **Data**, will let you choose :
+1) The first one, **Data**, will let you set :
 
-* The images folder
-* The labels folder
+* The path to the images folder
+* The path to the labels folder
+* The path to the results folder
 
 2) The second tab, **Augmentation**, lets you define dataset and augmentation parameters such as :
 
 * Whether to use images "as is" (**requires all images to be of the same size and cubic**) or extract patches.
 
 * If you're extracting patches :
-    * The size of patches to be extracted (ideally, please use a value **close to a pwoer of two**, such as 120 or 60.
+    * The size of patches to be extracted (ideally, please use a value **close to a power of two**, such as 120 or 60.
     * The number of samples to extract from each of your image to ensure correct size and perform data augmentation. A larger number will likely mean better performances, but longer training and larger memory usage.
 * Whether to perform data augmentation or not (elastic deforms, intensity shifts. random flipping,etc). A rule of thumb for augmentation is :
-    * If you're using the patch extraction method, enable it if you have more than 10 samples per image with at least 5 images
+    * If you're using the patch extraction method, enable it if you are using more than 10 samples per image with at least 5 images
     * If you have a large dataset and are not using patches extraction, enable it.
 
 
 3) The third contains training related parameters :
-* The model to use for training
+
+* The model to use for training (see table above)
 * The loss function used for training (see table below)
 * The batch size (larger means quicker training and possibly better performance but increased memory usage)
 * The number of epochs (a possibility is to start with 60 epochs, and decrease or increase depending on performance.)
 * The epoch interval for validation (for example, if set to two, the module will use the validation dataset to evaluate the model with the dice metric every two epochs.)
+
 If the dice metric is better on that validation interval, the model weights will be saved in the results folder.
 
 The available loss functions are :
@@ -68,9 +87,9 @@ perform data augmentation if you chose to, select a CUDA device if one is presen
     **The training will stop after the next validation interval is performed, to save the latest model should it be better.**
 
 .. note::
-    You can save the log to record the losses and validation metrics numerical value at each step. This log is autosaved as well when training completes.
+    You can save the log to record the losses and validation metrics numerical values at each step. This log is autosaved as well when training completes.
 
-After two validations steps have been performed, the training loss values and validation metrics will be automatically plotted
+After two validations steps have been performed (depending on the interval you set), the training loss values and validation metrics will be automatically plotted
 and shown on napari every time a validation step completes.
 This plot automatically saved each time validation is performed for now. The final version is stored separately in the results folder.