QCustom3DVolume#

The QCustom3DVolume class adds a volume rendered object to a graph. More…

Inheritance diagram of PySide6.QtDataVisualization.QCustom3DVolume

Synopsis#

Properties#

  • alphaMultiplier - Value that the alpha value of every texel of the volume texture is multiplied with at the render time

  • colorTable - Array containing the colors for indexed texture formats

  • drawSliceFrames - Whether slice frames are drawn around the volume

  • drawSlices - Whether the specified slices are drawn instead of the full volume

  • preserveOpacity - Whether the alpha multiplier is applied to all texels

  • sliceFrameColor - Color of the slice frame

  • sliceFrameGaps - Size of the air gap left between the volume itself and the frame in each dimension

  • sliceFrameThicknesses - Thickness of the slice frames for each dimension

  • sliceFrameWidths - Width of the slice frame

  • sliceIndexX - X-dimension index into the texture data indicating which vertical slice to show

  • sliceIndexY - Y-dimension index into the texture data indicating which horizontal slice to show

  • sliceIndexZ - Z-dimension index into the texture data indicating which vertical slice to show

  • textureData - Array containing the texture data in the format specified by textureFormat

  • textureDepth - Depth of the 3D texture defining the volume content in pixels

  • textureHeight - Height of the 3D texture defining the volume content in pixels

  • textureWidth - Width of the 3D texture defining the volume content in pixels

  • useHighDefShader - Whether a high or low definition shader is used to render the volume

Functions#

Signals#

Note

This documentation may contain snippets that were automatically translated from C++ to Python. We always welcome contributions to the snippet translation. If you see an issue with the translation, you can also let us know by creating a ticket on https:/bugreports.qt.io/projects/PYSIDE

Detailed Description#

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 the 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

addCustomItem() orthoProjection useHighDefShader

class PySide6.QtDataVisualization.QCustom3DVolume([parent=None])#

PySide6.QtDataVisualization.QCustom3DVolume(position, scaling, rotation, textureWidth, textureHeight, textureDepth, textureData, textureFormat, colorTable[, parent=None])

Parameters:

Constructs a custom 3D volume with the given parent.

Constructs a custom 3D volume with the given position, scaling, rotation, textureWidth, textureHeight, textureDepth, textureData, textureFormat, colorTable, and optional parent.

Note

Properties can be used directly when from __feature__ import true_property is used or via accessor functions otherwise.

property PᅟySide6.QtDataVisualization.QCustom3DVolume.alphaMultiplier: float#

This property holds The value that the alpha value of every texel of the volume texture is multiplied with at the render time..

This property 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:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.colorTable#

This property holds 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.

See also

textureData setTextureFormat() colorTable()

Access functions:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.drawSliceFrames: bool#

This property holds Whether slice frames are drawn around the volume..

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:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.drawSlices: bool#

This property holds Whether the specified slices are drawn instead of the full volume..

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.

See also

sliceIndexX sliceIndexY sliceIndexZ

Access functions:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.preserveOpacity: bool#

This property holds Whether the alpha multiplier is applied to all texels..

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.

See also

alphaMultiplier

Access functions:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.sliceFrameColor: PySide6.QtGui.QColor#

This property holds The color of the slice frame..

Transparent slice frame color is not supported.

Defaults to black.

See also

drawSliceFrames

Access functions:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.sliceFrameGaps: PySide6.QtGui.QVector3D#

This property holds The size of the 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).

See also

drawSliceFrames

Access functions:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.sliceFrameThicknesses: PySide6.QtGui.QVector3D#

This property holds 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).

See also

drawSliceFrames

Access functions:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.sliceFrameWidths: PySide6.QtGui.QVector3D#

This property holds The width 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).

See also

drawSliceFrames

Access functions:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.sliceIndexX: int#

This property holds 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:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.sliceIndexY: int#

This property holds 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:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.sliceIndexZ: int#

This property holds 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:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.textureData: QList#

This property holds 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 the textureDepth property. The data in each 2D texture 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 the 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-dimension line of the data needs to be 32-bit aligned. If textureFormat is Format_Indexed8 and the textureWidth value is not divisible by four, padding bytes might need to be added to each x-dimension line of the data. The textureDataWidth() function returns the padded byte count. The padding bytes should indicate a fully transparent color to avoid rendering artifacts.

Defaults to 0.

Access functions:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.textureDepth: int#

This property holds The depth of the 3D texture defining the volume content in pixels..

Defaults to 0.

Note

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

See also

textureData textureWidth textureHeight setTextureFormat()

Access functions:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.textureHeight: int#

This property holds The height of the 3D texture defining the volume content in pixels..

Defaults to 0.

Note

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

See also

textureData textureWidth textureDepth setTextureFormat()

Access functions:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.textureWidth: int#

This property holds The width of the 3D texture defining the volume content in pixels..

Defaults to 0.

Note

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

See also

textureData textureHeight textureDepth setTextureFormat() textureDataWidth()

Access functions:
property PᅟySide6.QtDataVisualization.QCustom3DVolume.useHighDefShader: bool#

This property holds Whether a high or low definition shader is used to render the volume..

If this property value is true, a high definition shader is used. 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 a much higher frame rate. The low definition shader does not guarantee that every texel of the volume texture is sampled, so there may be flickering if the volume contains distinct thin features.

Note

This value does not affect the level of detail when rendering the slices of the volume.

Defaults to true.

See also

renderSlice()

Access functions:
PySide6.QtDataVisualization.QCustom3DVolume.alphaMultiplier()#
Return type:

float

See also

setAlphaMultiplier()

Getter of property alphaMultiplier .

PySide6.QtDataVisualization.QCustom3DVolume.alphaMultiplierChanged(mult)#
Parameters:

mult – float

Notification signal of property alphaMultiplier .

PySide6.QtDataVisualization.QCustom3DVolume.colorTable()#
Return type:

See also

setColorTable()

Getter of property colorTable .

PySide6.QtDataVisualization.QCustom3DVolume.colorTableChanged()#

Notification signal of property colorTable .

PySide6.QtDataVisualization.QCustom3DVolume.createTextureData(images)#
Parameters:

images –

Return type:

QList

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 the Format_Indexed8 format, all texture data will be converted into the Format_ARGB32 format. If the images are in the Format_Indexed8 format, the colorTable value for the entire volume will be taken from the first image.

Returns a pointer to the newly created array.

PySide6.QtDataVisualization.QCustom3DVolume.drawSliceFrames()#
Return type:

bool

See also

setDrawSliceFrames()

Getter of property drawSliceFrames .

PySide6.QtDataVisualization.QCustom3DVolume.drawSliceFramesChanged(enabled)#
Parameters:

enabled – bool

Notification signal of property drawSliceFrames .

PySide6.QtDataVisualization.QCustom3DVolume.drawSlices()#
Return type:

bool

See also

setDrawSlices()

Getter of property drawSlices .

PySide6.QtDataVisualization.QCustom3DVolume.drawSlicesChanged(enabled)#
Parameters:

enabled – bool

Notification signal of property drawSlices .

PySide6.QtDataVisualization.QCustom3DVolume.preserveOpacity()#
Return type:

bool

See also

setPreserveOpacity()

Getter of property preserveOpacity .

PySide6.QtDataVisualization.QCustom3DVolume.preserveOpacityChanged(enabled)#
Parameters:

enabled – bool

Notification signal of property preserveOpacity .

PySide6.QtDataVisualization.QCustom3DVolume.renderSlice(axis, index)#
Parameters:

  • axis – Axis

  • index – int

Return type:

PySide6.QtGui.QImage

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

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

PySide6.QtDataVisualization.QCustom3DVolume.setAlphaMultiplier(mult)#
Parameters:

mult – float

See also

alphaMultiplier()

Setter of property alphaMultiplier .

PySide6.QtDataVisualization.QCustom3DVolume.setColorTable(colors)#
Parameters:

colors –

See also

colorTable()

Setter of property colorTable .

PySide6.QtDataVisualization.QCustom3DVolume.setDrawSliceFrames(enable)#
Parameters:

enable – bool

See also

drawSliceFrames()

Setter of property drawSliceFrames .

PySide6.QtDataVisualization.QCustom3DVolume.setDrawSlices(enable)#
Parameters:

enable – bool

See also

drawSlices()

Setter of property drawSlices .

PySide6.QtDataVisualization.QCustom3DVolume.setPreserveOpacity(enable)#
Parameters:

enable – bool

See also

preserveOpacity()

Setter of property preserveOpacity .

PySide6.QtDataVisualization.QCustom3DVolume.setSliceFrameColor(color)#
Parameters:

color – PySide6.QtGui.QColor

See also

sliceFrameColor()

Setter of property sliceFrameColor .

PySide6.QtDataVisualization.QCustom3DVolume.setSliceFrameGaps(values)#
Parameters:

values – PySide6.QtGui.QVector3D

See also

sliceFrameGaps()

Setter of property sliceFrameGaps .

PySide6.QtDataVisualization.QCustom3DVolume.setSliceFrameThicknesses(values)#
Parameters:

values – PySide6.QtGui.QVector3D

See also

sliceFrameThicknesses()

Setter of property sliceFrameThicknesses .

PySide6.QtDataVisualization.QCustom3DVolume.setSliceFrameWidths(values)#
Parameters:

values – PySide6.QtGui.QVector3D

See also

sliceFrameWidths()

Setter of property sliceFrameWidths .

PySide6.QtDataVisualization.QCustom3DVolume.setSliceIndexX(value)#
Parameters:

value – int

See also

sliceIndexX()

Setter of property sliceIndexX .

PySide6.QtDataVisualization.QCustom3DVolume.setSliceIndexY(value)#
Parameters:

value – int

See also

sliceIndexY()

Setter of property sliceIndexY .

PySide6.QtDataVisualization.QCustom3DVolume.setSliceIndexZ(value)#
Parameters:

value – int

See also

sliceIndexZ()

Setter of property sliceIndexZ .

PySide6.QtDataVisualization.QCustom3DVolume.setSliceIndices(x, y, z)#
Parameters:

  • x – int

  • y – int

  • z – int

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

See also

textureData

PySide6.QtDataVisualization.QCustom3DVolume.setSubTextureData(axis, index, image)#
Parameters:

Sets 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 textureFormat is indexed. If textureFormat is 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-dimension line of the data needs to be 32-bit aligned when targeting the y-axis or z-axis. If textureFormat is Format_Indexed8 and the textureWidth value is not divisible by four, padding bytes might need to be added to each x-dimension line of the image to properly align it. The padding bytes should indicate a fully transparent color to avoid rendering artifacts. It is not guaranteed that QImage will do this automatically.

See also

textureData renderSlice()

PySide6.QtDataVisualization.QCustom3DVolume.setSubTextureData(axis, index, data)
Parameters:

  • axis – Axis

  • index – int

  • data – str

Sets 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 the textureFormat property and have the 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 the renderSlice() method along the same axis.

Note

Each x-dimension line of the data needs to be 32-bit aligned when targeting the y-axis or z-axis. If textureFormat is Format_Indexed8 and the textureWidth value is not divisible by four, padding bytes might need to be added to each x-dimension line of the data to properly align it. The padding bytes should indicate a fully transparent color to avoid rendering artifacts.

See also

textureData renderSlice()

PySide6.QtDataVisualization.QCustom3DVolume.setTextureData(arg__1)#
Parameters:

arg__1 –

PySide6.QtDataVisualization.QCustom3DVolume.setTextureDepth(value)#
Parameters:

value – int

See also

textureDepth()

Setter of property textureDepth .

PySide6.QtDataVisualization.QCustom3DVolume.setTextureDimensions(width, height, depth)#
Parameters:

  • width – int

  • height – int

  • depth – int

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

See also

textureData

PySide6.QtDataVisualization.QCustom3DVolume.setTextureFormat(format)#
Parameters:

format – Format

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

PySide6.QtDataVisualization.QCustom3DVolume.setTextureHeight(value)#
Parameters:

value – int

See also

textureHeight()

Setter of property textureHeight .

PySide6.QtDataVisualization.QCustom3DVolume.setTextureWidth(value)#
Parameters:

value – int

See also

textureWidth()

Setter of property textureWidth .

PySide6.QtDataVisualization.QCustom3DVolume.setUseHighDefShader(enable)#
Parameters:

enable – bool

See also

useHighDefShader()

Setter of property useHighDefShader .

PySide6.QtDataVisualization.QCustom3DVolume.sliceFrameColor()#
Return type:

PySide6.QtGui.QColor

See also

setSliceFrameColor()

Getter of property sliceFrameColor .

PySide6.QtDataVisualization.QCustom3DVolume.sliceFrameColorChanged(color)#
Parameters:

color – PySide6.QtGui.QColor

Notification signal of property sliceFrameColor .

PySide6.QtDataVisualization.QCustom3DVolume.sliceFrameGaps()#
Return type:

PySide6.QtGui.QVector3D

See also

setSliceFrameGaps()

Getter of property sliceFrameGaps .

PySide6.QtDataVisualization.QCustom3DVolume.sliceFrameGapsChanged(values)#
Parameters:

values – PySide6.QtGui.QVector3D

Notification signal of property sliceFrameGaps .

PySide6.QtDataVisualization.QCustom3DVolume.sliceFrameThicknesses()#
Return type:

PySide6.QtGui.QVector3D

See also

setSliceFrameThicknesses()

Getter of property sliceFrameThicknesses .

PySide6.QtDataVisualization.QCustom3DVolume.sliceFrameThicknessesChanged(values)#
Parameters:

values – PySide6.QtGui.QVector3D

Notification signal of property sliceFrameThicknesses .

PySide6.QtDataVisualization.QCustom3DVolume.sliceFrameWidths()#
Return type:

PySide6.QtGui.QVector3D

See also

setSliceFrameWidths()

Getter of property sliceFrameWidths .

PySide6.QtDataVisualization.QCustom3DVolume.sliceFrameWidthsChanged(values)#
Parameters:

values – PySide6.QtGui.QVector3D

Notification signal of property sliceFrameWidths .

PySide6.QtDataVisualization.QCustom3DVolume.sliceIndexX()#
Return type:

int

See also

setSliceIndexX()

Getter of property sliceIndexX .

PySide6.QtDataVisualization.QCustom3DVolume.sliceIndexXChanged(value)#
Parameters:

value – int

Notification signal of property sliceIndexX .

PySide6.QtDataVisualization.QCustom3DVolume.sliceIndexY()#
Return type:

int

See also

setSliceIndexY()

Getter of property sliceIndexY .

PySide6.QtDataVisualization.QCustom3DVolume.sliceIndexYChanged(value)#
Parameters:

value – int

Notification signal of property sliceIndexY .

PySide6.QtDataVisualization.QCustom3DVolume.sliceIndexZ()#
Return type:

int

See also

setSliceIndexZ()

Getter of property sliceIndexZ .

PySide6.QtDataVisualization.QCustom3DVolume.sliceIndexZChanged(value)#
Parameters:

value – int

Notification signal of property sliceIndexZ .

PySide6.QtDataVisualization.QCustom3DVolume.textureData()#
Return type:

QList

See also

setTextureData()

Getter of property textureData .

PySide6.QtDataVisualization.QCustom3DVolume.textureDataChanged(data)#
Parameters:

data – QList

Notification signal of property textureData .

PySide6.QtDataVisualization.QCustom3DVolume.textureDataWidth()#
Return type:

int

Returns the actual texture data width. When the texture format is Format_Indexed8 , this value equals textureWidth aligned to a 32-bit boundary. Otherwise, this value equals four times textureWidth .

PySide6.QtDataVisualization.QCustom3DVolume.textureDepth()#
Return type:

int

See also

setTextureDepth()

Getter of property textureDepth .

PySide6.QtDataVisualization.QCustom3DVolume.textureDepthChanged(value)#
Parameters:

value – int

Notification signal of property textureDepth .

PySide6.QtDataVisualization.QCustom3DVolume.textureFormat()#
Return type:

Format

Returns the format of the textureData property value.

PySide6.QtDataVisualization.QCustom3DVolume.textureFormatChanged(format)#
Parameters:

format – Format

This signal is emitted when the format of the textureData value changes.

PySide6.QtDataVisualization.QCustom3DVolume.textureHeight()#
Return type:

int

See also

setTextureHeight()

Getter of property textureHeight .

PySide6.QtDataVisualization.QCustom3DVolume.textureHeightChanged(value)#
Parameters:

value – int

Notification signal of property textureHeight .

PySide6.QtDataVisualization.QCustom3DVolume.textureWidth()#
Return type:

int

See also

setTextureWidth()

Getter of property textureWidth .

PySide6.QtDataVisualization.QCustom3DVolume.textureWidthChanged(value)#
Parameters:

value – int

Notification signal of property textureWidth .

PySide6.QtDataVisualization.QCustom3DVolume.useHighDefShader()#
Return type:

bool

See also

setUseHighDefShader()

Getter of property useHighDefShader .

PySide6.QtDataVisualization.QCustom3DVolume.useHighDefShaderChanged(enabled)#
Parameters:

enabled – bool

Notification signal of property useHighDefShader .