En esta página

QCustom3DVolume Class

La clase QCustom3DVolume añade un objeto renderizado en 3D a un gráfico. Más información...

Encabezado: #include <QCustom3DVolume>
CMake: find_package(Qt6 REQUIRED COMPONENTS DataVisualization)
target_link_libraries(mytarget PRIVATE Qt6::DataVisualization)
qmake: QT += datavisualization
Desde: QtDataVisualization 1.2
En QML: Custom3DVolume
Heredado de: QCustom3DItem
Estado: Obsoleta

Esta clase está obsoleta. Se desaconseja encarecidamente su uso en código nuevo.

Propiedades

Funciones públicas

QCustom3DVolume(QObject *parent = nullptr)
QCustom3DVolume(const QVector3D &position, const QVector3D &scaling, const QQuaternion &rotation, int textureWidth, int textureHeight, int textureDepth, QList<uchar> *textureData, QImage::Format textureFormat, const QList<QRgb> &colorTable, QObject *parent = nullptr)
virtual ~QCustom3DVolume()
float alphaMultiplier() const
QList<QRgb> colorTable() const
QList<uchar> *createTextureData(const QList<QImage *> &images)
bool drawSliceFrames() const
bool drawSlices() const
bool preserveOpacity() const
QImage renderSlice(Qt::Axis axis, int index)
void setAlphaMultiplier(float mult)
void setColorTable(const QList<QRgb> &colors)
void setDrawSliceFrames(bool enable)
void setDrawSlices(bool enable)
void setPreserveOpacity(bool enable)
void setSliceFrameColor(const QColor &color)
void setSliceFrameGaps(const QVector3D &values)
void setSliceFrameThicknesses(const QVector3D &values)
void setSliceFrameWidths(const QVector3D &values)
void setSliceIndexX(int value)
void setSliceIndexY(int value)
void setSliceIndexZ(int value)
void setSliceIndices(int x, int y, int z)
void setSubTextureData(Qt::Axis axis, int index, const QImage &image)
void setSubTextureData(Qt::Axis axis, int index, const uchar *data)
void setTextureData(QList<uchar> *data)
void setTextureDepth(int value)
void setTextureDimensions(int width, int height, int depth)
void setTextureFormat(QImage::Format format)
void setTextureHeight(int value)
void setTextureWidth(int value)
void setUseHighDefShader(bool enable)
QColor sliceFrameColor() const
QVector3D sliceFrameGaps() const
QVector3D sliceFrameThicknesses() const
QVector3D sliceFrameWidths() const
int sliceIndexX() const
int sliceIndexY() const
int sliceIndexZ() const
QList<uchar> *textureData() const
int textureDataWidth() const
int textureDepth() const
QImage::Format textureFormat() const
int textureHeight() const
int textureWidth() const
bool useHighDefShader() const

Señales

void alphaMultiplierChanged(float mult)
void colorTableChanged()
void drawSliceFramesChanged(bool enabled)
void drawSlicesChanged(bool enabled)
void preserveOpacityChanged(bool enabled)
void sliceFrameColorChanged(const QColor &color)
void sliceFrameGapsChanged(const QVector3D &values)
void sliceFrameThicknessesChanged(const QVector3D &values)
void sliceFrameWidthsChanged(const QVector3D &values)
void sliceIndexXChanged(int value)
void sliceIndexYChanged(int value)
void sliceIndexZChanged(int value)
void textureDataChanged(QList<uchar> *data)
void textureDepthChanged(int value)
void textureFormatChanged(QImage::Format format)
void textureHeightChanged(int value)
void textureWidthChanged(int value)
void useHighDefShaderChanged(bool enabled)

Descripción detallada

Un objeto renderizado en volumen es una caja con una textura 3D. Se admiten tres planos de corte para el volumen, uno a lo largo de cada eje principal del mismo.

El renderizado de objetos volumétricos consume muchos recursos, especialmente cuando el volumen es en gran parte transparente, ya que el contenido del volumen se renderiza mediante trazado de rayos. El rendimiento varía de forma casi lineal con la cantidad de píxeles que ocupa el volumen en la pantalla, por lo que mostrar el volumen en una vista más pequeña o limitar el nivel de zoom del gráfico son formas sencillas de mejorar el rendimiento. Del mismo modo, las dimensiones de la textura del volumen tienen un gran impacto en el rendimiento. Si la velocidad de fotogramas es más importante que un renderizado pixel a pixel del contenido del volumen, considera desactivar el sombreador de alta definición configurando la propiedad « useHighDefShader » en « false ».

Nota: Los objetosvolumétricos solo son compatibles con la proyección ortográfica.

Nota: Los objetosvolumétricos utilizan texturas 3D, que no son compatibles con entornos OpenGL ES2.

Véase también QAbstract3DGraph::addCustomItem(), QAbstract3DGraph::orthoProjection y useHighDefShader.

Documentación de propiedades

alphaMultiplier : float

Esta propiedad contiene el valor por el que se multiplica el valor alfa de cada texel de la textura del volumen en el momento del renderizado.

Esta propiedad se puede utilizar para aplicar una transparencia uniforme al volumen. Si « preserveOpacity » es « true », solo se ven afectados los texeles que ya tengan al menos algo de transparencia, mientras que los texeles totalmente opacos no se ven afectados. El valor no debe ser negativo. El valor por defecto es « 1.0f ».

Funciones de acceso:

float alphaMultiplier() const
void setAlphaMultiplier(float mult)

Señal de notificación:

void alphaMultiplierChanged(float mult)

Véase también preserveOpacity y textureData.

colorTable : QList<QRgb>

Esta propiedad contiene la matriz con los colores para los formatos de textura indexados.

Si el formato de textura no es indexado, este array no se utiliza y puede estar vacío.

El valor por defecto es ` 0`.

Funciones de acceso:

QList<QRgb> colorTable() const
void setColorTable(const QList<QRgb> &colors)

Señal de notificación:

void colorTableChanged()

Véase también textureData, setTextureFormat() y QImage::colorTable().

drawSliceFrames : bool

Esta propiedad determina si se dibujan marcos de corte alrededor del volumen.

Si el valor de esta propiedad es « true », se dibujarán los marcos de los cortes indicados por las propiedades de índice de corte alrededor del volumen. Si es « false », no se dibujará ningún marco de corte.

El trazado de los marcos de corte es independiente del trazado de los cortes, por lo que se puede mostrar el volumen completo y, aun así, trazar los marcos de corte a su alrededor. Esto resulta útil cuando se utiliza ` renderSlice()` para mostrar los cortes fuera del propio gráfico.

El valor por defecto es false.

Funciones de acceso:

bool drawSliceFrames() const
void setDrawSliceFrames(bool enable)

Señal de notificación:

void drawSliceFramesChanged(bool enabled)

Véase también sliceIndexX, sliceIndexY, sliceIndexZ, drawSlices y renderSlice().

drawSlices : bool

Esta propiedad determina si se dibujan los cortes especificados en lugar del volumen completo.

Si el valor de esta propiedad es « true », se dibujarán los cortes indicados por las propiedades de índice de corte en lugar del volumen completo. Si es « false », siempre se dibujará el volumen completo. El valor por defecto es « false ».

Nota: Los cortes siempre se dibujan a lo largo de los ejes del elemento, por lo que, si el elemento se gira, los cortes también se giran.

Funciones de acceso:

bool drawSlices() const
void setDrawSlices(bool enable)

Señal de notificación:

void drawSlicesChanged(bool enabled)

Véase también sliceIndexX, sliceIndexY y sliceIndexZ.

preserveOpacity : bool

Esta propiedad determina si el multiplicador alfa se aplica a todos los texeles.

Si el valor de esta propiedad es « true », « alphaMultiplier » solo se aplica a los texeles que ya tienen cierta transparencia. Si es « false », el multiplicador se aplica al valor alfa de todos los texeles. El valor por defecto es « true ».

Funciones de acceso:

bool preserveOpacity() const
void setPreserveOpacity(bool enable)

Señal de notificación:

void preserveOpacityChanged(bool enabled)

Véase también alphaMultiplier.

sliceFrameColor : QColor

Esta propiedad determina el color del marco de la sección.

No se admite el color transparente para el marco de la sección.

El valor predeterminado es el negro.

Funciones de acceso:

QColor sliceFrameColor() const
void setSliceFrameColor(const QColor &color)

Señal de notificación:

void sliceFrameColorChanged(const QColor &color)

Véase también drawSliceFrames.

sliceFrameGaps : QVector3D

Esta propiedad indica el tamaño del espacio de aire que queda entre el propio volumen y el marco en cada dimensión.

El espacio puede variar según las distintas dimensiones. Los valores son fracciones del grosor del volumen en la misma dimensión. Los valores no pueden ser negativos.

El valor por defecto es « QVector3D(0.01, 0.01, 0.01) ».

Funciones de acceso:

QVector3D sliceFrameGaps() const
void setSliceFrameGaps(const QVector3D &values)

Señal de notificación:

void sliceFrameGapsChanged(const QVector3D &values)

Véase también drawSliceFrames.

sliceFrameThicknesses : QVector3D

Esta propiedad contiene el grosor de los marcos de las secciones para cada dimensión.

Los valores son fracciones del espesor del volumen en la misma dimensión. Los valores no pueden ser negativos.

El valor por defecto es « QVector3D(0.01, 0.01, 0.01) ».

Funciones de acceso:

QVector3D sliceFrameThicknesses() const
void setSliceFrameThicknesses(const QVector3D &values)

Señal de notificación:

void sliceFrameThicknessesChanged(const QVector3D &values)

Véase también drawSliceFrames.

sliceFrameWidths : QVector3D

Esta propiedad determina la anchura del marco de la sección.

El ancho puede variar según las distintas dimensiones, por lo que, por ejemplo, puedes omitir el dibujo de los marcos en determinados lados del volumen estableciendo el valor de esa dimensión en cero. Los valores son fracciones del espesor del volumen en la misma dimensión. Los valores no pueden ser negativos.

El valor por defecto es QVector3D(0.01, 0.01, 0.01).

Funciones de acceso:

QVector3D sliceFrameWidths() const
void setSliceFrameWidths(const QVector3D &values)

Señal de notificación:

void sliceFrameWidthsChanged(const QVector3D &values)

Véase también drawSliceFrames.

sliceIndexX : int

Esta propiedad contiene el índice de la dimensión x en los datos de la textura, que indica qué sección vertical se debe mostrar.

Si se establece cualquier dimensión en un valor negativo, se indica que no se dibuje ningún corte ni marco de corte para esa dimensión. Si todas las dimensiones son negativas, no se dibujan cortes ni marcos de corte, y el volumen se dibuja con normalidad.

El valor por defecto es « -1 ».

Funciones de acceso:

int sliceIndexX() const
void setSliceIndexX(int value)

Señal de notificación:

void sliceIndexXChanged(int value)

Véase también textureData, drawSlices y drawSliceFrames.

sliceIndexY : int

Esta propiedad contiene el índice de la dimensión y en los datos de la textura, que indica qué corte horizontal se debe mostrar.

Si se establece cualquier dimensión en un valor negativo, no se dibuja ninguna sección ni marco de sección para esa dimensión. Si todas las dimensiones son negativas, no se dibujan secciones ni marcos de sección, y el volumen se dibuja con normalidad.

El valor por defecto es « -1 ».

Funciones de acceso:

int sliceIndexY() const
void setSliceIndexY(int value)

Señal de notificación:

void sliceIndexYChanged(int value)

Véase también textureData, drawSlices y drawSliceFrames.

sliceIndexZ : int

Esta propiedad contiene el índice de la dimensión Z en los datos de la textura, que indica qué corte vertical se debe mostrar.

Si se establece cualquier dimensión en un valor negativo, no se dibuja ningún corte ni marco de corte para esa dimensión. Si todas las dimensiones son negativas, no se dibujan cortes ni marcos de corte, y el volumen se dibuja con normalidad.

El valor por defecto es « -1 ».

Funciones de acceso:

int sliceIndexZ() const
void setSliceIndexZ(int value)

Señal de notificación:

void sliceIndexZChanged(int value)

Véase también textureData, drawSlices y drawSliceFrames.

textureData : QList<uchar>*

Esta propiedad contiene la matriz con los datos de textura en el formato especificado en textureFormat.

El tamaño de este array debe ser, como mínimo, (textureDataWidth * textureHeight * textureDepth * texture format color depth in bytes).

Una textura 3D se define mediante una pila de subtexturas 2D. Cada subtextura debe tener el mismo tamaño (textureDataWidth * textureHeight), y la profundidad de la pila viene definida por la propiedad textureDepth. Los datos de cada textura 2D son idénticos a los de un objeto QImage con el mismo formato, por lo que se puede utilizar QImage::bits() para proporcionar los datos de cada subtextura.

La propiedad del nuevo array se transfiere a la instancia QCustom3DVolume. Si se establece otro array, el anterior se elimina. Si se vuelve a establecer el mismo array, se supone que su contenido ha cambiado y se activa el renderizado del gráfico.

Nota: Cada línea de la dimensión x de los datos debe estar alineada a 32 bits. Si textureFormat es QImage::Format_Indexed8 y el valor de textureWidth no es divisible por cuatro, puede que sea necesario añadir bytes de relleno a cada línea de la dimensión x de data. La función textureDataWidth() devuelve el recuento de bytes rellenados. Los bytes de relleno deben indicar un color totalmente transparente para evitar artefactos de renderizado.

El valor por defecto es 0.

Funciones de acceso:

QList<uchar> *textureData() const
void setTextureData(QList<uchar> *data)

Señal de notificación:

void textureDataChanged(QList<uchar> *data)

Véase también colorTable, setTextureFormat(), setSubTextureData() y textureDataWidth().

textureDepth : int

Esta propiedad contiene la profundidad, en píxeles, de la textura 3D que define el contenido del volumen.

El valor por defecto es 0.

Nota: Es posible que sea necesario redimensionar o volver a crearel « textureData » si se modifica este valor. El valor por defecto es « 0 ».

Funciones de acceso:

int textureDepth() const
void setTextureDepth(int value)

Señal de notificación:

void textureDepthChanged(int value)

Véase también textureData, textureWidth, textureHeight y setTextureFormat().

textureHeight : int

Esta propiedad contiene la altura, en píxeles, de la textura 3D que define el contenido del volumen.

El valor por defecto es « 0 ».

Nota: Es posible que haya que redimensionar o volver a crearel « textureData » si se modifica este valor. El valor por defecto es « 0 ».

Funciones de acceso:

int textureHeight() const
void setTextureHeight(int value)

Señal de notificación:

void textureHeightChanged(int value)

Véase también textureData, textureWidth, textureDepth y setTextureFormat().

textureWidth : int

Esta propiedad contiene el ancho, en píxeles, de la textura 3D que define el contenido del volumen.

El valor por defecto es « 0 ».

Nota: Es posible que sea necesario redimensionar o volver a crearel valor « textureData » si se modifica este valor. El valor por defecto es « 0 ».

Funciones de acceso:

int textureWidth() const
void setTextureWidth(int value)

Señal de notificación:

void textureWidthChanged(int value)

Véase también textureData, textureHeight, textureDepth, setTextureFormat() y textureDataWidth().

useHighDefShader : bool

Esta propiedad determina si se utiliza un shader de alta o baja definición para renderizar el volumen.

Si el valor de esta propiedad es « true », se utiliza un sombreador de alta definición. Si es « false », se utiliza un sombreador de baja definición.

El sombreador de alta definición garantiza que se muestree cada texel visible de la textura del volumen al renderizarlo. El sombreador de baja definición renderiza solo una aproximación aproximada del contenido del volumen, pero a una frecuencia de fotogramas mucho mayor. El sombreador de baja definición no garantiza que se muestree cada texel de la textura del volumen, por lo que puede producirse parpadeo si el volumen contiene elementos delgados bien definidos.

Nota: Este valor no afecta al nivel de detalle al renderizar los cortes del volumen.

El valor por defecto es « true ».

Funciones de acceso:

bool useHighDefShader() const
void setUseHighDefShader(bool enable)

Señal de notificación:

void useHighDefShaderChanged(bool enabled)

Véase también renderSlice().

Documentación de funciones de miembro

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

Crea un volumen 3D personalizado con el archivo « parent » proporcionado.

[explicit] QCustom3DVolume::QCustom3DVolume(const QVector3D &position, const QVector3D &scaling, const QQuaternion &rotation, int textureWidth, int textureHeight, int textureDepth, QList<uchar> *textureData, QImage::Format textureFormat, const QList<QRgb> &colorTable, QObject *parent = nullptr)

Crea un volumen 3D personalizado con los siguientes parámetros: position, scaling, rotation, textureWidth, textureHeight, textureDepth, textureData, textureFormat, colorTable y, opcionalmente, parent.

Véase también textureData, setTextureFormat() y colorTable.

[virtual noexcept] QCustom3DVolume::~QCustom3DVolume()

Elimina el volumen 3D personalizado.

QList<uchar> *QCustom3DVolume::createTextureData(const QList<QImage *> &images)

Crea una nueva matriz de datos de textura a partir de una matriz de « images » y la establece como « textureData » para este objeto de volumen. Las dimensiones de la textura también se establecen en función de las dimensiones de la imagen y de la matriz. Todas las imágenes de la matriz deben tener el mismo tamaño. Si las imágenes no están todas en el formato QImage::Format_Indexed8, todos los datos de textura se convertirán al formato QImage::Format_ARGB32. Si las imágenes están en el formato QImage::Format_Indexed8, el valor de colorTable para todo el volumen se tomará de la primera imagen.

Devuelve un puntero a la matriz recién creada.

Véase también textureData, textureWidth, textureHeight, textureDepth y setTextureFormat().

QImage QCustom3DVolume::renderSlice(Qt::Axis axis, int index)

Genera una imagen a partir de la sección especificada por index a lo largo del eje especificado por axis. Se utiliza el formato de textura de este objeto.

Devuelve la imagen renderizada del corte, o una imagen nula si se especifica un índice no válido.

Véase también setTextureFormat().

void QCustom3DVolume::setSliceIndices(int x, int y, int z)

Una función práctica para establecer los tres índices de corte (x, y y z) a la vez.

Véase también textureData.

void QCustom3DVolume::setSubTextureData(Qt::Axis axis, int index, const QImage &image)

Establece una única subtextura 2D de la textura 3D a lo largo del eje « axis » especificado del volumen. El parámetro « index » especifica la subtextura que se va a establecer. La imagen de origen image debe tener el formato especificado por la propiedad textureFormat si textureFormat está indexada. Si textureFormat es QImage::Format_ARGB32, la imagen se convierte a ese formato. La imagen debe tener el tamaño de la sección transversal de la textura del volumen a lo largo del eje especificado. La orientación de la imagen debe corresponder a la orientación de la imagen de corte generada por el método renderSlice() a lo largo del mismo eje.

Nota: Cada línea de la dimensión x de los datos debe estar alineada a 32 bits cuando se utiliza el eje y o el eje z como referencia. Si textureFormat es QImage::Format_Indexed8 y el valor de textureWidth no es divisible por cuatro, puede que sea necesario añadir bytes de relleno a cada línea de la dimensión x de la imagen para alinearla correctamente. Los bytes de relleno deben indicar un color totalmente transparente para evitar artefactos de renderizado. No se garantiza que QImage realice esto automáticamente.

Véase también textureData y renderSlice().

void QCustom3DVolume::setSubTextureData(Qt::Axis axis, int index, const uchar *data)

Establece una única subtextura 2D de la textura 3D a lo largo de la « axis » especificada del volumen. El parámetro « index » especifica la subtextura que se va a establecer. La textura data debe tener el formato especificado por la propiedad textureFormat y un tamaño equivalente al de la sección transversal de la textura del volumen a lo largo del eje especificado, multiplicado por la profundidad de color del formato de la textura en bytes. Se espera que la data esté ordenada de forma similar a los datos de las imágenes generadas por el método renderSlice() a lo largo del mismo eje.

Nota: Cada línea de la dimensión x de los datos debe estar alineada a 32 bits cuando se apunta al eje y o al eje z. Si textureFormat es QImage::Format_Indexed8 y el valor de textureWidth no es divisible por cuatro, puede que sea necesario añadir bytes de relleno a cada línea de la dimensión x de data para alinearla correctamente. Los bytes de relleno deben indicar un color totalmente transparente para evitar artefactos de renderizado.

Véase también textureData y renderSlice().

void QCustom3DVolume::setTextureDimensions(int width, int height, int depth)

Una función práctica para establecer las tres dimensiones de la textura (width, height y depth) a la vez.

Véase también textureData.

void QCustom3DVolume::setTextureFormat(QImage::Format format)

Establece el formato de la propiedad « textureData » en « format ». Actualmente solo se admiten dos formatos: « QImage::Format_Indexed8 » y « QImage::Format_ARGB32 ». Si se especifica un formato indexado, también debe establecerse « colorTable ». El valor por defecto es « QImage::Format_ARGB32 ».

Véase también textureFormat(), colorTable y textureData.

int QCustom3DVolume::textureDataWidth() const

Devuelve la anchura real de los datos de la textura. Cuando el formato de la textura es « QImage::Format_Indexed8 », este valor es igual a « textureWidth » alineado a un límite de 32 bits. En caso contrario, este valor es igual a cuatro veces « textureWidth ».

QImage::Format QCustom3DVolume::textureFormat() const

Devuelve el formato del valor de la propiedad « textureData ».

Véase también setTextureFormat().

[signal] void QCustom3DVolume::textureFormatChanged(QImage::Format format)

Esta señal se emite cuando cambia el valor de « format » de « textureData ».

Véase también setTextureFormat().

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