Track System

The track system handles loading racing circuits, managing centerline and raceline data, and coordinate conversions.

Source: gymkhana/envs/track/

Track loading

Tracks are loaded from map files following the ROS map convention:

  • A .yaml metadata file with resolution (m/pixel) and origin fields

  • A single-channel black-and-white image (black = obstacles, white = free space)

Both files must share the same base name and directory.

Map management

Maps are managed through a two-tier system:

The download URL is configured in gymkhana/envs/track/track_utils.py::MAPS_URL.

Frenet coordinates

The track system supports conversion between Cartesian and Frenet (arc-length based) coordinate frames.

frenet_to_cartesian()

Convert Frenet coordinates to Cartesian. Available in gymkhana/envs/track/track.py.

This is useful for initializing vehicles at specific positions along the track using env.reset(options={"poses": ...}).

Centerline and raceline

Each track includes:

  • Centerline: the geometric center of the track, used for Frenet projection and progress measurement

  • Raceline: an optimized racing line (when available), rendered in red when render_track_lines is enabled

Both use cubic spline interpolation for smooth trajectories.

API reference

Track loading, Frenet coordinate conversion, and rendering.

class gymkhana.envs.track.track.TrackSpec(name: str | None, image: str | None, resolution: float, origin: Tuple[float, float, float], negate: int, occupied_thresh: float, free_thresh: float)

Track metadata loaded from a ROS-format YAML map file.

name: str | None
image: str | None
resolution: float
origin: Tuple[float, float, float]
negate: int
occupied_thresh: float
free_thresh: float
class gymkhana.envs.track.track.Track(spec: TrackSpec, occupancy_map: ndarray, filepath: str | None = None, ext: str | None = None, centerline: Raceline | None = None, raceline: Raceline | None = None)

Racing circuit with occupancy map, centerline, and raceline.

Load via from_track_name() or from_track_path(). Supports Frenet coordinate conversion and reverse-direction driving.

spec: TrackSpec
filepath: str | None
ext: str | None
occupancy_map: ndarray
centerline: Raceline
raceline: Raceline
set_direction(reversed: bool) → None

Set track direction by swapping active centerline/raceline references.

Parameters:

reversed – If True, use reversed versions. If False, use regular versions.

static load_spec(track: str, filespec: str) → TrackSpec

Load track specification from a YAML file.

Parameters:

  • track – Track name identifier.

  • filespec – Path to the YAML metadata file.

Returns:

Populated TrackSpec instance.

static from_track_name(track: str, track_scale: float = 1.0) → Track

Load a track by name from the maps directory or user cache.

Parameters:

  • track – Track name (must exist in the local maps/ submodule or ~/.gymkhana/maps/).

  • track_scale – Scale factor applied to coordinates (default 1.0).

Returns:

Loaded Track instance.

Raises:

FileNotFoundError – If the track files cannot be found.

static from_track_path(path: Path, track_scale: float = 1.0) → Track

Load a track from a YAML file path.

Parameters:

  • path – Path to the track YAML metadata file.

  • track_scale – Scale factor applied to coordinates (default 1.0).

Returns:

Loaded Track instance.

Raises:

FileNotFoundError – If the track files cannot be found.

static from_refline(x: ndarray, y: ndarray, velx: ndarray)

Create a track from a reference line defined by waypoints and velocities.

Parameters:

  • x – X-coordinates of the waypoints.

  • y – Y-coordinates of the waypoints.

  • velx – Velocity at each waypoint.

Returns:

Track instance with a synthetic occupancy map.

frenet_to_cartesian(s, ey, ephi, use_raceline=False)

Convert Frenet coordinates to Cartesian.

Parameters:

  • s – Arc length distance along the centerline/raceline (meters).

  • ey – Lateral deviation from the reference line (meters).

  • ephi – Heading deviation (vehicle yaw minus track yaw, radians).

  • use_raceline – If True, convert relative to raceline; else centerline.

Returns:

Tuple (x, y, psi) — Cartesian position and yaw angle.

cartesian_to_frenet(x, y, phi, use_raceline=False, s_guess=0, precise=False, debug=False)

Convert Cartesian coordinates to Frenet coordinates.

Parameters:

  • x – Vehicle x-position (from std_state["x"]).

  • y – Vehicle y-position (from std_state["y"]).

  • phi – Vehicle yaw angle (from std_state["yaw"]).

  • use_raceline – If True, project onto raceline; else centerline.

  • s_guess – Initial arc length guess for the optimisation-based method.

  • precise – If True, use optimisation-based arc length search (requires a good s_guess; may fail if the guess is poor).

  • debug – If True, print validation info comparing precise vs. global search.

Returns:

Tuple (s, ey, ephi) — arc length, lateral deviation (meters), and heading deviation (radians).

render_centerline(e: EnvRenderer) → None

Render the track centerline in green.

Parameters:

e – Environment renderer object.

render_raceline(e: EnvRenderer) → None

Render the track raceline in red.

Parameters:

e – Environment renderer object.

render_both_lines(e: EnvRenderer) → None

Render both the centerline (green) and raceline (red).

Parameters:

e – Environment renderer object.

render_arc_length_annotations(e: EnvRenderer, interval: float = 5.0, point_color: tuple[int, int, int] = (255, 165, 0), text_color: tuple[int, int, int] = (255, 165, 0), point_size: int = 6, font_size: int = 10) → None

Render arc length annotations along the centerline at regular intervals.

Useful for identifying positions along the track in Frenet coordinates.

Parameters:

  • e – Environment renderer object.

  • interval – Distance between annotations in meters (default 5.0).

  • point_color – RGB color for annotation points (default orange).

  • text_color – RGB color for text labels (default orange).

  • point_size – Size of annotation points in pixels (default 6).

  • font_size – Font size for text labels (default 10).

render_frenet_projection(e: EnvRenderer, vehicle_color: tuple[int, int, int] = (255, 0, 255), projected_color: tuple[int, int, int] = (0, 255, 255), line_color: tuple[int, int, int] = (255, 128, 0), size: int = 8) → None

Render debug visualisation of Frenet coordinate projection.

Shows vehicle position (magenta), projected point on centerline (cyan), and a connecting line (orange). Requires debug_frenet_projection=True in the env config to populate the debug data.

Parameters:

  • e – Environment renderer object.

  • vehicle_color – RGB color for vehicle position marker.

  • projected_color – RGB color for projected point marker.

  • line_color – RGB color for connection line.

  • size – Size of rendered points in pixels.

render_lookahead_curvatures(e: EnvRenderer, vehicle_s: float, n_points: int, ds: float, color: tuple[int, int, int] = (0, 0, 255), size: int = 6) → None

Render lookahead curvature sampling points ahead of the vehicle.

Visualises the points where curvature is sampled by the observation system, matching the behaviour of sample_lookahead_curvatures().

Parameters:

  • e – Environment renderer object.

  • vehicle_s – Current arc length position of vehicle (meters).

  • n_points – Number of lookahead points to render.

  • ds – Spacing between points in meters.

  • color – RGB color tuple for rendered points.

  • size – Size of rendered points in pixels.

Raceline and centerline representation with cubic spline interpolation.

class gymkhana.envs.track.raceline.Raceline(xs: ndarray, ys: ndarray, velxs: ndarray, ss: ndarray | None = None, psis: ndarray | None = None, kappas: ndarray | None = None, accxs: ndarray | None = None, spline: CubicSpline2D | None = None, w_lefts: ndarray | None = None, w_rights: ndarray | None = None)

A racing or centerline path defined by waypoints and a cubic spline.

n

Number of waypoints.

ss

Arc length along the line.

xs

X-coordinates of the waypoints.

ys

Y-coordinates of the waypoints.

yaws

Yaw angles at the waypoints.

ks

Curvature at the waypoints.

vxs

Velocity along the line.

axs

Acceleration along the line.

w_lefts

Left track width at each waypoint.

w_rights

Right track width at each waypoint.

length

Total length of the raceline (meters).

spline

Cubic spline fitted through the waypoints.

static from_centerline_file(filepath: Path, delimiter: str | None = ',', fixed_speed: float | None = 1.0, track_scale: float | None = 1.0)

Load a centerline from a CSV file.

Expected format: [x, y, w_right, w_left] per row. Validates that the centerline is symmetric within 10% tolerance.

Parameters:

  • filepath – Path to the centerline CSV file.

  • delimiter – Field delimiter (default ",").

  • fixed_speed – Constant speed assigned to all waypoints (default 1.0).

  • track_scale – Scale factor applied to coordinates (default 1.0).

Returns:

Raceline instance representing the centerline.

static from_raceline_file(filepath: Path, delimiter: str = ';', track_scale: float | None = 1.0) → Raceline

Load an optimised raceline from a CSV file.

Expected format: [s, x, y, psi, k, vx, ax] per row.

Parameters:

  • filepath – Path to the raceline CSV file.

  • delimiter – Field delimiter (default ";").

  • track_scale – Scale factor applied to coordinates (default 1.0).

Returns:

Raceline instance representing the optimised racing line.

reversed() → Raceline

Create a reversed copy of this raceline for reverse-direction driving.

Works for both centerline (with w_lefts/w_rights) and raceline (where those fields are None). Track widths are swapped so left/right remain correct relative to the new driving direction.

Returns:

New Raceline with reversed direction.

render_waypoints(e: EnvRenderer, color: tuple[int, int, int] = (0, 128, 0)) → None

Render the raceline waypoints as a closed line.

Parameters:

  • e – Environment renderer object.

  • color – RGB color tuple for the line (default green (0, 128, 0)).