本页内容

Q3DScatter Class

Q3DScatter 类提供了用于渲染 3D 散点图的方法。更多内容...

头文件: #include <Q3DScatter>
CMake: find_package(Qt6 REQUIRED COMPONENTS DataVisualization)
target_link_libraries(mytarget PRIVATE Qt6::DataVisualization)
qmake: QT += datavisualization
自: QtDataVisualization 1.0
继承自: QAbstract3DGraph
状态: 已弃用

该类已弃用。我们强烈建议不要在新代码中使用它。

属性

公共函数

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

信号

void axisXChanged(QValue3DAxis *axis)
void axisYChanged(QValue3DAxis *axis)
void axisZChanged(QValue3DAxis *axis)
void selectedSeriesChanged(QScatter3DSeries *series)

详细说明

该类允许开发人员以 3D 形式渲染散点图,并通过自由旋转场景来查看图表。旋转操作通过按住鼠标右键并移动鼠标来实现。缩放操作通过鼠标滚轮完成。如果启用了选择功能,则可通过鼠标左键进行选择。点击鼠标滚轮可将场景重置为默认摄像机视图。 在触控设备上,旋转通过“轻点并拖动”实现,选择通过“轻点并长按”实现,缩放通过“双指捏合”实现。

如果未向 Q3DScatter 显式设置坐标轴,则会创建无标签的临时默认坐标轴。这些默认坐标轴可通过坐标轴访问器进行修改,但一旦为某个方向显式设置了坐标轴,该方向的默认坐标轴即被销毁。

Q3DScatter 支持同时显示多个系列。

如何构建一个最简的 Q3DScatter 图表

首先,创建 Q3DScatter。由于本例中我们将图表作为顶级窗口运行,因此需要清除默认设置的 `Qt::FramelessWindowHint ` 标志:

Q3DScatter scatter;
scatter.setFlags(scatter.flags() ^ Qt::FramelessWindowHint);

现在,Q3DScatter 已准备好接收待渲染的数据。添加一个包含 3 个QVector3D 项的系列:

QScatter3DSeries *series = new QScatter3DSeries;
QScatterDataArray data;
data << QVector3D(0.5f, 0.5f, 0.5f) << QVector3D(-0.3f, -0.5f, -0.4f) << QVector3D(0.0f, -0.3f, 0.2f);
series->dataProxy()->addItems(data);
scatter.addSeries(series);

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

scatter.show();

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

#include <QtDataVisualization>

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

    Q3DScatter scatter;
    scatter.setFlags(scatter.flags() ^ Qt::FramelessWindowHint);
    QScatter3DSeries *series = new QScatter3DSeries;
    QScatterDataArray data;
    data << QVector3D(0.5f, 0.5f, 0.5f) << QVector3D(-0.3f, -0.5f, -0.4f) << QVector3D(0.0f, -0.3f, 0.2f);
    series->dataProxy()->addItems(data);
    scatter.addSeries(series);
    scatter.show();

    return app.exec();
}

以下是这几行代码生成的效果:

一个极简的3D散点图,其中三个绿色球体位于一个线框网格框内

该场景支持旋转、缩放,并可选中某个数据点查看其位置,但此精简代码示例中未包含其他交互功能。您可以通过熟悉提供的示例(如“散点图”)来进一步学习。

另请参阅 Q3DBars 、Q3DSurface 以及 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)

[read-only] selectedSeries : QScatter3DSeries*

该属性存储所选系列或为空。

访问函数:

QScatter3DSeries *selectedSeries() const

通知信号:

void selectedSeriesChanged(QScatter3DSeries *series)

成员函数文档

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

构建一个新的三维散点图,可选地包含parent 窗口和format 表面。

[virtual noexcept] Q3DScatter::~Q3DScatter()

删除该3D散点图。

void Q3DScatter::addAxis(QValue3DAxis *axis)

将axis 添加到图形中。通过addAxis添加的坐标轴尚未被实际使用,addAxis仅用于将axis 的所有权分配给该图形。axis 不能为null,也不能已添加到其他图形中。

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

void Q3DScatter::addSeries(QScatter3DSeries *series)

将series 添加到图表中。一个图表可以包含多个系列,但只有一组坐标轴。如果新添加的系列指定了选定项,该项将被高亮显示,并且任何现有的选定状态都将被清除。仅有一个新添加的系列可以处于选定状态。

另请参阅 QAbstract3DGraph::hasSeries()。

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

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

另请参阅 addAxis()。

QValue3DAxis *Q3DScatter::axisZ() const

返回当前使用的 z 轴。

注意: 这是 axisZ 属性的获取 函数。

另请参阅 setAxisZ()。

void Q3DScatter::releaseAxis(QValue3DAxis *axis)

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

如果默认轴已被释放,随后又被重新添加,其行为将与任何其他轴相同。

另请参阅 addAxis()、setAxisX()、setAxisY() 以及setAxisZ()。

void Q3DScatter::removeSeries(QScatter3DSeries *series)

从图中移除series 。

另请参阅 QAbstract3DGraph::hasSeries()。

QList<QScatter3DSeries *> Q3DScatter::seriesList() const

返回已添加到该图表的系列列表。

另请参阅 QAbstract3DGraph::hasSeries()。

void Q3DScatter::setAxisX(QValue3DAxis *axis)

将axis 设置为活动x轴。会隐式调用addAxis(),将该坐标轴的所有权转移至此图表。

如果axis 为 null,则会创建一个临时默认坐标轴,该坐标轴无标签且范围会自动调整。如果显式将另一个坐标轴设置为相同的取向,则该临时坐标轴将被销毁。

注意: 这是属性axisX 的设置 函数。

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

void Q3DScatter::setAxisY(QValue3DAxis *axis)

将axis 设置为活动y轴。隐式调用addAxis(),将该坐标轴的所有权转移给此图。

如果axis 为 null,则会创建一个临时默认坐标轴,该坐标轴无标签且范围会自动调整。如果显式地将另一个坐标轴设置为相同的取向,则该临时坐标轴将被销毁。

注意: 属性axisY 的设置 函数。

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

void Q3DScatter::setAxisZ(QValue3DAxis *axis)

将axis 设置为活动z轴。会隐式调用addAxis(),将该坐标轴的所有权转移至此图。

如果 `axis ` 为 `null`,则会创建一个临时默认坐标轴,该坐标轴无标签且范围会自动调整。如果显式将另一个坐标轴设置为相同的取向,则该临时坐标轴将被销毁。

注意: 这是属性axisZ 的设置器 函数。

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

© 2026 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.