第25章 Qt Data Visualization：3D数据可视化实战

说实话，Qt Data Visualization 这个模块，我第一次接触时觉得它就是个「花架子」—— 3D 图表能有多实用？直到我在一个工业监控项目里，需要展示传感器阵列的实时数据分布，传统的 2D 折线图根本看不清楚空间趋势。嗯，那时候我才意识到，有些数据天生就是立体的。

这一章，我们就来聊聊 Qt 里的 3D 可视化三件套：散点图、柱状图、曲面图。我会把我在项目中踩过的坑、总结的技巧都抖出来。

25.1 3D散点图：Q3DScatter 实战

3D散点图，说白了就是在三维空间里撒一把「芝麻」，每个点代表一个数据样本。我最常用它来展示聚类分析的结果。

先看一个最简单的例子：

// 创建3D散点图窗口
Q3DScatter *scatter = new Q3DScatter();
scatter->setFlags(scatter->flags() ^ Qt::FramelessWindowHint);

// 创建数据系列
QScatter3DSeries *series = new QScatter3DSeries();
QScatterDataArray data;

// 填充数据：三个随机簇
for (int i = 0; i < 100; ++i) {
    data << QScatterDataItem(rand() % 10, rand() % 10, rand() % 10);
}
series->dataProxy()->addItems(data);
scatter->addSeries(series);
scatter->show();

25.2 3D柱状图：Q3DBars 与数据分组

3D柱状图适合展示分类数据的对比。比如不同地区、不同月份的销售额。我个人习惯用 QBarDataProxy 来管理数据，它天然支持行和列的概念。

// 创建3D柱状图
Q3DBars *bars = new Q3DBars();
bars->setFlags(bars->flags() ^ Qt::FramelessWindowHint);

// 构建数据代理
QBarDataProxy *proxy = new QBarDataProxy();
QBarDataArray rowArray;

// 添加三行数据（比如三个产品线）
for (int row = 0; row < 3; ++row) {
    QBarDataRow *dataRow = new QBarDataRow();
    for (int col = 0; col < 4; ++col) {
        *dataRow << QBarDataItem(rand() % 100);
    }
    rowArray << dataRow;
}
proxy->resetArray(rowArray);

QBar3DSeries *series = new QBar3DSeries(proxy);
series->setColor(QColor(Qt::blue));
bars->addSeries(series);
bars->show();

25.3 3D曲面图：Q3DSurface 与函数可视化

曲面图是我个人觉得最酷的。它能把数学函数、地形数据、热力图等变成一张「毯子」。你想想看，一个 z = sin(x) * cos(y) 的函数，用曲面图一看就全明白了。

// 创建曲面图
Q3DSurface *surface = new Q3DSurface();
surface->setFlags(surface->flags() ^ Qt::FramelessWindowHint);

// 使用自定义数据代理
QSurfaceDataProxy *proxy = new QSurfaceDataProxy();
QSurfaceDataArray dataArray;

// 生成 20x20 网格的 sin(x)*cos(y) 曲面
for (int i = 0; i < 20; ++i) {
    QSurfaceDataRow *row = new QSurfaceDataRow();
    for (int j = 0; j < 20; ++j) {
        float x = i * 0.5f;
        float y = j * 0.5f;
        float z = qSin(x) * qCos(y);
        *row << QSurfaceDataItem(x, z, y);
    }
    dataArray << row;
}
proxy->resetArray(dataArray);

QSurface3DSeries *series = new QSurface3DSeries(proxy);
series->setColorStyle(Q3DTheme::ColorStyleRangeGradient);
surface->addSeries(series);
surface->show();

25.4 数据代理：QAbstractDataProxy 家族

数据代理是 Qt Data Visualization 的灵魂。说白了，它就是数据与图表之间的「翻译官」。Qt 提供了几种现成的代理：

如果你需要实时更新数据，比如每秒刷新一次传感器读数，我建议使用 setItem() 或 updateItems() 方法，而不是每次都 resetArray()。后者会重建整个数据结构，开销很大。

25.5 自定义外观：Theme 与颜色映射

默认的 3D 图表其实挺丑的 —— 灰不溜秋的背景，单调的颜色。Qt 提供了 Q3DTheme 来拯救审美。

// 切换主题
Q3DTheme *theme = new Q3DTheme(Q3DTheme::ThemeQt);
theme->setBackgroundEnabled(false);
theme->setLabelBackgroundEnabled(false);
theme->setFont(QFont("Microsoft YaHei", 10));
theme->setColorStyle(Q3DTheme::ColorStyleRangeGradient);

// 自定义渐变色
QLinearGradient gradient(0, 0, 1, 0);
gradient.setColorAt(0.0, Qt::blue);
gradient.setColorAt(0.5, Qt::yellow);
gradient.setColorAt(1.0, Qt::red);
theme->setBaseGradient(gradient);

surface->setActiveTheme(theme);

25.6 交互控制：旋转、缩放与选择

3D 图表最大的优势就是交互性。用户可以用鼠标拖拽旋转视角，滚轮缩放。默认的 Q3DInputHandler 已经提供了这些功能，但你可以自定义。

// 自定义选择模式
Q3DInputHandler *handler = new Q3DInputHandler();
handler->setSelectionMode(QAbstract3DGraph::SelectionItemAndRow | 
                          QAbstract3DGraph::SelectionSlice);
surface->setActiveInputHandler(handler);

// 连接选择信号
connect(surface->selectedSeries(), &QSurface3DSeries::selectedPointChanged,
        [](const QPoint &point) {
    qDebug() << "选中点坐标:" << point;
});

嗯，这里要注意：如果你开启了 SelectionSlice 模式，点击柱状图时会自动显示一个切片视图，方便查看具体数值。这个功能在数据对比时特别实用。

25.7 避坑指南与性能优化

最后，分享几个我踩过的坑：

• 数据量过大导致卡顿：我曾经一次性往散点图里塞了10万个点，结果旋转时帧率掉到个位数。解决方案是使用 setMeshSmooth(true) 并适当降低点的大小。
• 轴范围设置不当：如果数据范围是 0-100，但轴默认范围是 0-10，图表会显示不全。记得调用 axis->setRange(min, max)。
• 内存泄漏：QBarDataRow 和 QSurfaceDataRow 是用 new 创建的，但 resetArray() 会接管所有权，不需要手动 delete。不过如果你频繁重置数据，记得先 clear() 再 resetArray()。
• 窗口嵌入问题：Q3DScatter 等组件默认是独立窗口。如果想嵌入到 QWidget 中，需要调用 QWidget::createWindowContainer() 包装一下。