简介这是一套基于Qt5与QCustomPlot实现的实时波形绘制控件面向Qt初学者、嵌入式上位机开发者以及需要快速搭建实时曲线界面的研发人员。控件以WidgetPlot2D为核心封装了波形初始化与数据追加接口只需initGraphName()设置曲线名称、addData()送入数据即可完成实时绘制可有效降低实时波形显示功能的开发门槛。压缩包共15个文件以cpp、h源码文件为主包含qcustomplot核心库、WidgetPlot2D控件实现、UI界面文件、pro工程配置与png演示截图整体仅459KB轻量易用便于直接加入现有Qt工程。配套工程示例完整已覆盖从工程配置到绘图接口调用的全部代码下载后即可编译运行并二次扩展。目前已有9653人学习/下载适合初学者参照集成也适合开发者快速移植到自己的上位机项目中。1. 实时波形绘制别硬画Qt 配 QCustomPlot 这套方案先把坑绕开用 Qt 做实时波形绘制如果第一反应是拿起 QPainter 在 paintEvent 里硬画数据量一上来界面很快就会卡成幻灯片。QCustomPlot 把曲线、坐标轴、数据容器和重绘策略封装成可调用的组件你只需要把采样数据喂给 graph重绘、缩放、坐标换算都由它代劳。它非常适合示波器、传感器监测、音频频谱这类每秒刷新几十次甚至上百次的场景。这篇笔记把整套方案从编译接入到参数调优、踩坑排查完整过一遍附带的源码包可以直接编译跑起来适合想在 Qt 项目里快速接入实时曲线的人。2. 把 QCustomPlot 接进工程文件组织、基础绘制与第一条波形2.1 源码包的文件构成与 .pro 引入方式下载下来的资源包结构很标准核心只有 qcustomplot.h 和 qcustomplot.cpp 两个文件外加一个可直接编译的 mainwindow 示例工程。很多人在这一步就把整个目录拖进工程结果把示例代码也一起编了进来编译出一堆无关紧要的警告。我一般只拷贝这两个核心文件放到项目的 src/thirdparty/qcustomplot/ 目录下然后在 .pro 工程文件里做两行声明INCLUDEPATH $$PWD/src/thirdparty/qcustomplot SOURCES src/thirdparty/qcustomplot/qcustomplot.cpp HEADERS src/thirdparty/qcustomplot/qcustomplot.h这里有个细节qcustomplot.cpp 非常大有数万行代码如果直接加进主工程每次改动业务代码编译器都会顺带重编这个大文件拖慢整个开发节奏。我后来把它单独拆到一个静态库子工程里业务代码改一行这个大文件不会跟着重编。如果你用的是 MSVC还要把 C 标准切到 C14 以上我在 .pro 里固定加一行CONFIG c14引入之后最直接的验证方式不是跑示例而是在构造函数里直接创建一块画布画一条线。下面的代码是后续所有波形功能的基础// 构造函数中初始化绘图区 QCustomPlot *customPlot new QCustomPlot(this); setCentralWidget(customPlot); // 添加第一条曲线CH1蓝色实线 customPlot-addGraph(); customPlot-graph(0)-setName(CH1); customPlot-graph(0)-setPen(QPen(QColor(0, 120, 255), 1.5)); // 坐标轴配置横轴时间纵轴幅值 customPlot-xAxis-setLabel(t / s); customPlot-yAxis-setLabel(Amp); customPlot-xAxis-setRange(0, 10); customPlot-yAxis-setRange(-1.5, 1.5);这里的 addGraph() 会创建并注册一条 QCPGraph我习惯用 graph(0) 索引访问因为后续添加第二条曲线时graph(1) 的语义是一致的。setPen 里的 QColor 用 RGB 数值而不是样式表字符串是为了后面动态改色时不至于反复解析颜色名。setRange 只是给坐标轴一个初始视野等实时数据进来这个范围会被数据驱动反复调整。2.2 四个必须认识的类graph、axis、layout、plottable源码包里所有实时功能最终都落在这几类对象上先分清谁是数据、谁是壳后面调参才不至于懵。QCPGraph 是单条曲线。它内部维护两个有序向量分别存横坐标和纵坐标实时波形里的追加一帧数据本质就是往这两个向量的尾部 push_back。graph 负责把数据映射为屏幕坐标但它不管坐标轴怎么显示。QCPAxis 是坐标轴。默认有 xAxis 和 yAxis 两个轴每个轴可以独立设置范围、刻度步长、标签格式。多通道波形如果两路幅值差异很大可以添加第二个 y 轴绑定到同一块绘图区实现双纵轴显示。QCPLayout 负责画布内的布局。默认一个绘图区 rect 占满整个控件图例、标题、页眉都挂在 layout 体系里。新手容易忽略它一旦出现图例跑到画布外面的情况回来检查 layout 的 cell 数量就对了。QCPAbstractPlottable 是所有可绘制对象的基类折线 graph 只是其中一种。除折线外还有 QCPCurve、QCPStatisticalBox 等类型。实时波形场景用 graph 足够但如果你将来要叠加散点标注或误差带就得理解这个继承关系因为不同子类的数据传入接口签名不一样。2.3 从静态画点到定时器喂数据第一条会动的曲线先把静态图跑通。手动造 100 个点调用 replot 刷新QVectordouble x(100), y(100); for (int i 0; i 100; i) { x[i] i * 0.01; // 横轴 0 ~ 1 秒 y[i] qSin(2 * M_PI * 5 * x[i]); // 5Hz 正弦 } customPlot-graph(0)-setData(x, y); customPlot-replot(); // 手动触发一次重绘setData 内部会把传入的两个 vector 完整拷贝一份存到 graph 里。这说明实时场景中如果每帧都新建两个 QVector 再整体 setData每一帧都在发生大块内存分配这是后面性能问题的主要来源。正确做法是维护一个 buffer用 addData 逐点追加或者把一批新样本一次性 addData。// 定时器刷新界面事件循环空闲时合并重绘 QTimer *refreshTimer new QTimer(this); connect(refreshTimer, QTimer::timeout, []{ customPlot-replot(QCustomPlot::rpQueuedReplot); }); refreshTimer-start(33); // 约 30FPS这里有两个参数可以调刷新间隔 33ms 对应 30FPS趋势类界面已经够用再高只是白占 CPUrpQueuedReplot 是队列式重绘会把请求投递到事件循环如果上一次还没画完新的请求会被合并避免重绘风暴。对单次刷新时序有要求的地方比如用户点了一下按钮要看结果才用默认的 rpImmediateRefresh 即时刷新。提示rpQueuedReplot 是异步的画出来的是最近一次请求的结果rpImmediateRefresh 是同步的调用结束后图形一定已更新。实时波形用前者人机交互反馈用后者两者混用时要留意最后一次请求的优先级。2.4 坐标轴范围跟随让波形滚动而不是被拉伸新手最容易做错的是每次更新数据后把坐标轴范围设死导致波形从窗口左边冒出来越画越高或者纵轴被拉伸到看不清细节。正确的滚动做法是维护一个时间游标每次数据到来后把横轴窗口整体右移double currentTime 0; const double windowLen 10.0; // 显示窗口 10 秒 void onNewSample(double val, double dt) { currentTime dt; customPlot-graph(0)-addData(currentTime, val); // 窗口右边界跟随最新时间左边界左移一个窗口长度 customPlot-xAxis-setRange(currentTime - windowLen, currentTime); customPlot-yAxis-setRange(-1.5, 1.5); // 纵轴视野固定 if (sampleCount % 10 0) { customPlot-replot(QCustomPlot::rpQueuedReplot); } }这个回调里有三个参数值得调左边界 currentTime - windowLen 决定波形向左移动的速度y 轴范围固定还是自适应取决于信号幅度是否会突变重绘节流点数是每 10 个采样重绘一次还是每次来点都重绘实际采样率到 50kHz 时这个节流能挡掉大量无效重绘。addData 逐点追加会触发 QVector 扩容但它采用倍增策略平均摊下来开销可控。真正要避免的是在实时主循环里频繁做整体 setData。3. 实时刷新与性能调优让曲线刷到 30FPS 还不掉帧3.1 数据模型采集线程只写缓冲GUI 线程只读并重绘实时曲线上位机最常见的翻车是把采集和处理全部塞进 GUI 线程界面一卡就全卡。QCustomPlot 不是线程安全的所以正确模型是采集线程写环形缓冲GUI 定时器读走缓冲再重绘。我通常这样组织// 采集线程不碰任何 QCustomPlot 对象 void acquireLoop() { while (running) { double val readSensor(); // 读设备或计算出的一个样本 { QMutexLocker locker(dataMutex); dataBuffer.append(val); } QThread::msleep(1); // 模拟 1ms 采样间隔 } } // GUI 线程定时把缓冲同步到 graph 并刷新 QTimer *uiRefresh new QTimer(this); connect(uiRefresh, QTimer::timeout, this, [this]{ QMutexLocker locker(dataMutex); QVectordouble xs, ys; xs.reserve(dataBuffer.size()); ys.reserve(dataBuffer.size()); for (double v : dataBuffer) { ys.append(v); xs.append(currentTime); currentTime 0.001; } customPlot-graph(0)-addData(xs, ys); dataBuffer.clear(); // 窗口右边界随最新时间走 customPlot-xAxis-setRange(currentTime - windowLen, currentTime); customPlot-replot(QCustomPlot::rpQueuedReplot); }); uiRefresh-start(33);这段代码有几个设计决定采集线程从不调用 replot因为跨线程调用会破坏 graph 内部的数据结构轻则闪屏重则段错误数据用 dataBuffer 中转而不是直接加锁操作 graph 的容器把锁的粒度控制在纯数据层面避免和 QCustomPlot 内部状态混在一起刷新定时器用队列式重绘让 Qt 在事件循环空闲时合并多次重绘请求。如果你的采样率很高比如 100kHz每 33ms 往 buffer 里灌的数据量是几千个点。把它们全部搬到 graph 里再逐点重绘就不合算了此时应该在采集端做第一层减采样只保留界面窗口内需要的点。这里面有个隐蔽的小坑QVector::append 在扩容时会重新分配内存如果 GUI 线程正拿着锁遍历同一个 buffer就会发生数据竞争。绕法很简单提前 reserve 一个足够大的容量或者用固定大小的数组手写一个环形缓冲锁只保护读写指针的偏移。3.2 抗锯齿是性能分水岭实时模式默认全关QCustomPlot 默认对文本和线条都开抗锯齿静态图没问题实时刷新时 CPU 开销直接翻倍。我在实时模式下的第一件事是关掉整体的抗锯齿按需再开个别元素// 实时模式关闭抗锯齿 customPlot-setNotAntialiasedElements(QCP::aeAll); // 需要时仅保留文本抗锯齿 customPlot-setNotAntialiasedElements(QCP::aeGraph | QCP::aeLine);参数说明setNotAntialiasedElements 接收的是一组不需要抗锯齿的枚举位组合。QCP::aeAll 表示所有元素都不抗锯齿最省 CPU代价是横纵轴刻度数字边缘会稍显发虚QCP::aeGraph | QCP::aeLine 表示曲线和连线不去锯齿文本仍保留。实测在十万点波形上关闭图形抗锯齿能省下约 20ms 的重绘耗时是整体优化里收益最大的一处。另外一个开关容易忽略setNoAntialiasingOnDrag(true)。它让用户拖动或缩放坐标轴时临时禁用抗锯齿松手后恢复既保证操作流畅又不牺牲最终显示质量。如果你的界面里用户会频繁框选一段波形放大这个开关一定要打开。3.3 减采样的两个层次显示层跳点与存储层降频数据采集率 50kHz 时十秒钟就能积累五十万点。折线图如果逐点绘制每秒要处理的顶点数远超屏幕像素纯粹浪费。QCustomPlot 在显示层可以通过跳点来减采样const int kMaxVisiblePoints 2000; int step qMax(1, graph-dataCount() / kMaxVisiblePoints); QVectordouble visibleX, visibleY; visibleX.reserve(kMaxVisiblePoints); visibleY.reserve(kMaxVisiblePoints); for (int i 0; i graph-dataCount(); i step) { // 只取 step 间隔的样本进入绘制原始数据继续留在 graph 中 const QCPGraphData point graph-data()-at(i); visibleX.append(point.key); visibleY.append(point.value); } graph-setData(visibleX, visibleY, true); // alreadySortedtrue这里先把全量数据交给 graph 保存显示时按像素宽度等间隔抽点传入绘制层。alreadySorted true 告诉容器数据已按 key 升序排列省掉内部排序。要注意的是每帧构造 visibleX 和 visibleY 两个新 vector本身有内存开销所以这个方案适合需要保留全部历史但界面只看抽样的场景。如果采样率稳定且需求只是看最近 N 秒我一般会在采集线程里维护一个固定容量的环形缓冲只保留窗口内的样本越界部分直接丢弃这是存储层降频。两种策略不是互斥关系可以组合采集端降频省内存显示端跳点省绘制时间。3.4 缩放拖拽防卡顿给 rangeChanged 加一层防抖实时波形还有一个容易忽略的瓶颈用户用滚轮缩放坐标轴或拖拽波形时每次操作都会触发坐标轴重算和整块重绘。底层数据点多时拖动一次会连续触发几十次重绘明显掉帧。常见做法是给坐标轴范围变化信号做防抖connect(customPlot-xAxis, QCPAxis::rangeChanged, this, MainWidget::onAxisRangeChanged); void MainWidget::onAxisRangeChanged(const QCPRange range) { // 200ms 内的连续变更只响应最后一次 if (rangeRefreshTimer nullptr) { rangeRefreshTimer new QTimer(this); rangeRefreshTimer-setSingleShot(true); connect(rangeRefreshTimer, QTimer::timeout, [this]{ customPlot-replot(QCustomPlot::rpQueuedReplot); }); } rangeRefreshTimer-start(200); }rangeChanged 在拖动时高频发射200ms 的 singleShot 会不断重置计时直到用户停下才真正重绘。代价是拖拽过程中画面不跟着动松手后刷新换来的是 CPU 占用大幅下降。这个 200ms 是按趋势观察界面调的经验值做实时控制类界面时不建议用因为操作反馈延迟不可接受。想折中的话可以把 200ms 改成 50ms再配 setNoAntialiasingOnDrag(true)跟手度和流畅度都能兼顾。3.5 用 QElapsedTimer 量化帧耗时别凭感觉调参性能优化最忌讳感觉卡了就关抗锯齿。我习惯在主窗口的状态栏放一个 QLabel每次重绘完成后显示真实耗时connect(customPlot, QCustomPlot::replotted, this, [this]{ qint64 elapsed lastReplotTimer.nsecsElapsed(); statusLabel-setText(QString(replot: %1 ms).arg(elapsed / 1e6, 0, f, 2)); }); // 重绘开始前启动计时 lastReplotTimer.start(); customPlot-replot();注意一个容易误用的细节rpQueuedReplot 是异步队列如果在调用后面立刻读计时器得到的只是入队耗时。要拿到真实重绘耗时用默认的立即刷新模式测一遍或者干脆挂在 replotted 信号上。我还犯过的错误是拿 Debug 版去测耗时Debug 下的 STL 边界检查和断言会让耗时翻倍调出来的参数完全不可用。所以性能对比一定要在 Release 下做否则会为一个只存在于 Debug 里的瓶颈去改业务代码。4. 避坑排查实时波形最容易翻车的五个问题先说明下面这些问题不是从文档里看的是我在几个实际项目里被坑过之后逐条记下来的按出现概率排了序。4.1 线程问题采集线程直接 replot 导致不定时崩溃现象程序启动后界面正常运行几十秒到几分钟开始随机崩溃。崩溃栈每次都不一样有时停在 Qt 的事件分发循环里有时停在 vector 的拷贝构造函数里错误位置毫无规律。重启后又能跑一阵这种间歇性崩溃最让人头疼。原因QCustomPlot 不是线程安全的。采集线程一边调用 replot 修改内部绘制状态另一边 GUI 线程正在重绘同一块画布两个线程同时访问数据就触发了未定义行为。崩溃不会立刻出现而是某一次恰好赶在数据搬移和绘制交错的瞬间才暴露。解决强制统一线程模型。采集线程只往自己的缓冲区写数据界面线程用 QTimer 读缓冲并重绘。确实需要在采集线程里立刻触发刷新时用 QMetaObject::invokeMethod(this, onDataReady, Qt::QueuedConnection) 投递到 GUI 线程由 GUI 线程去碰控件。从那以后我写的采集线程代码里再没出现过一次直接调用控件的方法。4.2 纵轴乱跳自动适配范围把波形拉成心电图现象波形能看到但纵轴范围一直在变有时显示 -0.01 到 0.01有时变成 -1500 到 1500。画面里的曲线被拉伸得跟心电图一样原始幅值细节完全丢失。原因调用了 rescaleAxes()让坐标轴每次按全量数据的最大最小值自动匹配范围。实时数据里一旦冒出一个毛刺或者直流漂移尖峰纵轴就被这个尖峰带飞后面的数据全被压成一条直线。解决实时模式下不要用 rescaleAxes() 做自动适配。y 轴要么设成固定范围要么做当前窗口内样本的最大最小值统计只随窗口内的极值更新同时给统计结果加一个钳位防止单点毛刺瞬间拉宽范围。信号幅度稳定时固定 y 轴范围最省心。4.3 曲线有锯齿源数据是平滑的画出来却带阶梯现象同一组数据用脚本画出来是平滑正弦进入 QCustomPlot 后曲线出现明显阶梯或毛刺而且有时候在时间轴上疏密不均。原因x 轴时间戳生成方式不对。用浮点累加 timer.elapsed()或者每帧写一句 currentTime 0.001都会累积浮点误差横坐标上的点间距变得忽大忽小折线自然带上码步。解决改用整数采样计数乘固定周期来生成时间戳误差不累积double ts sampleIndex * samplePeriod; sampleIndex;这样 x 值严格等间距锯齿问题肉眼可见地消失。如果一定要用墙钟时间也请用一个单调递增的时钟源别在循环里做浮点自加。4.4 内存涨不停setData 反复分配是元凶现象程序开一晚上内存从 200MB 涨到接近 1GB曲线刷新也跟着变慢操作开始粘滞。原因每帧都新建两个 QVector 然后整体 setDatagraph 内部会再拷贝一份瞬时内存压力翻倍旧的 QVector 被释放后留下大量碎片。还有的地方频繁用 graph-data()-at(i) 取值做临时对象分配和回收非常频繁。解决高频刷新路径改用 addData 增量追加历史只需要窗口内数据时用固定容量环形缓冲最后给容器开自动压缩。graph-data()-setAutoSqueeze(true) 让容器在数据删减后自动收缩容量避免 vector 只长不缩。4.5 副屏冻结波形在扩展屏上不刷新现象程序在扩展副屏上运行时波形像冻住一样不动鼠标切到主屏窗口上晃一下又恢复一小帧。原因多出现在 Qt 开了 OpenGL 合成、显卡驱动又老的环境里。副屏的缓冲区同步和主屏不一致导致 QOpenGLWidget 和依赖 QSurfaceFormat OpenGL 设置的控件在副屏上重绘被阻塞。QCustomPlot 本身是软绘制但只要工程里强制指定了 OpenGL 格式它的绘制路径也可能被带进这个状态。解决不要在 main 函数里为 QSurfaceFormat 强制设置 OpenGL 版本如果其他模块确实要硬件加速把 QCustomPlot 放在不继承那个 GL 上下文的独立窗口里。这个问题本质上和环境有关排查时先怀疑驱动再怀疑代码别一上来就改重绘逻辑。5. 进阶多通道波形、局部放大与数据落盘5.1 多通道独立的纵轴与图例一块画布上显示多路信号直接 addGraph 添加第二条即可但要注意两路幅度差异。第二路信号如果和第一路差一个量级共用 y 轴时小的那路看起来就是一条直线所以独立 y 轴是必需项。我给第二路单独配一个 y 轴customPlot-addGraph(customPlot-xAxis, customPlot-yAxis2); customPlot-yAxis2-setVisible(true); customPlot-yAxis2-setRange(-5, 5);yAxis2 默认隐藏要 setVisible(true)。两路共用 x 轴没问题但 y 轴如果幅度差异大共用会让其中一路被压扁。再打开图例按通道名区分视觉上会清爽很多customPlot-legend-setVisible(true); customPlot-graph(0)-setName(CH1); customPlot-graph(1)-setName(CH2);5.2 局部放大与光标读数需要仔细看某段波形时可以直接用鼠标滚轮缩放 x 轴或者按住左键拖选矩形区域放大这是 QCustomPlot 内置的交互不需要额外写代码。如果你觉得默认的滚轮方向反了可以在 QCustomPlot 子类里重写 wheelEvent 调整缩放方向。做光标读数时在 mouseMove 事件里做像素到数据的坐标映射double x customPlot-xAxis-pixelToCoord(event-pos().x()); double y customPlot-yAxis-pixelToCoord(event-pos().y());再用 QCPItemTracer 在曲线上挂一个跟随光标的小圆圈显示当前坐标值。这个功能对示波器类上位机很有用实现成本也不高。5.3 数据落盘导出 CSV 的注意事项最后说一个常用功能把波形导出成 CSV方便到别的工具里分析。导出时别临时造 vector直接从 graph 的原始数据容器里遍历QFile f(wave.csv); if (f.open(QIODevice::WriteOnly)) { QTextStream out(f); for (int i 0; i graph-dataCount(); i) { const QCPGraphData d graph-data()-at(i); out d.key , d.value \n; } }dataCount 很大时这个循环会卡界面建议放到后台线程或者只导出最近窗口内的数据再加工进度提示。我自己现在接 QCustomPlot 的新项目开头必做四步检查线程模型、抗锯齿开关、跳点步长、Release 实测耗时没跑完这四步之前不碰界面美化。这份源码包里的示例工程基本按这个顺序组织的如果你正为实时曲线的卡顿和崩溃发愁下载后直接改参数就能复现出第一版可用的波形界面。希望帮到你。本文还有配套的精品资源点击获取
简介这是一套基于Qt5与QCustomPlot实现的实时波形绘制控件面向Qt初学者、嵌入式上位机开发者以及需要快速搭建实时曲线界面的研发人员。控件以WidgetPlot2D为核心封装了波形初始化与数据追加接口只需initGraphName()设置曲线名称、addData()送入数据即可完成实时绘制可有效降低实时波形显示功能的开发门槛。压缩包共15个文件以cpp、h源码文件为主包含qcustomplot核心库、WidgetPlot2D控件实现、UI界面文件、pro工程配置与png演示截图整体仅459KB轻量易用便于直接加入现有Qt工程。配套工程示例完整已覆盖从工程配置到绘图接口调用的全部代码下载后即可编译运行并二次扩展。目前已有9653人学习/下载适合初学者参照集成也适合开发者快速移植到自己的上位机项目中。1. 实时波形绘制别硬画Qt 配 QCustomPlot 这套方案先把坑绕开用 Qt 做实时波形绘制如果第一反应是拿起 QPainter 在 paintEvent 里硬画数据量一上来界面很快就会卡成幻灯片。QCustomPlot 把曲线、坐标轴、数据容器和重绘策略封装成可调用的组件你只需要把采样数据喂给 graph重绘、缩放、坐标换算都由它代劳。它非常适合示波器、传感器监测、音频频谱这类每秒刷新几十次甚至上百次的场景。这篇笔记把整套方案从编译接入到参数调优、踩坑排查完整过一遍附带的源码包可以直接编译跑起来适合想在 Qt 项目里快速接入实时曲线的人。2. 把 QCustomPlot 接进工程文件组织、基础绘制与第一条波形2.1 源码包的文件构成与 .pro 引入方式下载下来的资源包结构很标准核心只有 qcustomplot.h 和 qcustomplot.cpp 两个文件外加一个可直接编译的 mainwindow 示例工程。很多人在这一步就把整个目录拖进工程结果把示例代码也一起编了进来编译出一堆无关紧要的警告。我一般只拷贝这两个核心文件放到项目的 src/thirdparty/qcustomplot/ 目录下然后在 .pro 工程文件里做两行声明INCLUDEPATH $$PWD/src/thirdparty/qcustomplot SOURCES src/thirdparty/qcustomplot/qcustomplot.cpp HEADERS src/thirdparty/qcustomplot/qcustomplot.h这里有个细节qcustomplot.cpp 非常大有数万行代码如果直接加进主工程每次改动业务代码编译器都会顺带重编这个大文件拖慢整个开发节奏。我后来把它单独拆到一个静态库子工程里业务代码改一行这个大文件不会跟着重编。如果你用的是 MSVC还要把 C 标准切到 C14 以上我在 .pro 里固定加一行CONFIG c14引入之后最直接的验证方式不是跑示例而是在构造函数里直接创建一块画布画一条线。下面的代码是后续所有波形功能的基础// 构造函数中初始化绘图区 QCustomPlot *customPlot new QCustomPlot(this); setCentralWidget(customPlot); // 添加第一条曲线CH1蓝色实线 customPlot-addGraph(); customPlot-graph(0)-setName(CH1); customPlot-graph(0)-setPen(QPen(QColor(0, 120, 255), 1.5)); // 坐标轴配置横轴时间纵轴幅值 customPlot-xAxis-setLabel(t / s); customPlot-yAxis-setLabel(Amp); customPlot-xAxis-setRange(0, 10); customPlot-yAxis-setRange(-1.5, 1.5);这里的 addGraph() 会创建并注册一条 QCPGraph我习惯用 graph(0) 索引访问因为后续添加第二条曲线时graph(1) 的语义是一致的。setPen 里的 QColor 用 RGB 数值而不是样式表字符串是为了后面动态改色时不至于反复解析颜色名。setRange 只是给坐标轴一个初始视野等实时数据进来这个范围会被数据驱动反复调整。2.2 四个必须认识的类graph、axis、layout、plottable源码包里所有实时功能最终都落在这几类对象上先分清谁是数据、谁是壳后面调参才不至于懵。QCPGraph 是单条曲线。它内部维护两个有序向量分别存横坐标和纵坐标实时波形里的追加一帧数据本质就是往这两个向量的尾部 push_back。graph 负责把数据映射为屏幕坐标但它不管坐标轴怎么显示。QCPAxis 是坐标轴。默认有 xAxis 和 yAxis 两个轴每个轴可以独立设置范围、刻度步长、标签格式。多通道波形如果两路幅值差异很大可以添加第二个 y 轴绑定到同一块绘图区实现双纵轴显示。QCPLayout 负责画布内的布局。默认一个绘图区 rect 占满整个控件图例、标题、页眉都挂在 layout 体系里。新手容易忽略它一旦出现图例跑到画布外面的情况回来检查 layout 的 cell 数量就对了。QCPAbstractPlottable 是所有可绘制对象的基类折线 graph 只是其中一种。除折线外还有 QCPCurve、QCPStatisticalBox 等类型。实时波形场景用 graph 足够但如果你将来要叠加散点标注或误差带就得理解这个继承关系因为不同子类的数据传入接口签名不一样。2.3 从静态画点到定时器喂数据第一条会动的曲线先把静态图跑通。手动造 100 个点调用 replot 刷新QVectordouble x(100), y(100); for (int i 0; i 100; i) { x[i] i * 0.01; // 横轴 0 ~ 1 秒 y[i] qSin(2 * M_PI * 5 * x[i]); // 5Hz 正弦 } customPlot-graph(0)-setData(x, y); customPlot-replot(); // 手动触发一次重绘setData 内部会把传入的两个 vector 完整拷贝一份存到 graph 里。这说明实时场景中如果每帧都新建两个 QVector 再整体 setData每一帧都在发生大块内存分配这是后面性能问题的主要来源。正确做法是维护一个 buffer用 addData 逐点追加或者把一批新样本一次性 addData。// 定时器刷新界面事件循环空闲时合并重绘 QTimer *refreshTimer new QTimer(this); connect(refreshTimer, QTimer::timeout, []{ customPlot-replot(QCustomPlot::rpQueuedReplot); }); refreshTimer-start(33); // 约 30FPS这里有两个参数可以调刷新间隔 33ms 对应 30FPS趋势类界面已经够用再高只是白占 CPUrpQueuedReplot 是队列式重绘会把请求投递到事件循环如果上一次还没画完新的请求会被合并避免重绘风暴。对单次刷新时序有要求的地方比如用户点了一下按钮要看结果才用默认的 rpImmediateRefresh 即时刷新。提示rpQueuedReplot 是异步的画出来的是最近一次请求的结果rpImmediateRefresh 是同步的调用结束后图形一定已更新。实时波形用前者人机交互反馈用后者两者混用时要留意最后一次请求的优先级。2.4 坐标轴范围跟随让波形滚动而不是被拉伸新手最容易做错的是每次更新数据后把坐标轴范围设死导致波形从窗口左边冒出来越画越高或者纵轴被拉伸到看不清细节。正确的滚动做法是维护一个时间游标每次数据到来后把横轴窗口整体右移double currentTime 0; const double windowLen 10.0; // 显示窗口 10 秒 void onNewSample(double val, double dt) { currentTime dt; customPlot-graph(0)-addData(currentTime, val); // 窗口右边界跟随最新时间左边界左移一个窗口长度 customPlot-xAxis-setRange(currentTime - windowLen, currentTime); customPlot-yAxis-setRange(-1.5, 1.5); // 纵轴视野固定 if (sampleCount % 10 0) { customPlot-replot(QCustomPlot::rpQueuedReplot); } }这个回调里有三个参数值得调左边界 currentTime - windowLen 决定波形向左移动的速度y 轴范围固定还是自适应取决于信号幅度是否会突变重绘节流点数是每 10 个采样重绘一次还是每次来点都重绘实际采样率到 50kHz 时这个节流能挡掉大量无效重绘。addData 逐点追加会触发 QVector 扩容但它采用倍增策略平均摊下来开销可控。真正要避免的是在实时主循环里频繁做整体 setData。3. 实时刷新与性能调优让曲线刷到 30FPS 还不掉帧3.1 数据模型采集线程只写缓冲GUI 线程只读并重绘实时曲线上位机最常见的翻车是把采集和处理全部塞进 GUI 线程界面一卡就全卡。QCustomPlot 不是线程安全的所以正确模型是采集线程写环形缓冲GUI 定时器读走缓冲再重绘。我通常这样组织// 采集线程不碰任何 QCustomPlot 对象 void acquireLoop() { while (running) { double val readSensor(); // 读设备或计算出的一个样本 { QMutexLocker locker(dataMutex); dataBuffer.append(val); } QThread::msleep(1); // 模拟 1ms 采样间隔 } } // GUI 线程定时把缓冲同步到 graph 并刷新 QTimer *uiRefresh new QTimer(this); connect(uiRefresh, QTimer::timeout, this, [this]{ QMutexLocker locker(dataMutex); QVectordouble xs, ys; xs.reserve(dataBuffer.size()); ys.reserve(dataBuffer.size()); for (double v : dataBuffer) { ys.append(v); xs.append(currentTime); currentTime 0.001; } customPlot-graph(0)-addData(xs, ys); dataBuffer.clear(); // 窗口右边界随最新时间走 customPlot-xAxis-setRange(currentTime - windowLen, currentTime); customPlot-replot(QCustomPlot::rpQueuedReplot); }); uiRefresh-start(33);这段代码有几个设计决定采集线程从不调用 replot因为跨线程调用会破坏 graph 内部的数据结构轻则闪屏重则段错误数据用 dataBuffer 中转而不是直接加锁操作 graph 的容器把锁的粒度控制在纯数据层面避免和 QCustomPlot 内部状态混在一起刷新定时器用队列式重绘让 Qt 在事件循环空闲时合并多次重绘请求。如果你的采样率很高比如 100kHz每 33ms 往 buffer 里灌的数据量是几千个点。把它们全部搬到 graph 里再逐点重绘就不合算了此时应该在采集端做第一层减采样只保留界面窗口内需要的点。这里面有个隐蔽的小坑QVector::append 在扩容时会重新分配内存如果 GUI 线程正拿着锁遍历同一个 buffer就会发生数据竞争。绕法很简单提前 reserve 一个足够大的容量或者用固定大小的数组手写一个环形缓冲锁只保护读写指针的偏移。3.2 抗锯齿是性能分水岭实时模式默认全关QCustomPlot 默认对文本和线条都开抗锯齿静态图没问题实时刷新时 CPU 开销直接翻倍。我在实时模式下的第一件事是关掉整体的抗锯齿按需再开个别元素// 实时模式关闭抗锯齿 customPlot-setNotAntialiasedElements(QCP::aeAll); // 需要时仅保留文本抗锯齿 customPlot-setNotAntialiasedElements(QCP::aeGraph | QCP::aeLine);参数说明setNotAntialiasedElements 接收的是一组不需要抗锯齿的枚举位组合。QCP::aeAll 表示所有元素都不抗锯齿最省 CPU代价是横纵轴刻度数字边缘会稍显发虚QCP::aeGraph | QCP::aeLine 表示曲线和连线不去锯齿文本仍保留。实测在十万点波形上关闭图形抗锯齿能省下约 20ms 的重绘耗时是整体优化里收益最大的一处。另外一个开关容易忽略setNoAntialiasingOnDrag(true)。它让用户拖动或缩放坐标轴时临时禁用抗锯齿松手后恢复既保证操作流畅又不牺牲最终显示质量。如果你的界面里用户会频繁框选一段波形放大这个开关一定要打开。3.3 减采样的两个层次显示层跳点与存储层降频数据采集率 50kHz 时十秒钟就能积累五十万点。折线图如果逐点绘制每秒要处理的顶点数远超屏幕像素纯粹浪费。QCustomPlot 在显示层可以通过跳点来减采样const int kMaxVisiblePoints 2000; int step qMax(1, graph-dataCount() / kMaxVisiblePoints); QVectordouble visibleX, visibleY; visibleX.reserve(kMaxVisiblePoints); visibleY.reserve(kMaxVisiblePoints); for (int i 0; i graph-dataCount(); i step) { // 只取 step 间隔的样本进入绘制原始数据继续留在 graph 中 const QCPGraphData point graph-data()-at(i); visibleX.append(point.key); visibleY.append(point.value); } graph-setData(visibleX, visibleY, true); // alreadySortedtrue这里先把全量数据交给 graph 保存显示时按像素宽度等间隔抽点传入绘制层。alreadySorted true 告诉容器数据已按 key 升序排列省掉内部排序。要注意的是每帧构造 visibleX 和 visibleY 两个新 vector本身有内存开销所以这个方案适合需要保留全部历史但界面只看抽样的场景。如果采样率稳定且需求只是看最近 N 秒我一般会在采集线程里维护一个固定容量的环形缓冲只保留窗口内的样本越界部分直接丢弃这是存储层降频。两种策略不是互斥关系可以组合采集端降频省内存显示端跳点省绘制时间。3.4 缩放拖拽防卡顿给 rangeChanged 加一层防抖实时波形还有一个容易忽略的瓶颈用户用滚轮缩放坐标轴或拖拽波形时每次操作都会触发坐标轴重算和整块重绘。底层数据点多时拖动一次会连续触发几十次重绘明显掉帧。常见做法是给坐标轴范围变化信号做防抖connect(customPlot-xAxis, QCPAxis::rangeChanged, this, MainWidget::onAxisRangeChanged); void MainWidget::onAxisRangeChanged(const QCPRange range) { // 200ms 内的连续变更只响应最后一次 if (rangeRefreshTimer nullptr) { rangeRefreshTimer new QTimer(this); rangeRefreshTimer-setSingleShot(true); connect(rangeRefreshTimer, QTimer::timeout, [this]{ customPlot-replot(QCustomPlot::rpQueuedReplot); }); } rangeRefreshTimer-start(200); }rangeChanged 在拖动时高频发射200ms 的 singleShot 会不断重置计时直到用户停下才真正重绘。代价是拖拽过程中画面不跟着动松手后刷新换来的是 CPU 占用大幅下降。这个 200ms 是按趋势观察界面调的经验值做实时控制类界面时不建议用因为操作反馈延迟不可接受。想折中的话可以把 200ms 改成 50ms再配 setNoAntialiasingOnDrag(true)跟手度和流畅度都能兼顾。3.5 用 QElapsedTimer 量化帧耗时别凭感觉调参性能优化最忌讳感觉卡了就关抗锯齿。我习惯在主窗口的状态栏放一个 QLabel每次重绘完成后显示真实耗时connect(customPlot, QCustomPlot::replotted, this, [this]{ qint64 elapsed lastReplotTimer.nsecsElapsed(); statusLabel-setText(QString(replot: %1 ms).arg(elapsed / 1e6, 0, f, 2)); }); // 重绘开始前启动计时 lastReplotTimer.start(); customPlot-replot();注意一个容易误用的细节rpQueuedReplot 是异步队列如果在调用后面立刻读计时器得到的只是入队耗时。要拿到真实重绘耗时用默认的立即刷新模式测一遍或者干脆挂在 replotted 信号上。我还犯过的错误是拿 Debug 版去测耗时Debug 下的 STL 边界检查和断言会让耗时翻倍调出来的参数完全不可用。所以性能对比一定要在 Release 下做否则会为一个只存在于 Debug 里的瓶颈去改业务代码。4. 避坑排查实时波形最容易翻车的五个问题先说明下面这些问题不是从文档里看的是我在几个实际项目里被坑过之后逐条记下来的按出现概率排了序。4.1 线程问题采集线程直接 replot 导致不定时崩溃现象程序启动后界面正常运行几十秒到几分钟开始随机崩溃。崩溃栈每次都不一样有时停在 Qt 的事件分发循环里有时停在 vector 的拷贝构造函数里错误位置毫无规律。重启后又能跑一阵这种间歇性崩溃最让人头疼。原因QCustomPlot 不是线程安全的。采集线程一边调用 replot 修改内部绘制状态另一边 GUI 线程正在重绘同一块画布两个线程同时访问数据就触发了未定义行为。崩溃不会立刻出现而是某一次恰好赶在数据搬移和绘制交错的瞬间才暴露。解决强制统一线程模型。采集线程只往自己的缓冲区写数据界面线程用 QTimer 读缓冲并重绘。确实需要在采集线程里立刻触发刷新时用 QMetaObject::invokeMethod(this, onDataReady, Qt::QueuedConnection) 投递到 GUI 线程由 GUI 线程去碰控件。从那以后我写的采集线程代码里再没出现过一次直接调用控件的方法。4.2 纵轴乱跳自动适配范围把波形拉成心电图现象波形能看到但纵轴范围一直在变有时显示 -0.01 到 0.01有时变成 -1500 到 1500。画面里的曲线被拉伸得跟心电图一样原始幅值细节完全丢失。原因调用了 rescaleAxes()让坐标轴每次按全量数据的最大最小值自动匹配范围。实时数据里一旦冒出一个毛刺或者直流漂移尖峰纵轴就被这个尖峰带飞后面的数据全被压成一条直线。解决实时模式下不要用 rescaleAxes() 做自动适配。y 轴要么设成固定范围要么做当前窗口内样本的最大最小值统计只随窗口内的极值更新同时给统计结果加一个钳位防止单点毛刺瞬间拉宽范围。信号幅度稳定时固定 y 轴范围最省心。4.3 曲线有锯齿源数据是平滑的画出来却带阶梯现象同一组数据用脚本画出来是平滑正弦进入 QCustomPlot 后曲线出现明显阶梯或毛刺而且有时候在时间轴上疏密不均。原因x 轴时间戳生成方式不对。用浮点累加 timer.elapsed()或者每帧写一句 currentTime 0.001都会累积浮点误差横坐标上的点间距变得忽大忽小折线自然带上码步。解决改用整数采样计数乘固定周期来生成时间戳误差不累积double ts sampleIndex * samplePeriod; sampleIndex;这样 x 值严格等间距锯齿问题肉眼可见地消失。如果一定要用墙钟时间也请用一个单调递增的时钟源别在循环里做浮点自加。4.4 内存涨不停setData 反复分配是元凶现象程序开一晚上内存从 200MB 涨到接近 1GB曲线刷新也跟着变慢操作开始粘滞。原因每帧都新建两个 QVector 然后整体 setDatagraph 内部会再拷贝一份瞬时内存压力翻倍旧的 QVector 被释放后留下大量碎片。还有的地方频繁用 graph-data()-at(i) 取值做临时对象分配和回收非常频繁。解决高频刷新路径改用 addData 增量追加历史只需要窗口内数据时用固定容量环形缓冲最后给容器开自动压缩。graph-data()-setAutoSqueeze(true) 让容器在数据删减后自动收缩容量避免 vector 只长不缩。4.5 副屏冻结波形在扩展屏上不刷新现象程序在扩展副屏上运行时波形像冻住一样不动鼠标切到主屏窗口上晃一下又恢复一小帧。原因多出现在 Qt 开了 OpenGL 合成、显卡驱动又老的环境里。副屏的缓冲区同步和主屏不一致导致 QOpenGLWidget 和依赖 QSurfaceFormat OpenGL 设置的控件在副屏上重绘被阻塞。QCustomPlot 本身是软绘制但只要工程里强制指定了 OpenGL 格式它的绘制路径也可能被带进这个状态。解决不要在 main 函数里为 QSurfaceFormat 强制设置 OpenGL 版本如果其他模块确实要硬件加速把 QCustomPlot 放在不继承那个 GL 上下文的独立窗口里。这个问题本质上和环境有关排查时先怀疑驱动再怀疑代码别一上来就改重绘逻辑。5. 进阶多通道波形、局部放大与数据落盘5.1 多通道独立的纵轴与图例一块画布上显示多路信号直接 addGraph 添加第二条即可但要注意两路幅度差异。第二路信号如果和第一路差一个量级共用 y 轴时小的那路看起来就是一条直线所以独立 y 轴是必需项。我给第二路单独配一个 y 轴customPlot-addGraph(customPlot-xAxis, customPlot-yAxis2); customPlot-yAxis2-setVisible(true); customPlot-yAxis2-setRange(-5, 5);yAxis2 默认隐藏要 setVisible(true)。两路共用 x 轴没问题但 y 轴如果幅度差异大共用会让其中一路被压扁。再打开图例按通道名区分视觉上会清爽很多customPlot-legend-setVisible(true); customPlot-graph(0)-setName(CH1); customPlot-graph(1)-setName(CH2);5.2 局部放大与光标读数需要仔细看某段波形时可以直接用鼠标滚轮缩放 x 轴或者按住左键拖选矩形区域放大这是 QCustomPlot 内置的交互不需要额外写代码。如果你觉得默认的滚轮方向反了可以在 QCustomPlot 子类里重写 wheelEvent 调整缩放方向。做光标读数时在 mouseMove 事件里做像素到数据的坐标映射double x customPlot-xAxis-pixelToCoord(event-pos().x()); double y customPlot-yAxis-pixelToCoord(event-pos().y());再用 QCPItemTracer 在曲线上挂一个跟随光标的小圆圈显示当前坐标值。这个功能对示波器类上位机很有用实现成本也不高。5.3 数据落盘导出 CSV 的注意事项最后说一个常用功能把波形导出成 CSV方便到别的工具里分析。导出时别临时造 vector直接从 graph 的原始数据容器里遍历QFile f(wave.csv); if (f.open(QIODevice::WriteOnly)) { QTextStream out(f); for (int i 0; i graph-dataCount(); i) { const QCPGraphData d graph-data()-at(i); out d.key , d.value \n; } }dataCount 很大时这个循环会卡界面建议放到后台线程或者只导出最近窗口内的数据再加工进度提示。我自己现在接 QCustomPlot 的新项目开头必做四步检查线程模型、抗锯齿开关、跳点步长、Release 实测耗时没跑完这四步之前不碰界面美化。这份源码包里的示例工程基本按这个顺序组织的如果你正为实时曲线的卡顿和崩溃发愁下载后直接改参数就能复现出第一版可用的波形界面。希望帮到你。本文还有配套的精品资源点击获取
平方复杂度无法被常规优化消除｜TaoToken 统一 Key 通道实测)
