Logs, Scenarios, & Debugging#

Overview#

Capturing data to and from the API can be useful for several purposes. The IAI SDK provides features for producing logs for several use cases.

Debug Logs#

Description#

Debug logs are relatively simple in comparison to scenario logs. These logs capture the raw data of all requests and responses to and from the API. In the case of the LARGE_DRIVE and LARGE_INITIALIZE tools, the data is formatted into its serializable form before being divided into individual API calls.

class invertedai.logs.debug_logger.DebugLogger(debug_dir_path: Optional[str] = None)[source]#

A tool for capturing debug logs which contain all serialized data from every request and response.

Parameters:: debug_log_path – The full path to the debug log directory where debug logs are written.

classmethod read_log_from_path(debug_log_path: str, is_visualize_log: bool = False, is_reproduce_log: bool = False, **kwargs)[source]#

A convenient entry point for quickly visualizing and/or reproducing a given debug log.

Parameters:

log_data – A loaded JSON dictionary of a debug log.
is_visualize_log – A flag to control whether the log is visualized. Please refer to the appropriate function for the relevant keyword arguments.
is_reproduce_log – A flag to control whether the log is reproduced. Please refer to the appropriate function for the relevant keyword arguments.

classmethod reproduce_log(log_data: Dict, gif_name: str = './debug_log_reproduction.gif', fov: int = 100, map_center: Optional[Tuple[float, float]] = None, use_log_seed: bool = True)[source]#

Given the initial state captured in the debug log and using all relevant information, attempt to reproduce the simulation from the debug log and visualize it for comparison with the original. This assumes the debug log was captured in chronological order by simulated time step.

Parameters:

log_data – A loaded JSON dictionary of a debug log.
gif_name – The path and name of the resulting GIF file.
fov – The field of view in metres for the birdview visualization.
map_center – The coordinates within the map on which to centre the visualization which is especially useful for large maps.
use_log_seed – A flag for whether to use the random seed in the debug log or input a value of None to DRIVE.

classmethod visualize_log(log_data: Dict, gif_name: str = './debug_log_visualization.gif', fov: int = 100, map_center: Optional[Tuple[float, float]] = None)[source]#

Visualize a debug log using the SDK visualizer tools. This assumes the debug log was captured in chronological order by simulated time step.

Parameters:

log_data – A loaded JSON dictionary of a debug log.
gif_name – The path and name of the resulting GIF file.
fov – The field of view in metres for the birdview visualization.
map_center – The coordinates within the map on which to centre the visualization which is especially useful for large maps.

Example Usage#

Capturing Debug Logs#

Capturing debug logs is a straight forward process, simply set the IAI_LOGGER_PATH environment variable. For example, in a Linux terminal, run the following command to set the path of a directory in which the debug logs will be written:

export IAI_LOGGER_PATH="<INSERT_DIRECTORY_PATH_HERE>"

If the directory does not exist, the python script will attempt to create the directory so that JSON debug logs may be written to that path.

Running Diagnostics#

While debug logs can be useful in capturing implementation issues, parsing the raw data can be difficult. The diagnostic tool can be used to check for common mistakes that MIGHT cause potential issues. The diagnostic tool will parse a debug log and print information on the command line regarding what could be causing degradation in performance. The diagnostic tool can be run directly by calling the diagnostic script with a path to the debug log file.

class invertedai.logs.diagnostics.DiagnosticTool(debug_log_path: str, ego_indexes: Optional[List[int]] = None)[source]#

A user-side tool that examines a debug log checking for common implementation mistakes and provides feedback.

Parameters:

debug_log_path – The full path to the debug log file to be loaded and analyzed.
ego_indexes – A list of index IDs for ego vehicles that will be analyzed differently (e.g. it is expected that the state of an ego vehicle may be modified external to the API).

full_diagnostic_test()[source]#: Main access point for this class. This function runs all available diagnostic tests and prints human-readable feedback for the benefit of a user to fix issues in their integration.

Scenario Logs#

Description#

This log type is designed primarily to capture scenarios and simulation rollouts of interest. These scenarios can then be loaded, replayed, and modified using the same tool. The data format and the specific tools with their primary functions are shown below.

class invertedai.logs.logger.ScenarioLog(*, agent_states: List[List[AgentState]], agent_properties: List[AgentProperties], traffic_lights_states: Optional[List[Dict[int, TrafficLightState]]] = None, location: str, rendering_center: Optional[Tuple[float, float]] = None, rendering_fov: Optional[int] = None, lights_random_seed: Optional[int] = None, initialize_random_seed: Optional[int] = None, drive_random_seed: Optional[int] = None, initialize_model_version: Optional[str] = 'best', drive_model_version: Optional[str] = 'best', light_recurrent_states: Optional[List[LightRecurrentState]] = None, recurrent_states: Optional[List[RecurrentState]] = None, waypoints: Optional[Dict[str, List[Point]]] = None)[source]#

A log containing simulation information for storage, replay, or an initial state from which a simulation can be continued. Some data fields contain data for all historic time steps while others contain information for the most recent time step to be used to continue a simulation.

agent_properties: List[AgentProperties]#: Agent properties data for all agents in this scenario/log.

agent_states: List[List[AgentState]]#: Historic data for all agents states up until the most recent time step.

drive_model_version: Optional[str]#: Please refer to the documentation of drive() for information on the api_model_version parameter.

drive_random_seed: Optional[int]#: Please refer to the documentation of drive() for information on the random_seed parameter.

initialize_model_version: Optional[str]#: Please refer to the documentation of initialize() for information on the api_model_version parameter.

initialize_random_seed: Optional[int]#: Please refer to the documentation of initialize() for information on the random_seed parameter.

light_recurrent_states: Optional[List[LightRecurrentState]]#: As of the most recent time step. Please refer to the documentation of drive() for further information on this parameter.

lights_random_seed: Optional[int]#: Controls the stochastic aspects of the the traffic lights states.

location: str#: Location name in IAI format.

recurrent_states: Optional[List[RecurrentState]]#: As of the most recent time step. Please refer to the documentation of drive() for further information on this parameter.

rendering_center: Optional[Tuple[float, float]]#: Please refer to the documentation of location_info() for information on this parameter.

rendering_fov: Optional[int]#: Please refer to the documentation of location_info() for information on this parameter.

traffic_lights_states: Optional[List[Dict[int, TrafficLightState]]]#: Historic data for all TrafficLightStatesDict up until the most recent time step.

waypoints: Optional[Dict[str, List[Point]]]#: As of the most recent time step. A list of waypoints keyed to agent ID’s not including waypoints already passed. These waypoints are not automatically populated into the agent properties.

class invertedai.logs.logger.LogWriter[source]#

A class for conveniently writing a log to a JSON log format.

drive(drive_response: DriveResponse)[source]#: Consume and store driving response information from a single timestep and append it to the end of the log.

classmethod export_log_to_file(log_path: str, scenario_log: ScenarioLog)[source]#: Class function to convert a given log data type into a JSON format and export it to a given file.

export_to_file(log_path: str, scenario_log: Optional[ScenarioLog] = None)[source]#: Convert the data currently contained within the log into a JSON format and export it to a given file. This function can furthermore be used to export a given scenario log instead of the log contained within the object.

initialize(location: Optional[str] = None, location_info_response: Optional[LocationResponse] = None, init_response: Optional[InitializeResponse] = None, lights_random_seed: Optional[int] = None, initialize_random_seed: Optional[int] = None, drive_random_seed: Optional[int] = None, scenario_log: Optional[ScenarioLog] = None)[source]#: Consume and store all initial information within a ScenarioLog data object. If random seed information is desired to be stored, it must be given separately but is not mandatory.

class invertedai.logs.logger.LogReader(log_path: str)[source]#

A class for conveniently reading in a log file then rendering it and/or plugging it into a simulation. Once the log is read, it is intended to be used in place of calling the API.

drive()[source]#: Read and make available state data from the current time step into the relevant member variables then increment the current time step so that this function may be called again. If the end of the log has been reached, return False otherwise return True.

initialize()[source]#: Read and make available state data from the 0th time step into the relevant state member variables e.g. agent_states. Furthermore, set the agent_properties state variable here analogously to how initialize() returns this information through the API.

reset_log()[source]#: In the case the log was modified, revert the log to its initial state after being read and clear all state data. Furthermore, change the current time step such that the first drive() time step can be read.

return_last_state()[source]#: Read and make available state data from the final time step contained within the log which is useful as a launching point for another simulation.

return_scenario_log(timestep_range: Optional[Tuple[int, int]] = None)[source]#: Return the original scenario log. Optionally choose a time range within the log of interest.

Example Usage#

Please click the following link to see an example of how to run a scenario log example. This example demonstrates running a sample scenario then writing to a log file, loading the sample log and visualizing it, then replaying the log but modifying it at a time step of interest.