F1TENTH Raceline Optimization

This repository is adapted from CL2-UWaterloo/Raceline-Optimization to support modern Python packages. The current code has been tested with Python 3.14, NumPy 2.4.4, SciPy 1.17.1, and Matplotlib 3.10.9.

The original upstream README is kept in Readme_original.md. This README focuses on the F1TENTH workflow in main_globaltraj_f110.py.

Basic Workflow

1. Set up a virtual environment.

   conda create -n raceline python
   conda activate raceline
   pip install -r requirements.txt

2. Copy the map generated by slam_toolbox into maps/.

3. Open map_converter.ipynb and set:

   MAP_NAME = <map_name>

   For example,

   MAP_NAME = race3

   Run the notebook to extract a centerline and estimate the track width from the occupancy-grid map. The generated track CSV will be written to:

   inputs/tracks/<map_name>.csv
   

4. Open sanity_check.ipynb and set:

   MAP_NAME = <map_name>

   Run the notebook to inspect the generated centerline and track widths.

5. Run raceline optimization:

   python3 main_globaltraj_f110.py --map_name <map_name>

   Generated trajectories are written under: outputs/<map_name>/.

   The current F1TENTH export format is a comma-separated csv file with the following columns:

   x_m,y_m,vx_mps,s_m,psi_rad,kappa_radpm,ax_mps2
   

Supported Modes

main_globaltraj_f110.py selects the optimization mode with:

opt_type = 'mincurv'

For F1TENTH use, mincurv is the default and is usually the most practical starting point.

All supported modes are:

shortest_path
mincurv
mincurv_iqp
mintime

Track Import Options

main_globaltraj_f110.py controls track import behavior with imp_opts:

imp_opts = {"flip_imp_track": False,
            "set_new_start": False,
            "new_start": np.array([0.0, -47.0]),
            "min_track_width": None,
            "num_laps": 1}

• flip_imp_track: set to True to reverse the driving direction of the imported track.

Error: at least one pair of normals is crossed!

If you see:

Error: At least two spline normals are crossed!

Things to try:

1. Uncomment the following line in map_converter.ipynb and rerun:

   transformed_data = transformed_data[::4]

   This subsamples the generated centerline. You can increase the subsample rate if normals are still crossed.

2. Increase spline smoothing s_reg in params/f110.ini:

   reg_smooth_opts={"k_reg": 3,
                    "s_reg": 10}

   The default value is 10, try increasing it 20, 30, 50, 70, etc.

Tuning mincurv Parameters

Most F1TENTH tuning happens in params/f110.ini.

Vehicle parameters

veh_params = {"v_max": 7.0,
              "length": 0.568,
              "width": 0.296,
              "mass": 3.74,
              "dragcoeff": 0.075,
              "curvlim": 3.0,
              "g": 9.81}

• v_max: maximum allowed speed in m/s.
• width: physical vehicle width in meters. used for warnings/checks/plots. does not affect mincurv optimization.
• mass, dragcoeff, and g: used for velocity calculations. does not affect the shape of the optimized raceline. does affect the velocity profile of the waypoints.

Minimum-curvature optimizer parameters

optim_opts_mincurv={"width_opt": 0.6,
                    "iqp_iters_min": 3,
                    "iqp_curverror_allowed": 0.01}

• width_opt: effective vehicle width used during optimization, including safety margin. Reduce it if the optimizer reports that the track is too narrow or cannot find a feasible line. Increase it for more conservative clearance.

ggv.csv

In mincurv mode, the script computes a velocity profile after the geometric raceline is created.

inputs/veh_dyn_info/ggv.csv defines the maximum longitudinal and lateral acceleration the car is allowed to use when assigning waypoint speeds. It has this format:

v_mps,ax_max_mps2,ay_max_mps2
0.0,8.0,8.0
10.0,8.0,8.0

• v_mps: speed sample in m/s.
• ax_max_mps2: maximum longitudinal acceleration at that speed.
• ay_max_mps2: maximum lateral acceleration at that speed.

To make the generated velocity profile more conservative, reduce ax_max_mps2 and ay_max_mps2.