Update documentation for sam_annotator

Author: constantinpape

build_doc.py

@@ -0,0 +1,17 @@
+import argparse
+from subprocess import run
+
+parser = argparse.ArgumentParser()
+parser.add_argument("--out", "-o", action="store_true")
+args = parser.parse_args()
+
+logo_url = "https://raw.githubusercontent.com/computational-cell-analytics/micro-sam/master/doc/images/micro-sam-logo.png"
+cmd = ["pdoc", "--docformat", "google", "--logo", logo_url]
+
+if args.out:
+    cmd.extend(["--out", "tmp/"])
+cmd.append("micro_sam")
+
+run(cmd)
+
+# pdoc --docformat google --logo "https://raw.githubusercontent.com/computational-cell-analytics/micro-sam/master/doc/images/micro-sam-logo.png" micro_sam

build_doc.sh

@@ -10,8 +10,19 @@ This functionality is used to implement the `micro_sam` annotation tools, but yo
 
 ## Finetuned models
 
-We provide fine-tuned Segment Anything models for microscopy data. They are still in an experimental stage and we will upload more and better models soon, as well as the code for fine-tuning.
-For using the current models, check out the [2d annotator example](https://github.com/computational-cell-analytics/micro-sam/blob/master/examples/annotator_2d.py#L62) and set `use_finetuned_model` to `True`.
-See the difference between the normal and fine-tuned Segment Anything ViT-h model on an image from [LiveCELL](https://sartorius-research.github.io/LIVECell/):
+We provide finetuned Segment Anything models for microscopy data. They are still in an experimental stage and we will upload more and better models soon, as well as the code for fine-tuning.
+For using the preliminary models, check out the [2d annotator example](https://github.com/computational-cell-analytics/micro-sam/blob/master/examples/annotator_2d.py#L62) and set `use_finetuned_model` to `True`.
+
+We currently provide support for the following models:
+- `vit_h`: The default Segment Anything model with vit-h backbone.
+- `vit_l`: The default Segment Anything model with vit-l backbone.
+- `vit_b`: The default Segment Anything model with vit-b backbone.
+- `vit_h_lm`: The preliminary finetuned Segment Anything model for light microscopy data with vit-h backbone.
+- `vit_b_lm`: The preliminary finetuned Segment Anything model for light microscopy data with vit-b backbone.
+
+These are also the valid names for the `model_type` parameter in `micro_sam`. The library will automatically choose and if necessary download the corresponding model.
+
+See the difference between the normal and finetuned Segment Anything ViT-h model on an image from [LiveCELL](https://sartorius-research.github.io/LIVECell/):
 
 <img src="https://raw.githubusercontent.com/computational-cell-analytics/micro-sam/master/doc/images/vanilla-v-finetuned.png" width="768">
+

doc/python_library.md

@@ -1,8 +1,8 @@
-from .__version__ import __version__
-
 """
 .. include:: ../doc/start_page.md
 .. include:: ../doc/installation.md
 .. include:: ../doc/annotation_tools.md
 .. include:: ../doc/python_library.md
 """
+
+from .__version__ import __version__

micro_sam/__init__.py

@@ -1,3 +1,7 @@
+"""
+The interactive annotation tools.
+"""
+
 from .annotator import annotator
 from .annotator_2d import annotator_2d
 from .annotator_3d import annotator_3d

micro_sam/sam_annotator/__init__.py

@@ -1,3 +1,6 @@
+"""The main GUI for starting annotation tools.
+"""
+
 import os
 import magicgui
 import numpy as np
@@ -12,10 +15,13 @@
 from .annotator_tracking import annotator_tracking
 
 config_dict = {}
+"""@private"""
 main_widget = None
+"""@private"""
 
 
 def show_error(msg):
+    """@private"""
     msg_box = QMessageBox()
     msg_box.setIcon(QMessageBox.Critical)
     msg_box.setText(msg)
@@ -24,14 +30,15 @@ def show_error(msg):
 
 
 def file_is_hirarchical(path_s):
+    """@private"""
     if isinstance(path_s, list):
         return all([file_is_hirarchical(path) for path in path_s])
     else:
         return os.path.splitext(path_s)[1] in [".hdf5", ".h5", "n5", ".zarr"]
 
 
 @magicgui.magicgui(call_button="2d annotator", labels=False)
-def on_2d():
+def _on_2d():
     global config_dict
     sub_widget = None
     config_dict["args"] = {}
@@ -123,7 +130,7 @@ def on_start():
 
 
 @magicgui.magicgui(call_button="3d annotator", labels=False)
-def on_3d():
+def _on_3d():
     global config_dict
     config_dict["args"] = {}
     args = config_dict["args"]
@@ -238,7 +245,7 @@ def on_start():
 
 
 @magicgui.magicgui(call_button="Image series annotator", labels=False)
-def on_series():
+def _on_series():
     global config_dict
     config_dict["args"] = {}
     args = config_dict["args"]
@@ -327,7 +334,7 @@ def on_start():
 
 
 @magicgui.magicgui(call_button="Tracking annotator", labels=False)
-def on_tracking():
+def _on_tracking():
     global config_dict
     config_dict["args"] = {}
     args = config_dict["args"]
@@ -442,10 +449,15 @@ def on_start():
 
 
 def annotator():
+    """Start the main micro_sam GUI.
+
+    From this GUI you can select which annotation tool you want to use and then
+    select the parameters for the tool.
+    """
     global main_widget, config_dict
     config_dict["workflow"] = ""
-    sub_container1 = Container(widgets=[on_2d, on_series], labels=False)
-    sub_container2 = Container(widgets=[on_3d, on_tracking], labels=False)
+    sub_container1 = Container(widgets=[_on_2d, _on_series], labels=False)
+    sub_container2 = Container(widgets=[_on_3d, _on_tracking], labels=False)
     sub_container3 = Container(widgets=[sub_container1, sub_container2], layout="horizontal", labels=False)
     main_widget = Container(widgets=[Label(value="Segment Anything for Microscopy"), sub_container3], labels=False)
     main_widget.show(run=True)
@@ -468,4 +480,5 @@ def annotator():
 
 
 def main():
+    """@private"""
     annotator()

micro_sam/sam_annotator/annotator.py

@@ -16,7 +16,7 @@
 
 
 @magicgui(call_button="Segment Object [S]")
-def segment_wigdet(v: Viewer):
+def _segment_widget(v: Viewer) -> None:
     # get the current box and point prompts
     boxes = vutil.prompt_layer_to_boxes(v.layers["box_prompts"])
     points, labels = vutil.prompt_layer_to_points(v.layers["prompts"])
@@ -60,14 +60,14 @@ def _changed_param(amg, **params):
 
 
 @magicgui(call_button="Automatic Segmentation")
-def autosegment_widget(
+def _autosegment_widget(
     v: Viewer,
     with_background: bool = True,
     pred_iou_thresh: float = 0.88,
     stability_score_thresh: float = 0.95,
     min_initial_size: int = 10,
     box_extension: float = 0.05,
-):
+) -> None:
     global AMG
     is_tiled = IMAGE_EMBEDDINGS["input_size"] is None
     param_changed = _changed_param(
@@ -150,24 +150,22 @@ def _initialize_viewer(raw, segmentation_result, tile_shape, show_embeddings):
     prompt_widget = vutil.create_prompt_menu(prompts, labels)
     v.window.add_dock_widget(prompt_widget)
 
-    # (optional) auto-segmentation functionality
-    v.window.add_dock_widget(autosegment_widget)
-
-    v.window.add_dock_widget(segment_wigdet)
-    v.window.add_dock_widget(vutil.commit_segmentation_widget)
-    v.window.add_dock_widget(vutil.clear_widget)
+    v.window.add_dock_widget(_autosegment_widget)
+    v.window.add_dock_widget(_segment_widget)
+    v.window.add_dock_widget(vutil._commit_segmentation_widget)
+    v.window.add_dock_widget(vutil._clear_widget)
 
     #
     # key bindings
     #
 
     @v.bind_key("s")
     def _segmet(v):
-        segment_wigdet(v)
+        _segment_widget(v)
 
     @v.bind_key("c")
     def _commit(v):
-        vutil.commit_segmentation_widget(v)
+        vutil._commit_segmentation_widget(v)
 
     @v.bind_key("t")
     def _toggle_label(event=None):
@@ -206,7 +204,30 @@ def annotator_2d(
     v: Optional[Viewer] = None,
     predictor: Optional[SamPredictor] = None,
 ) -> Optional[Viewer]:
-    """
+    """The 2d annotation tool.
+
+    Args:
+        raw: The image data.
+        embedding_path: Filepath where to save the embeddings.
+        show_embeddings: Show PCA visualization of the image embeddings.
+            This can be helpful to judge how well Segment Anything works for your data,
+            and which objects can be segmented.
+        segmentation_result: An initial segmentation to load.
+            This can be used to correct segmentations with Segment Anything or to save and load progress.
+            The segmentation will be loaded as the 'committed_objects' layer.
+        model_type: The Segment Anything model to use. For details on the available models check out
+            https://computational-cell-analytics.github.io/micro-sam/micro_sam.html#finetuned-models.
+        tile_shape: Shape of tiles for tiled embedding prediction.
+            If `None` then the whole image is passed to Segment Anything.
+        halo: Shape of the overlap between tiles, which is needed to segment objects on tile boarders.
+        return_viewer: Whether to return the napari viewer to further modify it before starting the tool.
+        v: The viewer to which the SegmentAnything functionality should be added.
+            This enables using a pre-initialized viewer, for example in `sam_annotator.image_series_annotator`.
+        predictor: The Segment Anything model. Passing this enables using fully custom models.
+            If you pass `predictor` then `model_type` will be ignored.
+
+    Returns:
+        The napari viewer, only returned if `return_viewer=True`.
     """
     # for access to the predictor and the image embeddings in the widgets
     global PREDICTOR, IMAGE_EMBEDDINGS, AMG
@@ -245,6 +266,7 @@ def annotator_2d(
 
 
 def main():
+    """@private"""
     parser = vutil._initialize_parser(description="Run interactive segmentation for an image.")
     args = parser.parse_args()
     raw = util.load_image_data(args.input, key=args.key)

micro_sam/sam_annotator/annotator_2d.py

@@ -125,7 +125,7 @@ def segment_range(z_start, z_stop, increment, stopping_criterion, threshold=None
 
 
 @magicgui(call_button="Segment Slice [S]")
-def segment_slice_wigdet(v: Viewer):
+def _segment_slice_wigdet(v: Viewer) -> None:
     position = v.cursor.position
     z = int(position[0])
 
@@ -153,9 +153,9 @@ def segment_slice_wigdet(v: Viewer):
 
 
 @magicgui(call_button="Segment Volume [V]", projection={"choices": ["default", "bounding_box", "mask", "points"]})
-def segment_volume_widget(
+def _segment_volume_widget(
     v: Viewer, iou_threshold: float = 0.8, projection: str = "default", box_extension: float = 0.1
-):
+) -> None:
     # step 1: segment all slices with prompts
     shape = v.layers["raw"].data.shape
 
@@ -197,7 +197,30 @@ def annotator_3d(
     halo: Optional[Tuple[int, int]] = None,
     return_viewer: bool = False,
     predictor: Optional[SamPredictor] = None,
-) -> None:
+) -> Optional[Viewer]:
+    """The 3d annotation tool.
+
+    Args:
+        raw: The image data.
+        embedding_path: Filepath for saving the precomputed embeddings.
+        show_embeddings: Show PCA visualization of the image embeddings.
+            This can be helpful to judge how well Segment Anything works for your data,
+            and which objects can be segmented.
+        segmentation_result: An initial segmentation to load.
+            This can be used to correct segmentations with Segment Anything or to save and load progress.
+            The segmentation will be loaded as the 'committed_objects' layer.
+        model_type: The Segment Anything model to use. For details on the available models check out
+            https://computational-cell-analytics.github.io/micro-sam/micro_sam.html#finetuned-models.
+        tile_shape: Shape of tiles for tiled embedding prediction.
+            If `None` then the whole image is passed to Segment Anything.
+        halo: Shape of the overlap between tiles, which is needed to segment objects on tile boarders.
+        return_viewer: Whether to return the napari viewer to further modify it before starting the tool.
+        predictor: The Segment Anything model. Passing this enables using fully custom models.
+            If you pass `predictor` then `model_type` will be ignored.
+
+    Returns:
+        The napari viewer, only returned if `return_viewer=True`.
+    """
     # for access to the predictor and the image embeddings in the widgets
     global PREDICTOR, IMAGE_EMBEDDINGS
 
@@ -258,27 +281,27 @@ def annotator_3d(
     prompt_widget = vutil.create_prompt_menu(prompts, labels)
     v.window.add_dock_widget(prompt_widget)
 
-    v.window.add_dock_widget(segment_slice_wigdet)
+    v.window.add_dock_widget(_segment_slice_wigdet)
 
-    v.window.add_dock_widget(segment_volume_widget)
-    v.window.add_dock_widget(vutil.commit_segmentation_widget)
-    v.window.add_dock_widget(vutil.clear_widget)
+    v.window.add_dock_widget(_segment_volume_widget)
+    v.window.add_dock_widget(vutil._commit_segmentation_widget)
+    v.window.add_dock_widget(vutil._clear_widget)
 
     #
     # key bindings
     #
 
     @v.bind_key("s")
     def _seg_slice(v):
-        segment_slice_wigdet(v)
+        _segment_slice_wigdet(v)
 
     @v.bind_key("v")
     def _seg_volume(v):
-        segment_volume_widget(v)
+        _segment_volume_widget(v)
 
     @v.bind_key("c")
     def _commit(v):
-        vutil.commit_segmentation_widget(v)
+        vutil._commit_segmentation_widget(v)
 
     @v.bind_key("t")
     def _toggle_label(event=None):
@@ -301,6 +324,7 @@ def clear_prompts(v):
 
 
 def main():
+    """@private"""
     parser = vutil._initialize_parser(description="Run interactive segmentation for an image volume.")
     args = parser.parse_args()
     raw = util.load_image_data(args.input, key=args.key)