Skip to main content
`Ctrl`+`K`

# `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