# coding: utf-8
# /*##########################################################################
#
# Copyright (c) 2017-2020 European Synchrotron Radiation Facility
#
# Permission is hereby granted, free of charge, to any person obtaining a copy
# of this software and associated documentation files (the "Software"), to deal
# in the Software without restriction, including without limitation the rights
# to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
# copies of the Software, and to permit persons to whom the Software is
# furnished to do so, subject to the following conditions:
#
# The above copyright notice and this permission notice shall be included in
# all copies or substantial portions of the Software.
#
# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
# IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
# FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
# AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
# LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
# OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
# THE SOFTWARE.
#
# ###########################################################################*/
"""This module provides the base class for items of the :class:`Plot`.
"""
__authors__ = ["T. Vincent"]
__license__ = "MIT"
__date__ = "29/01/2019"
import collections
try:
from collections import abc
except ImportError: # Python2 support
import collections as abc
from copy import deepcopy
import logging
import enum
import warnings
import weakref
import numpy
import six
from ....utils.deprecation import deprecated
from ....utils.enum import Enum as _Enum
from ... import qt
from ... import colors
from ...colors import Colormap
from ._pick import PickingResult
from silx import config
_logger = logging.getLogger(__name__)
[docs]@enum.unique
class ItemChangedType(enum.Enum):
"""Type of modification provided by :attr:`Item.sigItemChanged` signal."""
# Private setters and setInfo are not emitting sigItemChanged signal.
# Signals to consider:
# COLORMAP_SET emitted when setColormap is called but not forward colormap object signal
# CURRENT_COLOR_CHANGED emitted current color changed because highlight changed,
# highlighted color changed or color changed depending on hightlight state.
VISIBLE = 'visibleChanged'
"""Item's visibility changed flag."""
ZVALUE = 'zValueChanged'
"""Item's Z value changed flag."""
COLORMAP = 'colormapChanged' # Emitted when set + forward events from the colormap object
"""Item's colormap changed flag.
This is emitted both when setting a new colormap and
when the current colormap object is updated.
"""
SYMBOL = 'symbolChanged'
"""Item's symbol changed flag."""
SYMBOL_SIZE = 'symbolSizeChanged'
"""Item's symbol size changed flag."""
LINE_WIDTH = 'lineWidthChanged'
"""Item's line width changed flag."""
LINE_STYLE = 'lineStyleChanged'
"""Item's line style changed flag."""
COLOR = 'colorChanged'
"""Item's color changed flag."""
LINE_BG_COLOR = 'lineBgColorChanged'
"""Item's line background color changed flag."""
YAXIS = 'yAxisChanged'
"""Item's Y axis binding changed flag."""
FILL = 'fillChanged'
"""Item's fill changed flag."""
ALPHA = 'alphaChanged'
"""Item's transparency alpha changed flag."""
DATA = 'dataChanged'
"""Item's data changed flag"""
HIGHLIGHTED = 'highlightedChanged'
"""Item's highlight state changed flag."""
HIGHLIGHTED_COLOR = 'highlightedColorChanged'
"""Deprecated, use HIGHLIGHTED_STYLE instead."""
HIGHLIGHTED_STYLE = 'highlightedStyleChanged'
"""Item's highlighted style changed flag."""
SCALE = 'scaleChanged'
"""Item's scale changed flag."""
TEXT = 'textChanged'
"""Item's text changed flag."""
POSITION = 'positionChanged'
"""Item's position changed flag.
This is emitted when a marker position changed and
when an image origin changed.
"""
OVERLAY = 'overlayChanged'
"""Item's overlay state changed flag."""
VISUALIZATION_MODE = 'visualizationModeChanged'
"""Item's visualization mode changed flag."""
COMPLEX_MODE = 'complexModeChanged'
"""Item's complex data visualization mode changed flag."""
NAME = 'nameChanged'
"""Item's name changed flag."""
EDITABLE = 'editableChanged'
"""Item's editable state changed flags."""
SELECTABLE = 'selectableChanged'
"""Item's selectable state changed flags."""
[docs]class Item(qt.QObject):
"""Description of an item of the plot"""
_DEFAULT_Z_LAYER = 0
"""Default layer for overlay rendering"""
_DEFAULT_SELECTABLE = False
"""Default selectable state of items"""
sigItemChanged = qt.Signal(object)
"""Signal emitted when the item has changed.
It provides a flag describing which property of the item has changed.
See :class:`ItemChangedType` for flags description.
"""
def __init__(self):
qt.QObject.__init__(self)
self._dirty = True
self._plotRef = None
self._visible = True
self._selectable = self._DEFAULT_SELECTABLE
self._z = self._DEFAULT_Z_LAYER
self._info = None
self._xlabel = None
self._ylabel = None
self.__name = ''
self._backendRenderer = None
[docs] def getPlot(self):
"""Returns the ~silx.gui.plot.PlotWidget this item belongs to.
:rtype: Union[~silx.gui.plot.PlotWidget,None]
"""
return None if self._plotRef is None else self._plotRef()
def _setPlot(self, plot):
"""Set the plot this item belongs to.
WARNING: This should only be called from the Plot.
:param Union[~silx.gui.plot.PlotWidget,None] plot: The Plot instance.
"""
if plot is not None and self._plotRef is not None:
raise RuntimeError('Trying to add a node at two places.')
self._plotRef = None if plot is None else weakref.ref(plot)
self._updated()
[docs] def getBounds(self): # TODO return a Bounds object rather than a tuple
"""Returns the bounding box of this item in data coordinates
:returns: (xmin, xmax, ymin, ymax) or None
:rtype: 4-tuple of float or None
"""
return self._getBounds()
def _getBounds(self):
""":meth:`getBounds` implementation to override by sub-class"""
return None
[docs] def isVisible(self):
"""True if item is visible, False otherwise
:rtype: bool
"""
return self._visible
[docs] def setVisible(self, visible):
"""Set visibility of item.
:param bool visible: True to display it, False otherwise
"""
visible = bool(visible)
if visible != self._visible:
self._visible = visible
# When visibility has changed, always mark as dirty
self._updated(ItemChangedType.VISIBLE,
checkVisibility=False)
[docs] def isOverlay(self):
"""Return true if item is drawn as an overlay.
:rtype: bool
"""
return False
[docs] def getName(self):
"""Returns the name of the item which is used as legend.
:rtype: str
"""
return self.__name
[docs] def setName(self, name):
"""Set the name of the item which is used as legend.
:param str name: New name of the item
:raises RuntimeError: If item belongs to a PlotWidget.
"""
name = str(name)
if self.__name != name:
if self.getPlot() is not None:
raise RuntimeError(
"Cannot change name while item is in a PlotWidget")
self.__name = name
self._updated(ItemChangedType.NAME)
def getLegend(self): # Replaced by getName for API consistency
return self.getName()
@deprecated(replacement='setName', since_version='0.13')
def _setLegend(self, legend):
legend = str(legend) if legend is not None else ''
self.setName(legend)
[docs] def isSelectable(self):
"""Returns true if item is selectable (bool)"""
return self._selectable
def _setSelectable(self, selectable): # TODO support update
"""Set whether item is selectable or not.
This is private for now as change is not handled.
:param bool selectable: True to make item selectable
"""
self._selectable = bool(selectable)
[docs] def getZValue(self):
"""Returns the layer on which to draw this item (int)"""
return self._z
def setZValue(self, z):
z = int(z) if z is not None else self._DEFAULT_Z_LAYER
if z != self._z:
self._z = z
self._updated(ItemChangedType.ZVALUE)
[docs] def getInfo(self, copy=True):
"""Returns the info associated to this item
:param bool copy: True to get a deepcopy, False otherwise.
"""
return deepcopy(self._info) if copy else self._info
def setInfo(self, info, copy=True):
if copy:
info = deepcopy(info)
self._info = info
def _updated(self, event=None, checkVisibility=True):
"""Mark the item as dirty (i.e., needing update).
This also triggers Plot.replot.
:param event: The event to send to :attr:`sigItemChanged` signal.
:param bool checkVisibility: True to only mark as dirty if visible,
False to always mark as dirty.
"""
if not checkVisibility or self.isVisible():
if not self._dirty:
self._dirty = True
# TODO: send event instead of explicit call
plot = self.getPlot()
if plot is not None:
plot._itemRequiresUpdate(self)
if event is not None:
self.sigItemChanged.emit(event)
def _update(self, backend):
"""Called by Plot to update the backend for this item.
This is meant to be called asynchronously from _updated.
This optimizes the number of call to _update.
:param backend: The backend to update
"""
if self._dirty:
# Remove previous renderer from backend if any
self._removeBackendRenderer(backend)
# If not visible, do not add renderer to backend
if self.isVisible():
self._backendRenderer = self._addBackendRenderer(backend)
self._dirty = False
def _addBackendRenderer(self, backend):
"""Override in subclass to add specific backend renderer.
:param BackendBase backend: The backend to update
:return: The renderer handle to store or None if no renderer in backend
"""
return None
def _removeBackendRenderer(self, backend):
"""Override in subclass to remove specific backend renderer.
:param BackendBase backend: The backend to update
"""
if self._backendRenderer is not None:
backend.remove(self._backendRenderer)
self._backendRenderer = None
[docs] def pick(self, x, y):
"""Run picking test on this item
:param float x: The x pixel coord where to pick.
:param float y: The y pixel coord where to pick.
:return: None if not picked, else the picked position information
:rtype: Union[None,PickingResult]
"""
if not self.isVisible() or self._backendRenderer is None:
return None
plot = self.getPlot()
if plot is None:
return None
indices = plot._backend.pickItem(x, y, self._backendRenderer)
if indices is None:
return None
else:
return PickingResult(self, indices)
# Mix-in classes ##############################################################
class ItemMixInBase(object):
"""Base class for Item mix-in"""
def _updated(self, event=None, checkVisibility=True):
"""This is implemented in :class:`Item`.
Mark the item as dirty (i.e., needing update).
This also triggers Plot.replot.
:param event: The event to send to :attr:`sigItemChanged` signal.
:param bool checkVisibility: True to only mark as dirty if visible,
False to always mark as dirty.
"""
raise RuntimeError(
"Issue with Mix-In class inheritance order")
class LabelsMixIn(ItemMixInBase):
"""Mix-in class for items with x and y labels
Setters are private, otherwise it needs to check the plot
current active curve and access the internal current labels.
"""
def __init__(self):
self._xlabel = None
self._ylabel = None
def getXLabel(self):
"""Return the X axis label associated to this curve
:rtype: str or None
"""
return self._xlabel
def _setXLabel(self, label):
"""Set the X axis label associated with this curve
:param str label: The X axis label
"""
self._xlabel = str(label)
def getYLabel(self):
"""Return the Y axis label associated to this curve
:rtype: str or None
"""
return self._ylabel
def _setYLabel(self, label):
"""Set the Y axis label associated with this curve
:param str label: The Y axis label
"""
self._ylabel = str(label)
class DraggableMixIn(ItemMixInBase):
"""Mix-in class for draggable items"""
def __init__(self):
self._draggable = False
def isDraggable(self):
"""Returns true if image is draggable
:rtype: bool
"""
return self._draggable
def _setDraggable(self, draggable): # TODO support update
"""Set if image is draggable or not.
This is private for not as it does not support update.
:param bool draggable:
"""
self._draggable = bool(draggable)
def drag(self, from_, to):
"""Perform a drag of the item.
:param List[float] from_: (x, y) previous position in data coordinates
:param List[float] to: (x, y) current position in data coordinates
"""
raise NotImplementedError("Must be implemented in subclass")
class ColormapMixIn(ItemMixInBase):
"""Mix-in class for items with colormap"""
def __init__(self):
self._colormap = Colormap()
self._colormap.sigChanged.connect(self._colormapChanged)
self.__data = None
self.__cacheColormapRange = {} # Store {normalization: range}
def getColormap(self):
"""Return the used colormap"""
return self._colormap
def setColormap(self, colormap):
"""Set the colormap of this item
:param silx.gui.colors.Colormap colormap: colormap description
"""
if self._colormap is colormap:
return
if isinstance(colormap, dict):
colormap = Colormap._fromDict(colormap)
if self._colormap is not None:
self._colormap.sigChanged.disconnect(self._colormapChanged)
self._colormap = colormap
if self._colormap is not None:
self._colormap.sigChanged.connect(self._colormapChanged)
self._colormapChanged()
def _colormapChanged(self):
"""Handle updates of the colormap"""
self._updated(ItemChangedType.COLORMAP)
def _setColormappedData(self, data, copy=True,
min_=None, minPositive=None, max_=None):
"""Set the data used to compute the colormapped display.
It also resets the cache of data ranges.
This method MUST be called by inheriting classes when data is updated.
:param Union[None,numpy.ndarray] data:
:param Union[None,float] min_: Minimum value of the data
:param Union[None,float] minPositive:
Minimum of strictly positive values of the data
:param Union[None,float] max_: Maximum value of the data
"""
self.__data = None if data is None else numpy.array(data, copy=copy)
self.__cacheColormapRange = {} # Reset cache
# Fill-up colormap range cache if values are provided
if max_ is not None and numpy.isfinite(max_):
if min_ is not None and numpy.isfinite(min_):
self.__cacheColormapRange[Colormap.LINEAR, Colormap.MINMAX] = min_, max_
if minPositive is not None and numpy.isfinite(minPositive):
self.__cacheColormapRange[Colormap.LOGARITHM, Colormap.MINMAX] = minPositive, max_
colormap = self.getColormap()
if None in (colormap.getVMin(), colormap.getVMax()):
self._colormapChanged()
def getColormappedData(self, copy=True):
"""Returns the data used to compute the displayed colors
:param bool copy: True to get a copy,
False to get internal data (do not modify!).
:rtype: Union[None,numpy.ndarray]
"""
if self.__data is None:
return None
else:
return numpy.array(self.__data, copy=copy)
def _getColormapAutoscaleRange(self, colormap=None):
"""Returns the autoscale range for current data and colormap.
:param Union[None,~silx.gui.colors.Colormap] colormap:
The colormap for which to compute the autoscale range.
If None, the default, the colormap of the item is used
:return: (vmin, vmax) range (vmin and /or vmax might be `None`)
"""
if colormap is None:
colormap = self.getColormap()
data = self.getColormappedData(copy=False)
if colormap is None or data is None:
return None, None
normalization = colormap.getNormalization()
autoscaleMode = colormap.getAutoscaleMode()
key = normalization, autoscaleMode
vRange = self.__cacheColormapRange.get(key, None)
if vRange is None:
vRange = colormap._computeAutoscaleRange(data)
self.__cacheColormapRange[key] = vRange
return vRange
class SymbolMixIn(ItemMixInBase):
"""Mix-in class for items with symbol type"""
_DEFAULT_SYMBOL = None
"""Default marker of the item"""
_DEFAULT_SYMBOL_SIZE = config.DEFAULT_PLOT_SYMBOL_SIZE
"""Default marker size of the item"""
_SUPPORTED_SYMBOLS = collections.OrderedDict((
('o', 'Circle'),
('d', 'Diamond'),
('s', 'Square'),
('+', 'Plus'),
('x', 'Cross'),
('.', 'Point'),
(',', 'Pixel'),
('|', 'Vertical line'),
('_', 'Horizontal line'),
('tickleft', 'Tick left'),
('tickright', 'Tick right'),
('tickup', 'Tick up'),
('tickdown', 'Tick down'),
('caretleft', 'Caret left'),
('caretright', 'Caret right'),
('caretup', 'Caret up'),
('caretdown', 'Caret down'),
(u'\u2665', 'Heart'),
('', 'None')))
"""Dict of supported symbols"""
def __init__(self):
if self._DEFAULT_SYMBOL is None: # Use default from config
self._symbol = config.DEFAULT_PLOT_SYMBOL
else:
self._symbol = self._DEFAULT_SYMBOL
if self._DEFAULT_SYMBOL_SIZE is None: # Use default from config
self._symbol_size = config.DEFAULT_PLOT_SYMBOL_SIZE
else:
self._symbol_size = self._DEFAULT_SYMBOL_SIZE
@classmethod
def getSupportedSymbols(cls):
"""Returns the list of supported symbol names.
:rtype: tuple of str
"""
return tuple(cls._SUPPORTED_SYMBOLS.keys())
@classmethod
def getSupportedSymbolNames(cls):
"""Returns the list of supported symbol human-readable names.
:rtype: tuple of str
"""
return tuple(cls._SUPPORTED_SYMBOLS.values())
def getSymbolName(self, symbol=None):
"""Returns human-readable name for a symbol.
:param str symbol: The symbol from which to get the name.
Default: current symbol.
:rtype: str
:raise KeyError: if symbol is not in :meth:`getSupportedSymbols`.
"""
if symbol is None:
symbol = self.getSymbol()
return self._SUPPORTED_SYMBOLS[symbol]
def getSymbol(self):
"""Return the point marker type.
Marker type::
- 'o' circle
- '.' point
- ',' pixel
- '+' cross
- 'x' x-cross
- 'd' diamond
- 's' square
:rtype: str
"""
return self._symbol
def setSymbol(self, symbol):
"""Set the marker type
See :meth:`getSymbol`.
:param str symbol: Marker type or marker name
"""
if symbol is None:
symbol = self._DEFAULT_SYMBOL
elif symbol not in self.getSupportedSymbols():
for symbolCode, name in self._SUPPORTED_SYMBOLS.items():
if name.lower() == symbol.lower():
symbol = symbolCode
break
else:
raise ValueError('Unsupported symbol %s' % str(symbol))
if symbol != self._symbol:
self._symbol = symbol
self._updated(ItemChangedType.SYMBOL)
def getSymbolSize(self):
"""Return the point marker size in points.
:rtype: float
"""
return self._symbol_size
def setSymbolSize(self, size):
"""Set the point marker size in points.
See :meth:`getSymbolSize`.
:param str symbol: Marker type
"""
if size is None:
size = self._DEFAULT_SYMBOL_SIZE
if size != self._symbol_size:
self._symbol_size = size
self._updated(ItemChangedType.SYMBOL_SIZE)
class LineMixIn(ItemMixInBase):
"""Mix-in class for item with line"""
_DEFAULT_LINEWIDTH = 1.
"""Default line width"""
_DEFAULT_LINESTYLE = '-'
"""Default line style"""
_SUPPORTED_LINESTYLE = '', ' ', '-', '--', '-.', ':', None
"""Supported line styles"""
def __init__(self):
self._linewidth = self._DEFAULT_LINEWIDTH
self._linestyle = self._DEFAULT_LINESTYLE
@classmethod
def getSupportedLineStyles(cls):
"""Returns list of supported line styles.
:rtype: List[str,None]
"""
return cls._SUPPORTED_LINESTYLE
def getLineWidth(self):
"""Return the curve line width in pixels
:rtype: float
"""
return self._linewidth
def setLineWidth(self, width):
"""Set the width in pixel of the curve line
See :meth:`getLineWidth`.
:param float width: Width in pixels
"""
width = float(width)
if width != self._linewidth:
self._linewidth = width
self._updated(ItemChangedType.LINE_WIDTH)
def getLineStyle(self):
"""Return the type of the line
Type of line::
- ' ' no line
- '-' solid line
- '--' dashed line
- '-.' dash-dot line
- ':' dotted line
:rtype: str
"""
return self._linestyle
def setLineStyle(self, style):
"""Set the style of the curve line.
See :meth:`getLineStyle`.
:param str style: Line style
"""
style = str(style)
assert style in self.getSupportedLineStyles()
if style is None:
style = self._DEFAULT_LINESTYLE
if style != self._linestyle:
self._linestyle = style
self._updated(ItemChangedType.LINE_STYLE)
class ColorMixIn(ItemMixInBase):
"""Mix-in class for item with color"""
_DEFAULT_COLOR = (0., 0., 0., 1.)
"""Default color of the item"""
def __init__(self):
self._color = self._DEFAULT_COLOR
def getColor(self):
"""Returns the RGBA color of the item
:rtype: 4-tuple of float in [0, 1] or array of colors
"""
return self._color
def setColor(self, color, copy=True):
"""Set item color
:param color: color(s) to be used
:type color: str ("#RRGGBB") or (npoints, 4) unsigned byte array or
one of the predefined color names defined in colors.py
:param bool copy: True (Default) to get a copy,
False to use internal representation (do not modify!)
"""
if isinstance(color, six.string_types):
color = colors.rgba(color)
elif isinstance(color, qt.QColor):
color = colors.rgba(color)
else:
color = numpy.array(color, copy=copy)
# TODO more checks + improve color array support
if color.ndim == 1: # Single RGBA color
color = colors.rgba(color)
else: # Array of colors
assert color.ndim == 2
self._color = color
self._updated(ItemChangedType.COLOR)
class YAxisMixIn(ItemMixInBase):
"""Mix-in class for item with yaxis"""
_DEFAULT_YAXIS = 'left'
"""Default Y axis the item belongs to"""
def __init__(self):
self._yaxis = self._DEFAULT_YAXIS
def getYAxis(self):
"""Returns the Y axis this curve belongs to.
Either 'left' or 'right'.
:rtype: str
"""
return self._yaxis
def setYAxis(self, yaxis):
"""Set the Y axis this curve belongs to.
:param str yaxis: 'left' or 'right'
"""
yaxis = str(yaxis)
assert yaxis in ('left', 'right')
if yaxis != self._yaxis:
self._yaxis = yaxis
self._updated(ItemChangedType.YAXIS)
class FillMixIn(ItemMixInBase):
"""Mix-in class for item with fill"""
def __init__(self):
self._fill = False
def isFill(self):
"""Returns whether the item is filled or not.
:rtype: bool
"""
return self._fill
def setFill(self, fill):
"""Set whether to fill the item or not.
:param bool fill:
"""
fill = bool(fill)
if fill != self._fill:
self._fill = fill
self._updated(ItemChangedType.FILL)
class AlphaMixIn(ItemMixInBase):
"""Mix-in class for item with opacity"""
def __init__(self):
self._alpha = 1.
def getAlpha(self):
"""Returns the opacity of the item
:rtype: float in [0, 1.]
"""
return self._alpha
def setAlpha(self, alpha):
"""Set the opacity of the item
.. note::
If the colormap already has some transparency, this alpha
adds additional transparency. The alpha channel of the colormap
is multiplied by this value.
:param alpha: Opacity of the item, between 0 (full transparency)
and 1. (full opacity)
:type alpha: float
"""
alpha = float(alpha)
alpha = max(0., min(alpha, 1.)) # Clip alpha to [0., 1.] range
if alpha != self._alpha:
self._alpha = alpha
self._updated(ItemChangedType.ALPHA)
class ComplexMixIn(ItemMixInBase):
"""Mix-in class for complex data mode"""
_SUPPORTED_COMPLEX_MODES = None
"""Override to only support a subset of all ComplexMode"""
class ComplexMode(_Enum):
"""Identify available display mode for complex"""
NONE = 'none'
ABSOLUTE = 'amplitude'
PHASE = 'phase'
REAL = 'real'
IMAGINARY = 'imaginary'
AMPLITUDE_PHASE = 'amplitude_phase'
LOG10_AMPLITUDE_PHASE = 'log10_amplitude_phase'
SQUARE_AMPLITUDE = 'square_amplitude'
def __init__(self):
self.__complex_mode = self.ComplexMode.ABSOLUTE
def getComplexMode(self):
"""Returns the current complex visualization mode.
:rtype: ComplexMode
"""
return self.__complex_mode
def setComplexMode(self, mode):
"""Set the complex visualization mode.
:param ComplexMode mode: The visualization mode in:
'real', 'imaginary', 'phase', 'amplitude'
:return: True if value was set, False if is was already set
:rtype: bool
"""
mode = self.ComplexMode.from_value(mode)
assert mode in self.supportedComplexModes()
if mode != self.__complex_mode:
self.__complex_mode = mode
self._updated(ItemChangedType.COMPLEX_MODE)
return True
else:
return False
def _convertComplexData(self, data, mode=None):
"""Convert complex data to the specific mode.
:param Union[ComplexMode,None] mode:
The kind of value to compute.
If None (the default), the current complex mode is used.
:return: The converted dataset
:rtype: Union[numpy.ndarray[float],None]
"""
if data is None:
return None
if mode is None:
mode = self.getComplexMode()
if mode is self.ComplexMode.REAL:
return numpy.real(data)
elif mode is self.ComplexMode.IMAGINARY:
return numpy.imag(data)
elif mode is self.ComplexMode.ABSOLUTE:
return numpy.absolute(data)
elif mode is self.ComplexMode.PHASE:
return numpy.angle(data)
elif mode is self.ComplexMode.SQUARE_AMPLITUDE:
return numpy.absolute(data) ** 2
else:
raise ValueError('Unsupported conversion mode: %s', str(mode))
@classmethod
def supportedComplexModes(cls):
"""Returns the list of supported complex visualization modes.
See :class:`ComplexMode` and :meth:`setComplexMode`.
:rtype: List[ComplexMode]
"""
if cls._SUPPORTED_COMPLEX_MODES is None:
return cls.ComplexMode.members()
else:
return cls._SUPPORTED_COMPLEX_MODES
class ScatterVisualizationMixIn(ItemMixInBase):
"""Mix-in class for scatter plot visualization modes"""
_SUPPORTED_SCATTER_VISUALIZATION = None
"""Allows to override supported Visualizations"""
@enum.unique
class Visualization(_Enum):
"""Different modes of scatter plot visualizations"""
POINTS = 'points'
"""Display scatter plot as a point cloud"""
LINES = 'lines'
"""Display scatter plot as a wireframe.
This is based on Delaunay triangulation
"""
SOLID = 'solid'
"""Display scatter plot as a set of filled triangles.
This is based on Delaunay triangulation
"""
REGULAR_GRID = 'regular_grid'
"""Display scatter plot as an image.
It expects the points to be the intersection of a regular grid,
and the order of points following that of an image.
First line, then second one, and always in the same direction
(either all lines from left to right or all from right to left).
"""
IRREGULAR_GRID = 'irregular_grid'
"""Display scatter plot as contiguous quadrilaterals.
It expects the points to be the intersection of an irregular grid,
and the order of points following that of an image.
First line, then second one, and always in the same direction
(either all lines from left to right or all from right to left).
"""
BINNED_STATISTIC = 'binned_statistic'
"""Display scatter plot as 2D binned statistic (i.e., generalized histogram).
"""
@enum.unique
class VisualizationParameter(_Enum):
"""Different parameter names for scatter plot visualizations"""
GRID_MAJOR_ORDER = 'grid_major_order'
"""The major order of points in the regular grid.
Either 'row' (row-major, fast X) or 'column' (column-major, fast Y).
"""
GRID_BOUNDS = 'grid_bounds'
"""The expected range in data coordinates of the regular grid.
A 2-tuple of 2-tuple: (begin (x, y), end (x, y)).
This provides the data coordinates of the first point and the expected
last on.
As for `GRID_SHAPE`, this can be wider than the current data.
"""
GRID_SHAPE = 'grid_shape'
"""The expected size of the regular grid (height, width).
The given shape can be wider than the number of points,
in which case the grid is not fully filled.
"""
BINNED_STATISTIC_SHAPE = 'binned_statistic_shape'
"""The number of bins in each dimension (height, width).
"""
BINNED_STATISTIC_FUNCTION = 'binned_statistic_function'
"""The reduction function to apply to each bin (str).
Available reduction functions are: 'mean' (default), 'count', 'sum'.
"""
_SUPPORTED_VISUALIZATION_PARAMETER_VALUES = {
VisualizationParameter.GRID_MAJOR_ORDER: ('row', 'column'),
VisualizationParameter.BINNED_STATISTIC_FUNCTION: ('mean', 'count', 'sum'),
}
"""Supported visualization parameter values.
Defined for parameters with a set of acceptable values.
"""
def __init__(self):
self.__visualization = self.Visualization.POINTS
self.__parameters = dict( # Init parameters to None
(parameter, None) for parameter in self.VisualizationParameter)
self.__parameters[self.VisualizationParameter.BINNED_STATISTIC_FUNCTION] = 'mean'
@classmethod
def supportedVisualizations(cls):
"""Returns the list of supported scatter visualization modes.
See :meth:`setVisualization`
:rtype: List[Visualization]
"""
if cls._SUPPORTED_SCATTER_VISUALIZATION is None:
return cls.Visualization.members()
else:
return cls._SUPPORTED_SCATTER_VISUALIZATION
@classmethod
def supportedVisualizationParameterValues(cls, parameter):
"""Returns the list of supported scatter visualization modes.
See :meth:`VisualizationParameters`
:param VisualizationParameter parameter:
This parameter for which to retrieve the supported values.
:returns: tuple of supported of values or None if not defined.
"""
parameter = cls.VisualizationParameter(parameter)
return cls._SUPPORTED_VISUALIZATION_PARAMETER_VALUES.get(
parameter, None)
def setVisualization(self, mode):
"""Set the scatter plot visualization mode to use.
See :class:`Visualization` for all possible values,
and :meth:`supportedVisualizations` for supported ones.
:param Union[str,Visualization] mode:
The visualization mode to use.
:return: True if value was set, False if is was already set
:rtype: bool
"""
mode = self.Visualization.from_value(mode)
assert mode in self.supportedVisualizations()
if mode != self.__visualization:
self.__visualization = mode
self._updated(ItemChangedType.VISUALIZATION_MODE)
return True
else:
return False
def getVisualization(self):
"""Returns the scatter plot visualization mode in use.
:rtype: Visualization
"""
return self.__visualization
def setVisualizationParameter(self, parameter, value=None):
"""Set the given visualization parameter.
:param Union[str,VisualizationParameter] parameter:
The name of the parameter to set
:param value: The value to use for this parameter
Set to None to automatically set the parameter
:raises ValueError: If parameter is not supported
:return: True if parameter was set, False if is was already set
:rtype: bool
:raise ValueError: If value is not supported
"""
parameter = self.VisualizationParameter.from_value(parameter)
if self.__parameters[parameter] != value:
validValues = self.supportedVisualizationParameterValues(parameter)
if validValues is not None and value not in validValues:
raise ValueError("Unsupported parameter value: %s" % str(value))
self.__parameters[parameter] = value
self._updated(ItemChangedType.VISUALIZATION_MODE)
return True
return False
def getVisualizationParameter(self, parameter):
"""Returns the value of the given visualization parameter.
This method returns the parameter as set by
:meth:`setVisualizationParameter`.
:param parameter: The name of the parameter to retrieve
:returns: The value previously set or None if automatically set
:raises ValueError: If parameter is not supported
"""
if parameter not in self.VisualizationParameter:
raise ValueError("parameter not supported: %s", parameter)
return self.__parameters[parameter]
def getCurrentVisualizationParameter(self, parameter):
"""Returns the current value of the given visualization parameter.
If the parameter was set by :meth:`setVisualizationParameter` to
a value that is not None, this value is returned;
else the current value that is automatically computed is returned.
:param parameter: The name of the parameter to retrieve
:returns: The current value (either set or automatically computed)
:raises ValueError: If parameter is not supported
"""
# Override in subclass to provide automatically computed parameters
return self.getVisualizationParameter(parameter)
class PointsBase(Item, SymbolMixIn, AlphaMixIn):
"""Base class for :class:`Curve` and :class:`Scatter`"""
# note: _logFilterData must be overloaded if you overload
# getData to change its signature
_DEFAULT_Z_LAYER = 1
"""Default overlay layer for points,
on top of images."""
def __init__(self):
Item.__init__(self)
SymbolMixIn.__init__(self)
AlphaMixIn.__init__(self)
self._x = ()
self._y = ()
self._xerror = None
self._yerror = None
# Store filtered data for x > 0 and/or y > 0
self._filteredCache = {}
self._clippedCache = {}
# Store bounds depending on axes filtering >0:
# key is (isXPositiveFilter, isYPositiveFilter)
self._boundsCache = {}
@staticmethod
def _logFilterError(value, error):
"""Filter/convert error values if they go <= 0.
Replace error leading to negative values by nan
:param numpy.ndarray value: 1D array of values
:param numpy.ndarray error:
Array of errors: scalar, N, Nx1 or 2xN or None.
:return: Filtered error so error bars are never negative
"""
if error is not None:
# Convert Nx1 to N
if error.ndim == 2 and error.shape[1] == 1 and len(value) != 1:
error = numpy.ravel(error)
# Supports error being scalar, N or 2xN array
valueMinusError = value - numpy.atleast_2d(error)[0]
errorClipped = numpy.isnan(valueMinusError)
mask = numpy.logical_not(errorClipped)
errorClipped[mask] = valueMinusError[mask] <= 0
if numpy.any(errorClipped): # Need filtering
# expand errorbars to 2xN
if error.size == 1: # Scalar
error = numpy.full(
(2, len(value)), error, dtype=numpy.float)
elif error.ndim == 1: # N array
newError = numpy.empty((2, len(value)),
dtype=numpy.float)
newError[0, :] = error
newError[1, :] = error
error = newError
elif error.size == 2 * len(value): # 2xN array
error = numpy.array(
error, copy=True, dtype=numpy.float)
else:
_logger.error("Unhandled error array")
return error
error[0, errorClipped] = numpy.nan
return error
def _getClippingBoolArray(self, xPositive, yPositive):
"""Compute a boolean array to filter out points with negative
coordinates on log axes.
:param bool xPositive: True to filter arrays according to X coords.
:param bool yPositive: True to filter arrays according to Y coords.
:rtype: boolean numpy.ndarray
"""
assert xPositive or yPositive
if (xPositive, yPositive) not in self._clippedCache:
xclipped, yclipped = False, False
if xPositive:
x = self.getXData(copy=False)
with numpy.errstate(invalid='ignore'): # Ignore NaN warnings
xclipped = x <= 0
if yPositive:
y = self.getYData(copy=False)
with numpy.errstate(invalid='ignore'): # Ignore NaN warnings
yclipped = y <= 0
self._clippedCache[(xPositive, yPositive)] = \
numpy.logical_or(xclipped, yclipped)
return self._clippedCache[(xPositive, yPositive)]
def _logFilterData(self, xPositive, yPositive):
"""Filter out values with x or y <= 0 on log axes
:param bool xPositive: True to filter arrays according to X coords.
:param bool yPositive: True to filter arrays according to Y coords.
:return: The filter arrays or unchanged object if filtering not needed
:rtype: (x, y, xerror, yerror)
"""
x = self.getXData(copy=False)
y = self.getYData(copy=False)
xerror = self.getXErrorData(copy=False)
yerror = self.getYErrorData(copy=False)
if xPositive or yPositive:
clipped = self._getClippingBoolArray(xPositive, yPositive)
if numpy.any(clipped):
# copy to keep original array and convert to float
x = numpy.array(x, copy=True, dtype=numpy.float)
x[clipped] = numpy.nan
y = numpy.array(y, copy=True, dtype=numpy.float)
y[clipped] = numpy.nan
if xPositive and xerror is not None:
xerror = self._logFilterError(x, xerror)
if yPositive and yerror is not None:
yerror = self._logFilterError(y, yerror)
return x, y, xerror, yerror
def _getBounds(self):
if self.getXData(copy=False).size == 0: # Empty data
return None
plot = self.getPlot()
if plot is not None:
xPositive = plot.getXAxis()._isLogarithmic()
yPositive = plot.getYAxis()._isLogarithmic()
else:
xPositive = False
yPositive = False
# TODO bounds do not take error bars into account
if (xPositive, yPositive) not in self._boundsCache:
# use the getData class method because instance method can be
# overloaded to return additional arrays
data = PointsBase.getData(self, copy=False, displayed=True)
if len(data) == 5:
# hack to avoid duplicating caching mechanism in Scatter
# (happens when cached data is used, caching done using
# Scatter._logFilterData)
x, y, _xerror, _yerror = data[0], data[1], data[3], data[4]
else:
x, y, _xerror, _yerror = data
with warnings.catch_warnings():
warnings.simplefilter('ignore', category=RuntimeWarning)
# Ignore All-NaN slice encountered
self._boundsCache[(xPositive, yPositive)] = (
numpy.nanmin(x),
numpy.nanmax(x),
numpy.nanmin(y),
numpy.nanmax(y)
)
return self._boundsCache[(xPositive, yPositive)]
def _getCachedData(self):
"""Return cached filtered data if applicable,
i.e. if any axis is in log scale.
Return None if caching is not applicable."""
plot = self.getPlot()
if plot is not None:
xPositive = plot.getXAxis()._isLogarithmic()
yPositive = plot.getYAxis()._isLogarithmic()
if xPositive or yPositive:
# At least one axis has log scale, filter data
if (xPositive, yPositive) not in self._filteredCache:
self._filteredCache[(xPositive, yPositive)] = \
self._logFilterData(xPositive, yPositive)
return self._filteredCache[(xPositive, yPositive)]
return None
def getData(self, copy=True, displayed=False):
"""Returns the x, y values of the curve points and xerror, yerror
:param bool copy: True (Default) to get a copy,
False to use internal representation (do not modify!)
:param bool displayed: True to only get curve points that are displayed
in the plot. Default: False
Note: If plot has log scale, negative points
are not displayed.
:returns: (x, y, xerror, yerror)
:rtype: 4-tuple of numpy.ndarray
"""
if displayed: # filter data according to plot state
cached_data = self._getCachedData()
if cached_data is not None:
return cached_data
return (self.getXData(copy),
self.getYData(copy),
self.getXErrorData(copy),
self.getYErrorData(copy))
def getXData(self, copy=True):
"""Returns the x coordinates of the data points
:param copy: True (Default) to get a copy,
False to use internal representation (do not modify!)
:rtype: numpy.ndarray
"""
return numpy.array(self._x, copy=copy)
def getYData(self, copy=True):
"""Returns the y coordinates of the data points
:param copy: True (Default) to get a copy,
False to use internal representation (do not modify!)
:rtype: numpy.ndarray
"""
return numpy.array(self._y, copy=copy)
def getXErrorData(self, copy=True):
"""Returns the x error of the points
:param copy: True (Default) to get a copy,
False to use internal representation (do not modify!)
:rtype: numpy.ndarray, float or None
"""
if isinstance(self._xerror, numpy.ndarray):
return numpy.array(self._xerror, copy=copy)
else:
return self._xerror # float or None
def getYErrorData(self, copy=True):
"""Returns the y error of the points
:param copy: True (Default) to get a copy,
False to use internal representation (do not modify!)
:rtype: numpy.ndarray, float or None
"""
if isinstance(self._yerror, numpy.ndarray):
return numpy.array(self._yerror, copy=copy)
else:
return self._yerror # float or None
def setData(self, x, y, xerror=None, yerror=None, copy=True):
"""Set the data of the curve.
:param numpy.ndarray x: The data corresponding to the x coordinates.
:param numpy.ndarray y: The data corresponding to the y coordinates.
:param xerror: Values with the uncertainties on the x values
:type xerror: A float, or a numpy.ndarray of float32.
If it is an array, it can either be a 1D array of
same length as the data or a 2D array with 2 rows
of same length as the data: row 0 for positive errors,
row 1 for negative errors.
:param yerror: Values with the uncertainties on the y values.
:type yerror: A float, or a numpy.ndarray of float32. See xerror.
:param bool copy: True make a copy of the data (default),
False to use provided arrays.
"""
x = numpy.array(x, copy=copy)
y = numpy.array(y, copy=copy)
assert len(x) == len(y)
assert x.ndim == y.ndim == 1
if xerror is not None:
if isinstance(xerror, abc.Iterable):
xerror = numpy.array(xerror, copy=copy)
else:
xerror = float(xerror)
if yerror is not None:
if isinstance(yerror, abc.Iterable):
yerror = numpy.array(yerror, copy=copy)
else:
yerror = float(yerror)
# TODO checks on xerror, yerror
self._x, self._y = x, y
self._xerror, self._yerror = xerror, yerror
self._boundsCache = {} # Reset cached bounds
self._filteredCache = {} # Reset cached filtered data
self._clippedCache = {} # Reset cached clipped bool array
# TODO hackish data range implementation
if self.isVisible():
plot = self.getPlot()
if plot is not None:
plot._invalidateDataRange()
self._updated(ItemChangedType.DATA)
class BaselineMixIn(object):
"""Base class for Baseline mix-in"""
def __init__(self, baseline=None):
self._baseline = baseline
def _setBaseline(self, baseline):
"""
Set baseline value
:param baseline: baseline value(s)
:type: Union[None,float,numpy.ndarray]
"""
if (isinstance(baseline, abc.Iterable)):
baseline = numpy.array(baseline)
self._baseline = baseline
def getBaseline(self, copy=True):
"""
:param bool copy:
:return: histogram baseline
:rtype: Union[None,float,numpy.ndarray]
"""
if isinstance(self._baseline, numpy.ndarray):
return numpy.array(self._baseline, copy=True)
else:
return self._baseline
class _Style:
"""Object which store styles"""
class HighlightedMixIn(ItemMixInBase):
def __init__(self):
self._highlightStyle = self._DEFAULT_HIGHLIGHT_STYLE
self._highlighted = False
def isHighlighted(self):
"""Returns True if curve is highlighted.
:rtype: bool
"""
return self._highlighted
def setHighlighted(self, highlighted):
"""Set the highlight state of the curve
:param bool highlighted:
"""
highlighted = bool(highlighted)
if highlighted != self._highlighted:
self._highlighted = highlighted
# TODO inefficient: better to use backend's setCurveColor
self._updated(ItemChangedType.HIGHLIGHTED)
def getHighlightedStyle(self):
"""Returns the highlighted style in use
:rtype: CurveStyle
"""
return self._highlightStyle
def setHighlightedStyle(self, style):
"""Set the style to use for highlighting
:param CurveStyle style: New style to use
"""
previous = self.getHighlightedStyle()
if style != previous:
assert isinstance(style, _Style)
self._highlightStyle = style
self._updated(ItemChangedType.HIGHLIGHTED_STYLE)
# Backward compatibility event
if previous.getColor() != style.getColor():
self._updated(ItemChangedType.HIGHLIGHTED_COLOR)
