py-pluto 1.1.4__py3-none-any.whl

pyPLUTO/image.py

@@ -0,0 +1,302 @@
+"""Image class. It plots the data."""
+
+# ruff: noqa: ANN201  # noqa: RUF100
+
+from __future__ import annotations
+
+from typing import Unpack
+
+from pyPLUTO.amr import oplotbox
+from pyPLUTO.imagefuncs.colorbar import ColorbarManager
+from pyPLUTO.imagefuncs.contour import ContourManager
+from pyPLUTO.imagefuncs.create_axes import CreateAxesManager
+from pyPLUTO.imagefuncs.display import DisplayManager
+from pyPLUTO.imagefuncs.figure import FigureManager
+from pyPLUTO.imagefuncs.imagetools import ImageToolsManager
+from pyPLUTO.imagefuncs.interactive import InteractiveManager
+from pyPLUTO.imagefuncs.legend import LegendManager
+from pyPLUTO.imagefuncs.plot import PlotManager
+from pyPLUTO.imagefuncs.range import RangeManager
+from pyPLUTO.imagefuncs.scatter import ScatterManager
+from pyPLUTO.imagefuncs.set_axis import AxisManager
+from pyPLUTO.imagefuncs.streamplot import StreamplotManager
+from pyPLUTO.imagefuncs.zoom import ZoomManager
+from pyPLUTO.imagemixin import ImageMixin
+from pyPLUTO.imagestate import ImageState
+from pyPLUTO.utils.annotator import AllKwargs
+from pyPLUTO.utils.inspector import track_kwargs
+
+
+class Image(ImageMixin):
+    """Description of the Image class.
+
+    The Image class is a facade for the different managers that handle the
+    various aspects of plotting, such as creating axes, displaying data, adding
+    legends, text, fieldlines, colorbars, and more. It provides a unified
+    interface for creating and managing plots in a figure. The attributes are
+    handled through the `ImageState` class, which is a dataclass that stores the
+    state of the image, such as the figure, axes, and other properties. The
+    `Image` class uses a mediator pattern to manage the interactions between the
+    different managers and the state.
+
+    """
+
+    @track_kwargs
+    def __init__(
+        self,
+        text: bool = True,
+        check: bool = True,
+        **kwargs: Unpack[AllKwargs],
+    ) -> None:
+        """Initialize the Image class.
+
+        Ihat creates a new figure and sets the LaTeX conditions, as well as the
+        matplotlib style. Every Image is associated to a figure object and only
+        one in order to avoid confusion between images and figures. If you want
+        to create multiple figures, you have to create multiple Image objects.
+
+        Returns
+        -------
+        - None
+
+        Parameters
+        ----------
+        - close: bool, default True
+            If True, the existing figure with the same window number is closed.
+        - fig: Figure | None, default None
+            The figure instance. If not None, the figure is used (only
+            if we need to associate an Image to an existing figure).
+        - figsize: list[float], default [8,5]
+            The figure size.
+        - fontsize: int, default 17
+            The font size.
+        - LaTeX: bool | str, default False
+            The LaTeX option. Is True is selected, the default LaTeX font
+            is used. If 'pgf' is selected, the pgf backend is used to save pdf
+            figures with minimal file size. If XeLaTeX is not installed and the
+            'pgf' option is selected, the LaTeX option True is used as backup
+            strategy.
+        - numcolors: int, default 10
+            The number of colors in the colorscheme. The default number is 10,
+            but the full list contains 24 colors (+ black or white).
+        - nwin: int, default 1
+            The window number.
+        - oldcolor: bool, default False
+            if True, the old colors are used
+        - style: str, default 'default'
+            The style of the figure. Possible values are: 'seaborn', 'ggplot',
+            'fivethirtyeight', 'bmh', 'grayscale', 'dark_background', 'classic',
+            etc.
+        - suptitle: str, default None
+            The super title of the figure.
+        - suptitlesize: str | int, default 'large'
+            The figure title size.
+        - tight: bool, default True
+            If True, the tight layout is used.
+        - withblack: bool, default False
+            If True, the black color is used as first color.
+        - withwhite: bool, default False
+            If True, the white color is used as first color.
+
+        ----
+
+        Examples
+        --------
+        - Example #1: create an empty image
+
+            >>> import pyPLUTO as pp
+            >>> I = pp.Image()
+
+        - Example #2: create an image with the pgf backend
+
+            >>> import pyPLUTO as pp
+            >>> I = pp.Image(LaTeX="pgf")
+
+        - Example #3: create an image with the LaTeX option True
+
+            >>> import pyPLUTO as pp
+            >>> I = pp.Image(LaTeX=True)
+
+        - Example #4: create an image with fixed size
+
+            >>> import pyPLUTO as pp
+            >>> I = pp.Image(figsize=[5, 5])
+
+        - Example #5: create an image with a title
+
+            >>> import pyPLUTO as pp
+            >>> I = pp.Image(suptitle="Title")
+
+        """
+        kwargs.pop("kwargscheck", check)
+
+        self.state = ImageState()
+
+        self.FigureManager = FigureManager(self.state, **kwargs)
+
+        # Initialize managers
+        self.AxisManager = AxisManager(self.state)
+        self.ColorbarManager = ColorbarManager(self.state)
+        self.ContourManager = ContourManager(self.state)
+        self.CreateAxesManager = CreateAxesManager(self.state)
+        self.DisplayManager = DisplayManager(self.state)
+        self.ImageToolsManager = ImageToolsManager(self.state)
+        self.InteractiveManager = InteractiveManager(self.state)
+        self.LegendManager = LegendManager(self.state)
+        self.PlotManager = PlotManager(self.state)
+        self.RangeManager = RangeManager(self.state)
+        self.ScatterManager = ScatterManager(self.state)
+        self.StreamplotManager = StreamplotManager(self.state)
+        self.ZoomManager = ZoomManager(self.state)
+
+        if text:
+            print(f"Image class created at nwin {self.nwin}")
+
+    def __str__(self) -> str:
+        """Print the Image class."""
+        return r"""
+        Image class.
+        It plots the data.
+
+        Image properties:
+        - Figure size        (figsize)
+        - Window number      (nwin)
+        - Number of subplots (nrow0 x ncol0)
+        - Global fontsize    (fontsize)
+
+        Public methods available:
+
+        - create_axes
+            Adds a set of [nrow,ncol] subplots to the figure.
+        - colorbar
+            Places a colorbar in a subplot or next to a subplot.
+        - contour
+            Plots a contour plot in a subplot.
+        - display
+            Plots a 2D quantity in a subplot.
+        - interactive
+            Creates an interactive plot with a slider to change the data.
+        - legend
+            Places one legend in a subplot.
+        - set_axis
+            Changes the parameter of a specific subplot.
+        - plot
+            Plots one line in a subplot.
+        - savefig
+            Saves the figure in a file.
+        - scatter
+            Plots a scatter plot in a subplot.
+        - streamplot
+            Plots a stream plot in a subplot.
+        - text
+            Places the text in the figure or in a subplot.
+        - zoom
+            Creates an inset zoom region of a subplot.
+
+        Public attributes available:
+
+        - ax:
+            The list of relevant axes in the figure.
+        - fig
+            The figure associated to the image.
+        - fontsize
+            The fontsize in the figure.
+        - fontweight
+            The fontweight in the figure.
+        - nwin
+            The window number.
+        - tg
+            The tight layout of the figure.
+
+        Please do not use 'private' methods and attributes if not absolutely
+        necessary.
+        """
+
+    def __getattr__(self, name: str) -> object:
+        """Get the attribute of the Image class."""
+        return getattr(self.state, name)
+
+    def __setattr__(self, name: str, value: object) -> None:
+        """Set the attribute of the Image class."""
+        if name == "state" or not hasattr(self, "state"):
+            return super().__setattr__(name, value)
+        return setattr(self.state, name, value)
+
+    @property
+    def animate(self):
+        """Property for the animate method."""
+        return self.InteractiveManager.animate
+
+    @property
+    def colorbar(self):
+        """Property for the colorbar method."""
+        return self.ColorbarManager.colorbar
+
+    @property
+    def contour(self):
+        """Property for the contour method."""
+        return self.ContourManager.contour
+
+    @property
+    def create_axes(self):
+        """Property for the create_axes method."""
+        return self.CreateAxesManager.create_axes
+
+    @property
+    def display(self):
+        """Property for the display method."""
+        return self.DisplayManager.display
+
+    @property
+    def interactive(self):
+        """Property for the interactive method."""
+        return self.InteractiveManager.interactive
+
+    @property
+    def legend(self):
+        """Property for the legend method."""
+        return self.LegendManager.legend
+
+    @property
+    def plot(self):
+        """Property for the plot method."""
+        return self.PlotManager.plot
+
+    @property
+    def savefig(self):
+        """Property for the savefig method."""
+        return self.ImageToolsManager.savefig
+
+    @property
+    def scatter(self):
+        """Property for the scatter method."""
+        return self.ScatterManager.scatter
+
+    @property
+    def set_axis(self):
+        """Property for the set_axis method."""
+        return self.AxisManager.set_axis
+
+    @property
+    def show(self):
+        """Property for the show method."""
+        return self.ImageToolsManager.show
+
+    @property
+    def text(self):
+        """Property for the text method."""
+        return self.ImageToolsManager.text
+
+    @property
+    def streamplot(self):
+        """Property for the streamplot method."""
+        return self.StreamplotManager.streamplot
+
+    @property
+    def zoom(self):
+        """Property for the zoom method."""
+        return self.ZoomManager.zoom
+
+    def oplotbox(self, *args: object, **kwargs: object) -> None:
+        """Plot a box in the figure (AMR, WIP)."""
+        oplotbox(self, *args, **kwargs)

pyPLUTO/imagefuncs/colorbar.py

@@ -0,0 +1,240 @@
+"""Module providing colorbar management functionalities for image displays."""
+
+import warnings
+from typing import Any
+
+from matplotlib.axes import Axes
+from matplotlib.collections import LineCollection, PathCollection, QuadMesh
+from matplotlib.contour import QuadContourSet
+from mpl_toolkits.axes_grid1 import make_axes_locatable
+
+from pyPLUTO.imagefuncs.imagetools import ImageToolsManager
+from pyPLUTO.imagemixin import ImageMixin
+from pyPLUTO.imagestate import ImageState
+from pyPLUTO.utils.inspector import track_kwargs
+
+# class MyKwargs(TypedDict, total=False):
+#    """TypedDict for keyword arguments."""
+#
+#    clabel: str
+#    cpad: float
+#    cpos: str
+#    cticks: list[float] | None
+#    ctickslabels: list[str]
+#    extend: str
+#    extendrect: bool
+
+
+class ColorbarManager(ImageMixin):
+    """Class to manage the colorbar in the image.
+
+    This class provides methods to create and manage colorbars in the image
+    class. It allows for customization of the colorbar's position, size,
+    ticks, labels, and other properties.
+    """
+
+    exposed_methods = ("colorbar",)
+
+    def __init__(self, state: ImageState) -> None:
+        """Initialize the ColorbarManager with the given state."""
+        self.state = state
+        self.ImageToolsManager = ImageToolsManager(state)
+
+    @track_kwargs
+    def colorbar(
+        self,
+        pcm: (
+            QuadMesh | PathCollection | LineCollection | QuadContourSet | None
+        ) = None,
+        axs: Axes | int | None = None,
+        cax: Axes | int | None = None,
+        check: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        """Display a colorbar in a selected position.
+
+        The colorbar will be placed next to the axis axs. If the keyword cax is
+        enabled the colorbar is located in a specific axis, otherwise an axis
+        will be shrunk in order to place the colorbar.
+
+        Returns
+        -------
+        - None
+
+        Parameters
+        ----------
+        - axs: axis object, default None
+            The axes where the display that will be used for the colorbar is
+            located. If None, the last considered axis will be used.
+        - cax: axis object, default None
+            The axes where the colorbar should be placed. If None, the colorbar
+            will be placed next to the axis axs.
+        - clabel: str, default None
+            Sets the label of the colorbar.
+        - cpad: float, default 0.07
+            Fraction of original axes between colorbar and the axes (in case cax
+            is not defined).
+        - cpos: {'top','bottom','left','right'}, default 'right'
+            Sets the position of the colorbar.
+        - cticks: {[float], None}, default None
+            If enabled (and different from None), sets manually ticks on the
+            colorbar.
+        - ctickslabels: str, default None
+            If enabled, sets manually ticks labels on the colorbar.
+        - extend: {'neither','both','min','max'}, default 'neither'
+            Sets the extension of the triangular colorbar extension.
+        - extendrect: bool, default False
+            If True, the colorbar extension will be rectangular.
+        - pcm: QuadMesh | PathCollection | None, default None
+            The collection to be used for the colorbar. If None, the axs will be
+            used. If both pcm and axs are not None, pcm will be used.
+
+        ----
+
+        Examples
+        --------
+        - Example #1: create a standard colorbar on the right
+
+            >>> import pyPLUTO as pp
+            >>> I = pp.Image()
+            >>> I.display(var)
+            >>> I.colorbar()
+
+        - Example #2: create a colorbar in a different axis
+
+            >>> import pyPLUTO as pp
+            >>> I = pp.Image()
+            >>> ax = I.create_axes(ncol=2)
+            >>> I.display(var, ax=ax[0])
+            >>> I.colorbar(axs=ax[0], cax=ax[1])
+
+        - Example #3: create a set of 3 displays with a colorbar on the bottom.
+            Another colorbar is shown on the right of the topmost display
+
+            >>> import pyPLUTO as pp
+            >>> I = pp.Image()
+            >>> ax = I.create_axes(nrow=4)
+            >>> I.display(var1, ax=ax[0])
+            >>> I.colorbar(axs=ax[0])
+            >>> I.display(var2, ax=ax[1])
+            >>> I.display(var3, ax=ax[2])
+            >>> I.colorbar(axs=ax[2], cax=ax[3])
+
+        """
+        # Check parameters
+        if not isinstance(check, bool):
+            raise TypeError("check must be a boolean value.")
+
+        # If pcm and a source axes are selected, raise a warning and use pcm
+        if pcm is not None and axs is not None:
+            warn = "Both pcm and axs are not None, pcm will be used"
+            warnings.warn(warn, UserWarning, stacklevel=2)
+
+        # Standard check on the figure
+        if self.state.fig is None:
+            raise ValueError(
+                "No figure is present. Please create a figure first."
+            )
+
+        # Assign the source axis
+        axs = self._find_ax(pcm, axs, **kwargs)
+
+        # Select the keywords to position the colorbar
+        if pcm is None:
+            collection = axs.collections[0]
+            if not isinstance(collection, QuadMesh):
+                raise TypeError("First collection is not a QuadMesh")
+            pcm = collection
+        cpad = kwargs.get("cpad", 0.07)
+        cpos = kwargs.get("cpos", "right")
+        ccor = "vertical" if cpos in ["left", "right"] else "horizontal"
+
+        # Assign the colorbar axis, if cax is None create a new one
+        if cax is None:
+            divider = make_axes_locatable(axs)
+            cax = divider.append_axes(cpos, size="7%", pad=cpad)
+        else:
+            cax, naxc = self.ImageToolsManager.assign_ax(cax, **kwargs)
+            self.ImageToolsManager.hide_text(naxc, cax.texts)
+
+        # Check if the cax is an Axes instance
+        if not isinstance(cax, Axes):
+            raise TypeError("cax must be an Axes instance.")
+
+        # Place the colorbar
+        cbar = self.state.fig.colorbar(
+            pcm,
+            cax=cax,
+            label=kwargs.get("clabel", ""),
+            ticks=kwargs.get("cticks"),
+            orientation=ccor,
+            extend=kwargs.get("extend", "neither"),
+            extendrect=kwargs.get("extendrect", False),
+        )
+
+        # Set the tickslabels
+        ctkc = kwargs.get("ctickslabels", "Default")
+        if ctkc != "Default":
+            cbar.ax.set_yticklabels(ctkc)
+
+        # Ensure, if needed, the tight layout
+        if self.state.tight:
+            self.state.fig.tight_layout()
+
+        # End of function
+
+    @track_kwargs
+    def _find_ax(
+        self,
+        pcm: (
+            QuadMesh | PathCollection | LineCollection | QuadContourSet | None
+        ) = None,
+        axs: Axes | int | None = None,
+        **kwargs: Any,
+    ) -> Axes:
+        """Find and return the appropriate axis based on the input.
+
+        Parameters
+        ----------
+        - axs: Axes | int | None, default None
+            The axis or index of the axis to find. If None, the last used axis
+            will be returned.
+
+        Returns
+        -------
+        - Axes
+            The found axis object.
+
+        Raises
+        ------
+        - ValueError
+            If no figure is present or if the specified axis index is invalid.
+        - TypeError
+            If the provided axs parameter is not of type Axes or int.
+
+        """
+        # Standard check on the figure
+        if self.state.fig is None:
+            raise ValueError(
+                "No figure is present. Please create a figure first."
+            )
+        # Standard check on the figure
+        # Select the source axis
+        if pcm is not None:
+            # If the pcm is not none, use it and find the corresponding axes
+            if not isinstance(pcm.axes, Axes):
+                raise TypeError("Expected an Axes instance.")
+            axs = pcm.axes
+        elif axs is None:
+            # If axs is None, use the current axes
+            gca = self.state.fig.gca()
+            if not isinstance(gca, Axes):
+                raise TypeError("gca() did not return an Axes instance.")
+            axs = gca
+        axs, _ = self.ImageToolsManager.assign_ax(axs, **kwargs)
+        if self.state.fig is None:
+            raise ValueError(
+                "No figure is present. Please create a figure first."
+            )
+
+        return axs