geopro/external/gpr3dviewer/RadarProcessor.h

/*
 * RadarProcessor.h
 * 探地雷达GPR数据预处理算法核心类头文件
 * 功能：封装全套雷达道数据校正、滤波、增益、均衡、希尔伯特包络算法
 * 架构：模块化单步骤参数结构体 + 流水线顺序调度执行
 * 对接：MainWindow UI界面参数绑定、GPRDataModel三维道集数据模型
 * 适配：RAD/RD3格式多通道、多测线原始雷达数据
 */
#ifndef RADARPROCESSOR_H
#define RADARPROCESSOR_H

#include "GPRDataModel.h"
#include <QVector>
#include <QString>
#include <functional>

class RadarProcessor
{
public:
    /**
     * @brief 所有可执行预处理步骤枚举标识
     * 流水线严格按照枚举顺序业务逻辑排布
     */
    enum class ProcStepType
    {
        StepTimeZeroCut,        // 0：零时校正（切除直达波零点）
        StepZeroDrift,          // 1：道基线零漂消除
        StepRemoveDC,           // 2：简易整道直流偏移扣除
        StepBackgroundRemove,   // 3：剖面背景均值压制
        StepSphericalTVG,       // 4：球面扩散+介质吸收TVG深度增益
        StepBandpassFilter,     // 5：FIR带通滤波剔除高低频噪声
        StepProfileSmooth,      // 6：时空剖面平滑降噪
        StepInnerAGC,           // 7：单道内自适应振幅均衡AGC
        StepTraceToTraceAGC,    // 8：道与道之间整体振幅均衡
        StepHilbertTransform,   // 9：希尔伯特变换（包络/正交分量）
        StepGlobalGain,         // 10：全局统一倍率增益放大
        StepMigration           // 11：Kirchhoff偏移
    };

    //=========================================================================
    // 1. 零时切除参数结构体 StepTimeZeroCut
    // 作用：定位直达波起跳零点，裁掉零点前无效采样点，统一道起始位置
    //=========================================================================
    struct TimeZeroCutParams
    {
        bool autoDetect = true;                // true=自动识别零点；false=手动固定裁掉前N个采样
        int cutSamples = 30;                   // 手动模式裁切采样点数
        int frontSearchWindow = 180;           // 零点搜索窗口：只在道前180个采样内找起跳点
        double noiseSigmaMultiple = 3.0;        // 起跳判定阈值：噪声标准差倍数，大于判定为有效直达波
        bool enable = false;                   // 流水线开关：是否启用本步骤
    };

    /**
     * @brief 零漂消除模式枚举
     */
    enum class ZeroDriftMode
    {
        DC,         // 模式1：整道均值直流偏移一次性扣除（速度快）
        Sliding     // 模式2：滑动窗口逐段扣除基线（适合长时漂移严重数据）
    };
    struct ZeroDriftParams
    {
        ZeroDriftMode mode = ZeroDriftMode::Sliding;
        int slidingWindowSamples = 100;        // 滑动窗口采样点数，仅Sliding模式生效
        bool enable = false;
    };

    //=========================================================================
    // TVG球面深度增益 StepSphericalTVG
    // 物理原理：电磁波随传播距离球面扩散衰减+介质吸收衰减
    //=========================================================================
    struct SphericalTvgParams {
        bool enableSpherical = true;           // 开启球面扩散补偿
        bool enableAbsorption = true;          // 开启介质吸收衰减补偿
        double velocityMPerNs = 0.12;           // 雷达波速(m/ns)，从GPRDataHeader自动读取
        double referenceDepthM = 0.01;         // 参考基准深度（增益归一化基准）
        double exponent = 1.5;                 // 扩散指数：空气1.0、土体/混凝土常用1.0~2.0
        double absorptionBeta = 1.0;           // 吸收系数 β (dB/m)，干土小、湿土大
        double maxGain = 30.0;                 // 最大增益上限，防止深层噪声过度放大
        bool enable = false;
    };

    //=========================================================================
    // 带通滤波 StepBandpassFilter
    // 滤除天线主频外低频漂移、高频仪器白噪声
    //=========================================================================
    struct BandpassParams
    {
        bool autoFreq = true;                  // true自动根据天线主频计算通带；false手动填高低频
        double lowFreqHz = 1000;                // 通带下限(Hz)
        double highFreqHz = 100;              // 通带上限(Hz)
        double antennaFreqMHz = 200.0;          // 天线中心频率(MHz)，自动模式读取头文件
        bool enable = false;
    };

    //=========================================================================
    // 剖面二维平滑 StepProfileSmooth
    // 垂直=深度方向平滑；水平=测线道方向平滑
    //=========================================================================
    struct ProfileSmoothParams
    {
        int smoothWindow = 2;                  // 半窗口大小，实际总窗口=2*window+1
        bool verticalSmooth = true;            // 深度方向平滑开关
        bool horizontalSmooth = true;          // 测线道方向平滑开关
        bool enable = false;
    };

    //=========================================================================
    // 背景去除 StepBackgroundRemove
    // 压制整剖面静态杂波、地面耦合固定反射、钢筋/管线持续干扰
    //=========================================================================
    enum class BackgroundMode
    {
        MeanAverage,        // 均值法：多道平均作为背景相减，通用稳定
        SingularityFilter   // 奇异值滤波：保留强异常，压制平缓背景（空洞/管线优选）
    };
    struct BackgroundParams
    {
        BackgroundMode mode = BackgroundMode::MeanAverage;
        int averageTraceCount = 301;           // 参与平均背景的同通道道数量
        double singularityThreshold = 1.8;      // 奇异判定阈值，越大越不容易抹掉小异常
        bool enable = false;
    };

    //=========================================================================
    // 道内AGC StepInnerAGC
    // 同一道内深浅振幅均衡，消除天然深度衰减（TVG补充均衡）
    //=========================================================================
    struct TraceInnerAgcParams {
        int windowSamples = 120;               // 道内滑动RMS统计窗口
        double targetRms = 0.0;                // 目标RMS值；0=自适应均衡
        double maxGain = 6.0;                  // 单窗口最大增益限制
        double epsilon = 1.0;                  // 防除零极小值
        bool enable = false;
    };

    //=========================================================================
    // 道间AGC StepTraceToTraceAGC
    // 整条测线所有道之间振幅拉平，消除收发耦合波动、行走速度不均
    //=========================================================================
    enum class TraceToTraceMode
    {
        Global,     // 全局：全部道统一均衡基准
        Local       // 局部：滑动窗口相邻道均衡（起伏大路面优选）
    };
    struct TraceToTraceAgcParams {
        TraceToTraceMode mode = TraceToTraceMode::Local;
        int horizontalWindowTraces = 31;       // 局部模式滑动道窗口
        double targetRms = 0.0;
        double maxGain = 4.0;
        double epsilon = 1.0;
        bool enable = false;
    };

    //=========================================================================
    // 希尔伯特变换 StepHilbertTransform
    // 输出振幅包络（成像常用）或正交虚部（相位分析）
    //=========================================================================
    struct HilbertParams
    {
        bool computeEnvelope = true;           // true=振幅包络；false=正交相位分量
        bool enable = false;
    };

    // 全局倍率增益
    struct GlobalGainParams
    {
        double factor = 1.0;                   // 放大倍数，0.1~10区间常用
        bool enable = false;
    };

    // 简易去直流（轻量零漂）
    struct DcShiftParams
    {
        bool enable = false;
    };

    //=========================================================================
    // Kirchhoff偏移参数
    //=========================================================================
    struct MigrationParams
    {
        int sumWidth = 64;                     // 两侧各求和的迹线数量
        double velocityMPerNs = 0.12;           // 雷达波速(m/ns)
        bool enable = false;
    };

    //=========================================================================
    // 流水线单步单元：存储步骤类型 + 全套独立参数
    //=========================================================================
    struct ProcStepUnit
    {
        ProcStepType type;

        // 全部算法参数容器，运行时仅type对应的结构体生效
        TimeZeroCutParams zeroCut;
        SphericalTvgParams tvg;
        BandpassParams band;
        ProfileSmoothParams smooth;
        BackgroundParams bg;
        ZeroDriftParams zeroDrift;
        TraceInnerAgcParams innerAgc;
        TraceToTraceAgcParams traceAgc;
        HilbertParams hilbert;
        GlobalGainParams gain;
        DcShiftParams dc;
        MigrationParams migration;
    };

    //=========================================================================
    // 完整预处理流水线：有序步骤队列 + 默认标准流程
    //=========================================================================
    struct ProcPipeline
    {
        QVector<ProcStepUnit> steps;

        /**
         * @brief 加载工业通用标准处理流水线（道路检测默认）
         * 顺序：零时→零漂→背景→TVG增益→带通→平滑→内AGC→道间AGC→包络
         */
        void setDefaultFlow()
        {
            steps.clear();

            // 1. 零时校正
            ProcStepUnit s0;
            s0.type = ProcStepType::StepTimeZeroCut;
            s0.zeroCut.autoDetect = true;
            s0.zeroCut.cutSamples = 30;
            s0.zeroCut.frontSearchWindow = 180;
            s0.zeroCut.noiseSigmaMultiple = 3.0;
            s0.zeroCut.enable = true;
            steps.append(s0);

            // 2. 零漂去除
            ProcStepUnit s1;
            s1.type = ProcStepType::StepZeroDrift;
            s1.zeroDrift.mode = ZeroDriftMode::Sliding;
            s1.zeroDrift.slidingWindowSamples = 100;
            s1.zeroDrift.enable = true;
            steps.append(s1);

            // 3. 背景压制
            ProcStepUnit s2;
            s2.type = ProcStepType::StepBackgroundRemove;
            s2.bg.mode = BackgroundMode::MeanAverage;
            s2.bg.averageTraceCount = 301;
            s2.bg.enable = true;
            steps.append(s2);

            // 4. TVG深度增益
            ProcStepUnit s3;
            s3.type = ProcStepType::StepSphericalTVG;
            s3.tvg.enableSpherical = true;
            s3.tvg.enableAbsorption = true;
            s3.tvg.exponent = 1.0;
            s3.tvg.maxGain = 20.0;
            s3.tvg.absorptionBeta = 0.002;
            s3.tvg.enable = true;
            steps.append(s3);

            // 5. 带通滤波
            ProcStepUnit s4;
            s4.type = ProcStepType::StepBandpassFilter;
            s4.band.autoFreq = true;
            s4.band.lowFreqHz = 100;
            s4.band.highFreqHz = 1500;
            s4.band.enable = true;
            steps.append(s4);

            // 6. 剖面平滑
            ProcStepUnit s5;
            s5.type = ProcStepType::StepProfileSmooth;
            s5.smooth.smoothWindow = 2;
            s5.smooth.verticalSmooth = true;
            s5.smooth.horizontalSmooth = true;
            s5.smooth.enable = true;
            steps.append(s5);

            // 7. 道内AGC
            ProcStepUnit s6;
            s6.type = ProcStepType::StepInnerAGC;
            s6.innerAgc.windowSamples = 120;
            s6.innerAgc.maxGain = 6.0;
            s6.innerAgc.enable = true;
            steps.append(s6);

            // 8. 道间均衡AGC
            ProcStepUnit s7;
            s7.type = ProcStepType::StepTraceToTraceAGC;
            s7.traceAgc.mode = TraceToTraceMode::Local;
            s7.traceAgc.horizontalWindowTraces = 31;
            s7.traceAgc.maxGain = 4.0;
            s7.traceAgc.enable = true;
            steps.append(s7);
        }
    };

public:
    struct PipelineRuntimeContext {
        std::function<bool()> isCanceled;
        std::function<void(int stepIndex, int stepCount, const QString &stepName)> reportProgress;
    };

    RadarProcessor();

    //==================== 单算法静态处理函数 ====================
    /// 简易去除整道直流偏移
    static GPRDataModel removeDCShift(const GPRDataModel &input, const DcShiftParams& param);
    /// 零漂基线校正
    static GPRDataModel removeZeroDrift(const GPRDataModel &input, const ZeroDriftParams& param);
    /// 全局统一倍率增益
    static GPRDataModel applyGain(const GPRDataModel &input, const GlobalGainParams& param);
    /// TVG球面+吸收深度增益补偿
    static GPRDataModel sphericalTvg(const GPRDataModel &input, const SphericalTvgParams &params);
    /// 二维剖面均值平滑
    static GPRDataModel profileSmooth(const GPRDataModel &input, const ProfileSmoothParams &params);
    /// 道内滑动AGC均衡
    static GPRDataModel traceInnerAgc(const GPRDataModel &input, const TraceInnerAgcParams &params);
    /// 道与道之间振幅均衡
    static GPRDataModel traceToTraceEqualization(const GPRDataModel &input, const TraceToTraceAgcParams &params);
    /// 希尔伯特变换包络/相位
    static GPRDataModel hilbertTransform(const GPRDataModel &input, const HilbertParams &params);

    /// 零点自动/手动裁切算法实现
    static GPRDataModel cutTimeZero(const GPRDataModel& input, const TimeZeroCutParams& param);
    /// FIR带通滤波实现
    static GPRDataModel bandpassFilter(const GPRDataModel &input, const BandpassParams &params);
    /// 背景杂波去除实现（均值/奇异滤波双模式）
    static GPRDataModel backgroundRemoval(const GPRDataModel &input, const BackgroundParams &params);
    /// Kirchhoff偏移（x-t域双曲线求和）
    static GPRDataModel kirchhoffMigration(const GPRDataModel &input, const MigrationParams &params);

    /**
     * @brief 流水线总执行入口
     * @param rawData 原始未处理GPR三维道集数据
     * @param pipeline 有序步骤流水线配置
     * @return 逐步骤处理完成后的成品数据
     */
    static GPRDataModel runPipeline(const GPRDataModel& rawData, const ProcPipeline& pipeline);
    static GPRDataModel runPipeline(const GPRDataModel& rawData,
                                    const ProcPipeline& pipeline,
                                    const PipelineRuntimeContext *context);
};

#endif // RADARPROCESSOR_H