Metadata-Version: 2.4
Name: geositegraph
Version: 1.0.0
Summary: A graph-based framework for geotechnical site representation
Author-email: Wang Lai <wanglai@imust.edu.cn>
License-Expression: MIT
Project-URL: Homepage, https://github.com/wanglai25/geositegraph
Project-URL: Source, https://github.com/wanglai25/geositegraph.git
Project-URL: Issues, https://github.com/wanglai25/geositegraph/issues
Keywords: geotechnical,subsurface-modeling,graph-neural-networks,site-representation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: GIS
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Operating System :: OS Independent
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: numpy>=1.15.1
Requires-Dist: pandas>=0.23.4
Requires-Dist: scipy>=1.1.0
Requires-Dist: scikit-learn>=0.19.2
Requires-Dist: torch>=1.4.0
Requires-Dist: torch-geometric>=1.6.0
Requires-Dist: matplotlib>=2.2.3
Requires-Dist: pillow>=5.2.0
Requires-Dist: pyvista>=0.30.0
Requires-Dist: tqdm>=4.26.0
Requires-Dist: openpyxl>=2.5.6
Requires-Dist: xlrd>=1.1.0
Provides-Extra: docs
Requires-Dist: sphinx>=4.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme; extra == "docs"
Requires-Dist: myst-parser; extra == "docs"
Dynamic: license-file

# GeoSiteGraph: A Graph-Based Framework for Geotechnical Site Representation

[![PyPI version](https://img.shields.io/pypi/v/geositegraph.svg)](https://pypi.org/project/geositegraph/)
[![Python version](https://img.shields.io/pypi/pyversions/geositegraph.svg)](https://pypi.org/project/geositegraph/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

GeoSiteGraph is a Python framework for **graph-based geotechnical site representation, learning, and visualization**.  
It integrates multi-source geotechnical data processing, spatial graph construction, graph neural networks, and 3D visualization into a unified pipeline for subsurface characterization and prediction.

---

## Overview

GeoSiteGraph provides a unified workflow:
Geotechnical Data → Spatial Graph → Representation Learning → Prediction → Visualization
It is designed for geotechnical applications such as subsurface modeling, site characterization, and data-driven prediction using graph-based methods.

---

## ✨ Features

- **Multi-source Data Integration** for Excel/CSV geotechnical datasets
- **Spatial Graph Construction** from borehole logs and spatial coordinates
- **Graph Neural Networks** for site representation learning and prediction
- **3D Visualization** with PyVista for subsurface modeling and cross-section analysis  
- **Interactive GUI** based on PyQt5 for workflow exploration  
- **Scalable Training** with PyTorch and optional GPU acceleration  
- **Model Export** to standard 3D formats (PLY, OBJ, STL)  

---

## 🚀 Quick Start

### Installation

```bash
pip install geositegraph
```

### Basic Usage

```python
from geositegraph import DataHandler, GeoModel, GeoVisualizer

# Load geotechnical data
handler = DataHandler()
unique_types, num_classes = handler.load_data('geotechnical_data.xlsx')

# Preprocess and align coordinates
rect = handler.compute_mbr()
bounds = handler.align_coordinates(x_res=10, y_res=2, z_res=1)
params_dict = handler.create_param_dict()

# Construct spatial graph
coords, labels, edges = handler.generate_grid(bounds, r=2)

# Train graph neural network
model = GeoModel()
model.prepare_data(coords, labels, edges)
model.build_model(
    num_classes=num_classes,
    hidden_size=48,
    gcn_layers=3,
    mlp_layers=3,
    dropout=0.2
)
history = model.train(epochs=100, lr=3e-3)

# Prediction and visualization
predictions, probabilities = model.predict()
visualizer = GeoVisualizer()
mesh = visualizer.create_model(coords, predictions)
visualizer.show_model(mesh)
```

## Input Data Format

The input dataset should contain:

- `X`, `Y`, `Z`: Spatial coordinates
- `Soil/Rock type`: Soil/rock type classification  
- `Borehole ID`: Borehole ID (optional)
- `Borehole type`: Borehole type (optional)

Additional geotechnical parameters (e.g., strength, density, CPT measurements, etc.) can be incorporated for extended modeling tasks.

## Use Cases

GeoSiteGraph can be applied to:

- 3D subsurface modeling
- Borehole-based site characterization
- Graph-based representation learning of geotechnical data
- Similarity-based site comparison and clustering
- Data-driven prediction of soil/rock properties

## Examples

See the [examples/](examples/) directory:

- `basic_usage.py`: basic workflow
- `advanced_visualization.py`: advanced visualization
- `batch_processing.py`: batch processing
- `custom_model.py`: custom GNN architectures

## Documentation

- [Installation Guide](docs/installation.md)
- [API Reference](docs/api.md)
- [User Tutorial](docs/tutorial.md)
- [Developer Guide](docs/development.md)

## System Requirements

- Python 3.8+
- 8GB RAM minimum (16GB recommended)
- CUDA-compatible GPU (optional, for acceleration)
- OpenGL support for 3D visualization

## Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Citation

If you use GeoSiteGraph in your research, please cite:

```bibtex
@software{sitegraph2026,
  author = {Wang, Lai},
  title = {GeoSiteGraph: A Graph-Based Framework for Geotechnical Site Representation},
  year = {2026},
  version = {1.0.0},
  url = {https://github.com/wanglai25/geositegraph}
}
```

## Support

- 📧 Email: <wanglai@imust.edu.cn>
- 🐛 Issues: [GitHub Issues](https://github.com/wanglai25/geositegraph/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/wanglai25/geositegraph/discussions)
