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

Ejecución del ejemplo
Puedes ejecutar el ejemplo desde:
- Qt Creator
Abre el modo « Welcome » y selecciona el ejemplo en Examples. Para obtener más información, consulta Qt Creator: Tutorial: Compilar y ejecutar.
- Qt Extension for Visual Studio Code
Ejecute el comando « Qt: Open Qt examples » desde Command Palette y seleccione el ejemplo de la lista. Para obtener más información, consulte Qt Extension for Visual Studio Code: Tutorial: Compilar y ejecutar.
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.DirectlyAboveDado 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: trueEspectrograma 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.01Para 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.orthoProjectionOsciloscopio
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_ELEMENTAdemá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: falsePuedes 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
© 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.