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 :ref:`carla-client-shell`. Artery build and frontend commands are in :doc:`/reference/runtime`. 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 :doc:`/scenarios/maps`. 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** .. code-block:: bash python scripts/netconvert_carla.py [xodr_file] --output OUTPUT or, when reading the map directly from CARLA: .. code-block:: bash 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``. .. code-block:: bash 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** .. code-block:: bash 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** .. code-block:: bash 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 ~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash python scripts/get_spectator_position.py \ --carla-host "$CARLA_HOST" \ --carla-port 2000 This prints the current spectator location and rotation. Set Spectator Position ~~~~~~~~~~~~~~~~~~~~~~ .. code-block:: bash 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** .. code-block:: bash 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** .. code-block:: bash 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