Commit 44f2a0ec authored by Luke Campagnola's avatar Luke Campagnola
Browse files

Documentation updates

parent c44887e5
...@@ -10,8 +10,6 @@ Contents: ...@@ -10,8 +10,6 @@ Contents:
:maxdepth: 2 :maxdepth: 2
plotdataitem plotdataitem
plotcurveitem
scatterplotitem
plotitem plotitem
imageitem imageitem
viewbox viewbox
...@@ -19,6 +17,8 @@ Contents: ...@@ -19,6 +17,8 @@ Contents:
infiniteline infiniteline
roi roi
graphicslayout graphicslayout
plotcurveitem
scatterplotitem
axisitem axisitem
arrowitem arrowitem
curvepoint curvepoint
...@@ -33,5 +33,6 @@ Contents: ...@@ -33,5 +33,6 @@ Contents:
buttonitem buttonitem
graphicsobject graphicsobject
graphicswidget graphicswidget
graphicsitem
uigraphicsitem uigraphicsitem
PlotItem PlotItem
======== ========
.. autoclass:: pyqtgraph.PlotItem .. autoclass:: pyqtgraph.PlotItem()
:members: :members:
.. automethod:: pyqtgraph.PlotItem.__init__ .. automethod:: pyqtgraph.PlotItem.__init__
...@@ -3,9 +3,12 @@ from pyqtgraph.GraphicsScene import GraphicsScene ...@@ -3,9 +3,12 @@ from pyqtgraph.GraphicsScene import GraphicsScene
from pyqtgraph.Point import Point from pyqtgraph.Point import Point
import weakref 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): def __init__(self):
self._viewWidget = None self._viewWidget = None
......
from pyqtgraph.Qt import QtGui, QtCore from pyqtgraph.Qt import QtGui, QtCore
from GraphicsItemMethods import GraphicsItemMethods from GraphicsItem import GraphicsItem
__all__ = ['GraphicsObject'] __all__ = ['GraphicsObject']
class GraphicsObject(GraphicsItemMethods, QtGui.QGraphicsObject): class GraphicsObject(GraphicsItem, QtGui.QGraphicsObject):
"""Extends QGraphicsObject with a few important functions. """
(Most of these assume that the object is in a scene with a single view) **Bases:** :class:`GraphicsItem <pyqtgraph.graphicsItems.GraphicsItem>`, :class:`QtGui.QGraphicsObject`
This class also generates a cache of the Qt-internal addresses of each item Extension of QGraphicsObject with some useful methods (provided by :class:`GraphicsItem <pyqtgraph.graphicsItems.GraphicsItem>`)
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.
""" """
def __init__(self, *args): def __init__(self, *args):
QtGui.QGraphicsObject.__init__(self, *args) QtGui.QGraphicsObject.__init__(self, *args)
GraphicsItemMethods.__init__(self) GraphicsItem.__init__(self)
from pyqtgraph.Qt import QtGui, QtCore from pyqtgraph.Qt import QtGui, QtCore
from pyqtgraph.GraphicsScene import GraphicsScene from pyqtgraph.GraphicsScene import GraphicsScene
from GraphicsItemMethods import GraphicsItemMethods from GraphicsItem import GraphicsItem
__all__ = ['GraphicsWidget'] __all__ = ['GraphicsWidget']
class GraphicsWidget(GraphicsItemMethods, QtGui.QGraphicsWidget):
class GraphicsWidget(GraphicsItem, QtGui.QGraphicsWidget):
def __init__(self, *args, **kargs): def __init__(self, *args, **kargs):
""" """
**Bases:** :class:`GraphicsItem <pyqtgraph.GraphicsItem>`, :class:`QtGui.QGraphicsWidget`
Extends QGraphicsWidget with several helpful methods and workarounds for PyQt bugs. 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 <pyqtgraph.GraphicsItem>`.
""" """
QtGui.QGraphicsWidget.__init__(self, *args, **kargs) QtGui.QGraphicsWidget.__init__(self, *args, **kargs)
GraphicsItemMethods.__init__(self) GraphicsItem.__init__(self)
GraphicsScene.registerObject(self) ## workaround for pyqt bug in graphicsscene.items() GraphicsScene.registerObject(self) ## workaround for pyqt bug in graphicsscene.items()
#def getMenu(self): #def getMenu(self):
......
...@@ -12,8 +12,19 @@ from GraphicsObject import GraphicsObject ...@@ -12,8 +12,19 @@ from GraphicsObject import GraphicsObject
__all__ = ['ImageItem'] __all__ = ['ImageItem']
class ImageItem(GraphicsObject): class ImageItem(GraphicsObject):
""" """
GraphicsObject displaying an image. Optimized for rapid update (ie video display) **Bases:** :class:`GraphicsObject <pyqtgraph.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 <pyqtgraph.ImageItem.setLevels>`) and/or colored
with a lookup table (see :func:`setLookupTable <pyqtgraph.ImageItem.setLookupTable>`)
before being displayed.
ImageItem is frequently used in conjunction with
:class:`HistogramLUTItem <pyqtgraph.HistogramLUTItem>` or
:class:`HistogramLUTWidget <pyqtgraph.HistogramLUTWidget>` to provide a GUI
for controlling the levels and lookup table used to display the image.
""" """
...@@ -24,7 +35,7 @@ class ImageItem(GraphicsObject): ...@@ -24,7 +35,7 @@ class ImageItem(GraphicsObject):
def __init__(self, image=None, **kargs): def __init__(self, image=None, **kargs):
""" """
See setImage for all allowed arguments. See :func:`setImage <pyqtgraph.ImageItem.setImage>` for all allowed initialization arguments.
""" """
GraphicsObject.__init__(self) GraphicsObject.__init__(self)
#self.pixmapItem = QtGui.QGraphicsPixmapItem(self) #self.pixmapItem = QtGui.QGraphicsPixmapItem(self)
...@@ -51,6 +62,21 @@ class ImageItem(GraphicsObject): ...@@ -51,6 +62,21 @@ class ImageItem(GraphicsObject):
self.setOpts(**kargs) self.setOpts(**kargs)
def setCompositionMode(self, mode): 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.paintMode = mode
self.update() self.update()
...@@ -90,10 +116,13 @@ class ImageItem(GraphicsObject): ...@@ -90,10 +116,13 @@ class ImageItem(GraphicsObject):
def setLevels(self, levels, update=True): def setLevels(self, levels, update=True):
""" """
Set image scaling levels. Can be one of: Set image scaling levels. Can be one of:
[blackLevel, whiteLevel]
[[minRed, maxRed], [minGreen, maxGreen], [minBlue, maxBlue]] * [blackLevel, whiteLevel]
Only the first format is compatible with lookup tables. * [[minRed, maxRed], [minGreen, maxGreen], [minBlue, maxBlue]]
Only the first format is compatible with lookup tables. See :func:`makeARGB <pyqtgraph.makeARGB>`
for more details on how levels are applied.
""" """
self.levels = levels self.levels = levels
if update: if update:
...@@ -105,8 +134,14 @@ class ImageItem(GraphicsObject): ...@@ -105,8 +134,14 @@ class ImageItem(GraphicsObject):
def setLookupTable(self, lut, update=True): 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) Set the lookup table (numpy array) to use for this image. (see
Optionally, lut can be a callable that accepts the current image as an argument and returns the lookup table to use.""" :func:`makeARGB <pyqtgraph.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 <pyqtgraph.HistogramLUTItem>`
or :class:`GradientEditorItem <pyqtgraph.GradientEditorItem>`.
"""
self.lut = lut self.lut = lut
if update: if update:
self.updateImage() self.updateImage()
...@@ -126,23 +161,35 @@ class ImageItem(GraphicsObject): ...@@ -126,23 +161,35 @@ class ImageItem(GraphicsObject):
self.setBorder(kargs['border']) self.setBorder(kargs['border'])
def setRect(self, rect): 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.resetTransform()
self.translate(rect.left(), rect.top()) self.translate(rect.left(), rect.top())
self.scale(rect.width() / self.width(), rect.height() / self.height()) self.scale(rect.width() / self.width(), rect.height() / self.height())
def setImage(self, image=None, autoLevels=None, **kargs): def setImage(self, image=None, autoLevels=None, **kargs):
""" """
Update the image displayed by this item. Update the image displayed by this item. For more information on how the image
Arguments: is processed before displaying, see :func:`makeARGB <pyqtgraph.makeARGB>`
image
autoLevels ================= =========================================================================
lut **Arguments:**
levels image (numpy array) Specifies the image data. May be 2D (width, height) or
opacity 3D (width, height, RGBa). The array dtype must be integer or floating
compositionMode point of any bit depth. For 3D arrays, the third dimension must
border 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 <pyqtgraph.ImageItem.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 <pyqtgraph.ImageItem.setCompositionMode>`
border Sets the pen used when drawing the image border. Default is None.
================= =========================================================================
""" """
prof = debug.Profiler('ImageItem.setImage', disabled=True) prof = debug.Profiler('ImageItem.setImage', disabled=True)
...@@ -238,8 +285,10 @@ class ImageItem(GraphicsObject): ...@@ -238,8 +285,10 @@ class ImageItem(GraphicsObject):
def getHistogram(self, bins=500, step=3): def getHistogram(self, bins=500, step=3):
"""returns x and y arrays containing the histogram values for the current image. """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.""" 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: if self.image is None:
return None,None return None,None
stepData = self.image[::step, ::step] stepData = self.image[::step, ::step]
...@@ -247,7 +296,12 @@ class ImageItem(GraphicsObject): ...@@ -247,7 +296,12 @@ class ImageItem(GraphicsObject):
return hist[1][:-1], hist[0] return hist[1][:-1], hist[0]
def setPxMode(self, b): 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) self.setFlag(self.ItemIgnoresTransformations, b)
def setScaledMode(self): def setScaledMode(self):
......
...@@ -8,8 +8,18 @@ __all__ = ['LinearRegionItem'] ...@@ -8,8 +8,18 @@ __all__ = ['LinearRegionItem']
class LinearRegionItem(UIGraphicsItem): class LinearRegionItem(UIGraphicsItem):
""" """
**Bases:** :class:`UIGraphicsItem <pyqtgraph.UIGraphicsItem>`
Used for marking a horizontal or vertical region in plots. 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. 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) sigRegionChangeFinished = QtCore.Signal(object)
......
...@@ -14,7 +14,22 @@ import pyqtgraph.functions as fn ...@@ -14,7 +14,22 @@ import pyqtgraph.functions as fn
import pyqtgraph.debug as debug import pyqtgraph.debug as debug
class PlotDataItem(GraphicsObject): class PlotDataItem(GraphicsObject):
"""GraphicsItem for displaying plot curves, scatter plots, or both.""" """
**Bases:** :class:`GraphicsObject <pyqtgraph.GraphicsObject>`
GraphicsItem for displaying plot curves, scatter plots, or both.
While it is possible to use :class:`PlotCurveItem <pyqtgraph.PlotCurveItem>` or
:class:`ScatterPlotItem <pyqtgraph.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() <pyqtgraph.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) sigPlotChanged = QtCore.Signal(object)
sigClicked = QtCore.Signal(object) sigClicked = QtCore.Signal(object)
...@@ -23,7 +38,7 @@ class PlotDataItem(GraphicsObject): ...@@ -23,7 +38,7 @@ class PlotDataItem(GraphicsObject):
""" """
There are many different ways to create a PlotDataItem: 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 PlotDataItem(xValues, yValues) x and y values may be any sequence (including ndarray) of real numbers
...@@ -32,7 +47,7 @@ class PlotDataItem(GraphicsObject): ...@@ -32,7 +47,7 @@ class PlotDataItem(GraphicsObject):
PlotDataItem(ndarray(Nx2)) numpy array with shape (N, 2) where x=data[:,0] and y=data[:,1] 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), ...] PlotDataItem(recarray) numpy array with dtype=[('x', float), ('y', float), ...]
...@@ -42,34 +57,40 @@ class PlotDataItem(GraphicsObject): ...@@ -42,34 +57,40 @@ class PlotDataItem(GraphicsObject):
OR 2D array with a column 'y' and extra columns as needed. 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() <pyqtgraph.mkPen>`
shadowPen pen for secondary line to draw behind the primary line. disabled by default. shadowPen pen for secondary line to draw behind the primary line. disabled by default.
May be any single argument accepted by :func:`mkPen() <pyqtgraph.mkPen>`
fillLevel fill the area between the curve and fillLevel fillLevel fill the area between the curve and fillLevel
fillBrush fill to use when fillLevel is specified fillBrush fill to use when fillLevel is specified
May be any single argument accepted by :func:`mkBrush() <pyqtgraph.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, + options are o, s, t, d, +
symbolPen outline pen for drawing points OR list of pens, one per point symbolPen outline pen for drawing points OR list of pens, one per point
May be any single argument accepted by :func:`mkPen() <pyqtgraph.mkPen>`
symbolBrush brush for filling points OR list of brushes, one per point symbolBrush brush for filling points OR list of brushes, one per point
May be any single argument accepted by :func:`mkBrush() <pyqtgraph.mkBrush>`
symbolSize diameter of symbols OR list of diameters symbolSize diameter of symbols OR list of diameters
pxMode (bool) If True, then symbolSize is specified in pixels. If False, then symbolSize is pxMode (bool) If True, then symbolSize is specified in pixels. If False, then symbolSize is
specified in data coordinates. 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 identical spots are all identical. The spot image will be rendered only once and repeated for every point
decimate (int) decimate data decimate (int) decimate data
========== ================================================ ========== ================================================
Meta-info keyword arguments: **Meta-info keyword arguments:**
========== ================================================ ========== ================================================
name name of dataset. This would appear in a legend name name of dataset. This would appear in a legend
......
...@@ -56,10 +56,12 @@ except: ...@@ -56,10 +56,12 @@ except:
class PlotItem(GraphicsWidget): class PlotItem(GraphicsWidget):
""" """
Plot graphics item that can be added to any graphics scene. Implements axis titles, scales, interactive viewbox. **Bases:** :class:`GraphicsWidget <pyqtgraph.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() <pyqtgraph.PlotItem.plot>` to create a new PlotDataItem and add it to the view. Use :func:`plot() <pyqtgraph.PlotItem.plot>` to create a new PlotDataItem and add it to the view.
Use :func:`addItem() <pyqtgraph.PlotItem.addItem>` to add any QGraphicsItem to the view Use :func:`addItem() <pyqtgraph.PlotItem.addItem>` to add any QGraphicsItem to the view.
This class wraps several methods from its internal ViewBox: This class wraps several methods from its internal ViewBox:
:func:`setXRange <pyqtgraph.ViewBox.setXRange>`, :func:`setXRange <pyqtgraph.ViewBox.setXRange>`,
...@@ -77,6 +79,13 @@ class PlotItem(GraphicsWidget): ...@@ -77,6 +79,13 @@ class PlotItem(GraphicsWidget):
:func:`unregister <pyqtgraph.ViewBox.unregister>` :func:`unregister <pyqtgraph.ViewBox.unregister>`
The ViewBox itself can be accessed by calling :func:`getViewBox() <pyqtgraph.PlotItem.getViewBox>` The ViewBox itself can be accessed by calling :func:`getViewBox() <pyqtgraph.PlotItem.getViewBox>`
==================== =======================================================================
**Signals**
sigYRangeChanged wrapped from :class:`ViewBox <pyqtgraph.ViewBox>`
sigXRangeChanged wrapped from :class:`ViewBox <pyqtgraph.ViewBox>`
sigRangeChanged wrapped from :class:`ViewBox <pyqtgraph.ViewBox>`
==================== =======================================================================
""" """
sigRangeChanged = QtCore.Signal(object, object) ## Emitted when the ViewBox range has changed sigRangeChanged = QtCore.Signal(object, object) ## Emitted when the ViewBox range has changed
...@@ -99,7 +108,8 @@ class PlotItem(GraphicsWidget): ...@@ -99,7 +108,8 @@ class PlotItem(GraphicsWidget):
{'left': (args), 'bottom': (args), ...} {'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() <pyqtgraph.PlotItem.setLabel>`
Optionally, PlotItem my also be initialized with the keyword arguments left, Optionally, PlotItem my also be initialized with the keyword arguments left,
right, top, or bottom to achieve the same effect. right, top, or bottom to achieve the same effect.
*name* Registers a name for this view so that others may link to it *name* Registers a name for this view so that others may link to it
...@@ -720,6 +730,11 @@ class PlotItem(GraphicsWidget): ...@@ -720,6 +730,11 @@ class PlotItem(GraphicsWidget):
##self.replot() ##self.replot()
def addItem(self, item, *args, **kargs): 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) self.items.append(item)
vbargs = {} vbargs = {}
if 'ignoreBounds' in kargs: if 'ignoreBounds' in kargs:
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment