简介这是一份面向Qt与C开发者、数据可视化学习者的实战示例包围绕QCustomPlot控件实现瀑布图展开适合已具备Qt基础、希望掌握自定义2D图表绘制与动态效果的中级开发者。压缩包共36个文件约6.08MB以cpp与h源码为核心辅以o、obj编译产物、makefile构建脚本、ui界面文件及pro工程配置并包含exe可执行程序与pdb调试符号便于直接运行与二次开发。资源完整呈现了QCustomPlot的初始化、轴与图层设置、随机数据生成、QCPGraph分层绘制、连接线处理及replot刷新等关键环节同时涉及逐帧动画与鼠标交互事件响应代码按数据处理、图形设置与事件逻辑分层组织结构清晰。目前已有7815人学习下载读者可借此理解瀑布图的数据结构与绘制流程掌握Qt自定义绘图组件的设计思路并将其迁移到财务分析、项目管理等数据变化展示场景中。1. 从一张“会流动的频谱图”说起这个 Qt 瀑布图 Demo 到底能干什么如果你做过频谱分析、雷达回波、声呐扫描或者任何需要“时间 频率 强度”三维信息可视化的上位机大概率绕不开瀑布图这个东西。它把一帧一帧的频谱数据按时间轴往下堆颜色深浅代表信号强弱跑起来就像一条不断向下流动的彩色瀑布。用 Qt 做这类界面绕不开一个第三方库——QCustomPlot。它只有一对.h/.cpp文件却能画出曲线、柱状、热力图性能也扛得住实时刷新。这个 Demo 干的事很明确用 QCustomPlot 的QCPColorMap把二维数据矩阵映射成颜色图再配合定时器不断“推入”新数据、滚动旧数据做出一个能实时刷新的瀑布图效果。适合谁适合正在用 Qt/C 写上位机、需要做频谱或热力可视化的开发者尤其是那些不想引入庞大图表框架、只想塞两个文件进工程就开干的人。下面我按“能跑起来 → 看懂结构 → 改得动”的顺序把这个 Demo 拆一遍。2. 环境搭建与最小可运行工程把 QCustomPlot 塞进 Qt 项目2.1 依赖清单与工程文件配置这个 Demo 的依赖极简核心就三样Qt建议 5.12 以上Qt6 也能跑、QCustomPlot 源码、一个支持 C11 的编译器。QCustomPlot 官方只提供qcustomplot.h和qcustomplot.cpp两个文件没有动态库直接源码编译进工程。常见做法是把这两个文件放到工程目录下的third_party/qcustomplot/里然后在.pro里显式加入。# 目录结构建议 WaterfallDemo/ ├── WaterfallDemo.pro ├── main.cpp ├── mainwindow.h ├── mainwindow.cpp ├── mainwindow.ui └── third_party/ └── qcustomplot/ ├── qcustomplot.h └── qcustomplot.cpp.pro文件里要加的东西不多但有两个坑一是 QCustomPlot 用到了 printsupport 模块Qt5 下必须显式链接二是如果开了QT_NO_PRINTER编译会报一堆未定义符号。QT core gui printsupport greaterThan(QT_MAJOR_VERSION, 4): QT widgets CONFIG c11 SOURCES \ main.cpp \ mainwindow.cpp \ third_party/qcustomplot/qcustomplot.cpp HEADERS \ mainwindow.h \ third_party/qcustomplot/qcustomplot.h FORMS mainwindow.uiprintsupport是 QCustomPlot 导出图片和打印功能依赖的模块不加会在链接阶段报QPrinter相关错误。c11是 QCustomPlot 内部用到的特性要求Qt5 默认可能没开显式写上更稳。2.2 界面初始化创建 ColorMap 与坐标轴界面部分我一般不在.ui里拖 QCustomPlot 控件而是代码里直接 new 一个QCustomPlot塞进布局这样后续换布局更灵活。核心初始化就三步创建QCPColorMap、配置颜色梯度、设置坐标轴范围。// mainwindow.cpp 构造函数片段 void MainWindow::initPlot() { // 1. 创建 QCustomPlot 实例并加入布局 m_plot new QCustomPlot(this); setCentralWidget(m_plot); // 2. 创建颜色图对象绑定到 x/y 轴 m_colorMap new QCPColorMap(m_plot-xAxis, m_plot-yAxis); // 3. 设置数据矩阵尺寸x 方向 256 个频点y 方向 100 行时间 m_colorMap-data()-setSize(256, 100); m_colorMap-data()-setRange( QCPRange(0, 256), // x 轴频率索引 QCPRange(0, 100)); // y 轴时间行 // 4. 颜色梯度从深蓝到红色模拟信号强度 QCPColorGradient gradient; gradient.setColorStopAt(0.0, QColor(0, 0, 80)); gradient.setColorStopAt(0.5, QColor(0, 200, 200)); gradient.setColorStopAt(1.0, QColor(255, 60, 0)); m_colorMap-setGradient(gradient); // 5. 自动缩放颜色范围让弱信号也能看见 m_colorMap-setDataScaleType(QCPAxis::stLinear); m_colorMap-rescaleDataRange(true); // 6. 坐标轴标签 m_plot-xAxis-setLabel(Frequency Bin); m_plot-yAxis-setLabel(Time Frame); m_plot-replot(); }setSize(256, 100)决定了瀑布图的分辨率x 方向 256 个频点y 方向保留 100 帧历史。setRange把矩阵索引映射到坐标轴数值这里直接用索引当坐标实际项目里可以换成真实频率值。rescaleDataRange(true)里的true表示只考虑当前可见区域的数据范围避免历史极值把颜色压扁。颜色梯度用setColorStopAt定义三个锚点比默认的灰度图直观得多。2.3 定时器驱动让数据“流”起来瀑布图的“流动感”靠定时器不断推入新数据实现。常见做法是用QTimer每 50ms 触发一次模拟一帧新频谱然后把矩阵整体上移一行新数据填到底部。// 启动定时器 m_timer new QTimer(this); connect(m_timer, QTimer::timeout, this, MainWindow::onTick); m_timer-start(50); // 20 FPS void MainWindow::onTick() { // 1. 整体上移一行从第 1 行开始把数据复制到第 0 行 for (int y 0; y 99; y) { for (int x 0; x 256; x) { double v m_colorMap-data()-cell(x, y 1); m_colorMap-data()-setCell(x, y, v); } } // 2. 生成新一帧数据填到底部第 99 行 for (int x 0; x 256; x) { // 模拟中心频率附近高斯峰 随机噪声 double center 128.0; double sigma 20.0; double signal 1.0 * exp(-pow(x - center, 2) / (2 * sigma * sigma)); double noise (rand() % 100) / 500.0; m_colorMap-data()-setCell(x, 99, signal noise); } // 3. 重绘 m_colorMap-rescaleDataRange(true); m_plot-replot(QCustomPlot::rpQueuedReplot); }这段代码是瀑布图的核心逻辑。第一步的双层循环做数据搬移把第y1行的值赋给第y行相当于整个图像向上滚动一行。第二步在最后一行生成新数据这里用高斯峰加随机噪声模拟一个中心频率在 128 附近的信号。第三步rescaleDataRange(true)重新计算颜色映射范围rpQueuedReplot是 QCustomPlot 提供的排队重绘模式比直接replot()更省 CPU尤其在 20 FPS 以上时差别明显。注意数据搬移用双层循环在 256×100 规模下没问题但如果矩阵到 1024×500这个 O(n) 拷贝会成为瓶颈。后面第 5 章会讲怎么用环形缓冲区优化。3. 核心模块拆解QCPColorMap 的数据组织与渲染链路3.1 QCPColorMapData 的内存布局QCustomPlot 的颜色图数据存在QCPColorMapData里内部是一个一维QVectordouble按行优先排列。cell(x, y)和setCell(x, y, v)是访问接口索引计算公式是y * keySize x。理解这一点很重要因为所有性能优化都围绕这个布局展开。// QCPColorMapData 内部简化示意非源码帮助理解 class QCPColorMapData { QVectordouble mData; // 一维数组行优先 int mKeySize; // x 方向尺寸 int mValueSize; // y 方向尺寸 double cell(int x, int y) const { return mData[y * mKeySize x]; } void setCell(int x, int y, double v) { mData[y * mKeySize x] v; } };行优先意味着同一行的数据在内存里连续跨行访问会跳mKeySize个元素。所以第 2 章那个搬移循环如果按列遍历外层 x、内层 y缓存命中率会差很多。我一般把外层设成 y、内层设成 x让内存访问尽量连续。3.2 颜色映射与数据范围缩放QCPColorMap把数值映射到颜色分两步先通过dataScaleType把原始值变换到 [0,1]再通过QCPColorGradient查表得到颜色。默认是线性缩放但如果数据动态范围大比如 60dB 的频谱线性映射会让弱信号全挤在深色区。这时候可以换成对数缩放。// 对数缩放适合大动态范围频谱 m_colorMap-setDataScaleType(QCPAxis::stLogarithmic); // 手动指定颜色范围避免每帧 rescale 带来的闪烁 m_colorMap-setDataRange(QCPRange(0.001, 1.0));setDataScaleType(QCPAxis::stLogarithmic)会把数据先取对数再映射弱信号能被拉开。但注意对数缩放要求数据全为正数如果有零或负值QCustomPlot 会做截断处理可能出现颜色突变。setDataRange手动锁定范围可以避免自动缩放导致的整体闪烁代价是超出范围的信号会被截断成极值色。3.3 渲染性能replot 模式与刷新策略QCustomPlot 的replot()有几种模式默认是rpImmediateRefresh立即重绘并刷新控件。高频调用时 CPU 占用会很高。rpQueuedReplot把重绘请求排队合并同一事件循环内的多次调用适合定时器驱动场景。// 三种重绘模式对比 m_plot-replot(QCustomPlot::rpImmediateRefresh); // 立即重绘刷新 m_plot-replot(QCustomPlot::rpQueuedReplot); // 排队合并多次请求 m_plot-replot(QCustomPlot::rpRefreshHint); // 仅标记需要重绘实测在 20 FPS 下rpQueuedReplot比rpImmediateRefresh的 CPU 占用低 30% 左右。如果刷新率更高还可以考虑关闭抗锯齿m_plot-setNotAntialiasedElements(QCP::aeAll)颜色图本身不需要抗锯齿关了能省不少。4. 避坑与常见问题排查那些让我熬夜的报错4.1 编译报错 “undefined reference to QPrinter”现象链接阶段报一堆QPrinter、QPrintDialog未定义符号。原因.pro里没加printsupport模块。解决在.pro顶部加QT printsupport然后重新执行 qmake。如果用的是 CMake对应find_package(Qt5 COMPONENTS PrintSupport REQUIRED)并链接Qt5::PrintSupport。4.2 瀑布图不刷新或只显示第一帧现象定时器在跑但界面纹丝不动。原因replot()被调用但数据没变或者rescaleDataRange把范围锁死了。排查步骤先在onTick里打印m_colorMap-data()-cell(128, 99)确认数据在变再检查setDataRange是否被手动设成了固定值。如果是固定值新数据超出范围会被截断看起来就像没刷新。4.3 颜色图整体偏暗或全黑现象数据明明有值但显示出来一片黑。原因rescaleDataRange的onlyVisiblePlottables参数传了false导致历史极值把当前帧压扁。解决改成rescaleDataRange(true)或者手动setDataRange到一个合理区间。另一个可能是颜色梯度的锚点全设在了低值区检查setColorStopAt的分布。4.4 高频刷新时界面卡顿现象刷新率一过 30 FPS界面就拖影、按钮点不动。原因replot()在主线程同步执行数据搬移也是 O(n) 拷贝。解决把数据生成放到工作线程用信号槽把新帧传给 UI 线程搬移逻辑改用环形缓冲区第 5 章讲重绘用rpQueuedReplot。如果还卡考虑降低矩阵分辨率或关闭抗锯齿。4.5 Qt6 下编译报 “QCPAxis::stLinear 未定义”现象Qt5 能编Qt6 报错。原因Qt6 把一些枚举挪了位置QCustomPlot 老版本没适配。解决去 QCustomPlot 官网下最新版2.1.1 以上或者手动把QCPAxis::stLinear改成QCPAxis::ScaleType::stLinear。这个坑在 Qt5 升 Qt6 时很常见血泪经验是先把 QCustomPlot 升到最新再动业务代码。5. 二次开发改造从 Demo 到能用的频谱瀑布图5.1 用环形缓冲区替换数据搬移第 2 章那个双层循环搬移在 256×100 下耗时约 0.1ms但矩阵一大就顶不住。更优雅的做法是环形缓冲区不搬数据只移动“写指针”渲染时按逻辑顺序读取。class RingBuffer { public: RingBuffer(int width, int height) : mWidth(width), mHeight(height), mData(width * height, 0.0), mHead(0) {} // 写入新一帧覆盖最旧的一行 void pushFrame(const QVectordouble frame) { int row mHead % mHeight; for (int x 0; x mWidth; x) { mData[row * mWidth x] frame[x]; } mHead; } // 按逻辑顺序读取最旧的行在前 double at(int x, int y) const { int row (mHead y) % mHeight; return mData[row * mWidth x]; } private: int mWidth, mHeight; QVectordouble mData; int mHead; // 下一个写入位置 };pushFrame只写一行O(width) 复杂度比原来的 O(width×height) 快了一个数量级。at(x, y)里的(mHead y) % mHeight把环形索引映射成逻辑顺序y0 永远是最旧的一帧。渲染时遍历at填充QCPColorMapData或者直接继承QCPColorMapData重写访问接口省掉一次拷贝。5.2 接入真实数据源与多通道扩展Demo 里用高斯峰模拟数据实际项目里数据可能来自串口、网口或采集卡。常见做法是定义一个数据源接口把生成逻辑和 UI 解耦。class IDataSource { public: virtual ~IDataSource() default; virtual QVectordouble nextFrame() 0; }; class SerialSource : public IDataSource { public: QVectordouble nextFrame() override { // 从串口读一帧解析成 256 个 double QByteArray raw m_port.readAll(); return parseFrame(raw); } private: QSerialPort m_port; };多通道扩展的思路是每个通道一个QCPColorMap叠在同一个QCustomPlot里用setVisible切换。或者用QCPColorMap的setAlpha做半透明叠加。注意多个 ColorMap 共享坐标轴时rescaleDataRange要分别调用否则会互相干扰。5.3 交互增强游标、缩放与数据导出QCustomPlot 自带缩放和拖拽但默认是鼠标滚轮缩放整个图。瀑布图通常希望锁定 y 轴时间轴只缩放 x 轴频率轴。可以在mouseWheel信号里过滤connect(m_plot, QCustomPlot::mouseWheel, this, [this](QWheelEvent* e) { // 只允许 x 轴缩放 double factor pow(0.85, e-angleDelta().y() / 120.0); m_plot-xAxis-scaleRange(factor, m_plot-xAxis-pixelToCoord(e-pos().x())); m_plot-replot(QCustomPlot::rpQueuedReplot); e-accept(); });游标用QCPItemStraightLine或QCPItemTracer实现跟随鼠标显示当前频率和强度。数据导出用m_colorMap-data()-savePng()或遍历cell写 CSV。如果要做历史回放把每帧数据存到QVectorQVectordouble里加个滑块控制读取位置就行。5.4 一个我踩过的坑颜色范围自动缩放的抖动早期版本我每帧都调rescaleDataRange(true)结果瀑布图整体颜色一直在闪弱信号时亮时暗。后来改成固定范围加手动调节或者用滑动平均平滑范围变化// 平滑颜色范围避免逐帧抖动 double newMax computeFrameMax(); m_smoothMax m_smoothMax * 0.95 newMax * 0.05; m_colorMap-setDataRange(QCPRange(0.0, m_smoothMax));0.95/0.05这个系数让范围变化滞后于数据视觉上稳定很多。从那以后我每次做实时颜色图都强制走一遍“范围平滑”这一步再也没被闪烁坑过。希望这个 Demo 的拆解能帮到你拿到源码后先跑通再按第 5 章的思路改成自己项目能用的样子。本文还有配套的精品资源点击获取