ScalarFieldView: 3D volume scalar data viewer

This module provides a window to view a 3D scalar field.

It supports iso-surfaces, a cutting plane and the definition of a region of interest.

For sample code using ScalarFieldView, see silx.gui.plot3d sample code

ScalarFieldView

class ScalarFieldView(parent=None)

Bases: Plot3DWindow

Widget computing and displaying an iso-surface from a 3D scalar dataset.

Limitation: Currently, iso-surfaces are generated with higher values than the iso-level ‘inside’ the surface.

Parameters:

parent – See QMainWindow

sigDataChanged

Signal emitted when the scalar data field has changed.

sigTransformChanged

Signal emitted when the transformation has changed.

It is emitted by setTranslation(), setTransformMatrix(), setScale().

sigSelectedRegionChanged

Signal emitted when the selected region has changed.

This signal provides the new selected region.

saveConfig(ioDevice)

Saves this view state. Only isosurfaces at the moment. Does not save the isosurface’s function.

Parameters:

ioDevice (qt.QIODevice) – A qt.QIODevice.

loadConfig(ioDevice)

Loads this view state. See ScalarFieldView.saveView to know what is supported at the moment.

Parameters:

ioDevice (qt.QIODevice) – A qt.QIODevice.

setInteractiveMode(mode)

Choose the current interaction.

Parameters:

mode (str) – Either rotate, pan or plane

getInteractiveMode()

Returns the current interaction mode, see setInteractiveMode()

setData(data, copy=True)

Set the 3D scalar data set to use for building the iso-surface.

Dataset order is zyx (i.e., first dimension is z).

Parameters:

• data (3D numpy.ndarray of float32 with shape at least (2, 2, 2)) – scalar field from which to extract the iso-surface

• copy (bool) – True (default) to make a copy, False to avoid copy (DO NOT MODIFY data afterwards)

getData(copy=True)

Get the 3D scalar data currently used to build the iso-surface.

Parameters:

copy (bool) – True (default) to get a copy, False to get the internal data (DO NOT modify!)

Returns:

The data set (or None if not set)

getDataRange()

Return the range of the data as a 3-tuple of values.

positive min is NaN if no data is positive.

Returns:

(min, positive min, max) or None.

setOuterScale(sx=1.0, sy=1.0, sz=1.0)

Set the scale to apply to the whole scene including the axes.

This is useful when axis lengths in data space are really different.

Parameters:

• sx (float) – Scale factor along the X axis

• sy (float) – Scale factor along the Y axis

• sz (float) – Scale factor along the Z axis

getOuterScale()

Returns the scales provided by setOuterScale().

Return type:

numpy.ndarray

setScale(sx=1.0, sy=1.0, sz=1.0)

Set the scale of the 3D scalar field (i.e., size of a voxel).

Parameters:

• sx (float) – Scale factor along the X axis

• sy (float) – Scale factor along the Y axis

• sz (float) – Scale factor along the Z axis

getScale()

Returns the scales provided by setScale() as a numpy.ndarray.

setTranslation(x=0.0, y=0.0, z=0.0)

Set the translation of the origin of the data array in data coordinates.

Parameters:

• x (float) – Offset of the data origin on the X axis

• y (float) – Offset of the data origin on the Y axis

• z (float) – Offset of the data origin on the Z axis

getTranslation()

Returns the offset set by setTranslation() as a numpy.ndarray.

setTransformMatrix(matrix3x3)

Set the transform matrix applied to the data.

Parameters:

matrix (numpy.ndarray) – 3x3 transform matrix

getTransformMatrix()

Returns the transform matrix applied to the data.

See setTransformMatrix().

Return type:

numpy.ndarray

isBoundingBoxVisible()

Returns axes labels, grid and bounding box visibility.

Return type:

bool

setBoundingBoxVisible(visible)

Set axes labels, grid and bounding box visibility.

Parameters:

visible (bool) – True to show axes, False to hide

setAxesLabels(xlabel=None, ylabel=None, zlabel=None)

Set the text labels of the axes.

Parameters:

• xlabel (str) – Label of the X axis, None to leave unchanged.

• ylabel (str) – Label of the Y axis, None to leave unchanged.

• zlabel (str) – Label of the Z axis, None to leave unchanged.

getAxesLabels()

Returns the text labels of the axes

>>> widget = ScalarFieldView()
>>> widget.setAxesLabels(xlabel='X')

You can get the labels either as a 3-tuple:

>>> xlabel, ylabel, zlabel = widget.getAxesLabels()

Or as an object with methods getXLabel, getYLabel and getZLabel:

>>> labels = widget.getAxesLabels()
>>> labels.getXLabel()
... 'X'

Returns:

object describing the labels

getForegroundColor()

Return color used for text and bounding box (QColor)

setForegroundColor(color)

Set the foreground color.

Parameters:

color (QColor, str or array-like of 3 or 4 float in [0., 1.] or uint8) – RGB color: name, #RRGGBB or RGB values

getHighlightColor()

Return color used for highlighted item bounding box (QColor)

setHighlightColor(color)

Set hightlighted item color.

Parameters:

color (QColor, str or array-like of 3 or 4 float in [0., 1.] or uint8) – RGB color: name, #RRGGBB or RGB values

getCutPlanes()

Return an iterable of all cut planes of the view.

This includes hidden cut planes.

For now, there is always one cut plane.

setSelectedRegion(zrange=None, yrange=None, xrange_=None)

Set the 3D selected region aligned with the axes.

Provided range are array indices range. The provided ranges are clipped to the data. If a range is None, the range of the array on this dimension is used.

Parameters:

• zrange – (zmin, zmax) range of the selection

• yrange – (ymin, ymax) range of the selection

• xrange – (xmin, xmax) range of the selection

getSelectedRegion()

Returns the currently selected region or None.

sigIsosurfaceAdded

Signal emitted when a new iso-surface is added to the view.

The newly added iso-surface is provided by this signal

sigIsosurfaceRemoved

Signal emitted when an iso-surface is removed from the view

The removed iso-surface is provided by this signal.

addIsosurface(level, color)

Add an iso-surface to the view.

Parameters:

• level (float or callable) – The value at which to build the iso-surface or a callable (e.g., a function) taking a 3D numpy.ndarray as input and returning a float. Example: numpy.mean(data) + numpy.std(data)

• color (str or array-like of 4 float in [0., 1.]) – RGBA color of the isosurface

Returns:

Isosurface object describing this isosurface

getIsosurfaces()

Return an iterable of all iso-surfaces of the view

removeIsosurface(isosurface)

Remove an iso-surface from the view.

Parameters:

isosurface – The isosurface object to remove

clearIsosurfaces()

Remove all iso-surfaces from the view.

Helper classes

Those classes are used by ScalarFieldView.

CutPlane

class CutPlane(sfView)

Bases: QObject

Class representing a cutting plane

Parameters:

sfView (ScalarFieldView) – Widget in which the cut plane is applied.

sigVisibilityChanged

Signal emitted when the cut visibility has changed.

This signal provides the new visibility status.

sigDataChanged

Signal emitted when the data this plane is cutting has changed.

sigPlaneChanged

Signal emitted when the cut plane has moved

sigColormapChanged

Signal emitted when the colormap has changed

This signal provides the new colormap.

sigTransparencyChanged

Signal emitted when the transparency of the plane has changed.

This signal is emitted when calling setDisplayValuesBelowMin().

sigInterpolationChanged

Signal emitted when the cut plane interpolation has changed

This signal provides the new interpolation mode.

moveToCenter()

Move cut plane to center of data set

isValid()

Returns whether the cut plane is defined or not (bool)

getNormal(coordinates='array')

Returns the normal of the plane (as a unit vector)

Parameters:

coordinates (str) – The coordinate system to use: Either ‘scene’ or ‘array’ (default)

Returns:

Normal (nx, ny, nz), vector is 0 if no plane is defined

Return type:

numpy.ndarray

Raises:

ValueError – If coordinates is not correct

setNormal(normal, coordinates='array')

Set the normal of the plane.

Parameters:

• normal – 3-tuple of float: nx, ny, nz

• coordinates (str) – The coordinate system to use: Either ‘scene’ or ‘array’ (default)

Raises:

ValueError – If coordinates is not correct

getPoint(coordinates='array')

Returns a point on the plane.

Parameters:

coordinates (str) – The coordinate system to use: Either ‘scene’ or ‘array’ (default)

Returns:

(x, y, z)

Return type:

numpy.ndarray

Raises:

ValueError – If coordinates is not correct

setPoint(point, constraint=True, coordinates='array')

Set a point contained in the plane.

Warning: The plane might not intersect the bounding box of the data.

Parameters:

• point (3-tuple of float) – (x, y, z) position

• constraint (bool) – True (default) to make sure the plane intersect data bounding box, False to set the plane without any constraint.

Raises:

ValueError – If coordinates is not correc

getParameters(coordinates='array')

Returns the plane equation parameters: a*x + b*y + c*z + d = 0

Parameters:

coordinates (str) – The coordinate system to use: Either ‘scene’ or ‘array’ (default)

Returns:

Plane equation parameters: (a, b, c, d)

Return type:

numpy.ndarray

Raises:

ValueError – If coordinates is not correct

setParameters(parameters, constraint=True, coordinates='array')

Set the plane equation parameters: a*x + b*y + c*z + d = 0

Warning: The plane might not intersect the bounding box of the data.

Parameters:

• parameters (4-tuple of float) – (a, b, c, d) plane equation parameters.

• constraint (bool) – True (default) to make sure the plane intersect data bounding box, False to set the plane without any constraint.

Raises:

ValueError – If coordinates is not correc

isVisible()

Returns True if the plane is visible, False otherwise

setVisible(visible)

Set the visibility of the plane

Parameters:

visible (bool) – True to make plane visible

getStrokeColor()

Returns the color of the plane border (QColor)

setStrokeColor(color)

Set the color of the plane border.

Parameters:

color (QColor, str or array-like of 3 or 4 float in [0., 1.] or uint8) – RGB color: name, #RRGGBB or RGB values

getImageData()

Returns the data and information corresponding to the cut plane.

The returned data is not interpolated, it is a slice of the 3D scalar field.

Image data axes are so that plane normal is towards the point of view.

Returns:

An object containing the 2D data slice and information

getInterpolation()

Returns the interpolation used to display to cut plane.

Returns:

‘nearest’ or ‘linear’

Return type:

str

setInterpolation(interpolation)

Set the interpolation used to display to cut plane

The default interpolation is ‘linear’

Parameters:

interpolation (str) – ‘nearest’ or ‘linear’

getDisplayValuesBelowMin()

Return whether values <= colormap min are displayed or not.

Return type:

bool

setDisplayValuesBelowMin(display)

Set whether to display values <= colormap min.

Parameters:

display (bool) – True to show values below min, False to discard them

getColormap()

Returns the colormap set by setColormap().

Returns:

The colormap

Return type:

Colormap

setColormap(name='gray', norm=None, vmin=None, vmax=None)

Set the colormap to use.

By either providing a Colormap object or its name, normalization and range.

Parameters:

• name (str or Colormap) – Name of the colormap in ‘gray’, ‘reversed gray’, ‘temperature’, ‘red’, ‘green’, ‘blue’. Or Colormap object.

• norm (str) – Colormap mapping: ‘linear’ or ‘log’.

• vmin (float) – The minimum value of the range or None for autoscale

• vmax (float) – The maximum value of the range or None for autoscale

getColormapEffectiveRange()

Returns the currently used range of the colormap.

This range is computed from the data set if colormap is in autoscale. Range is clipped to positive values when using log scale.

Returns:

2-tuple of float

IsoSurface

class Isosurface(parent)

Bases: QObject

Class representing an iso-surface

Parameters:

parent – The View widget this iso-surface belongs to

sigLevelChanged

Signal emitted when the iso-surface level has changed.

This signal provides the new level value (might be nan).

sigColorChanged

Signal emitted when the iso-surface color has changed

sigVisibilityChanged

Signal emitted when the iso-surface visibility has changed.

This signal provides the new visibility status.

isVisible()

Returns True if iso-surface is visible, else False

setVisible(visible)

Set the visibility of the iso-surface in the view.

Parameters:

visible (bool) – True to show the iso-surface, False to hide

getLevel()

Return the level of this iso-surface (float)

setLevel(level)

Set the value at which to build the iso-surface.

Setting this value reset auto-level function

Parameters:

level (float) – The value at which to build the iso-surface

isAutoLevel()

True if iso-level is rebuild for each data set.

getAutoLevelFunction()

Return the function computing the iso-level (callable or None)

setAutoLevelFunction(autoLevel)

Set the function used to compute the iso-level.

WARNING: The function might get called in a thread.

Parameters:

autoLevel (callable) – A function taking a 3D numpy.ndarray of float32 and returning a float used as iso-level. Example: numpy.mean(data) + numpy.std(data)

getColor()

Return the color of this iso-surface (QColor)

setColor(color)

Set the color of the iso-surface

Parameters:

color (QColor, str or array-like of 4 float in [0., 1.]) – RGBA color of the isosurface

SelectedRegion

class SelectedRegion(arrayRange, dataBBox, translation=(0.0, 0.0, 0.0), scale=(1.0, 1.0, 1.0))

Bases: object

Selection of a 3D region aligned with the axis.

Parameters:

• arrayRange – Range of the selection in the array ((zmin, zmax), (ymin, ymax), (xmin, xmax))

• dataBBox – Bounding box of the selection in data coordinates ((xmin, xmax), (ymin, ymax), (zmin, zmax))

• translation – Offset from array to data coordinates (ox, oy, oz)

• scale – Scale from array to data coordinates (sx, sy, sz)

getArrayRange()

Returns array ranges of the selection: 3x2 array of int

Returns:

A numpy array with ((zmin, zmax), (ymin, ymax), (xmin, xmax))

Return type:

numpy.ndarray

getArraySlices()

Slices corresponding to the selected range in the array

Returns:

A numpy array with (zslice, yslice, zslice)

Return type:

numpy.ndarray

getDataRange()

Range in the data coordinates of the selection: 3x2 array of float

When the transform matrix is not the identity matrix (e.g., rotation, skew) the returned range is the one of the selected region bounding box in data coordinates.

Returns:

A numpy array with ((xmin, xmax), (ymin, ymax), (zmin, zmax))

Return type:

numpy.ndarray

getDataScale()

Scale from array to data coordinates: (sx, sy, sz)

Returns:

A numpy array with (sx, sy, sz)

Return type:

numpy.ndarray

getDataTranslation()

Offset from array to data coordinates: (ox, oy, oz)

Returns:

A numpy array with (ox, oy, oz)

Return type:

numpy.ndarray