diff --git a/documentation/source/graphicsItems/index.rst b/documentation/source/graphicsItems/index.rst index 46f5a938..09d92893 100644 --- a/documentation/source/graphicsItems/index.rst +++ b/documentation/source/graphicsItems/index.rst @@ -10,8 +10,6 @@ Contents: :maxdepth: 2 plotdataitem - plotcurveitem - scatterplotitem plotitem imageitem viewbox @@ -19,6 +17,8 @@ Contents: infiniteline roi graphicslayout + plotcurveitem + scatterplotitem axisitem arrowitem curvepoint @@ -33,5 +33,6 @@ Contents: buttonitem graphicsobject graphicswidget + graphicsitem uigraphicsitem diff --git a/documentation/source/graphicsItems/plotitem.rst b/documentation/source/graphicsItems/plotitem.rst index cbf5f9f4..60cedf60 100644 --- a/documentation/source/graphicsItems/plotitem.rst +++ b/documentation/source/graphicsItems/plotitem.rst @@ -1,7 +1,7 @@ PlotItem ======== -.. autoclass:: pyqtgraph.PlotItem +.. autoclass:: pyqtgraph.PlotItem() :members: - + .. automethod:: pyqtgraph.PlotItem.__init__ diff --git a/graphicsItems/GraphicsItemMethods.py b/graphicsItems/GraphicsItem.py similarity index 97% rename from graphicsItems/GraphicsItemMethods.py rename to graphicsItems/GraphicsItem.py index ca9c7a43..f8cb93cf 100644 --- a/graphicsItems/GraphicsItemMethods.py +++ b/graphicsItems/GraphicsItem.py @@ -3,9 +3,12 @@ from pyqtgraph.GraphicsScene import GraphicsScene from pyqtgraph.Point import Point import weakref -class GraphicsItemMethods(object): +class GraphicsItem(object): """ - Class providing useful methods to GraphicsObject and GraphicsWidget. + **Bases:** :class:`object` + + Abstract class providing useful methods to GraphicsObject and GraphicsWidget. + (This is required because we cannot have multiple inheritance with QObject subclasses.) """ def __init__(self): self._viewWidget = None diff --git a/graphicsItems/GraphicsObject.py b/graphicsItems/GraphicsObject.py index af727315..60acc670 100644 --- a/graphicsItems/GraphicsObject.py +++ b/graphicsItems/GraphicsObject.py @@ -1,19 +1,15 @@ from pyqtgraph.Qt import QtGui, QtCore -from GraphicsItemMethods import GraphicsItemMethods +from GraphicsItem import GraphicsItem __all__ = ['GraphicsObject'] -class GraphicsObject(GraphicsItemMethods, QtGui.QGraphicsObject): - """Extends QGraphicsObject with a few important functions. - (Most of these assume that the object is in a scene with a single view) - - This class also generates a cache of the Qt-internal addresses of each item - so that GraphicsScene.items() can return the correct objects (this is a PyQt bug) - - Note: most of the extended functionality is inherited from GraphicsItemMethods, - which is shared between GraphicsObject and GraphicsWidget. +class GraphicsObject(GraphicsItem, QtGui.QGraphicsObject): + """ + **Bases:** :class:`GraphicsItem `, :class:`QtGui.QGraphicsObject` + + Extension of QGraphicsObject with some useful methods (provided by :class:`GraphicsItem `) """ def __init__(self, *args): QtGui.QGraphicsObject.__init__(self, *args) - GraphicsItemMethods.__init__(self) + GraphicsItem.__init__(self) diff --git a/graphicsItems/GraphicsWidget.py b/graphicsItems/GraphicsWidget.py index 0181ea17..9f4c5480 100644 --- a/graphicsItems/GraphicsWidget.py +++ b/graphicsItems/GraphicsWidget.py @@ -1,16 +1,19 @@ from pyqtgraph.Qt import QtGui, QtCore from pyqtgraph.GraphicsScene import GraphicsScene -from GraphicsItemMethods import GraphicsItemMethods +from GraphicsItem import GraphicsItem __all__ = ['GraphicsWidget'] -class GraphicsWidget(GraphicsItemMethods, QtGui.QGraphicsWidget): + +class GraphicsWidget(GraphicsItem, QtGui.QGraphicsWidget): def __init__(self, *args, **kargs): """ + **Bases:** :class:`GraphicsItem `, :class:`QtGui.QGraphicsWidget` + Extends QGraphicsWidget with several helpful methods and workarounds for PyQt bugs. - Most of the extra functionality is inherited from GraphicsObjectSuperclass. + Most of the extra functionality is inherited from :class:`GraphicsItem `. """ QtGui.QGraphicsWidget.__init__(self, *args, **kargs) - GraphicsItemMethods.__init__(self) + GraphicsItem.__init__(self) GraphicsScene.registerObject(self) ## workaround for pyqt bug in graphicsscene.items() #def getMenu(self): diff --git a/graphicsItems/ImageItem.py b/graphicsItems/ImageItem.py index 423183ab..535d0281 100644 --- a/graphicsItems/ImageItem.py +++ b/graphicsItems/ImageItem.py @@ -12,8 +12,19 @@ from GraphicsObject import GraphicsObject __all__ = ['ImageItem'] class ImageItem(GraphicsObject): """ - GraphicsObject displaying an image. Optimized for rapid update (ie video display) + **Bases:** :class:`GraphicsObject ` + GraphicsObject displaying an image. Optimized for rapid update (ie video display). + This item displays either a 2D numpy array (height, width) or + a 3D array (height, width, RGBa). This array is optionally scaled (see + :func:`setLevels `) and/or colored + with a lookup table (see :func:`setLookupTable `) + before being displayed. + + ImageItem is frequently used in conjunction with + :class:`HistogramLUTItem ` or + :class:`HistogramLUTWidget ` to provide a GUI + for controlling the levels and lookup table used to display the image. """ @@ -24,7 +35,7 @@ class ImageItem(GraphicsObject): def __init__(self, image=None, **kargs): """ - See setImage for all allowed arguments. + See :func:`setImage ` for all allowed initialization arguments. """ GraphicsObject.__init__(self) #self.pixmapItem = QtGui.QGraphicsPixmapItem(self) @@ -51,6 +62,21 @@ class ImageItem(GraphicsObject): self.setOpts(**kargs) def setCompositionMode(self, mode): + """Change the composition mode of the item (see QPainter::CompositionMode + in the Qt documentation). This is useful when overlaying multiple ImageItems. + + ============================================ ============================================================ + **Most common arguments:** + QtGui.QPainter.CompositionMode_SourceOver Default; image replaces the background if it + is opaque. Otherwise, it uses the alpha channel to blend + the image with the background. + QtGui.QPainter.CompositionMode_Overlay The image color is mixed with the background color to + reflect the lightness or darkness of the background. + QtGui.QPainter.CompositionMode_Plus Both the alpha and color of the image and background pixels + are added together. + QtGui.QPainter.CompositionMode_Multiply The output is the image color multiplied by the background. + ============================================ ============================================================ + """ self.paintMode = mode self.update() @@ -90,10 +116,13 @@ class ImageItem(GraphicsObject): def setLevels(self, levels, update=True): """ - Set image scaling levels. Can be one of: - [blackLevel, whiteLevel] - [[minRed, maxRed], [minGreen, maxGreen], [minBlue, maxBlue]] - Only the first format is compatible with lookup tables. + Set image scaling levels. Can be one of: + + * [blackLevel, whiteLevel] + * [[minRed, maxRed], [minGreen, maxGreen], [minBlue, maxBlue]] + + Only the first format is compatible with lookup tables. See :func:`makeARGB ` + for more details on how levels are applied. """ self.levels = levels if update: @@ -105,8 +134,14 @@ class ImageItem(GraphicsObject): def setLookupTable(self, lut, update=True): """ - Set the lookup table to use for this image. (see functions.makeARGB for more information on how this is used) - Optionally, lut can be a callable that accepts the current image as an argument and returns the lookup table to use.""" + Set the lookup table (numpy array) to use for this image. (see + :func:`makeARGB ` for more information on how this is used). + Optionally, lut can be a callable that accepts the current image as an + argument and returns the lookup table to use. + + Ordinarily, this table is supplied by a :class:`HistogramLUTItem ` + or :class:`GradientEditorItem `. + """ self.lut = lut if update: self.updateImage() @@ -126,23 +161,35 @@ class ImageItem(GraphicsObject): self.setBorder(kargs['border']) def setRect(self, rect): - """Scale and translate the image to fit within rect.""" + """Scale and translate the image to fit within rect (must be a QRect or QRectF).""" self.resetTransform() self.translate(rect.left(), rect.top()) self.scale(rect.width() / self.width(), rect.height() / self.height()) def setImage(self, image=None, autoLevels=None, **kargs): """ - Update the image displayed by this item. - Arguments: - image - autoLevels - lut - levels - opacity - compositionMode - border + Update the image displayed by this item. For more information on how the image + is processed before displaying, see :func:`makeARGB ` + ================= ========================================================================= + **Arguments:** + image (numpy array) Specifies the image data. May be 2D (width, height) or + 3D (width, height, RGBa). The array dtype must be integer or floating + point of any bit depth. For 3D arrays, the third dimension must + be of length 3 (RGB) or 4 (RGBA). + autoLevels (bool) If True, this forces the image to automatically select + levels based on the maximum and minimum values in the data. + By default, this argument is true unless the levels argument is + given. + lut (numpy array) The color lookup table to use when displaying the image. + See :func:`setLookupTable `. + levels (min, max) The minimum and maximum values to use when rescaling the image + data. By default, this will be set to the minimum and maximum values + in the image. If the image array has dtype uint8, no rescaling is necessary. + opacity (float 0.0-1.0) + compositionMode see :func:`setCompositionMode ` + border Sets the pen used when drawing the image border. Default is None. + ================= ========================================================================= """ prof = debug.Profiler('ImageItem.setImage', disabled=True) @@ -238,8 +285,10 @@ class ImageItem(GraphicsObject): def getHistogram(self, bins=500, step=3): - """returns x and y arrays containing the histogram values for the current image. - The step argument causes pixels to be skipped when computing the histogram to save time.""" + """Returns x and y arrays containing the histogram values for the current image. + The step argument causes pixels to be skipped when computing the histogram to save time. + This method is also used when automatically computing levels. + """ if self.image is None: return None,None stepData = self.image[::step, ::step] @@ -247,7 +296,12 @@ class ImageItem(GraphicsObject): return hist[1][:-1], hist[0] def setPxMode(self, b): - """Set whether the item ignores transformations and draws directly to screen pixels.""" + """ + Set whether the item ignores transformations and draws directly to screen pixels. + If True, the item will not inherit any scale or rotation transformations from its + parent items, but its position will be transformed as usual. + (see GraphicsItem::ItemIgnoresTransformations in the Qt documentation) + """ self.setFlag(self.ItemIgnoresTransformations, b) def setScaledMode(self): diff --git a/graphicsItems/LinearRegionItem.py b/graphicsItems/LinearRegionItem.py index bdffd075..ef1c1b8e 100644 --- a/graphicsItems/LinearRegionItem.py +++ b/graphicsItems/LinearRegionItem.py @@ -8,8 +8,18 @@ __all__ = ['LinearRegionItem'] class LinearRegionItem(UIGraphicsItem): """ + **Bases:** :class:`UIGraphicsItem ` + Used for marking a horizontal or vertical region in plots. The region can be dragged and is bounded by lines which can be dragged individually. + + =============================== ============================================================================= + **Signals:** + sigRegionChangeFinished(self) Emitted when the user has finished dragging the region (or one of its lines) + and when the region is changed programatically. + sigRegionChanged(self) Emitted while the user is dragging the region (or one of its lines) + and when the region is changed programatically. + =============================== ============================================================================= """ sigRegionChangeFinished = QtCore.Signal(object) diff --git a/graphicsItems/PlotDataItem.py b/graphicsItems/PlotDataItem.py index 22c62d1a..44493799 100644 --- a/graphicsItems/PlotDataItem.py +++ b/graphicsItems/PlotDataItem.py @@ -14,7 +14,22 @@ import pyqtgraph.functions as fn import pyqtgraph.debug as debug class PlotDataItem(GraphicsObject): - """GraphicsItem for displaying plot curves, scatter plots, or both.""" + """ + **Bases:** :class:`GraphicsObject ` + + GraphicsItem for displaying plot curves, scatter plots, or both. + While it is possible to use :class:`PlotCurveItem ` or + :class:`ScatterPlotItem ` individually, this class + provides a unified interface to both. Inspances of :class:`PlotDataItem` are + usually created by plot() methods such as :func:`pyqtgraph.plot` and + :func:`PlotItem.plot() `. + + ===================== ============================================== + **Signals:** + sigPlotChanged(self) Emitted when the data in this item is updated. + sigClicked(self) Emitted when the item is clicked. + ===================== ============================================== + """ sigPlotChanged = QtCore.Signal(object) sigClicked = QtCore.Signal(object) @@ -23,7 +38,7 @@ class PlotDataItem(GraphicsObject): """ There are many different ways to create a PlotDataItem: - Data initialization: (x,y data only) + **Data initialization arguments:** (x,y data only) =================================== ====================================== PlotDataItem(xValues, yValues) x and y values may be any sequence (including ndarray) of real numbers @@ -32,7 +47,7 @@ class PlotDataItem(GraphicsObject): PlotDataItem(ndarray(Nx2)) numpy array with shape (N, 2) where x=data[:,0] and y=data[:,1] =================================== ====================================== - Data initialization: (x,y data AND may include spot style) + **Data initialization arguments:** (x,y data AND may include spot style) =========================== ========================================= PlotDataItem(recarray) numpy array with dtype=[('x', float), ('y', float), ...] @@ -42,34 +57,40 @@ class PlotDataItem(GraphicsObject): OR 2D array with a column 'y' and extra columns as needed. =========================== ========================================= - Line style keyword + **Line style keyword arguments:** ========== ================================================ - pen pen to use for drawing line between points. Default is solid grey, 1px width. Use None to disable line drawing. + pen pen to use for drawing line between points. + Default is solid grey, 1px width. Use None to disable line drawing. + May be any single argument accepted by :func:`mkPen() ` shadowPen pen for secondary line to draw behind the primary line. disabled by default. + May be any single argument accepted by :func:`mkPen() ` fillLevel fill the area between the curve and fillLevel fillBrush fill to use when fillLevel is specified + May be any single argument accepted by :func:`mkBrush() ` ========== ================================================ - Point style keyword arguments: + **Point style keyword arguments:** ============ ================================================ - symbol symbol to use for drawing points OR list of symbols, one per point. Default is no symbol. + symbol (str) symbol to use for drawing points OR list of symbols, one per point. Default is no symbol. options are o, s, t, d, + symbolPen outline pen for drawing points OR list of pens, one per point + May be any single argument accepted by :func:`mkPen() ` symbolBrush brush for filling points OR list of brushes, one per point + May be any single argument accepted by :func:`mkBrush() ` symbolSize diameter of symbols OR list of diameters pxMode (bool) If True, then symbolSize is specified in pixels. If False, then symbolSize is specified in data coordinates. ============ ================================================ - Optimization keyword arguments: + **Optimization keyword arguments:** ========== ================================================ identical spots are all identical. The spot image will be rendered only once and repeated for every point decimate (int) decimate data ========== ================================================ - Meta-info keyword arguments: + **Meta-info keyword arguments:** ========== ================================================ name name of dataset. This would appear in a legend diff --git a/graphicsItems/PlotItem/PlotItem.py b/graphicsItems/PlotItem/PlotItem.py index 7d3a2b2d..f1bd6313 100644 --- a/graphicsItems/PlotItem/PlotItem.py +++ b/graphicsItems/PlotItem/PlotItem.py @@ -56,10 +56,12 @@ except: class PlotItem(GraphicsWidget): """ - Plot graphics item that can be added to any graphics scene. Implements axis titles, scales, interactive viewbox. + **Bases:** :class:`GraphicsWidget ` + Plot graphics item that can be added to any graphics scene. Implements axes, titles, and interactive viewbox. + PlotItem also provides some basic analysis functionality that may be accessed from the context menu. Use :func:`plot() ` to create a new PlotDataItem and add it to the view. - Use :func:`addItem() ` to add any QGraphicsItem to the view + Use :func:`addItem() ` to add any QGraphicsItem to the view. This class wraps several methods from its internal ViewBox: :func:`setXRange `, @@ -77,6 +79,13 @@ class PlotItem(GraphicsWidget): :func:`unregister ` The ViewBox itself can be accessed by calling :func:`getViewBox() ` + + ==================== ======================================================================= + **Signals** + sigYRangeChanged wrapped from :class:`ViewBox ` + sigXRangeChanged wrapped from :class:`ViewBox ` + sigRangeChanged wrapped from :class:`ViewBox ` + ==================== ======================================================================= """ sigRangeChanged = QtCore.Signal(object, object) ## Emitted when the ViewBox range has changed @@ -99,7 +108,8 @@ class PlotItem(GraphicsWidget): {'left': (args), 'bottom': (args), ...} - The name of each axis and the corresponding arguments are passed to PlotItem.setLabel() + The name of each axis and the corresponding arguments are passed to + :func:`PlotItem.setLabel() ` Optionally, PlotItem my also be initialized with the keyword arguments left, right, top, or bottom to achieve the same effect. *name* Registers a name for this view so that others may link to it @@ -720,6 +730,11 @@ class PlotItem(GraphicsWidget): ##self.replot() def addItem(self, item, *args, **kargs): + """ + Add a graphics item to the view box. + If the item has plot data (PlotDataItem, PlotCurveItem, ScatterPlotItem), it may + be included in analysis performed by the PlotItem. + """ self.items.append(item) vbargs = {} if 'ignoreBounds' in kargs: