Utility Scripts

Run these commands from the OpenCDA repository root in the OpenCDA container, unless stated otherwise. For commands connecting to CARLA, set CARLA_HOST as in Connect from OpenCDA.

Artery build and frontend commands are in Runtime Commands and Targets.

CARLA/SUMO Map Conversion Utilities

We provide helper scripts for preparing SUMO map assets from CARLA maps.

These scripts are useful when a CARLA map has to be converted into SUMO-compatible files:

• .net.xml: SUMO road network file

• .poly.xml: SUMO polygon file with static environment objects

The scripts are located in OpenCDA’s scripts directory. For conversion dependencies and an ordered workflow, see Maps and SUMO Assets. Paths under opencda/sumo-assets refer to the host SUMO assets bind mount.

SUMO Network Generation netconvert_carla.py

This utility generates a SUMO .net.xml file from CARLA/OpenDRIVE map data.

It can work in two modes:

• convert a local .xodr OpenDRIVE file

• read OpenDRIVE data from the currently loaded CARLA world using --from-carla

The script uses SUMO netconvert, so SUMO_HOME must be configured and SUMO tools must be available in the environment.

Usage

python scripts/netconvert_carla.py [xodr_file] --output OUTPUT

or, when reading the map directly from CARLA:

python scripts/netconvert_carla.py \
  --from-carla \
  --carla-host "$CARLA_HOST" \
  --carla-port CARLA_PORT \
  --carla-map CARLA_MAP \
  --output OUTPUT

Arguments

• xodr_file: optional path to a local OpenDRIVE .xodr file. It is required unless --from-carla is used.

Options

• --output, -o: path to the generated SUMO .net.xml file

• --from-carla: read OpenDRIVE data from the currently loaded CARLA world

• --carla-host: CARLA server host

• --carla-port: CARLA server port

• --carla-timeout: CARLA API timeout in seconds

• --carla-map: CARLA map to load if it is not already active

• --guess-tls: infer traffic lights at intersections

Example

Create the output directory first with mkdir -p opencda/sumo-assets/maps/Town12.

python scripts/netconvert_carla.py \
  --from-carla \
  --carla-host "$CARLA_HOST" \
  --carla-map Town12 \
  --output opencda/sumo-assets/maps/Town12/Town12.generated.net.xml

SUMO Polygon Generation polyconvert_carla.py

This utility generates a SUMO .poly.xml file from static objects in a CARLA map.

It uses an existing SUMO .net.xml file for coordinate conversion and boundary clipping, then scans the CARLA world and writes selected static objects as SUMO polygons.

Usage

python scripts/polyconvert_carla.py \
  --net-file NET_FILE \
  --output OUTPUT \
  --carla-host "$CARLA_HOST" \
  --carla-map CARLA_MAP

Options

• --net-file: existing SUMO .net.xml file

• --output, --poly-output, -o: output SUMO .poly.xml file

• --carla-host: CARLA server host

• --carla-port: CARLA server port

• --carla-timeout: CARLA API timeout in seconds

• --carla-map: CARLA map to load if it is not already active

• --labels: comma-separated CARLA semantic labels to export

• --bounds: explicit CARLA scan bounds in min_x,min_y,max_x,max_y format

• --bounds-margin: additional margin around scan bounds

• --boundary-margin: additional margin around the SUMO network boundary

• --stream-distance: CARLA tile streaming distance

• --scan-step: distance between scan positions

• --settle-ticks: number of ticks to wait after moving the spectator

• --scan-altitude: spectator altitude during scanning

• --min-height: minimum object height

• --max-area: maximum polygon footprint area

• --max-wall-thickness: maximum wall thickness filter

• --verbose: enable verbose logging

Example

python scripts/polyconvert_carla.py \
  --net-file opencda/sumo-assets/maps/Town10HD/Town10HD.net.xml \
  --output opencda/sumo-assets/maps/Town10HD/Town10HD.generated.poly.xml \
  --carla-host "$CARLA_HOST" \
  --carla-map Town10HD

CARLA Spectator Utilities

We also provide small helper scripts for reading and setting the CARLA spectator position.

Get Spectator Position

python scripts/get_spectator_position.py \
  --carla-host "$CARLA_HOST" \
  --carla-port 2000

This prints the current spectator location and rotation.

Set Spectator Position

echo "10.0,20.0,50.0" | python scripts/set_spectator_position.py \
  --carla-host "$CARLA_HOST" \
  --carla-port 2000

This sets the spectator location from standard input.

Video Generation Utility make_video.py

This utility requires the ffmpeg executable on PATH and converts a sequence of rendered frames into a video file. Run ffmpeg -version first. Install FFmpeg in the environment used for conversion if it is absent. It is typically used to visualize simulation outputs generated by OpenCDA, for example 3D or BEV perception results.

Usage

python scripts/make_video.py [-h] [--framerate FRAMERATE] [--rotate ROTATE] [--pattern PATTERN] input_dir output_path

Arguments

• input_dir: directory containing input image frames

• output_path: path to the output video file, for example video.mp4

Options

• --framerate: frame rate in frames per second

• --rotate: rotate frames counter-clockwise, valid values are 90, 180, 270

• --pattern: filename pattern for the image sequence in glob format

Example

python scripts/make_video.py \
  simulation_output/coperception/vis_3d/v2xp_datadump_town06_carla_2026_03_24_09_56_21 \
  simulation_output/coperception/v2xp_datadump_town06_carla_3d.mp4