ParkingRobot/ClumsyPilot/ParkrobTrajplanner/PathSmoothing/Contracts/PathQualityMetrics.cs

namespace MultiWheelC.TrajectoryPlanning.PathSmoothing;

/// <summary>一条原始或平滑路径的不可变质量指标。</summary>
public sealed class PathQualityMetrics
{
    /// <summary>创建全零、不可行的质量指标。</summary>
    public PathQualityMetrics()
        : this(false, 0d, 0d, 0d, 0d, 0d, 0d, 0d, 0d, 0d, 0d, 0d)
    {
    }

    /// <summary>创建不显式提供曲率导数峰值的完整质量指标快照；曲率导数峰值按 0 处理。</summary>
    /// <param name="isFeasible">是否通过完整安全和运动学复核。</param>
    /// <param name="pathLengthMeters">路径总弧长，单位 m。</param>
    /// <param name="maximumAbsoluteVehicleCurvaturePerMeter">绝对车辆曲率峰值，单位 1/m。</param>
    /// <param name="rootMeanSquareVehicleCurvaturePerMeter">车辆曲率均方根，单位 1/m。</param>
    /// <param name="totalAbsoluteCurvatureVariationPerMeter">按方向段累计的绝对曲率变化，单位 1/m。</param>
    /// <param name="curvatureVariationEnergy">无单位的曲率变化能量/代价。</param>
    /// <param name="minimumBodyClearanceMeters">扩大车体的最小保守净空，单位 m。</param>
    /// <param name="lengthChangePercent">相对原始粗路径的长度变化百分比。</param>
    /// <param name="peakCurvatureChangePercent">相对原始粗路径的峰值曲率变化百分比。</param>
    /// <param name="curvatureVariationChangePercent">相对原始粗路径的曲率变化百分比。</param>
    /// <param name="minimumClearanceChangeMeters">相对原始粗路径的最小净空变化，单位 m。</param>
    public PathQualityMetrics(
        bool isFeasible,
        double pathLengthMeters,
        double maximumAbsoluteVehicleCurvaturePerMeter,
        double rootMeanSquareVehicleCurvaturePerMeter,
        double totalAbsoluteCurvatureVariationPerMeter,
        double curvatureVariationEnergy,
        double minimumBodyClearanceMeters,
        double lengthChangePercent,
        double peakCurvatureChangePercent,
        double curvatureVariationChangePercent,
        double minimumClearanceChangeMeters)
        : this(
            isFeasible,
            pathLengthMeters,
            maximumAbsoluteVehicleCurvaturePerMeter,
            0d,
            rootMeanSquareVehicleCurvaturePerMeter,
            totalAbsoluteCurvatureVariationPerMeter,
            curvatureVariationEnergy,
            minimumBodyClearanceMeters,
            lengthChangePercent,
            peakCurvatureChangePercent,
            curvatureVariationChangePercent,
            minimumClearanceChangeMeters)
    {
    }

    /// <summary>创建包含曲率导数峰值的完整质量指标快照。</summary>
    /// <param name="isFeasible">是否通过完整安全和运动学复核。</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>
    /// <param name="lengthChangePercent">相对原始粗路径的长度变化百分比。</param>
    /// <param name="peakCurvatureChangePercent">相对原始粗路径的峰值曲率变化百分比。</param>
    /// <param name="curvatureVariationChangePercent">相对原始粗路径的曲率变化百分比。</param>
    /// <param name="minimumClearanceChangeMeters">相对原始粗路径的最小净空变化，单位 m。</param>
    public PathQualityMetrics(
        bool isFeasible,
        double pathLengthMeters,
        double maximumAbsoluteVehicleCurvaturePerMeter,
        double maximumAbsoluteVehicleCurvatureDerivativePerSquareMeter,
        double rootMeanSquareVehicleCurvaturePerMeter,
        double totalAbsoluteCurvatureVariationPerMeter,
        double curvatureVariationEnergy,
        double minimumBodyClearanceMeters,
        double lengthChangePercent,
        double peakCurvatureChangePercent,
        double curvatureVariationChangePercent,
        double minimumClearanceChangeMeters)
    {
        IsFeasible = isFeasible;
        PathLengthMeters = pathLengthMeters;
        MaximumAbsoluteVehicleCurvaturePerMeter = maximumAbsoluteVehicleCurvaturePerMeter;
        MaximumAbsoluteVehicleCurvatureDerivativePerSquareMeter = maximumAbsoluteVehicleCurvatureDerivativePerSquareMeter;
        RootMeanSquareVehicleCurvaturePerMeter = rootMeanSquareVehicleCurvaturePerMeter;
        TotalAbsoluteCurvatureVariationPerMeter = totalAbsoluteCurvatureVariationPerMeter;
        CurvatureVariationEnergy = curvatureVariationEnergy;
        MinimumBodyClearanceMeters = minimumBodyClearanceMeters;
        LengthChangePercent = lengthChangePercent;
        PeakCurvatureChangePercent = peakCurvatureChangePercent;
        CurvatureVariationChangePercent = curvatureVariationChangePercent;
        MinimumClearanceChangeMeters = minimumClearanceChangeMeters;
    }

    /// <summary>该路径是否通过完整安全和运动学复核。</summary>
    public bool IsFeasible { get; }

    /// <summary>路径总弧长，单位 m。</summary>
    public double PathLengthMeters { get; }

    /// <summary>绝对车辆曲率峰值，单位 1/m。</summary>
    public double MaximumAbsoluteVehicleCurvaturePerMeter { get; }

    /// <summary>绝对车辆曲率导数峰值，单位 1/m²。</summary>
    public double MaximumAbsoluteVehicleCurvatureDerivativePerSquareMeter { get; }

    /// <summary>车辆曲率均方根，单位 1/m。</summary>
    public double RootMeanSquareVehicleCurvaturePerMeter { get; }

    /// <summary>逐方向段累加的绝对曲率变化，单位 1/m。</summary>
    public double TotalAbsoluteCurvatureVariationPerMeter { get; }

    /// <summary>逐方向段计算的曲率变化能量。</summary>
    public double CurvatureVariationEnergy { get; }

    /// <summary>曲率变化代价的兼容名称。</summary>
    public double CurvatureVariationCost => CurvatureVariationEnergy;

    /// <summary>完整扩大车体的最小保守净空，单位 m。</summary>
    public double MinimumBodyClearanceMeters { get; }

    /// <summary>相对原始粗路径的长度变化百分比。</summary>
    public double LengthChangePercent { get; }

    /// <summary>相对原始粗路径的峰值曲率变化百分比。</summary>
    public double PeakCurvatureChangePercent { get; }

    /// <summary>相对原始粗路径的曲率变化百分比。</summary>
    public double CurvatureVariationChangePercent { get; }

    /// <summary>相对原始粗路径的最小净空变化，单位 m。</summary>
    public double MinimumClearanceChangeMeters { get; }
}