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.
pip install riskenvRequires Python ≥ 3.10.
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)Convert to a heading angle before constructing Agent or Obstacle:
from riskenv import heading_from_quaternion
heading = heading_from_quaternion(qx, qy, qz, qw)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
)| 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 |
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)
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)
riskenv is distributed under the terms of the MIT license.