u-segment3D python version synced with GitLab version as of 6/4/2025.

Author: JennyZouUTSW

README.md

@@ -12,13 +12,20 @@
       + [Windows](#windows)
       + [MacOS](#macos)
    * [Getting Started](#getting-started)
+      + [Direct Method (cell gradients and probability maps as input) in a nutshell](#direct-method-cell-gradients-and-probability-maps-as-input-in-a-nutshell)
+      + [Indirect Method (instance segmentation masks as input) in a nutshell](#indirect-method-instance-segmentation-masks-as-input-in-a-nutshell)
+      + [Choosing an Indirect Method Distance Transform](#choosing-an-indirect-method-distance-transform)
       + [Example Data](#example-data)
       + [Example Scripts](#example-scripts)
    * [Overview of Library Features](#overview-of-library-features)
    * [Questions and Issues](#questions-and-issues)
    * [Danuser Lab Links](#danuser-lab-links)
 <!-- TOC end -->
 
+#### June 2025
+- we have updated API to add compatibility with Cellpose4 changes. u-Segment3D should work with cellpose>=4.0.5. If this is not available from pip, you will need to install the github version of cellpose: `pip install git+https://www.github.com/mouseland/cellpose.git`
+- Note: In Cellpose4, the cellpose-SAM model ('cpsam') is the default. As of writing it seems 'cyto3', 'cyto2', 'cyto' etc. are no longer built-in. Therefore currently u-Segment3D will install as dependency **Cellpose3**. This will allow most flexibility for users.  
+
 #### :star2: Mar 2025 :star2:
 - u-Segment3D is available in PyPI and can be directly installed with `pip install u-Segment3D`
 
@@ -28,7 +35,7 @@ Despite the name, the postprocessing and segmentation functions in u-Segment3D h
 
 The primary motivation in developing u-Segment3D is to take advantage and leverage existing state-of-the-art 2D segmentation models for 3D segmentation without further data training. 
 
-It is associated with the BioArxiv paper, [**A general algorithm for consensus 3D cell segmentation from 2D segmented stacks**](https://doi.org/10.1101/2024.05.03.592249), *bioRxiv*, 2024, written by Felix Y. Zhou, Clarence Yapp, Zhiguo Shang, Md Torikul Islam, Benjamin Nanes, Edward Jenkins, Gabriel M. Gihana, Bo-Jui Chang, Andrew Weems, Michael Dustin, Sean Morrison, Reto Fiolka, Kevin Dean, Andrew Jamieson, Peter K. Sorger and [Gaudenz Danuser](https://www.danuserlab-utsw.org/).
+It is associated with the BioArxiv paper, [**Universal consensus 3D segmentation of cells from 2D segmented stacks**](https://www.biorxiv.org/content/10.1101/2024.05.03.592249v3), *bioRxiv*, 2025, written by Felix Y. Zhou, Zach Marin, Clarence Yapp, Qiongjing Zhou, Benjamin A. Nanes, Stephan Daetwyler, Andrew R. Jamieson, Md Torikul Islam, Edward Jenkins, Gabriel M. Gihana, Jinlong Lin, Hazel M.Borges, Bo-Jui Chang, Andrew Weems, Sean J. Morrison, Peter K. Sorger, Reto Fiolka, Kevin Dean, and [Gaudenz Danuser](https://www.danuserlab-utsw.org/).
 
 The current library is still a work-in-progress. It is fully functional but documentation still require work and more tutorials are upcoming. 
 
@@ -157,6 +164,55 @@ segmentation3D, (probability3D, gradients3D) = uSegment3D.aggregate_2D_to_3D_seg
 
 **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**
 
+#### Choosing an Indirect Method Distance Transform
+Choosing a distance transform is a tradeoff for computational speed and accuracy. u-Segment3D provides distance transforms which specify a medial-axis skeleton implicitly and explicitly. If you have tubular, skeletal data, the implicit Euclidean Distance Transform works well. If you have convex cells, the explicit point-source transform, primarily the heat diffusion used also by Cellpose is good. For mixture of arbitrary morphologies, the explicit skeletal point-set transform is best, where u-Segment3D first estimates the medial-axis skeleton with binary morphological operations, then solves the heat diffusion equation using the skeletal points as sources.
+
+The distance transform types available in u-Segmented are summarized visually in the figure.
+<p align="center">
+  <img src="docs/imgs/different_available_transforms.JPG" width="1000"/>
+</p>
+<p align="center">
+  <img src="docs/imgs/transforms_and_shape_suitability.JPG" width="1000"/>
+</p>
+
+The distance transforms are specified by modifying the default parameters imported from parameters.py
+```
+import segment3D.parameters as uSegment3D_params
+
+# Get the default parameters. 
+indirect_aggregation_params = uSegment3D_params.get_2D_to_3D_aggregation_params()
+
+"""
+# a) using Explicit Point Source Distance transforms (either heat diffusion or geodesic)
+"""
+indirect_aggregation_params['indirect_method']['dtform_method'] = 'cellpose_improve' # exact version of Cellpose's iterative heat diffusion
+indirect_aggregation_params['indirect_method']['dtform_method'] = 'fmm' # Fast marching solved geodesic variant 
+indirect_aggregation_params['indirect_method']['edt_fixed_point_percentile'] = 0.01 # adjustment of where to place the medial centroid point. The higher this is, the more the centroid is sampled from only the ridges of the Euclidean Distance Transform. 
+    
+"""
+# b) 
+"""
+# 1. uses heat diffusion skeleton
+indirect_aggregation_params['indirect_method']['dtform_method'] = 'cellpose_skel' 
+# 2. uses Fast marching method solved geodesic skeleton
+indirect_aggregation_params['indirect_method']['dtform_method'] = 'fmm_skel' 
+
+# For both, medial-axis skeleton is found by skimage.morphology.skeletonize. This can result in skeletons with erroneous or too much bifurcations. The following parameters control the smoothing of the skeleton by Gaussian filtering then rebinarizing with a threshold
+indirect_aggregation_params['indirect_method']['smooth_skel_sigma'] = 1 
+indirect_aggregation_params['gradient_descent']['gradient_decay'] = 0.25
+
+"""
+# c) Implicit Skeletal Distance Transform (Euclidean Distance Transform)
+"""
+indirect_aggregation_params['indirect_method']['dtform_method'] = 'edt' # Uses edt package (https://pypi.org/project/edt/) for fast evaluation. 
+    
+"""
+The distance transforms can be further adjusted by modifying gradient decay rate.
+"""
+indirect_aggregation_params['gradient_descent']['gradient_decay'] = 0.25
+    
+```
+
 ### 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. 
 

docs/imgs/different_available_transforms.JPG

@@ -20,7 +20,7 @@ description="Generate consensus 3D segmentation from 2D segmented stacks"
 authors = [{name='Felix Y. Zhou', email='[email protected]'}]
 readme = "README.md"
 license={file = "LICENSE"}
-version = "0.1.0"
+version = "0.1.1"
 classifiers = [
     "Intended Audience :: Developers",
     "Operating System :: POSIX :: Linux",
@@ -32,7 +32,7 @@ classifiers = [
 
 requires-python = ">=3.9"
 dependencies = [
-    'cellpose',
+    'cellpose<4.0',
     'cupy-cuda11x; sys_platform!="darwin"',
     'dask[complete]',
     'scikit-image',
@@ -41,6 +41,7 @@ dependencies = [
     'opencv-python-headless',
     'scipy',
     'numpy<2.0',
+    'numba',
     'matplotlib',
     'seaborn',
     'trimesh',

docs/imgs/transforms_and_shape_suitability.JPG

@@ -292,6 +292,47 @@ def filter_2d_label_slices(labelled,bg_label=0, minsize=10):
     return labelled_
 
 
+def detect_and_relabel_multi_component_labels(labels, min_size=100):
+    
+    import skimage.measure as skmeasure
+    import skimage.morphology as skmorph
+    
+    labels_filt = np.zeros_like(labels)
+    
+    max_id = 1
+
+    regionprops = skmeasure.regionprops(labels)
+    
+    for cc, re in enumerate(regionprops[:]):
+        
+        bbox = re.bbox
+        coords = re.coords
+        
+        x1,y1,z1 = bbox[:3]
+        bbox_size = np.hstack(bbox[3:]) - np.hstack(bbox[:3])
+        
+        mask = np.zeros(bbox_size, dtype=bool)
+        mask[coords[:,0]-x1,
+             coords[:,1]-y1,
+             coords[:,2]-z1] = 1
+        
+        mask = skmorph.remove_small_objects(mask, min_size=min_size)
+        label_mask = skmeasure.label(mask>0)
+        
+        label_ids = np.setdiff1d(np.unique(label_mask),0)
+        
+        for ll in label_ids:
+            coords_ll = np.argwhere(label_mask==ll)
+            coords_ll = coords_ll + np.hstack(bbox[:3])
+            
+            labels_filt[coords_ll[:,0], 
+                                coords_ll[:,1], 
+                                coords_ll[:,2]] = max_id
+            max_id += 1
+    
+    return labels_filt
+
+
 def filter_segmentations_axis(labels, window=3, min_count=1):
     """ according to the persistence along 1 direction. - this works and is relatively fast. 
     """
@@ -486,6 +527,48 @@ def remove_small_labels(labels, min_size=64):
         return labels
 
 
+def intensity_filter_labels(labels, intensity_img, threshold=None, auto_thresh_method='Otsu'):
+    
+    import skimage.measure as skmeasure 
+    import skimage.filters as skfilters
+
+    labels_filt = labels.copy()
+    regionprops = skmeasure.regionprops(labels)
+    
+    all_region_I = [] 
+    all_region_I_inds = []
+    
+    for ind, reg in enumerate(regionprops):
+        coords = reg.coords
+        coords_I = np.nanmean(intensity_img[coords[:,0], 
+                                            coords[:,1],
+                                            coords[:,2]])
+        all_region_I.append(coords_I)
+        all_region_I_inds.append(ind)
+        
+    if len(all_region_I) > 0:
+        all_region_I = np.hstack(all_region_I)
+        all_region_I_inds = np.hstack(all_region_I_inds)
+        
+        if threshold is None:
+            if auto_thresh_method == 'Otsu':
+                threshold = skfilters.threshold_otsu(all_region_I)
+            elif auto_thresh_method == 'Mean':
+                threshold = np.nanmean(all_region_I)
+            elif auto_thresh_method == 'Median':
+                threshold = np.nanmedian(all_region_I)
+            else:
+                threshold = skfilters.threshold_otsu(all_region_I)
+        
+        remove_inds = all_region_I_inds[all_region_I<threshold]
+        
+        for rr in remove_inds:
+            coords = regionprops[rr].coords
+            labels_filt[coords[:,0], coords[:,1], coords[:,2]] = 0 # zero out
+        
+    return labels_filt
+            
+        
 def expand_masks(label_seeds, binary, dist_tform=None):
 
     import skimage.measure as skmeasure