# Path smoothing comparison

This module compares the clamped cubic B-spline, local cubic Bézier, and piecewise-quintic smoothers against the raw Hybrid A* coarse path. It is an offline developer analysis tool; it does not alter coarse-path search acceptance.

## Units and coordinates

All path positions, lengths, clearances, and collision-check spacing use **meters**. Heading uses **radians** and vehicle curvature uses `1/m`. Map construction retains its existing millimeter input contract; `PlanningGridMap` provides the meter-coordinate world queries used by smoothing. A smoothing result preserves the coarse path's first and last pose, rather than the original requested goal pose, so its endpoint error is inherited from the coarse planner's accepted goal tolerance.

## Facade usage

Only smooth a successful coarse result. A minimal formal call flow is:

```csharp
if (coarseResult.PlanningResult.Status != PlanningStatus.Success)
    return;
var smoothing = new PathSmoothingService().Smooth(
    new PathSmoothingRequest(
        coarseResult.PlanningResult.Path,
        coarseResult.PlanningResult.Segments,
        coarseResult.MapResult.Map,
        job.Vehicle,
        smoothingConfiguration),
    cancellationToken);
if (smoothing.Status == PathSmoothingStatus.Success ||
    smoothing.Status == PathSmoothingStatus.FallbackToCoarsePath)
    ConsumeSpatialReference(smoothing.Path, smoothing.Segments);
```

## Status handling and fallback

`Success` supplies a validated smoothed path. `FallbackToCoarsePath` is an explicit, safe degraded result and may be consumed by the same downstream spatial-reference interface. `Infeasible`, `InvalidInput`, `Failed`, and `Cancelled` must not be treated as a path. Comparison reports keep an infeasible candidate's markers for diagnosis but never select it as a recommendation.

## Fixture freshness

The eight fast fixtures are snapshots of successful coarse paths. Their configuration fingerprint is checked before use. After deliberately changing a scenario or planning configuration, regenerate them with `generate_path_smoothing_fixtures.ps1 -Overwrite`, then run `verify_path_smoothing_fixtures.ps1`. Fixture-only comparison never runs Hybrid A*.

## IEEE colors, fonts, and Windows PNG

SVG and PNG use the shared IEEE-style colors, status-bearing legends, coordinate ticks, and units. Every raw or smoothed trajectory is rendered as its complete set of discrete samples: reports intentionally draw no line segment between adjacent samples. The Windows PNG renderer requires the exact `SimSun` and `Times New Roman` font families and writes a 600 dpi raster image. If either font is unavailable, export returns `FontUnavailable`; it does not substitute a different font. PNG rendering relies on Windows GDI+, while SVG and CSV remain available without it. SVG uses text-family references, so portable publication requires checking the target font installation or converting text to paths in an external publishing tool.

## SQP boundary

This module is geometric smoothing and full-body validation, not sequential quadratic programming (SQP) trajectory optimization. It has no time parameterization, velocity, acceleration, steering-rate, or dynamic-obstacle constraints. Feed only its validated spatial reference into any later SQP or time-parameterization stage.

## Output files

`run_path_smoothing_comparison.ps1` writes developer reports only below `ClumsyPilot/obj/path_smoothing_reports`. Each scenario directory contains one `comparison.csv` and both SVG and 600 dpi PNG versions of these six focused figures:

1. `01-coarse-path-overview` — the Hybrid A* coarse-path planning view with map, start, and goal.
2. `02-all-paths-comparison` — raw and all three smoother point clouds only, without map or endpoint decorations.
3. `03-cubic-bspline-overview` — faded coarse reference and cubic B-spline result with map context.
4. `04-local-cubic-bezier-overview` — faded coarse reference and local cubic Bézier result with map context.
5. `05-piecewise-quintic-overview` — faded coarse reference and piecewise-quintic result with map context.
6. `06-curvature-comparison` — all available curvature samples with `s (m)` and `κ (m⁻¹)` axes.

Overhead figures preserve equal X/Y scale and use trajectory-focused bounds; their coordinate ticks are in metres. Inspect the SVG/PNG visually, retain CSV for numerical review, and use an external PDF/EPS publishing step if the final venue requires those formats.
