Adding new/updated io.github.betaseg_stardist_predict_0.1.0

solutions/io.github.betaseg/stardist_predict/CHANGELOG.md

@@ -4,5 +4,5 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [0.1.0] - 2023-06-26
+## [0.1.0] - 2023-12-28
 

solutions/io.github.betaseg/stardist_predict/README.md

@@ -1,35 +1,94 @@
-# StarDist train album solution
+# StarDist Model Training Solution for Album
 
-This album solution can be used to use a StarDist already trained model for inference from the command line.
+## Introduction
+This is an album solution designed to train a StarDist model directly from the command line. The primary goal of this solution is to facilitate the training of models to segment structures using the StarDist approach.
 
-## documentation
+Please refer to the detailed documentation of [StarDist](https://github.com/stardist/stardist) for in-depth understanding and guidelines.
 
-The extensive documentation of StarDist can be found at https://github.com/stardist/stardist.
+<details>
+  <summary><h2>Example: Training a 3D StarDist Model for Secretory Granules Segmentation</h2></summary>
 
-## Example: 3D segmentation of secretory granules with 3D stardist
+![Sample Image of Secretory Granules](granules.png)
 
-![](granules.png)
+The purpose of this example is to guide users on training a StarDist model to segment secretory granules from 3D FIB-SEM data. The training procedure and its significance are elaborated in the paper:
 
-This code in the solution was used predict from aStardist model to segment secretory granules from 3D FIB-SEM data as
-described in the paper:
-
-Müller, Andreas, et al. "3D FIB-SEM reconstruction of microtubule–organelle interaction in whole primary mouse β cells."
-Journal of Cell Biology 220.2 (2021).
-
-Download the example data (or adapt your own data into the same format)
+Müller, Andreas, et al. "3D FIB-SEM reconstruction of microtubule–organelle interaction in whole primary mouse β cells." Journal of Cell Biology 220.2 (2021).
 
+### Dataset Preparation
+Download the sample data (or you can prepare your own data in a similar format).
+```bash
 wget https://syncandshare.desy.de/index.php/s/5SJFRtAckjBg5gx/download/data_granules.zip
 unzip data_granules.zip
-which should result in the following folder structure:
+```
 
+After extracting, your data should be structured as follows:
+
+```bash
 data_granules
 ├── train
-│ ├── images
-│ └── masks
+│   ├── images
+│   └── masks
 └── val
-├── images
-└── masks
+    ├── images
+    └── masks
+```
+</details>
+
+## Installation
+Make sure album is already installed. If not, download and install it as described [here](https://album.solutions/).
+Also, don't forget to add the catalog to your album installation, so you can install the solutions from the catalog.
+
+Install the `stardist_train` and `stardist_predict` solution by using the graphical user interface (GUI) of album or by running the following command in the terminal:
+```bash
+album install io.github.betaseg:stardist_train:0.1.0
+album install io.github.betaseg:stardist_predict:0.1.0
+```
+
+## How to use
+<details>
+  <summary><h2>Training</h2></summary>
+To start the training process, provide the root directory of the data (using the "root" argument) and the desired output directory (using the "out" argument). By default, the solution will train a 3D stardist model for 100 epochs.
+
+The parameters can be set and run using either the GUI, or by adapting this example for command line usage:
+```bash
+album run stardist_train --root /data/stardist_train/data_granules --out /data/stardist_train/data_granules_out --epochs 10 --steps_per_epoch 15
+```
+
+During training, a _TensorBoard_ will be opened in your browser. You can monitor the training process and the model performance using the _TensorBoard_. The solution terminates when the training is finished and _TensorBoard_ is closed.
+
+The trained model will be saved in the specified output directory and contains the date and time of the run. The model can be used for inference using the `stardist_predict` solution.
+</details>
+
+<details open>
+  <summary><h2>Predict</h2></summary>
+For inference, provide the path to an input file (TIF) or directory containing multiple files (TIF) using the `fname_input` argument. 
+State the `model_name` and its corresponding directory `model_dir`.  
+The output directory must be specified using the `output_dir` argument. 
+
+```bash
+album run stardist_predict --fname_input /data/stardist_train/data_granules/val/images/high_c1_raw_region_2.tif --model_name 2023_06_28-17_45_35_stardist --model_basedir /data/stardist_train/data_granules_out/ --output_dir /data/stardist_train/predictions
+```
+</details>
+
+### Further documentation: 
+For further options, parameters and default values, please refer to the info page of the solution:
+```bash
+album info stardist_predict
+```
+
+## Hardware Requirements
+Ensure that your hardware meets the specific requirements of [StarDist](https://stardist.net/docs/faq.html#what-hardware-do-you-recommend) for efficient training. For training a 3D model, we recommend to use a GPU with at least 8GB of memory.
 
-The model must be received by calling the StarDist train album solution first.
+## Citation & License
+Stardist is licensed under the [BSD 3-Clause License](https://github.com/stardist/stardist/blob/master/LICENSE.txt).
 
-# todo: reproducable call
+If you use this solution, please cite the following paper:
+```
+title: Cell Detection with Star-Convex Polygons,
+doi: 10.1007/978-3-030-00934-2_30
+```
+and
+```
+title: Star-convex Polyhedra for 3D Object Detection and Segmentation in Microscopy,
+doi: 10.1109/WACV45572.2020.9093435
+```

solutions/io.github.betaseg/stardist_predict/solution.py

@@ -1,5 +1,6 @@
 from album.runner.api import get_args, setup, get_environment_path
 import sys
+
 env_file = """name:  stardist_train
 channels:
   - conda-forge
@@ -34,48 +35,53 @@
     - gputools
 """
 
+
 def run():
-    from csbdeep.utils.tf import limit_gpu_memory
-    limit_gpu_memory(fraction=0.8, total_memory=12000)
     from csbdeep.utils import Path
     from tifffile import imread, imsave
     import numpy as np
     from stardist.models import StarDist3D
 
+    def predict_tif(f, model, outdir, x0):
+        # compute n_tiles
+        n_tiles = tuple(int(np.ceil(s / 160)) for s in x0.shape)
+        print(f"using {n_tiles} tiles")
+
+        # normalize
+        print("normalizing...")
+        x = x0.astype(np.float32) / 255
+        # predict
+        y, polys = model.predict_instances(x, n_tiles=n_tiles)
+        rays = polys["rays"]
+        polys["rays_vertices"] = rays.vertices
+        polys["rays_faces"] = rays.faces
+        # save output
+        out = Path(outdir)
+        out.mkdir(exist_ok=True, parents=True)
+        imsave(out / f"{Path(f).stem}.stardist.tif", y)
+        np.savez(out / f"{Path(f).stem}.stardist.npz", **polys)
+
     # parse arguments
     args = get_args()
 
     # options
-    fname = args.fname_input
     model_name = args.model_name
     outdir = args.output_dir
     basedir = args.model_basedir
 
-    # load file
-    x0 = imread(fname)
-
-    # compute n_tiles
-    n_tiles = tuple(int(np.ceil(s / 160)) for s in x0.shape)
-    print(f"using {n_tiles} tiles")
-
     # load model and apply it to the stack
     model = StarDist3D(None, name=model_name, basedir=basedir)
 
-    # normalize
-    print("normalizing...")
-    x = x0.astype(np.float32) / 255
-
-    # predict
-    y, polys = model.predict_instances(x, n_tiles=n_tiles)
-    rays = polys["rays"]
-    polys["rays_vertices"] = rays.vertices
-    polys["rays_faces"] = rays.faces
-
-    # save output
-    out = Path(outdir)
-    out.mkdir(exist_ok=True, parents=True)
-    imsave(out / f"{Path(fname).stem}.stardist.tif", y)
-    np.savez(out / f"{Path(fname).stem}.stardist.npz", **polys)
+    # load files
+    input_path = Path(args.fname_input)
+    if input_path.is_dir():
+        for f in input_path.iterdir():
+            if f.suffix == ".tif":
+                x0 = imread(f)
+                predict_tif(f, model, outdir, x0)
+    else:
+        x0 = imread(input_path)
+        predict_tif(input_path, model, outdir, x0)
 
 
 setup(
@@ -103,17 +109,17 @@ def run():
     args=[
         {
             "name": "fname_input",
-            "description": "Path to the input file.",
+            "description": "Path of the input tif file or folder of tif images.",
             "required": True
         },
         {
             "name": "model_name",
-            "description": "Path to the input model.",
+            "description": "Name of the folder in which the input model is stored.",
             "required": True
         },
         {
             "name": "model_basedir",
-            "description": "Path to the model directory.",
+            "description": "Path to the directory that contains the folders (model_name) for each individual model.",
             "required": True
         },
         {

solutions/io.github.betaseg/stardist_predict/solution.yml

@@ -1,12 +1,13 @@
 album_api_version: 0.5.5
 args:
-- description: Path to the input file.
+- description: Path of the input tif file or folder of tif images.
   name: fname_input
   required: true
-- description: Path to the input model.
+- description: Name of the folder in which the input model is stored.
   name: model_name
   required: true
-- description: Path to the model directory.
+- description: Path to the directory that contains the folders (model_name) for each
+    individual model.
   name: model_basedir
   required: true
 - description: Path to the output directory.
@@ -42,6 +43,6 @@ solution_creators:
 tags:
 - StarDist
 - machine learning
-timestamp: '2023-06-26T12:18:40.765095'
+timestamp: '2023-12-28T20:34:59.537466'
 title: StarDist Predict
 version: 0.1.0