En esta página

Surface3DNode QML Type

Describe el uso del nodo «Gráfico de superficie 3D». Más información...

Import Statement: import QtGraphs
Inherits:

GraphsNode

Propiedades

Señales

Métodos

Descripción detallada

Este tipo permite a los desarrolladores representar un nodo de gráfico de superficie en 3D con ` Qt Quick`.

Para utilizar este tipo, tendrás que importar el módulo Qt Graphs:

import QtGraphs

A continuación, podrás utilizar Surface3DNode en tus archivos QML:

import QtQuick
import QtGraphs

View3D {
    width: 640
    height: 480

    Surface3DNode {
        width: parent.width
        height: parent.height
        Surface3DSeries {
            itemLabelFormat: "Pop density at (@xLabel N, @zLabel E): @yLabel"
            ItemModelSurfaceDataProxy {
                itemModel: dataModel
                // Mapping model roles to surface series rows, columns, and values.
                rowRole: "longitude"
                columnRole: "latitude"
                yPosRole: "pop_density"
            }
        }

        onTapped: {
            // Disable the default input handler
            unsetDefaultTapHandler()
            // Implement own custom event handler
            console.log("Custom tap event handler")
        }
    }
    ListModel {
        id: dataModel
        ListElement{ longitude: "20"; latitude: "10"; pop_density: "4.75"; }
        ListElement{ longitude: "21"; latitude: "10"; pop_density: "3.00"; }
        ListElement{ longitude: "22"; latitude: "10"; pop_density: "1.24"; }
        ListElement{ longitude: "23"; latitude: "10"; pop_density: "2.53"; }
        ListElement{ longitude: "20"; latitude: "11"; pop_density: "2.55"; }
        ListElement{ longitude: "21"; latitude: "11"; pop_density: "2.03"; }
        ListElement{ longitude: "22"; latitude: "11"; pop_density: "3.46"; }
        ListElement{ longitude: "23"; latitude: "11"; pop_density: "5.12"; }
        ListElement{ longitude: "20"; latitude: "12"; pop_density: "1.37"; }
        ListElement{ longitude: "21"; latitude: "12"; pop_density: "2.98"; }
        ListElement{ longitude: "22"; latitude: "12"; pop_density: "3.33"; }
        ListElement{ longitude: "23"; latitude: "12"; pop_density: "3.23"; }
        ListElement{ longitude: "20"; latitude: "13"; pop_density: "4.34"; }
        ListElement{ longitude: "21"; latitude: "13"; pop_density: "3.54"; }
        ListElement{ longitude: "22"; latitude: "13"; pop_density: "1.65"; }
        ListElement{ longitude: "23"; latitude: "13"; pop_density: "2.67"; }
    }
}

Véanse también las clases de C++ para 3D:Surface3DSeries, ItemModelSurfaceDataProxy, Bars3DNode, Scatter3DNode y Qt Graphs .

Documentación de propiedades

aspectRatio : real

La relación de escala del gráfico entre el eje más largo en el plano horizontal y el eje y. El valor predeterminado es 2.0.

Nota: Notiene ningún efecto sobre ` Bars3D`.

Véase también horizontalAspectRatio.

axisX : Value3DAxis

El eje X activo.

Si no se especifica ningún eje, se crea un eje temporal por defecto 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.

axisY : Value3DAxis

El eje Y activo.

Si no se especifica ningún eje, se crea un eje temporal por defecto 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.

axisZ : Value3DAxis

El eje Z activo.

Si no se especifica ningún eje, se crea un eje temporal por defecto 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.

customItemList : list<Custom3DItem>

La lista de elementos de tipo « Custom3DItem » añadidos al gráfico. El gráfico asume la propiedad de los elementos añadidos.

flipHorizontalGrid : bool

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 en 2D mediante 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`.

gridLineType : Graphs3D.GridLineType

Define si el tipo de líneas de cuadrícula es « Graphs3D.GridLineType.Shader » o « Graphs3D.GridLineType.Geometry ».

Este valor afecta a todas las líneas de cuadrícula.

Véase también Graphs3D.GridLineType.

horizontalAspectRatio : real

La relación de escala del gráfico entre el eje x y el eje z. El valor « 0.0 » indica que la escala se ajusta automáticamente en función de los rangos de los ejes. El valor por defecto es « 0.0 ».

Nota: Notiene ningún efecto sobre ` Bars3DNode`, que gestiona el escalado en el plano horizontal mediante las propiedades ` barThickness ` y ` barSpacing `. Los gráficos polares también ignoran esta propiedad.

Véase también aspectRatio, polar, Bars3DNode::barThickness y Bars3DNode::barSpacing.

labelMargin : real

Esta propiedad especifica el margen para la colocación de las etiquetas de los ejes.

Los valores negativos sitúan las etiquetas dentro del área de trazado, mientras que los valores positivos las sitúan fuera de ella. La rotación automática de las etiquetas se desactiva cuando el valor es negativo. El valor por defecto es 0.1

Véase también QAbstract3DAxis::labelAutoAngle.

locale : locale

Establece la configuración regional que se utiliza para dar formato a diversas etiquetas numéricas. El valor predeterminado es la configuración regional "C".

Véase también Value3DAxis::labelFormat.

margin : real

El valor absoluto que se utiliza para el espacio que queda entre el borde del área trazable del gráfico y el borde del fondo del gráfico.

Si el valor del margen es negativo, los márgenes se determinan automáticamente y pueden variar en función del tamaño de los elementos de la serie y del tipo de gráfico. El valor se interpreta como una fracción del rango del eje Y si las proporciones del gráfico no se han modificado con respecto a los valores predeterminados. El valor predeterminado es -1.0.

Nota: Establecer un margen para un gráfico de dispersión menor que el margen determinado automáticamente puede provocar que los elementos de dispersión situados en los bordes del gráfico se superpongan con el fondo del gráfico.

Nota: En los gráficos de dispersión y de superficie, si el margen es pequeño en comparación con el tamaño de las etiquetas de los ejes, las posiciones de las etiquetas de los extremos de los ejes se ajustan para evitar que se superpongan con las etiquetas de los extremos de los ejes adyacentes.

optimizationHint : Graphs3D.OptimizationHint

Especifica si se utiliza el modo predeterminado o el modo heredado para la optimización del renderizado.

El modo predeterminado utiliza el renderizado instanciado y ofrece todas las funciones con el mejor nivel de rendimiento en la mayoría de los sistemas. El modo estático optimiza el renderizado de gráficos y es ideal para conjuntos de datos grandes que no cambian. Es más lento con cambios dinámicos en los datos y rotaciones de elementos. La selección no está optimizada, por lo que no es recomendable utilizar el modo estático con conjuntos de datos masivos. El modo heredado renderiza todos los elementos del gráfico de forma individual, sin instanciación. Solo debe utilizarse si el modo predeterminado no funciona, es decir, si el sistema de destino no admite la instanciación. El valor predeterminado es Default.

Nota: En algunos entornos, es posible que los gráficos de gran tamaño que utilicen la optimización estática no se representen, ya que todos los elementos se representan mediante una única llamada de dibujo, y los distintos controladores gráficos admiten diferentes recuentos máximos de vértices por llamada. Esto suele ser un problema sobre todo en plataformas de 32 bits y OpenGL ES2. Para solucionar este problema, elige una malla de elementos con un número reducido de vértices o utiliza la malla de puntos.

Véase también Abstract3DSeries::mesh y Graphs3D.OptimizationHint.

polar : bool

Si se establece true, los ejes horizontales se transforman en ejes polares. El eje x se convierte en el eje angular y el eje z, en el eje radial. El modo polar no está disponible para los gráficos de barras.

El valor por defecto es false.

Véase también radialLabelOffset.

queriedGraphPosition : vector3d [read-only]

Esta propiedad de solo lectura contiene los últimos valores de posición del gráfico a lo largo de cada eje consultados mediante ` Scene3D::graphPositionQuery`. Los valores se normalizan para que estén comprendidos en el intervalo ` [-1, 1]`. Si la posición consultada se encuentra fuera de los límites del gráfico, los valores no reflejarán la posición real, sino que corresponderán a una posición indefinida fuera del intervalo ` [-1, 1]`. El valor permanecerá indefinido hasta que se realice una consulta.

No existe una única coordenada 3D correcta que se corresponda con una posición concreta de la pantalla, por lo que, para mantener la coherencia, las consultas siempre se realizan respecto a los lados interiores de un rectángulo invisible que rodea el gráfico.

Nota: Los gráficosde barras solo permiten consultar la posición del gráfico a la altura de la base del mismo, por lo que el valor de y es siempre cero en los gráficos de barras y las consultas válidas solo pueden realizarse en posiciones de la pantalla que contengan la base del gráfico.

Véase también Scene3D::graphPositionQuery.

radialLabelOffset : real

Esta propiedad especifica el desplazamiento horizontal normalizado de las etiquetas del eje polar radial. El valor 0.0 indica que las etiquetas deben dibujarse junto a la línea de la cuadrícula del eje angular correspondiente al ángulo 0. El valor 1.0 indica que las etiquetas se dibujan en su ubicación habitual, en el borde del fondo del gráfico. Esta propiedad se ignora si el valor de la propiedad «polar» es false. El valor por defecto es 1.0.

Véase también polar.

selectedElement : Graphs3D.ElementType [read-only]

El elemento seleccionado en el gráfico.

Esta propiedad se puede utilizar para consultar el tipo del elemento seleccionado. El tipo es válido hasta que se realice una nueva selección en el gráfico y se emita la señal « selectedElementChanged ».

La señal se puede utilizar, por ejemplo, para implementar un manejo de entradas personalizado, tal y como se muestra en el ejemplo «Axis Handling ».

Véase también selectedLabelIndex(), selectedAxis(), selectedCustomItemIndex(), selectedCustomItem(), Bars3DNode::selectedSeries, Scatter3DNode::selectedSeries, Scene3D::selectionQueryPosition y Graphs3D.ElementType.

selectedSeries : Surface3DSeries [read-only]

La serie seleccionada o nulo. Si el objeto « selectionMode » tiene activada la bandera « MultiSeries », esta propiedad contiene la serie a la que pertenece el punto seleccionado.

selectionMode : Graphs3D.SelectionMode

El modo de selección activo en el gráfico. Uno de los valores de la enumeración graphs3d.selectionflag.

seriesList : list<Surface3DSeries> [default]

Esta propiedad contiene las series del gráfico. Por defecto, esta propiedad contiene una lista vacía. Para establecer las series, utiliza la función addSeries() o defínelas como elementos secundarios del gráfico.

theme : GraphsTheme

El tema activo del gráfico.

Véase también GraphsTheme.

Documentación de Signal

axisXChanged(ValueAxis3D axis)

Esta señal se emite cuando axisX cambia a axis.

Nota: El controlador correspondiente es onAxisXChanged.

axisYChanged(ValueAxis3D axis)

Esta señal se emite cuando axisY cambia a axis.

Nota: El controlador correspondiente es onAxisYChanged.

axisZChanged(ValueAxis3D axis)

Esta señal se emite cuando axisZ cambia a axis.

Nota: El controlador correspondiente es onAxisZChanged.

flipHorizontalGridChanged(bool flip)

Esta señal se emite cuando flipHorizontalGrid cambia a flip.

Nota: El controlador correspondiente es onFlipHorizontalGridChanged.

selectedSeriesChanged(Surface3DSeries series)

Esta señal se emite cuando selectedSeries cambia a series.

Nota: El controlador correspondiente es onSelectedSeriesChanged.

Documentación del método

qsizetype addCustomItem(Custom3DItem item)

Añade un objeto ` Custom3DItem ` item al gráfico. El gráfico asume la propiedad del elemento añadido.

Devuelve el índice del elemento añadido si la adición se ha realizado correctamente, -1 si se intenta añadir un elemento nulo y el índice del elemento si se intenta añadir un elemento que ya está presente.

Véase también removeCustomItems(), removeCustomItem() y removeCustomItemAt().

void addSeries(Surface3DSeries series)

Añade el « series » al gráfico.

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

void clearSelection()

Borra la selección de todas las series asociadas.

void doPicking(QPoint point)

Realiza la selección utilizando las coordenadas de la vista de point en los elementos del gráfico, seleccionando el primer elemento con el que se produce el contacto. El manejo predeterminado de entradas lleva a cabo esta acción al recibir el evento onTapped.

Véase también selectedElement.

void doRayPicking(QVector3D origin, QVector3D direction)

Realiza la selección a partir de origin y en direction sobre los elementos del gráfico, eligiendo el primer elemento encontrado.

Véase también selectedElement.

bool hasSeries(Abstract3DSeries series)

Devuelve si el objeto « series » ya se ha añadido al gráfico.

void releaseCustomItem(Custom3DItem item)

Recupera la propiedad de « item » y elimina « item » del gráfico.

Nota: Si se vuelve a añadir el mismo elemento al gráfico, es necesario volver a establecer el archivo de textura.

Véase también Custom3DItem::textureFile.

void removeCustomItem(Custom3DItem item)

Elimina el « item » personalizado. Borra los recursos que se le habían asignado.

void removeCustomItemAt(vector3d position)

Elimina todos los elementos personalizados de position. Borra los recursos que se les han asignado.

void removeCustomItems()

Elimina todos los elementos personalizados. Borra los recursos que se les habían asignado.

void removeSeries(Surface3DSeries series)

Elimina el « series » del gráfico.

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

Abstract3DAxis selectedAxis()

Se puede utilizar para obtener el eje seleccionado tras recibir una señal « selectedElementChanged » con cualquier tipo de etiqueta. La selección es válida hasta la siguiente señal « selectedElementChanged ».

Devuelve el eje seleccionado o nulo.

Véase también selectedElement.

Custom3DItem selectedCustomItem()

Se puede utilizar para obtener el elemento personalizado seleccionado tras recibir una señal « selectedElementChanged » de tipo « ElementType.CustomItem ». La propiedad del elemento sigue correspondiendo al gráfico. La selección es válida hasta la siguiente señal « selectedElementChanged ».

Devuelve el elemento personalizado seleccionado o «null».

Véase también « selectedElement ».

qsizetype selectedCustomItemIndex()

Se puede utilizar para consultar el índice del elemento personalizado seleccionado tras recibir una señal « selectedElementChanged » de tipo « ElementType.CustomItem ». La selección es válida hasta la siguiente señal « selectedElementChanged ».

Devuelve el índice del elemento personalizado seleccionado o -1.

Véase también selectedElement.

int selectedLabelIndex()

Se puede utilizar para consultar el índice de la etiqueta seleccionada tras recibir una señal « selectedElementChanged » con cualquier tipo de etiqueta. La selección es válida hasta la siguiente señal « selectedElementChanged ».

Devuelve el índice de la etiqueta seleccionada o -1.

Véase también selectedElement.

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