Skip to content

Configuration reference

Two files hold the parameters of a site: config.yaml for runtime settings and camera_calibration.json for the calibrated lens. This page lists every key of both, its shipped value, and which code reads it.

Who reads what

Reader From config.yaml From camera_calibration.json
decision_testbench.py camera.height, camera.pitch_deg fov_deg, radius_px, frame_width, frame_height, pad_size, cx, cy, k1, k2
sim_visualizer.py --errors camera.height, camera.pitch_deg fov_deg, radius_px, frame_width, frame_height, pad_size, cx, cy
generate_figures.py loads the file through load_camera_calibration()
calibration/calibrate_fisheye.py writes the file
bikeped/sim/fisheye.py (CARLA fisheye view) camera.fov, camera.radius, camera.cx, camera.cy, camera.k1, camera.k2, camera.pitch_deg fov_deg, radius_px, cx, cy, k1, k2, which override the config.yaml values

No other code in this repository opens config.yaml. The remaining keys configure the live bridge of the reference deployment (mqtt_bridge.py), which is not included here. The starter kit does not read config.yaml either. It holds the same settings as constants in its USER CONFIG block, and the tables below name the matching constant where there is one.

Two consequences are worth knowing before you edit the file:

  • Changing the decision block does not change testbench results. The testbench takes its parameters from DecisionParams and PIPELINE_CONFIGS in decision_testbench.py, whose default entry carries the same values as the shipped decision block.
  • If config.yaml is missing, the testbench uses a camera height of 3.048 m and a pitch of 0. If camera_calibration.json is missing, it prints No camera_calibration.json found, using defaults and uses the defaults of FisheyeCamera.

config.yaml

video

Key Default Unit Meaning
use_webcam true Read the live camera instead of a file. Kit: USE_WEBCAM.
file_path "06022025_19.avi" Video file used when use_webcam is false. Kit: VIDEO_FILE.
process_every_k_frames 1 frames Frame subsampling factor of the live bridge. The kit processes every frame.

preprocessing

Key Default Unit Meaning
pad_size 3840 px The frame is centred on a black square of this side. Kit: INPUT_PAD_SIZE.
crop_size 3500 px Side of the centre crop taken from the padded square. All intrinsics refer to this cropped frame. Kit: INPUT_CROP_SIZE.

camera

Key Default Unit Meaning
height 3.6576 m Mounting height above the ground (12 ft). Read by the testbench. Kit: CAMERA_HEIGHT_M.
fov 197.90 deg Field of view across the image circle. Kit: CAMERA_FOV_DEG.
radius 1750 px Radius of the image circle. Kit: CAMERA_RADIUS_PX.
pitch_deg 0 deg Tilt of the optical axis. Negative looks down. Read by the testbench. Kit: CAMERA_PITCH_DEG.
cx, cy 1752.69, 1804.54 px Optical centre in the cropped frame. Kit: CAMERA_CX, CAMERA_CY.
projection "linear" Projection model, see projection names. Kit: CAMERA_PROJECTION.
k1, k2 0.0, 0.0 Radial terms of r = f (θ + k1 θ³ + k2 θ⁵), used with linear only. Set them from a calibration run with --fit-distortion. Kit: CAMERA_K1, CAMERA_K2.
latency_frames 0 frames Frames of measured camera latency to compensate by first-order kinematic prediction. 0 disables it. At 30 FPS one frame is 33 ms, so the value is the measured latency in milliseconds divided by 33.

The intrinsics appear twice, here and in camera_calibration.json. The testbench reads them from the JSON file. After a calibration run, calibrate_fisheye.py prints the camera.fov and camera.radius values to copy into this block, and camera.cx and camera.cy when the optical centre is more than 5 px from the frame centre.

detection

Key Default Unit Meaning
model_path "yolo11x.engine" Detector weights or TensorRT engine. The kit downloads yolo11xxl.pt instead, see YOLO_HF_FILE.
confidence 0.1 Detection confidence threshold. Kit: YOLO_CONF.
input_size 1280 px Inference size. Kit: YOLO_IMGSZ.
valid_classes [0, 1, 2, 3, 5, 7, 9, 31, 36, 37, 16] COCO class IDs kept. The code in this repository names 0 person, 1 bicycle, 2 car, 3 motorcycle, 5 bus, 7 truck, 9 traffic light and 16 dog. Kit: YOLO_CLASSES, which keeps the first six.
tracker "bytetrack.yaml" Tracker configuration of the live bridge. The kit tracks on the ground plane with its own GroundPlaneTracker.

decision

Key Default Unit Meaning
bike_memory_frames 58 frames Stage 2 stays open while a cyclist was seen within this many frames. Kit: DEC_BIKE_MEMORY_FRAMES.
prox_min 1.9 m Lower bound on the bike to pedestrian distance that can alert. Kit: DEC_PROX_MIN_M.
prox_max 24.8 m Upper bound on that distance. Kit: DEC_PROX_MAX_M.
prox_speed_min 0.147 m Minimum cyclist displacement over the lookback for an alert. Kit: DEC_PROX_SPEED_MIN.
lookback_frames 2 frames Lookback k of the closing check. Kit: DEC_LOOKBACK_FRAMES.
max_range 25 m Agents farther than this from the camera are skipped in stage 3. Kit: DEC_MAX_RANGE_M.
max_object_age 10 frames Listed in the file and in DecisionParams. DecisionPipeline has no such argument and no code in this repository reads the key.
speed_adaptive true Extend the upper bound to the cyclist's stopping distance when that is larger. Kit: DEC_SPEED_ADAPTIVE.
cyclist_reaction_s 0.84 s Perception-reaction time in the stopping distance. Kit: DEC_REACTION_S.
cyclist_decel_ms2 1.96 m/s² Deceleration in the stopping distance. Kit: DEC_DECEL_MS2.

The two braking values are the 85th-percentile field measurements of Martin and Bigazzi (2025) cited in decision_pipeline.py. The decision pipeline describes how each parameter enters the three stages.

The constructor defaults of DecisionPipeline are a different set (bike_memory_frames=77, prox_min=0.5, prox_max=20.7, prox_speed_min=0.098, lookback_frames=1). The testbench and the kit pass every parameter explicitly, so those defaults only apply if you construct the class yourself without arguments.

tracking

Key Default Unit Meaning
history_frames 5 frames Read by the live bridge only. The file gives no description.
min_track_points 4 points Read by the live bridge only. The file gives no description.
speed_window 4 samples Read by the live bridge only. DecisionPipeline estimates cyclist speed over a fixed window of 4 samples.

feedback

Key Default Unit Meaning
blinking true Read by the live bridge only. The file gives no description.
go_signal true Read by the live bridge only. The file gives no description.
sound_threshold 60 Read by the live bridge only. The kit throttles sounds with SOUND_THROTTLE_FRAMES.

mqtt

Key Default Unit Meaning
enabled true Publish track messages. Kit: MQTT_ENABLED.
broker "test.mosquitto.org" Broker host name. Kit: MQTT_BROKER.
port 1883 Broker port. Kit: MQTT_PORT.
topic "bikeped/intersection/tracks" Topic. Kit: MQTT_TOPIC.
username, password null, null Credentials. Kit: MQTT_USERNAME, MQTT_PASSWORD.
client_id "bikeped_tracker" Client identifier. Kit: MQTT_CLIENT_ID.
qos 0 Quality of service. Kit: MQTT_QOS.
publish_interval 1 Read by the live bridge only. The kit publishes every frame.

latency

Key Default Unit Meaning
enabled false Collect per-frame latency data. Kit: LATENCY_ENABLED, which defaults to True.
save_path "latency_data.npy" Output array. Kit: LATENCY_SAVE_PATH.
save_interval_frames 500 frames Checkpoint period. Kit: LATENCY_SAVE_INTERVAL.
warmup_frames 30 frames Frames discarded at start while the model warms up. Kit: LATENCY_WARMUP_FRAMES.

Top level

Key Default Unit Meaning
debug false Debug switch of the live bridge. Kit: DEBUG.
verbose false Verbose logging. Kit: VERBOSE.

camera_calibration.json

Written by calibrate_fisheye.py. The shipped file is the calibration of the reference camera.

camera_calibration.json
{
  "model": "equidistant",
  "cx": 1752.69,
  "cy": 1804.54,
  "focal_length": 1013.31,
  "fov_deg": 197.9,
  "radius_px": 1750.0,
  "k1": 0.0,
  "k2": 0.0,
  "rms_error_px": 4.6334,
  "num_frames": 42,
  "num_points": 1470,
  "frame_width": 3500,
  "frame_height": 3500,
  "pad_size": 3840,
  "crop_size": 3500
}
Key Shipped value Unit Meaning
model "equidistant" Projection model that was fitted. calibrate_fisheye.py always writes equidistant.
cx, cy 1752.69, 1804.54 px Optical centre in the cropped frame.
focal_length 1013.31 px/rad Equidistant focal length f in r = f θ.
fov_deg 197.9 deg Field of view derived from the focal length: 2 · radius_px · 180 / (f · π).
radius_px 1750.0 px Half the side of the cropped frame.
k1, k2 0.0, 0.0 Radial correction terms. Zero unless the run used --fit-distortion.
rms_error_px 4.6334 px RMS reprojection error of the fit.
num_frames 42 frames Checkerboard frames used.
num_points 1470 corners Corner observations used.
frame_width, frame_height 3500, 3500 px Size of the cropped frame the intrinsics refer to.
pad_size, crop_size 3840, 3500 px Preprocessing the calibration frames went through.

FisheyeCamera in the testbench does not read focal_length. It computes the focal length from fov_deg and radius_px, which gives the same 1013.3 px for the shipped file. The quality fields (rms_error_px, num_frames, num_points) and model are a record of the calibration run and are not used at runtime here.

The calibration script also writes a sibling camera_calibration.yaml with three blocks: calibration (the values above without the frame and preprocessing sizes), preprocessing (pad_size, crop_size) and config_yaml_updates (the camera.fov and camera.radius values for config.yaml).

Projection names

camera.projection and the kit's CAMERA_PROJECTION use the names in the first column. The calibration tools use the model names in the second.

Config name Model Formula
linear equidistant r = f · θ
equalarea equisolid r = 2f · sin(θ / 2)
stereographic stereographic r = 2f · tan(θ / 2)
orthographic orthographic r = f · sin(θ)

θ is the angle between the incoming ray and the optical axis, and r is the distance from the optical centre in pixels. calibrate_fisheye.py fits the equidistant model only. compare_fisheye_models.py fits all four on the same frames so you can check which one your lens follows.