Auf dieser Seite

Q3DSurface Class

Die Klasse „Q3DSurface“ bietet Methoden zum Rendern von 3D-Oberflächendiagrammen. Mehr...

Überschrift: #include <Q3DSurface>
CMake: find_package(Qt6 REQUIRED COMPONENTS DataVisualization)
target_link_libraries(mytarget PRIVATE Qt6::DataVisualization)
qmake: QT += datavisualization
Seit: QtDataVisualization 1.0
Erbt von: QAbstract3DGraph
Status: Veraltet

Diese Klasse ist veraltet. Wir raten dringend davon ab, sie in neuem Code zu verwenden.

Eigenschaften

Öffentliche Funktionen

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)

Signale

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

Ausführliche Beschreibung

Diese Klasse ermöglicht es Entwicklern, 3D-Oberflächendiagramme zu rendern und diese durch freies Drehen der Szene zu betrachten. Die visuellen Eigenschaften der Oberfläche, wie z. B. der Zeichenmodus und die Schattierung, können über QSurface3DSeries gesteuert werden.

Die Klasse `Q3DSurface` unterstützt die Auswahl, indem sie eine hervorgehobene Kugel an dem Datenpunkt anzeigt, auf den der Benutzer mit der linken Maustaste geklickt hat (sofern der Standard-Eingabehandler verwendet wird) oder der über ` QSurface3DSeries` ausgewählt wurde. Der Auswahlzeiger wird von einer Beschriftung begleitet, die standardmäßig den Wert des Datenpunkts und die Koordinaten des Punkts anzeigt.

Der auf der Achse angezeigte Wertebereich und das Beschriftungsformat können über ` QValue3DAxis` gesteuert werden.

Um das Diagramm zu drehen, halten Sie die rechte Maustaste gedrückt und bewegen Sie die Maus. Das Zoomen erfolgt über das Mausrad. Bei beiden Funktionen wird davon ausgegangen, dass der Standard-Eingabehandler verwendet wird.

Wenn für Q3DSurface keine Achsen explizit festgelegt sind, werden temporäre Standardachsen ohne Beschriftungen erstellt. Diese Standardachsen können über Achsen-Accessoren geändert werden, doch sobald eine Achse explizit für die jeweilige Ausrichtung festgelegt wird, wird die Standardachse für diese Ausrichtung gelöscht.

So erstellen Sie ein minimales Q3DSurface-Diagramm

Erstellen Sie zunächst ein „Q3DSurface“-Objekt. Da wir das Diagramm in diesem Beispiel als Fenster auf oberster Ebene ausführen, müssen wir das Flag „ Qt::FramelessWindowHint “ zurücksetzen, das standardmäßig gesetzt ist:

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

Nun ist Q3DSurface bereit, Daten zum Rendern zu empfangen. Erstellen Sie Datenelemente, um Werte zu empfangen:

Führen Sie zunächst die Daten in die Zeilenelemente ein und fügen Sie anschließend deren Zeiger zum Datenelement hinzu:

*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;

Erstellen Sie eine neue Reihe und weisen Sie ihr Daten zu:

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

Abschließend müssen Sie das Diagramm als sichtbar festlegen:

surface.show();

Der vollständige Code zum Erstellen und Anzeigen dieses Diagramms lautet:

#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();
}

Und das ist das Ergebnis dieser wenigen Codezeilen:

Minimalistisches 3D-Oberflächendiagramm, das eine grüne, gefaltete Kammoberfläche über einem Gitterboden zeigt

Die Szene kann gedreht und vergrößert werden, und es kann ein Oberflächenpunkt ausgewählt werden, um dessen Position anzuzeigen; dieses minimale Code-Beispiel enthält jedoch keine weiteren Interaktionsmöglichkeiten. Weitere Informationen erhalten Sie, wenn Sie sich mit den bereitgestellten Beispielen, wie dem „Surface Graph“, vertraut machen.

Siehe auch Q3DBars, Q3DScatter und Qt Data Visualization C++ Classes.

Dokumentation zu den Eigenschaften

axisX : QValue3DAxis*

Diese Eigenschaft gibt die aktive x-Achse an.

Zugriffsfunktionen:

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

Benachrichtigungssignal:

void axisXChanged(QValue3DAxis *axis)

axisY : QValue3DAxis*

Diese Eigenschaft gibt die aktive y-Achse an.

Zugriffsfunktionen:

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

Benachrichtigungssignal:

void axisYChanged(QValue3DAxis *axis)

axisZ : QValue3DAxis*

Diese Eigenschaft gibt die aktive Z-Achse an.

Zugriffsfunktionen:

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

Benachrichtigungssignal:

void axisZChanged(QValue3DAxis *axis)

[since QtDataVisualization 1.2] flipHorizontalGrid : bool

Diese Eigenschaft gilt unabhängig davon, ob das Raster der horizontalen Achse über dem Diagramm statt darunter angezeigt wird.

In einigen Anwendungsfällen wird das Horizontalachsenraster größtenteils von der Oberfläche verdeckt, sodass es sinnvoller sein kann, das Horizontalachsenraster oberhalb des Diagramms statt darunter anzuzeigen. Ein typischer Anwendungsfall hierfür ist die Darstellung von 2D-Spektrogrammen unter Verwendung einer orthogonalen Projektion mit einer Blickrichtung von oben nach unten.

Wenn „ false “ gesetzt ist, werden das horizontale Achsenraster und die Beschriftungen auf dem horizontalen Hintergrund des Diagramms gezeichnet. Wenn „ true “ gesetzt ist, werden das horizontale Achsenraster und die Beschriftungen auf der dem horizontalen Hintergrund gegenüberliegenden Seite des Diagramms gezeichnet. Der Standardwert ist „ false “.

Diese Aufzählung wurde in QtDataVisualization 1.2 eingeführt.

Zugriffsfunktionen:

bool flipHorizontalGrid() const
void setFlipHorizontalGrid(bool flip)

Notifier-Signal:

void flipHorizontalGridChanged(bool flip)

[read-only] selectedSeries : QSurface3DSeries*

Diese Eigenschaft enthält die ausgewählte Reihe oder den Wert „null“.

Wenn für „selectionMode“ der Wert „ SelectionMultiSeries “ festgelegt ist, enthält diese Eigenschaft die Reihe, zu der der ausgewählte Punkt gehört.

Zugriffsfunktionen:

QSurface3DSeries *selectedSeries() const

Benachrichtigungssignal:

void selectedSeriesChanged(QSurface3DSeries *series)

Dokumentation der Mitgliedsfunktionen

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

Erstellt ein neues 3D-Oberflächendiagramm mit optionalem Fenster „ parent “ und Oberflächendaten „ format “.

[virtual noexcept] Q3DSurface::~Q3DSurface()

Löscht die 3D-Oberflächengrafik.

void Q3DSurface::addAxis(QValue3DAxis *axis)

Fügt „ axis “ zum Diagramm hinzu. Die über „addAxis“ hinzugefügten Achsen werden noch nicht verwendet; „addAxis“ dient lediglich dazu, die Zuständigkeit für die „ axis “ dem Diagramm zuzuweisen. „ axis “ darf nicht null sein oder bereits einem anderen Diagramm hinzugefügt worden sein.

Siehe auch „ releaseAxis()“, „ setAxisX()“, „ setAxisY()“ und „ setAxisZ()“.

void Q3DSurface::addSeries(QSurface3DSeries *series)

Fügt die „ series “ zum Diagramm hinzu. Ein Diagramm kann mehrere Reihen enthalten, verfügt jedoch nur über einen Achsenpaar. Wenn für die neu hinzugefügte Reihe ein Element ausgewählt wurde, wird dieses hervorgehoben und eine eventuell vorhandene Auswahl wird aufgehoben. Nur eine der hinzugefügten Reihen kann aktiv ausgewählt sein.

Siehe auch „ QAbstract3DGraph::hasSeries()“.

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

Gibt die Liste aller hinzugefügten Achsen zurück.

Siehe auch „ addAxis()“.

void Q3DSurface::releaseAxis(QValue3DAxis *axis)

Gibt die Eigentumsrechte an der „ axis “ wieder an den Aufrufer zurück, sofern diese zu diesem Graphen hinzugefügt wurde. Wenn die freigegebene „ axis “ gerade verwendet wird, wird eine neue Standardachse erstellt und als aktiv gesetzt.

Wird die Standardachse freigegeben und später wieder hinzugefügt, verhält sie sich wie jede andere Achse.

Siehe auch „ addAxis()“, „ setAxisX()“, „ setAxisY()“ und „ setAxisZ()“.

void Q3DSurface::removeSeries(QSurface3DSeries *series)

Entfernt den „ series “ aus dem Diagramm.

Siehe auch „ QAbstract3DGraph::hasSeries()“.

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

Gibt die Liste der zu diesem Diagramm hinzugefügten Reihen zurück.

Siehe auch „ QAbstract3DGraph::hasSeries()“.

void Q3DSurface::setAxisX(QValue3DAxis *axis)

Legt „ axis “ als aktive x-Achse fest. Ruft implizit „ addAxis()“ auf, um die Eigentumsrechte an der Achse auf dieses Diagramm zu übertragen.

Ist axis null, wird eine temporäre Standardachse ohne Beschriftungen und mit automatisch angepasster Skalierung erstellt.

Diese temporäre Achse wird gelöscht, wenn eine andere Achse explizit auf dieselbe Ausrichtung festgelegt wird.

Hinweis: Setter -Funktion für die Eigenschaft ` axisX`.

Siehe auch „ axisX()“, „ addAxis()“ und „ releaseAxis()“.

void Q3DSurface::setAxisY(QValue3DAxis *axis)

Legt „ axis “ als aktive y-Achse fest. Ruft implizit „ addAxis()“ auf, um die Eigentumsrechte an der Achse auf dieses Diagramm zu übertragen.

Ist axis null, wird eine temporäre Standardachse ohne Beschriftungen und mit einem sich automatisch anpassenden Bereich erstellt.

Diese temporäre Achse wird gelöscht, wenn eine andere Achse explizit auf dieselbe Ausrichtung gesetzt wird.

Hinweis: Setter -Funktion für die Eigenschaft ` axisY`.

Siehe auch „ axisY()“, „ addAxis()“ und „ releaseAxis()“.

void Q3DSurface::setAxisZ(QValue3DAxis *axis)

Legt „ axis “ als aktive Z-Achse fest. Ruft implizit „ addAxis()“ auf, um die Eigentumsrechte an der Achse auf dieses Diagramm zu übertragen.

Ist axis null, wird eine temporäre Standardachse ohne Beschriftungen und mit einem sich automatisch anpassenden Bereich erstellt.

Diese temporäre Achse wird gelöscht, wenn eine andere Achse explizit auf dieselbe Ausrichtung gesetzt wird.

Hinweis: Setter -Funktion für die Eigenschaft ` axisZ`.

Siehe auch „ axisZ()“, „ addAxis()“ und „ 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.