Merge pull request #55 from C-Achard/general_improvements

WIP : General improvements

Author: C-Achard

.gitattributes

@@ -7,7 +7,8 @@ __pycache__/
 *.so
 
 # unwanted results files
-*.csv
+*.tif
+napari_cellseg3d/_tests/res/*.csv
 
 # Distribution / packaging
 .Python
@@ -90,7 +91,8 @@ venv/
 
 ########
 #project specific
-#dataset, weights, old logos
+#dataset, weights, old logos, requirements
 /napari_cellseg3d/models/dataset/
 /napari_cellseg3d/models/saved_weights/
 /docs/res/logo/old_logo/
+/reqs/

.gitignore

@@ -18,10 +18,13 @@ make_group
 **************************************
 .. autofunction:: napari_cellseg3d.interface::make_group
 
+add_to_group
+**************************************
+.. autofunction:: napari_cellseg3d.interface::add_to_group
 
-make_container_widget
+make_container
 **************************************
-.. autofunction:: napari_cellseg3d.interface::make_container_widget
+.. autofunction:: napari_cellseg3d.interface::make_container
 
 
 make_button

docs/res/code/interface.rst

@@ -12,7 +12,7 @@ Class : ModelFramework
 Methods
 **********************
 .. autoclass:: napari_cellseg3d.model_framework::ModelFramework
-   :members:  __init__,load_dataset_paths,save_log,get_model, get_loss,display_status_report,load_dataset_paths,create_train_dataset_dict, load_image_dataset, load_label_dataset,load_results_path,load_model_path,get_device, update_default, remove_from_viewer
+   :members:  __init__,toggle_visibility, load_dataset_paths,save_log, save_log_to_path,get_model, get_loss,display_status_report,load_dataset_paths,create_train_dataset_dict, load_image_dataset, load_label_dataset,load_results_path,load_model_path,get_device, update_default, remove_from_viewer
    :noindex:
 
 

docs/res/code/model_framework.rst

@@ -13,6 +13,10 @@ binary_watershed
 **************************************
 .. autofunction:: napari_cellseg3d.model_instance_seg::binary_watershed
 
+volume_stats
+**************************************
+.. autofunction:: napari_cellseg3d.model_instance_seg::volume_stats
+
 clear_small_objects
 **************************************
 .. autofunction:: napari_cellseg3d.model_instance_seg::clear_small_objects

docs/res/code/model_instance_seg.rst

@@ -11,7 +11,7 @@ Class : ConvertUtils
 Methods
 **********************
 .. autoclass:: napari_cellseg3d.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:
+    :members:  __init__, build, folder_to_semantic, layer_to_semantic, folder_to_instance, layer_to_instance, layer_remove_small, folder_remove_small , check_ready_layer,check_ready_folder
     :noindex:
 
 Attributes

docs/res/code/plugin_convert.rst

@@ -13,6 +13,10 @@ get_time
 **************************************
 .. autofunction:: napari_cellseg3d.utils::get_time
 
+time_difference
+**************************************
+.. autofunction:: napari_cellseg3d.utils::time_difference
+
 get_time_filepath
 **************************************
 .. autofunction:: napari_cellseg3d.utils::get_time_filepath
@@ -29,6 +33,14 @@ dice_coeff
 **************************************
 .. autofunction:: napari_cellseg3d.utils::dice_coeff
 
+sphericity_volume_area
+**************************************
+.. autofunction:: napari_cellseg3d.utils::sphericity_volume_area
+
+sphericity_axis
+**************************************
+.. autofunction:: napari_cellseg3d.utils::sphericity_axis
+
 normalize_x
 **************************************
 .. autofunction:: napari_cellseg3d.utils::normalize_x

docs/res/code/utils.rst

@@ -31,38 +31,74 @@ Interface and functionalities
 
 * **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.
+  | 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 extension (**.tif** or **.tiff** currently supported) 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 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)
+  | 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)
+
+.. note::
+    Currently the SegResNet model requires you to provide the size of the images the model was trained with due to the VAE module.
+    Provided weights use a size of 128, please leave it as is if you're not using custom weights.
+
+* **Inference parameters** :
+
+  | You can choose to use inference on the whole image at once, which generally yields better performance at the cost of more memory,
+  | or you can use a specific window size to run inference on smaller chunks one by one, for lower memory usage.
+  | You can also choose to keep the dataset in the RAM rather than the VRAM (cpu vs cuda device) to avoid running out of VRAM
+  | if you have several images.
 
 
 * **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.
+  | 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 imaging method 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 thresholding.
+  | You can perform thresholding to **binarize your labels**,
+  | all values beneath the **confidence threshold** will be set to 0 using this.
 
 * **Instance segmentation** :
 
-  | You can convert the semantic segmentation into instance labels by using either the watershed or connected components method.
+  | 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.
 
+
+.. _watershed: https://scikit-image.org/docs/dev/auto_examples/segmentation/plot_watershed.html
+.. _connected components: https://scikit-image.org/docs/dev/api/skimage.measure.html#skimage.measure.label
+
+
+* **Computing objects statistics** :
+
+You can choose to compute various stats from the labels and save them to a csv for later use.
+This includes, for each object :
+
+* Object volume (pixels)
+* :math:`X,Y,Z` coordinates of the centroid
+* Sphericity
+
+And more general statistics :
+
+* Image size
+* Total image volume (pixels)
+* Total object (labeled) volume (pixels)
+* Filling ratio (fraction of the volume that is labeled)
+* The number of labeled objects
+
+In the ``notebooks`` folder you can find an example of plotting cell statistics using the result csv.
+
 * **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.
+  | 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.

docs/res/guides/inference_module_guide.rst

@@ -11,7 +11,20 @@ The Dice coefficient is defined as :
 
 It is a measure of similarity between two sets- :math:`0` indicating no similarity and :math:`1` complete similarity.
 
-You will need to provide two folders : one for ground truth labels and one for predicition labels.
+You will need to provide the following parameters:
+
+* Two folders : one for ground truth labels and one for prediction labels.
+
+* The threshold below which the score is considered insufficient.
+  Any pair below that score will be shown on the viewer; and be displayed in red in the plot.
+
+* Whether to automatically determine the best orientation for the computation by rotating and flipping;
+  use this if your images do not have the same orientation.
+
+.. note::
+    Due to changes in orientation of images after running inference, the utility can rotate and flip images randomly 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.
 
 .. important::
     This utility assumes that **predictions are padded to a power of two already.** Ground truth labels can be smaller,
@@ -22,10 +35,6 @@ Once you are ready, press the "Compute Dice" button. This will plot the Dice sco
 Pairs with a low score will be displayed on the viewer for checking, ground truth in **blue**, low score prediction in **red**.
 
 
-.. 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.
 
 
 Source code

docs/res/guides/metrics_module_guide.rst

@@ -4,7 +4,7 @@ Reviewer module guide
 =================================
 
 This module allows you to review your labels, from predictions or manual labeling,
-and correct them if needed. It then saves the status of each file in a csv, for easier monitoring.
+and correct them if needed. It then saves the status of each file in a csv, as well as the time taken per slice review, for easier monitoring.
 
 
 
@@ -17,13 +17,13 @@ Launching the review process
     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.
+    Only single .tif files or folder of several .png or .tif are currently supported.
 
-* Model name :
+* Csv file 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 you choose to create a new dataset, a new csv will be created no matter what,
+    If you choose to create a new dataset, a new csv will always be created,
     with a trailing number if several copies of it already exists.
 
 * Start :