Skip to content

docs: Write sections 4.1, 4.2 and 4.4 of the book: cubic splines, Pure Pursuit and rear wheel feedback - #219

Merged
ShisatoYano merged 2 commits into
ShisatoYano:mainfrom
Dhruv-Sharma29:docs/book-ch4-geometric-controllers
Nov 15, 2026
Merged

ShisatoYano merged 2 commits into
ShisatoYano:mainfrom
Dhruv-Sharma29:docs/book-ch4-geometric-controllers

Conversation

@Dhruv-Sharma29

Copy link
Copy Markdown
Contributor

Closes #200

Overview

Adds the theory layer of the three remaining sections of chapter 4, one page each, following the writing guide and the Stanley section:

  • 4.1 Course generation with cubic splines (doc/path_tracking/cubic_spline.md): the natural cubic spline derived step by step (conditions, coefficients, the tridiagonal system, natural ends), the chord-length parameter of the 2D course, the yaw angle and curvature formulas, and the target speed along the course (switch-backs and the stop at the end).
  • 4.2 Pure Pursuit (doc/path_tracking/pure_pursuit.md): the look-ahead point, the arc through it (law of sines), the curvature as a proportional law on the look-ahead point's offset, the steering angle from the bicycle model, the speed-dependent look-ahead distance with a linearized analysis of why it grows with speed, and the adaptive look-ahead distance.
  • 4.4 Rear wheel feedback (doc/path_tracking/rear_wheel_feedback.md): the errors at the rear axle, the error dynamics in the course frame, the control law and its Lyapunov argument, the steering angle, and a "Pure Pursuit vs Stanley vs rear wheel feedback" comparison (what each one looks at and how it behaves at speed).

Each page has a figure script in doc/path_tracking/figures/ (cubic_spline_course.py, pure_pursuit_geometry.py, rear_wheel_feedback_errors.py) that computes its geometry with the page's equations. The pages are listed on the chapter page, and the new symbols $s$, $l_d$ and $\alpha$ are added to Notation and Units.

The Limits sections also say where the code differs from the theory, for example that RearWheelFeedbackController sets the whole yaw rate to 0 when the heading error is exactly 0, and that the simulations' course has a turn of about 1 m radius driven at a constant 20 km/h.

How I checked it

  • sphinx-build -W --keep-going -b html doc doc/_build/html builds without warnings, and pytest test/test_book_chapters.py passes.
  • Read the three pages in the built book: every equation renders, every figure loads, and the links between the pages work.
  • The spline equations of 4.1, implemented in the figure script, give the same coefficients as CubicSpline for the simulations' course.
  • The linearized Pure Pursuit result (damping ratio $1/\sqrt{2}$, the same settling distance at any speed) was checked with a short simulation at 2 and 10 m/s.
  • The references were checked against the papers: Coulter (1992), Snider (2009), Hoffmann et al. (2007), and Paden et al. (2016), whose equation (V.12) is the law of 4.4 (the original by Samson is cited as given there).

Copilot AI balanced review requested due to automatic review settings November 8, 2026 07:46

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot was unable to review this pull request because the user who requested the review has insufficient remaining quota. Try requesting a review at a lower effort level.

@ShisatoYano ShisatoYano added the documentation Improvements or additions to documentation label Nov 15, 2026
@ShisatoYano
ShisatoYano self-requested a review November 15, 2026 11:37
@ShisatoYano

Copy link
Copy Markdown
Owner

Thank you, @Dhruv-Sharma29, for writing three sections at once, and at this quality! The derivations are complete and easy to follow (the spline coefficients step by step, the law of sines for the arc, the Frenet equations and the Lyapunov function), the Limits sections say honestly where the code differs from the theory, and the linearized analysis that connects Pure Pursuit and rear wheel feedback ($k_\theta = 2/l_d$, $k_e = 2/l_d^2$) is a real insight for readers. The comparison table is exactly what #200 asked for.

I checked it against the code and the math:

  • The book builds without warnings with this branch, the three figure scripts run, and the figures match the equations (for example, the center of rotation in the Pure Pursuit figure is perpendicular to the heading).
  • The numbers match the code: the course's curvature ranges from -1.04 to 0.49 1/m and is 0 at both ends; $k = 0.3$ s and $l_{d,\min} = 2$ m for Pure Pursuit; $k = 0.4$ s, $k_\kappa = 2$ m and the clamp to [2, 25] m for the adaptive version; $k_\theta = 1$, $k_e = 0.5$ and the $\theta_e = 0$ special case for rear wheel feedback; the switch-back test and the 100-sample ramp of the target speed.
  • I re-derived (4) of 4.1, (2), (3) and (7) of 4.2, and (2), (3), (5) and (7) of 4.4: they are correct, as are the damping ratio $1/\sqrt{2}$, the 4 % overshoot ($e^{-\pi}$) and the 31 m/s² lateral acceleration.

One request before merging:

  1. 4.2, Limits, "Only one point": "Two vehicles with different headings but the same look-ahead point get the same steering" isn't right: $\alpha$ in (1) depends on the heading $\theta$, so different headings give different steering. I think the point is about the course: Pure Pursuit uses only the position of the look-ahead point, not the course's heading or curvature there, so two courses that pass through the same look-ahead point give the same steering, whatever their direction at that point. Could you rewrite the sentence along those lines?

Suggestions:

  1. The symbol $s$. In 4.1, $s$ is the chord-length parameter, which "is close to the distance traveled but not equal to it" ($\sigma$ is the true distance there). In 4.4, $\dot s = v\cos\theta_e / (1 - \kappa e)$ needs the true distance along the course. Please say in 4.4 that $s$ is the distance along the course (the $\sigma$ of 4.1), and make the NOTATION.md entry mention both uses, for example "Distance along the course; in 4.1 also the spline's chord-length parameter, which is close to it".
  2. "Comes back over about $2,l_d$" (4.2 and the comparison table): from a pure offset, the solution of (7) first reaches the course after $\frac{3\pi}{4} l_d \approx 2.4,l_d$, and settles within 2 % after about $4,l_d$. Saying "reaches the course after about $2.4,l_d$" would make the number checkable.

Optional: since #230, the writing guide adds a short Check your understanding part (two or three questions answered from the text, with folded answers) to the theory layer. This PR was opened before that, so it isn't needed here; if you'd like to add questions, the Stanley section has an example, or they can come in a follow-up.

🤖 Generated with Claude Code

…e Pursuit and rear wheel feedback

Add the theory layer of the three remaining sections of chapter 4 (ShisatoYano#200):
the natural cubic spline course with its yaw, curvature and target speed,
Pure Pursuit with the adaptive look-ahead distance, and rear wheel feedback
with its Lyapunov argument and a comparison of the three controllers.
Each page has a figure script, and the new symbols are added to Notation.
- 4.2 Limits: Pure Pursuit ignores the course's heading and curvature at the
  look-ahead point; the old sentence wrongly said the vehicle's heading
  doesn't matter
- 4.4 and Notation: s in the Frenet equations is the true distance along the
  course, while 4.1 also uses it for the chord-length parameter
- 4.2 and the comparison table: give checkable numbers for how fast Pure
  Pursuit comes back (first reaches the course after 3*pi/4 l_d, within 2 %
  after about 4 l_d)
@Dhruv-Sharma29 Dhruv-Sharma29 changed the title docs: 📝 Write sections 4.1, 4.2 and 4.4 of the book: cubic splines, Pure Pursuit and rear wheel feedback docs: Write sections 4.1, 4.2 and 4.4 of the book: cubic splines, Pure Pursuit and rear wheel feedback Nov 15, 2026
@Dhruv-Sharma29

Copy link
Copy Markdown
Contributor Author

Thank you for the careful review. I've pushed the changes:

  1. Rewrote the "Only one point" bullet in 4.2: Pure Pursuit uses only the position of the look-ahead point, not the course's heading or curvature there, so two courses through the same point give the same steering, whatever their direction at that point.
  2. 4.4 now says that $s$ in the Frenet equations is the true distance along the course (the $\sigma$ of 4.1), and the Notation entry mentions both uses.
  3. 4.2 and the comparison table now say that, from a pure offset, the vehicle first reaches the course after $\frac{3\pi}{4} l_d \approx 2.4,l_d$ and stays within 2 % after about $4,l_d$.

I left the optional "Check your understanding" questions out of this PR.

@Dhruv-Sharma29
Dhruv-Sharma29 force-pushed the docs/book-ch4-geometric-controllers branch from e9d0212 to d96e402 Compare November 15, 2026 14:54
@ShisatoYano

Copy link
Copy Markdown
Owner

Thank you, @Dhruv-Sharma29, for the quick update! All three points are addressed:

  1. The "Only one point" bullet is now correct, and "however they bend between the vehicle and the point" makes it even clearer.
  2. 4.4 and NOTATION.md now say which $s$ is which.
  3. The numbers are checkable now: from $e'' + (2/l_d),e' + (2/l_d^2),e = 0$, a pure offset gives $e = e_0,e^{-s/l_d}(\cos(s/l_d) + \sin(s/l_d))$, which first reaches zero at $s = \frac{3\pi}{4},l_d$, and its envelope $\sqrt{2},e_0,e^{-s/l_d}$ falls below 2 % at about $4.3,l_d$.

The book still builds without warnings after merging with the current main. Leaving the questions for a follow-up is fine. This is ready to merge from my side.

🤖 Generated with Claude Code

@ShisatoYano
ShisatoYano merged commit 1d232b9 into ShisatoYano:main Nov 15, 2026
5 checks passed
@github-project-automation github-project-automation Bot moved this from Todo to Done in AVCBG Work Plan Nov 15, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

Status: Done

Development

Successfully merging this pull request may close these issues.

Book chapter 4: Following a course (cubic splines, Pure Pursuit, rear wheel feedback)

3 participants