简介Qt与QCustomPlot结合的实时波形绘制控件专为需要快速搭建上位机或实时数据可视化界面的Qt初学者与研发人员而设计解决从零绘制实时曲线难度大、封装复杂、上手成本高的问题。控件以WidgetPlot2D形式封装支持自定义多条波形名称调用简单的addData接口即可持续追加数据并实时刷新交互流畅适用于仪器仪表、数据采集、传感器监测等多类场景。资源包共15个文件以cpp、h源码为核心辅以ui界面文件、png图标、qrc资源配置及pro工程文件整体体积仅459KB结构紧凑方便直接并入现有Qt项目工程基于QCustomPlot二次封装已处理好依赖与pro配置下载后即可编译体验。当前已有9637人浏览学习实用性与认可度可见一斑。压缩包内提供完整可运行工程、演示界面与配套资源文件既可作为QCustomPlot绘图的学习范例也能作为实时波形显示模块的快速启动模板支撑后续功能扩展与二次开发。 做采集类上位机的人应该都有这种体验波形数据从串口或者网口源源不断进来可界面上那条曲线就是跟不上拖一下窗口就开始转圈CPU风扇跟着狂转。我之前接过一个项目一开始用QChart做实时波形数据点一上万CPU占用直接飙到30%以上后来换成QCustomPlot同样量级的数据量占用降下去一大截曲线跟得上采集速度了界面也灵了。这篇文章不聊虚的我把用Qt QCustomPlot做实时波形绘制、实时曲线绘制的完整流程理一遍从最基础的曲线搭起来到性能调优、时域转频域做实时频谱最后再讲讲部署阶段一定会踩的坑。如果你正在做数据采集上位机、示波器类工具、频谱分析界面或者刚入门Qt想找一个靠谱的绘图方案这篇应该能帮你少走不少弯路。1. 为什么是QCustomPlot实时波形场景的选型逻辑1.1 三个候选方案横向对比很多新手上来第一句话就问QCustomPlot、QChart和自绘到底选哪个这个问题没有标准答案但放到实时波形这个场景下答案其实非常明确。我做了个简单的对比表方案上手难度实时性能扩展能力适合场景QChartQt Charts低中动态数据更新开销偏大面向统计图表做仪表盘顺手静态图表、报表、简单动态曲线自定义paintEvent高坐标轴/缩放/滚动都要自己写取决于实现深度完全自主可做任何效果特殊渲染需求比如大规模点阵、热力图QCustomPlot低单文件库高专门为科学绘图设计波形、频谱、柱状、散点全支持数据采集上位机、示波器、频谱分析QChart是官方模块API设计偏向演示型图表QLineSeries在动态增删点时内部要维护大量信号连接点数过万以后明显吃力。自绘自由度最高但一个能滚动的坐标轴、带缩放的窗口、自动刻度的网格写起来少说几百行测试周期也长。QCustomPlot的定位就是科学绘图和实时曲线一个QCPGraph就能管理一条完整的数据序列滚动窗口、坐标缩放、网格、图例都是现成的这才是它能在这个场景胜出的根本原因。1.2 QCustomPlot为什么适合实时刷新QCustomPlot高效的关键在于它的数据组织方式。每条曲线QCPGraph内部的数据是QVectorQCPGraphDataQCPGraphData就是一对double一个key一个value连续内存存储。追加数据的时候如果key是单调递增的直接往Vector尾部塞摊销复杂度是O(1)绘制时默认开启的setAdaptiveSampling(true)会在数据点数远大于实际像素宽度时自动抽稀也就是说绘制耗时主要跟控件像素宽度相关而不是跟数据总量完全线性增长。这两个底层机制叠加起来让它天生适合流式数据的实时刷新。还有一个很多人没注意到的点QCustomPlot是QWidget本身自带双缓冲重绘时不会出现闪烁。你把窗口拖来拖去、放大缩小它的坐标轴和曲线会跟着一起重绘但不会像自绘方案那样频繁闪。实际项目中省掉的这些擦屁股工作比多出来的那一点点库性能更值钱。1.3 一个常被忽略的授权问题用QCustomPlot不用花钱但也不是完全没有约束。它的许可证是GPLv3同时也提供商业授权。如果你是做内部工具、学习项目、开源项目直接拿来用没问题但如果你做的是闭源商业软件要么把相关部分按照GPLv3开源要么花钱买商业授权。这个决定最好在项目启动时就做好别等产品做完了、代码写了几万行再被法务或用户提醒才去处理那会非常被动。2. 最小可用的实时曲线核心接口与代码骨架2.1 画布、坐标轴和一条曲线QCustomPlot用起来比想象中还简单。一个QCustomPlot控件放到界面上加一条曲线设置坐标轴范围就完成了80%的工作// 假设界面上已经放置了一个 QCustomPlot* plot plot-addGraph(); plot-graph(0)-setPen(QPen(QColor(0, 170, 255), 2)); plot-xAxis-setLabel(time (s)); plot-yAxis-setLabel(value); plot-xAxis-setRange(-5, 0); // 默认显示最近5秒 plot-yAxis-setRange(-1.2, 1.2); plot-xAxis-grid()-setSubGridVisible(true); plot-yAxis-grid()-setSubGridVisible(true);这段代码里addGraph()会创建一条默认曲线graph(0)是它的索引。setPen设置曲线颜色和线宽这里我习惯把所有网格、坐标轴颜色调成偏暗的灰色曲线用亮色这样长时间盯着屏幕不会太累。如果你做的是散点图也就是热搜里经常有人问的QCustomPlot画xy散点图只需要把线型关掉、加上散点样式plot-graph(0)-setLineStyle(QCPGraph::lsNone); plot-graph(0)-setScatterStyle(QCPScatterStyle(QCPScatterStyle::ssCircle, 4));关键思路是QCustomPlot里的曲线就是数据点 绘制样式的组合你要线就画线要点就画点线点都要也行。2.2 addData 与 replaceData两种数据追加方式的取舍实时波形最核心的操作是往曲线里追加数据。QCustomPlot提供两种常见方式用错的后果很不一样。addData(key, value)适合流式追加来一个点加一个点key通常是时间戳或者采样序号。还有一种重载addData(QVectordouble keys, QVectordouble values)支持批量追加一次塞入一整批点比循环单个addData快不少。replaceData(keys, values)则是整体替换它会把曲线原来的所有数据清掉再设置新数据适合整帧刷新的场景比如从一个网络缓冲区里一次性解析出一整段波形。一个必须注意的坑addData的key必须尽量保持递增。QCustomPlot内部在追加新点时如果发现key比最后一个key小它会去寻找合适的位置插入这个操作是O(n)的。如果你在实时数据里偶尔丢包、乱序导致key回退性能会肉眼可见地劣化。所以能保证采集顺序的前提下直接用采样序号当key最稳。2.3 窗口滚动让波形始终显示最新数据实时波形不可能是无限增长的否则数据越来越多内存和绘制压力都会失控。常规做法是只保留最近一个时间窗口内的数据。假设窗口是5秒void Widget::appendData(double key, double value) { QCustomPlot* plot m_plot; plot-graph(0)-addData(key, value); // 只保留最近60秒的原始数据让窗口滑动 plot-graph(0)-data()-removeBefore(key - 60.0); // 坐标轴右端对齐最新数据窗口宽度固定为5秒 plot-xAxis-setRange(key, 5, Qt::AlignRight); plot-yAxis-rescaleValueAxis(false, true); plot-replot(QCustomPlot::rpQueuedReplot); }setRange(key, 5, Qt::AlignRight)的意思是把x轴范围设为以key为右边界、宽度为5的区间波形看起来就是从左往右滚动。removeBefore清理窗口之外的数据这一步一定不能省否则数据量永远在涨曲线迟早卡死。rpQueuedReplot也是一个关键细节它不会立刻重绘而是把重绘请求排进事件循环同一轮事件里的多次请求会合并成一次绘制。这个机制对性能的影响比大多数人想象中大得多。3. 性能优化实战从卡顿到流畅的调优链路3.1 先定位瓶颈再动手很多朋友一遇到卡顿就怀疑是QCustomPlot不行其实大概率是调用方式有问题。最常见的错误就是每收到一个数据点就replot一次串口每秒发几千个点你每秒重绘几千次CPU不爆炸才怪。所以第一步不是优化而是定位。用QElapsedTimer简单量一下单次replot的耗时QElapsedTimer t; t.start(); plot-replot(); qDebug() replot cost: t.elapsed() ms;如果单次replot只有几毫秒但界面还是卡那说明是重绘次数太多如果单次replot已经几十毫秒那就是绘制本身太重需要从数据量和绘制开关上入手。这两种情况的优化方向完全不同别搞反。3.2 一组立竿见影的优化开关以下这几个设置是QCustomPlot实时绘制调优里最实用的组合实测下来效果非常明显plot-setNotAntialiasedElements(QCP::aeAll); // 关闭所有元素抗锯齿 plot-setPlottingHint(QCP::phFastPolylines); // 启用快速折线绘制 plot-graph(0)-setAdaptiveSampling(true); // 开启自适应降采样 plot-graph(0)-setLineStyle(QCPGraph::lsLine); plot-graph(0)-setPen(QPen(QColor(0, 170, 255), 1));抗锯齿是最大的性能杀手。它能让曲线边缘更平滑但对实时波形来说是不必要的视觉负担尤其在点数千、万个的时候关闭抗锯齿能省下一大截绘制时间。phFastPolylines是QCustomPlot提供的快速折线模式让QPainter用更高效的方式批量画线。自适应采样前面说过数据点多的时候它会自动抽稀让绘制耗时不再线性恶化。如果你不需要显示的曲线粗细变化线宽固定为1像素绘制效率也是最高的。曲线一粗边缘填充范围变大对线的绘制开销会明显上升。3.3 把重绘合并到定时器里优化重绘次数最稳的方案是用一个QTimer统一节奏比如30毫秒刷一次刚好约33帧QTimer* refreshTimer new QTimer(this); refreshTimer-setInterval(30); connect(refreshTimer, QTimer::timeout, this, Widget::flushPlot); refreshTimer-start(); // 数据收集时不刷新到达一定数量或到时间了再一次性刷新 void Widget::collectData(double key, double value) { keyBuffer.append(key); valueBuffer.append(value); if (keyBuffer.size() 1000) { flushPlot(); } } void Widget::flushPlot() { if (keyBuffer.isEmpty()) return; plot-graph(0)-addData(keyBuffer, valueBuffer); keyBuffer.clear(); valueBuffer.clear(); plot-graph(0)-data()-removeBefore(lastKey - 60.0); plot-xAxis-setRange(lastKey, 5, Qt::AlignRight); plot-replot(QCustomPlot::rpQueuedReplot); }这种攒一批、刷一次的思路比每来一个点就刷新省太多事。实时波形对帧率的要求其实没那么苛刻30帧肉眼完全流畅你把刷新间隔设在30到40毫秒之间既省CPU又能保证跟手程度。3.4 实测数据与边界控制我在自己的开发机Win10i5-9500核显Qt 5.15.2 MSVC2019 64位Release上测过一组数据给大家做个参考场景默认设置关闭抗锯齿 快速折线 自适应采样1万个点约35 FPS稳定在60 FPS以上5万个点约12 FPS约45 FPS20万个点约4 FPS约20 FPS这是单条曲线的结果。真实项目里往往还有网格、图例、多条曲线性能会再打折。所以我给自己定了一条经验线曲线数据点不超过控件像素宽度的2倍。比如绘图区宽度是1000像素那就窗口内保留2000个点以内多出来的数据用removeBefore清掉。波形视觉上几乎无差别但绘制压力小一个数量级。如果确实需要看更长的历史可以再加一个局部放大功能而不是让所有历史点堆在同一个窗口里。4. 进阶时域转频域的实时频谱绘制4.1 时域波形到底缺了什么时域波形能看到信号的幅值随时间怎么变化但看不出这个信号里包含了哪些频率成分。举个例子你采集到的信号里混着50Hz工频干扰和100Hz谐波时域上就是一条不规则的毛刺波形肉眼很难分析但如果把它做FFT变换到频域这两个频率上会出现清晰的两根谱线哪个成分能量大一目了然。这也是为什么那么多人搜qt时域图转换为频域图使用qcustomplot显示——本质上就是把采集到的波形段先做FFT再把频率-幅度关系画出来。4.2 FFT库选型kissfft是个顺手的选择Qt本身不带FFT功能需要自己集成一个FFT库。我试过FFTW功能非常强但安装、分发依赖都比较重后来换成kissfft轻量到几乎没有存在感。kissfft就几个源文件kiss_fft.c、kiss_fft.h加到工程里直接编译不需要额外配置API也很简单。做实数序列FFT的话再加一个kiss_fftr.c。上位机项目的频谱分析点数量级通常在1024到4096kissfft这个级别完全够用分配配置结构体之后会自己算好旋转因子效率不是问题。4.3 从时域到频域的完整数据链路实时频谱的标准流程是攒够N个采样点 → 加窗函数 → FFT → 取幅值 → 转dB → 刷新显示。N一般取1024或2048。这里有一个关键步骤加窗。直接从信号里截断一段做FFT会在频域上产生严重的频谱泄漏表现为谱线变宽、旁边多出很多毛刺。最简单的汉宁窗就能解决大部分问题。#include kiss_fft.h const int N 1024; kiss_fft_cfg cfg kiss_fft_alloc(N, 0, nullptr, nullptr); std::vectorkiss_fft_cpx in(N), out(N); std::vectordouble freqData(N / 2); // 每过来一批新样本就做一次FFT void Widget::computeSpectrum(const std::vectordouble samples, double sampleRate) { for (int i 0; i N; i) { // 汉宁窗 double win 0.5 * (1.0 - cos(2.0 * M_PI * i / (N - 1))); in[i].r samples[i] * win; in[i].i 0.0; } kiss_fft(cfg, in.data(), out.data()); // 单边频谱只取前 N/2 个频点 for (int i 0; i N / 2; i) { double mag sqrt(out[i].r * out[i].r out[i].i * out[i].i); double magDb 20.0 * log10(mag 1e-12); // 转成dB加小量避免log10(0) double freq i * sampleRate / N; freqData[i] QPointF(freq, magDb); } }这里做出来的是一个频谱帧。sampleRate / N就是频率分辨率比如采样率是48kHzN是1024那每个频点间隔约46.875Hz频率分辨率就是这样来的。如果你想分辨更细的频率就增大N但代价是FFT计算更慢、频谱刷新延迟更高实际项目中要自己权衡。4.4 频谱显示QCPBars与对数频率轴频谱和时域波形不一样它是离散的频点用柱状图更直观。QCustomPlot里对应的类是QCPBarsQCPBars* bars new QCPBars(plot-xAxis, plot-yAxis); bars-setPen(Qt::NoPen); bars-setBrush(QColor(0, 170, 255, 120)); // 刷新时将频谱数据设置进去 QVectordouble keys, values; for (int i 0; i N / 2; i) { keys.append(freqData[i].x()); values.append(freqData[i].y()); } bars-setData(keys, values); plot-xAxis-setRange(0, sampleRate / 2); plot-yAxis-setRange(-100, 0); plot-replot(QCustomPlot::rpQueuedReplot);如果做的是音频频谱横轴我建议设置为对数刻度因为人耳对频率的感知是对数的。QCustomPlot改对数轴很直接plot-xAxis-setScaleType(QCPAxis::stLogarithmic); plot-xAxis-setScaleLogBase(10);这里有个隐藏的坑对数轴上的数据点key不能是0或负数。比如频谱里0Hz的直流分量如果直接放进去整个轴会渲染异常或者曲线消失。一般的做法是丢弃0Hz或者把最小频率从1Hz开始。我通常直接把第1个频点之后的用于显示直流分量单独处理。频谱刷新不需要跟波形一样60帧视觉上20到30帧就完全够了。我在实际项目里频谱更新放在一个30到40毫秒的定时器里FFT计算和replot都在这个周期内完成CPU占用非常可控。5. 部署与串坑记录windeployqt、OpenGL、串口集成5.1 no qt platform plugin could be initialized 到底缺了什么这个报错在Windows上已经成了Qt部署的必修课几乎每个拿Qt写完第一个小工具的人都会遇到。双击exe弹窗告诉你no qt platform plugin could be initialized. Please reinstall the application程序直接退出。原因很简单Qt程序光拷贝一个exe是不能独立运行的它需要加载各种Qt动态库尤其是平台插件qwindows.dll。这个插件通常放在Qt安装目录的plugins\platforms下。当你缺少它、或者它不在程序能找到的路径下时Qt无法创建窗口就报这个错。解决办法是用官方提供的部署工具windeployqt在编译好的exe目录执行windeployqt --release --no-translations 你的程序.exe它会自动把所有依赖的Qt库、平台插件、样式插件拷贝到exe旁边。但有几个容易踩的细节必须保证windeployqt和你编译用的Qt版本一致否则拷进来的库版本可能不匹配Release程序用--releaseDebug程序别用这个Debug和Release的Qt库混用运行时经常直接崩溃生成结果里那个platforms目录必须在exe的同级目录下不能自己挪位置。另外如果你的程序是用MSVC编译的目标机器上还需要安装对应的VC运行库。拷完Qt库不拷运行库照样在别的机器上起不来。5.2 QCustomPlot的OpenGL加速建议先测再开网上经常有人问qcustomplot打开opengl尤其在做大数据量曲线时大家都寄希望于OpenGL加速。QCustomPlot确实支持OpenGL启用方式是在编译时定义QCUSTOMPLOT_USE_OPENGL宏然后在运行时调用plot-setOpenGl(true)。但我的实测结论是默认别开开了也必须全场景回归测试。在普通桌面显卡上OpenGL加速对大数据量折线确实有帮助但在虚拟机、远程桌面、集成显卡驱动不完善的机器上很容易出现画面空白、闪烁甚至程序崩溃。尤其是很多工控环境的显卡驱动都非常老这一点比开发机要保守很多。我在一个现场项目的工控机上开过OpenGL结果波形完全显示不出来关掉立刻恢复。后来我的策略就是开源代码里写死不开OpenGL只有在确认目标设备显卡支持、并且用户真的觉得卡的时候才考虑开启。5.3 串口数据流别在readyRead里直接replotqt 串口编程是QCustomPlot实时波形绕不开的搭档因为大多数采集类上位机第一个数据源就是串口。新手最常见的写法是connect(serial, QSerialPort::readyRead, this, []{ QByteArray data serial-readAll(); // 解析数据然后立刻replot plot-replot(); });这个问题在于串口数据到达频率和GUI重绘频率完全不在一个量级串口在高速采集时readyRead可能一秒钟触发几十次你每触发一次就去replot事件循环被重绘请求堵死界面直接卡成PPT。更合理的做法是数据接收和绘图分离。我的方案是readyRead里只做readAll把字节流塞进一个QByteArray缓冲区界面上的QTimer每30毫秒触发一次从缓冲区解析出完整的帧数据解析出key和value之后批量追加到曲线再统一replot。这样无论串口来得多快绘图压力始终被定时器锁死在一个可控频率上。如果解析本身很耗时那就把解析放到工作线程线程解析完通过信号把整理好的QVectordouble发回GUI线程GUI线程只做追加和重绘既不会卡界面也不会丢数据。5.4 Qt与QCustomPlot版本搭配选哪套最省事版本选错编译期就会给你颜色看。我遇到过好几个朋友装的是Qt 6.x从网上下载了老版本的QCustomPlot编译直接报错。我的建议是Qt版本QCustomPlot版本说明Qt 5.12.x2.0.x老项目经典搭配稳定Qt 5.15.22.1.x目前比较主流的组合Qt 6.x2.1.0及以上2.1系列开始才支持Qt 6Qt 5.15.2是目前很多老项目的首选因为它是Qt 5系列的LTS版本稳定、资料多、踩坑方案齐全。如果你在官网下载慢国内有很多高校镜像站可以下安装包速度稳定很多。新项目也可以直接上Qt 6但配套库的成熟度还是要自己做一轮验证。IDE方面说句实话别纠结Qt Creator和VS Code哪个更高级。做QCustomPlot这种带UI的桌面程序先用Qt Creator配合官方套件跑通最省心VS Code的配置成本在工作以后值得在入门阶段只会增加挫败感。最后再分享一条我做这类项目的心得。实时波形绘制项目最容易翻车的地方永远不是绘图本身而是数据链路。串口有没有丢帧、时间戳有没有跳变、缓冲区的数据有没有积压这些问题不解决波形画得再丝滑也只是自欺欺人。我习惯先把采集线程单独跑起来把原始数据落盘存一份绘图窗口只负责消费数据这样界面卡了还是数据源卡了一查就知道。先把数据流搞健康再谈波形漂不漂亮这个顺序别反了。本文还有配套的精品资源点击获取