cjw/geMoldInsight
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
89660bba4eaf5d3a2bb17d8285703d0f2b1cad27
geMoldInsight/venv/lib/python3.11/site-packages/pyvista/plotting/themes.py
T

3498 lines
100 KiB
Python
Raw Normal View History

init
2026-02-12 23:22:11 +08:00
"""API description for managing plotting theme parameters in pyvista.
Examples
--------
Apply a built-in theme
>>> import pyvista as pv
>>> pv.set_plot_theme('default')
>>> pv.set_plot_theme('document')
>>> pv.set_plot_theme('dark')
>>> pv.set_plot_theme('paraview')
Load a theme into pyvista
>>> from pyvista.plotting.themes import DocumentTheme
>>> theme = DocumentTheme()
>>> theme.save('my_theme.json') # doctest:+SKIP
>>> loaded_theme = pv.load_theme('my_theme.json') # doctest:+SKIP
Create a custom theme from the default theme and load it into
pyvista.
>>> my_theme = DocumentTheme()
>>> my_theme.font.size = 20
>>> my_theme.font.title_size = 40
>>> my_theme.cmap = 'jet'
>>> pv.global_theme.load_theme(my_theme)
>>> pv.global_theme.font.size
20
"""
from __future__ import annotations
from enum import Enum
from itertools import chain
import json
import os
import pathlib
from pathlib import Path
from typing import TYPE_CHECKING
from typing import Any
import warnings
import pyvista # noqa: TC001
from pyvista.core.utilities.misc import _check_range
from .colors import Color
from .colors import get_cmap_safe
from .colors import get_cycler
from .opts import InterpolationType
from .tools import parse_font_family
if TYPE_CHECKING:
from collections.abc import Callable
from pyvista.core._typing_core import VectorLike
from pyvista.jupyter import JupyterBackendOptions
from ._typing import ColorLike
from ._typing import ColormapOptions
def _set_plot_theme_from_env() -> None:
"""Set plot theme from an environment variable."""
if 'PYVISTA_PLOT_THEME' in os.environ:
try:
theme = os.environ['PYVISTA_PLOT_THEME']
set_plot_theme(theme.lower())
except ValueError:
allowed = ', '.join([item.name for item in _NATIVE_THEMES])
warnings.warn(
f'\n\nInvalid PYVISTA_PLOT_THEME environment variable "{theme}". '
f'Should be one of the following: {allowed}',
)
def load_theme(filename):
"""Load a theme from a file.
Parameters
----------
filename : str
Theme file. Must be json.
Returns
-------
pyvista.Theme
The loaded theme.
Examples
--------
>>> import pyvista as pv
>>> from pyvista.plotting.themes import DocumentTheme
>>> theme = DocumentTheme()
>>> theme.save('my_theme.json') # doctest:+SKIP
>>> loaded_theme = pv.load_theme('my_theme.json') # doctest:+SKIP
"""
with Path(filename).open() as f:
theme_dict = json.load(f)
return Theme.from_dict(theme_dict)
def set_plot_theme(theme):
"""Set the plotting parameters to a predefined theme using a string.
Parameters
----------
theme : str
Theme name. Either ``'default'``, ``'document'``, ``'dark'``,
or ``'paraview'``.
Examples
--------
Set to the default theme.
>>> import pyvista as pv
>>> pv.set_plot_theme('default')
Set to the document theme.
>>> pv.set_plot_theme('document')
Set to the dark theme.
>>> pv.set_plot_theme('dark')
Set to the ParaView theme.
>>> pv.set_plot_theme('paraview')
"""
import pyvista # noqa: PLC0415
if isinstance(theme, str):
theme = theme.lower()
try:
new_theme_type = _NATIVE_THEMES[theme].value
except KeyError:
msg = f"Theme {theme} not found in PyVista's native themes."
raise ValueError(msg)
pyvista.global_theme.load_theme(new_theme_type())
elif isinstance(theme, Theme):
pyvista.global_theme.load_theme(theme)
else:
msg = (
f'Expected a ``pyvista.plotting.themes.Theme`` or ``str``, not {type(theme).__name__}'
)
raise TypeError(msg)
# Mostly from https://stackoverflow.com/questions/56579348/how-can-i-force-subclasses-to-have-slots
class _ForceSlots(type):
"""Metaclass to force classes and subclasses to have __slots__."""
@classmethod
def __prepare__(cls, name, bases, **kwargs): # type: ignore[override]
super_prepared = super().__prepare__(cls, name, bases, **kwargs) # type: ignore[arg-type, call-arg, misc]
super_prepared['__slots__'] = ()
return super_prepared
class _ThemeConfig(metaclass=_ForceSlots):
"""Provide common methods for theme configuration classes."""
__slots__: list[str] = []
@classmethod
def from_dict(cls, dict_):
"""Create from a dictionary."""
inst = cls()
for key, value in dict_.items():
attr = getattr(inst, key)
if hasattr(attr, 'from_dict'):
setattr(inst, key, attr.from_dict(value))
else:
setattr(inst, key, value)
return inst
def to_dict(self) -> dict[str, Any]:
"""Return theme config parameters as a dictionary.
Returns
-------
dict
This theme parameter represented as a dictionary.
"""
# remove the first underscore in each entry
dict_ = {}
for key in self._all__slots__():
value = getattr(self, key)
key_ = key[1:]
if hasattr(value, 'to_dict'):
dict_[key_] = value.to_dict()
else:
dict_[key_] = value
return dict_
def __eq__(self, other) -> bool:
if not isinstance(other, _ThemeConfig):
return False
for attr_name in other._all__slots__():
attr = getattr(self, attr_name)
other_attr = getattr(other, attr_name)
if (
isinstance(attr, (tuple, list)) and tuple(attr) != tuple(other_attr)
) or not attr == other_attr:
return False
return True
__hash__ = None # type: ignore[assignment] # https://github.com/pyvista/pyvista/pull/7671
def __getitem__(self, key):
"""Get a value via a key.
Implemented here for backwards compatibility.
"""
return getattr(self, key)
def __setitem__(self, key, value):
"""Set a value via a key.
Implemented here for backwards compatibility.
"""
setattr(self, key, value)
@classmethod
def _all__slots__(cls):
"""Get all slots including parent classes."""
mro = cls.mro()
return tuple(chain.from_iterable(c.__slots__ for c in mro if c is not object)) # type: ignore[attr-defined]
class _LightingConfig(_ThemeConfig):
"""PyVista lighting configuration.
This will control the lighting interpolation type, parameters,
and Physically Based Rendering (PBR) options
Examples
--------
Set global PBR parameters.
>>> import pyvista as pv
>>> pv.global_theme.lighting_params.interpolation = 'pbr'
>>> pv.global_theme.lighting_params.metallic = 0.5
>>> pv.global_theme.lighting_params.roughness = 0.25
"""
__slots__ = [
'_ambient',
'_diffuse',
'_emissive',
'_interpolation',
'_metallic',
'_roughness',
'_specular',
'_specular_power',
]
def __init__(self):
self._interpolation = InterpolationType.FLAT.value
self._metallic = 0.0
self._roughness = 0.5
self._ambient = 0.0
self._diffuse = 1.0
self._specular = 0.0
self._specular_power = 100.0
self._emissive = False
@property
def interpolation(self) -> InterpolationType: # numpydoc ignore=RT01
"""Return or set the default interpolation type.
See :class:`pyvista.plotting.opts.InterpolationType`.
Options are:
* ``'Phong'``
* ``'Flat'``
* ``'Physically based rendering'``
This is stored as an integer value of the ``InterpolationType``
so that the theme can be JSON-serializable.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.lighting_params.interpolation = 'Phong'
>>> pv.global_theme.lighting_params.interpolation
<InterpolationType.PHONG: 2>
"""
return InterpolationType.from_any(self._interpolation)
@interpolation.setter
def interpolation(
self,
interpolation: str | int | InterpolationType,
):
self._interpolation = InterpolationType.from_any(interpolation).value
@property
def metallic(self) -> float: # numpydoc ignore=RT01
"""Return or set the metallic value.
This requires that the interpolation be set to ``'Physically based
rendering'``. Must be between 0 and 1.
Examples
--------
Set the global metallic value used in physically based rendering to
``0.5``.
>>> import pyvista as pv
>>> pv.global_theme.lighting_params.metallic = 0.5
>>> pv.global_theme.lighting_params.metallic
0.5
"""
return self._metallic
@metallic.setter
def metallic(self, metallic: float):
_check_range(metallic, (0, 1), 'metallic')
self._metallic = metallic
@property
def roughness(self) -> float: # numpydoc ignore=RT01
"""Return or set the roughness value.
This value has to be between 0 (glossy) and 1 (rough). A glossy
material has reflections and a high specular part. This parameter is
only used by PBR interpolation.
Examples
--------
Set the global roughness value used in physically based rendering to
``0.25``.
>>> import pyvista as pv
>>> pv.global_theme.lighting_params.roughness = 0.25
>>> pv.global_theme.lighting_params.roughness
0.25
"""
return self._roughness
@roughness.setter
def roughness(self, roughness: float):
_check_range(roughness, (0, 1), 'roughness')
self._roughness = roughness
@property
def ambient(self) -> float: # numpydoc ignore=RT01
"""Return or set the ambient value.
When lighting is enabled, this is the amount of light in the range of 0
to 1 that reaches the actor when not directed at the light source
emitted from the viewer.
Examples
--------
Set the global ambient lighting value to ``0.2``.
>>> import pyvista as pv
>>> pv.global_theme.lighting_params.ambient = 0.2
>>> pv.global_theme.lighting_params.ambient
0.2
"""
return self._ambient
@ambient.setter
def ambient(self, ambient: float):
_check_range(ambient, (0, 1), 'ambient')
self._ambient = ambient
@property
def diffuse(self) -> float: # numpydoc ignore=RT01
"""Return or set the diffuse value.
This is the scattering of light by reflection or
transmission. Diffuse reflection results when light strikes an
irregular surface such as a frosted window or the surface of a
frosted or coated light bulb. Must be between 0 and 1.
Examples
--------
Set the global diffuse lighting value to ``0.5``.
>>> import pyvista as pv
>>> pv.global_theme.lighting_params.diffuse = 0.5
>>> pv.global_theme.lighting_params.diffuse
0.5
"""
return self._diffuse
@diffuse.setter
def diffuse(self, diffuse: float):
_check_range(diffuse, (0, 1), 'diffuse')
self._diffuse = diffuse
@property
def specular(self) -> float: # numpydoc ignore=RT01
"""Return or set the specular value.
Specular lighting simulates the bright spot of a light that appears
on shiny objects. Must be between 0 and 1.
Examples
--------
Set the global specular value to ``0.1``.
>>> import pyvista as pv
>>> pv.global_theme.lighting_params.specular = 0.1
>>> pv.global_theme.lighting_params.specular
0.1
"""
return self._specular
@specular.setter
def specular(self, specular: float):
_check_range(specular, (0, 1), 'specular')
self._specular = specular
@property
def specular_power(self) -> float: # numpydoc ignore=RT01
"""Return or set the specular power value.
Must be between 0.0 and 128.0.
Examples
--------
Set the global specular power value to ``50``.
>>> import pyvista as pv
>>> pv.global_theme.lighting_params.specular_power = 50
>>> pv.global_theme.lighting_params.specular_power
50
"""
return self._specular_power
@specular_power.setter
def specular_power(self, specular_power: float):
_check_range(specular_power, (0, 128), 'specular_power')
self._specular_power = specular_power
@property
def emissive(self) -> bool: # numpydoc ignore=RT01
"""Return or set if emissive is used with point Gaussian style.
Examples
--------
Globally enable emissive lighting when using the point Gaussian style.
>>> import pyvista as pv
>>> pv.global_theme.lighting_params.emissive = True
>>> pv.global_theme.lighting_params.emissive
True
"""
return self._emissive
@emissive.setter
def emissive(self, emissive: bool):
self._emissive = bool(emissive)
class _DepthPeelingConfig(_ThemeConfig):
"""PyVista depth peeling configuration.
Examples
--------
Set global depth peeling parameters.
>>> import pyvista as pv
>>> pv.global_theme.depth_peeling.number_of_peels = 1
>>> pv.global_theme.depth_peeling.occlusion_ratio = 0.0
>>> pv.global_theme.depth_peeling.enabled = True
"""
__slots__ = ['_enabled', '_number_of_peels', '_occlusion_ratio']
def __init__(self):
self._number_of_peels = 4
self._occlusion_ratio = 0.0
self._enabled = False
@property
def number_of_peels(self) -> int: # numpydoc ignore=RT01
"""Return or set the number of peels in depth peeling.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.depth_peeling.number_of_peels = 1
"""
return self._number_of_peels
@number_of_peels.setter
def number_of_peels(self, number_of_peels: int):
self._number_of_peels = int(number_of_peels)
@property
def occlusion_ratio(self) -> float: # numpydoc ignore=RT01
"""Return or set the occlusion ratio in depth peeling.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.depth_peeling.occlusion_ratio = 0.0
"""
return self._occlusion_ratio
@occlusion_ratio.setter
def occlusion_ratio(self, occlusion_ratio: float):
self._occlusion_ratio = float(occlusion_ratio)
@property
def enabled(self) -> bool: # numpydoc ignore=RT01
"""Return or set if depth peeling is enabled.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.depth_peeling.enabled = True
"""
return self._enabled
@enabled.setter
def enabled(self, enabled: bool):
self._enabled = bool(enabled)
def __repr__(self):
txt = ['']
parm = {
'Number': 'number_of_peels',
'Occlusion ratio': 'occlusion_ratio',
'Enabled': 'enabled',
}
for name, attr in parm.items():
setting = getattr(self, attr)
txt.append(f' {name:<21}: {setting}')
return '\n'.join(txt)
class _SilhouetteConfig(_ThemeConfig):
"""PyVista silhouette configuration.
Examples
--------
Set global silhouette parameters.
>>> import pyvista as pv
>>> pv.global_theme.silhouette.enabled = True
>>> pv.global_theme.silhouette.color = 'grey'
>>> pv.global_theme.silhouette.line_width = 2
>>> pv.global_theme.silhouette.feature_angle = 20
"""
__slots__ = [
'_color',
'_decimate',
'_enabled',
'_feature_angle',
'_line_width',
'_opacity',
]
def __init__(self):
self._color = Color('black')
self._line_width = 2
self._opacity = 1.0
self._feature_angle = None
self._decimate = None
self._enabled = False
@property
def enabled(self) -> bool: # numpydoc ignore=RT01
"""Return or set whether silhouette is on or off."""
return self._enabled
@enabled.setter
def enabled(self, enabled: bool):
self._enabled = bool(enabled)
@property
def color(self) -> Color: # numpydoc ignore=RT01
"""Return or set the silhouette color.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.silhouette.color = 'red'
"""
return self._color
@color.setter
def color(self, color: ColorLike):
self._color = Color(color)
@property
def line_width(self) -> float: # numpydoc ignore=RT01
"""Return or set the silhouette line width.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.silhouette.line_width = 2.0
"""
return self._line_width
@line_width.setter
def line_width(self, line_width: float):
self._line_width = float(line_width) # type: ignore[assignment]
@property
def opacity(self) -> float: # numpydoc ignore=RT01
"""Return or set the silhouette opacity.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.silhouette.opacity = 1.0
"""
return self._opacity
@opacity.setter
def opacity(self, opacity: float):
_check_range(opacity, (0, 1), 'opacity')
self._opacity = float(opacity)
@property
def feature_angle(self) -> float | None: # numpydoc ignore=RT01
"""Return or set the silhouette feature angle.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.silhouette.feature_angle = 20.0
"""
return self._feature_angle
@feature_angle.setter
def feature_angle(self, feature_angle: float | None):
self._feature_angle = feature_angle
@property
def decimate(self) -> float: # numpydoc ignore=RT01
"""Return or set the amount to decimate the silhouette.
Parameter must be between 0 and 1.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.silhouette.decimate = 0.9
"""
return self._decimate # type: ignore[return-value]
@decimate.setter
def decimate(self, decimate: float | None):
if decimate is None:
self._decimate = None
else:
_check_range(decimate, (0, 1), 'decimate')
self._decimate = float(decimate)
def __repr__(self):
txt = ['']
parm = {
'Color': 'color',
'Line width': 'line_width',
'Opacity': 'opacity',
'Feature angle': 'feature_angle',
'Decimate': 'decimate',
}
for name, attr in parm.items():
setting = getattr(self, attr)
txt.append(f' {name:<21}: {setting}')
return '\n'.join(txt)
class _ColorbarConfig(_ThemeConfig):
"""PyVista colorbar configuration.
Examples
--------
Set the colorbar width.
>>> import pyvista as pv
>>> pv.global_theme.colorbar_horizontal.width = 0.2
"""
__slots__ = ['_height', '_position_x', '_position_y', '_width']
def __init__(self):
self._width = None
self._height = None
self._position_x = None
self._position_y = None
@property
def width(self) -> float: # numpydoc ignore=RT01
"""Return or set colorbar width.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.colorbar_horizontal.width = 0.2
"""
return self._width # type: ignore[return-value]
@width.setter
def width(self, width: float):
self._width = float(width)
@property
def height(self) -> float: # numpydoc ignore=RT01
"""Return or set colorbar height.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.colorbar_horizontal.height = 0.2
"""
return self._height # type: ignore[return-value]
@height.setter
def height(self, height: float):
self._height = float(height)
@property
def position_x(self) -> float: # numpydoc ignore=RT01
"""Return or set colorbar x position.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.colorbar_horizontal.position_x = 0.2
"""
return self._position_x # type: ignore[return-value]
@position_x.setter
def position_x(self, position_x: float):
self._position_x = float(position_x)
@property
def position_y(self) -> float: # numpydoc ignore=RT01
"""Return or set colorbar y position.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.colorbar_horizontal.position_y = 0.2
"""
return self._position_y # type: ignore[return-value]
@position_y.setter
def position_y(self, position_y: float):
self._position_y = float(position_y)
def __repr__(self):
txt = ['']
parm = {
'Width': 'width',
'Height': 'height',
'X Position': 'position_x',
'Y Position': 'position_y',
}
for name, attr in parm.items():
setting = getattr(self, attr)
txt.append(f' {name:<21}: {setting}')
return '\n'.join(txt)
class _AxesConfig(_ThemeConfig):
"""PyVista axes configuration.
Examples
--------
Show the default axes configuration values.
>>> import pyvista as pv
>>> pv.global_theme.axes.x_color
Color(name='tomato', hex='#ff6347ff', opacity=255)
>>> pv.global_theme.axes.y_color
Color(name='seagreen', hex='#2e8b57ff', opacity=255)
>>> pv.global_theme.axes.z_color
Color(name='blue', hex='#0000ffff', opacity=255)
>>> pv.global_theme.axes.box
False
>>> pv.global_theme.axes.show
True
Set the x-axis color to black.
>>> pv.global_theme.axes.x_color = 'black'
Show the axes orientation widget by default.
>>> pv.global_theme.axes.show = True
Use the :func:`axes orientation box <pyvista.create_axes_orientation_box>`
as the orientation widget.
>>> pv.global_theme.axes.box = True
"""
__slots__ = ['_box', '_show', '_x_color', '_y_color', '_z_color']
def __init__(self):
self._x_color = Color('tomato')
self._y_color = Color('seagreen')
self._z_color = Color('mediumblue')
self._box = False
self._show = True
def __repr__(self):
txt = ['Axes configuration']
parm = {
'X Color': 'x_color',
'Y Color': 'y_color',
'Z Color': 'z_color',
'Use Box': 'box',
'Show': 'show',
}
for name, attr in parm.items():
setting = getattr(self, attr)
txt.append(f' {name:<21}: {setting}')
return '\n'.join(txt)
@property
def x_color(self) -> Color: # numpydoc ignore=RT01
"""Return or set x-axis color.
Examples
--------
Get the default x-axis color
>>> import pyvista as pv
>>> pv.global_theme.axes.x_color
Color(name='tomato', hex='#ff6347ff', opacity=255)
Change the default color.
>>> pv.global_theme.axes.x_color = 'red'
"""
return self._x_color
@x_color.setter
def x_color(self, color: ColorLike):
self._x_color = Color(color)
@property
def y_color(self) -> Color: # numpydoc ignore=RT01
"""Return or set y-axis color.
Examples
--------
Get the default y-axis color
>>> import pyvista as pv
>>> pv.global_theme.axes.y_color
Color(name='seagreen', hex='#2e8b57ff', opacity=255)
Change the default color.
>>> pv.global_theme.axes.y_color = 'green'
"""
return self._y_color
@y_color.setter
def y_color(self, color: ColorLike):
self._y_color = Color(color)
@property
def z_color(self) -> Color: # numpydoc ignore=RT01
"""Return or set z-axis color.
Examples
--------
Get the default z-axis color
>>> import pyvista as pv
>>> pv.global_theme.axes.z_color
Color(name='blue', hex='#0000ffff', opacity=255)
Change the default color.
>>> pv.global_theme.axes.z_color = 'purple'
"""
return self._z_color
@z_color.setter
def z_color(self, color: ColorLike):
self._z_color = Color(color)
@property
def box(self) -> bool: # numpydoc ignore=RT01
"""Use a box axes orientation widget.
If ``True``, Use the :func:`axes orientation box <pyvista.create_axes_orientation_box>`
instead of the :class:`pyvista.AxesActor` as the orientation widget for plots.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.axes.box = True
"""
return self._box
@box.setter
def box(self, box: bool):
self._box = bool(box)
@property
def show(self) -> bool: # numpydoc ignore=RT01
"""Show or hide the axes actor.
Examples
--------
Hide the axes by default.
>>> import pyvista as pv
>>> pv.global_theme.axes.show = False
"""
return self._show
@show.setter
def show(self, show: bool):
self._show = bool(show)
class _Font(_ThemeConfig):
"""PyVista plotter font configuration.
Examples
--------
Set the default font family to 'arial'. Must be either
'arial', 'courier', or 'times'.
>>> import pyvista as pv
>>> pv.global_theme.font.family = 'arial'
Set the default font size to 20.
>>> pv.global_theme.font.size = 20
Set the default title size to 40
>>> pv.global_theme.font.title_size = 40
Set the default label size to 10
>>> pv.global_theme.font.label_size = 10
Set the default text color to 'grey'
>>> pv.global_theme.font.color = 'grey'
Set the string formatter used to format numerical data to '%.6e'
>>> pv.global_theme.font.fmt = '%.6e'
"""
__slots__ = ['_color', '_family', '_fmt', '_label_size', '_size', '_title_size']
def __init__(self):
self._family = 'arial'
self._size = 12
self._title_size = None
self._label_size = None
self._color = Color('white')
self._fmt = None
def __repr__(self):
txt = ['']
parm = {
'Family': 'family',
'Size': 'size',
'Title size': 'title_size',
'Label size': 'label_size',
'Color': 'color',
'Float format': 'fmt',
}
for name, attr in parm.items():
setting = getattr(self, attr)
txt.append(f' {name:<21}: {setting}')
return '\n'.join(txt)
@property
def family(self) -> str: # numpydoc ignore=RT01
"""Return or set the font family.
Must be one of the following:
* ``"arial"``
* ``"courier"``
* ``"times"``
Examples
--------
Set the default global font family to 'courier'.
>>> import pyvista as pv
>>> pv.global_theme.font.family = 'courier'
"""
return self._family
@family.setter
def family(self, family: str):
parse_font_family(family) # check valid font
self._family = family
@property
def size(self) -> int: # numpydoc ignore=RT01
"""Return or set the font size.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.font.size = 20
"""
return self._size
@size.setter
def size(self, size: int):
self._size = int(size)
@property
def title_size(self) -> int: # numpydoc ignore=RT01
"""Return or set the title size.
If ``None``, then VTK uses ``UnconstrainedFontSizeOn`` for titles.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.font.title_size = 20
"""
return self._title_size # type: ignore[return-value]
@title_size.setter
def title_size(self, title_size: int | None):
if title_size is None:
self._title_size = None
else:
self._title_size = int(title_size)
@property
def label_size(self) -> int: # numpydoc ignore=RT01
"""Return or set the label size.
If ``None``, then VTK uses ``UnconstrainedFontSizeOn`` for labels.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.font.label_size = 20
"""
return self._label_size # type: ignore[return-value]
@label_size.setter
def label_size(self, label_size: int | None):
if label_size is None:
self._label_size = None
else:
self._label_size = int(label_size)
@property
def color(self) -> Color: # numpydoc ignore=RT01
"""Return or set the font color.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.font.color = 'black'
"""
return self._color
@color.setter
def color(self, color: ColorLike):
self._color = Color(color)
@property
def fmt(self) -> str: # numpydoc ignore=RT01
"""Return or set the string formatter used to format numerical data.
Examples
--------
Set the string formatter used to format numerical data to '%.6e'.
>>> import pyvista as pv
>>> pv.global_theme.font.fmt = '%.6e'
"""
return self._fmt # type: ignore[return-value]
@fmt.setter
def fmt(self, fmt: str):
self._fmt = fmt
class _SliderStyleConfig(_ThemeConfig):
"""PyVista configuration for a single slider style."""
__slots__ = [
'_cap_length',
'_cap_opacity',
'_cap_width',
'_name',
'_slider_color',
'_slider_length',
'_slider_width',
'_tube_color',
'_tube_width',
]
def __init__(self):
"""Initialize the slider style configuration."""
self._name = None
self._slider_length = None
self._slider_width = None
self._slider_color = None
self._tube_width = None
self._tube_color = None
self._cap_opacity = None
self._cap_length = None
self._cap_width = None
@property
def name(self) -> str: # numpydoc ignore=RT01
"""Return the name of the slider style configuration."""
return self._name # type: ignore[return-value]
@name.setter
def name(self, name: str):
self._name = name
@property
def cap_width(self) -> float: # numpydoc ignore=RT01
"""Return or set the cap width.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.slider_styles.modern.cap_width = 0.02
"""
return self._cap_width # type: ignore[return-value]
@cap_width.setter
def cap_width(self, cap_width: float):
self._cap_width = float(cap_width)
@property
def cap_length(self) -> float: # numpydoc ignore=RT01
"""Return or set the cap length.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.slider_styles.modern.cap_length = 0.01
"""
return self._cap_length # type: ignore[return-value]
@cap_length.setter
def cap_length(self, cap_length: float):
self._cap_length = float(cap_length)
@property
def cap_opacity(self) -> float: # numpydoc ignore=RT01
"""Return or set the cap opacity.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.slider_styles.modern.cap_opacity = 1.0
"""
return self._cap_opacity # type: ignore[return-value]
@cap_opacity.setter
def cap_opacity(self, cap_opacity: float):
_check_range(cap_opacity, (0, 1), 'cap_opacity')
self._cap_opacity = float(cap_opacity)
@property
def tube_color(self) -> Color: # numpydoc ignore=RT01
"""Return or set the tube color.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.slider_styles.modern.tube_color = 'black'
"""
return self._tube_color # type: ignore[return-value]
@tube_color.setter
def tube_color(self, tube_color: ColorLike):
self._tube_color = Color(tube_color)
@property
def tube_width(self) -> float: # numpydoc ignore=RT01
"""Return or set the tube_width.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.slider_styles.modern.tube_width = 0.005
"""
return self._tube_width # type: ignore[return-value]
@tube_width.setter
def tube_width(self, tube_width: float):
self._tube_width = float(tube_width)
@property
def slider_color(self) -> Color: # numpydoc ignore=RT01
"""Return or set the slider color.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.slider_styles.modern.slider_color = 'grey'
"""
return self._slider_color # type: ignore[return-value]
@slider_color.setter
def slider_color(self, slider_color: ColorLike):
self._slider_color = Color(slider_color)
@property
def slider_width(self) -> float: # numpydoc ignore=RT01
"""Return or set the slider width.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.slider_styles.modern.slider_width = 0.04
"""
return self._slider_width # type: ignore[return-value]
@slider_width.setter
def slider_width(self, slider_width: float):
self._slider_width = float(slider_width)
@property
def slider_length(self) -> float: # numpydoc ignore=RT01
"""Return or set the slider_length.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.slider_styles.modern.slider_length = 0.02
"""
return self._slider_length # type: ignore[return-value]
@slider_length.setter
def slider_length(self, slider_length: float):
self._slider_length = float(slider_length)
def __repr__(self):
txt = ['']
parm = {
'Slider length': 'slider_length',
'Slider width': 'slider_width',
'Slider color': 'slider_color',
'Tube width': 'tube_width',
'Tube color': 'tube_color',
'Cap opacity': 'cap_opacity',
'Cap length': 'cap_length',
'Cap width': 'cap_width',
}
for name, attr in parm.items():
setting = getattr(self, attr)
txt.append(f' {name:<17}: {setting}')
return '\n'.join(txt)
class _SliderConfig(_ThemeConfig):
"""PyVista configuration encompassing all slider styles.
Examples
--------
Set the classic slider configuration.
>>> import pyvista as pv
>>> slider_styles = pv.global_theme.slider_styles
>>> slider_styles.classic.slider_length = 0.02
>>> slider_styles.classic.slider_width = 0.04
>>> slider_styles.classic.slider_color = (0.5, 0.5, 0.5)
>>> slider_styles.classic.tube_width = 0.005
>>> slider_styles.classic.tube_color = (1.0, 1.0, 1.0)
>>> slider_styles.classic.cap_opacity = 1
>>> slider_styles.classic.cap_length = 0.01
>>> slider_styles.classic.cap_width = 0.02
Set the modern slider configuration.
>>> slider_styles.modern.slider_length = 0.02
>>> slider_styles.modern.slider_width = 0.04
>>> slider_styles.modern.slider_color = (0.43, 0.44, 0.45)
>>> slider_styles.modern.tube_width = 0.04
>>> slider_styles.modern.tube_color = (0.69, 0.70, 0.709)
>>> slider_styles.modern.cap_opacity = 0
>>> slider_styles.modern.cap_length = 0.01
>>> slider_styles.modern.cap_width = 0.02
"""
__slots__ = ['_classic', '_modern']
def __init__(self):
"""Initialize the slider configuration."""
self._classic = _SliderStyleConfig()
self._classic.name = 'classic'
self._classic.slider_length = 0.02
self._classic.slider_width = 0.04
self._classic.slider_color = 'gray'
self._classic.tube_width = 0.005
self._classic.tube_color = 'white'
self._classic.cap_opacity = 1
self._classic.cap_length = 0.01
self._classic.cap_width = 0.02
self._modern = _SliderStyleConfig()
self._modern.name = 'modern'
self._modern.slider_length = 0.02
self._modern.slider_width = 0.04
self._modern.slider_color = (110, 113, 117)
self._modern.tube_width = 0.04
self._modern.tube_color = (178, 179, 181)
self._modern.cap_opacity = 0
self._modern.cap_length = 0.01
self._modern.cap_width = 0.02
@property
def classic(self) -> _SliderStyleConfig: # numpydoc ignore=RT01
"""Return the Classic slider configuration."""
return self._classic
@classic.setter
def classic(self, config: _SliderStyleConfig):
if not isinstance(config, _SliderStyleConfig):
msg = 'Configuration type must be `_SliderStyleConfig`' # type: ignore[unreachable]
raise TypeError(msg)
self._classic = config
@property
def modern(self) -> _SliderStyleConfig: # numpydoc ignore=RT01
"""Return the Modern slider configuration."""
return self._modern
@modern.setter
def modern(self, config: _SliderStyleConfig):
if not isinstance(config, _SliderStyleConfig):
msg = 'Configuration type must be `_SliderStyleConfig`' # type: ignore[unreachable]
raise TypeError(msg)
self._modern = config
def __repr__(self):
txt = ['']
parm = {
'Classic': 'classic',
'Modern': 'modern',
}
for name, attr in parm.items():
setting = getattr(self, attr)
txt.append(f' {name:<21}: {setting}')
return '\n'.join(txt)
def __iter__(self):
for style in [self._classic, self._modern]:
yield style.name
class _TrameConfig(_ThemeConfig):
"""PyVista Trame configuration.
Examples
--------
Set global trame view parameters.
>>> import pyvista as pv
>>> pv.global_theme.trame.interactive_ratio = 2
>>> pv.global_theme.trame.still_ratio = 2
"""
__slots__ = [
'_default_mode',
'_interactive_ratio',
'_jupyter_extension_available',
'_jupyter_extension_enabled',
'_jupyter_server_name',
'_jupyter_server_port',
'_server_proxy_enabled',
'_server_proxy_prefix',
'_still_ratio',
]
def __init__(self):
self._interactive_ratio = 1
self._still_ratio = 1
self._jupyter_server_name = 'pyvista-jupyter'
self._jupyter_server_port = 0
self._server_proxy_enabled = 'PYVISTA_TRAME_SERVER_PROXY_PREFIX' in os.environ
# default for ``jupyter-server-proxy``
service = os.environ.get('JUPYTERHUB_SERVICE_PREFIX', '')
prefix = os.environ.get('PYVISTA_TRAME_SERVER_PROXY_PREFIX', '/proxy/')
if service and not prefix.startswith('http'): # pragma: no cover
self._server_proxy_prefix = str(Path(service) / prefix.lstrip('/')).rstrip('/') + '/'
self._server_proxy_enabled = True
else:
self._server_proxy_prefix = prefix
self._jupyter_extension_available = 'TRAME_JUPYTER_WWW' in os.environ
self._jupyter_extension_enabled = (
self._jupyter_extension_available and not self._server_proxy_enabled
)
# if set, jupyter_mode overwrites defaults
jupyter_mode = os.environ.get('PYVISTA_TRAME_JUPYTER_MODE')
if jupyter_mode == 'extension' and self._jupyter_extension_available: # pragma: no cover
self._server_proxy_enabled = False
self._jupyter_extension_enabled = True
elif jupyter_mode == 'proxy' and self._server_proxy_enabled: # pragma: no cover
self._jupyter_extension_enabled = False
elif jupyter_mode == 'native': # pragma: no cover
self._jupyter_extension_enabled = False
self._server_proxy_enabled = False
self._default_mode = 'trame'
@property
def interactive_ratio(self) -> float: # numpydoc ignore=RT01
"""Return or set the interactive ratio for PyVista Trame views.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.trame.interactive_ratio = 2
"""
return self._interactive_ratio
@interactive_ratio.setter
def interactive_ratio(self, interactive_ratio: float):
self._interactive_ratio = interactive_ratio # type: ignore[assignment]
@property
def still_ratio(self) -> float: # numpydoc ignore=RT01
"""Return or set the still ratio for PyVista Trame views.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.trame.still_ratio = 2
"""
return self._still_ratio
@still_ratio.setter
def still_ratio(self, still_ratio: float):
self._still_ratio = still_ratio # type: ignore[assignment]
@property
def jupyter_server_name(self): # numpydoc ignore=RT01
"""Return or set the trame server name PyVista uses in Jupyter.
This defaults to ``'pyvista-jupyter'``.
This must be set before running :func:`pyvista.set_jupyter_backend`
to ensure a server of this name is launched.
Most users should not need to modify this.
"""
return self._jupyter_server_name
@jupyter_server_name.setter
def jupyter_server_name(self, name: str):
self._jupyter_server_name = name
@property
def jupyter_server_port(self) -> int: # numpydoc ignore=RT01
"""Return or set the port for the Trame Jupyter server."""
return self._jupyter_server_port
@jupyter_server_port.setter
def jupyter_server_port(self, port: int):
self._jupyter_server_port = port
@property
def server_proxy_enabled(self) -> bool: # numpydoc ignore=RT01
"""Return or set if use of relative URLs is enabled for the Jupyter interface."""
return self._server_proxy_enabled
@server_proxy_enabled.setter
def server_proxy_enabled(self, enabled: bool):
if enabled and self.jupyter_extension_enabled:
warnings.warn('Enabling server_proxy will disable jupyter_extension')
self._jupyter_extension_enabled = False
self._server_proxy_enabled = bool(enabled)
@property
def server_proxy_prefix(self): # numpydoc ignore=RT01
"""Return or set URL prefix when using relative URLs with the Jupyter interface."""
return self._server_proxy_prefix
@server_proxy_prefix.setter
def server_proxy_prefix(self, prefix: str):
self._server_proxy_prefix = prefix
@property
def jupyter_extension_available(self) -> bool: # numpydoc ignore=RT01
"""Return whether the trame_jupyter_extension is detected."""
return self._jupyter_extension_available
@jupyter_extension_available.setter
def jupyter_extension_available(self, _available: bool):
warnings.warn(
'The jupyter_extension_available flag is read only and is automatically detected.',
)
@property
def jupyter_extension_enabled(self) -> bool: # numpydoc ignore=RT01
"""Return or set whether to use the trame_jupyter_extension to communicate with clients."""
return self._jupyter_extension_enabled
@jupyter_extension_enabled.setter
def jupyter_extension_enabled(self, enabled: bool):
if enabled and not self.jupyter_extension_available:
msg = 'The trame_jupyter_extension is not available'
raise ValueError(msg)
if enabled and self.server_proxy_enabled:
warnings.warn('Enabling jupyter_extension will disable server_proxy')
self._server_proxy_enabled = False
self._jupyter_extension_enabled = bool(enabled)
@property
def default_mode(self): # numpydoc ignore=RT01
"""Return or set the default mode of the Trame backend.
* ``'trame'``: Uses a view that can switch between client and server
rendering modes.
* ``'server'``: Uses a view that is purely server rendering.
* ``'client'``: Uses a view that is purely client rendering (generally
safe without a virtual frame buffer)
"""
return self._default_mode
@default_mode.setter
def default_mode(self, mode: str):
self._default_mode = mode
class _CameraConfig(_ThemeConfig):
"""PyVista camera configuration.
Examples
--------
Set global camera parameters.
>>> import pyvista as pv
>>> pv.global_theme.camera.position = [1.0, 1.0, 1.0]
>>> pv.global_theme.camera.viewup = [0.0, 0.0, 1.0]
"""
__slots__ = [
'_parallel_projection',
'_parallel_scale',
'_position',
'_viewup',
]
def __init__(self):
self._position = [1.0, 1.0, 1.0]
self._viewup = [0.0, 0.0, 1.0]
self._parallel_projection = False
self._parallel_scale = 1.0
@property
def position(self) -> VectorLike[float]: # numpydoc ignore=RT01
"""Return or set the camera position.
Examples
--------
Set camera position.
>>> import pyvista as pv
>>> pv.global_theme.camera.position = [1.0, 1.0, 1.0]
"""
return self._position
@position.setter
def position(self, position: VectorLike[float]):
self._position = position # type: ignore[assignment]
@property
def viewup(self) -> VectorLike[float]: # numpydoc ignore=RT01
"""Return or set the camera viewup.
Examples
--------
Set camera viewup.
>>> import pyvista as pv
>>> pv.global_theme.camera.viewup = [0.0, 0.0, 1.0]
"""
return self._viewup
@viewup.setter
def viewup(self, viewup: VectorLike[float]):
self._viewup = viewup # type: ignore[assignment]
@property
def parallel_projection(self) -> bool: # numpydoc ignore=RT01
"""Return or set parallel projection mode.
Examples
--------
Enable parallel projection.
>>> import pyvista as pv
>>> pv.global_theme.camera.parallel_projection = True
"""
return self._parallel_projection
@parallel_projection.setter
def parallel_projection(self, value: bool) -> None:
self._parallel_projection = value
@property
def parallel_scale(self) -> bool: # numpydoc ignore=RT01
"""Return or set parallel scale.
Examples
--------
Set parallel scale.
>>> import pyvista as pv
>>> pv.global_theme.camera.parallel_scale = 2.0
"""
return self._parallel_scale # type: ignore[return-value]
@parallel_scale.setter
def parallel_scale(self, value: bool) -> None:
self._parallel_scale = value
class Theme(_ThemeConfig):
"""Base VTK theme.
Examples
--------
Change the global default background color to white.
>>> import pyvista as pv
>>> pv.global_theme.color = 'white'
Show edges by default.
>>> pv.global_theme.show_edges = True
Create a new theme from the default theme and apply it globally.
>>> from pyvista.plotting.themes import DocumentTheme
>>> my_theme = DocumentTheme()
>>> my_theme.color = 'red'
>>> my_theme.background = 'white'
>>> pv.global_theme.load_theme(my_theme)
"""
__slots__ = [
'_above_range_color',
'_allow_empty_mesh',
'_anti_aliasing',
'_auto_close',
'_axes',
'_background',
'_before_close_callback',
'_before_close_callback',
'_below_range_color',
'_camera',
'_cmap',
'_color',
'_color_cycler',
'_colorbar_horizontal',
'_colorbar_orientation',
'_colorbar_vertical',
'_depth_peeling',
'_edge_color',
'_edge_opacity',
'_enable_camera_orientation_widget',
'_floor_color',
'_font',
'_full_screen',
'_hidden_line_removal',
'_image_scale',
'_interactive',
'_interpolate_before_map',
'_jupyter_backend',
'_lighting',
'_lighting_params',
'_line_width',
'_logo_file',
'_multi_rendering_splitting_position',
'_multi_samples',
'_name',
'_nan_color',
'_notebook',
'_opacity',
'_outline_color',
'_point_size',
'_render_lines_as_tubes',
'_render_points_as_spheres',
'_resample_environment_texture',
'_return_cpos',
'_sharp_edges_feature_angle',
'_show_edges',
'_show_scalar_bar',
'_show_vertices',
'_silhouette',
'_slider_styles',
'_smooth_shading',
'_split_sharp_edges',
'_title',
'_trame',
'_transparent_background',
'_volume_mapper',
'_window_size',
]
def __init__(self):
"""Initialize the theme."""
self._name = 'default'
self._background = Color([0.3, 0.3, 0.3])
self._full_screen = False
self._camera = _CameraConfig()
self._notebook = None
self._window_size = [1024, 768]
self._image_scale = 1
self._font = _Font()
self._cmap: ColormapOptions = 'viridis'
self._color = Color('white')
self._color_cycler = None
self._nan_color = Color('darkgray')
self._above_range_color = Color('grey')
self._below_range_color = Color('grey')
self._edge_color = Color('black')
self._line_width = 1.0
self._point_size = 5.0
self._outline_color = Color('white')
self._floor_color = Color('gray')
self._colorbar_orientation = 'horizontal'
self._colorbar_horizontal = _ColorbarConfig()
self._colorbar_horizontal.width = 0.6
self._colorbar_horizontal.height = 0.08
self._colorbar_horizontal.position_x = 0.35
self._colorbar_horizontal.position_y = 0.05
self._colorbar_vertical = _ColorbarConfig()
self._colorbar_vertical.width = 0.08
self._colorbar_vertical.height = 0.45
self._colorbar_vertical.position_x = 0.9
self._colorbar_vertical.position_y = 0.02
self._show_scalar_bar = True
self._show_edges = False
self._show_vertices = False
self._lighting = True
self._interactive = False
self._render_points_as_spheres = False
self._render_lines_as_tubes = False
self._transparent_background = False
self._title = 'PyVista'
self._axes = _AxesConfig()
self._split_sharp_edges = False
self._sharp_edges_feature_angle = 30.0
self._before_close_callback = None
self._allow_empty_mesh = False
# Grab system flag for anti-aliasing
# Use a default value of 8 multi-samples as this is default for VTK
try:
self._multi_samples = int(os.environ.get('PYVISTA_MULTI_SAMPLES', '8'))
except ValueError: # pragma: no cover
self._multi_samples = 8
# Grab system flag for auto-closing
self._auto_close = os.environ.get('PYVISTA_AUTO_CLOSE', '').lower() != 'false'
self._jupyter_backend: JupyterBackendOptions = (
os.environ.get('PYVISTA_JUPYTER_BACKEND', 'trame') # type: ignore[assignment]
)
self._trame = _TrameConfig()
self._multi_rendering_splitting_position = None
self._volume_mapper = 'smart'
self._smooth_shading = False
self._depth_peeling = _DepthPeelingConfig()
self._silhouette = _SilhouetteConfig()
self._slider_styles = _SliderConfig()
self._return_cpos = True
self._hidden_line_removal = False
self._anti_aliasing = 'msaa'
self._enable_camera_orientation_widget = False
self._lighting_params = _LightingConfig()
self._interpolate_before_map = True
self._opacity = 1.0
self._edge_opacity = 1.0
self._logo_file = None
self._resample_environment_texture: bool | float = False
@property
def hidden_line_removal(self) -> bool: # numpydoc ignore=RT01
"""Return or set hidden line removal.
Wireframe geometry will be drawn using hidden line removal if
the rendering engine supports it.
See Also
--------
pyvista.Plotter.enable_hidden_line_removal
Examples
--------
Enable hidden line removal.
>>> import pyvista as pv
>>> pv.global_theme.hidden_line_removal = True
>>> pv.global_theme.hidden_line_removal
True
"""
return self._hidden_line_removal
@hidden_line_removal.setter
def hidden_line_removal(self, value: bool):
self._hidden_line_removal = value
@property
def interpolate_before_map(self) -> bool: # numpydoc ignore=RT01
"""Return or set whether to interpolate colors before mapping.
If the ``interpolate_before_map`` is turned off, the color
mapping occurs at polygon points and colors are interpolated,
which is generally less accurate whereas if the
``interpolate_before_map`` is on (the default), then the scalars
will be interpolated across the topology of the dataset which is
more accurate.
See also :ref:`interpolate_before_map_example`.
Examples
--------
Enable hidden line removal.
>>> import pyvista as pv
Load a cylinder which has cells with a wide spread
>>> cyl = pv.Cylinder(direction=(0, 0, 1), height=2).elevation()
Common display argument to make sure all else is constant
>>> dargs = dict(scalars='Elevation', cmap='rainbow', show_edges=True)
>>> p = pv.Plotter(shape=(1, 2))
>>> _ = p.add_mesh(
... cyl,
... interpolate_before_map=False,
... scalar_bar_args={'title': 'Elevation - interpolated'},
... **dargs,
... )
>>> p.subplot(0, 1)
>>> _ = p.add_mesh(
... cyl,
... interpolate_before_map=True,
... scalar_bar_args={'title': 'Elevation - interpolated'},
... **dargs,
... )
>>> p.link_views()
>>> p.camera_position = [
... (-1.67, -5.10, 2.06),
... (0.0, 0.0, 0.0),
... (0.00, 0.37, 0.93),
... ]
>>> p.show() # doctest: +SKIP
"""
return self._interpolate_before_map
@interpolate_before_map.setter
def interpolate_before_map(self, value: bool):
self._interpolate_before_map = value
@property
def opacity(self) -> float: # numpydoc ignore=RT01
"""Return or set the opacity.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.opacity = 0.5
"""
return self._opacity
@opacity.setter
def opacity(self, opacity: float):
_check_range(opacity, (0, 1), 'opacity')
self._opacity = float(opacity)
@property
def edge_opacity(self) -> float: # numpydoc ignore=RT01
"""Return or set the edges opacity.
.. note::
`edge_opacity` uses ``SetEdgeOpacity`` as the underlying method which
requires VTK version 9.3 or higher. If ``SetEdgeOpacity`` is not
available, `edge_opacity` is set to 1.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.edge_opacity = 0.5
"""
return self._edge_opacity
@edge_opacity.setter
def edge_opacity(self, edge_opacity: float):
_check_range(edge_opacity, (0, 1), 'edge_opacity')
self._edge_opacity = float(edge_opacity)
@property
def above_range_color(self) -> Color: # numpydoc ignore=RT01
"""Return or set the default above range color.
Examples
--------
Set the above range color to red.
>>> import pyvista as pv
>>> pv.global_theme.above_range_color = 'r'
>>> pv.global_theme.above_range_color
Color(name='red', hex='#ff0000ff', opacity=255)
"""
return self._above_range_color
@above_range_color.setter
def above_range_color(self, value: ColorLike):
self._above_range_color = Color(value)
@property
def below_range_color(self) -> Color: # numpydoc ignore=RT01
"""Return or set the default below range color.
Examples
--------
Set the below range color to blue.
>>> import pyvista as pv
>>> pv.global_theme.below_range_color = 'b'
>>> pv.global_theme.below_range_color
Color(name='blue', hex='#0000ffff', opacity=255)
"""
return self._below_range_color
@below_range_color.setter
def below_range_color(self, value: ColorLike):
self._below_range_color = Color(value)
@property
def return_cpos(self) -> bool: # numpydoc ignore=RT01
"""Return or set the default behavior of returning the camera position.
Examples
--------
Disable returning camera position by ``show`` and ``plot`` methods.
>>> import pyvista as pv
>>> pv.global_theme.return_cpos = False
"""
return self._return_cpos
@return_cpos.setter
def return_cpos(self, value: bool):
self._return_cpos = value
@property
def background(self) -> Color: # numpydoc ignore=RT01
"""Return or set the default background color of pyvista plots.
Examples
--------
Set the default global background of all plots to white.
>>> import pyvista as pv
>>> pv.global_theme.background = 'white'
"""
return self._background
@background.setter
def background(self, new_background: ColorLike) -> None:
self._background = Color(new_background)
@property
def jupyter_backend(
self,
) -> JupyterBackendOptions: # numpydoc ignore=RT01
"""Return or set the jupyter notebook plotting backend.
Jupyter backend to use when plotting. Must be one of the
following:
* ``'static'`` : Display a single static image within the
Jupyterlab environment. Still requires that a virtual
framebuffer be set up when displaying on a headless server,
but does not require any additional modules to be installed.
* ``'client'`` : Export/serialize the scene graph to be rendered
with VTK.js client-side through ``trame``. Requires ``trame``
and ``jupyter-server-proxy`` to be installed.
* ``'server'``: Render remotely and stream the resulting VTK
images back to the client using ``trame``. This replaces the
``'ipyvtklink'`` backend with better performance.
Supports the most VTK features, but suffers from minor lag due
to remote rendering. Requires that a virtual framebuffer be set
up when displaying on a headless server. Must have at least ``trame``
and ``jupyter-server-proxy`` installed for cloud/remote Jupyter
instances. This mode is also aliased by ``'trame'``.
* ``'trame'``: The full Trame-based backend that combines both
``'server'`` and ``'client'`` into one backend. This requires a
virtual frame buffer.
* ``'html'``: The ``'client'`` backend, but able to be embedded.
* ``'none'`` : Do not display any plots within jupyterlab,
instead display using dedicated VTK render windows. This
will generate nothing on headless servers even with a
virtual framebuffer.
Examples
--------
Just show static images.
>>> pv.set_jupyter_backend('static') # doctest:+SKIP
Disable all plotting within JupyterLab and display using a
standard desktop VTK render window.
>>> pv.set_jupyter_backend(None) # doctest:+SKIP
"""
return self._jupyter_backend
@jupyter_backend.setter
def jupyter_backend(self, backend: str):
from pyvista.jupyter import _validate_jupyter_backend # noqa: PLC0415
self._jupyter_backend = _validate_jupyter_backend(backend)
@property
def trame(self) -> _TrameConfig: # numpydoc ignore=RT01
"""Return or set the default trame parameters."""
return self._trame
@trame.setter
def trame(self, config: _TrameConfig):
if not isinstance(config, _TrameConfig):
msg = 'Configuration type must be `_TrameConfig`.' # type: ignore[unreachable]
raise TypeError(msg)
self._trame = config
@property
def auto_close(self) -> bool: # numpydoc ignore=RT01
"""Automatically close the figures when finished plotting.
.. DANGER::
Set to ``False`` with extreme caution.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.auto_close = False
"""
return self._auto_close
@auto_close.setter
def auto_close(self, value: bool):
self._auto_close = value
@property
def full_screen(self) -> bool: # numpydoc ignore=RT01
"""Return if figures are shown in full screen.
Examples
--------
Set windows to be full screen by default.
>>> import pyvista as pv
>>> pv.global_theme.full_screen = True
"""
return self._full_screen
@full_screen.setter
def full_screen(self, value: bool):
self._full_screen = value
@property
def enable_camera_orientation_widget(self) -> bool: # numpydoc ignore=RT01
"""Enable the camera orientation widget in all plotters.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.enable_camera_orientation_widget = True
>>> pv.global_theme.enable_camera_orientation_widget
True
"""
return self._enable_camera_orientation_widget
@enable_camera_orientation_widget.setter
def enable_camera_orientation_widget(self, value: bool):
self._enable_camera_orientation_widget = value
@property
def camera(self): # numpydoc ignore=RT01
"""Return or set the default camera position.
Examples
--------
Set both the position and viewup of the camera.
>>> import pyvista as pv
>>> pv.global_theme.camera.position = [1.0, 1.0, 1.0]
>>> pv.global_theme.camera.viewup = [0.0, 0.0, 1.0]
"""
return self._camera
@camera.setter
def camera(self, camera):
if isinstance(camera, dict):
self._camera = _CameraConfig.from_dict(camera)
elif isinstance(camera, _CameraConfig):
self._camera = camera
else:
msg = f'camera value must either be a `dict` or a `_CameraConfig`, got {type(camera)}'
raise TypeError(msg)
@property
def notebook(self) -> bool | None: # numpydoc ignore=RT01
"""Return or set the state of notebook plotting.
Setting this to ``True`` always enables notebook plotting,
while setting it to ``False`` disables plotting even when
plotting within a jupyter notebook and plots externally.
Examples
--------
Disable all jupyter notebook plotting.
>>> import pyvista as pv
>>> pv.global_theme.notebook = False
"""
return self._notebook
@notebook.setter
def notebook(self, value: bool | None):
self._notebook = value
@property
def window_size(self) -> list[int]: # numpydoc ignore=RT01
"""Return or set the default render window size.
Examples
--------
Set window size to ``[400, 400]``.
>>> import pyvista as pv
>>> pv.global_theme.window_size = [400, 400]
"""
return self._window_size
@window_size.setter
def window_size(self, window_size: list[int]):
if len(window_size) != 2:
msg = 'Expected a length 2 iterable for ``window_size``.'
raise ValueError(msg)
# ensure positive size
if window_size[0] < 0 or window_size[1] < 0:
msg = 'Window size must be a positive value.'
raise ValueError(msg)
self._window_size = window_size
@property
def image_scale(self) -> int: # numpydoc ignore=RT01
"""Return or set the default image scale factor."""
return self._image_scale
@image_scale.setter
def image_scale(self, value: int):
value = int(value)
if value < 1:
msg = 'Scale factor must be a positive integer.'
raise ValueError(msg)
self._image_scale = int(value)
@property
def font(self) -> _Font: # numpydoc ignore=RT01
"""Return or set the default font size, family, and/or color.
Examples
--------
Set the default font family to 'arial'. Must be either
'arial', 'courier', or 'times'.
>>> import pyvista as pv
>>> pv.global_theme.font.family = 'arial'
Set the default font size to 20.
>>> pv.global_theme.font.size = 20
Set the default title size to 40.
>>> pv.global_theme.font.title_size = 40
Set the default label size to 10.
>>> pv.global_theme.font.label_size = 10
Set the default text color to 'grey'.
>>> pv.global_theme.font.color = 'grey'
String formatter used to format numerical data to '%.6e'.
>>> pv.global_theme.font.fmt = '%.6e'
"""
return self._font
@font.setter
def font(self, config: _Font):
if not isinstance(config, _Font):
msg = 'Configuration type must be `_Font`.' # type: ignore[unreachable]
raise TypeError(msg)
self._font = config
@property
def cmap(self) -> ColormapOptions: # numpydoc ignore=RT01
"""Return or set the default colormap of pyvista.
See :ref:`named_colormaps` for supported colormaps.
Only applicable when displaying ``scalars``.
You can also specify a list of colors to override an existing
colormap with a custom one. For example, to create a three
color colormap you might specify ``['green', 'red', 'blue']``
Examples
--------
Set the default global colormap to 'jet'.
>>> import pyvista as pv
>>> pv.global_theme.cmap = 'jet'
"""
return self._cmap
@cmap.setter
def cmap(self, cmap: ColormapOptions):
get_cmap_safe(cmap) # for validation
self._cmap = cmap
@property
def color(self) -> Color: # numpydoc ignore=RT01
"""Return or set the default color of meshes in pyvista.
Used for meshes without ``scalars``.
When setting, the value must be either a string, rgb list,
or hex color string. For example:
* ``color='white'``
* ``color='w'``
* ``color=[1.0, 1.0, 1.0]``
* ``color='#FFFFFF'``
Examples
--------
Set the default mesh color to 'red'.
>>> import pyvista as pv
>>> pv.global_theme.color = 'red'
"""
return self._color
@color.setter
def color(self, color: ColorLike):
self._color = Color(color)
@property
def color_cycler(self): # numpydoc ignore=RT01
"""Return or set the default color cycler used to color meshes.
This color cycler is iterated over by each renderer to sequentially
color datasets when displaying them through ``add_mesh``.
When setting, the value must be either a list of color-like objects,
or a cycler of color-like objects. If the value passed is a single
string, it must be one of:
* ``'default'`` - Use the default color cycler (matches matplotlib's default)
* ``'matplotlib`` - Dynamically get matplotlib's current theme's color cycler.
* ``'all'`` - Cycle through all available colors in
``pyvista.plotting.colors.hexcolors``
Setting to ``None`` will disable the use of the color cycler.
Examples
--------
Set the default color cycler to iterate through red, green, and blue.
>>> import pyvista as pv
>>> pv.global_theme.color_cycler = ['red', 'green', 'blue']
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(pv.Cone(center=(0, 0, 0))) # red
>>> _ = pl.add_mesh(pv.Cube(center=(1, 0, 0))) # green
>>> _ = pl.add_mesh(pv.Sphere(center=(1, 1, 0))) # blue
>>> _ = pl.add_mesh(pv.Cylinder(center=(0, 1, 0))) # red again
>>> pl.show() # doctest: +SKIP
"""
return self._color_cycler
@color_cycler.setter
def color_cycler(self, color_cycler):
self._color_cycler = get_cycler(color_cycler)
@property
def nan_color(self) -> Color: # numpydoc ignore=RT01
"""Return or set the default NaN color.
This color is used to plot all NaN values.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.nan_color = 'darkgray'
"""
return self._nan_color
@nan_color.setter
def nan_color(self, nan_color: ColorLike):
self._nan_color = Color(nan_color)
@property
def edge_color(self) -> Color: # numpydoc ignore=RT01
"""Return or set the default edge color.
Examples
--------
Set the global edge color to 'blue'.
>>> import pyvista as pv
>>> pv.global_theme.edge_color = 'blue'
"""
return self._edge_color
@edge_color.setter
def edge_color(self, edge_color: ColorLike):
self._edge_color = Color(edge_color)
@property
def line_width(self) -> float: # numpydoc ignore=RT01
"""Return or set the default line width.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.line_width = 2.0
"""
return self._line_width
@line_width.setter
def line_width(self, line_width: float):
self._line_width = float(line_width)
@property
def point_size(self) -> float: # numpydoc ignore=RT01
"""Return or set the default point size.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.line_width = 10.0
"""
return self._point_size
@point_size.setter
def point_size(self, point_size: float):
self._point_size = float(point_size)
@property
def outline_color(self) -> Color: # numpydoc ignore=RT01
"""Return or set the default outline color.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.outline_color = 'white'
"""
return self._outline_color
@outline_color.setter
def outline_color(self, outline_color: ColorLike):
self._outline_color = Color(outline_color)
@property
def floor_color(self) -> Color: # numpydoc ignore=RT01
"""Return or set the default floor color.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.floor_color = 'black'
"""
return self._floor_color
@floor_color.setter
def floor_color(self, floor_color: ColorLike):
self._floor_color = Color(floor_color)
@property
def colorbar_orientation(self) -> str: # numpydoc ignore=RT01
"""Return or set the default colorbar orientation.
Must be either ``'vertical'`` or ``'horizontal'``.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.colorbar_orientation = 'horizontal'
"""
return self._colorbar_orientation
@colorbar_orientation.setter
def colorbar_orientation(self, colorbar_orientation: str):
if colorbar_orientation not in ['vertical', 'horizontal']:
msg = 'Colorbar orientation must be either "vertical" or "horizontal"'
raise ValueError(msg)
self._colorbar_orientation = colorbar_orientation
@property
def colorbar_horizontal(self) -> _ColorbarConfig: # numpydoc ignore=RT01
"""Return or set the default parameters of a horizontal colorbar.
Examples
--------
Set the default horizontal colorbar width to 0.6.
>>> import pyvista as pv
>>> pv.global_theme.colorbar_horizontal.width = 0.6
Set the default horizontal colorbar height to 0.2.
>>> pv.global_theme.colorbar_horizontal.height = 0.2
"""
return self._colorbar_horizontal
@colorbar_horizontal.setter
def colorbar_horizontal(self, config: _ColorbarConfig):
if not isinstance(config, _ColorbarConfig):
msg = 'Configuration type must be `_ColorbarConfig`.' # type: ignore[unreachable]
raise TypeError(msg)
self._colorbar_horizontal = config
@property
def colorbar_vertical(self) -> _ColorbarConfig: # numpydoc ignore=RT01
"""Return or set the default parameters of a vertical colorbar.
Examples
--------
Set the default colorbar width to 0.45.
>>> import pyvista as pv
>>> pv.global_theme.colorbar_vertical.width = 0.45
Set the default colorbar height to 0.8.
>>> import pyvista as pv
>>> pv.global_theme.colorbar_vertical.height = 0.8
"""
return self._colorbar_vertical
@colorbar_vertical.setter
def colorbar_vertical(self, config: _ColorbarConfig):
if not isinstance(config, _ColorbarConfig):
msg = 'Configuration type must be `_ColorbarConfig`.' # type: ignore[unreachable]
raise TypeError(msg)
self._colorbar_vertical = config
@property
def show_scalar_bar(self) -> bool: # numpydoc ignore=RT01
"""Return or set the default color bar visibility.
Examples
--------
Show the scalar bar by default when scalars are available.
>>> import pyvista as pv
>>> pv.global_theme.show_scalar_bar = True
"""
return self._show_scalar_bar
@show_scalar_bar.setter
def show_scalar_bar(self, show_scalar_bar: bool):
self._show_scalar_bar = bool(show_scalar_bar)
@property
def show_edges(self) -> bool: # numpydoc ignore=RT01
"""Return or set the default edge visibility.
Examples
--------
Show edges globally by default.
>>> import pyvista as pv
>>> pv.global_theme.show_edges = True
"""
return self._show_edges
@show_edges.setter
def show_edges(self, show_edges: bool):
self._show_edges = bool(show_edges)
@property
def show_vertices(self) -> bool: # numpydoc ignore=RT01
"""Return or set the default vertex visibility.
Examples
--------
Show vertices globally by default.
>>> import pyvista as pv
>>> pv.global_theme.show_vertices = True
"""
return self._show_vertices
@show_vertices.setter
def show_vertices(self, show_vertices: bool):
self._show_vertices = bool(show_vertices)
@property
def lighting(self) -> bool: # numpydoc ignore=RT01
"""Return or set the default ``lighting``.
Examples
--------
Disable lighting globally.
>>> import pyvista as pv
>>> pv.global_theme.lighting = False
"""
return self._lighting
@lighting.setter
def lighting(self, lighting: bool):
self._lighting = lighting
@property
def interactive(self) -> bool: # numpydoc ignore=RT01
"""Return or set the default ``interactive`` parameter.
Examples
--------
Make all plots non-interactive globally.
>>> import pyvista as pv
>>> pv.global_theme.interactive = False
"""
return self._interactive
@interactive.setter
def interactive(self, interactive: bool):
self._interactive = bool(interactive)
@property
def render_points_as_spheres(self) -> bool: # numpydoc ignore=RT01
"""Return or set the default ``render_points_as_spheres`` parameter.
Examples
--------
Render points as spheres by default globally.
>>> import pyvista as pv
>>> pv.global_theme.render_points_as_spheres = True
"""
return self._render_points_as_spheres
@render_points_as_spheres.setter
def render_points_as_spheres(self, render_points_as_spheres: bool):
self._render_points_as_spheres = bool(render_points_as_spheres)
@property
def render_lines_as_tubes(self) -> bool: # numpydoc ignore=RT01
"""Return or set the default ``render_lines_as_tubes`` parameter.
Examples
--------
Render points as spheres by default globally.
>>> import pyvista as pv
>>> pv.global_theme.render_lines_as_tubes = True
"""
return self._render_lines_as_tubes
@render_lines_as_tubes.setter
def render_lines_as_tubes(self, render_lines_as_tubes: bool):
self._render_lines_as_tubes = bool(render_lines_as_tubes)
@property
def transparent_background(self) -> bool: # numpydoc ignore=RT01
"""Return or set the default ``transparent_background`` parameter.
Examples
--------
Set transparent_background globally to ``True``.
>>> import pyvista as pv
>>> pv.global_theme.transparent_background = True
"""
return self._transparent_background
@transparent_background.setter
def transparent_background(self, transparent_background: bool):
self._transparent_background = transparent_background
@property
def title(self) -> str: # numpydoc ignore=RT01
"""Return or set the default ``title`` parameter.
This is the VTK render window title.
Examples
--------
Set title globally to 'plot'.
>>> import pyvista as pv
>>> pv.global_theme.title = 'plot'
"""
return self._title
@title.setter
def title(self, title: str):
self._title = title
@property
def anti_aliasing(self) -> str | None: # numpydoc ignore=RT01
"""Enable or disable anti-aliasing.
Should be either ``"ssaa"``, ``"msaa"``, ``"fxaa"``, or ``None``.
Examples
--------
Use super-sampling anti-aliasing in the global theme.
>>> import pyvista as pv
>>> pv.global_theme.anti_aliasing = 'ssaa'
>>> pv.global_theme.anti_aliasing
'ssaa'
Disable anti-aliasing in the global theme.
>>> import pyvista as pv
>>> pv.global_theme.anti_aliasing = None
See :ref:`anti_aliasing_example` for more information regarding
anti-aliasing.
"""
return self._anti_aliasing
@anti_aliasing.setter
def anti_aliasing(self, anti_aliasing: str | None):
if isinstance(anti_aliasing, str):
if anti_aliasing not in ['ssaa', 'msaa', 'fxaa']:
msg = 'anti_aliasing must be either "ssaa", "msaa", or "fxaa"'
raise ValueError(msg)
elif anti_aliasing is not None:
msg = 'anti_aliasing must be either "ssaa", "msaa", "fxaa", or None' # type: ignore[unreachable]
raise TypeError(msg)
self._anti_aliasing = anti_aliasing # type: ignore[assignment]
@property
def multi_samples(self) -> int: # numpydoc ignore=RT01
"""Return or set the default ``multi_samples`` parameter.
Set the number of multisamples to used with hardware anti_aliasing. This
is only used when :attr:`anti_aliasing <Theme.anti_aliasing>` is
set to ``"msaa"``.
Examples
--------
Set the default number of multisamples to 2 and enable ``"msaa"``
>>> import pyvista as pv
>>> pv.global_theme.anti_aliasing = 'msaa'
>>> pv.global_theme.multi_samples = 2
"""
return self._multi_samples
@multi_samples.setter
def multi_samples(self, multi_samples: int):
self._multi_samples = int(multi_samples)
@property
def multi_rendering_splitting_position(self) -> float: # numpydoc ignore=RT01
"""Return or set the default ``multi_rendering_splitting_position`` parameter.
Examples
--------
Set multi_rendering_splitting_position globally to 0.5 (the
middle of the window).
>>> import pyvista as pv
>>> pv.global_theme.multi_rendering_splitting_position = 0.5
"""
return self._multi_rendering_splitting_position # type: ignore[return-value]
@multi_rendering_splitting_position.setter
def multi_rendering_splitting_position(
self,
multi_rendering_splitting_position: float,
):
self._multi_rendering_splitting_position = multi_rendering_splitting_position
@property
def volume_mapper(self) -> str: # numpydoc ignore=RT01
"""Return or set the default ``volume_mapper`` parameter.
Must be one of the following strings, which are mapped to the
following VTK volume mappers.
* ``'fixed_point'`` : :vtk:`vtkFixedPointVolumeRayCastMapper`
* ``'gpu'`` : :vtk:`vtkGPUVolumeRayCastMapper`
* ``'open_gl'`` : :vtk:`vtkOpenGLGPUVolumeRayCastMapper`
* ``'smart'`` : :vtk:`vtkSmartVolumeMapper`
Examples
--------
Set default volume mapper globally to 'gpu'.
>>> import pyvista as pv
>>> pv.global_theme.volume_mapper = 'gpu'
"""
return self._volume_mapper
@volume_mapper.setter
def volume_mapper(self, mapper: str):
mappers = ['fixed_point', 'gpu', 'open_gl', 'smart']
if mapper not in mappers:
msg = (
f'Mapper ({mapper}) unknown. Available volume mappers '
f'include:\n {", ".join(mappers)}'
)
raise ValueError(msg)
self._volume_mapper = mapper
@property
def smooth_shading(self) -> bool: # numpydoc ignore=RT01
"""Return or set the default ``smooth_shading`` parameter.
Examples
--------
Set the global smooth_shading parameter default to ``True``.
>>> import pyvista as pv
>>> pv.global_theme.smooth_shading = True
"""
return self._smooth_shading
@smooth_shading.setter
def smooth_shading(self, smooth_shading: bool):
self._smooth_shading = bool(smooth_shading)
@property
def depth_peeling(self) -> _DepthPeelingConfig: # numpydoc ignore=RT01
"""Return or set the default depth peeling parameters.
Examples
--------
Set the global depth_peeling parameter default to be enabled
with 8 peels.
>>> import pyvista as pv
>>> pv.global_theme.depth_peeling.number_of_peels = 8
>>> pv.global_theme.depth_peeling.occlusion_ratio = 0.0
>>> pv.global_theme.depth_peeling.enabled = True
"""
return self._depth_peeling
@depth_peeling.setter
def depth_peeling(self, config: _DepthPeelingConfig):
if not isinstance(config, _DepthPeelingConfig):
msg = 'Configuration type must be `_DepthPeelingConfig`.' # type: ignore[unreachable]
raise TypeError(msg)
self._depth_peeling = config
@property
def silhouette(self) -> _SilhouetteConfig: # numpydoc ignore=RT01
"""Return or set the default ``silhouette`` configuration.
Examples
--------
Set parameters of the silhouette.
>>> import pyvista as pv
>>> pv.global_theme.silhouette.color = 'grey'
>>> pv.global_theme.silhouette.line_width = 2.0
>>> pv.global_theme.silhouette.feature_angle = 20
"""
return self._silhouette
@silhouette.setter
def silhouette(self, config: _SilhouetteConfig):
if not isinstance(config, _SilhouetteConfig):
msg = 'Configuration type must be `_SilhouetteConfig`' # type: ignore[unreachable]
raise TypeError(msg)
self._silhouette = config
@property
def slider_styles(self) -> _SliderConfig: # numpydoc ignore=RT01
"""Return the default slider style configurations."""
return self._slider_styles
@slider_styles.setter
def slider_styles(self, config: _SliderConfig):
if not isinstance(config, _SliderConfig):
msg = 'Configuration type must be `_SliderConfig`.' # type: ignore[unreachable]
raise TypeError(msg)
self._slider_styles = config
@property
def axes(self) -> _AxesConfig: # numpydoc ignore=RT01
"""Return or set the default ``axes`` configuration.
Examples
--------
Set the x-axis color to black.
>>> import pyvista as pv
>>> pv.global_theme.axes.x_color = 'black'
Show the axes orientation widget by default.
>>> pv.global_theme.axes.show = True
Use the :func:`axes orientation box <pyvista.create_axes_orientation_box>`
as the orientation widget.
>>> pv.global_theme.axes.box = True
"""
return self._axes
@axes.setter
def axes(self, config: _AxesConfig):
if not isinstance(config, _AxesConfig):
msg = 'Configuration type must be `_AxesConfig`.' # type: ignore[unreachable]
raise TypeError(msg)
self._axes = config
@property
def before_close_callback(
self,
) -> Callable[[pyvista.Plotter], None]: # numpydoc ignore=RT01
"""Return the default before_close_callback function for Plotter."""
return self._before_close_callback # type: ignore[return-value]
@before_close_callback.setter
def before_close_callback(
self,
value: Callable[[pyvista.Plotter], None],
):
self._before_close_callback = value
@property
def allow_empty_mesh(self) -> bool: # numpydoc ignore=RT01
"""Return or set whether to allow plotting empty meshes.
Examples
--------
Enable plotting of empty meshes.
>>> import pyvista as pv
>>> pv.global_theme.allow_empty_mesh = True
Now add an empty mesh to a plotter
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(pv.PolyData())
>>> pl.show() # doctest: +SKIP
"""
return self._allow_empty_mesh
@allow_empty_mesh.setter
def allow_empty_mesh(self, allow_empty_mesh: bool):
self._allow_empty_mesh = bool(allow_empty_mesh)
def restore_defaults(self):
"""Restore the theme defaults.
Examples
--------
>>> import pyvista as pv
>>> pv.global_theme.restore_defaults()
"""
self.__init__() # type: ignore[misc]
def __repr__(self):
"""User friendly representation of the current theme."""
txt = [f'{self.name.capitalize()} Theme']
txt.append('-' * len(txt[0]))
parm = {
'Background': 'background',
'Jupyter backend': 'jupyter_backend',
'Full screen': 'full_screen',
'Window size': 'window_size',
'Camera': 'camera',
'Notebook': 'notebook',
'Font': 'font',
'Auto close': 'auto_close',
'Colormap': 'cmap',
'Color': 'color',
'Color Cycler': 'color_cycler',
'NaN color': 'nan_color',
'Edge color': 'edge_color',
'Outline color': 'outline_color',
'Floor color': 'floor_color',
'Colorbar orientation': 'colorbar_orientation',
'Colorbar - horizontal': 'colorbar_horizontal',
'Colorbar - vertical': 'colorbar_vertical',
'Show scalar bar': 'show_scalar_bar',
'Show edges': 'show_edges',
'Lighting': 'lighting',
'Interactive': 'interactive',
'Render points as spheres': 'render_points_as_spheres',
'Transparent Background': 'transparent_background',
'Title': 'title',
'Axes': 'axes',
'Multi-samples': 'multi_samples',
'Multi-renderer Split Pos': 'multi_rendering_splitting_position',
'Volume mapper': 'volume_mapper',
'Smooth shading': 'smooth_shading',
'Depth peeling': 'depth_peeling',
'Silhouette': 'silhouette',
'Slider Styles': 'slider_styles',
'Return Camera Position': 'return_cpos',
'Hidden Line Removal': 'hidden_line_removal',
'Anti-Aliasing': '_anti_aliasing',
'Split sharp edges': '_split_sharp_edges',
'Sharp edges feat. angle': '_sharp_edges_feature_angle',
'Before close callback': '_before_close_callback',
}
for name, attr in parm.items():
setting = getattr(self, attr)
txt.append(f'{name:<25}: {setting}')
return '\n'.join(txt)
@property
def name(self) -> str: # numpydoc ignore=RT01
"""Return or set the name of the theme."""
return self._name
@name.setter
def name(self, name: str):
self._name = name
def load_theme(self, theme: str | Theme) -> None:
"""Overwrite the current theme with a theme.
Parameters
----------
theme : pyvista.plotting.themes.Theme
Theme to use to overwrite this theme.
Examples
--------
Create a custom theme from the default theme and load it into
the global theme of pyvista.
>>> import pyvista as pv
>>> from pyvista.plotting.themes import DocumentTheme
>>> my_theme = DocumentTheme()
>>> my_theme.font.size = 20
>>> my_theme.font.title_size = 40
>>> my_theme.cmap = 'jet'
>>> pv.global_theme.load_theme(my_theme)
>>> pv.global_theme.font.size
20
Create a custom theme from the dark theme and load it into
pyvista.
>>> from pyvista.plotting.themes import DarkTheme
>>> my_theme = DarkTheme()
>>> my_theme.show_edges = True
>>> pv.global_theme.load_theme(my_theme)
>>> pv.global_theme.show_edges
True
"""
if isinstance(theme, str):
theme = load_theme(theme)
if not isinstance(theme, Theme):
msg = '``theme`` must be a pyvista theme like ``pyvista.plotting.themes.Theme``.'
raise TypeError(msg)
for attr_name in Theme.__slots__:
setattr(self, attr_name, getattr(theme, attr_name))
def save(self, filename: str) -> None:
"""Serialize this theme to a json file.
``before_close_callback`` is non-serializable and is omitted.
Parameters
----------
filename : str
Path to save the theme to. Should end in ``'.json'``.
Examples
--------
Export and then load back in a theme.
>>> import pyvista as pv
>>> theme = pv.themes.DocumentTheme()
>>> theme.background = 'white'
>>> theme.save('my_theme.json') # doctest:+SKIP
>>> loaded_theme = pv.load_theme('my_theme.json') # doctest:+SKIP
"""
data = self.to_dict()
# functions are not serializable
del data['before_close_callback']
with Path(filename).open('w') as f:
json.dump(data, f)
@property
def split_sharp_edges(self) -> bool: # numpydoc ignore=RT01
"""Set or return splitting sharp edges.
See :ref:`shading_example` for an example showing split sharp edges.
Examples
--------
Enable the splitting of sharp edges globally.
>>> import pyvista as pv
>>> pv.global_theme.split_sharp_edges = True
>>> pv.global_theme.split_sharp_edges
True
Disable the splitting of sharp edges globally.
>>> import pyvista as pv
>>> pv.global_theme.split_sharp_edges = False
>>> pv.global_theme.split_sharp_edges
False
"""
return self._split_sharp_edges
@split_sharp_edges.setter
def split_sharp_edges(self, value: bool):
self._split_sharp_edges = value
@property
def sharp_edges_feature_angle(self) -> float: # numpydoc ignore=RT01
"""Set or return the angle of the sharp edges feature angle.
See :ref:`shading_example` for an example showing split sharp edges.
Examples
--------
Change the sharp edges feature angle to 45 degrees.
>>> import pyvista as pv
>>> pv.global_theme.sharp_edges_feature_angle = 45.0
>>> pv.global_theme.sharp_edges_feature_angle
45.0
"""
return self._sharp_edges_feature_angle
@sharp_edges_feature_angle.setter
def sharp_edges_feature_angle(self, value: float):
self._sharp_edges_feature_angle = float(value)
@property
def lighting_params(self) -> _LightingConfig: # numpydoc ignore=RT01
"""Return or set the default lighting configuration."""
return self._lighting_params
@lighting_params.setter
def lighting_params(self, config: _LightingConfig):
if not isinstance(config, _LightingConfig):
msg = 'Configuration type must be `_LightingConfig`.' # type: ignore[unreachable]
raise TypeError(msg)
self._lighting_params = config
@property
def resample_environment_texture(self) -> bool | float: # numpydoc ignore=RT01
"""Set or return resampling environment texture.
Resample the environment texture when using
:meth:`~pyvista.Plotter.set_environment_texture`.
Set this to a float to set the sampling rate explicitly or set
to ``True`` to downsample the texture to 1/16th of its original
resolution.
Downsampling the texture can substantially improve performance for
some environments, e.g. headless setups or if GPU support is limited.
.. versionadded:: 0.45
Examples
--------
Enable resampling the environment texture globally.
>>> import pyvista as pv
>>> pv.global_theme.resample_environment_texture = True
>>> pv.global_theme.resample_environment_texture
True
Disable the resampling the environment texture.
>>> import pyvista as pv
>>> pv.global_theme.resample_environment_texture = False
>>> pv.global_theme.resample_environment_texture
False
"""
return self._resample_environment_texture
@resample_environment_texture.setter
def resample_environment_texture(self, value: bool | float):
self._resample_environment_texture = value
@property
def logo_file(self) -> str | None: # numpydoc ignore=RT01
"""Return or set the logo file.
.. note::
:func:`pyvista.Plotter.add_logo_widget` will default to
PyVista's logo if this is unset.
Examples
--------
Set the logo file to a custom logo.
>>> import pyvista as pv
>>> from pyvista import examples
>>> logo_file = examples.download_file('vtk.png')
>>> pv.global_theme.logo_file = logo_file
Now the logo will be used by default for :func:`pyvista.Plotter.add_logo_widget`.
>>> pl = pv.Plotter()
>>> _ = pl.add_logo_widget()
>>> _ = pl.add_mesh(pv.Sphere(), show_edges=True)
>>> pl.show()
"""
return self._logo_file
@logo_file.setter
def logo_file(self, logo_file: str | pathlib.Path | None):
if logo_file is None:
path = None
else:
if not pathlib.Path(logo_file).exists():
msg = f'Logo file ({logo_file}) not found.'
raise FileNotFoundError(msg)
path = str(logo_file)
self._logo_file = path
class DarkTheme(Theme):
"""Dark mode theme.
Black background, "viridis" colormap, tan meshes, white (hidden) edges.
Examples
--------
Make the dark theme the global default.
>>> import pyvista as pv
>>> from pyvista import themes
>>> pv.set_plot_theme(themes.DarkTheme())
Alternatively, set via a string.
>>> pv.set_plot_theme('dark')
"""
def __init__(self):
"""Initialize the theme."""
super().__init__()
self.name = 'dark'
self.background = 'black'
self.cmap = 'viridis'
self.font.color = 'white'
self.show_edges = False
self.color = 'lightblue'
self.outline_color = 'white'
self.edge_color = 'white'
self.axes.x_color = 'tomato'
self.axes.y_color = 'seagreen'
self.axes.z_color = 'blue'
class ParaViewTheme(Theme):
"""A paraview-like theme.
Examples
--------
Make the paraview-like theme the global default.
>>> import pyvista as pv
>>> from pyvista import themes
>>> pv.set_plot_theme(themes.ParaViewTheme())
Alternatively, set via a string.
>>> pv.set_plot_theme('paraview')
"""
def __init__(self):
"""Initialize theme."""
super().__init__()
self.name = 'paraview'
self.background = 'paraview'
self.cmap = 'coolwarm'
self.font.family = 'arial'
self.font.label_size = 16
self.font.color = 'white'
self.show_edges = False
self.color = 'white'
self.outline_color = 'white'
self.edge_color = 'black'
self.axes.x_color = 'tomato'
self.axes.y_color = 'gold'
self.axes.z_color = 'green'
class DocumentTheme(Theme):
"""A document theme well suited for papers and presentations.
This theme uses:
* A white background
* Black fonts
* The "viridis" colormap
* disables edges for surface plots
* Hidden edge removal
Best used for presentations, papers, etc.
Examples
--------
Make the document theme the global default.
>>> import pyvista as pv
>>> from pyvista import themes
>>> pv.set_plot_theme(themes.DocumentTheme())
Alternatively, set via a string.
>>> pv.set_plot_theme('document')
"""
def __init__(self):
"""Initialize the theme."""
super().__init__()
self.name = 'document'
self.background = 'white'
self.cmap = 'viridis'
self.font.size = 18
self.font.title_size = 18
self.font.label_size = 18
self.font.color = 'black'
self.show_edges = False
self.color = 'lightblue'
self.outline_color = 'black'
self.edge_color = 'black'
self.axes.x_color = 'tomato'
self.axes.y_color = 'seagreen'
self.axes.z_color = 'blue'
class DocumentProTheme(DocumentTheme):
"""A more professional document theme.
This theme extends the base document theme with:
* Default color cycling
* Rendering points as spheres
* MSAA anti aliassing
* Depth peeling
"""
def __init__(self):
"""Initialize the theme."""
super().__init__()
self.name = 'document_pro'
self.anti_aliasing = 'ssaa'
self.color_cycler = get_cycler('default')
self.render_points_as_spheres = True
self.multi_samples = 8
self.depth_peeling.number_of_peels = 4
self.depth_peeling.occlusion_ratio = 0.0
self.depth_peeling.enabled = True
class _DocumentBuildTheme(DocumentTheme):
"""Theme used for building the documentation."""
def __init__(self):
"""Initialize the theme."""
super().__init__()
self.name = 'document_build'
self.window_size = [1024, 768]
self.font.size = 22
self.font.label_size = 22
self.font.title_size = 22
self.return_cpos = False
self.resample_environment_texture = True
class _TestingTheme(Theme):
"""Low resolution testing theme for ``pytest``.
Necessary for image regression. Xvfb doesn't support
multi-sampling, it's disabled for consistency between desktops and
remote testing.
Also disables ``return_cpos`` to make it easier for us to write
examples without returning camera positions.
Resampling is also enabled for environment textures since this
can be very slow without a GPU.
"""
def __init__(self):
super().__init__()
self.name = 'testing'
self.multi_samples = 1
self.window_size = [400, 400]
self.axes.show = False
self.return_cpos = False
self.resample_environment_texture = True
class _NATIVE_THEMES(Enum): # noqa: N801
"""Global built-in themes available to PyVista."""
paraview = ParaViewTheme
document = DocumentTheme
document_pro = DocumentProTheme
document_build = _DocumentBuildTheme
dark = DarkTheme
default = document
testing = _TestingTheme
vtk = Theme
Reference in New Issue Copy Permalink