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: silx.gui.plot3d.Plot3DWindow.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: PyQt5.QtCore.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: PyQt5.QtCore.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