Metadata-Version: 2.4
Name: sgtlib
Version: 3.8.7
Summary: A Python library for graph theory analysis of microscopy images.
Author-email: Dickson Owuor <owuordickson@gmail.com>, "Drew A. Vecchio" <vecdrew@umich.edu>, Kody Whisnant <kgwhis@umich.edu>, Alain Kadar <alaink@umich.edu>, Xiong Ye Xiao <xiongyex@usc.edu>, Nicholas Kotov <kotov@umich.edu>
Maintainer-email: Dickson Owuor <owuordickson@gmail.com>
License-Expression: GPL-3.0-or-later
Project-URL: Homepage, https://github.com/owuordickson/structural-gt
Project-URL: Kotov, https://kotov.engin.umich.edu/
Project-URL: COMPASS, https://compass.engin.umich.edu/
Project-URL: Documentation, https://structural-gt.readthedocs.io
Project-URL: Repository, https://github.com/owuordickson/structural-gt.git
Project-URL: Bug Tracker, https://github.com/owuordickson/structural-gt/issues
Project-URL: Changelog, https://github.com/owuordickson/structural-gt/blob/main/CHANGELOG.md
Keywords: nano-particles,nano-structures,graph-theory
Classifier: Development Status :: 4 - Beta
Classifier: Programming Language :: Python :: 3.14
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.14
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: license.txt
Requires-Dist: numpy==2.4.6
Requires-Dist: pandas==3.0.3
Requires-Dist: scipy==1.17.1
Requires-Dist: gsd==5.0.1
Requires-Dist: igraph==1.0.0
Requires-Dist: matplotlib==3.10.9
Requires-Dist: networkx==3.6.1
Requires-Dist: scikit-image==0.26.0
Requires-Dist: opencv-python>=4.13.0
Requires-Dist: pillow==12.2.0
Requires-Dist: PySide6==6.11.1
Requires-Dist: xlsxwriter==3.2.9
Requires-Dist: requests==2.34.2
Requires-Dist: scikit-learn==1.9.0
Requires-Dist: gudhi==3.12.0
Provides-Extra: ovito
Requires-Dist: ovito>=3.14.0; extra == "ovito"
Dynamic: license-file

[![Downloads](https://pepy.tech/badge/sgtlib)](https://pepy.tech/project/sgtlib) [![Downloads](https://pepy.tech/badge/sgtlib/week)](https://pepy.tech/project/sgtlib)
![Dependents](https://badgen.net/github/dependents-repo/owuordickson/structural-gt/?icon=github)
[![DOI](https://zenodo.org/badge/739102771.svg)](https://doi.org/10.5281/zenodo.16542144)
![Dependents](https://badgen.net/github/license/owuordickson/structural-gt/?icon=github)

# StructuralGT

A software tool that allows graph theory analysis of nanostructures. This is a modified version of **StructuralGT** initially proposed by Drew A. Vecchio, DOI: [10.1021/acsnano.1c04711](https://pubs.acs.org/doi/10.1021/acsnano.1c04711?ref=pdf).

## Installation

## 1. Install as software

* Download link: https://github.com/owuordickson/structural-gt/releases/tag/v3.6.8
* Install and enjoy. 
* 5 minute YouTube tutorial: https://www.youtube.com/watch?v=bEXaIKnse3g
* We would love to hear from you, please give us feedback.

## 2. Install via pip
* Install Python version 3.14 on your computer.
* Execute the following commands:

```bash
pip install sgtlib
```


## 3. Install via source code

Therefore, please follow the manual installation instructions provided below:

* Install Python version 3.14 on your computer.
* Git Clone this repo: ```https://github.com/owuordickson/structural-gt.git```
* Extract the ```source code``` folder named **'structural-gt'** and save it to your preferred location on your PC.
* Open a terminal application such as CMD. 
* Navigate to the location where you saved the **'structural-gt'** folder using the terminal. 
* Execute the following commands:

```bash
cd structural-gt
pip install --upgrade pip
pip install -r requirements.txt
pip install .
```

## 3. Usage

### 3(a) Executing GUI App

To run the GUI version, please follow these steps:

* Open a terminal application such as CMD.
* Execute the following command:

```bash
StructuralGT
```

### 3(b) Executing Terminal App

Before executing ```StructuralGT-cli```, you need to specify these parameters:

* **image file path** or **image directory/folder**: *[required and mutually exclusive]* you can set the file path using ```-f path-to-image``` or set the directory path using ```-d path-to-folder```. If the directory path is set, StructuralGT will compute the GT metrics of all the images simultaneously,
* **configuration file path**: *[required]* you can set the path to config the file using ```-c path-to-config```. To make it easy, find the file ```sgt_configs.ini``` (in the *''root folder''*) and modify it to capture your GT parameters,
* **type of GT task**: *[required]* you can either 'extract graph' using ```-t 1``` or compute GT metrics using ```-t 2```,
* **output directory**: *[optional]* you can set the folder where the GT results will be stored using ```-o path-to-folder```,
* **allow auto-scaling** : *[optional]* allows StructuralGT to automatically scale images to an optimal size for computation. You can disable this using ```-s 0```.

Please follow these steps to execute:

* Open a terminal application such as CMD.
* Execute the following command:

```bash
StructuralGT-cli -d datasets/ -c datasets/sgt_configs.ini -o results/ -t 2
```

OR 

```bash
StructuralGT-cli -f datasets/InVitroBioFilm.png -c datasets/sgt_configs.ini -t 2
```

OR

```bash
StructuralGT-cli -f datasets/InVitroBioFilm.png -c datasets/sgt_configs.ini -t 1
```

### 3(c) Using Library API
To use ```StructuralGT``` library:
* Make sure you **install via pip**
* Create a **Python** script or **Jupyter Notebook** and import modules as shown:

```python
import matplotlib.pyplot as plt
from sgtlib import modules as sgt

# set paths
img_path = "path/to/image"
cfg_file = "path/to/sgt_configs.ini"  # Optional: leave blank


# Define a function for receiving progress updates
def print_updates(progress_val, progress_msg):
    print(f"{progress_val}: {progress_msg}")


# Create a Network object
ntwk_obj, _ = sgt.ImageProcessor.from_image_file(img_path, config_file=cfg_file)

# Apply image filters according to cfg_file
ntwk_obj.add_listener(print_updates)
ntwk_obj.apply_img_filters()
ntwk_obj.remove_listener(print_updates)

# View images
sel_img_batch = ntwk_obj.selected_batch
bin_images = [obj.img_bin for obj in sel_img_batch.images]
grayscale_images = [obj.img_grayscale for obj in sel_img_batch.images]
plt.imshow(bin_images[0])
plt.axis('off')  # Optional: Turn off axis ticks and labels for a cleaner image display
plt.title('Binary Image')
plt.show()

plt.imshow(grayscale_images[0])
plt.axis('off')  # Optional: Turn off axis ticks and labels for a cleaner image display
plt.title('Grayscale Image')
plt.show()

# Extract graph
ntwk_obj.add_listener(print_updates)
ntwk_obj.build_graph_network()
ntwk_obj.remove_listener(print_updates)

# View graph
net_images = [ntwk_obj.graph_obj.img_ntwk]
plt.imshow(net_images[0])
plt.axis('off')  # Optional: Turn off axis ticks and labels for a cleaner image display
plt.title('Graph Image')
plt.show()

# Compute graph theory metrics
compute_obj = sgt.GraphAnalyzer(ntwk_obj)
sgt.GraphAnalyzer.safe_run_analyzer(compute_obj, print_updates)
print(compute_obj.output_df)

# Save in PDF
sgt.GraphAnalyzer.write_to_pdf(compute_obj)
```


### 3(d) Generating Synthetic Networks

The synthesis button, second from the left on the ribbon, opens [NetworkSynth](https://github.com/WilliamLuminary/NetworkSynth), which builds synthetic networks modelled on an extracted graph. It runs as its own program, so you choose the settings and the output folder in its window.

Extract a graph first and the button hands it straight over: the network travels down a pipe to NetworkSynth and the image is passed by path, so nothing is exported, saved or picked by hand. It opens with both already in place and drawn together, reading the network in the coordinate space StructuralGT traced it in, which is a scaled copy of the image rather than the file itself. The graph in view is the one that travels, so it is one network per click.

Point it at other inputs there and change your mind, and a button in its Input card puts the extracted network back. Open it with no graph extracted and it starts empty, ready for whatever inputs you choose there.

NetworkSynth is a separate program, and this application finds it either as an installed package or as a checkout.

**Install the package.** Nothing to configure afterwards, and it works the same on every platform:

```bash
pip install "networksynth @ https://github.com/WilliamLuminary/NetworkSynth/archive/refs/heads/dist.zip"
```

That URL is always the newest release. Install it into the environment StructuralGT runs in, and the button finds it on the import path. Swap `dist` for `dist-dev` to take the newest pre-release instead, which is for developers. Every [release](https://github.com/WilliamLuminary/NetworkSynth/releases) also carries a built wheel if you would rather not build one.

**Or take the submodule,** which is what a source checkout of this repository is set up for:

```bash
git submodule sync networksynth
git submodule update --init --checkout networksynth
git -C networksynth fetch origin dist --depth 1
git -C networksynth checkout -B dist FETCH_HEAD
```

`--checkout` is needed because the submodule is set to `update = none`, so a plain `--init` skips it. Run `git submodule sync` again any time `.gitmodules` changes, or the old URL stays cached in your clone.

**To update a submodule, or to move between releases and pre-releases:**

```bash
BRANCH=dist    # dist-dev for pre-releases, developers only
git -C networksynth fetch origin $BRANCH --depth 1
git -C networksynth checkout -B $BRANCH FETCH_HEAD
```

Those two commands are the whole of it: run them with `dist` to take the newest release, with `dist-dev` to try a pre-release, and with `dist` again to come back.

If NetworkSynth fails, the last lines of its output appear in the SGT Logs window.

The checkout runs in StructuralGT's own environment, so that environment has to cover NetworkSynth's dependencies as well. Most are shared already; install the rest from the checkout's `pyproject.toml`, currently `pot` and `psutil`:

```bash
pip install "pot~=0.9.7" "psutil~=7.2.2"
```

You can also point the button at a different folder or a different Python under `[synthesis-settings]` in `sgt_configs.ini`.


## Contributors ✨

Thanks go to these incredible people:

<a href="https://github.com/owuordickson/structural-gt/graphs/contributors">
  <img src="https://contrib.rocks/image?repo=owuordickson/structural-gt" />
</a>

Made with [contrib.rocks](https://contrib.rocks).
