tactics2d.dataset_parser

Dataset parser module.

Argoverse2Parser

This class implements a parser for Argoverse 2 dataset. The default size of the participants are referred to the official visualization toolkit.

Reference

Wilson, Benjamin, et al. "Argoverse 2: Next generation datasets for self-driving perception and forecasting." arXiv preprint arXiv:2301.00493 (2023).

parse_map(file, folder)

This function parses a map from a single Argoverse json file.

Parameters:

• file (str) –

  The name of the map file. The file is expected to be a json file (.json).

• folder (str) –

  The path to the folder containing the map data.

Returns:

• map_ ( Map ) –

  A map object.

parse_trajectory(file, folder)

This function parses trajectories from a single Argoverse parquet file. Because the duration of the scenario has been well articulated, the parser will not provide an option to select time range within a single scenario. The states were collected at 10Hz.

Parameters:

• file (str) –

  The name of the trajectory data file. The file is expected to be a parquet file.

• folder (str) –

  The path to the folder containing the trajectory data.

Returns:

• participants ( dict ) –

  A dictionary of participants. The keys are the ids of the participants. The values are the participants.

• actual_stamp_range ( Tuple[int, int] ) –

  The actual time range of the trajectory data. The first element is the start time. The second element is the end time. The unit of time stamp is millisecond (ms).

CitySimParser

This class implements a parser of the CitySim Dataset.

Reference

Zheng, Ou, et al. "CitySim: A drone-based vehicle trajectory dataset for safety-oriented research and digital twins." Transportation research record 2678.4 (2024): 606-621.

get_time_range(file, folder)

This function gets the time range of a single trajectory data file.

Parameters:

• file (str) –

  The name of the trajectory data file. The file is expected to be a csv file.

• folder (str) –

  The path to the folder containing the trajectory data.

Returns:

• actual_time_range ( Tuple[int, int] ) –

  The time range of the trajectory data. The first element is the start time. The second element is the end time. The unit of time stamp is millisecond.

parse_trajectory(file, folder, time_range=None, ids=None)

This function parses the trajectory data of CitySim datasets. The states were collected at 30Hz.

Parameters:

• file (str) –

  The name of the trajectory data file. The file is expected to be a csv file.

• folder (str) –

  The path to the folder containing the trajectory data.

• time_range (Tuple[int, int], default: None ) –

  The time range of the trajectory data to parse. The unit of time stamp is millisecond. If the time range is not given, the parser will parse the whole trajectory data. Defaults to None.

• ids (list, default: None ) –

  The list of trajectory ids that needs to parse. If this value is not specified, the parser will parse all the trajectories within the time range. Defaults to None.

Returns:

• participants ( dict ) –

  A dictionary of participants. The keys are the ids of the participants. The values are the participants.

• actual_stamp_range ( Tuple[int, int] ) –

  The actual time range of the trajectory data. The first element is the start time. The second element is the end time. The unit of time stamp is millisecond.

DLPParser

This class implements a parser of the Dragon Lake Parking Dataset.

Reference

Shen, Xu, et al. "Parkpredict: Motion and intent prediction of vehicles in parking lots." 2020 IEEE Intelligent Vehicles Symposium (IV). IEEE, 2020.

parse_trajectory(file, folder, time_range=None)

This function parses trajectories from a series of DLP dataset files. The states were collected at 25Hz.

Parameters:

• file (str) –

  The name of the trajectory file or the id as a string. The file is expected to be a json file (.json). The parser will extract the integer id from the string and parse the trajectory data from the following files: DJI_%04d_agents.json % file_id, DJI_%04d_frames.json % file_id, DJI_%04d_instances.json % file_id, DJI_%04d_obstacles.json % file_id.

• folder (str) –

  The path to the folder containing the trajectory data.

• time_range (Tuple[int, int], default: None ) –

  The time range of the trajectory data to parse. The unit of time stamp is millisecond (ms). If the time range is not given, the parser will parse the whole trajectory data.

Returns:

• participants ( dict ) –

  A dictionary of vehicles. The keys are the ids of the vehicles. The values are the vehicles.

• actual_stamp_range ( Tuple[int, int] ) –

  The actual time range of the trajectory data. The first element is the start time. The second element is the end time. The unit of time stamp is millisecond (ms).

DriveInsightDParser

This class implements a parser of the DriveInsight Dataset.

Reference

Zhdanov, Pavlo, et al. "DriveInsight: CCTV-based dataset capturing real-world scenarios." IEEE Transactions on Circuits and Systems for Video Technology, 2025 (under review).

parse(scenario_id, folder, map_name='cz_zlin.xodr')

This function parses a complete DriveInsightD scenario including trajectory data, road network, and environment metadata.

Parameters:

• scenario_id (str) –

  The scenario identifier.

• folder (str) –

  The path to the folder containing the scenario files.

• map_name (str, default: 'cz_zlin.xodr' ) –

  The filename of the OpenDRIVE road network. Defaults to "cz_zlin.xodr".

Returns:

• scenario ( dict ) –

  A dictionary with the following keys:

  • scenario_id (str): The scenario identifier.
  • metadata (dict): Environment metadata with keys time, weather, precipitation, and friction.
  • time_range (Tuple[int, int]): Start and end timestamps in milliseconds.
  • map (Map): The parsed Tactics2D Map object.
  • participants (dict): The parsed participant objects.

parse_trajectory(file, folder, stamp_range=None)

This function parses trajectories from a DriveInsightD OpenSCENARIO file.

Parameters:

• file (Union[int, str]) –

  The scenario identifier used to locate the file {file}_scenario.xosc.

• folder (str) –

  The path to the folder containing the scenario file.

• stamp_range (Optional[Tuple[float, float]], default: None ) –

  The time range of the trajectory data to parse. The unit of time stamp is millisecond (ms). If the stamp range is not given, the parser will parse the whole trajectory data. Defaults to None.

Returns:

• participants ( dict[str, Union[Vehicle, Cyclist, Pedestrian, Other]] ) –

  A dictionary mapping participant names to their objects.

• actual_stamp_range ( Tuple[int, int] ) –

  The actual time range of the trajectory data. The first element is the start time and the second is the end time. The unit of time stamp is millisecond (ms).

InteractionParser

This class implements a parser for INTERACTION dataset.

Reference

Zhan, Wei, et al. "Interaction dataset: An international, adversarial and cooperative motion dataset in interactive driving scenarios with semantic maps." arXiv preprint arXiv:1910.03088 (2019).

get_time_range(file, folder)

This function gets the time range of a single trajectory data file.

Parameters:

• file (str) –

  The name of the trajectory file or the id as a string. The parser will extract the integer id from the string and parse the trajectory data from the following files: vehicle_tracks_%03d.csv % file_id, pedestrian_tracks_%03d.csv % file_id.

• folder (str) –

  The path to the folder containing the trajectory data.

Returns:

• actual_time_range ( Tuple[int, int] ) –

  The time range of the trajectory data. The first element is the start time. The second element is the end time. The unit of time stamp is millisecond (ms).

parse_pedestrians(participants, file_path, time_range=None)

This function parses the pedestrian trajectory file in INTERACTION dataset. Because the original dataset does not distinguish cyclist and pedestrian, this function calls a type guesser, which is built from other datasets, to guess the type of the participants.

Parameters:

• participants (dict) –

  A dictionary of participants.

• file_path (str) –

  The path to the pedestrian trajectory file.

• time_range (Tuple[int, int], default: None ) –

  The time range of the trajectory data to parse. The unit of time stamp is millisecond (ms). If the time range is not given, the parser will parse the whole trajectory data.

Returns:

• participants ( dict ) –

  A dictionary of participants. The keys are the ids of the participants. The values are the participants.

• actual_stamp_range ( Tuple[int, int] ) –

  The actual time range of the trajectory data. The first element is the start time. The second element is the end time. The unit of time stamp is millisecond (ms).

parse_trajectory(file, folder, time_range=None)

Parse the trajectory data of INTERACTION dataset. The states were collected at 10Hz.

Parameters:

• file (str) –

  The name of the trajectory file or the id as a string. The parser will extract the integer id from the string and parse the trajectory data from the following files: vehicle_tracks_%03d.csv % file_id, pedestrian_tracks_%03d.csv % file_id.

• folder (str) –

  The path to the folder containing the trajectory data.

• time_range (Tuple[int, int], default: None ) –

  The time range of the trajectory data to parse. The unit of time stamp is millisecond (ms). If the time range is not given, the parser will parse the whole trajectory data.

Returns:

• participants ( dict ) –

  A dictionary of participants. The keys are the ids of the participants. The values are the participants.

• actual_stamp_range ( Tuple[int, int] ) –

  The actual time range of the trajectory data. The first element is the start time. The second element is the end time. The unit of time stamp is millisecond (ms).

parse_vehicle(file_path, time_range=None)

This function parses the vehicle trajectory file in INTERACTION dataset.

Parameters:

• file_path (str) –

  The path to the vehicle trajectory file.

• time_range (Tuple[int, int], default: None ) –

  The time range of the trajectory data to parse. The unit of time stamp is millisecond (ms). If the time range is not given, the parser will parse the whole trajectory data.

Returns:

• vehicles ( dict ) –

  A dictionary of vehicles. The keys are the ids of the vehicles. The values are the vehicles.

• actual_stamp_range ( Tuple[int, int] ) –

  The actual time range of the trajectory data. The first element is the start time. The second element is the end time. The unit of time stamp is millisecond (ms).

LevelXParser

This class implements a parser for the series of datasets collected by the Institute for Automotive Engineering (ika) of RWTH Aachen University. Because the commercial version of the datasets are held by LevelXData, we call this series of datasets LevelX-series datasets. The datasets include: highD, inD, rounD, exiD, uniD.

Reference

Krajewski, Robert, et al. "The highd dataset: A drone dataset of naturalistic vehicle trajectories on german highways for validation of highly automated driving systems." 2018 21st international conference on intelligent transportation systems (ITSC). IEEE, 2018.

Bock, Julian, et al. "The ind dataset: A drone dataset of naturalistic road user trajectories at german intersections." 2020 IEEE Intelligent Vehicles Symposium (IV). IEEE, 2020.

Krajewski, Robert, et al. "The round dataset: A drone dataset of road user trajectories at roundabouts in germany." 2020 IEEE 23rd International Conference on Intelligent Transportation Systems (ITSC). IEEE, 2020.

Moers, Tobias, et al. "The exiD dataset: A real-world trajectory dataset of highly interactive highway scenarios in Germany." 2022 IEEE Intelligent Vehicles Symposium (IV). IEEE, 2022.

__init__(dataset)

Initialize the parser.

Parameters:

• dataset (str) –

  The dataset you want to parse. The available choices are: highD, inD, rounD, exiD, uniD, ignorant of letter case.

get_location(file, folder)

This function retrieves the location from which a trajectory data file is obtained.

Parameters:

• file (str) –

  The name of the trajectory file or the id as a string. The parser will extract the integer id from the string and parse the trajectory data from the following files: %02d_recordingMeta.csv % file_id.

• folder (str) –

  The path to the folder containing the trajectory data.

Returns:

• location_id ( int ) –

  The id of the location.

get_time_range(file, folder)

This function gets the time range of a single trajectory data file.

Parameters:

• file (str) –

  The name of the trajectory file or the id as a string. The parser will extract the integer id from the string and parse the trajectory data from the following files: %02d_tracksMeta.csv % file_id.

• folder (str) –

  The path to the folder containing the trajectory data.

Returns:

• actual_time_range ( Tuple[int, int] ) –

  The time range of the trajectory data. The first element is the start time. The second element is the end time. The unit of time stamp is millisecond.

parse_map(**kwargs)

TODO: provide an API similar to other parsers to parse the map data. At present the map data are self-built and can be parsed by the Lanelet2Parser.

parse_trajectory(file, folder, time_range=None, ids=None)

This function parses the trajectory data of LevelX-series datasets. The states were collected at 25Hz.

Parameters:

• file (str) –

  The name of the trajectory file or the id as a string. The parser will extract the integer id from the string and parse the trajectory data from the following files: %02d_tracks.csv % file_id and %02d_tracksMeta.csv % file_id.

• folder (str) –

  The path to the folder containing the trajectory data.

• time_range (Tuple[int, int], default: None ) –

  The time range of the trajectory data to parse. The unit of time stamp is millisecond. If the time range is not given, the parser will parse the whole trajectory data. Defaults to None.

• ids (list, default: None ) –

  The list of trajectory ids that needs to parse. If this value is not specified, the parser will parse all the trajectories within the time range. Defaults to None.

Returns:

• participants ( dict ) –

  A dictionary of participants. The keys are the ids of the participants. The values are the participants.

• actual_stamp_range ( Tuple[int, int] ) –

  The actual time range of the trajectory data. The first element is the start time. The second element is the end time. The unit of time stamp is millisecond.

NGSIMParser

TODO: The support of NGSIM dataset is planned to be added before version 1.1.0.

parse_trajectory(file, folder, time_range=None, ids=None)

This function parses the trajectory data of the NGSIM dataset. The states were collected at 10Hz.

Parameters:

• file (int) –
• folder (str) –

  The path to the folder containing the trajectory data.

• time_range (Tuple[int, int], default: None ) –

  The time range of the trajectory data to parse. The unit of time stamp is millisecond. If the time range is not given, the parser will parse the whole trajectory data. Defaults to None.

• ids (list, default: None ) –

  The list of trajectory ids that needs to parse. If this value is not specified, the parser will parse all the trajectories within the time range. Defaults to None.

Returns:

• participants ( dict ) –

  A dictionary of participants. The keys are the ids of the participants. The values are the participants.

• actual_stamp_range ( Tuple[int, int] ) –

  The actual time range of the trajectory data. The first element is the start time. The second element is the end time. The unit of time stamp is millisecond."

NuPlanParser

Parser for the NuPlan dataset.

The parser converts NuPlan database logs and geopackage maps into Tactics2D participants and map elements. It keeps dataset-specific details in custom_tags while exposing common map semantics such as lane centerlines, boundaries, successors, neighbors, drivable areas, stop polygons, and traffic lights.

Reference

Caesar, Holger, et al. "nuplan: A closed-loop ml-based planning benchmark for autonomous vehicles." arXiv preprint arXiv:2106.11810 (2021).

get_location(file, folder)

Get the NuPlan location of a single trajectory database.

parse_map(file, folder=None)

Parse a NuPlan geopackage map into a Tactics2D Map.

Parameters:

• file (str) –

  The path or name of a NuPlan map.gpkg file.

• folder (Optional[str], default: None ) –

  Optional folder containing file.

Returns:

• Map –

  A Tactics2D map populated with common lane-level semantics.

parse_trajectory(file, folder, time_range=None)

Parse trajectories from a single NuPlan database file.

Parameters:

• file (str) –

  The name or path of the NuPlan sqlite database file.

• folder (str) –

  The folder containing file.

• time_range (Tuple[int, int], default: None ) –

  Optional millisecond range relative to 2021-01-01 00:00:00. When omitted, the whole database is parsed.

Returns:

• dict –

  (participants, actual_time_range) where participants are

• Tuple[int, int] –

  Tactics2D participant objects and the range is in milliseconds.

WOMDParser

This class implements a parser for Waymo Open Motion Dataset (WOMD).

Reference

Ettinger, Scott, et al. "Large scale interactive motion forecasting for autonomous driving: The waymo open motion dataset." Proceedings of the IEEE/CVF International Conference on Computer Vision. 2021.

Because loading the tfrecord file is time consuming, the trajectory and the map parsers provide two ways to load the file. The first way is to load the file directly from the given file path. The second way is to load the file from a tfrecord.tfrecord_iterator object. If the tfrecord.tfrecord_iterator object is given, the parser will ignore the file path.

get_scenario_ids(dataset, cache_data=False)

This function get the list of scenario ids from the given tfrecord file.

Parameters:

• dataset (tfrecord_iterator) –

  The dataset to parse.

• cache_data (bool, default: False ) –

  If True, also cache the raw data bytes for each scenario.

Returns:

• id_list ( List[str] ) –

  A list of scenario ids looking like ["637f20cafde22ff8", ...].

• Union[List[str], Tuple[List[str], List[bytes]]] –

  If cache_data is True, returns a tuple (id_list, data_list) where data_list contains

• Union[List[str], Tuple[List[str], List[bytes]]] –

  the raw bytes for each scenario.

parse_map(scenario_id=None, **kwargs)

This function parses the map from a single WOMD file.

Parameters:

• scenario_id (str, default: None ) –

  The id of the scenario to parse. If the scenario id is not given, the first scenario in the file will be parsed.

Other Parameters:

• dataset (tfrecord_iterator) –

  The dataset to parse.

• file (str) –

  The name of the trajectory file. The file is expected to be a tfrecord file (.tfrecord).

• folder (str) –

  The path to the folder containing the tfrecord file.

Returns:

• map_ ( Map ) –

  A map object.

Raises:

• KeyError –

  Either dataset or file and folder should be given as keyword arguments.

parse_trajectory(scenario_id=None, **kwargs)

This function parses trajectories from a single WOMD file. Because the duration of the scenario has been well articulated, the parser will not provide an option to select time range within a single scenario. The states were collected at 10Hz.

Parameters:

• scenario_id (Union[str, int], default: None ) –

  The id of the scenario to parse. If the scenario id is a string, the parser will search for the scenario id in the file. If the scenario id is an integer, the parser will parse scenario_id-th scenario in the file. If the scenario id is None or is not found, the first scenario in the file will be parsed.

Other Parameters:

• dataset (tfrecord_iterator) –

  The dataset to parse.

• file (str) –

  The name of the trajectory file. The file is expected to be a tfrecord file (.tfrecord).

• folder (str) –

  The path to the folder containing the tfrecord file.

Returns:

• participants ( dict ) –

  A dictionary of participants. If the scenario id is not found, return None.

• actual_time_range ( Tuple[int, int] ) –

  The actual time range of the trajectory data. The first element is the start time. The second element is the end time. The unit of time stamp is millisecond.

Raises:

• KeyError –

  Either dataset or file and folder should be given as keyword arguments.