nettracer3d 0.6.7__tar.gz → 0.6.9__tar.gz

{nettracer3d-0.6.7/src/nettracer3d.egg-info → nettracer3d-0.6.9}/PKG-INFO

@@ -1,14 +1,15 @@
 Metadata-Version: 2.4
 Name: nettracer3d
-Version: 0.6.7
+Version: 0.6.9
 Summary: Scripts for intializing and analyzing networks from segmentations of three dimensional images.
-Author-email: Liam McLaughlin <mclaughlinliam99@gmail.com>
-Project-URL: User_Tutorial, https://www.youtube.com/watch?v=cRatn5VTWDY
+Author-email: Liam McLaughlin <liamm@wustl.edu>
+Project-URL: Documentation, https://nettracer3d.readthedocs.io/en/latest/
+Project-URL: Video_Tutorial, https://www.youtube.com/watch?v=cRatn5VTWDY
 Project-URL: Reference_Citation_For_Use, https://doi.org/10.1101/2024.07.29.605633
 Classifier: Programming Language :: Python :: 3
 Classifier: License :: Other/Proprietary License
 Classifier: Operating System :: OS Independent
-Requires-Python: >=3.8
+Requires-Python: ==3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: numpy==1.26.4
@@ -38,20 +39,46 @@ Dynamic: license-file
 
 NetTracer3D is a python package developed for both 2D and 3D analysis of microscopic images in the .tif file format. It supports generation of 3D networks showing the relationships between objects (or nodes) in three dimensional space, either based on their own proximity or connectivity via connecting objects such as nerves or blood vessels. In addition to these functionalities are several advanced 3D data processing algorithms, such as labeling of branched structures or abstraction of branched structures into networks. Note that nettracer3d uses segmented data, which can be segmented from other softwares such as ImageJ and imported into NetTracer3D, although it does offer its own segmentation via intensity and volumetric thresholding, or random forest machine learning segmentation. NetTracer3D currently has a fully functional GUI. To use the GUI, after installing the nettracer3d package via pip, enter the command 'nettracer3d' in your command prompt:
 
+--- Documentation ---
 
-This gui is built from the PyQt6 package and therefore may not function on dockers or virtual envs that are unable to support PyQt6 displays. More advanced documentation is coming down the line, but for now please see: https://www.youtube.com/watch?v=cRatn5VTWDY
-for a video tutorial on using the GUI.
+Please see: https://nettracer3d.readthedocs.io/en/latest/
+
+--- Installation ---
+
+To install nettracer3d, simply install Python and use this command in your command terminal:
+
+pip install nettracer3d
+
+I recommend installing the program as an Anaconda package to ensure its modules are work together on your specific system:
+(Install anaconda at the link below, set up a new python env for nettracer3d, then use the same pip command).
+
+https://www.anaconda.com/download?utm_source=anacondadocs&utm_medium=documentation&utm_campaign=download&utm_content=installwindows
+
+nettracer3d mostly utilizes the CPU for processing and visualization, although it does have a few GPU-aided options. If you would like to use the GPU for these, you will need an NVIDIA GPU and a corresponding CUDA toolkit which can be installed here:
+https://developer.nvidia.com/cuda-toolkit
+
+To install nettracer3d with associated GPU-supporting packages, please use:
+
+If your CUDA toolkit is version 11: pip install nettracer3d[CUDA11]
+If your CUDA toolkit is version 12: pip install nettracer3d[CUDA12]
+If you just want the entire cupy library: pip install nettracer3d[cupy]
+
+
+This gui is built from the PyQt6 package and therefore may not function on dockers or virtual envs that are unable to support PyQt6 displays.
+
+
+For a (slightly outdated) video tutorial on using the GUI: https://www.youtube.com/watch?v=cRatn5VTWDY
 
 NetTracer3D is free to use/fork for academic/nonprofit use so long as citation is provided, and is available for commercial use at a fee (see license file for information).
 
 NetTracer3D was developed by Liam McLaughlin while working under Dr. Sanjay Jain at Washington University School of Medicine.
 
--- Version 0.6.7 updates --
+-- Version 0.6.9 updates --
 
-1. Updated all methods to use dilation to allow the user to select between perfect distance transform based dilation (which can be slower but allows for perfect searching - and is designed to account for scaling differences), or the current pseudo-3d kernel method.
+1. Adjusted all distance transform-based dilation/radius calculating methods to simply use the already supported scipy.ndimage.distance_transform_edt() sampling parameter to account for differentially scaled axis (previously the image was being resampled but now it no longer will need to do that).
 
-1.5. The dt dilator accounts for scaling by stretching (upsampling) images to equivalent scales before dilating with the distance transform. It will not attempt to downsample. This admittedly will ask for greater memory and some more processing. To give the user the option to use the dt dilator without dealing with this, I added two new options to the resize method. You can now have it upsample your image until its equivalently scaled, or, if you don't need the fidelity, downsample your image until it's equivalently scaled. When the scaling is equivalent, the dt dilator will always just use the regular distance transform without attempting to resize the array.
+2. Added new right click option to extract highlighted regions and implant their data onto a separate image or into a new empty image.
 
-2. Fixed radius finding method to also account for scaling correctly. Previous method scaled wrong. New method predictably accounts for differing scaling in xy vs z dims as well.
+3. General bug fixes and improvements.
 
-3. Bug fixes.
+4. Now specifies python 3.11. 

nettracer3d-0.6.9/README.md

@@ -0,0 +1,45 @@
+NetTracer3D is a python package developed for both 2D and 3D analysis of microscopic images in the .tif file format. It supports generation of 3D networks showing the relationships between objects (or nodes) in three dimensional space, either based on their own proximity or connectivity via connecting objects such as nerves or blood vessels. In addition to these functionalities are several advanced 3D data processing algorithms, such as labeling of branched structures or abstraction of branched structures into networks. Note that nettracer3d uses segmented data, which can be segmented from other softwares such as ImageJ and imported into NetTracer3D, although it does offer its own segmentation via intensity and volumetric thresholding, or random forest machine learning segmentation. NetTracer3D currently has a fully functional GUI. To use the GUI, after installing the nettracer3d package via pip, enter the command 'nettracer3d' in your command prompt:
+
+--- Documentation ---
+
+Please see: https://nettracer3d.readthedocs.io/en/latest/
+
+--- Installation ---
+
+To install nettracer3d, simply install Python and use this command in your command terminal:
+
+pip install nettracer3d
+
+I recommend installing the program as an Anaconda package to ensure its modules are work together on your specific system:
+(Install anaconda at the link below, set up a new python env for nettracer3d, then use the same pip command).
+
+https://www.anaconda.com/download?utm_source=anacondadocs&utm_medium=documentation&utm_campaign=download&utm_content=installwindows
+
+nettracer3d mostly utilizes the CPU for processing and visualization, although it does have a few GPU-aided options. If you would like to use the GPU for these, you will need an NVIDIA GPU and a corresponding CUDA toolkit which can be installed here:
+https://developer.nvidia.com/cuda-toolkit
+
+To install nettracer3d with associated GPU-supporting packages, please use:
+
+If your CUDA toolkit is version 11: pip install nettracer3d[CUDA11]
+If your CUDA toolkit is version 12: pip install nettracer3d[CUDA12]
+If you just want the entire cupy library: pip install nettracer3d[cupy]
+
+
+This gui is built from the PyQt6 package and therefore may not function on dockers or virtual envs that are unable to support PyQt6 displays.
+
+
+For a (slightly outdated) video tutorial on using the GUI: https://www.youtube.com/watch?v=cRatn5VTWDY
+
+NetTracer3D is free to use/fork for academic/nonprofit use so long as citation is provided, and is available for commercial use at a fee (see license file for information).
+
+NetTracer3D was developed by Liam McLaughlin while working under Dr. Sanjay Jain at Washington University School of Medicine.
+
+-- Version 0.6.9 updates --
+
+1. Adjusted all distance transform-based dilation/radius calculating methods to simply use the already supported scipy.ndimage.distance_transform_edt() sampling parameter to account for differentially scaled axis (previously the image was being resampled but now it no longer will need to do that).
+
+2. Added new right click option to extract highlighted regions and implant their data onto a separate image or into a new empty image.
+
+3. General bug fixes and improvements.
+
+4. Now specifies python 3.11. 

{nettracer3d-0.6.7 → nettracer3d-0.6.9}/pyproject.toml

@@ -1,8 +1,8 @@
 [project]
 name = "nettracer3d"
-version = "0.6.7"
+version = "0.6.9"
 authors = [
-  { name="Liam McLaughlin", email="mclaughlinliam99@gmail.com" },
+  { name="Liam McLaughlin", email="liamm@wustl.edu" },
 ]
 description = "Scripts for intializing and analyzing networks from segmentations of three dimensional images."
 
@@ -27,7 +27,7 @@ dependencies = [
 ]
 
 readme = "README.md"
-requires-python = ">=3.8"
+requires-python = "==3.11"
 classifiers = [
     "Programming Language :: Python :: 3",
     "License :: Other/Proprietary License",
@@ -49,5 +49,6 @@ cupy = [
 nettracer3d = "nettracer3d.run:main"
 
 [project.urls]
-User_Tutorial = "https://www.youtube.com/watch?v=cRatn5VTWDY"
+Documentation = "https://nettracer3d.readthedocs.io/en/latest/"
+Video_Tutorial = "https://www.youtube.com/watch?v=cRatn5VTWDY"
 Reference_Citation_For_Use = "https://doi.org/10.1101/2024.07.29.605633"

{nettracer3d-0.6.7 → nettracer3d-0.6.9}/src/nettracer3d/modularity.py

@@ -446,31 +446,11 @@ def community_partition(master_list, weighted = False, style = 0, dostats = True
         except:
             pass
 
-        try:        
-            # Per-community statistics
-            for i, com in enumerate(communities):
-                subgraph = G.subgraph(com)
-                
-                # Basic community metrics
-                stats[f'Community {i+1} Density'] = nx.density(subgraph)
-                stats[f'Community {i+1} Conductance'] = nx.conductance(G, com)
-                stats[f'Community {i+1} Avg Clustering'] = nx.average_clustering(subgraph)
-                
-                # Degree centrality
-                degree_cent = nx.degree_centrality(subgraph)
-                stats[f'Community {i+1} Avg Degree Centrality'] = np.mean(list(degree_cent.values()))
-                
-                # Average path length (only for connected subgraphs)
-                if nx.is_connected(subgraph):
-                    stats[f'Community {i+1} Avg Path Length'] = nx.average_shortest_path_length(subgraph)
-        except:
-            pass
-
-        try:        
+        #try:        
             # Add some Louvain-specific statistics
-            stats['Partition Resolution'] = 1.0  # Default resolution parameter
-        except:
-            pass
+            #stats['Partition Resolution'] = 1.0  # Default resolution parameter
+        #except:
+            #pass
         try:
             stats['Number of Iterations'] = len(set(partition.values()))
         except:
@@ -514,6 +494,25 @@ def community_partition(master_list, weighted = False, style = 0, dostats = True
         except:
             pass
 
+        try:        
+            # Per-community statistics
+            for i, com in enumerate(communities):
+                subgraph = G.subgraph(com)
+                
+                # Basic community metrics
+                stats[f'Community {i+1} Density'] = nx.density(subgraph)
+                stats[f'Community {i+1} Conductance'] = nx.conductance(G, com)
+                stats[f'Community {i+1} Avg Clustering'] = nx.average_clustering(subgraph)
+                
+                # Degree centrality
+                degree_cent = nx.degree_centrality(subgraph)
+                stats[f'Community {i+1} Avg Degree Centrality'] = np.mean(list(degree_cent.values()))
+                
+                # Average path length (only for connected subgraphs)
+                if nx.is_connected(subgraph):
+                    stats[f'Community {i+1} Avg Path Length'] = nx.average_shortest_path_length(subgraph)
+        except:
+            pass
         
         return stats
 

{nettracer3d-0.6.7 → nettracer3d-0.6.9}/src/nettracer3d/morphology.py

@@ -354,6 +354,7 @@ def process_object_cpu(label, objects, labeled_array, xy_scale = 1, z_scale = 1)
     mask = (subarray == label)
 
 
+    """
     # Determine which dimension needs resampling
     if (z_scale > xy_scale) and mask.shape[0] != 1:
         # Z dimension needs to be stretched
@@ -371,13 +372,13 @@ def process_object_cpu(label, objects, labeled_array, xy_scale = 1, z_scale = 1)
     # Resample the mask if needed
     if zoom_factor:
         mask = ndimage.zoom(mask, zoom_factor, order=0)  # Use order=0 for binary masks
-
+    """
     
     # Compute distance transform on the smaller mask
-    dist_transform = compute_distance_transform_distance(mask)
+    dist_transform = compute_distance_transform_distance(mask, sampling = [z_scale, xy_scale, xy_scale])
     
     # Filter out small values near the edge to focus on more central regions
-    radius = np.max(dist_transform) * cardinal
+    radius = np.max(dist_transform)
     
     return label, radius
 
@@ -474,6 +475,7 @@ def estimate_object_radii_gpu(labeled_array, xy_scale = 1, z_scale = 1):
             # Create binary mask for this object (directly on GPU)
             mask_gpu = (labeled_array_gpu[tuple(padded_slices)] == label)
 
+            """
             # Determine which dimension needs resampling
             if (z_scale > xy_scale) and mask_gpu.shape[0] != 1:
                 # Z dimension needs to be stretched
@@ -491,11 +493,12 @@ def estimate_object_radii_gpu(labeled_array, xy_scale = 1, z_scale = 1):
             # Resample the mask if needed
             if zoom_factor:
                 mask_gpu = cpx.zoom(mask_gpu, zoom_factor, order=0)  # Use order=0 for binary masks
+            """
             
             # Compute distance transform on GPU
-            dist_transform_gpu = compute_distance_transform_distance_GPU(mask_gpu)
+            dist_transform_gpu = compute_distance_transform_distance_GPU(mask_gpu, sampling = [z_scale, xy_scale, xy_scale])
         
-            radius = float(cp.max(dist_transform_gpu).get()) * cardinal
+            radius = float(cp.max(dist_transform_gpu).get())
 
 
             # Store the radius and the scaled radius
@@ -510,14 +513,14 @@ def estimate_object_radii_gpu(labeled_array, xy_scale = 1, z_scale = 1):
         print(f"GPU calculation failed, trying CPU instead -> {e}")
         return estimate_object_radii_cpu(labeled_array)
 
-def compute_distance_transform_distance_GPU(nodes):
+def compute_distance_transform_distance_GPU(nodes, sampling = [1,1,1]):
 
     is_pseudo_3d = nodes.shape[0] == 1
     if is_pseudo_3d:
         nodes = cp.squeeze(nodes)  # Convert to 2D for processing
     
     # Compute the distance transform on the GPU
-    distance = cpx.distance_transform_edt(nodes)
+    distance = cpx.distance_transform_edt(nodes, sampling = sampling)
 
     if is_pseudo_3d:
         cp.expand_dims(distance, axis = 0)
@@ -525,14 +528,14 @@ def compute_distance_transform_distance_GPU(nodes):
     return distance    
 
 
-def compute_distance_transform_distance(nodes):
+def compute_distance_transform_distance(nodes, sampling = [1,1,1]):
 
     is_pseudo_3d = nodes.shape[0] == 1
     if is_pseudo_3d:
         nodes = np.squeeze(nodes)  # Convert to 2D for processing
 
     # Fallback to CPU if there's an issue with GPU computation
-    distance = ndimage.distance_transform_edt(nodes)
+    distance = ndimage.distance_transform_edt(nodes, sampling = sampling)
     if is_pseudo_3d:
         np.expand_dims(distance, axis = 0)
     return distance

{nettracer3d-0.6.7 → nettracer3d-0.6.9}/src/nettracer3d/nettracer.py

@@ -987,6 +987,7 @@ def dilate_3D_dt(array, search_distance, xy_scaling=1.0, z_scaling=1.0):
 
     del array
 
+    """
     # Determine which dimension needs resampling
     if (z_scaling > xy_scaling):
         # Z dimension needs to be stretched
@@ -1007,17 +1008,18 @@ def dilate_3D_dt(array, search_distance, xy_scaling=1.0, z_scaling=1.0):
     # Resample the mask if needed
     if zoom_factor:
         inv = ndimage.zoom(inv, zoom_factor, order=0)  # Use order=0 for binary masks
-    
+    """
+
     # Compute distance transform (Euclidean)
-    inv = smart_dilate.compute_distance_transform_distance(inv)
+    inv = smart_dilate.compute_distance_transform_distance(inv, sampling = [z_scaling, xy_scaling, xy_scaling])
 
-    inv = inv * cardinal
+    #inv = inv * cardinal
     
     # Threshold the distance transform to get dilated result
     inv = inv <= search_distance
 
-    if rev_factor:
-        inv = ndimage.zoom(inv, rev_factor, order=0)  # Use order=0 for binary masks
+    #if rev_factor:
+        #inv = ndimage.zoom(inv, rev_factor, order=0)  # Use order=0 for binary masks
     
     return inv.astype(np.uint8)
 
@@ -1043,6 +1045,7 @@ def erode_3D_dt(array, search_distance, xy_scaling=1.0, z_scaling=1.0):
     
     # For erosion, we work directly with the foreground (no inversion needed)
     
+    """
     # Determine which dimension needs resampling
     if (z_scaling > xy_scaling):
         # Z dimension needs to be stretched
@@ -1063,21 +1066,22 @@ def erode_3D_dt(array, search_distance, xy_scaling=1.0, z_scaling=1.0):
     # Resample the mask if needed
     if zoom_factor:
         array = ndimage.zoom(array, zoom_factor, order=0)  # Use order=0 for binary masks
+    """
     
     print("Computing a distance transform for a perfect erosion...")
 
-    array = smart_dilate.compute_distance_transform_distance(array)
+    array = smart_dilate.compute_distance_transform_distance(array, sampling = [z_scaling, xy_scaling, xy_scaling])
     
     # Apply scaling factor
-    array = array * cardinal
+    #array = array * cardinal
     
     # Threshold the distance transform to get eroded result
     # For erosion, we keep only the points that are at least search_distance from the boundary
     array = array >= search_distance
     
     # Resample back to original dimensions if needed
-    if rev_factor:
-        array = ndimage.zoom(array, rev_factor, order=0)  # Use order=0 for binary masks
+    #if rev_factor:
+        #array = ndimage.zoom(array, rev_factor, order=0)  # Use order=0 for binary masks
     
     return array.astype(np.uint8)
 
@@ -2061,7 +2065,24 @@ def mask(image, mask, directory = None):
 
     mask = mask != 0
 
-    image = image * mask
+    if len(image.shape) == 3:
+
+        image = image * mask
+    else:
+        # Split into separate color channels
+        channels = [image[..., i] for i in range(3)]
+        masked_channels = []
+        
+        for image in channels:
+            # Upsample each channel separately
+            if len(image.shape) == 2:
+                np.expand_dims(image, axis = 0)
+            image = image * mask
+            masked_channels.append(image)
+            
+        # Stack the channels back together
+        image = np.stack(masked_channels, axis=-1)
+
 
     if string_bool:
         if directory is None:
@@ -3363,16 +3384,17 @@ class Network_3D:
         :param skeletonize: (Optional - Val = False, boolean) - A boolean of whether to skeletonize the edges when using them.
         """
 
-
-        directory = encapsulate()
+        if directory is not None:
+            directory = encapsulate()
 
         self._xy_scale = xy_scale
         self._z_scale = z_scale
 
-        try:
-            self.save_scaling(directory)
-        except:
-            pass
+        if directory is not None:
+            try:
+                self.save_scaling(directory)
+            except:
+                pass
 
         if search is None and ignore_search_region == False:
             search = 0
@@ -3383,19 +3405,23 @@ class Network_3D:
         self._nodes = nodes
         del nodes
 
+        if self._nodes.shape[0] == 1:
+            fast_dil = True #Set this to true because the 2D algo always uses the distance transform and doesnt need this special ver
+
         if label_nodes:
             self._nodes, num_nodes = label_objects(self._nodes)
         if other_nodes is not None:
             self.merge_nodes(other_nodes, label_nodes)
 
-        try:
-            self.save_nodes(directory)
-        except:
-            pass
-        try:
-            self.save_node_identities(directory)
-        except:
-            pass
+        if directory is not None:
+            try:
+                self.save_nodes(directory)
+            except:
+                pass
+            try:
+                self.save_node_identities(directory)
+            except:
+                pass
 
         if not ignore_search_region:
             self.calculate_search_region(search, GPU = GPU, fast_dil = fast_dil, GPU_downsample = GPU_downsample)
@@ -3408,31 +3434,35 @@ class Network_3D:
 
         self.calculate_edges(edges, diledge = diledge, inners = inners, hash_inner_edges = hash_inners, search = search, remove_edgetrunk = remove_trunk, GPU = GPU, fast_dil = fast_dil, skeletonized = skeletonize)
         del edges
-        try:
-            self.save_edges(directory)
-        except:
-            pass
+        if directory is not None:
+            try:
+                self.save_edges(directory)
+            except:
+                pass
 
         self.calculate_network(search = search, ignore_search_region = ignore_search_region)
 
-        try:
-            self.save_network(directory)
-        except:
-            pass
+        if directory is not None:
+            try:
+                self.save_network(directory)
+            except:
+                pass
 
         if self._nodes is None:
             self.load_nodes(directory)
 
         self.calculate_node_centroids(down_factor)
-        try:
-            self.save_node_centroids(directory)
-        except:
-            pass
+        if directory is not None:
+            try:
+                self.save_node_centroids(directory)
+            except:
+                pass
         self.calculate_edge_centroids(down_factor)
-        try:
-            self.save_edge_centroids(directory)
-        except:
-            pass
+        if directory is not None:
+            try:
+                self.save_edge_centroids(directory)
+            except:
+                pass
 
 
     def draw_network(self, directory = None, down_factor = None, GPU = False):
@@ -4506,11 +4536,28 @@ class Network_3D:
 
 
 
-    def kd_network(self, distance = 100, targets = None):
+    def kd_network(self, distance = 100, targets = None, make_array = False):
+
+        centroids = copy.deepcopy(self._node_centroids)
+
+        if self._xy_scale == self._z_scale:
+            upsample = None
+            distance = distance/self._xy_scale # Account for scaling
+        else:
+            upsample = [self._xy_scale, self._z_scale] # This means resolutions have to be normalized
+            if self._xy_scale < self._z_scale:
+                distance = distance/self._xy_scale # We always upsample to normalize
+                refactor = self._z_scale/self._xy_scale
+                for node, centroid in centroids.items():
+                    centroids[node] = [centroid[0] * refactor, centroid[1], centroid[2]]
+            elif self._z_scale < self._xy_scale:
+                distance = distance/self._z_scale
+                refactor = self._xy_scale/self._z_scale
+                for node, centroid in centroids.items():
+                    centroids[node] = [centroid[0], centroid[1] * refactor, centroid[2] * refactor]
 
-        array = self.centroid_array()
 
-        neighbors = proximity.find_neighbors_kdtree(array, distance, targets = targets)
+        neighbors = proximity.find_neighbors_kdtree(distance, targets = targets, centroids = centroids)
 
         network = create_and_save_dataframe(neighbors)
 
@@ -4520,7 +4567,11 @@ class Network_3D:
 
         self.remove_edge_weights()
 
-        return array
+        if make_array:
+
+            array = self.centroid_array()
+
+            return array