En esta página

Galería de gráficos de superficie

Galería con tres formas diferentes de utilizar un gráfico de Surface3D.

La Galería de gráficos de superficie muestra tres funciones personalizadas diferentes con gráficos de « Surface3D ». Estas funciones cuentan con sus propias pestañas en la aplicación.

Las siguientes secciones se centran únicamente en esas funciones y omiten la explicación de la funcionalidad básica; para obtener documentación más detallada con ejemplos en QML, consulta «Gráfico de dispersión sencillo».

Superficie de mapa de altitud en 3D con controles de terreno y cuadrícula

Ejecución del ejemplo

Puedes ejecutar el ejemplo desde:

Mapa de altitud

En la pestaña « Height Map », genera un gráfico de superficie a partir de datos de altura. Los datos utilizados son un mapa de altitud del monte Ruapehu y del monte Ngauruhoe, en Nueva Zelanda.

Añadir datos al gráfico

Los datos se configuran mediante « HeightMapSurfaceDataProxy », que lee la información de altura a partir de una imagen de mapa de altitud. El propio proxy se encuentra en un « Surface3DSeries ». Dentro del « HeightMapSurfaceDataProxy », la propiedad « heightMapFile » especifica el archivo de imagen que contiene los datos de altura. Las propiedades de valor del proxy definen los valores mínimo y máximo de la superficie, la anchura, la profundidad y la altura. Los valores de z y x corresponden a la latitud y la longitud, aproximadamente en la posición real, y el de y está expresado en metros.

Nota: La relación de aspecto del gráfico no se ajusta a la escala real, sino que, en su lugar, la altura se ha exagerado.

Surface3DSeries {
    id: heightSeries
    shading: Surface3DSeries.Shading.Smooth
    drawMode: Surface3DSeries.DrawSurface

    HeightMapSurfaceDataProxy {
        heightMapFile: "://qml/surfacegallery/heightmap.png"
        // We don't want the default data values set by heightmap proxy, but use
        // actual coordinate and height values instead
        autoScaleY: true
        minYValue: 740
        maxYValue: 2787
        minZValue: -374 // ~ -39.374411"N
        maxZValue: -116 // ~ -39.115971"N
        minXValue: 472  // ~ 175.471767"E
        maxXValue: 781  // ~ 175.780758"E
    }

    onDrawModeChanged: heightMapView.checkState()
}
Visualización de los datos

En main.qml, configura el elemento Surface3D para mostrar los datos.

En primer lugar, define el degradado personalizado que se utilizará para la superficie. Establece los colores desde la posición 0,0 hasta 1,0 con «Gradient», con dos paradas adicionales para que el gráfico resulte más llamativo:

Gradient {
    id: surfaceGradient
    GradientStop { position: 0.0; color: "darkgreen"}
    GradientStop { position: 0.15; color: "darkslategray" }
    GradientStop { position: 0.7; color: "peru" }
    GradientStop { position: 1.0; color: "white" }
}

Establece este elemento en la propiedad « baseGradients » del elemento « theme » utilizado en Surface3D:

theme: GraphsTheme {
    colorScheme: GraphsTheme.ColorScheme.Dark
    labelFont.family: "STCaiyun"
    labelFont.pointSize: 35
    colorStyle: GraphsTheme.ColorStyle.ObjectGradient
    baseGradients: [surfaceGradient] // Use the custom gradient
}

Utiliza los botones para controlar otras funciones de « Surface3D ».

El primer botón activa y desactiva la cuadrícula de la superficie. El modo de dibujo no se puede borrar por completo; por lo tanto, a menos que la propia superficie esté visible, la cuadrícula de la superficie no se puede ocultar:

onClicked: {
    if (heightSeries.drawMode & Surface3DSeries.DrawWireframe)
        heightSeries.drawMode &= ~Surface3DSeries.DrawWireframe;
    else
        heightSeries.drawMode |= Surface3DSeries.DrawWireframe;
}

El segundo establece el color de la cuadrícula de la superficie:

onClicked: {
    if (Qt.colorEqual(heightSeries.wireframeColor, "#000000")) {
        heightSeries.wireframeColor = "red";
        text = "Black surface\ngrid color";
    } else {
        heightSeries.wireframeColor = "black";
        text = "Red surface\ngrid color";
    }
}

El tercero activa o desactiva la superficie en el modo de dibujo de superficie. El modo de dibujo no se puede borrar por completo, por lo que, a menos que la cuadrícula de la superficie esté visible, la superficie en sí no se puede ocultar:

onClicked: {
    if (heightSeries.drawMode & Surface3DSeries.DrawSurface)
        heightSeries.drawMode &= ~Surface3DSeries.DrawSurface;
    else
        heightSeries.drawMode |= Surface3DSeries.DrawSurface;
}

El cuarto establece el modo de sombreado. Si estás ejecutando el ejemplo en un sistema OpenGL ES, el sombreado plano no está disponible:

onClicked: {
    if (heightSeries.shading === Surface3DSeries.Shading.Flat) {
        heightSeries.shading = Surface3DSeries.Shading.Smooth;
        text = "Show\nFlat"
    } else {
        heightSeries.shading = Surface3DSeries.Shading.Flat;
        text = "Show\nSmooth"
    }
}

Los botones restantes controlan las características del fondo del gráfico.

Espectrograma

En la pestaña « Spectrogram », se muestran espectrogramas polares y cartesianos y se utiliza la proyección ortográfica para visualizarlos en 2D.

Un espectrograma es un gráfico de superficie con un gradiente de rango que se utiliza para resaltar los diferentes valores. Normalmente, los espectrogramas se muestran como superficies bidimensionales, que se simulan mediante una vista ortográfica desde arriba del gráfico. Para reforzar el efecto 2D, desactiva la rotación del gráfico mediante el ratón o el tacto cuando estés en modo ortográfico.

Creación de un espectrograma

Para crear un espectrograma en 2D, defina un elemento ` Surface3D ` con los datos indicados en ` Surface3DSeries ` y un ` ItemModelSurfaceDataProxy`:

Surface3D {
    id: surfaceGraph
    anchors.fill: parent

    // Don't show specular spotlight as we don't want it to distort the colors
    lightStrength: 0.0
    ambientLightStrength: 1.0

    Surface3DSeries {
        id: surfaceSeries
        shading: Surface3DSeries.Shading.Smooth
        drawMode: Surface3DSeries.DrawSurface
        baseGradient: surfaceGradient
        colorStyle: GraphsTheme.ColorStyle.RangeGradient
        itemLabelFormat: "(@xLabel, @zLabel): @yLabel"

        ItemModelSurfaceDataProxy {
            itemModel: surfaceData.model
            rowRole: "radius"
            columnRole: "angle"
            yPosRole: "value"
        }
    }

Las propiedades clave para habilitar el efecto 2D son « orthoProjection » y « cameraPreset ». Elimina la perspectiva habilitando la proyección ortográfica para el gráfico y la dimensión Y visualizando el gráfico directamente desde arriba:

// Remove the perspective and view the graph from top down to achieve 2D effect
orthoProjection: true
cameraPreset: Graphs3D.CameraPreset.DirectlyAbove

Dado que este punto de vista hace que la cuadrícula del eje horizontal quede prácticamente oculta por la superficie, invierte la cuadrícula horizontal para que se dibuje sobre el gráfico:

flipHorizontalGrid: true
Espectrograma polar

Dependiendo de los datos, a veces resulta más natural utilizar un gráfico polar en lugar de uno cartesiano. Esto es posible gracias a la propiedad polar.

Añade un botón para alternar entre los modos polar y cartesiano:

Button {
    id: polarToggle
    anchors.margins: 5
    anchors.left: parent.left
    anchors.top: parent.top
    width: spectrogramView.buttonWidth // Calculated elsewhere based on screen orientation
    text: "Switch to\n" + (surfaceGraph.polar ? "cartesian" : "polar")
    onClicked: surfaceGraph.polar = !surfaceGraph.polar;
}

En el modo polar, el eje X se convierte en el eje polar angular, y el eje Z se convierte en un eje polar radial. Los puntos de la superficie se recalculan según los nuevos ejes.

Las etiquetas del eje radial se dibujan fuera del gráfico de forma predeterminada. Para dibujarlas justo al lado del eje angular de 0 grados dentro del gráfico, define solo un pequeño desplazamiento para ellas:

radialLabelOffset: 0.01

Para reforzar el efecto 2D, desactiva la rotación del gráfico en modo ortográfico sobrescribiendo el controlador de entrada predeterminado con uno personalizado, que alterna automáticamente la propiedad ` rotationEnabled ` en función del modo de proyección:

rotationEnabled: !surfaceGraph.orthoProjection

Osciloscopio

En la pestaña « Oscilloscope », combina C++ y QML en una aplicación y muestra datos que cambian dinámicamente.

Fuente de datos en C++

Los proxies basados en modelos de elementos son adecuados para gráficos sencillos o estáticos, pero utiliza proxies básicos para obtener el mejor rendimiento al mostrar datos que cambian en tiempo real. Estos no son compatibles con QML, ya que los elementos de datos que almacenan no heredan de QObject y, por lo tanto, no se pueden manipular directamente desde el código QML. Para superar esta limitación, implementa una clase sencilla de tipo « DataSource » en C++ para rellenar el proxy de datos de la serie.

Crea una clase ` DataSource ` que proporcione dos métodos que puedan invocarse desde QML:

class DataSource : public QObject
{
    Q_OBJECT
    ...
Q_INVOKABLE void generateData(int cacheCount,
                              int rowCount,
                              int columnCount,
                              float xMin,
                              float xMax,
                              float yMin,
                              float yMax,
                              float zMin,
                              float zMax);

Q_INVOKABLE void update(QSurface3DSeries *series);

El primer método, ` generateData()`, crea una caché de datos simulados de osciloscopio para su visualización. Los datos se almacenan en caché en un formato que ` QSurfaceDataProxy ` acepta:

// Populate caches
for (int i = 0; i < cacheCount; i++) {
    QSurfaceDataArray &cache = m_data[i];
    float cacheXAdjustment = cacheStep * i;
    float cacheIndexAdjustment = cacheIndexStep * i;
    for (int j = 0; j < rowCount; j++) {
        QSurfaceDataRow &row = cache[j];
        float rowMod = (float(j)) / float(rowCount);
        float yRangeMod = yRange * rowMod;
        float zRangeMod = zRange * rowMod;
        float z = zRangeMod + zMin;
        qreal waveAngleMul = M_PI * M_PI * rowMod;
        float waveMul = yRangeMod * 0.2f;
        for (int k = 0; k < columnCount; k++) {
            float colMod = (float(k)) / float(columnCount);
            float xRangeMod = xRange * colMod;
            float x = xRangeMod + xMin + cacheXAdjustment;
            float colWave = float(qSin((2.0 * M_PI * colMod) - (1.0 / 2.0 * M_PI)) + 1.0);
            float y = (colWave * ((float(qSin(waveAngleMul * colMod) + 1.0)))) * waveMul
                      + QRandomGenerator::global()->bounded(0.15f) * yRangeMod;

            int index = k + cacheIndexAdjustment;
            if (index >= columnCount) {
                // Wrap over
                index -= columnCount;
                x -= xRange;
            }
            row[index] = QSurfaceDataItem(x, y, z);
        }
    }
}

El segundo método, ` update()`, copia un conjunto de los datos almacenados en caché a otro array, que se asigna a la serie llamando a ` QSurfaceDataProxy::resetArray()`. Para minimizar la sobrecarga, reutiliza el mismo array si sus dimensiones no han cambiado:

// Each iteration uses data from a different cached array
m_index++;
if (m_index > m_data.count() - 1)
    m_index = 0;

QSurfaceDataArray array = m_data.at(m_index);
int newRowCount = array.size();
int newColumnCount = array.at(0).size();

// If the first time or the dimensions of the cache array have changed,
// reconstruct the reset array
if (m_resetArray.isEmpty() || series->dataProxy()->rowCount() != newRowCount
    || series->dataProxy()->columnCount() != newColumnCount) {
    m_resetArray.clear();
    m_resetArray.reserve(newRowCount);
    for (int i = 0; i < newRowCount; i++)
        m_resetArray.append(QSurfaceDataRow(newColumnCount));
}

// Copy items from our cache to the reset array
for (int i = 0; i < newRowCount; i++) {
    const QSurfaceDataRow &sourceRow = array.at(i);
    QSurfaceDataRow &row = m_resetArray[i];
    for (int j = 0; j < newColumnCount; j++)
        row[j].setPosition(sourceRow.at(j).position());
}

// Notify the proxy that data has changed
series->dataProxy()->resetArray(m_resetArray);

Aunque estemos operando sobre el puntero a la matriz previamente asignado a la serie, sigue siendo necesario llamar a QSurfaceDataProxy::resetArray() tras modificar los datos que contiene para que el gráfico los represente.

Para poder acceder a los métodos de DataSource desde QML, expón la fuente de datos configurando DataSource como un QML_ELEMENT:

class DataSource : public QObject
{
    Q_OBJECT
    QML_ELEMENT

Además, decláralo como un módulo QML en el archivo CMakeLists.txt:

qt6_add_qml_module(surfacegallery
    URI SurfaceGallery
    VERSION 1.0
    NO_RESOURCE_TARGET_PATH
    SOURCES
        datasource.cpp datasource.h
    ...
)

Para utilizar punteros QSurface3DSeries como parámetros de los métodos de la clase DataSource en todos los entornos y compilaciones, asegúrate de que el metatipo esté registrado:

qRegisterMetaType<QSurface3DSeries *>();
Aplicación QML

Para utilizar el ` DataSource`, importa el módulo QML y crea una instancia de ` DataSource ` para utilizarla:

import SurfaceGalleryExample
...
DataSource {
    id: dataSource
}

Define un gráfico « Surface3D » y asígnale un « Surface3DSeries »:

Surface3D {
    id: surfaceGraph
    anchors.fill: parent

    Surface3DSeries {
        id: surfaceSeries
        drawMode: Surface3DSeries.DrawSurfaceAndWireframe
        itemLabelFormat: "@xLabel, @zLabel: @yLabel"

No especifiques un proxy para el ` Surface3DSeries ` que adjuntes al gráfico. De este modo, la serie utilizará el ` QSurfaceDataProxy` predeterminado.

Oculta la etiqueta del elemento con « itemLabelVisible ». Con datos dinámicos y que cambian rápidamente, una etiqueta de selección flotante resultaría molesta y difícil de leer.

itemLabelVisible: false

Puedes mostrar la información del elemento seleccionado en un elemento « Text » en lugar de la etiqueta flotante predeterminada situada encima del puntero de selección:

onItemLabelChanged: {
    if (surfaceSeries.selectedPoint == surfaceSeries.invalidSelectionPosition)
        selectionText.text = "No selection";
    else
        selectionText.text = surfaceSeries.itemLabel;
}

Inicialice la caché de ` DataSource ` cuando el gráfico esté completo llamando a la función auxiliar ` generateData()`, que a su vez llama al método del mismo nombre en ` DataSource`:

Component.onCompleted: oscilloscopeView.generateData();
...
function generateData() {
    dataSource.generateData(oscilloscopeView.sampleCache, oscilloscopeView.sampleRows,
                            oscilloscopeView.sampleColumns,
                            surfaceGraph.axisX.min, surfaceGraph.axisX.max,
                            surfaceGraph.axisY.min, surfaceGraph.axisY.max,
                            surfaceGraph.axisZ.min, surfaceGraph.axisZ.max);
}

Para activar las actualizaciones de los datos, define un ` Timer`, que llama al método ` update() ` de ` DataSource ` a los intervalos solicitados:

Timer {
    id: refreshTimer
    interval: 1000 / frequencySlider.value
    running: true
    repeat: true
    onTriggered: dataSource.update(surfaceSeries);
}
Activación del renderizado directo

Dado que esta aplicación puede manejar una gran cantidad de datos que cambian rápidamente, utiliza el modo de renderizado directo para mejorar el rendimiento. Para habilitar el suavizado en este modo, cambia el formato de superficie de la ventana de la aplicación. El formato predeterminado utilizado por QQuickView no admite el suavizado. Utiliza la función de utilidad proporcionada para cambiar el formato de superficie en main.cpp:

#include <QtGraphs/qutils.h>
...
// Enable antialiasing in direct rendering mode
viewer.setFormat(QQuick3D::idealSurfaceFormat(8));

Contenido del ejemplo

Proyecto de ejemplo en code.qt.io

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