Galería de gráficos de superficie
Galería con tres formas diferentes de utilizar un gráfico Surface3D.
La Galería de gráficos de superficie muestra tres funciones personalizadas diferentes con gráficos 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 el 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 altura. El propio proxy está contenido en un Surface3DSeries. Dentro de 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 anchura, la profundidad y la altura de la superficie. Los valores de « z » y « x » corresponden a la latitud y la longitud, aproximadamente en la posición real, y la « y » está expresada en metros.
Nota: La relación de aspecto del gráfico no se ajusta a la escala real, sino que, en su lugar, se exagera la altura.
Surface3DSeries {
id: heightSeries
flatShadingEnabled: false
drawMode: Surface3DSeries.DrawSurface
HeightMapSurfaceDataProxy {
heightMapFile: "://qml/qmlsurfacegallery/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 visualizar 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 ColorGradient, con dos paradas adicionales para que el gráfico resulte más vivo:
ColorGradient {
id: surfaceGradient
ColorGradientStop { position: 0.0; color: "darkgreen"}
ColorGradientStop { position: 0.15; color: "darkslategray" }
ColorGradientStop { position: 0.7; color: "peru" }
ColorGradientStop { position: 1.0; color: "white" }
}Establece este elemento en la propiedad « baseGradients » del objeto « theme » utilizado en Surface3D:
theme: Theme3D {
type: Theme3D.ThemeStoneMoss
font.family: "STCaiyun"
font.pointSize: 35
colorStyle: Theme3D.ColorStyleRangeGradient
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 que, a menos que la propia superficie sea 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 sea 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.flatShadingEnabled) {
heightSeries.flatShadingEnabled = false;
text = "Show\nFlat"
} else {
heightSeries.flatShadingEnabled = true;
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 representarlos en 2D.
Un espectrograma es un gráfico de superficie con un degradado de rango que se utiliza para resaltar los diferentes valores. Normalmente, los espectrogramas se muestran como superficies bidimensionales, lo que se simula con una vista ortográfica de arriba hacia abajo del gráfico. Para reforzar el efecto 2D, desactiva la rotación del gráfico mediante el ratón o la pantalla táctil cuando estés en el modo ortográfico.
Creación de un espectrograma
Para crear un espectrograma en 2D, define un elemento «Surface3D» con los datos proporcionados en «Surface3DSeries» mediante un «ItemModelSurfaceDataProxy»:
Surface3D {
id: surfaceGraph
anchors.fill: parent
Surface3DSeries {
id: surfaceSeries
flatShadingEnabled: false
drawMode: Surface3DSeries.DrawSurface
baseGradient: surfaceGradient
colorStyle: Theme3D.ColorStyleRangeGradient
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 ` scene.activeCamera.cameraPreset`. Elimina la perspectiva habilitando la proyección ortográfica para el gráfico, y la dimensión Y al visualizar el gráfico directamente desde arriba:
// Remove the perspective and view the graph from top down to achieve 2D effect
orthoProjection: true
scene.activeCamera.cameraPreset: Camera3D.CameraPresetDirectlyAboveDado que este punto de vista hace que la superficie oculte en su mayor parte la cuadrícula del eje horizontal, 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 se puede hacer mediante 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 por uno personalizado, que alterna automáticamente la propiedad ` rotationEnabled ` en función del modo de proyección:
inputHandler: TouchInputHandler3D {
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 el modelo 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 pueden manipularse 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
auto *generator = QRandomGenerator::global();
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 rowColWaveAngleMul = M_PI * M_PI * rowMod;
float rowColWaveMul = 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(rowColWaveAngleMul * colMod) + 1.0))))
* rowColWaveMul
+ generator->bounded(0.15f) * yRangeMod;
int index = k + cacheIndexAdjustment;
if (index >= columnCount) {
// Wrap over
index -= columnCount;
x -= xRange;
}
row[index] = QVector3D(x, y, z);
}
}
}El segundo método, ` update()`, copia un conjunto de los datos almacenados en caché a otro array, que se asigna al proxy de datos de 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
if (++m_index >= m_data.size())
m_index = 0;
const 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 || series->dataProxy()->rowCount() != newRowCount
|| series->dataProxy()->columnCount() != newColumnCount) {
m_resetArray = new QSurfaceDataArray();
m_resetArray->reserve(newRowCount);
for (int i = 0; i < newRowCount; ++i)
m_resetArray->append(new 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];
std::copy(sourceRow.cbegin(), sourceRow.cend(), row.begin());
}
// Notify the proxy that data has changed
series->dataProxy()->resetArray(m_resetArray);Aunque estemos operando sobre el puntero de la matriz previamente asignado al proxy, es 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, exponga la fuente de datos convirtiendo DataSource en 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(qmlsurfacegallery
URI SurfaceGallery
VERSION 1.0
NO_RESOURCE_TARGET_PATH
SOURCES
datasource.cpp datasource.h
...
)Para utilizar punteros a `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 ` DataSource`, importa el módulo QML y crea una instancia de ` DataSource ` que se vaya a utilizar:
import SurfaceGallery
...
DataSource {
id: dataSource
}Define un gráfico Surface3D y asígnale una Surface3DSeries:
Surface3D {
id: surfaceGraph
anchors.fill: parent
Surface3DSeries {
id: surfaceSeries
drawMode: Surface3DSeries.DrawSurfaceAndWireframe
itemLabelFormat: "@xLabel, @zLabel: @yLabel"No especifiques un proxy para la 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 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 <QtDataVisualization/qutils.h>
...
// Enable antialiasing in direct rendering mode
viewer.setFormat(qDefaultSurfaceFormat(true));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.