Metadata-Version: 2.4
Name: riskenv
Version: 1.0.0
Summary: A Python library for computing Risk Envelopes — convex hulls of collision-risk regions for motion planning in dynamic environments.
Project-URL: Documentation, https://github.com/RyanMcKeeQUB/riskenv/blob/stable/README.md
Project-URL: Issues, https://github.com/RyanMcKeeQUB/riskenv/issues
Project-URL: Source, https://github.com/RyanMcKeeQUB/riskenv
Project-URL: Changelog, https://github.com/RyanMcKeeQUB/riskenv/releases
Author-email: Ryan McKee <r.mckee@qub.ac.uk>
License: MIT License
        
        Copyright (c) 2025 COLAV LAB
        
        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.
License-File: LICENSE
Classifier: Development Status :: 5 - Production/Stable
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Requires-Dist: matplotlib
Requires-Dist: numpy
Requires-Dist: scipy
Provides-Extra: test
Requires-Dist: pytest; extra == 'test'
Requires-Dist: pytest-cov; extra == 'test'
Requires-Dist: pyyaml; extra == 'test'
Description-Content-Type: text/markdown

# riskenv

[![PyPI - Version](https://img.shields.io/pypi/v/riskenv.svg)](https://pypi.org/project/riskenv)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/riskenv.svg)](https://pypi.org/project/riskenv)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**riskenv** computes the **Risk Envelope** — a convex hull bounding all collision-risk regions around an agent given a set of moving obstacles. It is designed for real-time motion planning in dynamic environments and works in both 2D and 3D spatial contexts across any application domain (autonomous vessels, ground robots, UAVs, etc.).

The Risk Envelope is defined by three filtering criteria (Indices of Interest I1, I2, I3) derived from closest-point-of-approach (CPA) geometry, and is returned as a set of convex hull vertices ready for use in a downstream planner.

![Risk Envelope equation](./docs/unsafe_set_calculation.png)

![Risk Envelope diagram](./docs/unsafe_set_diagram.png)

-----

## Table of Contents

- [Installation](#installation)
- [Usage](#usage)
- [CPA metric summary](#cpa-metric-summary)
- [Structure](#structure)
- [References](#references)
- [License](#license)

## Installation

```bash
pip install riskenv
```

Requires Python ≥ 3.10.

## Usage

### Minimal example

```python
import math
from riskenv import create_unsafe_set, Agent, Obstacle

agent = Agent(
    position=(10.0, 10.0),   # (x, y) or (x, y, z) in metres
    heading=0.0,              # yaw angle in radians
    speed=15.0,               # m/s
    yaw_rate=0.2,             # rad/s
    safety_radius=5.0,        # metres
)

obstacles = [
    Obstacle(
        position=(30.0, 20.0),
        heading=math.pi,      # facing along -x axis
        speed=20.0,
        yaw_rate=0.1,
        safety_radius=10.0,
        tag='vessel_a',
    ),
]

# dsf: distance safety factor (metres) — the proximity threshold for I1/I2/I3
# time_of_interest: TCPA horizon in seconds for the I3 filter (default 15 s)
# Returns: list of [x, y] hull vertices, or [] if no risk region exists.
vertices = create_unsafe_set(agent=agent, obstacles=obstacles, dsf=10.0)
```

### Quaternion users

Convert to a heading angle before constructing `Agent` or `Obstacle`:

```python
from riskenv import heading_from_quaternion

heading = heading_from_quaternion(qx, qy, qz, qw)
```

### Lower-level API

All internal building blocks are importable directly from the top-level package:

```python
from riskenv import (
    calc_cpa,                              # DCPA / TCPA for a single obstacle
    calculate_obstacle_metrics_for_agent,  # annotate all obstacles with CPA metrics
    predict_position,                      # dead-reckoning position at time dt
    calc_I1, calc_I2, calc_I3,            # individual index-of-interest filters
    unionise_indices_of_interest,          # merge I1 / I2 / I3 without duplicates
    gen_uIoI_convhull,                     # convex hull from a union set
    ObstacleWithMetrics,                   # Obstacle + tcpa/dcpa container
)
```

## CPA metric summary

| Case | v\_rel\_norm\_sq | p\_rel == [0, 0] | tcpa > 0 | DCPA | TCPA |
|---|---|---|---|---|---|
| 1.1 Identical position, same velocity | < 1e-6 | ✅ | – | NaN | inf |
| 1.2 Zero relative velocity, offset | < 1e-6 | ❌ | – | ‖p\_rel‖ | ‖p\_rel‖ / ‖v1‖ (or inf) |
| 2.1 Future CPA | ≥ 1e-6 | – | ✅ | ‖p\_rel + tcpa · v\_rel‖ | computed tcpa |
| 2.2 CPA in past or at t=0 | ≥ 1e-6 | – | ❌ | NaN | NaN |

## Structure

```
src/riskenv/
├── objects/              — Agent, Obstacle, ObstacleWithMetrics
├── risk_assessment/      — calc_cpa, heading_from_quaternion, calculate_obstacle_metrics_for_agent
├── indices_of_interest/  — calc_I1, calc_I2, calc_I3, unionise_indices_of_interest
├── collision_geometry/   — gen_uIoI_convhull
├── position_prediction/  — predict_position
└── unsafe_set/           — create_unsafe_set (top-level orchestrator)
```

## References

This package implements the Risk Envelope method for motion planning originally described in:

> R. McKee, N. Athanasopoulos, W. Naeem, *"Geometric Motion Planning in Dynamic Environments"* — *(citation pending publication)*

## License

`riskenv` is distributed under the terms of the [MIT](LICENSE) license.
