Add "Lock LUT range" option for image items

Fix Add option to update LUT range automatically #18

Author: PierreRaybaut

CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog #
 
+## Version 2.5.0 ##
+
+In this release, test coverage is 79%.
+
+💥 New features / Enhancements:
+
+* Added "Lock LUT range" option for image items:
+  * This new option is disabled by default, which matches the previous behavior:
+    when updating an image item data, the LUT range is automatically adjusted to
+    the new data range (if not passed as an argument to the `BaseImageItem.set_data`
+    method)
+  * When enabled, the LUT range is locked and the LUT range is not adjusted when
+    updating the image item data
+  * The option is available in image parameters dialog
+  * A new tool `LockLUTRangeTool` has been implemented to toggle the option from the
+    plot context menu: the tool is not registered by default in the plot widget, but
+    can be added by the host application if needed
+  * See test script `tests.features.test_image_data_update` for an example of usage
+    of the new option and tool
+
 ## Version 2.4.2 ##
 
 In this release, test coverage is 79%.

doc/features/tools/reference.rst

@@ -118,6 +118,8 @@ Image tools
    :members:
 .. autoclass:: plotpy.tools.ReverseColormapTool
    :members:
+.. autoclass:: plotpy.tools.LockLUTRangeTool
+   :members:
 .. autoclass:: plotpy.tools.XCSPanelTool
    :members:
 .. autoclass:: plotpy.tools.YCSPanelTool

plotpy/items/image/base.py

@@ -333,16 +333,16 @@ def set_data(
             data: 2D NumPy array
             lut_range: LUT range -- tuple (levelmin, levelmax) (Default value = None)
         """
-        if lut_range is not None:
-            _min, _max = lut_range
-        else:
-            _min, _max = get_nan_range(data)
-
         self.data = data
         self.histogram_cache = None
         self.update_bounds()
         self.update_border()
-        self.set_lut_range((_min, _max))
+        if not self.param.keep_lut_range:
+            if lut_range is not None:
+                _min, _max = lut_range
+            else:
+                _min, _max = get_nan_range(data)
+            self.set_lut_range((_min, _max))
 
     def get_data(
         self, x0: float, y0: float, x1: float | None = None, y1: float | None = None