En esta página

QCustom3DItem Class

La clase QCustom3DItem añade un elemento personalizado a un gráfico. Más información...

Encabezado: #include <QCustom3DItem>
CMake: find_package(Qt6 REQUIRED COMPONENTS Graphs)
target_link_libraries(mytarget PRIVATE Qt6::Graphs)
qmake: QT += graphs
En QML: Custom3DItem
Heredado de: QObject
Heredado por:

QCustom3DLabel y QCustom3DVolume

Propiedades

Funciones públicas

QCustom3DItem(QObject *parent = nullptr)
QCustom3DItem(const QString &meshFile, QVector3D position, QVector3D scaling, const QQuaternion &rotation, const QImage &texture, QObject *parent = nullptr)
virtual ~QCustom3DItem() override
bool isPositionAbsolute() const
bool isRotationAbsolute() const
bool isScalingAbsolute() const
bool isShadowCasting() const
bool isVisible() const
QString meshFile() const
QVector3D position() const
QQuaternion rotation()
QVector3D scaling() const
void setMeshFile(const QString &meshFile)
void setPosition(QVector3D position)
void setPositionAbsolute(bool positionAbsolute)
void setRotation(const QQuaternion &rotation)
void setRotationAbsolute(bool rotationAbsolute)
void setRotationAxisAndAngle(QVector3D axis, float angle)
void setScaling(QVector3D scaling)
void setScalingAbsolute(bool scalingAbsolute)
void setShadowCasting(bool enabled)
void setTextureFile(const QString &textureFile)
void setTextureImage(const QImage &textureImage)
void setVisible(bool visible)
QString textureFile() const

Señales

void meshFileChanged(const QString &meshFile)
void positionAbsoluteChanged(bool positionAbsolute)
void positionChanged(QVector3D position)
void rotationAbsoluteChanged(bool newRotationAbsolute)
void rotationChanged(const QQuaternion &rotation)
void scalingAbsoluteChanged(bool scalingAbsolute)
void scalingChanged(QVector3D scaling)
void shadowCastingChanged(bool shadowCasting)
void textureFileChanged(const QString &textureFile)
void visibleChanged(bool visible)

Descripción detallada

Un elemento personalizado tiene una malla, una posición, una escala y una rotación personalizadas, además de una textura opcional.

Véase también ` Q3DGraphsWidgetItem::addCustomItem()`.

Documentación de propiedades

meshFile : QString

Esta propiedad contiene el nombre del archivo de malla del elemento.

El elemento del archivo debe estar en formato de malla. Los demás tipos se pueden convertir mediante la herramienta de importación de activos de Balsam. Se recomienda que los archivos de malla incluyan vértices, normales y coordenadas UV.

Funciones de acceso:

QString meshFile() const
void setMeshFile(const QString &meshFile)

Señal de notificación:

void meshFileChanged(const QString &meshFile)

position : QVector3D

Esta propiedad almacena la posición del elemento como un objeto ` QVector3D`.

El valor por defecto es ` QVector3D(0.0, 0.0, 0.0)`.

La posición del elemento se especifica en coordenadas de datos o en coordenadas absolutas, dependiendo de la propiedad « positionAbsolute ». Cuando se utilizan coordenadas absolutas, los valores comprendidos entre -1.0...1.0 se encuentran dentro de los rangos de los ejes.

Nota: Los elementos situados fuera de cualquier rango de eje no se representan si positionAbsolute es false, a menos que el elemento sea un QCustom3DVolume que quedaría parcialmente visible y scalingAbsolute también sea false. En ese caso, se representará la parte visible del volumen.

Funciones de acceso:

QVector3D position() const
void setPosition(QVector3D position)

Señal de notificación:

void positionChanged(QVector3D position)

Véase también positionAbsolute.

positionAbsolute : bool

Esta propiedad determina si la posición de los elementos se va a gestionar en coordenadas de datos o en coordenadas absolutas.

El valor por defecto es « false ». Los elementos con coordenadas absolutas siempre se representarán, mientras que los elementos con coordenadas de datos solo se representarán si se encuentran dentro de los rangos de los ejes.

Funciones de acceso:

bool isPositionAbsolute() const
void setPositionAbsolute(bool positionAbsolute)

Señal de notificación:

void positionAbsoluteChanged(bool positionAbsolute)

Véase también position.

rotation : QQuaternion

Esta propiedad almacena la rotación del elemento como un objeto de tipo ` QQuaternion`.

El valor por defecto es « QQuaternion(0.0, 0.0, 0.0, 0.0) ».

Funciones de acceso:

QQuaternion rotation()
void setRotation(const QQuaternion &rotation)

Señal de notificador:

void rotationChanged(const QQuaternion &rotation)

[since 6.11] rotationAbsolute : bool

Esta propiedad determina si la rotación de los elementos se gestionará en coordenadas del eje de datos o en coordenadas absolutas.

Define si la rotación de los elementos se gestionará en función de los valores de datos o en valores absolutos. El valor por defecto es « true ». Los elementos con rotación absoluta girarán según las coordenadas por defecto, independientemente del eje. Los elementos con rotación basada en datos girarán según las coordenadas del eje.

Esta enumeración se introdujo en Qt 6.11.

Funciones de acceso:

bool isRotationAbsolute() const
void setRotationAbsolute(bool rotationAbsolute)

Señal de notificador:

void rotationAbsoluteChanged(bool newRotationAbsolute)

Véase también rotation.

scaling : QVector3D

Esta propiedad almacena el escalado del elemento como un objeto de tipo « QVector3D ».

El valor predeterminado es « QVector3D(0.1, 0.1, 0.1) ».

El escalado de los elementos se realiza en valores de datos o en valores absolutos, dependiendo de la propiedad « scalingAbsolute ». El vector por defecto, interpretado como valores absolutos, establece el elemento en el 10 % de la altura del gráfico, siempre que la malla del elemento esté normalizada y las relaciones de aspecto del gráfico no se hayan modificado con respecto a los valores por defecto.

Nota: En Qt 6.8 se asumía erróneamente que los modelos se escalaban a un tamaño de 1 (-0,5...0,5) de forma predeterminada, cuando en realidad se escalan a un tamaño de 2 (-1...1). Debido a esto, todos los elementos personalizados a partir de Qt 6.9 tienen el doble de tamaño en comparación con Qt 6.8

Funciones de acceso:

QVector3D scaling() const
void setScaling(QVector3D scaling)

Señal del notificador:

void scalingChanged(QVector3D scaling)

Véase también scalingAbsolute.

scalingAbsolute : bool

Esta propiedad determina si el escalado de los elementos se gestionará mediante valores de datos o mediante valores absolutos.

El valor predeterminado es « true ».

Los elementos con escalado absoluto se representarán con el mismo tamaño, independientemente de los rangos de los ejes. Los elementos con escalado de datos cambiarán su tamaño aparente en función de los rangos de los ejes. Si positionAbsolute es true, esta propiedad se ignora y el escalado se interpreta como un valor absoluto. Si el elemento tiene rotación, el escalado de datos se calcula sobre el elemento sin rotar. Del mismo modo, para los elementos QCustom3DVolume, el recorte de rango se calcula sobre el elemento sin rotar.

Nota: Solo se admite el escalado absoluto para elementos de tipo « QCustom3DLabel » o para elementos personalizados utilizados en gráficos de tipo « polar ».

Nota: La malla del elemento personalizado debe normalizarse al rango [-1 ,1], o el escalado de datos no será preciso.

Funciones de acceso:

bool isScalingAbsolute() const
void setScalingAbsolute(bool scalingAbsolute)

Señal de notificación:

void scalingAbsoluteChanged(bool scalingAbsolute)

Véase también scaling y positionAbsolute.

shadowCasting : bool

Esta propiedad determina si se habilita la proyección de sombras para el elemento.

El valor por defecto es « true ». Si se establece en « false », el elemento no proyecta sombras independientemente del valor de «Q3DGraphsWidgetItem::ShadowQuality».

Funciones de acceso:

bool isShadowCasting() const
void setShadowCasting(bool enabled)

Señal del notificador:

void shadowCastingChanged(bool shadowCasting)

textureFile : QString

Esta propiedad contiene el nombre del archivo de textura del elemento.

Si ni esta propiedad ni la imagen de textura están definidas, se utilizará una textura gris lisa.

Nota: Para ahorrar memoria, el objeto « QImage » cargado desde el archivo se borra una vez creada la textura.

Funciones de acceso:

QString textureFile() const
void setTextureFile(const QString &textureFile)

Señal de notificación:

void textureFileChanged(const QString &textureFile)

visible : bool

Esta propiedad determina la visibilidad del elemento.

El valor predeterminado es « true ».

Funciones de acceso:

bool isVisible() const
void setVisible(bool visible)

Señal del notificador:

void visibleChanged(bool visible)

Documentación de la función miembro

[explicit] QCustom3DItem::QCustom3DItem(QObject *parent = nullptr)

Crea un elemento 3D personalizado con el ` parent` especificado.

[explicit] QCustom3DItem::QCustom3DItem(const QString &meshFile, QVector3D position, QVector3D scaling, const QQuaternion &rotation, const QImage &texture, QObject *parent = nullptr)

Crea un elemento 3D personalizado con los valores especificados para « meshFile », « position », « scaling », « rotation » y « texture », así como con la imagen y el valor opcional « parent ».

[override virtual noexcept] QCustom3DItem::~QCustom3DItem()

Elimina el elemento 3D personalizado.

[invokable] void QCustom3DItem::setRotationAxisAndAngle(QVector3D axis, float angle)

Una función de ayuda para construir el cuaternión de rotación a partir de axis y angle.

Nota: Esta función se puede invocar a través del sistema de metaobjetos y desde QML. Véase Q_INVOKABLE.

Véase también rotation.

void QCustom3DItem::setTextureImage(const QImage &textureImage)

Establece el valor de « textureImage » como un « QImage » para el elemento. La textura predeterminada es gris liso.

Nota: Para ahorrar memoria, el ` QImage ` proporcionado se borra una vez creada la textura.

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