Metadata-Version: 2.4
Name: nettracer3d
Version: 1.6.0
Summary: GUI 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: Youtube_Tutorial, https://www.youtube.com/watch?v=_4uDy0mzG94&list=PLsrhxiimzKJMZ3_gTWkfrcAdJQQobUhj7
Project-URL: Installer, https://github.com/mclaughlinliam3/NetTracer3D/releases
Project-URL: Paper, https://doi.org/10.64898/2026.03.25.714104
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: pyqtgraph
Requires-Dist: scikit-learn
Requires-Dist: setuptools
Requires-Dist: umap-learn
Requires-Dist: numba
Requires-Dist: lightgbm
Requires-Dist: napari
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: edt
Requires-Dist: edt; extra == "edt"
Provides-Extra: rec
Requires-Dist: edt; extra == "rec"
Requires-Dist: igraph; extra == "rec"
Requires-Dist: leidenalg; extra == "rec"
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/


--- Video Tutorial ---

Please see: https://www.youtube.com/watch?v=_4uDy0mzG94&list=PLsrhxiimzKJMZ3_gTWkfrcAdJQQobUhj7


--- Using the windows installer ---

If you are on windows, an installer will be available at the GitHub repo: https://github.com/mclaughlinliam3/NetTracer3D/releases

Simply download and run the installer, then open the program in windows. You can also download the executable and its dependencies directly. Note that this version will be missing a few features compared to the Python package, namely GPU segmentation support. It will also not be updated as often.


--- Installing as a Python package ---

1. **Get Python and Pip on your path**: To install nettracer3d, first install Python version 3.12. (You can try other python versions also but I can't say which one's will cause dependency problems). Make sure the Python installation installs pip, and that both Python and pip are available on your PATH. I recommend installing Python using the installer which is available here. Make sure to check the option to 'add Python to PATH' when it appears: https://www.python.org/downloads/


2. **Base Package**: Next, use this command in your command terminal

	* pip install nettracer3d


3. **Optional Performance Boost**: If you are trying to process large images, you may also want to include the 'edt' module in your package. This will allow parallelized CPU calculations for several of the search functions which can increase their speed by an order of magnitude or more depending on how many cores your CPU has. This can be a major benefit if you have a strong CPU and sufficient RAM. It requires an extra pre-installation step, thus is not included by default. You will also have to install the C++ build tools from windows. Please head to this link, then download and run the installer: https://visualstudio.microsoft.com/visual-cpp-build-tools/. In the menu of the installer, select the 'Desktop Development with C++' option, then proceed to download/install it using the installation menu. You will likely want to be using the Python distributed from the actual Python website and not the windows store (or elsewhere) or the edt module may not work properly. To bundle with edt use:

	* pip install nettracer3d[edt]


4. **Recommended full package**: Or if you want to just get both edt and napari at once. This will also give you the module to run leiden clustering:
	
	* pip install nettracer3d[rec]


5. Likewise, if you already installed the default version, you can add the leiden modules and/or edt with just:

	* pip install edt
	* pip install leidenalg
	* pip install igraph

   
--- Installing as a Python package in Anaconda---

Depending on your use case, it may be a good idea to install 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



--- Plugins ---

This is in sort of a beta state at the moment, but as of version 1.6.0 NetTracer3D is supporting plugin architecture. The only plugin currently bundled with the main package is a window to access Cellpose (and/or its gui), to run cell segmentation within NetTracer3D if desired. (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)

Plugins allow modules to be run beyond what's included in the base package, mostly as a way to compartmentalize highly specific functionalities that do not belong in the more broadly applicable main window. For example, the Cellpose plugin will not install cellpose but configures a dependencies file that will allow the user to install it easily through pip.

--- 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 Cellpose (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.


NetTracer3D is freely available for academic and nonprofit use and can obtained from pip (pip install nettracer3d), provided that citation is included in any abstract, paper, or presentation utilizing NetTracer3D.

If you use NetTracer3D for your research, we just ask you please cite this paper: https://doi.org/10.64898/2026.03.25.714104

NetTracer3D was developed by Liam McLaughlin while working under Dr. Sanjay Jain at Washington University School of Medicine.

-- Version 1.6.0 Updates --

	* Removed some of the optional pip install commands. Napari is now included as a default install, and so all of the visualization derivative pip installs are gone.
	* Added plugin support. There is currently no online plugin distributor present so this is more of an early beta than anything; also I wanted to move the Cellpose manager out of the main window and into a more compartmentalized area. But what is set up is a plugin manager and associated api that allows essential variables and functions from the gui to be accessed by external modules for more customizable interactions. The api has a set of safe functions available to use to make plugins. Plugins should then be named __init__.py and distributed in a folder alongside a requirements.txt file. Plugins can be placed in the plugins directory under the main NetTracer3D package directory. If these were ever to be distributed online, this would be handled automatically ideally. Once the 1.6.0 documentation has been updated, there will be a plugin page to read more in depth about this.
	* For data tables that are generated - you can now auto filter them for specific node identities. Useful if you want to just analyze a specific population but you're getting data on everything.
	* From the 'Select All' right click menu - there is now an option to select all the labels available within the 'active_channel', but to select the nodes matching those labels. Useful if you have a subset of node masks in the overlays or similar but just want to select those objects within the nodes channel.
	* Not really a main feature but if you specify channel tiff names to end with 'compressed.tif', they will now save as compressed files. They are compressed by default when saving the entire session but this gives a way to do it for single channels.
	* The 'Network Nearest Neighbors' function now has some additional features for computing the overlay1 output. Before you could just optionally compute an overlay showing the shortest paths between your objects of interest. Now, you can also compute a 'Steiner Subgraph', which is similar to the former but also forces all the objects to exist in the same interconnected subgraph (so you'll get a shortest, snaking path between all the objects). The shortest paths overlay would just make each object find each other object and not necessarily have everything be connected. You can also compute a 'Minimal Connecting Subgraph', which essentially computes short paths between all your objects while also connecting them if a path exists. This tends to be a busier graph than the steiner, often yielding multiple short paths between objects, while also forcing complete connection of the subgraph. This last instance will also send its subgraph to the 'Selection Table' in the lower right if the user wants to do more with it.
	* A few other bug fixes.
	
	
	



