glplot 0.1.8__tar.gz → 0.1.9__tar.gz

{glplot-0.1.8 → glplot-0.1.9}/CITATION.cff

@@ -12,8 +12,10 @@ authors:
     orcid: "https://orcid.org/0009-0002-3961-1426"
   - family-names: Riccius
     given-names: Felix
+    orcid: "https://orcid.org/0000-0002-1331-4469"
   - family-names: Holland
     given-names: Julian
+    orcid: "https://orcid.org/0000-0003-0134-1790"
   - family-names: Ducci
     given-names: Gianmarco
 identifiers:

{glplot-0.1.8 → glplot-0.1.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: glplot
-Version: 0.1.8
+Version: 0.1.9
 Summary: High-performance OpenGL plotting library for Python
 Project-URL: Homepage, https://github.com/AkarisDimitry/GLPlot
 Project-URL: Repository, https://github.com/AkarisDimitry/GLPlot
@@ -32,11 +32,13 @@ Provides-Extra: dev
 Requires-Dist: build>=1.0; extra == 'dev'
 Requires-Dist: pytest-cov>=4.0; extra == 'dev'
 Requires-Dist: pytest-mock>=3.10; extra == 'dev'
+Requires-Dist: pytest-timeout>=2.1; extra == 'dev'
 Requires-Dist: pytest>=7.0; extra == 'dev'
 Requires-Dist: twine>=4.0; extra == 'dev'
 Provides-Extra: test
 Requires-Dist: pytest-cov>=4.0; extra == 'test'
 Requires-Dist: pytest-mock>=3.10; extra == 'test'
+Requires-Dist: pytest-timeout>=2.1; extra == 'test'
 Requires-Dist: pytest>=7.0; extra == 'test'
 Description-Content-Type: text/markdown
 

{glplot-0.1.8 → glplot-0.1.9}/glplot/core/panel.py

@@ -18,7 +18,8 @@ origin, which is what ``glViewport`` wants).
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING, Optional, Tuple
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any, List, Optional, Tuple
 
 from ..controllers import CameraController
 from .camera3d import Axes3DOptions, Camera3D
@@ -29,6 +30,61 @@ if TYPE_CHECKING:
     from ..options import EngineOptions
 
 
+@dataclass
+class ColorbarSpec:
+    """One colorbar attached to a :class:`Panel`, drawn as a screen-space overlay.
+
+    Deliberately not a :class:`Panel` itself: any rect registered on ``fig.panels`` is
+    click-to-activate and pan/zoom-able (see ``GPULinePlot._panel_index_at``), so a
+    colorbar built that way would silently steal "current axes" the moment a script did
+    ``im = plt.imshow(...); plt.colorbar(); plt.title(...)`` -- the title would land on
+    the colorbar. A ``ColorbarSpec`` instead just describes a strip of the figure and is
+    drawn by :func:`glplot.renderers.colorbar.draw_colorbars`, in the same whole-window,
+    camera-free pixel space :meth:`GPULinePlot._draw_panel_borders` already draws in.
+
+    ``norm`` is always a concrete, bounded ``matplotlib.colors.Normalize`` instance (never
+    a bare scale name and never unbounded) -- the single source of truth the gradient fill,
+    the tick locator, and the headless ``savefig()`` reconstruction all read alike, so the
+    live bar and the exported PNG cannot independently drift from what was actually asked
+    for.
+    """
+
+    #: (x0, y0, w, h) in figure fractions, bottom-left origin -- same convention as
+    #: :attr:`Panel.rect_frac`, and the strip vacated from the host panel's own rect.
+    rect_frac: Tuple[float, float, float, float]
+    #: "vertical" for a right/left bar, "horizontal" for a top/bottom one.
+    orientation: str
+    #: Which edge of the host panel this bar sits against: "right", "left", "top" or
+    #: "bottom". Distinct from ``orientation`` because a caller can ask for either
+    #: independently, as matplotlib's own ``colorbar()`` does.
+    location: str
+    #: Colormap name, resolved (never ``None``) at ``colorbar()`` call time.
+    cmap: str
+    #: A concrete ``matplotlib.colors.Normalize`` (or subclass) instance with real
+    #: ``vmin``/``vmax`` already resolved.
+    norm: Any
+    #: Explicit tick positions, or ``None`` to auto-locate from ``norm``'s type.
+    ticks: Optional[Any] = None
+    #: A tick label format (matplotlib ``Formatter``, format string, or ``None`` to
+    #: auto-format from the locator).
+    format: Optional[Any] = None
+    #: The colorbar's own axis label (``Colorbar.set_label``), or ``None``.
+    label: Optional[str] = None
+    #: Matplotlib-parity placement knobs, stored for the headless reconstruction (which
+    #: rebuilds a real matplotlib colorbar and can honour them precisely); the live
+    #: renderer's own bar geometry does not re-derive a precise aspect-ratio width from
+    #: these -- see ``colorbar()``'s docstring.
+    fraction: float = 0.15
+    pad: float = 0.05
+    shrink: float = 1.0
+    aspect: float = 20.0
+    #: When True, the bar sits *inside* the host panel's own rect (over the plotted
+    #: content, near ``location``'s edge) instead of shrinking the panel to make room
+    #: outside it. Ticks/label flip to point inward, toward the panel's centre, since
+    #: there is no room outside the panel for them to point into.
+    inset: bool = False
+
+
 class Panel:
     """One plotting region: its scene, camera, interaction state, and window rectangle."""
 
@@ -64,6 +120,30 @@ class Panel:
         #: panel that is never animated costs one object and no frame time.
         self.timeline = Timeline()
 
+        #: Colorbars drawn against this panel's edges. Metadata only -- never a
+        #: :class:`Panel` of its own, never registered on ``fig.panels`` -- so a
+        #: colorbar can never become the active/pannable axes. See
+        #: :class:`ColorbarSpec` for why.
+        self.colorbars: List["ColorbarSpec"] = []
+
+        #: This panel's own axis names and axes title.
+        #:
+        #: Per panel for the same reason the cameras and scenes are: a split figure plots
+        #: four different quantities and has to be able to *name* them four different
+        #: ways. These were figure-global until they lived here, so a 2x2 grid could only
+        #: ever carry one x-name, one y-name and one title between all four panels --
+        #: whichever call ran last won, and the other three axes went unlabelled.
+        #:
+        #: The engine forwards ``xlabel``/``ylabel`` to the active panel's copy (the same
+        #: delegation ``scene``/``camera``/``cache`` use), so ``gplt.xlabel(...)`` keeps
+        #: writing "the current axes' x-name" and every existing single-panel caller is
+        #: unaffected. ``title`` is *not* forwarded that way -- ``engine.title`` is also
+        #: the GLFW window caption and is assigned in ``__init__`` before any panel
+        #: exists -- so ``set_title`` writes both, and readers prefer this one.
+        self.xlabel: str = ""
+        self.ylabel: str = ""
+        self.title: str = ""
+
         #: Explicit dimensionality: 2, 3, or ``None`` for "infer from the layers".
         #:
         #: None is the default and reproduces GLPlot's historical behaviour exactly — a

{glplot-0.1.8 → glplot-0.1.9}/glplot/engine.py

@@ -55,6 +55,8 @@ from .renderers import axes3d
 from .renderers.density import DensityRenderer
 from .renderers.exact import ExactLineRenderer
 from .renderers.interaction import InteractionRenderer
+from .renderers.colorbar import draw_colorbars
+from .renderers.contour_labels import draw_contour_labels
 from .renderers.legend import draw_legend
 from .utils.export import ExportManager
 from .utils.scale import forward as _scale_forward
@@ -238,6 +240,34 @@ class GPULinePlot:
     def cache(self, value: CacheState) -> None:
         self.active_panel.cache = value
 
+    @property
+    def xlabel(self) -> str:
+        """The active panel's x-axis name (``gplt.xlabel()``).
+
+        Forwarded to the panel for the same reason ``scene``/``camera`` are: a split
+        figure plots a different quantity per panel and has to be able to name each one.
+        Held as a plain attribute on the engine until this existed, which made it
+        figure-global -- a 2x2 grid got one x-name between all four panels.
+
+        Every reader keeps working unchanged: the live axis renderer reads
+        ``plot.xlabel`` inside the per-panel overlay pass (``_draw_panels`` swaps
+        ``active_panel_index`` around it), so it now resolves per panel for free.
+        """
+        return self.active_panel.xlabel
+
+    @xlabel.setter
+    def xlabel(self, value: str) -> None:
+        self.active_panel.xlabel = "" if value is None else str(value)
+
+    @property
+    def ylabel(self) -> str:
+        """The active panel's y-axis name (``gplt.ylabel()``). See :attr:`xlabel`."""
+        return self.active_panel.ylabel
+
+    @ylabel.setter
+    def ylabel(self, value: str) -> None:
+        self.active_panel.ylabel = "" if value is None else str(value)
+
     @property
     def camera3d(self) -> Camera3D:
         """The active panel's 3D point of view."""
@@ -324,6 +354,13 @@ class GPULinePlot:
         """
         self.title = str(title)
         self.options.title = str(title)
+        # Also the *active panel's* own axes title, so a split figure can title each
+        # panel separately. `self.title` stays the window caption (and the single-panel
+        # axes title) rather than becoming a forwarding property like `xlabel`/`ylabel`:
+        # it is assigned in `__init__` before any panel exists, so forwarding it would
+        # write to a panel that is not there yet.
+        if getattr(self, "panels", None):
+            self.active_panel.title = str(title)
         self.options.axis_title_fontsize = fontsize
         self.options.axis_title_color = color
         self.frame.dirty_ui = True
@@ -2044,35 +2081,38 @@ class GPULinePlot:
     # --------------------------------------------------------
 
     def _draw_overlays(self) -> None:
-        """Draw the axis scale labels and the legend for the active panel.
+        """Draw the axis scale labels, contour labels and the legend for the active panel.
 
         Screen-aligned overlays that must repaint every frame (so they stay live and survive
         the cached impostor). Reads the active panel's camera and the engine's current pixel
         dimensions, which ``_draw_panels`` sets to the panel's rect when several panels exist.
         """
+        # Built once, outside the `axis_show_labels` gate below: the contour labels and the
+        # legend are not axis annotations and must still draw when the axis numbers are off.
+        window_world = self.camera_controller.world_window(self.width, self.height)
+        mvp = self.camera_controller.mvp(self.width, self.height)
+        ndc_scale, ndc_offset = self._get_ndc_transform(window_world)
+        ctx_labels = RenderContext(
+            mvp=mvp,
+            window_world=window_world,
+            ndc_scale=ndc_scale,
+            ndc_offset=ndc_offset,
+            width_px=self.width,
+            height_px=self.height,
+            fb_width=self.fb_width,
+            fb_height=self.fb_height,
+            dpr=self.fb_width / max(self.width, 1),
+            mode=self.policy.runtime.current_mode,
+            global_alpha=1.0,
+            lod_keep_prob=1.0,
+            is_density=self.display_density,
+            time=time.perf_counter(),
+            px_offset=self._panel_offset_px,
+        )
+
         # Draw Axis Labels (Scale) on every frame so they update dynamically and persist when
         # the scene is cached.
         if self.options.axis_show_labels:
-            window_world = self.camera_controller.world_window(self.width, self.height)
-            mvp = self.camera_controller.mvp(self.width, self.height)
-            ndc_scale, ndc_offset = self._get_ndc_transform(window_world)
-            ctx_labels = RenderContext(
-                mvp=mvp,
-                window_world=window_world,
-                ndc_scale=ndc_scale,
-                ndc_offset=ndc_offset,
-                width_px=self.width,
-                height_px=self.height,
-                fb_width=self.fb_width,
-                fb_height=self.fb_height,
-                dpr=self.fb_width / max(self.width, 1),
-                mode=self.policy.runtime.current_mode,
-                global_alpha=1.0,
-                lod_keep_prob=1.0,
-                is_density=self.display_density,
-                time=time.perf_counter(),
-                px_offset=self._panel_offset_px,
-            )
             if self._is_pure_3d_scene():
                 # A 3D scene's numbers live on the box's edges, not on two screen-aligned
                 # spines, so they come from the 3D anchors rather than the AxisManager.
@@ -2082,6 +2122,13 @@ class GPULinePlot:
                 self.axis_manager.update(ctx_labels)
                 self.renderer_manager.renderers["axis"]._draw_labels(self.axis_manager, ctx_labels)
 
+        # Inline contour values, seated on their own level lines. Same draw list and the
+        # same reasoning as the legend below: not an axis annotation, so outside that
+        # gate, and 2D-only (a 3D contour is real `wireframe3d` geometry with no
+        # screen-space line to seat a number on). Draws nothing unless `clabel()` asked.
+        if not self._is_pure_3d_scene():
+            draw_contour_labels(self, ctx_labels)
+
         # The legend, on the same background draw list as the axis labels and for the
         # same reason: it must composite over the cached impostor, which is not
         # redrawn during an interaction. Deliberately outside the `axis_show_labels`
@@ -2481,6 +2528,11 @@ class GPULinePlot:
             # pixel size via _draw_panels, which swaps them for the panel's rect).
             self._draw_panels(self._draw_overlays)
 
+            # Colorbars, once per frame in whole-window pixel space (not per-panel, like
+            # `_draw_panel_borders` one call earlier) -- see renderers/colorbar.py's module
+            # docstring for why a colorbar is screen-space metadata, not a `Panel`.
+            draw_colorbars(self)
+
             # HUD panels are only updated if HUD is enabled, but begin/end must wrap all
             if self.policy.runtime.hud_enabled_this_frame:
                 self.hud.update()
@@ -3303,11 +3355,16 @@ class GPULinePlot:
         from .utils.mpl_process import launch_snapshot_viewer
 
         snap = self.capture_snapshot(scale=2.0)
+        # `or None`, not a bare read: `xlabel`/`ylabel` are now always-present properties
+        # forwarding to the active panel (they used to be attributes that simply did not
+        # exist until `gplt.xlabel()` created them, which is what the `getattr` default
+        # was catching). An unset label is the empty string now, and this viewer's
+        # contract is that "no label" arrives as None.
         launch_snapshot_viewer(
             snap,
-            xlabel=getattr(self, "xlabel", None),
-            ylabel=getattr(self, "ylabel", None),
-            title=getattr(self, "title", None),
+            xlabel=getattr(self, "xlabel", None) or None,
+            ylabel=getattr(self, "ylabel", None) or None,
+            title=getattr(self, "title", None) or None,
         )
 
     def toggle_line_colormap(self) -> None: