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

Documentation updates

parent c44887e5
......@@ -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
PlotItem
========
.. autoclass:: pyqtgraph.PlotItem
.. autoclass:: pyqtgraph.PlotItem()
:members:
.. automethod:: pyqtgraph.PlotItem.__init__
......@@ -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
......
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 <pyqtgraph.graphicsItems.GraphicsItem>`, :class:`QtGui.QGraphicsObject`
Extension of QGraphicsObject with some useful methods (provided by :class:`GraphicsItem <pyqtgraph.graphicsItems.GraphicsItem>`)
"""
def __init__(self, *args):
QtGui.QGraphicsObject.__init__(self, *args)
GraphicsItemMethods.__init__(self)
GraphicsItem.__init__(self)
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 <pyqtgraph.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 <pyqtgraph.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):
......
......@@ -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 <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):
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)
#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 <pyqtgraph.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 <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
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 <pyqtgraph.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 <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)
......@@ -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):
......
......@@ -8,8 +8,18 @@ __all__ = ['LinearRegionItem']
class LinearRegionItem(UIGraphicsItem):
"""
**Bases:** :class:`UIGraphicsItem <pyqtgraph.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)
......
......@@ -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 <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)
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() <pyqtgraph.mkPen>`
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
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, +
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
May be any single argument accepted by :func:`mkBrush() <pyqtgraph.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
......
......@@ -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 <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:`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:
:func:`setXRange <pyqtgraph.ViewBox.setXRange>`,
......@@ -77,6 +79,13 @@ class PlotItem(GraphicsWidget):
:func:`unregister <pyqtgraph.ViewBox.unregister>`
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
......@@ -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() <pyqtgraph.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:
......
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