QCustom3DVolume Class

The QCustom3DVolume class is for creating volume rendered objects to be added to a graph. More...

Header: #include <QCustom3DVolume>
Since: QtDataVisualization 1.2
Instantiated By: Custom3DVolume
Inherits: QCustom3DItem

Properties

Public Functions

QCustom3DVolume(QObject *parent = Q_NULLPTR)
QCustom3DVolume(const QVector3D &position, const QVector3D &scaling, const QQuaternion &rotation, int textureWidth, int textureHeight, int textureDepth, QVector<uchar> *textureData, QImage::Format textureFormat, const QVector<QRgb> &colorTable, QObject *parent = Q_NULLPTR)
virtual ~QCustom3DVolume()
float alphaMultiplier() const
QVector<QRgb> colorTable() const
QVector<uchar> *createTextureData(const QVector<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 QVector<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 uchar *data)
void setSubTextureData(Qt::Axis axis, int index, const QImage &image)
void setTextureData(QVector<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
QVector<uchar> *textureData() const
int textureDataWidth() const
int textureDepth() const
QImage::Format textureFormat() const
int textureHeight() const
int textureWidth() const
bool useHighDefShader() const

Signals

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(QVector<uchar> *data)
void textureDepthChanged(int value)
void textureFormatChanged(QImage::Format format)
void textureHeightChanged(int value)
void textureWidthChanged(int value)
void useHighDefShaderChanged(bool enabled)

Additional Inherited Members

  • 1 public slot inherited from QObject
  • 1 public variable inherited from QObject
  • 10 static public members inherited from QObject
  • 9 protected functions inherited from QObject
  • 2 protected variables inherited from QObject

Detailed Description

The QCustom3DVolume class is for creating volume rendered objects to be added to a graph.

This class is for creating volume rendered objects to be added to a graph. A volume rendered object is a box with a 3D texture. Three slice planes are supported for the volume, one along each main axis of the volume.

Rendering volume objects is very performance intensive, especially when the volume is largely transparent, as the contents of the volume are ray-traced. The performance scales nearly linearly with the amount of pixels that the volume occupies on the screen, so showing the volume in a smaller view or limiting the zoom level of the graph are easy ways to improve performance. Similarly, the volume texture dimensions have a large impact on performance. If the frame rate is more important than pixel-perfect rendering of the volume contents, consider turning the high definition shader off by setting useHighDefShader property to false.

Note: Volumetric objects are only supported with orthographic projection.

Note: Volumetric objects utilize 3D textures, which are not supported in OpenGL ES2 environments.

See also QAbstract3DGraph::addCustomItem(), QAbstract3DGraph::orthoProjection, and useHighDefShader.

Property Documentation

alphaMultiplier : float

The alpha value of every texel of the volume texture is multiplied with this value at the render time. This can be used to introduce uniform transparency to the volume. If preserveOpacity is true, only texels with at least some transparency to begin with are affected, and fully opaque texels are not affected. The value must not be negative. Defaults to 1.0f.

Access functions:

float alphaMultiplier() const
void setAlphaMultiplier(float mult)

Notifier signal:

void alphaMultiplierChanged(float mult)

See also preserveOpacity and textureData.

colorTable : QVector<QRgb>

The array containing the colors for indexed texture formats. If the texture format is not indexed, this array is not used and can be empty.

Defaults to 0.

Access functions:

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

Notifier signal:

void colorTableChanged()

See also textureData, setTextureFormat(), and QImage::colorTable().

drawSliceFrames : bool

If this property value is true, the frames of slices indicated by slice index properties will be drawn around the volume. If it is false, no slice frames will be drawn. Drawing slice frames is independent of drawing slices, so you can show the full volume and still draw the slice frames around it. This is useful when using renderSlice() to display the slices outside the graph itself. Defaults to false.

Access functions:

bool drawSliceFrames() const
void setDrawSliceFrames(bool enable)

Notifier signal:

void drawSliceFramesChanged(bool enabled)

See also sliceIndexX, sliceIndexY, sliceIndexZ, drawSlices, and renderSlice().

drawSlices : bool

If this property value is true, the slices indicated by slice index properties will be drawn instead of the full volume. If it is false, the full volume will always be drawn. Defaults to false.

Note: The slices are always drawn along the item axes, so if the item is rotated, the slices are rotated as well.

Access functions:

bool drawSlices() const
void setDrawSlices(bool enable)

Notifier signal:

void drawSlicesChanged(bool enabled)

See also sliceIndexX, sliceIndexY, and sliceIndexZ.

preserveOpacity : bool

If this property value is true, alphaMultiplier is only applied to texels that already have some transparency. If it is false, the multiplier is applied to the alpha value of all texels. Defaults to true.

Access functions:

bool preserveOpacity() const
void setPreserveOpacity(bool enable)

Notifier signal:

void preserveOpacityChanged(bool enabled)

See also alphaMultiplier.

sliceFrameColor : QColor

Indicates the color of the slice frame. Transparent slice frame color is not supported.

Defaults to black.

Access functions:

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

Notifier signal:

void sliceFrameColorChanged(const QColor &color)

See also drawSliceFrames.

sliceFrameGaps : QVector3D

Indicates the amount of air gap left between the volume itself and the frame in each dimension. The gap can be different on different dimensions. The values are fractions of the volume thickness in the same dimension. The values cannot be negative.

Defaults to QVector3D(0.01, 0.01, 0.01).

Access functions:

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

Notifier signal:

void sliceFrameGapsChanged(const QVector3D &values)

See also drawSliceFrames.

sliceFrameThicknesses : QVector3D

Indicates the thickness of the slice frames for each dimension. The values are fractions of the volume thickness in the same dimension. The values cannot be negative.

Defaults to QVector3D(0.01, 0.01, 0.01).

Access functions:

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

Notifier signal:

void sliceFrameThicknessesChanged(const QVector3D &values)

See also drawSliceFrames.

sliceFrameWidths : QVector3D

Indicates the widths of the slice frame. The width can be different on different dimensions, so you can for example omit drawing the frames on certain sides of the volume by setting the value for that dimension to zero. The values are fractions of the volume thickness in the same dimension. The values cannot be negative.

Defaults to QVector3D(0.01, 0.01, 0.01).

Access functions:

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

Notifier signal:

void sliceFrameWidthsChanged(const QVector3D &values)

See also drawSliceFrames.

sliceIndexX : int

The X dimension index into the texture data indicating which vertical slice to show. Setting any dimension to negative indicates no slice or slice frame for that dimension is drawn. If all dimensions are negative, no slices or slice frames are drawn and the volume is drawn normally. Defaults to -1.

Access functions:

int sliceIndexX() const
void setSliceIndexX(int value)

Notifier signal:

void sliceIndexXChanged(int value)

See also textureData, drawSlices, and drawSliceFrames.

sliceIndexY : int

The Y dimension index into the texture data indicating which horizontal slice to show. Setting any dimension to negative indicates no slice or slice frame for that dimension is drawn. If all dimensions are negative, no slices or slice frames are drawn and the volume is drawn normally. Defaults to -1.

Access functions:

int sliceIndexY() const
void setSliceIndexY(int value)

Notifier signal:

void sliceIndexYChanged(int value)

See also textureData, drawSlices, and drawSliceFrames.

sliceIndexZ : int

The Z dimension index into the texture data indicating which vertical slice to show. Setting any dimension to negative indicates no slice or slice frame for that dimension is drawn. If all dimensions are negative, no slices or slice frames are drawn and the volume is drawn normally. Defaults to -1.

Access functions:

int sliceIndexZ() const
void setSliceIndexZ(int value)

Notifier signal:

void sliceIndexZChanged(int value)

See also textureData, drawSlices, and drawSliceFrames.

textureData : QVector<uchar> *

The array containing the texture data in the format specified by textureFormat. The size of this array must be at least (textureDataWidth * textureHeight * textureDepth * texture format color depth in bytes).

A 3D texture is defined by a stack of 2D subtextures. Each subtexture must be of identical size (textureDataWidth * textureHeight), and the depth of the stack is defined by textureDepth property. Each 2D texture data is identical to a QImage data with the same format, so QImage::bits() can be used to supply the data for each subtexture.

Ownership of the new array transfers to QCustom3DVolume instance. If another array is set, the previous array is deleted. If the same array is set again, it is assumed that the array contents have been changed and the graph rendering is triggered.

Note: Each X-line of the data needs to be 32bit aligned. If the textureFormat is QImage::Format_Indexed8 and textureWidth is not divisible by four, padding bytes need to be added to each X-line of the data. You can get the padded byte count with textureDataWidth() function. The padding bytes should indicate an fully transparent color to avoid rendering artifacts.

Defaults to 0.

Access functions:

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

Notifier signal:

void textureDataChanged(QVector<uchar> *data)

See also colorTable, setTextureFormat(), setSubTextureData(), and textureDataWidth().

textureDepth : int

The depth of the 3D texture defining the volume content in pixels. Defaults to 0.

Note: The textureData may need to be resized or recreated if this value is changed. Defaults to 0.

Access functions:

int textureDepth() const
void setTextureDepth(int value)

Notifier signal:

void textureDepthChanged(int value)

See also textureData, textureWidth, textureHeight, and setTextureFormat().

textureHeight : int

The height of the 3D texture defining the volume content in pixels. Defaults to 0.

Note: The textureData may need to be resized or recreated if this value is changed. Defaults to 0.

Access functions:

int textureHeight() const
void setTextureHeight(int value)

Notifier signal:

void textureHeightChanged(int value)

See also textureData, textureWidth, textureDepth, and setTextureFormat().

textureWidth : int

The width of the 3D texture defining the volume content in pixels. Defaults to 0.

Note: The textureData may need to be resized or recreated if this value is changed. Defaults to 0.

Access functions:

int textureWidth() const
void setTextureWidth(int value)

Notifier signal:

void textureWidthChanged(int value)

See also textureData, textureHeight, textureDepth, setTextureFormat(), and textureDataWidth().

useHighDefShader : bool

If this property value is true, a high definition shader is used to render the volume. If it is false, a low definition shader is used.

The high definition shader guarantees that every visible texel of the volume texture is sampled when the volume is rendered. The low definition shader renders only a rough approximation of the volume contents, but at much higher frame rate. The low definition shader doesn't guarantee every texel of the volume texture is sampled, so there may be flickering if the volume contains distinct thin features.

Note: This value doesn't affect the level of detail when rendering the slices of the volume.

Defaults to true.

Access functions:

bool useHighDefShader() const
void setUseHighDefShader(bool enable)

Notifier signal:

void useHighDefShaderChanged(bool enabled)

See also renderSlice().

Member Function Documentation

QCustom3DVolume::QCustom3DVolume(QObject *parent = Q_NULLPTR)

Constructs QCustom3DVolume with given parent.

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

Constructs QCustom3DVolume with given position, scaling, rotation, textureWidth, textureHeight, textureDepth, textureData, textureFormat, colorTable, and optional parent.

See also textureData, setTextureFormat(), and colorTable.

[virtual] QCustom3DVolume::~QCustom3DVolume()

Destroys QCustom3DVolume.

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

This function creates a new texture data array from an array of images and sets it as textureData for this volume object. The texture dimensions are also set according to image and array dimensions. All of the images in the array must be the same size. If the images are not all in QImage::Format_Indexed8 format, all texture data will be converted into QImage::Format_ARGB32 format. If the images are in QImage::Format_Indexed8 format, the colorTable for the entire volume will be taken from the first image.

Returns pointer to the newly created array.

See also textureData, textureWidth, textureHeight, textureDepth, and setTextureFormat().

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

Renders the slice specified by index along axis into an image. The texture format of this object is used.

Returns the rendered image of the slice, or a null image if invalid index is specified.

See also setTextureFormat().

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

A convenience function for setting all three slice indices (x, y, and z) at once.

See also textureData.

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

This function allows setting a single 2D subtexture of the 3D texture along the specified axis of the volume. The index parameter specifies the subtexture to set. The texture data must be in the format specified by textureFormat property and have size of the cross-section of the volume texture along the specified axis multiplied by the texture format color depth in bytes. The data is expected to be ordered similarly to the data in images produced by renderSlice() method along the same axis.

Note: Each X-line of the data needs to be 32bit aligned when targeting Y-axis or Z-axis. If the textureFormat is QImage::Format_Indexed8 and textureWidth is not divisible by four, padding bytes need to be added to each X-line of the data in cases it is not already properly aligned. The padding bytes should indicate an fully transparent color to avoid rendering artifacts.

See also textureData and renderSlice().

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

This function allows setting a single 2D subtexture of the 3D texture along the specified axis of the volume. The index parameter specifies the subtexture to set. The source image must be in the format specified by the textureFormat property if the textureFormat is indexed. If the textureFormat is QImage::Format_ARGB32, the image is converted to that format. The image must have the size of the cross-section of the volume texture along the specified axis. The orientation of the image should correspond to the orientation of the slice image produced by renderSlice() method along the same axis.

Note: Each X-line of the data needs to be 32bit aligned when targeting Y-axis or Z-axis. If the textureFormat is QImage::Format_Indexed8 and textureWidth is not divisible by four, padding bytes need to be added to each X-line of the image in cases it is not already properly aligned. The padding bytes should indicate an fully transparent color to avoid rendering artifacts. It is not guaranteed QImage will do this automatically.

See also textureData and renderSlice().

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

A convenience function for setting all three texture dimensions (width, height, and depth) at once.

See also textureData.

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

Sets the format of the textureData to format. Only two formats are supported currently: QImage::Format_Indexed8 and QImage::Format_ARGB32. If an indexed format is specified, colorTable must also be set. Defaults to QImage::Format_ARGB32.

See also textureFormat(), colorTable, and textureData.

int QCustom3DVolume::textureDataWidth() const

Returns the actual texture data width. When the texture format is QImage::Format_Indexed8, this is textureWidth aligned to 32bit boundary. Otherwise this is four times textureWidth.

QImage::Format QCustom3DVolume::textureFormat() const

Returns the format of the textureData.

See also setTextureFormat().

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

This signal is emitted when the textureData format changes.

See also setTextureFormat().