scenario-characterization 0.4.1

Automated Scenario Characterization Toolkit.

ScenarioCharacterization

An open-source framework for automated, dataset-agnostic profiling of driving scenarios in trajectory datasets. Built upon the scenario characterization approach introduced in SafeShift, this project extends it into a modular, configuration-driven pipeline with three layers:

1. Dataset adapter — ingests custom datasets and re-formats them into a common scenario representation, validated by Pydantic schemas.
2. Characterizer — performs feature extraction, behavior probing, and criticality scoring at the scenario and agent levels.
3. Analysis — supports scenario visualization, feature and score analyses, categorical profiling, and scenario mining.

New datasets plug in without rewriting the characterization and analysis stack. The framework is demonstrated on Waymo Open Motion, nuScenes, and Argoverse2. Developed as part of an internship project at StackAV.

Visualization Examples

Categorical Scores	Animated Scenarios	Static Scenarios
Results from our categorical profiler. Agents are visualized from dark green (low crit.) to dark red (high crit.) based on their criticality with respect to the ego agent (blue).	Result from our animated visualizer, showing agents by type: vehicle (gray), pedestrian (magenta), cyclist (green), and ego (blue), along with the scenario's elapsed time throughout the episode.	Result from our static scenario visualizer. The episode's time is shown by increasing trajectory opacity over time.

Repository: github.com/navarrs/ScenarioCharacterization

Installation

Install the package

uv pip install scenario-characterization

Install the package in editable mode

Clone the repository and install the package in editable mode:

git clone [e-mail]:navarrs/ScenarioCharacterization.git
cd ScenarioCharacterization
uv run pip install -e .

To install with dataset-specific dependencies, use the appropriate optional extra:

# Waymo Open Motion Dataset (requires Python 3.10)
uv run pip install -e ".[waymo]"

# nuScenes dataset (requires Python 3.12)
uv run pip install -e ".[nuscenes]"

If installing with development dependencies, run:

uv run pip install -e ".[dev]"
uv run pre-commit install

Documentation

• Organization: Overview of the Hydra configuration structure.
• Schemas: Guidelines for creating dataset adapters and processors that comply with the required input/output schemas.
• Characterization: Details on supported scenario characterization and visualization tools, and how to use them.
• Analysis: Shows how to run feature and score analyses.
• Waymo Example: Step-by-step usage example using the Waymo Open Motion Dataset.
• nuScenes Example: Step-by-step usage example using the nuScenes dataset.

Citing

@INPROCEEDINGS{stoler2024safeshift,
  author={Stoler, Benjamin and Navarro, Ingrid and Jana, Meghdeep and Hwang, Soonmin and Francis, Jonathan and Oh, Jean},
  booktitle={2024 IEEE Intelligent Vehicles Symposium (IV)},
  title={SafeShift: Safety-Informed Distribution Shifts for Robust Trajectory Prediction in Autonomous Driving},
  year={2024},
  volume={},
  number={},
  pages={1179-1186},
  keywords={Meters;Collaboration;Predictive models;Robustness;Iron;Trajectory;Safety},
  doi={10.1109/IV55156.2024.10588828}}

Development

Run uv sync --frozen --all-groups to set up the environment. Run pre-commit run --all-files to run all hooks on all files.