nettracer3d 0.8.1__tar.gz → 0.8.2__tar.gz

nettracer3d-0.8.2/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.4
+Name: nettracer3d
+Version: 0.8.2
+Summary: Scripts for intializing and analyzing networks from segmentations of three dimensional images.
+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.7
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy
+Requires-Dist: scipy
+Requires-Dist: scikit-image
+Requires-Dist: Pillow
+Requires-Dist: matplotlib
+Requires-Dist: networkx
+Requires-Dist: opencv-python-headless
+Requires-Dist: openpyxl
+Requires-Dist: pandas
+Requires-Dist: tifffile
+Requires-Dist: qtrangeslider
+Requires-Dist: PyQt6
+Requires-Dist: scikit-learn
+Requires-Dist: nibabel
+Requires-Dist: setuptools
+Requires-Dist: umap-learn
+Provides-Extra: cuda11
+Requires-Dist: cupy-cuda11x; extra == "cuda11"
+Provides-Extra: cuda12
+Requires-Dist: cupy-cuda12x; extra == "cuda12"
+Provides-Extra: cupy
+Requires-Dist: cupy; extra == "cupy"
+Provides-Extra: cellpose
+Requires-Dist: cellpose[GUI]; extra == "cellpose"
+Provides-Extra: viz
+Requires-Dist: napari; extra == "viz"
+Provides-Extra: all
+Requires-Dist: cellpose[GUI]; extra == "all"
+Requires-Dist: napari; extra == "all"
+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 ---
+
+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
+
+Optional Packages
+~~~~~~~~~~~~~~~~~~
+I recommend including Napari (Chi-Li Chiu, Nathan Clack, the napari community, napari: a Python Multi-Dimensional Image Viewer Platform for the Research Community, Microscopy and Microanalysis, Volume 28, Issue S1, 1 August 2022, Pages 1576–1577, https://doi.org/10.1017/S1431927622006328) in the download as well, which allows NetTracer3D to use 3D displays. The standard package only comes with its native 2D slice display window. 
+If Napari is present, all 3D images and overlays from NetTracer3D can be easily displayed in 3D with a click of a button. To package with Napari, use this install command instead: 
+
+    pip install nettracer3d[viz]
+
+Additionally, for easy access to high-quality cell segmentation, as of version 0.8.2, NetTracer3D can be optionally packaged with Cellpose3. (Stringer, C., Pachitariu, M. Cellpose3: one-click image restoration for improved cellular segmentation. Nat Methods 22, 592–599 (2025). https://doi.org/10.1038/s41592-025-02595-5)
+Cellpose3 is not involved with the rest of the program in any way, although its GUI can be opened from NetTracer3D's GUI, provided both are installed in the same environment. It is a top-tier cell segmenter which can assist in the production of cell networks.
+To include Cellpose3 in the install, use this command:
+
+
+    pip install nettracer3d[cellpose]
+
+Alternatively, both Napari and Cellpose can be included in the package with this command: (Or they can be independently installed with pip from the base package env)
+
+
+    pip install nettracer3d[all]
+
+GPU
+~~~~~~~~~~~~~~~~~~
+NetTracer3D is mostly CPU-bound, but a few functions can optionally use the GPU. To install optional GPU functionalities, first set up a CUDA toolkit that runs with the GPU on your machine. This requires an NVIDIA GPU. Then, find your GPUs compatible CUDA toolkit and install it with the auto-installer from the NVIDIA website: https://developer.nvidia.com/cuda-toolkit
+
+With a CUDA toolkit installed, use:
+
+    pip install nettracer3d[CUDA11] #If your CUDA toolkit is version 11
+    pip install nettracer3d[CUDA12] #If your CUDA toolkit is version 12
+    pip install nettracer3d[cupy] #For the generic cupy library (The above two are usually the ones you want)
+
+Or if you've already installed the NetTracer3D base package and want to get just the GPU associated packages:
+
+    pip install cupy-cuda11x #If your CUDA toolkit is version 11
+    pip install cupy-cuda12x #If your CUDA toolkit is version 12
+    pip install cupy #For the generic cupy library (The above two are usually the ones you want)
+
+While not related to NetTracer3D, if you want to use Cellpose3 (for which GPU-usage is somewhat obligatory) to help segment cells for any networks, you will also want to install pytorch here: https://pytorch.org/. Use the pytorch build menu on this webpage to find a pip install command that is compatible with Python and your CUDA version.
+
+
+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.8.2 Updates -- 
+
+	* Bug Fixes.
+	* Improved some of the image viewer window features.
+	* New option to zoom in on specific windows by clicking + dragging while in zoom mode.
+	* Added more features to UMAP/community neighborhood clustering (optional DBSCAN clustering, results more robust to node distribution)
+	* Made Napari and optional rather than core dependency.
+	* Added Cellpose as an optional dependency.

nettracer3d-0.8.2/README.md

@@ -0,0 +1,72 @@
+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
+
+Optional Packages
+~~~~~~~~~~~~~~~~~~
+I recommend including Napari (Chi-Li Chiu, Nathan Clack, the napari community, napari: a Python Multi-Dimensional Image Viewer Platform for the Research Community, Microscopy and Microanalysis, Volume 28, Issue S1, 1 August 2022, Pages 1576–1577, https://doi.org/10.1017/S1431927622006328) in the download as well, which allows NetTracer3D to use 3D displays. The standard package only comes with its native 2D slice display window. 
+If Napari is present, all 3D images and overlays from NetTracer3D can be easily displayed in 3D with a click of a button. To package with Napari, use this install command instead: 
+
+    pip install nettracer3d[viz]
+
+Additionally, for easy access to high-quality cell segmentation, as of version 0.8.2, NetTracer3D can be optionally packaged with Cellpose3. (Stringer, C., Pachitariu, M. Cellpose3: one-click image restoration for improved cellular segmentation. Nat Methods 22, 592–599 (2025). https://doi.org/10.1038/s41592-025-02595-5)
+Cellpose3 is not involved with the rest of the program in any way, although its GUI can be opened from NetTracer3D's GUI, provided both are installed in the same environment. It is a top-tier cell segmenter which can assist in the production of cell networks.
+To include Cellpose3 in the install, use this command:
+
+
+    pip install nettracer3d[cellpose]
+
+Alternatively, both Napari and Cellpose can be included in the package with this command: (Or they can be independently installed with pip from the base package env)
+
+
+    pip install nettracer3d[all]
+
+GPU
+~~~~~~~~~~~~~~~~~~
+NetTracer3D is mostly CPU-bound, but a few functions can optionally use the GPU. To install optional GPU functionalities, first set up a CUDA toolkit that runs with the GPU on your machine. This requires an NVIDIA GPU. Then, find your GPUs compatible CUDA toolkit and install it with the auto-installer from the NVIDIA website: https://developer.nvidia.com/cuda-toolkit
+
+With a CUDA toolkit installed, use:
+
+    pip install nettracer3d[CUDA11] #If your CUDA toolkit is version 11
+    pip install nettracer3d[CUDA12] #If your CUDA toolkit is version 12
+    pip install nettracer3d[cupy] #For the generic cupy library (The above two are usually the ones you want)
+
+Or if you've already installed the NetTracer3D base package and want to get just the GPU associated packages:
+
+    pip install cupy-cuda11x #If your CUDA toolkit is version 11
+    pip install cupy-cuda12x #If your CUDA toolkit is version 12
+    pip install cupy #For the generic cupy library (The above two are usually the ones you want)
+
+While not related to NetTracer3D, if you want to use Cellpose3 (for which GPU-usage is somewhat obligatory) to help segment cells for any networks, you will also want to install pytorch here: https://pytorch.org/. Use the pytorch build menu on this webpage to find a pip install command that is compatible with Python and your CUDA version.
+
+
+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.8.2 Updates -- 
+
+	* Bug Fixes.
+	* Improved some of the image viewer window features.
+	* New option to zoom in on specific windows by clicking + dragging while in zoom mode.
+	* Added more features to UMAP/community neighborhood clustering (optional DBSCAN clustering, results more robust to node distribution)
+	* Made Napari and optional rather than core dependency.
+	* Added Cellpose as an optional dependency.

{nettracer3d-0.8.1 → nettracer3d-0.8.2}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nettracer3d"
-version = "0.8.1"
+version = "0.8.2"
 authors = [
   { name="Liam McLaughlin", email="liamm@wustl.edu" },
 ]
@@ -16,7 +16,6 @@ dependencies = [
     "opencv-python-headless",
     "openpyxl",
     "pandas",
-    "napari",
     "tifffile",
     "qtrangeslider",
     "PyQt6",
@@ -35,15 +34,17 @@ classifiers = [
 ]
 
 [project.optional-dependencies]
-CUDA11 = [
-"cupy-cuda11x"
-]
-CUDA12 = [
-"cupy-cuda12x"
-]
-cupy = [
-"cupy"
-]
+# GPU options (choose one)
+CUDA11 = ["cupy-cuda11x"]
+CUDA12 = ["cupy-cuda12x"]
+cupy = ["cupy"]
+
+# Features
+cellpose = ["cellpose[GUI]"]
+viz = ["napari"]
+
+# All non-GPU features
+all = ["cellpose[GUI]", "napari"]
 
 [project.scripts]
 nettracer3d = "nettracer3d.run:main"

nettracer3d-0.8.2/src/nettracer3d/cellpose_manager.py

@@ -0,0 +1,161 @@
+import subprocess
+import sys
+import threading
+from pathlib import Path
+from PyQt6.QtWidgets import QMessageBox, QWidget
+
+class CellposeGUILauncher:
+    """Simple launcher for cellpose GUI in PyQt6 applications."""
+    
+    def __init__(self, parent_widget=None):
+        """
+        Initialize the launcher.
+        
+        Args:
+            parent_widget: PyQt6 widget for showing message boxes (optional)
+        """
+        self.parent_widget = parent_widget
+        self.cellpose_process = None
+    
+    def launch_cellpose_gui(self, image_path=None, working_directory=None):
+        """
+        Launch cellpose GUI in a separate thread.
+        
+        Args:
+            image_path (str, optional): Path to image file to load automatically
+            working_directory (str, optional): Directory to start cellpose in
+        
+        Returns:
+            bool: True if launch was initiated successfully
+        """
+        def run_cellpose():
+            """Function to run in separate thread."""
+            try:
+                # Build command
+                cmd = [sys.executable, "-m", "cellpose"]
+                
+                # Add image path if provided
+                if image_path and Path(image_path).exists():
+                    cmd.extend(["--image_path", str(image_path)])
+                
+                # Set working directory
+                cwd = working_directory if working_directory else None
+                
+                # Launch cellpose GUI
+                self.cellpose_process = subprocess.Popen(
+                    cmd,
+                    cwd=cwd,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE
+                )
+                
+                # Optional: wait for process to complete
+                # self.cellpose_process.wait()
+                
+            except Exception as e:
+                if self.parent_widget:
+                    # Show error in main thread
+                    self.show_error(f"Failed to launch cellpose GUI: {str(e)}")
+                else:
+                    print(f"Failed to launch cellpose GUI: {str(e)}")
+        
+        try:
+            # Start cellpose in separate thread
+            thread = threading.Thread(target=run_cellpose, daemon=True)
+            thread.start()
+            
+            if self.parent_widget:
+                self.show_info("Cellpose GUI launched!")
+            else:
+                print("Cellpose GUI launched!")
+            
+            return True
+            
+        except Exception as e:
+            if self.parent_widget:
+                self.show_error(f"Failed to start cellpose thread: {str(e)}")
+            else:
+                print(f"Failed to start cellpose thread: {str(e)}")
+            return False
+    
+    def launch_with_directory(self, directory_path):
+        """
+        Launch cellpose GUI with a specific directory.
+        
+        Args:
+            directory_path (str): Directory containing images
+        """
+        cmd_args = ["--dir", str(directory_path)]
+        return self.launch_cellpose_gui_with_args(cmd_args, working_directory=directory_path)
+    
+    def launch_cellpose_gui_with_args(self, additional_args=None, working_directory=None):
+        """
+        Launch cellpose GUI with custom arguments.
+        
+        Args:
+            additional_args (list): List of additional command line arguments
+            working_directory (str): Working directory for cellpose
+        """
+        def run_cellpose_custom():
+            try:
+                cmd = [sys.executable, "-m", "cellpose"]
+                
+                if additional_args:
+                    cmd.extend(additional_args)
+                
+                cwd = working_directory if working_directory else None
+                
+                self.cellpose_process = subprocess.Popen(
+                    cmd,
+                    cwd=cwd,
+                    stdout=subprocess.PIPE,
+                    stderr=subprocess.PIPE
+                )
+                
+            except Exception as e:
+                if self.parent_widget:
+                    self.show_error(f"Failed to launch cellpose GUI: {str(e)}")
+                else:
+                    print(f"Failed to launch cellpose GUI: {str(e)}")
+        
+        try:
+            thread = threading.Thread(target=run_cellpose_custom, daemon=True)
+            thread.start()
+            return True
+        except Exception as e:
+            if self.parent_widget:
+                self.show_error(f"Failed to start cellpose: {str(e)}")
+            return False
+    
+    def is_cellpose_running(self):
+        """
+        Check if cellpose process is still running.
+        
+        Returns:
+            bool: True if cellpose is still running
+        """
+        if self.cellpose_process is None:
+            return False
+        
+        return self.cellpose_process.poll() is None
+    
+    def close_cellpose(self):
+        """Terminate the cellpose process if running."""
+        if self.cellpose_process and self.is_cellpose_running():
+            try:
+                self.cellpose_process.terminate()
+                self.cellpose_process.wait(timeout=5)  # Wait up to 5 seconds
+            except subprocess.TimeoutExpired:
+                self.cellpose_process.kill()  # Force kill if it doesn't terminate
+            except Exception as e:
+                print(f"Error closing cellpose: {e}")
+    
+    def show_info(self, message):
+        """Show info message if parent widget available."""
+        if self.parent_widget:
+            QMessageBox.information(self.parent_widget, "Cellpose Launcher", message)
+    
+    def show_error(self, message):
+        """Show error message if parent widget available."""
+        if self.parent_widget:
+            QMessageBox.critical(self.parent_widget, "Cellpose Error", message)

{nettracer3d-0.8.1 → nettracer3d-0.8.2}/src/nettracer3d/community_extractor.py

@@ -393,28 +393,105 @@ def find_hub_nodes(G: nx.Graph, proportion: float = 0.1) -> List:
     return output
 
 def get_color_name_mapping():
-    """Return a dictionary of common colors and their RGB values."""
+    """Return a dictionary of descriptive color names and their RGB values."""
     return {
-        'red': (255, 0, 0),
-        'green': (0, 255, 0),
-        'blue': (0, 0, 255),
-        'yellow': (255, 255, 0),
-        'cyan': (0, 255, 255),
+        # Reds
+        'crimson_red': (220, 20, 60),
+        'bright_red': (255, 0, 0),
+        'dark_red': (139, 0, 0),
+        'coral_red': (255, 127, 80),
+        'rose_red': (255, 102, 102),
+        'burgundy': (128, 0, 32),
+        'cherry_red': (222, 49, 99),
+        
+        # Greens
+        'forest_green': (34, 139, 34),
+        'lime_green': (50, 205, 50),
+        'bright_green': (0, 255, 0),
+        'dark_green': (0, 100, 0),
+        'mint_green': (152, 255, 152),
+        'sage_green': (159, 183, 121),
+        'emerald_green': (80, 200, 120),
+        'olive_green': (128, 128, 0),
+        
+        # Blues
+        'royal_blue': (65, 105, 225),
+        'bright_blue': (0, 0, 255),
+        'navy_blue': (0, 0, 128),
+        'sky_blue': (135, 206, 235),
+        'steel_blue': (70, 130, 180),
+        'powder_blue': (176, 224, 230),
+        'midnight_blue': (25, 25, 112),
+        'cobalt_blue': (0, 71, 171),
+        
+        # Purples
+        'deep_purple': (75, 0, 130),
+        'royal_purple': (120, 81, 169),
+        'lavender': (230, 230, 250),
+        'plum_purple': (221, 160, 221),
+        'violet_purple': (238, 130, 238),
         'magenta': (255, 0, 255),
-        'purple': (128, 0, 128),
-        'orange': (255, 165, 0),
-        'brown': (165, 42, 42),
-        'pink': (255, 192, 203),
-        'navy': (0, 0, 128),
-        'teal': (0, 128, 128),
-        'olive': (128, 128, 0),
-        'maroon': (128, 0, 0),
-        'lime': (50, 205, 50),
-        'indigo': (75, 0, 130),
-        'violet': (238, 130, 238),
-        'coral': (255, 127, 80),
+        'orchid': (218, 112, 214),
+        
+        # Yellows & Golds
+        'bright_yellow': (255, 255, 0),
+        'golden_yellow': (255, 215, 0),
+        'lemon_yellow': (255, 247, 0),
+        'amber': (255, 191, 0),
+        'mustard_yellow': (255, 219, 88),
+        'cream': (255, 253, 208),
+        'wheat': (245, 222, 179),
+        
+        # Oranges
+        'bright_orange': (255, 165, 0),
+        'burnt_orange': (204, 85, 0),
+        'peach': (255, 218, 185),
+        'tangerine': (255, 163, 67),
+        'pumpkin_orange': (255, 117, 24),
+        'apricot': (251, 206, 177),
+        
+        # Pinks
+        'hot_pink': (255, 105, 180),
+        'light_pink': (255, 192, 203),
+        'deep_pink': (255, 20, 147),
+        'salmon_pink': (250, 128, 114),
+        'blush_pink': (255, 182, 193),
+        'fuchsia': (255, 0, 255),
+        
+        # Cyans & Teals
+        'bright_cyan': (0, 255, 255),
+        'dark_teal': (0, 128, 128),
         'turquoise': (64, 224, 208),
-        'gold': (255, 215, 0)
+        'aqua': (0, 255, 255),
+        'seafoam': (159, 226, 191),
+        'teal_blue': (54, 117, 136),
+        
+        # Browns & Earth Tones
+        'chocolate_brown': (210, 105, 30),
+        'saddle_brown': (139, 69, 19),
+        'light_brown': (205, 133, 63),
+        'tan': (210, 180, 140),
+        'beige': (245, 245, 220),
+        'coffee_brown': (111, 78, 55),
+        'rust_brown': (183, 65, 14),
+        
+        # Grays & Neutrals
+        'charcoal_gray': (54, 69, 79),
+        'light_gray': (211, 211, 211),
+        'silver': (192, 192, 192),
+        'slate_gray': (112, 128, 144),
+        'ash_gray': (178, 190, 181),
+        'smoke_gray': (152, 152, 152),
+        
+        # Additional Distinctive Colors
+        'lime_yellow': (191, 255, 0),
+        'electric_blue': (125, 249, 255),
+        'neon_green': (57, 255, 20),
+        'wine_red': (114, 47, 55),
+        'copper': (184, 115, 51),
+        'ivory': (255, 255, 240),
+        'periwinkle': (204, 204, 255),
+        'mint': (189, 252, 201)
     }
 
 def rgb_to_color_name(rgb: Tuple[int, int, int]) -> str:
@@ -440,7 +517,7 @@ def rgb_to_color_name(rgb: Tuple[int, int, int]) -> str:
         distance = np.sqrt(np.sum((rgb_array - np.array(color_rgb)) ** 2))
         if distance < min_distance:
             min_distance = distance
-            closest_color = color_name
+            closest_color = color_name + f" {str(rgb_array)}"
             
     return closest_color