Graphics

Environment rendering is done with pygame, which must be installed separately.

A window is created at the first call of env.render(). Its dimensions can be configured:

env = gym.make(
    "roundabout-v0",
    config={
        "screen_width": 640,
        "screen_height": 480
    }
)
env.reset()
env.render()

World surface

The simulation is rendered in a RoadSurface pygame surface, which defines the location and zoom of the rendered location. By default, the rendered area is always centered on the ego-vehicle. Its initial scale and offset can be set with the "scaling" and "centering_position" configurations, and can also be updated during simulation using the O,L keys and K,M keys, respectively.

Scene graphics

• Roads are rendered in the RoadGraphics class.

• Vehicles are rendered in the VehicleGraphics class.

API

class highway_env.envs.common.graphics.EnvViewer(env: AbstractEnv, config: dict | None = None)

A viewer to render a highway driving environment.

set_agent_display(agent_display: Callable) → None

Set a display callback provided by an agent

So that they can render their behaviour on a dedicated agent surface, or even on the simulation surface.

Parameters:

agent_display – a callback provided by the agent to display on surfaces

set_agent_action_sequence(actions: list[Action]) → None

Set the sequence of actions chosen by the agent, so that it can be displayed

Parameters:

actions – list of action, following the env’s action space specification

handle_events() → None

Handle pygame events by forwarding them to the display and environment vehicle.

display() → None

Display the road and vehicles on a pygame window.

get_image() → ndarray

The rendered image as a rgb array.

Gymnasium’s channel convention is H x W x C

window_position() → ndarray

the world position of the center of the displayed window.

close() → None

Close the pygame window.

class highway_env.road.graphics.WorldSurface(size: tuple[int, int], flags: object, surf: Surface)

A pygame Surface implementing a local coordinate system so that we can move and zoom in the displayed area.

pix(length: float) → int

Convert a distance [m] to pixels [px].

Parameters:

length – the input distance [m]

Returns:

the corresponding size [px]

pos2pix(x: float, y: float) → tuple[int, int]

Convert two world coordinates [m] into a position in the surface [px]

Parameters:

• x – x world coordinate [m]

• y – y world coordinate [m]

Returns:

the coordinates of the corresponding pixel [px]

vec2pix(vec: Tuple[float, float] | ndarray) → tuple[int, int]

Convert a world position [m] into a position in the surface [px].

Parameters:

vec – a world position [m]

Returns:

the coordinates of the corresponding pixel [px]

is_visible(vec: Tuple[float, float] | ndarray, margin: int = 50) → bool

Is a position visible in the surface? :param vec: a position :param margin: margins around the frame to test for visibility :return: whether the position is visible

move_display_window_to(position: Tuple[float, float] | ndarray) → None

Set the origin of the displayed area to center on a given world position.

Parameters:

position – a world position [m]

handle_event(event: Event) → None

Handle pygame events for moving and zooming in the displayed area.

Parameters:

event – a pygame event

class highway_env.road.graphics.LaneGraphics

A visualization of a lane.

STRIPE_SPACING: float = 4.33

Offset between stripes [m]

STRIPE_LENGTH: float = 3

Length of a stripe [m]

STRIPE_WIDTH: float = 0.3

Width of a stripe [m]

classmethod display(lane: AbstractLane, surface: WorldSurface) → None

Display a lane on a surface.

Parameters:

• lane – the lane to be displayed

• surface – the pygame surface

classmethod striped_line(lane: AbstractLane, surface: WorldSurface, stripes_count: int, longitudinal: float, side: int) → None

Draw a striped line on one side of a lane, on a surface.

Parameters:

• lane – the lane

• surface – the pygame surface

• stripes_count – the number of stripes to draw

• longitudinal – the longitudinal position of the first stripe [m]

• side – which side of the road to draw [0:left, 1:right]

classmethod continuous_curve(lane: AbstractLane, surface: WorldSurface, stripes_count: int, longitudinal: float, side: int) → None

Draw a striped line on one side of a lane, on a surface.

Parameters:

• lane – the lane

• surface – the pygame surface

• stripes_count – the number of stripes to draw

• longitudinal – the longitudinal position of the first stripe [m]

• side – which side of the road to draw [0:left, 1:right]

classmethod continuous_line(lane: AbstractLane, surface: WorldSurface, stripes_count: int, longitudinal: float, side: int) → None

Draw a continuous line on one side of a lane, on a surface.

Parameters:

• lane – the lane

• surface – the pygame surface

• stripes_count – the number of stripes that would be drawn if the line was striped

• longitudinal – the longitudinal position of the start of the line [m]

• side – which side of the road to draw [0:left, 1:right]

classmethod draw_stripes(lane: AbstractLane, surface: WorldSurface, starts: list[float], ends: list[float], lats: list[float]) → None

Draw a set of stripes along a lane.

Parameters:

• lane – the lane

• surface – the surface to draw on

• starts – a list of starting longitudinal positions for each stripe [m]

• ends – a list of ending longitudinal positions for each stripe [m]

• lats – a list of lateral positions for each stripe [m]

class highway_env.road.graphics.RoadGraphics

A visualization of a road lanes and vehicles.

static display(road: Road, surface: WorldSurface) → None

Display the road lanes on a surface.

Parameters:

• road – the road to be displayed

• surface – the pygame surface

static display_traffic(road: Road, surface: WorldSurface, simulation_frequency: int = 15, offscreen: bool = False) → None

Display the road vehicles on a surface.

Parameters:

• road – the road to be displayed

• surface – the pygame surface

• simulation_frequency – simulation frequency

• offscreen – render without displaying on a screen

static display_road_objects(road: Road, surface: WorldSurface, offscreen: bool = False) → None

Display the road objects on a surface.

Parameters:

• road – the road to be displayed

• surface – the pygame surface

• offscreen – whether the rendering should be done offscreen or not

class highway_env.road.graphics.RoadObjectGraphics

A visualization of objects on the road.

classmethod display(object_: RoadObject, surface: WorldSurface, transparent: bool = False, offscreen: bool = False)

Display a road objects on a pygame surface.

The objects is represented as a colored rotated rectangle

Parameters:

• object – the vehicle to be drawn

• surface – the surface to draw the object on

• transparent – whether the object should be drawn slightly transparent

• offscreen – whether the rendering should be done offscreen or not

static blit_rotate(surf: Surface, image: Surface, pos: ndarray | Sequence[float], angle: float, origin_pos: ndarray | Sequence[float] | None = None, show_rect: bool = False) → None

Many thanks to https://stackoverflow.com/a/54714144.