geovista.themes =============== .. py:module:: geovista.themes .. autoapi-nested-parse:: Configures custom :doc:`pyvista ` themes for ``geovista``. These themes are discoverable by ``pyvista`` and registered through ``[project.entry-points]`` TOML table metadata (``PEP621``) in our ``pyproject.toml``. Registered themes may be enabled through :func:`geovista.set_plot_theme`, :func:`pyvista.set_plot_theme` or the ``PYVISTA_PLOT_THEME`` environment variable. See Also -------- :func:`pyvista.registered_themes` Enumeration of available registered themes. Notes ----- .. versionadded:: 0.6.0 .. !! processed by numpydoc !! Classes ------- .. autoapisummary:: geovista.themes.GeoVistaDocumentTheme geovista.themes.GeoVistaTheme geovista.themes.ThemeMixin Functions --------- .. autoapisummary:: geovista.themes.resolve_theme_name geovista.themes.restore_plot_theme geovista.themes.set_plot_theme Module Contents --------------- .. py:class:: GeoVistaDocumentTheme Bases: :py:obj:`pyvista.plotting.themes.DocumentTheme`, :py:obj:`ThemeMixin` Theme used for building the documentation. Examples -------- Make the ``geovista_document`` theme the global default using an instance of the theme. >>> import pyvista as pv >>> from geovista.themes import GeoVistaDocumentTheme >>> pv.set_plot_theme(GeoVistaDocumentTheme()) Alternatively, enable the theme via its string name. >>> pv.set_plot_theme("geovista_document") Notes ----- .. versionadded:: 0.6.0 Documentation plotting theme for ``geovista``. .. !! processed by numpydoc !! .. py:class:: GeoVistaTheme Bases: :py:obj:`pyvista.plotting.themes.Theme`, :py:obj:`ThemeMixin` Default ``geovista`` plot theme. Examples -------- Make the ``geovista`` theme the global default using an instance of the theme. >>> import pyvista as pv >>> from geovista.themes import GeoVistaTheme >>> pv.set_plot_theme(GeoVistaTheme()) Alternatively, enable the theme via its string name. >>> pv.set_plot_theme("geovista") Notes ----- .. versionadded:: 0.6.0 Default plotting theme for ``geovista``. .. !! processed by numpydoc !! .. py:class:: ThemeMixin Common ``geovista`` plotting theme property state. .. rubric:: Notes .. versionadded:: 0.6.0 .. !! processed by numpydoc !! .. py:method:: mixin_state() Configure common property state. .. !! processed by numpydoc !! .. py:function:: resolve_theme_name(name) Create an instance of the registered theme or dotted path theme class. :Parameters: **name** : :class:`python:str` The name of the registered theme to lookup or the dotted path ``package.module:ClassName`` theme to be created. :Returns: :obj:`Theme ` | :data:`python:None` An instance of the theme or ``None`` if the requested theme is not registered. :Raises: :obj:`ValueError` When `name` is an invalid dotted path specification or cannot be imported. .. rubric:: Notes .. versionadded:: 0.6.0 .. !! processed by numpydoc !! .. py:function:: restore_plot_theme() Activate the previous plot theme. Provides a convenience to undo the last call to :func:`geovista.themes.set_plot_theme`. Note that the entire call stack history is cached, so multiple calls to :func:`geovista.themes.set_plot_theme` may be undone in reverse order to restore a previous theme. When no cached theme is available, the current theme will remain active and ``None`` is returned. :Returns: :obj:`Theme ` | :data:`python:None` The previously cached theme if available, otherwise ``None``. .. rubric:: Notes .. versionadded:: 0.6.0 .. !! processed by numpydoc !! .. py:function:: set_plot_theme(theme, /, *, bootstrap = False) Set plotting parameters to a predefined theme. The enabled plot theme will be used by all plotters and rendering. Requests to enable a plot theme will be ignored when the environment variable ``GEOVISTA_DISABLE_PLOT_THEME`` is set. Note that the replaced theme is cached and may be restored with :func:`geovista.themes.restore_plot_theme`. :Parameters: **theme** : :obj:`Theme ` or :class:`python:str` The theme to apply, which may be either: * The string name of a registered theme. See :func:`pyvista.registered_themes` for the available :doc:`pyvista ` built-in and third-party entry-point group themes. * A string ``package.module:ClassName`` dotted path to an importable :class:`pyvista.plotting.themes.Theme` subclass. * A :class:`pyvista.plotting.themes.Theme` subclass instance. **bootstrap** : :class:`python:bool`, default=False When ``True``, theme configuration is skipped if the environment variable ``PYVISTA_PLOT_THEME`` is set. Otherwise, the provided `theme` will be enabled regardless of that environment variable. This behaviour allows a pre-defined ``PYVISTA_PLOT_THEME`` to take precedence. :Returns: :class:`python:bool` ``True`` if the theme was successfully enabled, otherwise ``False``. :Raises: :obj:`ValueError` When `theme` is an invalid dotted path specification or cannot be imported. .. seealso:: :func:`geovista.themes.restore_plot_theme` Reinstates the plot theme to the previous replaced theme. :func:`pyvista.registered_themes` The list of available registered themes. :class:`pyvista.plotting.themes.Theme` Base class for all themes. Subclasses with the class property ``_default_name`` are discoverable by :doc:`pyvista `. .. rubric:: Notes .. versionadded:: 0.6.0 .. rubric:: Examples .. pyvista-plot:: Set the default ``geovista`` theme. >>> import geovista as gv >>> gv.set_plot_theme("geovista") True Set the pyvista dark theme. >>> gv.set_plot_theme("dark") True Load a theme from an importable package module specified as a dotted path. >>> gv.set_plot_theme("geovista.themes:GeoVistaTheme") True Set the pyvista paraview theme. >>> from pyvista import themes >>> gv.set_plot_theme(themes.ParaViewTheme()) True .. !! processed by numpydoc !!