RaceLine Optimizer
raceline-optimizer is a native Rust library and CLI for racing-line
optimization, minimum-time trajectory optimization, and reproducible track
geometry preparation. It computes locally optimized trajectory candidates
inside explicit left/right track boundaries under configurable vehicle and
geometry constraints.
License for 0.2.1: source-available for noncommercial use, modification, and redistribution under LICENSE. Commercial use, including paid products, SaaS, client services, and internal for-profit use, requires prior written permission from PE Patsukevich Aleksandr (Red Rat in Hat): contact@redratinhat.com. This release is not offered under an OSI open-source license. Earlier releases retain their original license terms; see UPSTREAM.md.
RaceLineCalc uses a separate private solver distribution, including the proprietary V2 models. Its track editor builds tracks from images without requiring users to assemble the JSON pipeline manually.
Example shown: a completed counterclockwise point-mass solve using a README-specific wide-line envelope: 0.5 g drive, 0.5 g braking, and 1.5 g left/right lateral limits. The technical overlay includes prepared boundaries, solver stations, speed extrema, signed lateral acceleration, and brake-to-drive transitions.
What it provides
- Deterministic station geometry for closed circuits and open routes.
- Point-mass, double-track car, and lean-aware motorcycle optimization.
- IPOPT-backed JSON library and CLI with diagnostics, progress, and cancellation.
Results are locally optimized candidates, not claims of global optimality or real-world lap-time validation.
Solver success and the summary quality flag are not substitutes for the
detailed feasibility audit. Inspect its sample frame: station, collocation,
collocation-polynomial dense, and linear-interpolation diagnostics can differ.
Existing public configurations can retain between-node violations even when
the summary quality flag is clean. Solved_To_Acceptable_Level is also distinct
from strict Solve_Succeeded.
Public V1 examples
All examples below use the same technical circuit so that the path and speed differences come from the model/profile rather than from a different drawing. Open an image to inspect the full-resolution station, acceleration, and speed annotations. They illustrate particular configurations rather than a benchmark or a claim that one vehicle family is inherently faster than another.
Proprietary V2 models in RaceLineCalc
RaceLineCalc also includes proprietary Car V2 and Moto V2 vehicle models. Their source code, calibration data, and private qualification fixtures are not distributed in this repository; the public Rust crate continues to provide the reusable V1 model families described above.
The V2 models share a deeper contact-and-tire contract while retaining separate vehicle dynamics:
- Car V2 adds transient body roll, dynamically coupled wheel loads, camber- aware tire response, steering dynamics, and longitudinal/aerodynamic load consistency.
- Moto V2 adds camber-aware tire moments, rake/trail and gyroscopic effects, coupled roll-steer-yaw dynamics, physical rider steering authority, and transient pitch/contact dynamics.
Physical motion channels
The counts below describe physical motion channels, not the number of NLP variables. Frenet path coordinates, collocation copies, force coordinates, and solver auxiliaries are not additional mechanical degrees of freedom.
| Model | Physical motion channels | What those channels mean | Contact and control depth |
|---|---|---|---|
| Point V1 (source-available) | Reduced planar translation | Advances and moves laterally inside the track; it has no resolved body attitude. | Acceleration-envelope limits; no wheel, roll, pitch, or steering mechanics. |
| Car V1 (source-available) | 3 rigid-body channels: longitudinal, lateral, yaw | Resolves forward motion, body sideslip, and rotation about the vertical axis. | Four tire contacts and a directly controlled steering angle; vertical loads are equilibrium-constrained rather than transient body-roll states. |
| Car V2 (RaceLineCalc) | 4 rigid-body channels: longitudinal, lateral, yaw, roll | Adds transient rotation of the sprung body about its longitudinal axis. | Dynamically coupled wheel loads, camber-aware tires, a rate-limited steering actuator, and consistent longitudinal/aerodynamic load effects. |
| Moto V1 (source-available) | 4 rigid-body channels: longitudinal, lateral, yaw, lean; plus steering-axis rotation | Adds motorcycle lean and steering motion to planar single-track dynamics. | Front/rear contacts, lean and steering rates, combined grip, and branch-safe tire operation; no resolved pitch/heave chassis motion. |
| Moto V2 (RaceLineCalc) | 6 rigid-body channels: longitudinal, lateral, heave, roll/lean, pitch, yaw; plus steering-axis rotation | Adds vertical chassis travel and fore-aft rotation while retaining coupled lean, yaw, and steering motion. | Transient axle contact loads, camber/tire moments, rake/trail, wheel gyroscopic coupling, and physical rider steering torque. |
The V2 source, equations, coefficients, and calibration remain proprietary. The table intentionally describes externally meaningful model scope rather than implementation details.
The RaceLineCalc result view exposes model-owned product traces such as speed, drive/brake force, grip utilization, body roll or motorcycle lean, and steering effort. The comparisons below use the same prepared circuit, direction, 160-station geometry, and base vehicle profile on both sides. They are product examples rather than global-optimum or real-world lap-time claims.
Matched Car V1 and Car V2 results
Matched Moto V1 and Moto V2 results
Workspace
| Package | Purpose |
|---|---|
raceline-optimizer |
Solver library, public contracts, station generation, vehicle dynamics, and quality checks. |
raceline-optimizer-cli |
raceline-optimize optimize and raceline-optimize inspect. |
Only the reusable optimizer and CLI are public here. RaceLineCalc mobile UI, billing, analytics, image autotracing, FFI packaging, and private product regression fixtures remain outside this repository.
Requirements
- Rust 1.85 or newer.
- A compatible IPOPT shared library for actual solves.
The project dynamically loads IPOPT by default; native binaries are not bundled.
Pass the library with --ipopt-library, or set RLC_IPOPT_LIBRARY. See
IPOPT setup for platform-specific names and diagnostics.
Quick start
Clone the repository and verify the public workspace:
Run the included point-mass example:
Inspect the generated trajectory without solving it again:
On Windows PowerShell, replace the trailing \ line continuations with
backticks and pass a compatible libipopt-3.dll path. More car and motorcycle
examples are in the
CLI documentation.
Input and output contracts
The ordinary optimize workflow keeps versioned solver request envelopes out of
the user interface:
--trackaccepts aTrackAreaContractV1JSON document containing the left and right boundaries, units, route mode, direction, and optional open-route start/finish geometry.--vehicleacceptsraceline_optimizer_vehicle.v1and selectspoint_mass,car, orbikeplus its vehicle profile.- The CLI generates deterministic station geometry and dispatches the matching public solver API.
- Successful solves emit
rust_solver_response.v1; failures emit the typedrust_solver_error.v1schema.
Advanced integrations can use prepare to build station geometry without a
vehicle solve, and solve to replay a complete versioned request. These commands
do not introduce a new request schema; see the
CLI documentation.
The examples are small synthetic tracks and profiles intended to be copied and modified. See architecture for the full data flow.
Library API
The stable integration boundary starts in raceline_optimizer::solver_api:
solve_point_mass_jsonsolve_car_mintime_jsonsolve_bike_mintime_json- progress/cancellation variants for each solve family
build_station_geometry_json
These functions preserve typed error codes and the same JSON output contracts as
the CLI. Lower-level modules remain public in 0.1.x for research and advanced
integration, but may be narrowed before 1.0.
Known limits
- IPOPT availability and its native linear-solver configuration are external to this crate.
- Input boundaries must describe a coherent corridor; folded or crossing station sections are rejected by topology and section-frame validation.
- Numerical convergence is model-, track-, initialization-, and scale-dependent.
- The repository does not include a GUI or image-to-track extraction.
- The public API is pre-1.0 and may evolve with explicit release notes.
Development
Before opening a pull request, run:
See CONTRIBUTING.md, SECURITY.md, and the GitHub Actions workflow. Maintainers should also use the release checklist, which records the required library → CLI publish order.
Upstream history and license
This repository preserves its historical fork relationship with
TUMFTM/global_racetrajectory_optimization, while the current working tree is
an independently developed Rust implementation imported from RaceLineCalc.
Exact transition commits, checksums, and license boundaries are documented in
UPSTREAM.md and EXPORT-MANIFEST.json.
The 0.2.1 Rust distribution is source-available under LICENSE, with commercial use requiring a separate written license. Preserved MIT/Apache license texts document earlier Rust releases; they are not an alternative license grant for this release as a whole. Historical upstream commits and removed upstream files remain under LGPL-3.0. This project does not claim endorsement by TUMFTM.