Package: invertedai
InvertedAIOverviewInverted AI provides an API for controlling non-playable characters (NPCs) in autonomous driving simulations,
available as either aREST APIor aPython SDK, (andC++ SDK) built on top of it. Using the API requires an access key -
create an account on ouruser portalto get one.  New users are given keys preloaded with an API access budget; researcher users affiliated to academic institutions generally receive a sufficient amount of credits to conduct their research for free.  This page describes how to get started quickly. For more in-depth understanding,
see theAPI usage guide, and detailed documentation for theREST API,
thePython SDK, and theC++ SDK.
To understand the underlying technology and why it's necessary for autonomous driving simulations, visit theInverted AI website.Getting startedInstallationFor installing the Python package fromPyPI:pipinstall--upgradeinvertedaiThe Python client SDK isopen source,
so you can also download it and build locally.Minimal exampleimportnumpyasnpimportmatplotlib.pyplotaspltimportinvertedaiasiailocation="iai:drake_street_and_pacific_blvd"# select one of available locationsiai.add_apikey('')# specify your key here or through the IAI_API_KEY variableprint("Begin initialization.")# get static information about a given location including map in osm# format and list traffic lights with their IDs and locations.location_info_response=iai.location_info(location=location)# initialize the simulation by spawning NPCsresponse=iai.initialize(location=location,# select one of available locationsagent_count=10,# number of NPCs to spawnget_birdview=True,# provides simple visualization - don't use in productiontraffic_light_state_history=None)agent_attributes=response.agent_attributes# get dimension and other attributes of NPCslocation_info_response=iai.location_info(location=location)rendered_static_map=location_info_response.birdview_image.decode()scene_plotter=iai.utils.ScenePlotter(rendered_static_map,location_info_response.map_fov,(location_info_response.map_center.x,location_info_response.map_center.y),location_info_response.static_actors)scene_plotter.initialize_recording(agent_states=response.agent_states,agent_attributes=agent_attributes,)print("Begin stepping through simulation.")for_inrange(100):# how many simulation steps to execute (10 steps is 1 second)# query the API for subsequent NPC predictionsresponse=iai.drive(location=location,agent_attributes=agent_attributes,agent_states=response.agent_states,recurrent_states=response.recurrent_states,get_birdview=True,light_recurrent_states=response.light_recurrent_states,)# save the visualizationscene_plotter.record_step(response.agent_states,response.traffic_lights_states)print("Simulation finished, save visualization.")# save the visualization to diskfig,ax=plt.subplots(constrained_layout=True,figsize=(50,50))gif_name='minimal_example.gif'scene_plotter.animate_scene(output_name=gif_name,ax=ax,direction_vec=False,velocity_vec=False,plot_frame_number=True)print("Done")Stateful CosimulationConceptually, the API is used to establish synchronous co-simulation between your own simulator running locally on
your machine and the NPC engine running on Inverted AI servers. The basic integration in Python looks like this.fromtypingimportListimportnumpyasnpimportinvertedaiasiaiimportmatplotlib.pyplotaspltiai.add_apikey('')# specify your key here or through the IAI_API_KEY variableclassLocalSimulator:"""Mock up of a local simulator, where you control the ego vehicle. This example only supports single ego vehicle."""def__init__(self,ego_state:iai.common.AgentState,npc_states:List[iai.common.AgentState]):self.ego_state=ego_stateself.npc_states=npc_statesdef_step_ego(self):"""The simple motion model drives forward with constant speed.The ego agent ignores the map and NPCs for simplicity."""dt=0.1dx=self.ego_state.speed*dt*np.cos(self.ego_state.orientation)dy=self.ego_state.speed*dt*np.sin(self.ego_state.orientation)self.ego_state=iai.common.AgentState(center=iai.common.Point(x=self.ego_state.center.x+dx,y=self.ego_state.center.y+dy),orientation=self.ego_state.orientation,speed=self.ego_state.speed,)defstep(self,predicted_npc_states):self._step_ego()# ego vehicle moves first so that it doesn't see future NPC movementself.npc_states=predicted_npc_statesreturnself.ego_stateprint("Begin initialization.")location='iai:ubc_roundabout'iai_simulation=iai.BasicCosimulation(# instantiate a stateful wrapper for Inverted AI APIlocation=location,# select one of available locationsagent_count=5,# how many vehicles in total to use in the simulationego_agent_mask=[True,False,False,False,False],# first vehicle is ego, rest are NPCsget_birdview=False,# provides simple visualization - don't use in productiontraffic_lights=True,# gets the traffic light states and used for initialization and steping the simulation)location_info_response=iai.location_info(location=location)rendered_static_map=location_info_response.birdview_image.decode()scene_plotter=iai.utils.ScenePlotter(rendered_static_map,location_info_response.map_fov,(location_info_response.map_center.x,location_info_response.map_center.y),location_info_response.static_actors)scene_plotter.initialize_recording(agent_states=iai_simulation.agent_states,agent_attributes=iai_simulation.agent_attributes,)print("Begin stepping through simulation.")local_simulation=LocalSimulator(iai_simulation.ego_states[0],iai_simulation.npc_states)for_inrange(100):# how many simulation steps to execute (10 steps is 1 second)# query the API for subsequent NPC predictions, informing it how the ego vehicle actediai_simulation.step([local_simulation.ego_state])# collect predictions for the next time steppredicted_npc_behavior=iai_simulation.npc_states# execute predictions in your simulator, using your actions for the ego vehicleupdated_ego_agent_state=local_simulation.step(predicted_npc_behavior)# save the visualization with ScenePlotterscene_plotter.record_step(iai_simulation.agent_states)print("Simulation finished, save visualization.")# save the visualization to diskfig,ax=plt.subplots(constrained_layout=True,figsize=(50,50))gif_name='cosimulation_minimal_example.gif'scene_plotter.animate_scene(output_name=gif_name,ax=ax,direction_vec=False,velocity_vec=False,plot_frame_number=True)print("Done")To quickly check out how Inverted AI NPCs
behave, try ourColab,
where all agents are NPCs, or go to ourgithub repositoryto execute it locally.
When you're ready to try our NPCs with a real simulator, see the exampleCARLA integration.
The examples are currently only provided in Python, but if you want to use the API from another language,
you can use theREST APIdirectly.