Skip to content

Start here

bikeped is a collision warning system for crossings shared by pedestrians and cyclists. This page says what the project is, what the repository holds, and where each topic is documented.

What the project is

A level fisheye camera on a pole faces across one crosswalk. A Jetson Orin next to it runs an object detector, a ground-plane tracker and a three-stage decision pipeline at 30 FPS, and drives a warning light. Each frame ends in one of four states: idle when no pedestrian is present, safe when a pedestrian is present and no cyclist has been seen in the last 58 frames (about 2 s), warning when both are present, and alert when a cyclist and a pedestrian are closing on each other.

The repository is the companion code of the paper A Real-Time Bike-Pedestrian Safety System with Wide-Angle Perception and Evaluation Testbed for Urban Intersections. The decision logic in it is the file that runs on the device. Around that file sits an offline testbench that replays 24 scripted conformance scenarios through the same logic and produces every number in the paper, so a change to a threshold can be evaluated on a laptop before it reaches an intersection.

What is in the repository

Path Contents
decision_pipeline.py The three-stage decision logic, imported by both the deployed bridge and the testbench.
decision_testbench.py Offline scenario runner: fisheye camera model, detection failure and localisation error models, ground-truth danger labelling, optimizer, Monte Carlo, latency sweep.
bikeped/scenarios/ Scenario library: the 24 conformance scenarios and the suites added next to them.
bikeped/sim/ CARLA renderer for Unreal Engine 4 and Unreal Engine 5 builds.
simulator/index.html Browser simulator in a single HTML file.
sim_visualizer.py Schematic 3D renderer that writes one MP4 per scenario.
calibration/ Fisheye intrinsic calibration from checkerboard frames.
bridge_starter/ Deployment starter kit: one script with a USER CONFIG block.
run_experiments.py Runs every experiment in the paper in sequence.
config.yaml, camera_calibration.json Runtime parameters and calibrated intrinsics of the deployed system.

The repository layout page lists every file.

First steps

  • Install

    Python 3.10 or newer, one requirements file, and the optional pieces for CARLA, the bridge kit and the docs.

  • Quickstart

    Run the testbench, compare decision rules, render a scenario and call the pipeline from Python.

  • Repository layout

    An annotated tree, and which files the paper numbers come from.

Understand the system

  • How it works

    The path of one frame from the camera to the warning light.

  • Perception

    The fisheye model, ground-plane localisation and the bounding-box error model.

  • Decision pipeline

    The three stages, their parameters and the decision-rule baselines.

  • Safety model

    Braking profiles and how a frame is labelled dangerous.

  • Uncertainty

    The detection failure and localisation noise models used by the testbench.

Run simulations

  • Simulators

    The three simulators and when to use which.

  • Scenarios

    The conformance suite, the extended suites, and how to write or generate your own.

  • Browser simulator

    The decision pipeline running live in a web page, with nothing to install.

  • Testbench

    The offline runner behind the tables in the paper.

  • CARLA

    Photorealistic renders of the same scenarios through the calibrated lens model, on UE4 and UE5.

Reproduce the paper

  • Experiments

    One command for everything, and one command per table and figure.

  • Optimizer

    How the selected parameters were found by differential evolution.

  • Latency

    The camera latency sweep and the per-step latency report.

  • Placement

    Camera height, pitch and road width.

  • Dataset

    The scenarios, per-frame labels and videos published on Hugging Face.

Deploy

  • Calibration

    Capture checkerboard frames and fit the lens model.

  • Bridge starter kit

    A self-contained live system to adapt to a new intersection.

  • Tuning

    The proximity floor and rider suppression for your detector and camera geometry.

  • Hardware

    The camera, the compute and the indicator light.

Look something up

  • Command line

    Every script and module entry point with its flags.

  • Configuration

    Every key of config.yaml and camera_calibration.json.

  • File formats

    Scenario dictionaries, render manifests, ground-truth files and the catalog.

  • Python API

    Module reference built from the docstrings.

  • FAQ

    Short answers to questions that come up when running or adapting the system.

  • Changelog

    What changed, by date.

  • Citing

    The BibTeX entry and the abstract.