docs: document smoothing processing core

2026-08-04 14:29:51 +08:00
parent 4a7dd875a4
commit 8f6e97e88f
17 changed files with 153 additions and 11 deletions
@@ -11,7 +11,12 @@ public sealed class ArcLengthResampler
 {
    private const double Tolerance = 1e-10d;

-    /// <summary>以目标间距重采样一个方向段；段末锚点始终原样保留。</summary>
+    /// <summary>以目标间距重采样单一方向段；段首/段末精确锚点始终原样保留。</summary>
+    /// <param name="points">同一方向段内按严格递增局部弧长排序的点集合；位置和弧长单位为 m，航向为 rad。</param>
+    /// <param name="spacingMeters">目标采样间距，单位 m，必须为有限正数。</param>
+    /// <param name="resampled">成功时为只读重采样点集合；失败时为空只读集合。</param>
+    /// <param name="reason">失败时描述非法点、退化几何或间距；成功时为空字符串。</param>
+    /// <returns>输入属于一个有效同方向区间且可安全插值时为 <see langword="true"/>；否则为 <see langword="false"/>。</returns>
    public bool TryResample(
        IReadOnlyList<SmoothingPoint2D> points,
        double spacingMeters,
@@ -89,7 +94,12 @@ public sealed class ArcLengthResampler
        return true;
    }

-    /// <summary>重采样一个完整方向段并保留其换向拓扑标记。</summary>
+    /// <summary>重采样完整预处理方向段并保留段编号、方向和换向拓扑标记。</summary>
+    /// <param name="segment">待重采样的单一前进或倒车方向段。</param>
+    /// <param name="spacingMeters">目标局部弧长间距，单位 m。</param>
+    /// <param name="resampled">成功时为新不可变预处理方向段；失败时为 <see langword="null"/>。</param>
+    /// <param name="reason">失败原因；成功时为空字符串。</param>
+    /// <returns>底层点集重采样成功时为 <see langword="true"/>；否则为 <see langword="false"/>。</returns>
    public bool TryResample(
        PreparedDirectionSegment segment,
        double spacingMeters,
@@ -8,6 +8,16 @@ namespace MultiWheelC.TrajectoryPlanning.PathSmoothing.Processing;
 /// <summary>同一几何分析器产生的路径、方向段和未验证质量统计。</summary>
 public sealed class PathGeometryAnalysis
 {
+    /// <summary>创建一次几何重算的只读结果快照。</summary>
+    /// <param name="path">重算后的完整路径点集合。</param>
+    /// <param name="segments">完整覆盖 <paramref name="path"/> 的方向段集合。</param>
+    /// <param name="pathLengthMeters">路径总弧长，单位 m。</param>
+    /// <param name="maximumAbsoluteVehicleCurvaturePerMeter">车辆曲率绝对值峰值，单位 1/m。</param>
+    /// <param name="maximumAbsoluteVehicleCurvatureDerivativePerSquareMeter">车辆曲率导数绝对值峰值，单位 1/m²。</param>
+    /// <param name="rootMeanSquareVehicleCurvaturePerMeter">车辆曲率均方根，单位 1/m。</param>
+    /// <param name="totalAbsoluteCurvatureVariationPerMeter">不跨换向点的累计绝对曲率变化，单位 1/m。</param>
+    /// <param name="curvatureVariationEnergy">不跨换向点的曲率变化代价。</param>
+    /// <param name="minimumBodyClearanceMeters">输入点携带的最小保守车体净空，单位 m。</param>
    internal PathGeometryAnalysis(
        IReadOnlyList<SmoothedPathPoint> path,
        IReadOnlyList<SmoothedPathSegment> segments,
@@ -12,9 +12,12 @@ public sealed class PathGeometryAnalyzer
    private const double MinimumDistanceMeters = 1e-10d;
    private const double BoundaryToleranceMeters = 1e-8d;

-    /// <summary>
-    /// 对候选方向段进行确定性几何分析。换向点两侧永不参与同一次差分。
-    /// </summary>
+    /// <summary>对候选方向段执行确定性几何分析；换向点两侧永不参与同一次航向或曲率差分。</summary>
+    /// <param name="candidateSegments">按段索引排列的候选前进/倒车段；每段点位置为 m、航向为 rad。</param>
+    /// <param name="spacingMeters">最终几何采样间距，单位 m，必须为有限正数。</param>
+    /// <param name="analysis">成功时为完整路径、方向段、弧长、曲率、曲率导数和净空统计；失败时为 <see langword="null"/>。</param>
+    /// <param name="reason">失败时描述输入、边界、退化几何或曲率估计问题；成功时为空字符串。</param>
+    /// <returns>所有方向段和换向拓扑可重采样、可分析且总弧长保持严格递增时为 <see langword="true"/>；否则为 <see langword="false"/>。</returns>
    public bool TryAnalyze(
        IReadOnlyList<PreparedDirectionSegment> candidateSegments,
        double spacingMeters,
@@ -8,6 +8,12 @@ namespace MultiWheelC.TrajectoryPlanning.PathSmoothing.Processing;
 /// <summary>按方向段局部弧长插值平滑算法的原始路径参考。</summary>
 internal static class PathReferenceInterpolator
 {
+    /// <summary>在同一方向段内按局部弧长线性插值一个几何参考点。</summary>
+    /// <param name="points">弧长非递减的原始段采样点集合。</param>
+    /// <param name="targetArcLength">欲查询的局部弧长，单位 m。</param>
+    /// <param name="reference">成功时为插值或精确命中的参考点；失败时为 <see langword="null"/>。</param>
+    /// <param name="reason">失败原因；成功时为空字符串。</param>
+    /// <returns>目标弧长位于有效输入范围内时为 <see langword="true"/>；否则为 <see langword="false"/>。</returns>
    internal static bool TryInterpolateByArcLength(
        IReadOnlyList<SmoothingPoint2D> points,
        double targetArcLength,
@@ -18,13 +18,18 @@ public sealed class PathSmoothingPreprocessor
    {
    }

-    /// <summary>创建使用指定重采样器的预处理器。</summary>
+    /// <summary>创建使用指定确定性弧长重采样器的预处理器。</summary>
+    /// <param name="resampler">同一方向段内按 m 为单位弧长重采样的组件，不能为 <see langword="null"/>。</param>
    public PathSmoothingPreprocessor(ArcLengthResampler resampler)
    {
        _resampler = resampler ?? throw new ArgumentNullException(nameof(resampler));
    }

-    /// <summary>将一条粗路径请求校验、按方向拆分并按配置间距重采样。</summary>
+    /// <summary>校验粗路径契约、保留换向拓扑，并按配置间距拆分和重采样方向段。</summary>
+    /// <param name="request">不可变平滑请求；粗路径位置/弧长单位为 m、航向为 rad，且必须携带地图、车辆和配置。</param>
+    /// <param name="preparedPath">成功时为包含只读、同方向严格递增弧长段的预处理路径；失败时为 <see langword="null"/>。</param>
+    /// <param name="reason">失败时说明输入、拓扑或采样间距约束；成功时为空字符串。</param>
+    /// <returns>所有输入、方向分段、换向锚点和重采样检查通过时为 <see langword="true"/>；否则为 <see langword="false"/> 且不产生部分路径。</returns>
    public bool TryPrepare(PathSmoothingRequest request, out PreparedPath preparedPath, out string reason)
    {
        preparedPath = null;
@@ -9,6 +9,11 @@ namespace MultiWheelC.TrajectoryPlanning.PathSmoothing.Processing;
 public sealed class PreparedDirectionSegment
 {
    /// <summary>创建不可变方向段。</summary>
+    /// <param name="segmentIndex">在 <see cref="PreparedPath.Segments"/> 中从零开始的段索引。</param>
+    /// <param name="direction">本段唯一的车辆行驶方向。</param>
+    /// <param name="points">本段的非空采样点集合；构造后会复制为只读快照。</param>
+    /// <param name="startsAtGearSwitch">若首点紧随换向，则为 <see langword="true"/>。</param>
+    /// <param name="endsAtGearSwitch">若末点紧邻换向，则为 <see langword="true"/>。</param>
    public PreparedDirectionSegment(
        int segmentIndex,
        TravelDirection direction,
@@ -20,6 +25,12 @@ public sealed class PreparedDirectionSegment
    }

    /// <summary>创建带有真实起始车辆曲率边界状态的不可变方向段。</summary>
+    /// <param name="segmentIndex">在 <see cref="PreparedPath.Segments"/> 中从零开始的段索引。</param>
+    /// <param name="direction">本段唯一的车辆行驶方向。</param>
+    /// <param name="points">本段的非空采样点集合；构造后会复制为只读快照。</param>
+    /// <param name="startsAtGearSwitch">若首点紧随换向，则为 <see langword="true"/>。</param>
+    /// <param name="endsAtGearSwitch">若末点紧邻换向，则为 <see langword="true"/>。</param>
+    /// <param name="startVehicleCurvaturePerMeter">物理起点车辆曲率边界，单位 1/m；未知时为 <see langword="null"/>。</param>
    public PreparedDirectionSegment(
        int segmentIndex,
        TravelDirection direction,
@@ -8,6 +8,7 @@ namespace MultiWheelC.TrajectoryPlanning.PathSmoothing.Processing;
 public sealed class PreparedPath
 {
    /// <summary>创建不可变预处理路径。</summary>
+    /// <param name="segments">按原始行驶顺序排列的非空方向段集合；构造后会复制为只读快照。</param>
    public PreparedPath(IReadOnlyList<PreparedDirectionSegment> segments)
    {
        if (segments == null || segments.Count == 0)
@@ -22,10 +23,10 @@ public sealed class PreparedPath
        Points = Flatten(Segments);
    }

-    /// <summary>按原始前进/倒车拓扑排列的方向段。</summary>
+    /// <summary>按原始前进/倒车拓扑排列的 <see cref="PreparedDirectionSegment"/> 只读集合。</summary>
    public IReadOnlyList<PreparedDirectionSegment> Segments { get; }

-    /// <summary>将所有方向段顺序拼接后的点；换向重复点保留两次。</summary>
+    /// <summary>将所有方向段顺序拼接后的 <see cref="SmoothingPoint2D"/> 只读集合；换向重复点保留两次。</summary>
    public IReadOnlyList<SmoothingPoint2D> Points { get; }

    private static IReadOnlyList<T> CopyReadOnly<T>(IReadOnlyList<T> source)
@@ -7,6 +7,14 @@ namespace MultiWheelC.TrajectoryPlanning.PathSmoothing.Processing;
 public sealed class SmoothingPoint2D
 {
    /// <summary>创建不可变二维路径点。</summary>
+    /// <param name="xMeters">世界坐标 X，单位 m。</param>
+    /// <param name="yMeters">世界坐标 Y，单位 m。</param>
+    /// <param name="arcLengthMeters">本方向段内从零开始的累计弧长，单位 m。</param>
+    /// <param name="headingRadians">归一化车辆航向，单位 rad。</param>
+    /// <param name="unwrappedHeadingRadians">连续展开的车辆航向，单位 rad。</param>
+    /// <param name="bodyClearanceMeters">路径点携带的保守车体净空，单位 m。</param>
+    /// <param name="isGearSwitchPoint">该点是否标记新方向段的换向边界。</param>
+    /// <param name="source">点在平滑处理流中的来源枚举。</param>
    public SmoothingPoint2D(
        double xMeters,
        double yMeters,