Metadata-Version: 2.4
Name: sgtlib
Version: 3.7.9
Summary: A software tool 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.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: license.txt
Requires-Dist: numpy==2.2.6
Requires-Dist: pandas==2.3.2
Requires-Dist: scipy==1.16.2
Requires-Dist: gsd==4.0.0
Requires-Dist: igraph==0.11.9
Requires-Dist: matplotlib==3.10.6
Requires-Dist: networkx==3.5
Requires-Dist: scikit-image==0.25.2
Requires-Dist: opencv-python>=4.12.0
Requires-Dist: pillow==11.3.0
Requires-Dist: PySide6==6.9.2
Requires-Dist: kneed==0.8.5
Requires-Dist: xlsxwriter==3.2.9
Requires-Dist: requests==2.32.5
Requires-Dist: dropbox==12.0.2
Requires-Dist: cryptography==46.0.1
Requires-Dist: scikit-learn==1.7.2
Provides-Extra: ovito
Requires-Dist: ovito>=3.13.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.13 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.13 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)
```


## 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).
