Add percentage-based autoscale margin configuration

Replace hardcoded autoscale margin with configurable `autoscale_margin_percent`
parameter in BasePlotOptions. Users can now specify intuitive percentage values
(0.2% default) instead of decimal fractions (0.002). Maintains full backward
compatibility while improving user experience.

Author: PierreRaybaut

CHANGELOG.md

@@ -4,6 +4,12 @@
 
 💥 New features / Enhancements:
 
+* Configurable autoscale margin:
+  * Added `autoscale_margin_percent` parameter to `BasePlotOptions` for intuitive percentage-based margin control
+  * Users can now specify autoscale margins as percentages (e.g., `0.2` for 0.2%, `5.0` for 5%)
+  * Replaces the previous decimal-based approach with more user-friendly percentage values
+  * Default remains 0.2% (equivalent to previous 0.002) for backward compatibility
+  * Includes validation to prevent unreasonable values (0-50% range)
 * Image statistics tool improvements:
   * Enhanced `get_stats` function to display delta (Δ) values for coordinate ranges
   * Now shows Δx, Δy, and Δz values alongside the min/max ranges for better analysis

plotpy/plot/base.py

@@ -88,6 +88,8 @@ class BasePlotOptions:
         axes_synchronised: If True, the axes are synchronised
         force_colorbar_enabled: If True, the colorbar is always enabled
         show_axes_tab: If True, the axes tab is shown in the parameters dialog
+        autoscale_margin_percent: The percentage margin added when autoscaling
+         (0.2% by default)
     """
 
     title: str | None = None
@@ -107,6 +109,7 @@ class BasePlotOptions:
     axes_synchronised: bool = False
     force_colorbar_enabled: bool = False
     show_axes_tab: bool = True
+    autoscale_margin_percent: float = 0.2
 
     def __post_init__(self) -> None:
         """Check arguments"""
@@ -120,6 +123,11 @@ def __post_init__(self) -> None:
         # Check aspect ratio
         if self.aspect_ratio <= 0:
             raise ValueError("aspect_ratio must be strictly positive")
+        # Check autoscale margin percentage
+        if self.autoscale_margin_percent < 0:
+            raise ValueError("autoscale_margin_percent must be non-negative")
+        if self.autoscale_margin_percent > 50:
+            raise ValueError("autoscale_margin_percent must be <= 50%")
         # Show a warning if force_colorbar_enabled is True and type is "curve"
         if self.force_colorbar_enabled and self.type == "curve":
             warnings.warn(
@@ -309,6 +317,7 @@ def __init__(
         self.options = options = options if options is not None else BasePlotOptions()
 
         self.__autoscale_excluded_items: list[itf.IBasePlotItem] = []
+        self.autoscale_margin_percent = options.autoscale_margin_percent
         self.lock_aspect_ratio = options.lock_aspect_ratio
         self.__autoLockAspectRatio = False
         if self.lock_aspect_ratio is None:
@@ -1105,6 +1114,32 @@ def set_scales(self, xscale: str, yscale: str) -> None:
         self.set_axis_scale(ay, yscale)
         self.replot()
 
+    def get_autoscale_margin_percent(self) -> float:
+        """Get autoscale margin percentage
+
+        Returns:
+            float: the autoscale margin percentage
+        """
+        return self.autoscale_margin_percent
+
+    def set_autoscale_margin_percent(self, margin_percent: float) -> None:
+        """Set autoscale margin percentage
+
+        Args:
+            margin_percent (float): the autoscale margin percentage (0-50)
+
+        Raises:
+            ValueError: if margin_percent is not in valid range
+        """
+        if margin_percent < 0:
+            raise ValueError("autoscale_margin_percent must be non-negative")
+        if margin_percent > 50:
+            raise ValueError("autoscale_margin_percent must be <= 50%")
+
+        self.autoscale_margin_percent = margin_percent
+        # Trigger an autoscale to apply the new margin immediately
+        self.do_autoscale(replot=True)
+
     def enable_used_axes(self):
         """
         Enable only used axes
@@ -2037,12 +2072,14 @@ def do_autoscale(self, replot: bool = True, axis_id: int | None = None) -> None:
                 vmax += 1
             elif self.get_axis_scale(axis_id) == "lin":
                 dv = vmax - vmin
-                vmin -= 0.002 * dv
-                vmax += 0.002 * dv
+                margin = self.autoscale_margin_percent / 100.0
+                vmin -= margin * dv
+                vmax += margin * dv
             elif vmin > 0 and vmax > 0:  # log scale
                 dv = np.log10(vmax) - np.log10(vmin)
-                vmin = 10 ** (np.log10(vmin) - 0.002 * dv)
-                vmax = 10 ** (np.log10(vmax) + 0.002 * dv)
+                margin = self.autoscale_margin_percent / 100.0
+                vmin = 10 ** (np.log10(vmin) - margin * dv)
+                vmax = 10 ** (np.log10(vmax) + margin * dv)
             self.set_axis_limits(axis_id, vmin, vmax)
         self.setAutoReplot(auto)
         self.updateAxes()