Metadata-Version: 2.4
Name: rockslope
Version: 0.1.1
Summary: Stereonet-based tools for rock slope kinematic analysis.
Author-email: Alexander Altnöder <alexander.altnoeder@gmx.de>
License: MIT License
        
        Copyright (c) 2025 Your Name
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/alalt/RockSlope
Project-URL: Source, https://github.com/alalt/RockSlope
Project-URL: Tracker, https://github.com/alalt/RockSlope/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Visualization
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: numpy>=1.20
Requires-Dist: matplotlib>=3.6
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Requires-Dist: sphinx; extra == "dev"
Requires-Dist: sphinx-rtd-theme; extra == "dev"
Dynamic: license-file

# RockSlope

RockSlope is a Python library for stereonet-based structural geology and rock slope kinematic analysis. It provides a high-level workflow for handling joint orientation data, defining joint sets, computing orientation statistics, performing kinematic failure analyses, visualizing results on stereonets, and generating text-based reports.

The public API is centered around the `RockMass` class, which is intended for end users. Lower-level modules implement spherical geometry, statistics, plotting, and kinematic checks and are considered internal.

---

## Features

RockSlope supports the following core capabilities:

- Management of joint orientation data (dip direction / dip).
- Conversion between geological orientations and spherical unit vectors.
- Definition of joint sets using circular and rectangular selection windows.
- Spherical statistical analysis:
  - Mean axes
  - Fisher confidence angles
  - Variability angles
  - Fisher and Davis kappa estimates
- Stereonet plotting with Matplotlib:
  - Poles, great circles, intersections
  - Selection windows
  - Mean axes and confidence circles
  - Density plots (Kamb method)
- Rock slope kinematic analysis:
  - Planar sliding (with and without lateral limits)
  - Wedge sliding
  - Flexural toppling
  - Direct toppling (intersection- and base-plane based)
- Generation of reStructuredText reports summarizing statistics and kinematics.

All angles passed to the public API are expected in degrees. Internally, computations are performed in radians using unit vectors on the sphere.

---

## Installation

Once published on PyPI:

```bash
pip install rockslope
````

For local development using the `src` layout:

```bash
python -m venv .venv
source .venv/bin/activate  # on Windows: .venv\Scripts\activate
pip install -e .[dev]
```

This installs RockSlope in editable mode together with development dependencies.

---

## Quick Start

### Basic Usage

```python
import numpy as np
from rockslope import RockMass

# Joint orientations as dip direction / dip (degrees)
joints = np.array([
    [230.0, 23.0],
    [145.0, 45.0],
    [240.0, 30.0],
])

rockmass = RockMass(joints)

# Define a slope orientation
rockmass.add_slope(dip_direction=90.0, dip=45.0)

# Define joint sets using selection windows
rockmass.add_circular_selection(
    dip_direction=320.0,
    dip=25.0,
    apical_angle=60.0,
)

# Compute statistics for the defined sets
rockmass.compute_statistics()

# Compute kinematic failure modes
rockmass.compute_kinematics(joint_friction=30.0, lateral_limit=30.0)

# Plot a stereonet with planar sliding results
rockmass.plot(
    poles=True,
    selection_windows=True,
    confidence_angles="fisher",
    kinematics="planar_sliding",
    show=True,
)
```

---

## Selection Windows

RockSlope supports two types of selection windows for defining joint sets:

* **Circular selection**
  Defined by a central orientation and an apical angle.

* **Rectangular selection**
  Defined by a central orientation with separate declination and inclination bounds.

Selections are stored internally and used for both statistical analysis and plotting.

---

## Kinematic Analysis

Kinematic checks are performed against a defined slope orientation. The following failure modes are supported:

* Planar sliding (with optional lateral limits)
* Planar sliding without lateral limits
* Wedge sliding (primary and secondary zones)
* Flexural toppling
* Direct toppling (intersection-based and base-plane based)

Results are stored on the `RockMass` instance and can be visualized on stereonets or summarized in reports.

---

## Reporting

RockSlope can generate a text-based report in reStructuredText format:

```python
rockmass.get_report(
    projectname="Example Slope",
    author="Author Name",
    date="2026-01-01",
    description="Kinematic analysis of a rock slope",
    save_as="report.rst",
)
```

The report includes:

* Project metadata
* Number of planes and intersections
* Joint set statistics (if computed)
* Kinematic analysis summary (if computed)

---

## Data Import

Joint orientations can be loaded from CSV files:

```python
from rockslope import joints_from_csv

joints = joints_from_csv(
    "joints.csv",
    col_dip_direction=0,
    col_dip=1,
    skip=1,
    delimiter=";",
)
```

The CSV file must contain dip direction and dip values in degrees.

---

## Internal Modules

The following modules are used internally by `RockMass`:

* `sphericmath`: spherical geometry and vector operations
* `sphericstats`: spherical statistics and parameter estimation
* `selections`: circular and rectangular selection windows
* `plot`: Matplotlib stereonet projection and plotting utilities
* `kinematics`: rock slope kinematic checks
* `rstbuilder`: helpers for report generation

These modules are considered implementation details and are not part of the stable public API.

---

## Documentation

RockSlope uses Google-style docstrings and Sphinx with the Napoleon extension. To build the documentation locally:

```bash
pip install -e .[dev]
sphinx-build -b html docs docs/_build/html
```

The API documentation focuses on the high-level `RockMass` interface.

---

## Testing

A pytest-based test suite is included:

```bash
pip install -e .[dev]
pytest
```

---

## License

RockSlope is released under the MIT License. See the `LICENSE` file for details.
