Try and clear up more confusion about levels

Author: j9ac9k

doc/source/api_reference/graphicsItems/imageitem.rst

@@ -55,12 +55,9 @@ The following guidance should be observed if performance is an important factor
 * 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.
-
+* For 4-channel data, use `uint8` or `uint16` with :python:`levels=None`.
+* ``levels`` should be set to (even if to ``None``) to avoid autoLevels sampling.
+* ``levels`` should be single channel or ``None``.
 * 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:
 

pyqtgraph/graphicsItems/ImageItem.py

@@ -144,18 +144,23 @@ def boundingRect(self) -> QtCore.QRectF:
             return QtCore.QRectF(0., 0., 0., 0.)
         return QtCore.QRectF(0., 0., float(self.width()), float(self.height()))
 
-    def setLevels(self, levels: npt.ArrayLike, update: bool=True):
+    def setLevels(self, levels: npt.ArrayLike | None, update: bool=True):
         """
-        Sets image scaling levels. 
+        Sets image scaling levels. Calling this method, even with ``levels=None`` will
+        disable auto leveling (set ``autoLevels=False``).
         
         Parameters
         ----------
-        levels : array_like
+        levels : array_like or None
             - ``[blackLevel, whiteLevel]`` 
                 sets black and white levels for monochrome data and can be used with a
                 lookup table.
             - ``[[minR, maxR], [minG, maxG], [minB, maxB]]``
                 sets individual scaling for RGB values. Not compatible with lookup tables.
+            - ``None``
+                Disables the application of levels, but setting to ``None`` prevents
+                the auto-levels mechanism from sampling the image.  Not compatible with
+                images that use floating point dtypes.
         update : bool, optional
             Controls if image immediately updates to reflect the new levels, default True
 
@@ -173,10 +178,11 @@ def setLevels(self, levels: npt.ArrayLike, update: bool=True):
         if update:
             self.updateImage()
 
-    def getLevels(self):
+    def getLevels(self) -> numpy.ndarray | None:
         """
-        Returns the list representing the current level settings. See :func:`setLevels`.
-        When ``autoLevels`` is active, the format is ``[blackLevel, whiteLevel]``.
+        Returns the array representing the current level settings. See
+        :func:`setLevels`. When ``autoLevels`` is active, the format is
+        ``[blackLevel, whiteLevel]``.
         """
         return self.levels
 
@@ -503,7 +509,7 @@ def setImage(
             if mn == mx or self._xp.isnan(mn) or self._xp.isnan(mx):
                 mn = 0
                 mx = 255
-            kargs['levels'] = [mn,mx]
+            kargs['levels'] = self._xp.asarray((mn,mx))
 
         profile()