chore: save current workspace progress

2026-08-09 22:13:18 +08:00
parent 650c2ab0e3
commit 2f4fd15e52
449 changed files with 76593 additions and 971 deletions
@@ -0,0 +1,56 @@
+# 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.