En esta página

Q3DSurfaceWidgetItem Class

La clase Q3DSurfaceWidgetItem proporciona métodos para representar gráficos de superficies en 3D. Más información...

Encabezado: #include <Q3DSurfaceWidgetItem>
CMake: find_package(Qt6 REQUIRED COMPONENTS GraphsWidgets)
target_link_libraries(mytarget PRIVATE Qt6::GraphsWidgets)
qmake: QT += graphswidgets
Heredan: Q3DGraphsWidgetItem

Propiedades

Funciones públicas

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

Ranuras públicas

void setAxisX(QValue3DAxis *axis)
void setAxisY(QValue3DAxis *axis)
void setAxisZ(QValue3DAxis *axis)
void setFlipHorizontalGrid(bool flip)

Señales

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)

Descripción detallada

Esta clase permite a los desarrolladores representar gráficos de superficies en 3D y visualizarlos girando la escena libremente. Las propiedades visuales de la superficie, como el modo de dibujo y el sombreado, se pueden controlar mediante QSurface3DSeries.

El Q3DSurfaceWidgetItem admite la selección mostrando una bola resaltada sobre el punto de datos en el que el usuario ha hecho clic con el botón izquierdo del ratón (cuando se utiliza el controlador de entrada predeterminado) o que se ha seleccionado mediante QSurface3DSeries. El puntero de selección va acompañado de una etiqueta que, por defecto, muestra el valor del punto de datos y las coordenadas del punto.

El rango de valores y el formato de la etiqueta que se muestran en el eje se pueden controlar mediante ` QValue3DAxis`.

Para girar el gráfico, mantenga pulsado el botón derecho del ratón y mueva el ratón. El zoom se realiza con la rueda del ratón. Ambas acciones suponen que se está utilizando el controlador de entrada predeterminado.

Si no se definen ejes explícitamente para `Q3DSurfaceWidgetItem`, se crean ejes predeterminados temporales sin etiquetas. Estos ejes predeterminados pueden modificarse mediante los accesores de ejes, pero en cuanto se define explícitamente cualquier eje para la orientación, el eje predeterminado para esa orientación se elimina.

Cómo construir un gráfico Q3DSurfaceWidgetItem mínimo

En primer lugar, crea un Q3DSurfaceWidgetItem. Dado que en este ejemplo estamos ejecutando el gráfico como una ventana de nivel superior, debemos desactivar el indicador « Qt::FramelessWindowHint », que está activado por defecto:

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

Ahora Q3DSurfaceWidgetItem está listo para recibir los datos que se van a representar. Crea elementos de datos para recibir valores:

Nota: En la nueva relación de serie proxy, los datos se almacenan en series. Por lo tanto, para que el proxy pueda añadir, eliminar o editar los datos, es imprescindible crear primero una serie.

Primero, introduce los datos en los elementos de fila y, a continuación, añade sus punteros al elemento de datos:

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;

Crea una nueva serie y asigna datos a ella:

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

Por último, tendrás que configurarla como visible:

surface.widget()->show();

El código completo necesario para crear y mostrar este gráfico es:

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

Y esto es lo que producen esas pocas líneas de código:

Gráfico de superficie en 3D con un plano verde inclinado

La escena se puede girar, ampliar y se puede seleccionar un punto de la superficie para ver su posición, pero este ejemplo de código mínimo no incluye otras interacciones. Puedes obtener más información familiarizándote con los ejemplos proporcionados, como la Galería de gráficos de superficie.

Véase también Q3DBarsWidgetItem, Q3DScatterWidgetItem y Qt Graphs : Clases de C++ para 3D.

Documentación de propiedades

axisX : QValue3DAxis*

Esta propiedad indica el eje X activo.

Establece axis como el eje X activo. Llama implícitamente a addAxis() para transferir la propiedad del eje a este gráfico.

Si axis es nulo, se crea un eje predeterminado temporal sin etiquetas y con un rango que se ajusta automáticamente.

Este eje temporal se elimina si se establece explícitamente otro eje con la misma orientación.

Funciones de acceso:

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

Señal de notificación:

void axisXChanged(QValue3DAxis *axis)

Véanse también addAxis() y releaseAxis().

axisY : QValue3DAxis*

Esta propiedad indica el eje Y activo.

Establece axis como el eje Y activo. Llama implícitamente a addAxis() para transferir la propiedad del eje a este gráfico.

Si axis es nulo, se crea un eje predeterminado temporal sin etiquetas y con un rango que se ajusta automáticamente.

Este eje temporal se elimina si se establece explícitamente otro eje con la misma orientación.

Funciones de acceso:

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

Señal de notificación:

void axisYChanged(QValue3DAxis *axis)

Véase también ` addAxis()` y ` releaseAxis()`.

axisZ : QValue3DAxis*

Esta propiedad indica el eje Z activo.

Establece axis como el eje Z activo. Llama implícitamente a addAxis() para transferir la propiedad del eje a este gráfico.

Si axis es nulo, se crea un eje predeterminado temporal sin etiquetas y con un rango que se ajusta automáticamente.

Este eje temporal se elimina si se establece explícitamente otro eje con la misma orientación.

Funciones de acceso:

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

Señal de notificador:

void axisZChanged(QValue3DAxis *axis)

Véase también addAxis() y releaseAxis().

flipHorizontalGrid : bool

Esta propiedad determina si la cuadrícula del eje horizontal se muestra en la parte superior del gráfico en lugar de en la parte inferior.

En algunos casos de uso, la cuadrícula del eje horizontal queda cubierta en su mayor parte por la superficie, por lo que puede resultar más útil mostrar la cuadrícula del eje horizontal en la parte superior del gráfico en lugar de en la inferior. Un caso de uso típico de esto es la visualización de espectrogramas 2D mediante proyección ortográfica con una perspectiva de arriba hacia abajo.

Si false, la cuadrícula del eje horizontal y las etiquetas se dibujan sobre el fondo horizontal del gráfico. Si true, la cuadrícula del eje horizontal y las etiquetas se dibujan en el lado opuesto del gráfico respecto al fondo horizontal. El valor por defecto es false.

Funciones de acceso:

bool flipHorizontalGrid() const
void setFlipHorizontalGrid(bool flip)

Señal de notificación:

void flipHorizontalGridChanged(bool flip)

[read-only] selectedSeries : QSurface3DSeries*

Esta propiedad contiene la serie seleccionada o el valor nulo.

Si se ha establecido « MultiSeries » en «selectionMode», esta propiedad contiene la serie a la que pertenece el punto seleccionado.

Funciones de acceso:

QSurface3DSeries *selectedSeries() const

Señal de notificador:

void selectedSeriesChanged(QSurface3DSeries *series)

Documentación de funciones de miembro

[explicit] Q3DSurfaceWidgetItem::Q3DSurfaceWidgetItem(QObject *parent = nullptr)

Crea un nuevo gráfico de superficie en 3D con el parámetro opcional « parent ».

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

Elimina el gráfico de superficie en 3D.

void Q3DSurfaceWidgetItem::addAxis(QValue3DAxis *axis)

Añade « axis » al gráfico. Los ejes añadidos mediante «addAxis» aún no se consideran en uso; «addAxis» se utiliza simplemente para asignar la propiedad de « axis » al gráfico. « axis » no debe ser nulo ni estar añadido a otro gráfico.

Véanse también releaseAxis(), setAxisX(), setAxisY() y setAxisZ().

void Q3DSurfaceWidgetItem::addSeries(QSurface3DSeries *series)

Añade la serie « series » al gráfico. Un gráfico puede contener varias series, pero solo tiene un conjunto de ejes. Si la serie recién añadida tiene un elemento seleccionado, este se resaltará y se desactivará cualquier selección existente. Solo una de las series añadidas puede tener una selección activa.

Véase también Q3DGraphsWidgetItem::hasSeries().

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

Devuelve la lista de todos los ejes añadidos.

Véase también addAxis().

void Q3DSurfaceWidgetItem::releaseAxis(QValue3DAxis *axis)

Devuelve la propiedad del « axis » al llamante, si se ha añadido a este gráfico. Si el « axis » liberado está en uso, se creará un nuevo eje predeterminado y se activará.

Si el eje predeterminado se libera y se vuelve a añadir más tarde, se comportará como cualquier otro eje.

Véase también addAxis(), setAxisX(), setAxisY() y setAxisZ().

void Q3DSurfaceWidgetItem::removeSeries(QSurface3DSeries *series)

Elimina el « series » del gráfico.

Véase también Q3DGraphsWidgetItem::hasSeries().

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

Exporta la vista de corte solicitada a una imagen. El resultado del corte es la serie de index. Para exportar todas las series, establece index en -1. El corte exportado es una línea de fila o columna, definida por sliceType, en un requestedIndex determinado.

La señal sliceImageChanged se emite cuando la imagen está lista y puede capturarse de la siguiente manera:

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

item->renderSliceToImage(sliceType, index);

La imagen se renderiza con la configuración actual de suavizado.

Esta función se introdujo en Qt 6.10.

Véase también QQuickItem::grabToImage() y sliceImageChanged().

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

Devuelve la lista de series añadidas a este gráfico.

Véase también Q3DGraphsWidgetItem::hasSeries().

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

Se emite cuando « renderSliceToImage » ha preparado « image ».

Esta función se introdujo en 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.