Track

track

Track loading, synthetic layout generation, and geometry processing.

TrackData dataclass

Processed track representation in arc-length domain.

Parameters:

Name	Type	Description	Default
x	ndarray	Global x-coordinate samples along the centerline [m].	required
y	ndarray	Global y-coordinate samples along the centerline [m].	required
elevation	ndarray	Elevation samples along the centerline [m].	required
banking	ndarray	Banking angle samples [rad].	required
arc_length	ndarray	Monotonic arc-length coordinate [m].	required
heading	ndarray	Centerline heading angle [rad].	required
curvature	ndarray	Signed curvature along arc length [1/m].	required
grade	ndarray	Longitudinal grade dz/ds (-).	required

length property

length: float

Track length [m].

Returns:

Type	Description
float	Final arc-length value of the discretized track [m].

validate

validate() -> None

Validate consistency of all track arrays.

Raises:

Type	Description
TrackDataError	If array lengths, arc length monotonicity, or numeric validity checks fail.

build_circular_track

build_circular_track(radius: float = DEFAULT_CIRCLE_RADIUS, sample_count: int = DEFAULT_CIRCLE_SAMPLE_COUNT, clockwise: bool = False, elevation: float = 0.0, banking: float = 0.0) -> TrackData

Build a circular closed-loop track with approximately constant curvature.

Parameters:

Name	Type	Description	Default
radius	float	Circle radius [m].	DEFAULT_CIRCLE_RADIUS
sample_count	int	Number of unique samples around the circle.	DEFAULT_CIRCLE_SAMPLE_COUNT
clockwise	bool	Whether to traverse the circle clockwise.	False
elevation	float	Constant elevation value along the track [m].	0.0
banking	float	Constant banking angle along the track [rad].	0.0

Returns:

Type	Description
TrackData	Validated circular TrackData representation.

Raises:

Type	Description
TrackDataError	If geometric input values are outside valid bounds.

build_figure_eight_track

build_figure_eight_track(lobe_radius: float = DEFAULT_FIGURE_EIGHT_RADIUS, sample_count: int = DEFAULT_FIGURE_EIGHT_SAMPLE_COUNT, elevation: float = 0.0, banking: float = 0.0) -> TrackData

Build a closed figure-eight track using a Gerono lemniscate centerline.

Parameters:

Name	Type	Description	Default
lobe_radius	float	Characteristic lobe radius scaling the layout [m].	DEFAULT_FIGURE_EIGHT_RADIUS
sample_count	int	Number of unique samples along the centerline.	DEFAULT_FIGURE_EIGHT_SAMPLE_COUNT
elevation	float	Constant elevation value along the track [m].	0.0
banking	float	Constant banking angle along the track [rad].	0.0

Returns:

Type	Description
TrackData	Validated figure-eight TrackData representation.

Raises:

Type	Description
TrackDataError	If geometric input values are outside valid bounds.

build_straight_track

build_straight_track(length: float = DEFAULT_STRAIGHT_LENGTH, sample_count: int = DEFAULT_STRAIGHT_SAMPLE_COUNT, elevation: float = 0.0, banking: float = 0.0) -> TrackData

Build a straight track centerline with constant elevation and banking.

Parameters:

Name	Type	Description	Default
length	float	Total straight-line track length [m].	DEFAULT_STRAIGHT_LENGTH
sample_count	int	Number of centerline samples.	DEFAULT_STRAIGHT_SAMPLE_COUNT
elevation	float	Constant elevation value along the track [m].	0.0
banking	float	Constant banking angle along the track [rad].	0.0

Returns:

Type	Description
TrackData	Validated straight TrackData representation.

Raises:

Type	Description
TrackDataError	If geometric input values are outside valid bounds.

load_track_csv

load_track_csv(path: str | Path) -> TrackData

Load a track CSV into TrackData.

Parameters:

Name	Type	Description	Default
path	str | Path	Path to a CSV containing x, y, elevation, and banking.	required

Returns:

Type	Description
TrackData	Parsed and validated track representation.

Raises:

Type	Description
TrackDataError	If the file does not exist, has an invalid schema, or contains too few rows.