En esta página

Q3DSurface Class

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

Encabezado: #include <Q3DSurface>
CMake: find_package(Qt6 REQUIRED COMPONENTS DataVisualization)
target_link_libraries(mytarget PRIVATE Qt6::DataVisualization)
qmake: QT += datavisualization
Desde: QtDataVisualization 1.0
Heredado de: QAbstract3DGraph
Estado: Obsoleta

Esta clase está obsoleta. Se desaconseja encarecidamente su uso en código nuevo.

Propiedades

Funciones públicas

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)

Señales

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

Descripción detallada

Esta clase permite a los desarrolladores generar 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.

Q3DSurface 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 a través de QValue3DAxis.

Para girar el gráfico, mantén pulsado el botón derecho del ratón y mueve 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 establecen ejes de forma explícita en Q3DSurface, se crean ejes predeterminados temporales sin etiquetas. Estos ejes predeterminados se pueden modificar mediante los accesores de ejes, pero tan pronto como se establezca explícitamente un eje para una orientación, el eje predeterminado para esa orientación se elimina.

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

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

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

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

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

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

Crea una nueva serie y asigna datos a ella:

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

Por último, tendrás que hacer que sea visible:

surface.show();

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

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

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

Gráfico minimalista de una superficie 3D que muestra una superficie ondulada de color verde sobre un suelo cuadriculado

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 ninguna otra interacción. Puedes obtener más información familiarizándote con los ejemplos proporcionados, como el gráfico de superficie.

Véase también Q3DBars, Q3DScatter y Qt Data Visualization C++ Classes.

Documentación de propiedades

axisX : QValue3DAxis*

Esta propiedad contiene el eje X activo.

Funciones de acceso:

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

Señal de notificación:

void axisXChanged(QValue3DAxis *axis)

axisY : QValue3DAxis*

Esta propiedad contiene el eje Y activo.

Funciones de acceso:

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

Señal de notificación:

void axisYChanged(QValue3DAxis *axis)

axisZ : QValue3DAxis*

Esta propiedad determina el eje Z activo.

Funciones de acceso:

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

Señal de notificación:

void axisZChanged(QValue3DAxis *axis)

[since QtDataVisualization 1.2] flipHorizontalGrid : bool

Esta propiedad se mantiene tanto si la cuadrícula del eje horizontal se muestra en la parte superior del gráfico como si se muestra 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 utilizando la proyección ortográfica con una perspectiva de arriba hacia abajo.

Si se establece ` false`, la cuadrícula del eje horizontal y las etiquetas se dibujan sobre el fondo horizontal del gráfico. Si se establece ` 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`.

Esta enumeración se introdujo en QtDataVisualization 1.2.

Funciones de acceso:

bool flipHorizontalGrid() const
void setFlipHorizontalGrid(bool flip)

Señal de notificador:

void flipHorizontalGridChanged(bool flip)

[read-only] selectedSeries : QSurface3DSeries*

Esta propiedad contiene la serie seleccionada o el valor nulo.

Si selectionMode tiene establecido un valor « SelectionMultiSeries », esta propiedad contiene la serie a la que pertenece el punto seleccionado.

Funciones de acceso:

QSurface3DSeries *selectedSeries() const

Señal de notificación:

void selectedSeriesChanged(QSurface3DSeries *series)

Documentación de las funciones de miembro

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

Crea un nuevo gráfico de superficie en 3D con una ventana opcional de « parent » y una superficie « format ».

[virtual noexcept] Q3DSurface::~Q3DSurface()

Elimina el gráfico de superficie en 3D.

void Q3DSurface::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. El axis no debe ser nulo ni estar añadido a otro gráfico.

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

void Q3DSurface::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 QAbstract3DGraph::hasSeries().

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

Devuelve la lista de todos los ejes añadidos.

Véase también addAxis().

void Q3DSurface::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 por defecto 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 Q3DSurface::removeSeries(QSurface3DSeries *series)

Elimina el « series » del gráfico.

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

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

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

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

void Q3DSurface::setAxisX(QValue3DAxis *axis)

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 destruye si se establece explícitamente otro eje con la misma orientación.

Nota: Funciónde configuración para la propiedad axisX.

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

void Q3DSurface::setAxisY(QValue3DAxis *axis)

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.

Nota: Funciónde configuración para la propiedad axisY.

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

void Q3DSurface::setAxisZ(QValue3DAxis *axis)

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.

Nota: Funciónde configuración para la propiedad axisZ.

Véase también axisZ(), addAxis() y 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.