Q3DSurface Class

Q3DSurface 类提供了渲染三维曲面图的方法。更多

Header: #include <Q3DSurface>
CMake: find_package(Qt6 REQUIRED COMPONENTS DataVisualization)
target_link_libraries(mytarget PRIVATE Qt6::DataVisualization)
qmake: QT += datavisualization
QtDataVisualization 1.0
继承: QAbstract3DGraph

属性

公共功能

Q3DSurface(const QSurfaceFormat *format = nullptr, QWindow *parent = nullptr)
virtual ~Q3DSurface()
void addAxis(QValue3DAxis *axis)
void addSeries(QSurface3DSeries *series)
QList<QValue3DAxis *> axes() const
QValue3DAxis *axisX() const
QValue3DAxis *axisY() const
QValue3DAxis *axisZ() const
bool flipHorizontalGrid() const
void releaseAxis(QValue3DAxis *axis)
void removeSeries(QSurface3DSeries *series)
QSurface3DSeries *selectedSeries() const
QList<QSurface3DSeries *> seriesList() const
void setAxisX(QValue3DAxis *axis)
void setAxisY(QValue3DAxis *axis)
void setAxisZ(QValue3DAxis *axis)
void setFlipHorizontalGrid(bool flip)

信号

void axisXChanged(QValue3DAxis *axis)
void axisYChanged(QValue3DAxis *axis)
void axisZChanged(QValue3DAxis *axis)
void flipHorizontalGridChanged(bool flip)
void selectedSeriesChanged(QSurface3DSeries *series)

详细说明

通过该类,开发人员可以渲染三维曲面图,并通过自由旋转场景来查看它们。曲面的可视化属性(如绘制模式和阴影)可通过QSurface3DSeries 控制。

Q3DSurface 支持选择功能,在用户点击鼠标左键(使用默认输入处理程序时)或通过QSurface3DSeries 选择的数据点上显示一个高亮球。选择指针附带一个标签,默认情况下显示数据点的值和坐标。

坐标轴上显示的数值范围和标签格式可通过QValue3DAxis 控制。

要旋转图表,请按住鼠标右键并移动鼠标。缩放则使用鼠标滚轮。两者都假定使用默认输入处理程序。

如果没有为 Q3DSurface 明确设置坐标轴,则会创建没有标签的临时默认坐标轴。这些默认坐标轴可通过坐标轴访问器进行修改,但一旦为某个方向明确设置了坐标轴,该方向的默认坐标轴就会被销毁。

如何构建最小 Q3DSurface 图形

首先,构建 Q3DSurface。由于我们在本例中将图形作为顶层窗口运行,因此需要清除默认设置的Qt::FramelessWindowHint 标志:

Q3DSurface surface;
surface.setFlags(surface.flags() ^ Qt::FramelessWindowHint);

现在,Q3DSurface 已准备好接收要渲染的数据。创建数据元素以接收数值:

首先将数据输入行元素,然后将其指针添加到数据元素:

*dataRow1 << QVector3D(0.0f, 0.1f, 0.5f) << QVector3D(1.0f, 0.5f, 0.5f);
*dataRow2 << QVector3D(0.0f, 1.8f, 1.0f) << QVector3D(1.0f, 1.2f, 1.0f);
*data << dataRow1 << dataRow2;

创建一个新系列并为其设置数据:

QSurface3DSeries *series = new QSurface3DSeries;
series->dataProxy()->resetArray(data);
surface.addSeries(series);

最后,你需要将其设置为可见:

surface.show();

创建和显示该图表所需的完整代码如下:

#include <QtDataVisualization>

int main(int argc, char **argv)
{
    qputenv("QSG_RHI_BACKEND", "opengl");
    QGuiApplication app(argc, argv);

    Q3DSurface surface;
    surface.setFlags(surface.flags() ^ Qt::FramelessWindowHint);
    QSurfaceDataArray *data = new QSurfaceDataArray;
    QSurfaceDataRow *dataRow1 = new QSurfaceDataRow;
    QSurfaceDataRow *dataRow2 = new QSurfaceDataRow;

    *dataRow1 << QVector3D(0.0f, 0.1f, 0.5f) << QVector3D(1.0f, 0.5f, 0.5f);
    *dataRow2 << QVector3D(0.0f, 1.8f, 1.0f) << QVector3D(1.0f, 1.2f, 1.0f);
    *data << dataRow1 << dataRow2;

    QSurface3DSeries *series = new QSurface3DSeries;
    series->dataProxy()->resetArray(data);
    surface.addSeries(series);
    surface.show();

    return app.exec();
}

这就是这几行代码产生的结果:

场景可以旋转、缩放,还可以选择表面点查看其位置,但在这个最小代码示例中不包括其他交互操作。您可以通过熟悉所提供的示例(如曲面图)了解更多信息。

另请参见 Q3DBars,Q3DScatter, 和 Qt Data Visualization C++ Classes.

属性文档

axisX : QValue3DAxis*

该属性用于保存活动 X 轴。

访问功能:

QValue3DAxis *axisX() const
void setAxisX(QValue3DAxis *axis)

通知信号:

void axisXChanged(QValue3DAxis *axis)

axisY : QValue3DAxis*

该属性用于保存活动 Y 轴。

访问功能:

QValue3DAxis *axisY() const
void setAxisY(QValue3DAxis *axis)

通知信号:

void axisYChanged(QValue3DAxis *axis)

axisZ : QValue3DAxis*

该属性用于保存活动 Z 轴。

访问功能:

QValue3DAxis *axisZ() const
void setAxisZ(QValue3DAxis *axis)

通知信号:

void axisZChanged(QValue3DAxis *axis)

[since QtDataVisualization 1.2] flipHorizontalGrid : bool

该属性用于确定水平轴网格是否显示在图形顶部而不是底部。

在某些使用案例中,水平轴网格大部分被表面覆盖,因此将水平轴网格显示在图形顶部而不是底部可能更有用。一个典型的使用案例就是使用正投影图形以自上而下的视角显示二维频谱图。

如果false ,横轴网格和标签将绘制在图表的水平背景上。如果为true ,则横轴网格和标签绘制在图形与水平背景相反的一侧。默认值为false

此属性在 QtDataVisualization 1.2 中引入。

访问函数:

bool flipHorizontalGrid() const
void setFlipHorizontalGrid(bool flip)

Notifier 信号:

void flipHorizontalGridChanged(bool flip)

[read-only] selectedSeries : QSurface3DSeries* const

此属性表示所选系列或空。

如果设置了 selectionMode(选择模式)SelectionMultiSeries ,则此属性将保存拥有所选点的系列。

访问功能:

QSurface3DSeries *selectedSeries() const

Notifier 信号:

void selectedSeriesChanged(QSurface3DSeries *series)

成员函数 文档

[explicit] Q3DSurface::Q3DSurface(const QSurfaceFormat *format = nullptr, QWindow *parent = nullptr)

构建新的三维曲面图,可选parent 窗口和曲面format

[virtual noexcept] Q3DSurface::~Q3DSurface()

销毁 3D 表面图形。

void Q3DSurface::addAxis(QValue3DAxis *axis)

axis 添加到图表中。通过 addAxis 添加的坐标轴尚未投入使用,addAxis 只是用来将axis 的所有权赋予图形。axis 不得为空或添加到其他图形中。

另请参阅 releaseAxis()、setAxisX()、setAxisY() 和setAxisZ()。

void Q3DSurface::addSeries(QSurface3DSeries *series)

series 添加到图表中。图形可以包含多个序列,但只有一组坐标轴。如果新添加的序列已指定了一个选中项,则该选中项将突出显示,并且任何现有选中项都将被清除。只有一个添加的序列可以有一个活动选区。

另请参见 QAbstract3DGraph::hasSeries()。

QList<QValue3DAxis *> Q3DSurface::axes() const

返回所有已添加轴的列表。

另请参见 addAxis()。

void Q3DSurface::releaseAxis(QValue3DAxis *axis)

如果axis 已添加到此图形中,则将其所有权释放给调用者。如果被释放的axis 正在使用中,将创建一个新的默认坐标轴并将其设置为活动状态。

如果默认轴被释放并在稍后添加回来,它的行为与其他轴一样。

另请参见 addAxis()、setAxisX()、setAxisY() 和setAxisZ()。

void Q3DSurface::removeSeries(QSurface3DSeries *series)

从图表中删除series

另请参见 QAbstract3DGraph::hasSeries().

QList<QSurface3DSeries *> Q3DSurface::seriesList() const

返回添加到此图表的系列列表。

另请参阅 QAbstract3DGraph::hasSeries()。

void Q3DSurface::setAxisX(QValue3DAxis *axis)

axis 设置为活动 x 轴。隐式调用addAxis() 将坐标轴的所有权转移到此图形。

如果axis 为空,则会创建一个没有标签和自动调整范围的临时默认坐标轴。

如果将另一个轴明确设置为相同方向,则会销毁该临时轴。

注: 属性axisX 的设置函数。

另请参阅 axisX()、addAxis() 和releaseAxis()。

void Q3DSurface::setAxisY(QValue3DAxis *axis)

axis 设置为活动 Y 轴。隐式调用addAxis() 将坐标轴的所有权转移到此图形。

如果axis 为空,则会创建一个没有标签和自动调整范围的临时默认坐标轴。

如果将另一个轴明确设置为相同方向,则会销毁该临时轴。

注: 属性axisY 的设置函数。

另请参阅 axisY()、addAxis() 和releaseAxis()。

void Q3DSurface::setAxisZ(QValue3DAxis *axis)

axis 设置为活动 Z 轴。隐式调用addAxis() 将坐标轴的所有权转移到此图形。

如果axis 为空,则会创建一个没有标签和自动调整范围的临时默认坐标轴。

如果将另一个轴明确设置为相同方向,则会销毁该临时轴。

注: 属性axisZ 的设置函数。

另请参阅 axisZ()、addAxis() 和releaseAxis()。

© 2025 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.