Metadata-Version: 2.4
Name: pyqsm
Version: 0.1.0
Summary: Python Utilities for TLS LiDAR Scans of Trees
Author: pyQSM Contributors
Maintainer: pyQSM Contributors
License: Mozilla Public License Version 2.0
Project-URL: Homepage, https://github.com/wischmcj/pyQSM
Project-URL: Documentation, https://pyqsm.readthedocs.io/
Project-URL: Repository, https://github.com/your-username/pyQSM.git
Project-URL: Issues, https://github.com/your-username/pyQSM/issues
Keywords: lidar,point-cloud,tree-analysis,forestry,3d-processing,skeletonization,qsm,terrestrial-laser-scanning,tls
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
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: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Scientific/Engineering :: Mathematics
Requires-Python: >=3.8
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: open3d>=0.17.0
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: scipy>=1.7.0
Requires-Dist: polyscope>=1.0.0
Requires-Dist: networkx>=2.6.0
Requires-Dist: mistree>=0.1.0
Requires-Dist: robust-laplacian>=0.1.0
Requires-Dist: plyfile>=0.7.0
Provides-Extra: dev
Requires-Dist: pytest>=6.0.0; extra == "dev"
Requires-Dist: pytest-cov>=2.0.0; extra == "dev"
Requires-Dist: black>=21.0.0; extra == "dev"
Requires-Dist: flake8>=3.8.0; extra == "dev"
Requires-Dist: mypy>=0.910; extra == "dev"
Requires-Dist: pre-commit>=2.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: sphinx>=4.0.0; extra == "docs"
Requires-Dist: sphinx-rtd-theme>=1.0.0; extra == "docs"
Requires-Dist: myst-parser>=0.15.0; extra == "docs"
Provides-Extra: all
Requires-Dist: pyqsm[dev,docs]; extra == "all"
Dynamic: license-file

# pyQSM: Python Utilities for TLS LiDAR Scans of Trees

pyQSM is a Python library for processing Terrestrial Laser Scanning (TLS) LiDAR point clouds and extracting information regarding tree structural traits from trees found in said scans. The library provides comprehensive tools for tree isolation, structural trait estimation, and 3D surface-reconstruction from point cloud data.

## Overview

pyQSM focuses on three primary use cases:
1. **Tree Isolation**: Separating individual trees from surrounding man-made objects and other vegetation.
2. **Epiphyte Segmentation**: Isolating and analyzing different parts of trees (trunk, branches, leaves) as well as plants in and around the trees.
3. **Ray Casting Similations**: Creation of 3D meshes representing objects and examining their characteristics via tensor intersection calculations.

## Key Features

### 🌳 Tree Processing Pipeline
- **Point Cloud Preprocessing**: Cleaning, filtering, and statistical outlier removal
- **Tree Isolation**: Advanced algorithms to separate individual trees from complex environments
- **Structural Segmentation**: Automatic identification of trunk, branches, and foliage components
- **Skeletonization**: Extract tree skeletal structure using robust Laplacian-based methods
- **QSM Generation**: Create quantitative structural models with cylindrical approximations

### 🔧 Core Algorithms
- **Skeleton Extraction**: Robust Laplacian-based point cloud skeletonization
- **Clustering**: DBSCAN and K-means clustering for point cloud segmentation
- **Geometric Fitting**: RANSAC-based cylinder and sphere fitting
- **Tree Topology**: Graph-based representation of tree structure
- **Surface geometry.reconstruction**: Mesh generation and processing

### 📊 Analysis & Visualization
- **Canopy Metrics**: Comprehensive tree structure analysis
- **3D Visualization**: Interactive point cloud and mesh visualization using Open3D
- **Color Analysis**: HSV-based foliage classification and analysis
- **Ray Casting**: Advanced geometric analysis and projection methods
- **UI Interface**: GUI components for interactive data exploration

## Architecture

```
pyQSM/
├── pyQSM/                                # Main source code
│   ├── geometry/                       # Geometric processing modules
│   │   ├── skeletonize.py              # Skeleton/Wireframe extraction algorithms
│   │   ├── point_cloud_processing.py   # Point cloud utilities
│   │   ├── zoom_and_filter.py          # Bounded filtering utilities
│   │   └── mesh_processing.py          # Triangle Mesh manipulation
|   |   └── reconstruction.py               # 3D geometry.reconstruction tools
│   ├── math/                          # Utility functions
│   │   ├── fit.py                      # RANSAC, DBSCAN, etc. clustering
│   │   └── math_utils.py               # Basic math (i.e. finding center, percentiles)
│   ├── utils/                          # Utility functions
│   │   ├── io.py                       # Input/output operations
│   │   ├── logging_utils.py            # Logging helper functions
│   │   ├── plotting.py                 # Matplotlib scatter plots, histograms, etc.
│   │   └── lib_integration.py          # External library integration
│   ├── viz/                            # Visualization modules
│   │   ├── viz_utils.py                # Open3D visualization utilities
│   │   ├── color.py                    # Color analysis and mapping
│   │   └── tables.py                   # for outputing tabular data
│   ├── tree_isolation.py               # Tree isolation algorithms
│   ├── qsm_generation.py               # QSM generation pipeline
│   ├── canopy_metrics.py               # Tree analysis metrics
│   └── ray_casting.py                  # Ray casting operations
├── scripts/                            # Processing scripts and workflows
├── data/                               # Data storage and examples
└── requirements.txt                    # Dependencies
```

## Installation

### Prerequisites
- Python 3.8+
- CUDA support (optional, for GPU acceleration)

### Dependencies
```bash
pip install -r requirements.txt
```

Key dependencies include:
- `open3d` - 3D data processing
- `numpy` - Numerical computing
- `scipy` - Scientific computing
- `matplotlib` - Plotting and visualization
- `networkx` - Graph processing
- `scikit-learn` - Machine learning algorithms
- `polyscope` - 3D visualization
- `robust_laplacian` - Laplacian mesh processing

### Configuration
The library uses TOML configuration files for algorithm parameters:
- `src/pyqsm_config.toml` - Main configuration file
- Environment variables: `PY_QSM_CONFIG`, `PY_QSM_LOG_CONFIG`

### Configuration

Algorithm parameters can be customized in `pyqsm_config.toml`:

```toml
[skeletonize]
moll = 1e-6
n_neighbors = 20
max_iter = 20
init_contraction = 7
init_attraction = 1

[dbscan]
epsilon = 0.1
min_neighbors = 10

[sphere]
min_radius = 0.01
max_radius = 1.5
```

### Processing Scripts

The `scripts/` directory contains ready-to-use processing workflows:

- `tree_isolation_script.py` - Complete tree isolation pipeline
- `tree_iso_from_feature_branch.py` - Feature-based tree isolation
- `visualize_o3d_ml.py` - Machine learning-based visualization

## Research Applications

pyQSM is designed for:
- **Tree Canopy Segmentation**: Automated identification of individual trees and epipytes there-in

- **Environmental Simulation**: Triangle meshes can be used along side ray-casting to simulate different angles of sunlight, cloud cover and rain angle 

## License

This project is licensed under the Mozilla Public License Version 2.0. See [LICENSE](LICENSE) for details.

## Citation

If you use pyQSM in your research, please cite:
```
[Publication details to be added when available]
```

## Support

For questions, issues, or contributions:
- Open an issue on GitHub
- Check the documentation in the `data/notes/` directory
- Review example workflows in the `scripts/` directory

---

**Note**: This library is under active development. Features and APIs may change between versions. Please check the changelog for breaking changes and updates.
