Substantially upgrade ImageItem docs

Author: j9ac9k

doc/source/api_reference/functions.rst

@@ -103,6 +103,8 @@ Miscellaneous Functions
 
 .. autofunction:: pyqtgraph.exit
 
+.. autofunction:: pyqtgraph.functions.makeARGB
+
 
 Legacy Color Helper Functions
 -------------------------------

doc/source/api_reference/graphicsItems/imageitem.rst

@@ -1,49 +1,91 @@
+.. role:: python(code)
+   :language: python
+
 ImageItem
 =========
 
-:class:`~pyqtgraph.ImageItem` displays images inside a :class:`~pyqtgraph.GraphicsView`, or a 
-:class:`~pyqtgraph.ViewBox`, which may itself be part of a :class:`~pyqtgraph.PlotItem`. It is designed
-for rapid updates as needed for a video display. The supplied data is optionally scaled (see 
-:func:`~pyqtgraph.ImageItem.setLevels`) and/or colored according to a
-lookup table (see :func:`~pyqtgraph.ImageItem.setColorMap` and 
-:func:`~pyqtgraph.ImageItem.setLookupTable`).
+:class:`~pyqtgraph.ImageItem` displays images inside a
+:class:`~pyqtgraph.GraphicsView`, or a :class:`~pyqtgraph.ViewBox`, which may itself be
+part of a :class:`~pyqtgraph.PlotItem`. It is designed for rapid updates as needed for
+a video display. The supplied data is optionally scaled (see 
+:meth:`ImageItem.setLevels <pyqtgraph.ImageItem.setLevels>`) and/or colored according
+to a lookup table (see :meth:`ImageItem.setColorMap <pyqtgraph.ImageItem.setColorMap>`
+and  :meth:`ImageItem.setLookupTable <pyqtgraph.ImageItem.setLookupTable>`).
 
 Data is provided as a NumPy array with an ordering of either
 
-    * `col-major`, where the shape of the array represents (width, height) or
-    * `row-major`, where the shape of the array represents (height, width).
+* `col-major`, where the shape of the array represents (width, height) or
+* `row-major`, where the shape of the array represents (height, width).
 
-While `col-major` is the default, `row-major` ordering typically has the best performance. In either ordering, 
-a third dimension can be added to the array to hold individual
-``[R,G,B]`` or ``[R,G,B,A]`` components.
+While `col-major` is the default, `row-major` ordering typically has the best
+performance. In either ordering, a third dimension can be added to the array to hold
+individual :python:`[R,G,B]` or :python:`[R,G,B,A]` channels/components.
 
 Notes
 -----
 
-Data ordering can be set for each ImageItem, or in the :ref:`global configuration options <apiref_config>` by ::
-
-    pyqtgraph.setConfigOption('imageAxisOrder', 'row-major') # best performance
-
 An image can be placed into a plot area of a given extent directly through the
-:func:`~pyqtgraph.ImageItem.setRect` method or the ``rect`` keyword. This is internally realized through
-assigning a ``QtGui.QTransform``. For other translation, scaling or rotations effects that
-persist for all later image data, the user can also directly define and assign such a 
-transform, as shown in the example below. 
-
-ImageItem is frequently used in conjunction with :class:`~pyqtgraph.ColorBarItem` to provide
-a color map display and interactive level adjustments, or with
-:class:`~pyqtgraph.HistogramLUTItem` or :class:`~pyqtgraph.HistogramLUTWidget` for a full GUI
-to control the levels and lookup table used to display the image.
-
-If performance is critial, the following points may be worth investigating:
-
-    * Use row-major ordering and C-contiguous image data.
-    * Manually provide ``level`` information to avoid autoLevels sampling of the image.
-    * Prefer `float32` to `float64` for floating point data, avoid NaN values.
-    * Use lookup tables with <= 256 entries for false color images.
-    * Avoid individual level adjustments RGB components.
-    * Use the latest version of NumPy. Notably, SIMD code added in version 1.20 significantly improved performance on Linux platforms.
-    * Enable Numba with ``pyqtgraph.setConfigOption('useNumba', True)``, although the JIT compilation will only accelerate repeated image display.
+:meth:`ImageItem.setRect <pyqtgraph.ImageItem.setRect>` method or the ``rect`` keyword.
+This is internally realized through assigning a :class:`QTransform`. For other
+translation, scaling or rotations effects that persist for all later image data, the
+user can also directly define and assign such a transform, as shown in the example
+below.
+
+:class:`~pyqtgraph.ImageItem` is frequently used in conjunction with
+:class:`~pyqtgraph.ColorBarItem` to provide a color map display and interactive level
+adjustments, or with :class:`~pyqtgraph.HistogramLUTItem` or
+:class:`~pyqtgraph.HistogramLUTWidget` for a full GUI to control the levels and lookup
+table used to display the image.
+
+Performance
+-----------
+
+The performance of :class:`~pyqtgraph.ImageItem` can vary *significantly* based on
+attributes of the ``image``, ``levels`` and ``lut`` input arguments. It should not be
+assumed that the default parameters are the most performant, as the default values are 
+largely there to preserve backwards compatibility.
+
+The following guidance should be observed if performance is an important factor
+
+    * Instantiate :class:`~pyqtgraph.ImageItem` with :python:`axisOrder='row-major'`
+      
+      * Alternatively, set the global configuration optionally
+        :python:`pyqtgraph.setConfigOption('imageAxisOrder', 'row-major')`
+
+    * Use C-contiguous image data.
+    * For 1 or 3 channel data, use `uint8`, `uint16`, `float32`, or `float64` 
+      ``image`` dtype.
+    * For 4-channel data, use `uint8` or `uint16` with :python":`levels=None`.
+    * ``levels`` should be single channel (if 1 or 3 channel data).
+      
+      * Setting :python:`levels=None` will trigger autoLevels sampling, and thus should
+        be avoided if possible.
+
+    * If using LUTs (lookup tables), ensure they have a dtype of `uint8` and have 256
+      points or less, and that. That can be accomplished with calling:
+    
+      * :func:`ImageItem.setColorMap <pyqtgraph.ImageItem.setColorMap>` or
+      * :func:`ImageItem.setLookupTable <pyqtgraph.ImageItem.setLookupTable>` with 
+        :python:`ColorMap.getLookupTable(nPts=256)` (default is :python:`nPts=512`)
+
+    * For floating point ``image`` arrays, prefer `float32` dtype to `float64`
+      and avoid ``NaN`` values.
+    * Enable Numba with :python:`pyqtgraph.setConfigOption('useNumba', True)`
+
+      * JIT compilation will only accelerate repeated image display.
+
+Internally, pyqtgraph attempts to directly construct a :class:`QImage` using a
+combination of :class:`QImage.Format <QImage.Format>` options and
+:meth:`QImage.setColorTable <QImage.setColorTable>` if necessary. This does not work in
+all cases that pyqtgraph supports.  If pyqtgraph is unable to construct the
+:class:`QImage` in such a fashion, it will fall back on
+:func:`~pyqtgraph.functions.makeARGB` to manipulate the data in a manner that
+:class:`QImage` can read it in.  There is a *significant* performance penalty when
+having to use :func:`~pyqtgraph.functions.makeARGB`.
+
+For applications that are *very* performance sensitive, every effort should be made so
+that the arguments passed to :meth:`ImageItem.setImage <pyqtgraph.ImageItem.setImage>`
+do not call :func:`~pyqtgraph.functions.makeARGB`.
 
 .. _ImageItem_examples:
 
@@ -53,13 +95,16 @@ Examples
 .. literalinclude:: /images/gen_example_imageitem_transform.py
     :lines: 19-28
     :dedent: 8
+    :language: python
 
 .. thumbnail:: 
     /images/example_imageitem_transform.png
     :width: 49%
     :alt: Example of transformed image display
     :title: Transformed Image Display
 
+API
+---
 
 .. autoclass:: pyqtgraph.ImageItem
     :members:

doc/source/conf.py

@@ -13,7 +13,7 @@
 import os
 import sys
 import time
-from datetime import datetime
+import datetime
 
 from sphinx.application import Sphinx
 
@@ -63,9 +63,14 @@
     ("py:class", r"re\.Pattern"),  # doesn't seem to be a good ref in python docs
 ]
 
+napoleon_use_admonition_for_examples = True
+napoleon_use_admonition_for_notes = True
+napoleon_use_admonition_for_references = True
+napoleon_use_rtype = True
+napoleon_custom_sections = [("Signals", "params_style")]
 napoleon_preprocess_types = True
 napoleon_type_aliases = {
-    "callable": ":class:`collections.abc.Callable`",
+    "callable": ":class:`~collections.abc.Callable`",
     "np.ndarray": ":class:`numpy.ndarray`",
     'array_like': ':term:`array_like`',
     'color_like': ':func:`pyqtgraph.mkColor`',
@@ -80,10 +85,12 @@
 
 # General information about the project.
 project = 'pyqtgraph'
-now = datetime.utcfromtimestamp(
-    int(os.environ.get('SOURCE_DATE_EPOCH', time.time()))
+
+now = datetime.datetime.fromtimestamp(
+    int(os.environ.get('SOURCE_DATE_EPOCH', time.time())),
+    tz=datetime.timezone.utc
 )
-copyright = '2011 - {}, PyQtGraph developers'.format(now.year)
+copyright = f'2011 - {now.year}, PyQtGraph developers'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

pyqtgraph/functions.py

@@ -1986,11 +1986,12 @@ def arrayToQPath(x, y, connect='all', finiteCheck=True):
     a ``QDataStream`` object is created and the QDataStream >> QPainterPath
     operator is used to pass the data.  The memory format is as follows
 
-    numVerts(i4)
-    0(i4)   x(f8)   y(f8)    <-- 0 means this vertex does not connect
-    1(i4)   x(f8)   y(f8)    <-- 1 means this vertex connects to the previous vertex
-    ...
-    cStart(i4)   fillRule(i4)
+    .. code-block:
+        numVerts(i4)
+        0(i4)   x(f8)   y(f8)    <-- 0 means this vertex does not connect
+        1(i4)   x(f8)   y(f8)    <-- 1 means this vertex connects to the previous vertex
+        ...
+        cStart(i4)   fillRule(i4)
     
     see: https://github.com/qt/qtbase/blob/dev/src/gui/painting/qpainterpath.cpp