riskenv

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.

Table of Contents

• Installation
• Usage
• CPA metric summary
• Structure
• References
• License

Installation

pip install riskenv

Requires Python ≥ 3.10.

Usage

Minimal example

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:

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:

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

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.