terrangraph 1.0.0__tar.gz

terrangraph-1.0.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: terrangraph
+Version: 1.0.0
+Summary: A graph-based framework for geotechnical site representation and subsurface intelligence
+Author-email: Wang Lai <wanglai@imust.edu.cn>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/wanglai25/terrangraph
+Project-URL: Source, https://github.com/wanglai25/terrangraph
+Project-URL: Issues, https://github.com/wanglai25/terrangraph/issues
+Keywords: geotechnical,subsurface,graph-learning,graph-neural-networks,site-characterization,representation-learning
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Information Analysis
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.20
+Requires-Dist: pandas>=1.0
+Requires-Dist: scipy>=1.5
+Requires-Dist: scikit-learn>=0.24
+Requires-Dist: tqdm>=4.40
+Provides-Extra: ml
+Requires-Dist: torch>=1.9; extra == "ml"
+Requires-Dist: torch-geometric>=2.0; extra == "ml"
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.0; extra == "viz"
+Requires-Dist: pyvista>=0.30; extra == "viz"
+Requires-Dist: pillow>=8.0; extra == "viz"
+Provides-Extra: all
+Requires-Dist: torch>=1.9; extra == "all"
+Requires-Dist: torch-geometric>=2.0; extra == "all"
+Requires-Dist: matplotlib>=3.0; extra == "all"
+Requires-Dist: pyvista>=0.30; extra == "all"
+Requires-Dist: pillow>=8.0; extra == "all"
+
+# TerranGraph: A Graph-Based Framework for Geotechnical Site Representation
+
+<p align="center">
+  <img src="assets/banner.png" alt="TerranGraph banner" width="100%">
+</p>
+
+<p align="center">
+  <b>TerranGraph — A unified graph learning framework for subsurface intelligence.</b>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/terrangraph/">
+    <img src="https://img.shields.io/pypi/v/terrangraph.svg" alt="PyPI version">
+  </a>
+  <a href="https://pypi.org/project/terrangraph/">
+    <img src="https://img.shields.io/pypi/pyversions/terrangraph.svg" alt="Python version">
+  </a>
+  <a href="https://opensource.org/licenses/MIT">
+    <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
+  </a>
+</p>
+
+TerranGraph is a Python framework for geotechnical site representation, learning, and visualization. It integrates multi-source data processing, spatial graph construction, graph neural networks, and 3D visualization into a single workflow for subsurface modeling and prediction.
+
+---
+
+## Overview
+
+TerranGraph follows an end-to-end workflow:
+
+**Geotechnical Data → Spatial Graph → Representation Learning → Prediction → Visualization**
+
+Designed for subsurface modeling and site characterization, TerranGraph bridges geotechnical data and graph-based intelligence.
+
+---
+
+## Features
+
+- **Multi-source data integration** for Excel and 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 such as PLY, OBJ, and STL
+
+---
+
+## Installation
+
+Install the lightweight core package:
+
+```bash
+pip install terrangraph
+```
+
+Install with graph learning support:
+
+```bash
+pip install terrangraph[ml]
+```
+
+Install with visualization support:
+
+```bash
+pip install terrangraph[viz]
+```
+
+Install full features:
+
+```bash
+pip install terrangraph[all]
+```
+
+## Quick Start
+
+```python
+from terrangraph import DataHandler, GeoModel, GeoVisualizer
+
+# Load geotechnical data
+handler = DataHandler()
+unique_types, num_classes = handler.load_data("your_dataset.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 include:
+
+- `X`, `Y`, `Z`: spatial coordinates
+- `Soil/Rock Type`: soil or rock type classification
+- `Borehole ID`: borehole identifier (optional)
+- `Borehole Type`: borehole category (optional)
+
+Additional geotechnical parameters (e.g., strength, density, CPT measurements, etc.) can be incorporated for extended modeling tasks.
+
+## Use Cases
+
+TerranGraph can be used for:
+
+- 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 and rock properties
+
+## Project Structure
+
+```text
+terrangraph/
+├── src/
+│   └── terrangraph/
+│       ├── __init__.py              # Package exports
+│       ├── cli.py                   # Command-line interface
+│       └── core/
+│           ├── __init__.py
+│           ├── data_handler.py      # Data loading and preprocessing
+│           ├── geo_model.py         # Graph neural network models
+│           └── visualizer.py        # 3D visualization (PyVista)
+│
+├── assets/                          # Logo and banner images
+├── docs/                            # Documentation files
+├── CHANGELOG.md                     # Version history
+├── LICENSE                          # License
+├── pyproject.toml                   # Package configuration
+└── README.md                        # Project documentation
+```
+
+## 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 (required for `ml`)
+- OpenGL support for 3D visualization (required for `viz`)
+
+## Roadmap
+
+### Current Capabilities
+
+- [x] Graph-based geotechnical site representation  
+- [x] Spatial graph construction from borehole data  
+- [x] GNN-based prediction framework  
+- [x] 3D subsurface visualization (PyVista)  
+
+### Next Steps
+
+- [ ] Integration of additional geotechnical parameters (e.g., CPT, strength, density)
+- [ ] Integration of real-time monitoring data (e.g., tunneling operation data)  
+- [ ] Contrastive learning for site similarity analysis  
+- [ ] Support for large-scale geotechnical datasets  
+- [ ] Probabilistic modeling and uncertainty quantification  
+
+## 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 TerranGraph in your research, please cite:
+
+```bibtex
+@software{wang2026terrangraph,
+  author = {Wang, Lai},
+  title = {TerranGraph: A Graph-Based Framework for Geotechnical Site Representation},
+  year = {2026},
+  version = {1.0.0},
+  url = {https://github.com/wanglai25/terrangraph}
+}
+```
+
+## Support
+
+- Email: <wanglai@imust.edu.cn>
+- Issues: [GitHub Issues](https://github.com/wanglai25/terrangraph/issues)
+- Discussions: [GitHub Discussions](https://github.com/wanglai25/terrangraph/discussions)

terrangraph-1.0.0/README.md

@@ -0,0 +1,220 @@
+# TerranGraph: A Graph-Based Framework for Geotechnical Site Representation
+
+<p align="center">
+  <img src="assets/banner.png" alt="TerranGraph banner" width="100%">
+</p>
+
+<p align="center">
+  <b>TerranGraph — A unified graph learning framework for subsurface intelligence.</b>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/terrangraph/">
+    <img src="https://img.shields.io/pypi/v/terrangraph.svg" alt="PyPI version">
+  </a>
+  <a href="https://pypi.org/project/terrangraph/">
+    <img src="https://img.shields.io/pypi/pyversions/terrangraph.svg" alt="Python version">
+  </a>
+  <a href="https://opensource.org/licenses/MIT">
+    <img src="https://img.shields.io/badge/License-MIT-yellow.svg" alt="License: MIT">
+  </a>
+</p>
+
+TerranGraph is a Python framework for geotechnical site representation, learning, and visualization. It integrates multi-source data processing, spatial graph construction, graph neural networks, and 3D visualization into a single workflow for subsurface modeling and prediction.
+
+---
+
+## Overview
+
+TerranGraph follows an end-to-end workflow:
+
+**Geotechnical Data → Spatial Graph → Representation Learning → Prediction → Visualization**
+
+Designed for subsurface modeling and site characterization, TerranGraph bridges geotechnical data and graph-based intelligence.
+
+---
+
+## Features
+
+- **Multi-source data integration** for Excel and 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 such as PLY, OBJ, and STL
+
+---
+
+## Installation
+
+Install the lightweight core package:
+
+```bash
+pip install terrangraph
+```
+
+Install with graph learning support:
+
+```bash
+pip install terrangraph[ml]
+```
+
+Install with visualization support:
+
+```bash
+pip install terrangraph[viz]
+```
+
+Install full features:
+
+```bash
+pip install terrangraph[all]
+```
+
+## Quick Start
+
+```python
+from terrangraph import DataHandler, GeoModel, GeoVisualizer
+
+# Load geotechnical data
+handler = DataHandler()
+unique_types, num_classes = handler.load_data("your_dataset.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 include:
+
+- `X`, `Y`, `Z`: spatial coordinates
+- `Soil/Rock Type`: soil or rock type classification
+- `Borehole ID`: borehole identifier (optional)
+- `Borehole Type`: borehole category (optional)
+
+Additional geotechnical parameters (e.g., strength, density, CPT measurements, etc.) can be incorporated for extended modeling tasks.
+
+## Use Cases
+
+TerranGraph can be used for:
+
+- 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 and rock properties
+
+## Project Structure
+
+```text
+terrangraph/
+├── src/
+│   └── terrangraph/
+│       ├── __init__.py              # Package exports
+│       ├── cli.py                   # Command-line interface
+│       └── core/
+│           ├── __init__.py
+│           ├── data_handler.py      # Data loading and preprocessing
+│           ├── geo_model.py         # Graph neural network models
+│           └── visualizer.py        # 3D visualization (PyVista)
+│
+├── assets/                          # Logo and banner images
+├── docs/                            # Documentation files
+├── CHANGELOG.md                     # Version history
+├── LICENSE                          # License
+├── pyproject.toml                   # Package configuration
+└── README.md                        # Project documentation
+```
+
+## 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 (required for `ml`)
+- OpenGL support for 3D visualization (required for `viz`)
+
+## Roadmap
+
+### Current Capabilities
+
+- [x] Graph-based geotechnical site representation  
+- [x] Spatial graph construction from borehole data  
+- [x] GNN-based prediction framework  
+- [x] 3D subsurface visualization (PyVista)  
+
+### Next Steps
+
+- [ ] Integration of additional geotechnical parameters (e.g., CPT, strength, density)
+- [ ] Integration of real-time monitoring data (e.g., tunneling operation data)  
+- [ ] Contrastive learning for site similarity analysis  
+- [ ] Support for large-scale geotechnical datasets  
+- [ ] Probabilistic modeling and uncertainty quantification  
+
+## 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 TerranGraph in your research, please cite:
+
+```bibtex
+@software{wang2026terrangraph,
+  author = {Wang, Lai},
+  title = {TerranGraph: A Graph-Based Framework for Geotechnical Site Representation},
+  year = {2026},
+  version = {1.0.0},
+  url = {https://github.com/wanglai25/terrangraph}
+}
+```
+
+## Support
+
+- Email: <wanglai@imust.edu.cn>
+- Issues: [GitHub Issues](https://github.com/wanglai25/terrangraph/issues)
+- Discussions: [GitHub Discussions](https://github.com/wanglai25/terrangraph/discussions)

terrangraph-1.0.0/pyproject.toml

@@ -0,0 +1,86 @@
+[build-system]
+requires = ["setuptools>=77", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "terrangraph"
+dynamic = ["version"]
+description = "A graph-based framework for geotechnical site representation and subsurface intelligence"
+readme = { file = "README.md", content-type = "text/markdown" }
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "Wang Lai", email = "wanglai@imust.edu.cn" },
+]
+
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Scientific/Engineering :: Information Analysis",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3 :: Only",
+    "Programming Language :: Python :: 3.8",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Operating System :: OS Independent",
+]
+
+keywords = [
+    "geotechnical",
+    "subsurface",
+    "graph-learning",
+    "graph-neural-networks",
+    "site-characterization",
+    "representation-learning",
+]
+
+requires-python = ">=3.8"
+
+dependencies = [
+    "numpy>=1.20",
+    "pandas>=1.0",
+    "scipy>=1.5",
+    "scikit-learn>=0.24",
+    "tqdm>=4.40",
+]
+
+[project.optional-dependencies]
+
+ml = [
+    "torch>=1.9",
+    "torch-geometric>=2.0",
+]
+
+viz = [
+    "matplotlib>=3.0",
+    "pyvista>=0.30",
+    "pillow>=8.0",
+]
+
+# full install
+all = [
+    "torch>=1.9",
+    "torch-geometric>=2.0",
+    "matplotlib>=3.0",
+    "pyvista>=0.30",
+    "pillow>=8.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/wanglai25/terrangraph"
+Source = "https://github.com/wanglai25/terrangraph"
+Issues = "https://github.com/wanglai25/terrangraph/issues"
+
+[project.scripts]
+terrangraph = "terrangraph.cli:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+packages = { find = { where = ["src"], include = ["terrangraph*"] } }
+include-package-data = true
+
+[tool.setuptools.dynamic]
+version = { attr = "terrangraph.__version__" }

terrangraph-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

terrangraph-1.0.0/src/terrangraph/__init__.py

@@ -0,0 +1,69 @@
+"""
+TerranGraph - Graph-Based Geotechnical Site Representation
+========================================================
+
+TerranGraph is a Python framework for graph-based learning of geotechnical site
+representation and subsurface modeling. It integrates multi-source geotechnical
+data processing, spatial graph construction, graph neural networks, and 3D
+visualization into a unified workflow for subsurface characterization and prediction.
+
+Main Components:
+- DataHandler: Data loading and preprocessing for geotechnical data
+- GeoModel: Graph neural network modeling for site representation learning
+- GeoVisualizer: 3D visualization using PyVista
+- CLI: Command-line interface for workflow execution
+- GUI: PyQt5-based interactive interface (optional)
+
+Example:
+    >>> from terrangraph import DataHandler, GeoModel, GeoVisualizer
+    >>>
+    >>> # Load and process data
+    >>> handler = DataHandler()
+    >>> handler.load_data("geotechnical_data.xlsx")
+    >>>
+    >>> # Generate spatial graph
+    >>> coords, labels, edges = handler.generate_grid()
+    >>>
+    >>> # Train model
+    >>> model = GeoModel()
+    >>> model.prepare_data(coords, labels, edges)
+    >>> model.build_model(num_classes=5)
+    >>> model.train(epochs=100)
+    >>>
+    >>> # Visualize results
+    >>> visualizer = GeoVisualizer()
+    >>> predictions, _ = model.predict()
+    >>> mesh = visualizer.create_model(coords, predictions)
+    >>> visualizer.show_model(mesh)
+"""
+
+__version__ = "1.0.0"
+__author__ = "Wang Lai"
+__email__ = "wanglai@imust.edu.cn"
+__license__ = "MIT"
+
+# Core components
+from .core.data_handler import DataHandler
+from .core.geo_model import GeoModel, GNN
+from .core.visualizer import GeoVisualizer
+
+# Command line interface
+from .cli import main as cli_main
+
+# Public API
+__all__ = [
+    # Version info
+    '__version__', '__author__', '__email__', '__license__',
+    
+    # Core classes
+    'DataHandler', 'GeoModel', 'GNN', 'GeoVisualizer',
+    
+    # Utilities
+    'validate_data_format', 'estimate_memory_usage', 'optimize_parameters',
+    
+    # CLI
+    'cli_main',
+    
+    # GUI availability
+    'GUI_AVAILABLE',
+]