Sur cette page

Q3DSurfaceWidgetItem Class

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

En-tête : #include <Q3DSurfaceWidgetItem>
CMake : find_package(Qt6 REQUIRED COMPONENTS GraphsWidgets)
target_link_libraries(mytarget PRIVATE Qt6::GraphsWidgets)
qmake : QT += graphswidgets
Hérite de : Q3DGraphsWidgetItem

Propriétés

Fonctions publiques

Q3DSurfaceWidgetItem(QObject *parent = nullptr)
virtual ~Q3DSurfaceWidgetItem() override
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)
(since 6.10) void renderSliceToImage(int index, int requestedIndex, QtGraphs3D::SliceCaptureType sliceType)
QSurface3DSeries *selectedSeries() const
QList<QSurface3DSeries *> seriesList() const

Emplacements publics

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)
(since 6.10) void sliceImageChanged(const QImage &image)

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 d'affichage et l'ombrage, peuvent être contrôlées via QSurface3DSeries.

Le Q3DSurfaceWidgetItem prend en charge la sélection en affichant une boule mise 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 actions supposent que le gestionnaire d'entrée par défaut est utilisé.

Si aucun axe n’est défini explicitement pour `Q3DSurfaceWidgetItem`, 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 défini explicitement pour une orientation, l’axe par défaut correspondant à cette orientation est détruit.

Comment construire un graphique Q3DSurfaceWidgetItem minimal

Commencez par créer un objet Q3DSurfaceWidgetItem. Étant donné que, dans cet exemple, nous exécutons le graphe en tant que fenêtre de niveau supérieur, nous devons désactiver le drapeau « Qt::FramelessWindowHint », qui est activé par défaut :

QQuickWidget quickWidget;
Q3DSurfaceWidgetItem surface;
surface.setWidget(&quickWidget);
surface.widget()->setMinimumSize(QSize(256, 256));

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

Remarque : dans la nouvelle relation de série proxy, les données sont stockées dans des séries. Par conséquent, pour que le proxy puisse ajouter, supprimer ou modifier les données, il est indispensable de créer d’abord une série.

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

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

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

QSurface3DSeries series;
series.dataProxy()->resetArray(data);
surface.addSeries(&series);

Enfin, vous devrez la rendre visible :

surface.widget()->show();

Le code complet nécessaire pour créer et afficher ce graphique est le suivant :

#include <QtGraphs>
#include <QtGraphsWidgets/q3dsurfacewidgetitem.h>
#include <QtWidgets/qapplication.h>

int main(int argc, char **argv)
{
    QApplication app(argc, argv);

    QQuickWidget quickWidget;
    Q3DSurfaceWidgetItem surface;
    surface.setWidget(&quickWidget);
    surface.widget()->setMinimumSize(QSize(256, 256));
    QSurfaceDataArray data;
    QSurfaceDataRow dataRow1;
    QSurfaceDataRow dataRow2;

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

    QSurface3DSeries series;
    series.dataProxy()->resetArray(data);
    surface.addSeries(&series);
    surface.widget()->show();

    return app.exec();
}

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

Représentation 3D d'une surface avec un plan vert incliné

La scène peut être pivotée, agrandie, et il est possible de sélectionner un point de la surface pour afficher sa position, mais cet exemple de code minimal ne comprend aucune autre interaction. Vous pouvez en savoir plus en vous familiarisant avec les exemples fournis, comme la galerie de graphiques de surface.

Voir également Q3DBarsWidgetItem, Q3DScatterWidgetItem et Qt Graphs Classes C++ pour la 3D.

Documentation sur les propriétés

axisX : QValue3DAxis*

Cette propriété indique l'axe des x actif.

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.

Fonctions d’accès :

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

Signal de notification :

void axisXChanged(QValue3DAxis *axis)

Voir également addAxis() et releaseAxis().

axisY : QValue3DAxis*

Cette propriété désigne l'axe des y actif.

Définit axis comme axe 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.

Fonctions d'accès :

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

Signal de notification :

void axisYChanged(QValue3DAxis *axis)

Voir également addAxis() et releaseAxis().

axisZ : QValue3DAxis*

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

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.

Fonctions d'accès :

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

Signal de notification :

void axisZChanged(QValue3DAxis *axis)

Voir également addAxis() et releaseAxis().

flipHorizontalGrid : bool

Cette propriété détermine si la grille de l'axe horizontal s'affiche 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 utile 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 un point de vue de haut en bas.

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`.

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 « MultiSeries », 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] Q3DSurfaceWidgetItem::Q3DSurfaceWidgetItem(QObject *parent = nullptr)

Crée un nouveau graphique de surface en 3D avec l'option « parent ».

[override virtual noexcept] Q3DSurfaceWidgetItem::~Q3DSurfaceWidgetItem()

Supprime le graphique de surface 3D.

void Q3DSurfaceWidgetItem::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 Q3DSurfaceWidgetItem::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 Q3DGraphsWidgetItem::hasSeries().

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

Renvoie la liste de tous les axes ajoutés.

Voir aussi addAxis().

void Q3DSurfaceWidgetItem::releaseAxis(QValue3DAxis *axis)

Restitue la propriété de l'axis à l'appelant, s'il est ajouté à ce graphe. Si l'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 Q3DSurfaceWidgetItem::removeSeries(QSurface3DSeries *series)

Supprime l'series e du graphe.

Voir aussi Q3DGraphsWidgetItem::hasSeries().

[since 6.10] void Q3DSurfaceWidgetItem::renderSliceToImage(int index, int requestedIndex, QtGraphs3D::SliceCaptureType sliceType)

Exporte la vue de coupe demandée vers une image. Le résultat de la coupe est la série de index. Pour exporter toutes les séries, définissez index sur -1. La coupe exportée correspond à une ligne ou une colonne, définie par sliceType, à une requestedIndex donnée.

Le signal sliceImageChanged est émis lorsque l’image est prête et peut être capturé comme suit :

connect(item, &Q3DSurfaceWidgetItem::sliceImageChanged, this, [](const QImage &image) {
    // ~~~
});

item->renderSliceToImage(sliceType, index);

L'image est rendue avec les paramètres d'anticrénelage actuels.

Cette fonction a été introduite dans Qt 6.10.

Voir également QQuickItem::grabToImage() et sliceImageChanged().

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

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

Voir aussi Q3DGraphsWidgetItem::hasSeries().

[signal, since 6.10] void Q3DSurfaceWidgetItem::sliceImageChanged(const QImage &image)

Émis lorsque ` renderSliceToImage ` a préparé ` image`.

Cette fonction a été introduite dans Qt 6.10.

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