Metadata-Version: 2.4
Name: pyPetrograph
Version: 0.4.0
Summary: A toolkit for semi-automated, ML-assisted thin-section petrography: porosity estimation, mineral counting, grain segmentation and micro-texture analysis
Author: Larry Syu-Heng Lai
License-Expression: AGPL-3.0-or-later
Project-URL: Homepage, https://github.com/GeoLarryLai/pyPetrograph
Project-URL: Repository, https://github.com/GeoLarryLai/pyPetrograph
Project-URL: Changelog, https://github.com/GeoLarryLai/pyPetrograph/blob/main/CHANGELOG.md
Keywords: petrography,thin-section,mineralogy,segmentation,porosity
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Operating System :: OS Independent
Classifier: Environment :: Web Environment
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Image Processing
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: numpy>=1.24
Requires-Dist: pillow>=10
Requires-Dist: matplotlib>=3.7
Requires-Dist: scikit-learn>=1.3
Requires-Dist: scipy>=1.10
Requires-Dist: geopandas>=0.14
Requires-Dist: shapely>=2
Requires-Dist: rasterio>=1.3
Requires-Dist: affine>=2.4
Requires-Dist: joblib>=1.3
Requires-Dist: pandas>=2
Requires-Dist: lightgbm>=4
Requires-Dist: scikit-image>=0.22
Requires-Dist: rapidocr<4,>=3
Requires-Dist: onnxruntime
Requires-Dist: fastapi>=0.110
Requires-Dist: uvicorn>=0.27
Dynamic: license-file

# pyPetrograph

v0.3.0

[![PyPI version](https://img.shields.io/pypi/v/pypetrograph.svg)](https://pypi.org/project/pypetrograph/) [![pepy downloads](https://static.pepy.tech/badge/pypetrograph)](https://pepy.tech/project/pypetrograph) [![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.23659316.svg)](https://doi.org/10.5281/zenodo.23659316)

pyPetrograph is a machine-learning toolkit for thin-section petrography.

**Warning:** This tool is under development. Use with caution. APIs and numbers can still change.

## What it does

**Hand-label features and map their area %.** Paint a few examples of each class you care about (pores, grains, cement, …) from color, edge sharpness, and microtexture. A LightGBM pixel classifier (random forest optional) maps the rest of the photo and reports area % of each class.

**Count grains on a painted mineral map.** Match pixels to a color legend, split grains that touch, and count how many grains sit in each class.

**Segment grains from a multi-image overlay.** Line up several image types of the same field (plane-polarized light, crossed polars, or others) and refine grain outlines with a U-Net, so boundaries are not drawn from one lighting alone. *(Experimental, incomplete.)* Experimental and incomplete: results and functions may change, so use them with caution.

**Advanced Mineral Identification and Characterization System (AMICS) workflow (notebook 4 and the app).** From a BSE image, a mineral map and its legend: read the legend (OCR, editable), outline every grain on the BSE, name each grain from the map, and export counts, per-mineral grain sizes and figures.

| Grain segmentation | Mineral composition | Knolling |
|---|---|---|
| ![segmentation](https://raw.githubusercontent.com/GeoLarryLai/pyPetrograph/main/docs/images/amics_10B_segmentation.jpg) | ![composition](https://raw.githubusercontent.com/GeoLarryLai/pyPetrograph/main/docs/images/amics_10B_composition.jpg) | ![knolling](https://raw.githubusercontent.com/GeoLarryLai/pyPetrograph/main/docs/images/amics_10B_knolling.jpg) |

The app (`pypetrograph-app`) runs in your web browser and offers two jobs: **thin-section photos** (porosity %, as notebook 1) and **AMICS grain counting** (as notebook 4), each step by step. Demo videos are on [GitHub](https://github.com/GeoLarryLai/pyPetrograph#the-app).

[![Demo: measuring porosity in the app](https://raw.githubusercontent.com/GeoLarryLai/pyPetrograph/main/docs/videos/pyPetrograph_optical_demo.webp)](https://github.com/GeoLarryLai/pyPetrograph/blob/main/docs/videos/pyPetrograph_optical_demo.mp4)

## Install

```bash
pip install pyPetrograph
```

Or from the repository:

```bash
git clone https://github.com/GeoLarryLai/pyPetrograph.git
cd pyPetrograph
pip install .
```

⚠️ The default install is **~920 MB**, including legend OCR (rapidocr with onnxruntime and OpenCV, plus the bundled PP-OCRv4 models, **~190 MB**) and the app (fastapi + uvicorn, ~11 MB). Tests (dev only): `pip install pytest httpx`.

## SegmentEveryGrain (optional, for grain segmentation)

Grain segmentation (notebooks 3 and 4, and *Run segmentation* in the app) uses [SegmentEveryGrain](https://github.com/zsylvester/segmenteverygrain). Install it into the same environment as pyPetrograph (it brings TensorFlow, PyTorch and SAM 2.1):

```bash
pip install segmenteverygrain
```

pyPetrograph downloads the SegmentEveryGrain U-Net and, only if *SAM 2.1 refine* is on, the SAM 2.1 checkpoint (~860 MB) on first use. See the [SegmentEveryGrain repository](https://github.com/zsylvester/segmenteverygrain#installation) for full details and troubleshooting.

Without it, everything else works: notebooks 1 and 2, the non-segmentation steps of notebooks 3 and 4, and every app step, including *Load saved grains* and editing them. In the app, *Run segmentation* is greyed out with a link here.

## App

```bash
pypetrograph-app
```

Opens the AMICS workflow in your web browser (local only). The notebook pop-up windows need ⚠️ [PySide6-Essentials](https://pypi.org/project/PySide6-Essentials/) (**~250 MB**, not in the default install): `pip install PySide6-Essentials`.

## Demos

Example notebooks, test images and figures are in the [GitHub repository](https://github.com/GeoLarryLai/pyPetrograph).

## Credits

pyPetrograph is developed by **Larry Syu-Heng Lai** (larrysyuhenglai@gmail.com). Part of the concept and base design (in Notebook 1) originated from early source code written by **Zoltan Sylvester** at the Quantitative Clastic Laboratory, Bureau of Economic Geology, The University of Texas at Austin. This project was initiated as part of a collaboration with **Priyanka Periwal**, **Lucy Tingwei Ko**, **Kelly Hattori**, and **Amanda Calle** across multiple research groups and the [e-MAGE lab](https://www.beg.utexas.edu/research/labs/sem), and Larry intends to continue it after his departure from the Bureau.

## License

```text
Program: pyPetrograph
A toolkit for semi-automated, ML-assisted thin-section petrography:
porosity estimation, mineral counting, grain segmentation and micro-
texture analysis
Copyright (C) 2026  Larry Syu-Heng Lai
```

GNU Affero General Public License 3.0 or later (`LICENSE`).
