u-segment3D python version synced with GitLab version as of 3/10/2025.

Author: JennyZouUTSW

README.md

@@ -19,6 +19,9 @@
    * [Danuser Lab Links](#danuser-lab-links)
 <!-- TOC end -->
 
+#### :star2: Mar 2025 :star2:
+- u-Segment3D is available in PyPI and can be directly installed with `pip install u-Segment3D`
+
 #### May 22, 2024
 u-Segment3D is a Python library to merge 2D slice-by-slice segmented 3D volumes in x-y, x-z, or y-z views into a single consensus 3D segmentation. u-Segment3D can use the probabilities and gradients directly predicted by popular existing Neural Network segmentation models such as Cellpose (Direct Method) or operates on the provided 2D segmentations directly (Indirect Method). u-Segment3D does not require all 3 views, any number can be used, nor do each view need be generated by the same algorithm. u-Segment3D also provides a number of postprocessing algorithms to recover missing features after obtaining the 3D segmentation. Therefore it can also be used as a postprocessing module for 3D segmentations in general. 
 Despite the name, the postprocessing and segmentation functions in u-Segment3D have 2D equivalents which can be used to enhance 2D segmentation too. Please see the tutorials.
@@ -111,6 +114,28 @@ The simplest way to get started is to check out the included notebook tutorials
   <img src="docs/imgs/tutorials_flowchart_cheatsheet.png" width="1000"/>
 </p>
 
+#### Direct Method (cell gradients and probability maps as input) in a nutshell
+If you have computed 2D slice-by-slice instance cell segmentations in xy, xz, and yz views, represented by their unit-length gradients  and a 0-1 normalized cell probability maps then you can translate these into one 3D instance segmentation mask with a few lines of code:
+```
+import segment3D.parameters as uSegment3D_params
+import segment3D.usegment3d as uSegment3D
+
+# instantiate default parameters
+aggregation_params = uSegment3D_params.get_2D_to_3D_aggregation_params()
+
+# integrate labels_xy, labels_xz, labels_yz into one single 3D segmentation. Give a single-channel volume image, img we define its xy view as img, its xz view as img.transpose(1,2,0) and its yz view as img.transpose(2,0,1)
+segmentation3D, (probability3D, gradients3D) = uSegment3D.aggregate_2D_to_3D_segmentation_direct_method(segmentations=[img_segment_2D_xy_probs,
+                                                                                                                          img_segment_2D_xz_probs,
+                                                                                                                           img_segment_2D_yz_probs], 
+                                                                                                                  gradients =   [img_segment_2D_xy_flows, 
+                                                                                                                   img_segment_2D_xz_flows,
+                                                                                                                    img_segment_2D_yz_flows], 
+                                                                                                                   params=aggregation_params,
+                                                                                                                savefolder=None,
+                                                                                                                basename=None)
+``` 
+
+#### Indirect Method (instance segmentation masks as input) in a nutshell
 The easiest way to use u-Segment3D is the indirect method. If you have 2D slice-by-slice instance segmentation masks of cells in xy, xz, and yz views, then you can translate these into one 3D instance segmentation mask with a few lines of code:
 ```
 import segment3D.parameters as uSegment3D_params
@@ -130,6 +155,8 @@ segmentation3D, (probability3D, gradients3D) = uSegment3D.aggregate_2D_to_3D_seg
                                                                                                                 basename=None)
 ``` 
 
+**NOTE: for both direct and indirect method above, you can use the empty list `[]` if you do not have segmentation or gradients in one or more orthoviews. This is how u-Segment3D permits 3D translation from any combination of orthoviews**
+
 ### Example Data
 Please download the zipped folder containing example data from the [link](https://www.dropbox.com/scl/fo/le8rjbrohg9p29kebq25f/ANp7T7Z7bh4GsaphRmp7Qc0?rlkey=prgj9mxlluy8cl7x68ygtrigz&st=x89yerip&dl=0). The following examples assume you have unzipped the data to the `example_data/` directory of this repository, and is running the examples after installation from their current location in the repository. Please adjust filepaths accordingly, if otherwise.