Sur cette page

Q3DSurface Class

La classe Q3DSurface fournit des méthodes permettant de générer des graphiques de surfaces en 3D. En savoir plus...

En-tête : #include <Q3DSurface>
CMake : find_package(Qt6 REQUIRED COMPONENTS DataVisualization)
target_link_libraries(mytarget PRIVATE Qt6::DataVisualization)
qmake : QT += datavisualization
Depuis : QtDataVisualization 1.0
Hérite de : QAbstract3DGraph
Statut : Obsolète

Cette classe est obsolète. Nous déconseillons fortement de l'utiliser dans du nouveau code.

Propriétés

Fonctions publiques

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)

Signaux

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

Description détaillée

Cette classe permet aux développeurs de générer des graphiques de surface en 3D et de les visualiser en faisant pivoter librement la scène. Les propriétés visuelles de la surface, telles que le mode de dessin et l'ombrage, peuvent être contrôlées via QSurface3DSeries.

La classe Q3DSurface prend en charge la sélection en affichant une boule en surbrillance sur le point de données sur lequel l’utilisateur a cliqué avec le bouton gauche de la souris (lorsque le gestionnaire d’entrée par défaut est utilisé) ou sélectionné via QSurface3DSeries. Le pointeur de sélection est accompagné d’une étiquette qui, par défaut, affiche la valeur du point de données et les coordonnées de ce point.

La plage de valeurs et le format de l'étiquette affichés sur l'axe peuvent être contrôlés via QValue3DAxis.

Pour faire pivoter le graphique, maintenez le bouton droit de la souris enfoncé et déplacez la souris. Le zoom s’effectue à l’aide de la molette de la souris. Ces deux opérations supposent que le gestionnaire d’entrée par défaut est utilisé.

Si aucun axe n’est explicitement défini pour Q3DSurface, des axes par défaut temporaires sans étiquette sont créés. Ces axes par défaut peuvent être modifiés via les accesseurs d’axe, mais dès qu’un axe est explicitement défini pour une orientation donnée, l’axe par défaut correspondant à cette orientation est supprimé.

Comment construire un graphique Q3DSurface minimal

Commencez par créer un objet Q3DSurface. Comme, dans cet exemple, le graphique s’exécute en tant que fenêtre de niveau supérieur, il faut désactiver le drapeau « Qt::FramelessWindowHint », qui est activé par défaut :

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

Q3DSurface est désormais prêt à recevoir les données à afficher. Créez des éléments de données pour recevoir les valeurs :

Commencez par alimenter les éléments de ligne en données, puis ajoutez leurs pointeurs à l'élément de données :

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

Créez une nouvelle série et attribuez-lui des données :

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

Enfin, vous devrez le rendre visible :

surface.show();

Voici le code complet nécessaire pour créer et afficher ce graphique :

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

Et voici le résultat obtenu avec ces quelques lignes de code :

Représentation 3D minimaliste d'une surface, montrant une crête plissée verte au-dessus d'un sol quadrillé

La scène peut être pivotée, agrandie, et un point de la surface peut être sélectionné pour afficher sa position, mais cet exemple de code minimal ne prévoit aucune autre interaction. Vous pouvez en savoir plus en vous familiarisant avec les exemples fournis, comme le graphique de surface.

Voir également Q3DBars, Q3DScatter et Qt Data Visualization C++ Classes.

Documentation sur les propriétés

axisX : QValue3DAxis*

Cette propriété définit l'axe x actif.

Fonctions d'accès :

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

Signal de notification :

void axisXChanged(QValue3DAxis *axis)

axisY : QValue3DAxis*

Cette propriété définit l'axe Y actif.

Fonctions d'accès :

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

Signal de notification :

void axisYChanged(QValue3DAxis *axis)

axisZ : QValue3DAxis*

Cette propriété définit l'axe z actif.

Fonctions d'accès :

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

Signal de notification :

void axisZChanged(QValue3DAxis *axis)

[since QtDataVisualization 1.2] flipHorizontalGrid : bool

Cette propriété s'applique que la grille de l'axe horizontal soit affichée au-dessus du graphique plutôt qu'en dessous.

Dans certains cas d'utilisation, la grille de l'axe horizontal est en grande partie recouverte par la surface ; il peut donc être plus pratique d'afficher la grille de l'axe horizontal au-dessus du graphique plutôt qu'en dessous. Un cas d'utilisation typique est l'affichage de spectrogrammes 2D utilisant une projection orthographique avec une vue de dessus.

Si ` false`, la grille et les étiquettes de l’axe horizontal sont dessinées sur l’arrière-plan horizontal du graphique. Si ` true`, la grille et les étiquettes de l’axe horizontal sont dessinées du côté opposé au fond horizontal du graphique. La valeur par défaut est ` false`.

Cette énumération a été introduite dans QtDataVisualization 1.2.

Fonctions d'accès :

bool flipHorizontalGrid() const
void setFlipHorizontalGrid(bool flip)

Signal de notification :

void flipHorizontalGridChanged(bool flip)

[read-only] selectedSeries : QSurface3DSeries*

Cette propriété contient la série sélectionnée ou la valeur null.

Si selectionMode est défini sur « SelectionMultiSeries », cette propriété contient la série à laquelle appartient le point sélectionné.

Fonctions d'accès :

QSurface3DSeries *selectedSeries() const

Signal de notification :

void selectedSeriesChanged(QSurface3DSeries *series)

Documentation des fonctions membres

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

Crée un nouveau graphique de surface en 3D avec, en option, une fenêtre d'parent s et une format de la surface.

[virtual noexcept] Q3DSurface::~Q3DSurface()

Supprime le graphique de surface 3D.

void Q3DSurface::addAxis(QValue3DAxis *axis)

Ajoute axis au graphe. Les axes ajoutés via addAxis ne sont pas encore utilisés ; addAxis sert simplement à attribuer la propriété de l'axis au graphe. L'axis ne doit pas être null ni avoir été ajouté à un autre graphe.

Voir également releaseAxis(), setAxisX(), setAxisY() et setAxisZ().

void Q3DSurface::addSeries(QSurface3DSeries *series)

Ajoute la série « series » au graphique. Un graphique peut contenir plusieurs séries, mais ne dispose que d’un seul jeu d’axes. Si la série nouvellement ajoutée comporte un élément sélectionné, celui-ci sera mis en surbrillance et toute sélection existante sera désélectionnée. Une seule série ajoutée peut faire l’objet d’une sélection active.

Voir également QAbstract3DGraph::hasSeries().

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

Renvoie la liste de tous les axes ajoutés.

Voir aussi addAxis().

void Q3DSurface::releaseAxis(QValue3DAxis *axis)

Restitue la propriété de l'axe « axis » à l'appelant, s'il est ajouté à ce graphe. Si l'axe « axis » restitué est en cours d'utilisation, un nouvel axe par défaut sera créé et activé.

Si l’axe par défaut est libéré puis rajouté ultérieurement, il se comporte comme n’importe quel autre axe.

Voir également addAxis(), setAxisX(), setAxisY() et setAxisZ().

void Q3DSurface::removeSeries(QSurface3DSeries *series)

Supprime l'series e du graphique.

Voir aussi QAbstract3DGraph::hasSeries().

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

Renvoie la liste des séries ajoutées à ce graphique.

Voir aussi QAbstract3DGraph::hasSeries().

void Q3DSurface::setAxisX(QValue3DAxis *axis)

Définit ` axis ` comme axe x actif. Appelle implicitement la méthode ` addAxis()` pour transférer la propriété de l'axe à ce graphique.

Si axis est nul, un axe temporaire par défaut, sans étiquettes et dont la plage s'ajuste automatiquement, est créé.

Cet axe temporaire est détruit si un autre axe est explicitement défini avec la même orientation.

Remarque : fonctionde définition de la propriété axisX.

Voir également axisX(), addAxis() et releaseAxis().

void Q3DSurface::setAxisY(QValue3DAxis *axis)

Définit ` axis ` comme axe des y actif. Appelle implicitement la méthode ` addAxis()` pour transférer la propriété de l'axe à ce graphique.

Si axis est nul, un axe temporaire par défaut, sans étiquettes et dont la plage s'ajuste automatiquement, est créé.

Cet axe temporaire est détruit si un autre axe est explicitement défini avec la même orientation.

Remarque : fonctionde définition de la propriété axisY.

Voir également axisY(), addAxis() et releaseAxis().

void Q3DSurface::setAxisZ(QValue3DAxis *axis)

Définit ` axis ` comme axe Z actif. Appelle implicitement la méthode ` addAxis()` pour transférer la propriété de l'axe à ce graphique.

Si axis est nul, un axe temporaire par défaut, sans étiquettes et dont la plage s'ajuste automatiquement, est créé.

Cet axe temporaire est détruit si un autre axe est explicitement défini avec la même orientation.

Remarque : fonctionde définition pour la propriété axisZ.

Voir également axisZ(), addAxis() et 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.