Imported from kopffarben/PH-Curve (PHCurveLibrary/AGENTS.md). Install upstream with npx skills add kopffarben/PH-Curve --skill PHCurveLibrary. Copyright stays with the author.

AGENTS.md

This library lives inside the PH-Curve solution alongside PHCurveLibrary.Test and PHCurveLibrary.Benchmark.

This document outlines the agent-based architecture of the PHCurveLibrary for Pythagorean-Hodograph (PH) curves with G² interpolation. It describes each component (“agent”) and the core data structures, along with the underlying mathematics and key literature references. Ignore all commented-out instructions.

File Layout

The library is organised into separate source files:

• HermiteControlPoint3D.cs defines the Hermite endpoint data structure.
• PHCurve3D.cs implements the PH curve representation.
• PHCurveFactory.cs provides construction and validation helpers.

Documentation Requirements

• Language: All comments must be written in English.
• Public members: should include XML documentation comments.
• Mathematical context: All comments should include XML documentation summarising the underlying mathematics. Cite relevant formulas or algorithms and include academic references when appropriate.

Data Structures

HermiteControlPoint3D

• Type: struct
• Purpose: Encapsulates the Hermite boundary conditions at one endpoint of a PH segment, including:
  • Position (Vector3): 3D point coordinates.
  • Tangent (Vector3): First derivative direction.
  • Curvature (float): Signed curvature magnitude.
  • PrincipalNormal (Vector3): Direction of curvature in 3D.
• Usage: Passed into PHCurveFactory.CreateQuintic(...) to specify G² interpolation data.

PHCurve3D

• Type: struct
• Purpose: Represents one PH-Quintic segment by its five hodograph coefficients A–E.
• Capabilities:
  • Position(t), Derivative(t), SecondDerivative(t)
  • Speed(t) = ||r'(t)||, TangentUnit(t), PrincipalNormal(t)
  • Exact arc-length calculation and offset‐point generation.
• Usage:
  • Produced by PHCurveFactory.
  • Consumed by path‐planning and real‐time agents for evaluation.

PHCurveFactory

• Responsibility: Construct PH segments from Hermite endpoints.
• Mathematical Core: Solves for B, C, D, E in the system [ \begin{cases} A + B + C + D + E = T_1,\ A + \tfrac12B + \tfrac13C + \tfrac14D + \tfrac15E = P_1 - P_0,\ A\cdot C + \tfrac12 B\cdot B = 0,\ B\cdot D + C\cdot C + A\cdot E = 0,\ 2C + 3D + 4E = \kappa_1,|T_1|^2,N_1, \end{cases} ] enforcing Hermite‐position, tangent, PH‐orthogonality, and end‐curvature constraints.
• Tasks:
  • CreateQuintic(p0, p1) → returns PHCurve3D.
  • ValidateG2(a, b) → checks position, tangent, normal continuity.
• References:
  • Jaklić et al. (2015), G² Quintic Hermite Interpolation, NM TMA 8(3):219–236. Preprint Local PDF
  • Farouki & Dong (2012), PHquintic Library, Technical Report. PDF Local PDF

PathPlanner

• Responsibility: Assemble a multi‐segment PH path.
• Mathematical Core: Ensures at each join (T_i(1)=T_{i+1}(0)) and (N_i(1)=N_{i+1}(0)).
• Tasks:
  • AddSegment(p_{i-1}, p_i) → uses PHCurveFactory.
  • BuildPath() → returns List<PHCurve3D>.
  • ValidatePathG2() → iterates ValidateG2.
• References:
  • Albrecht & Farouki (1996), Homotopy Methods for PH Splines, CAGD 13(3):291–305. DOI

AlternativeCurveAgent

• Responsibility: Offer non-PH G² transitions.
• Mathematical Core:
  • Clothoid (Euler Spiral): (\kappa(s)=a s + b), parameterized by Fresnel integrals.
  • Rational Cubic: Weighted Bézier form for end‐curvature control.
• Tasks:
  • CreateClothoid(p0, p1, κ0, κ1)
  • CreateRationalCubic(p0, p1, weights)
• References:
  • Walton & Meek (1996), Clothoid Approximation, CAGD 13(9):513–526. PDF
  • Habib & Sakai (2010), Rational Cubic Spirals, CAGD. DOI

CurveOptimizer

• Responsibility: Select the best curve among multiple candidates.
• Mathematical Core:
  • Bending energy (E=\int_0^1\kappa(t)^2,dt).
  • Path length (L=\int_0^1|r'(t)|,dt).
  • Curvature variation metrics.
• Tasks:
  • Evaluate(curve) → computes quality metrics.
  • SelectBest(candidates) → picks minimal‐energy solution.
• References:
  • Farouki et al. (2008), Optimization of Spatial PH Quintics, CAGD 25(3):274–297. DOI Local PDF

Additional References

For a summary of these papers, see SUMMARY.md. A dedicated overview of fitting methods is provided in Fitting/SUMMARY.md.

• Farouki & Dong (2012), PHquintic Library PDF (UC Davis eScholarship) Local PDF

• Jaklič et al. (2015), G² Quintic PH-Interpolation Preprint (University of Primorska) Local PDF

• Meek & Walton (2007), G² PH-Quintic Spirale PDF (ResearchGate)

• Kozak (2014), Spatial Rational PH Cubic PDF (arXiv) Local PDF

• Farouki et al. (2008), Spatial PH Quintic Optimisation PDF (arXiv) Local PDF

• Walton & Meek (1996), Clothoid Approximation PDF (ResearchGate)

• Farouki & Saguin-Sprynski (2014), C2 interpolation of spatial data subject to arc-length constraints PDF (ResearchGate) Local PDF

• Farouki et al. (2008), Identification of Spatial PH Quintic Hermite Interpolants with Near-Optimal Shape Measures Download PDF (ResearchGate / Academia.edu) Local PDF

• Schröcker & Šír (2023), Optimal interpolation with spatial rational PH curves PDF (arXiv) Local PDF

• Arrizabalaga & Ryll (2022), Spatial motion planning with Pythagorean Hodograph curves PDF (arXiv) Local PDF

• Arrizabalaga et al. (2024), PHODCOS: Pythagorean Hodograph-based Differentiable Coordinate System PDF (arXiv) Local PDF