clothoid

A Rust library for computing and fitting Clothoids (also known as Euler spirals or Cornu spirals). A clothoid is a curve whose curvature changes linearly with its arc length — the mathematically smooth transition between straight and curved motion, essential for autonomous vehicle path planning, railway design, and CNC toolpath generation.

Features

• Path fitting — fit a smooth clothoid path between any two 2D poses (position + heading)
• Two optimizers — Nelder-Mead (fast, default) and CMA-ES (robust on difficult landscapes)
• Configurable objective — 12 tunable penalty weights for curvature, symmetry, segment length, G² continuity, etc.
• High-precision Fresnel integrals — optional fresnel feature crate backend, or built-in approximation (Wilde 2009 / Abramowitz & Stegun)
• Incremental fitting — auto-escalates segment count and restarts with randomized initial conditions
• Interactive demo — drag start/end poses, tweak weights in real time, watch the optimizer converge

Quick Start

use clothoid::Clothoid;

let spiral = Clothoid::new(1.0);
let angle = spiral.direction_angle(0.5); // θ(s) = s² / (2a²)

Path fitting

use clothoid::fit::{FitState, FitConfig};
use clothoid::optimizer::Pose;

let mut fitter = FitState::new(); // Nelder-Mead
// or: FitState::cma_es() for CMA-ES

let start = Pose::new(-3.0, 0.0, 0.0);
let end   = Pose::new( 3.0, 0.0, 0.0);
let config = FitConfig::default();

let (exploration, best) = fitter.step(&start, &end, &config);

Interactive Demo

The included demo opens a window where you can drag start/end poses and watch the optimizer fit a clothoid path in real time.

cargo run --release --example interactive_demo

UI Elements

Controls

Global

Mouse

Tuning Knobs

Objective Weights (press when panel is visible)

Each weight cycles through a ladder: 0.0 → 0.01 → 0.05 → 0.1 → 0.25 → 0.5 → 1.0 → 2.5 → 5.0 → 10.0 → 25.0 → 50.0 → 0.0. Setting a weight to 0.0 disables that penalty term entirely.

HUD Readouts

• GEN — Generation counter. Increments each time the fitter resets (pose change, optimizer switch, or manual restart).
• BEST FIT — Position error, angle error, and total objective score of the best solution found.
• Log tail — Last 3 successful fit messages showing segment count and errors.

What Changes Imply

Increasing max segments (+ key)

• More complex paths — the optimizer can chain multiple clothoid arcs to satisfy difficult pose constraints
• Slower convergence — each segment adds 4 parameters (straight length, start κ, end κ, arc length); the simplex grows linearly with dimension
• Restart cycle — after 200 failed attempts at the current segment count, the fitter escalates (1 → 2 → … → max), then wraps back to 1

Tightening max κ ([ key)

• Gentler curves — the optimizer is forced to find paths with lower curvature, which may require longer arcs or more segments
• May prevent convergence — if the target poses are too close with incompatible headings, no valid low-curvature path exists
• Visually — paths become smoother and more spread out

Raising objective weights

• Higher priority — the optimizer will sacrifice other terms to minimise this one. E.g. raising w_end_pos to 50 makes reaching the target position dominant over curvature smoothness
• Trade-offs — increasing w_g2 (G² continuity) may increase total path length; increasing w_sign_flips may produce longer single-curvature arcs
• Disabling (0.0) — removes the constraint entirely. Setting w_max_kappa = 0 allows arbitrarily tight turns

Switching optimizers (O key)

API Reference

Core Types

• Clothoid — single spiral curve parameterised by scaling factor a
• Pose — 2D pose (x, y, angle)
• FitState — stateful incremental fitter; call step() each iteration
• FitConfig — configuration (max segments, max κ, tolerances, objective)
• PlanObjective — weighted penalty function; recommended() for tuned defaults, default() for legacy-compatible behaviour

Feature Flags

Reading Material

• The Clothoid
• Calculating coordinates along a clothoid between 2 curves
• Doran K. Wilde, "Computing Clothoid Segments for Trajectory Generation", IEEE/RSJ IROS 2009
• Abramowitz & Stegun, "Handbook of Mathematical Functions", NBS AMS 55, 1964