Skip to main content
`Ctrl`+`K`

# `items`: SceneWidget items

The following classes are items that describes the content of a `SceneWidget`:

- `ImageData`

- `ImageRgba`

- `Scatter2D`

- `Scatter3D`

- `ScalarField3D`

- `ClipPlane`

- `Mesh`

- `GroupItem`

## 2D images

### `ImageData`

`ImageData` inherits from `DataItem3D` and also provides its API.

class ImageData(parent=None)

  Description of a 2D image data.

  Parameters:

    parent – The View widget this item belongs to.

  setData(data, copy=True)

    Set the image data to display.

    The data will be casted to float32.

    Parameters:

      - data (numpy.ndarray) – The image data

      - copy (bool) – True (default) to copy the data, False to use as is (do not modify!).

  getData(copy=True)

    Get the image data.

    Parameters:

      copy (bool) – True (default) to get a copy, False to get internal representation (do not modify!).

    Return type:

      numpy.ndarray

    Returns:

      The image data

  getColormap()

    Return the used colormap

  getInterpolation()

    Returns the interpolation mode set by `setInterpolation()`

    Return type:

      str

  setColormap(colormap)

    Set the colormap of this item

    Parameters:

      colormap (silx.gui.colors.Colormap) – colormap description

  setInterpolation(mode)

    Set image interpolation mode

    Parameters:

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

### `ImageRgba`

`ImageRgba` inherits from `DataItem3D` and also provides its API.

class ImageRgba(parent=None)

  Description of a 2D data RGB(A) image.

  Parameters:

    parent – The View widget this item belongs to.

  setData(data, copy=True)

    Set the RGB(A) image data to display.

    Supported array format: float32 in [0, 1], uint8.

    Parameters:

      - data (numpy.ndarray) – The RGBA image data as an array of shape (H, W, Channels)

      - copy (bool) – True (default) to copy the data, False to use as is (do not modify!).

  getData(copy=True)

    Get the image data.

    Parameters:

      copy (bool) – True (default) to get a copy, False to get internal representation (do not modify!).

    Return type:

      numpy.ndarray

    Returns:

      The image data

  getInterpolation()

    Returns the interpolation mode set by `setInterpolation()`

    Return type:

      str

  setInterpolation(mode)

    Set image interpolation mode

    Parameters:

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

## 2D/3D scatter data

### `Scatter2D`

`Scatter2D` inherits from `DataItem3D` and also provides its API.

class Scatter2D(parent=None)

  2D scatter data with settable visualization mode.

  Parameters:

    parent – The View widget this item belongs to.

  isPropertyEnabled(name, visualization=None)

    Returns true if the property is used with visualization mode.

    Parameters:

      - name (str) – The name of the property to check, in: ‘lineWidth’, ‘symbol’, ‘symbolSize’

      - visualization (str) – The visualization mode for which to get the info. By default, it is the current visualization mode.

    Returns:

  setHeightMap(heightMap)

    Set whether to display the data has a height map or not.

    When displayed as a height map, the data values are used as z coordinates.

    Parameters:

      heightMap (bool) – True to display a height map, False to display as 2D data with z=0

  isHeightMap()

    Returns True if data is displayed as a height map.

    Return type:

      bool

  getLineWidth()

    Return the curve line width in pixels (float)

  setLineWidth(width)

    Set the width in pixel of the curve line

    See `getLineWidth()`.

    Parameters:

      width (float) – Width in pixels

  setData(x, y, value, copy=True)

    Set the data represented by this item.

    Provided arrays must have the same length.

    Parameters:

      - x (numpy.ndarray) – X coordinates (array-like)

      - y (numpy.ndarray) – Y coordinates (array-like)

      - value – Points value: array-like or single scalar

      - copy (bool) – True (default) to make a copy of the data, False to avoid copy if possible (do not modify the arrays).

  getData(copy=True)

    Returns data as provided to `setData()`.

    Parameters:

      copy (bool) – True to get a copy, False to return internal data (do not modify!)

    Returns:

      (x, y, value)

  getXData(copy=True)

    Returns X data coordinates.

    Parameters:

      copy (bool) – True to get a copy, False to return internal array (do not modify!)

    Returns:

      X coordinates

    Return type:

      numpy.ndarray

  getYData(copy=True)

    Returns Y data coordinates.

    Parameters:

      copy (bool) – True to get a copy, False to return internal array (do not modify!)

    Returns:

      Y coordinates

    Return type:

      numpy.ndarray

  getValueData(copy=True)

    Returns data values.

    Parameters:

      copy (bool) – True to get a copy, False to return internal array (do not modify!)

    Returns:

      data values

    Return type:

      numpy.ndarray

  getColormap()

    Return the used colormap

  classmethod getSupportedSymbols()

    Returns the list of supported symbol names.

    Return type:

      tuple of str

  getSymbol()

    Return the point marker type.

    Marker type:

        - 'o' circle
        - '.' point
        - ',' pixel
        - '+' cross
        - 'x' x-cross
        - 'd' diamond
        - 's' square

    Return type:

      str

  getVisualization()

    Returns the scatter plot visualization mode in use.

    Return type:

      Visualization

  setColormap(colormap)

    Set the colormap of this item

    Parameters:

      colormap (silx.gui.colors.Colormap) – colormap description

  setSymbol(symbol)

    Set the marker type

    See `getSymbol()`.

    Parameters:

      symbol (str) – Marker type or marker name

  setVisualization(mode)

    Set the scatter plot visualization mode to use.

    See `Visualization` for all possible values, and `supportedVisualizations()` for supported ones.

    Parameters:

      mode (Union[str,Visualization]) – The visualization mode to use.

    Returns:

      True if value was set, False if is was already set

    Return type:

      bool

  classmethod supportedVisualizations()

    Returns the list of supported scatter visualization modes.

    See `setVisualization()`

    Return type:

      List[Visualization]

### `Scatter3D`

`Scatter3D` inherits from `DataItem3D` and also provides its API.

class Scatter3D(parent=None)

  Description of a 3D scatter plot.

  Parameters:

    parent – The View widget this item belongs to.

  setData(x, y, z, value, copy=True)

    Set the data of the scatter plot

    Parameters:

      - x (numpy.ndarray) – Array of X coordinates (single value not accepted)

      - y – Points Y coordinate (array-like or single value)

      - z – Points Z coordinate (array-like or single value)

      - value – Points values (array-like or single value)

      - copy (bool) – True (default) to copy the data, False to use provided data (do not modify!)

  getData(copy=True)

    Returns data as provided to `setData()`.

    Parameters:

      copy (bool) – True to get a copy, False to return internal data (do not modify!)

    Returns:

      (x, y, z, value)

  getXData(copy=True)

    Returns X data coordinates.

    Parameters:

      copy (bool) – True to get a copy, False to return internal array (do not modify!)

    Returns:

      X coordinates

    Return type:

      numpy.ndarray

  getYData(copy=True)

    Returns Y data coordinates.

    Parameters:

      copy (bool) – True to get a copy, False to return internal array (do not modify!)

    Returns:

      Y coordinates

    Return type:

      numpy.ndarray

  getZData(copy=True)

    Returns Z data coordinates.

    Parameters:

      copy (bool) – True to get a copy, False to return internal array (do not modify!)

    Returns:

      Z coordinates

    Return type:

      numpy.ndarray

  getValueData(copy=True)

    Returns data values.

    Parameters:

      copy (bool) – True to get a copy, False to return internal array (do not modify!)

    Returns:

      data values

    Return type:

      numpy.ndarray

  getColormap()

    Return the used colormap

  classmethod getSupportedSymbols()

    Returns the list of supported symbol names.

    Return type:

      tuple of str

  getSymbol()

    Return the point marker type.

    Marker type:

        - 'o' circle
        - '.' point
        - ',' pixel
        - '+' cross
        - 'x' x-cross
        - 'd' diamond
        - 's' square

    Return type:

      str

  setColormap(colormap)

    Set the colormap of this item

    Parameters:

      colormap (silx.gui.colors.Colormap) – colormap description

  setSymbol(symbol)

    Set the marker type

    See `getSymbol()`.

    Parameters:

      symbol (str) – Marker type or marker name

## 3D volume

### `ScalarField3D`

`ScalarField3D` inherits from `DataItem3D` and also provides its API.

class ScalarField3D(parent=None)

  3D scalar field on a regular grid.

  Parameters:

    parent – The View widget this item belongs to.

  setData(data, copy=True)

    Set the 3D scalar data represented by this item.

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

    Parameters:

      - data (3D numpy.ndarray of float32 with shape at least (2, 2, 2)) – 3D array

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

  getData(copy=True)

    Return 3D dataset.

    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)

  getCutPlanes()

    Return an iterable of all `CutPlane` of this item.

    This includes hidden cut planes.

    For now, there is always one cut plane.

  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 isosurface to this item.

    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

    Return type:

      Isosurface

  getIsosurfaces()

    Return an iterable of all `Isosurface` instance of this item

  removeIsosurface(isosurface)

    Remove an iso-surface from this item.

    Parameters:

      isosurface (Isosurface) – The isosurface object to remove

  clearIsosurfaces()

    Remove all `Isosurface` instances from this item.

The following classes allows to configure `ScalarField3D` visualization:

### `IsoSurface`

`IsoSurface` inherits from `Item3D` and also provides its API.

class Isosurface(parent)

  Bases: `Item3D`

  Class representing an iso-surface in a `ScalarField3D` item.

  Parameters:

    parent – The DataItem3D this iso-surface belongs to

  setParent(parent)

    Override set parent to handle root item change

  getData(copy=True)

    Return 3D dataset.

    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)

  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

### `CutPlane`

`CutPlane` inherits from `Item3D` and also provides its API.

class CutPlane(parent)

  Class representing a cutting plane in a `ScalarField3D` item.

  Parameters:

    parent – 3D Data set in which the cut plane is applied.

  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()

    Return the used colormap

  getInterpolation()

    Returns the interpolation mode set by `setInterpolation()`

    Return type:

      str

  getNormal()

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

    Returns:

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

    Return type:

      numpy.ndarray

  getParameters()

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

    Returns:

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

    Return type:

      numpy.ndarray

  getPoint()

    Returns a point on the plane

    Returns:

      (x, y, z)

    Return type:

      numpy.ndarray

  isValid()

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

  moveToCenter()

    Move cut plane to center of data set

  setColormap(colormap)

    Set the colormap of this item

    Parameters:

      colormap (silx.gui.colors.Colormap) – colormap description

  setInterpolation(mode)

    Set image interpolation mode

    Parameters:

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

  setNormal(normal)

    Set the normal of the plane

    Parameters:

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

  setParameters(parameters)

    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. The given parameters will be normalized.

    Parameters:

      parameters – (a, b, c, d) equation parameters

  setPoint(point)

    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

## Height map

### `HeightMapData`

`HeightMapData` inherits from `DataItem3D` and also provides its API.

class HeightMapData(parent=None)

  Description of a 2D height field associated to a colormapped dataset.

  Parameters:

    parent – The View widget this item belongs to.

  setColormappedData(data, copy=True)

    Set the 2D data used to compute colors.

    Parameters:

      - data – 2D array of data

      - copy (`bool`) – True (default) to copy the data, False to use as is (do not modify!).

  getColormappedData(copy=True)

    Returns the 2D data used to compute colors.

    Parameters:

      copy (`bool`) – True (default) to get a copy, False to get internal representation (do not modify!).

    Return type:

      `ndarray`

  getData(copy=True)

    Get the height field 2D data.

    Parameters:

      - copy (`bool`) – True (default) to get a copy, False to get internal representation (do not modify!).

      - copy

    Return type:

      `ndarray`

  setData(data, copy=True)

    Set the height field data.

    Parameters:

      - data

      - copy (`bool`) – True (default) to copy the data, False to use as is (do not modify!).

### `HeightMapRGBA`

`HeightMapRGBA` inherits from `DataItem3D` and also provides its API.

class HeightMapRGBA(parent=None)

  Description of a 2D height field associated to a RGB(A) image.

  Parameters:

    parent – The View widget this item belongs to.

  setColorData(data, copy=True)

    Set the RGB(A) image to use.

    Supported array format: float32 in [0, 1], uint8.

    Parameters:

      - data – The RGBA image data as an array of shape (H, W, Channels)

      - copy (`bool`) – True (default) to copy the data, False to use as is (do not modify!).

  getColorData(copy=True)

    Get the RGB(A) image data.

    Parameters:

      copy (`bool`) – True (default) to get a copy, False to get internal representation (do not modify!).

    Return type:

      `ndarray`

  getData(copy=True)

    Get the height field 2D data.

    Parameters:

      - copy (`bool`) – True (default) to get a copy, False to get internal representation (do not modify!).

      - copy

    Return type:

      `ndarray`

  setData(data, copy=True)

    Set the height field data.

    Parameters:

      - data

      - copy (`bool`) – True (default) to copy the data, False to use as is (do not modify!).

## Clipping plane

### `ClipPlane`

`ClipPlane` inherits from `Item3D` and also provides its API.

class ClipPlane(parent=None)

  Bases: `Item3D`, `PlaneMixIn`

  Represents a clipping plane that clips following items within the group.

  For now only on clip plane is allowed at once in a scene.

## 3D mesh

### `Mesh`

`Mesh` inherits from `DataItem3D` and also provides its API.

class Mesh(parent=None)

  Bases: `_MeshBase`

  Description of mesh.

  Parameters:

    parent – The View widget this item belongs to.

  setData(position, color, normal=None, mode='triangles', indices=None, copy=True)

    Set mesh geometry data.

    Supported drawing modes are: ‘triangles’, ‘triangle_strip’, ‘fan’

    Parameters:

      - position (numpy.ndarray) – Position (x, y, z) of each vertex as a (N, 3) array

      - color (numpy.ndarray) – Colors for each point or a single color

      - normal (Union[numpy.ndarray,None]) – Normals for each point or None (default)

      - mode (str) – The drawing mode.

      - indices (Union[List[int],None]) – Array of vertex indices or None to use arrays directly.

      - copy (bool) – True (default) to copy the data, False to use as is (do not modify!).

  getData(copy=True)

    Get the mesh geometry.

    Parameters:

      copy (bool) – True (default) to get a copy, False to get internal representation (do not modify!).

    Returns:

      The positions, colors, normals and mode

    Return type:

      tuple of numpy.ndarray

  getColorData(copy=True)

    Get the mesh vertex colors.

    Parameters:

      copy (bool) – True (default) to get a copy, False to get internal representation (do not modify!).

    Returns:

      The RGBA colors as a (N, 4) array or a single color

    Return type:

      numpy.ndarray

## Item base classes

The following classes provides the base classes for other items.

### `Item3D`

class Item3D(parent, primitive=None)

  Bases: `QObject`

  Base class representing an item in the scene.

  Parameters:

    - parent – The View widget this item belongs to.

    - primitive – An optional primitive to use as scene primitive

  sigItemChanged

    Signal emitted when an item’s property has changed.

    It provides a flag describing which property of the item has changed. See `ItemChangedType` and `Item3DChangedType` for flags description.

  setParent(parent)

    Override set parent to handle root item change

  root()

    Returns the root of the scene this item belongs to.

    The root is the up-most Item3D in the scene tree hierarchy.

    Return type:

      Union[Item3D, None]

  getLabel()

    Returns the label associated to this item.

    Return type:

      str

  setLabel(label)

    Set the label associated to this item.

    Parameters:

      label (str)

  isVisible()

    Returns True if item is visible, else False

    Return type:

      bool

  setVisible(visible=True)

    Set the visibility of the item in the scene.

    Parameters:

      visible (bool) – True (default) to show the item, False to hide

### `DataItem3D`

`DataItem3D` inherits from `Item3D` and also provides its API.

class DataItem3D(parent, group=None)

  Bases: `Item3D`

  Base class representing a data item with transform in the scene.

  Parameters:

    - parent – The View widget this item belongs to.

    - group (Union[GroupBBox, None]) – The scene group to use for rendering

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

    Set the scale of the item in the scene.

    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()`.

    Return type:

      numpy.ndarray

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

    Set the translation of the origin of the item in the scene.

    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()`.

    Return type:

      numpy.ndarray

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

    Set the center of rotation of the item.

    Position of the rotation center is either a float for an absolute position or one of the following string to define a position relative to the item’s bounding box: ‘lower’, ‘center’, ‘upper’

    Parameters:

      - x – rotation center position on the X axis

      - y – rotation center position on the Y axis

      - z – rotation center position on the Z axis

    Return type:

      float or str

    Return type:

      float or str

    Return type:

      float or str

  getRotationCenter()

    Returns the rotation center set by `setRotationCenter()`.

    Return type:

      3-tuple of float or str

  setRotation(angle=0.0, axis=(0.0, 0.0, 1.0))

    Set the rotation of the item in the scene

    Parameters:

      - angle (float) – The rotation angle in degrees.

      - axis – The (x, y, z) coordinates of the rotation axis.

  getRotation()

    Returns the rotation set by `setRotation()`.

    Returns:

      (angle, axis)

    Return type:

      2-tuple (float, numpy.ndarray)

  setMatrix(matrix=None)

    Set the transform matrix

    Parameters:

      matrix (numpy.ndarray) – 3x3 transform matrix

  getMatrix()

    Returns the matrix set by `setMatrix()`

    Returns:

      3x3 matrix

    Return type:

      numpy.ndarray

  isBoundingBoxVisible()

    Returns item’s bounding box visibility.

    Return type:

      bool

  setBoundingBoxVisible(visible)

    Set item’s bounding box visibility.

    Parameters:

      visible (bool) – True to show the bounding box, False (default) to hide it

### `GroupItem`

`GroupItem` inherits from `DataItem3D` and also provides its API.

class GroupItem(parent=None)

  Bases: `_BaseGroupItem`

  Group of items sharing a common transform.