Debian Codegraph @

pyvista/plotting/themes.py

raw
1 """API description for managing plotting theme parameters in pyvista.
2
3 Examples
4 --------
5 Apply a built-in theme
6
7 >>> import pyvista as pv
8 >>> pv.set_plot_theme('default')
9 >>> pv.set_plot_theme('document')
10 >>> pv.set_plot_theme('dark')
11 >>> pv.set_plot_theme('paraview')
12
13 Load a theme into pyvista
14
15 >>> from pyvista.plotting.themes import DocumentTheme
16 >>> theme = DocumentTheme()
17 >>> theme.save('my_theme.json') # doctest:+SKIP
18 >>> loaded_theme = pv.load_theme('my_theme.json') # doctest:+SKIP
19
20 Create a custom theme from the default theme and load it into
21 pyvista.
22
23 >>> my_theme = DocumentTheme()
24 >>> my_theme.font.size = 20
25 >>> my_theme.font.title_size = 40
26 >>> my_theme.cmap = 'jet'
27 >>> pv.global_theme.load_theme(my_theme)
28 >>> pv.global_theme.font.size
29 20
30
31 """
32
33 from __future__ import annotations
34
35 from enum import Enum
36 import json
37 import os
38 import pathlib
39 from pathlib import Path
40 from typing import TYPE_CHECKING
41 from typing import Any
42 from typing import ClassVar
43
44 import pyvista # noqa: TC001
45 from pyvista._warn_external import warn_external
46 from pyvista.core.config import _ConfigBase
47 from pyvista.core.utilities.misc import _check_range
48
49 from .colors import Color
50 from .colors import get_cmap_safe
51 from .colors import get_cycler
52 from .interactor_style_registry import _validate_interactor_style
53 from .opts import InterpolationType
54 from .opts import PointSpriteShape
55 from .theme_registry import _available_theme_names
56 from .theme_registry import _register_alias
57 from .theme_registry import _register_theme_class
58 from .theme_registry import _resolve_dotted_path
59 from .theme_registry import _resolve_theme
60 from .tools import parse_font_family
61
62 if TYPE_CHECKING:
63 from collections.abc import Callable
64
65 from pyvista.core._typing_core import VectorLike
66
67 from ._typing import ColorLike
68 from ._typing import ColormapOptions
69
70
71 def _set_plot_theme_from_env() -> None:
72 """Set plot theme from an environment variable."""
73 if 'PYVISTA_PLOT_THEME' in os.environ:
74 theme = os.environ['PYVISTA_PLOT_THEME']
75 try:
76 # Dotted paths are case-sensitive; registered names are lowercased.
77 set_plot_theme(theme if ':' in theme else theme.lower())
78 except ValueError:
79 allowed = ', '.join(_available_theme_names())
80 warn_external(
81 f'\n\nInvalid PYVISTA_PLOT_THEME environment variable "{theme}". '
82 f'Should be one of {{ {allowed} }} or "package.module:ClassName".',
83 )
84
85
86 def load_theme(filename):
87 """Load a theme from a file.
88
89 Parameters
90 ----------
91 filename : str
92 Theme file. Must be json.
93
94 Returns
95 -------
96 pyvista.Theme
97 The loaded theme.
98
99 Examples
100 --------
101 >>> import pyvista as pv
102 >>> from pyvista.plotting.themes import DocumentTheme
103 >>> theme = DocumentTheme()
104 >>> theme.save('my_theme.json') # doctest:+SKIP
105 >>> loaded_theme = pv.load_theme('my_theme.json') # doctest:+SKIP
106
107 """
108 with Path(filename).open() as f:
109 theme_dict = json.load(f)
110 return Theme.from_dict(theme_dict)
111
112
113 def set_plot_theme(theme):
114 """Set plotting parameters to a predefined theme using a string or ``Theme``.
115
116 Parameters
117 ----------
118 theme : str | Theme
119 Theme to apply. Accepts any of:
120
121 * A registered theme name. Built-in names include ``'dark'``,
122 ``'default'``, ``'document'``, ``'document_build'``,
123 ``'document_pro'``, ``'paraview'``, ``'testing'``, and
124 ``'vtk'``. Third-party plugins can add more via the
125 ``pyvista.themes`` entry-point group. Use
126 :func:`~pyvista.registered_themes` to list everything that is
127 currently available.
128 * A ``"package.module:ClassName"`` dotted path to any importable
129 :class:`~pyvista.plotting.themes.Theme` subclass.
130 * A :class:`~pyvista.plotting.themes.Theme` instance.
131
132 See Also
133 --------
134 pyvista.registered_themes
135 List all registered theme names.
136 pyvista.plotting.themes.Theme
137 Base class. Subclasses with a class-level ``_default_name`` are
138 discoverable by name; see the class docstring for details aimed
139 at theme authors and plugin packages.
140
141 Examples
142 --------
143 Set to the default theme.
144
145 >>> import pyvista as pv
146 >>> pv.set_plot_theme('default')
147
148 Set to the document theme.
149
150 >>> pv.set_plot_theme('document')
151
152 Set to the dark theme.
153
154 >>> pv.set_plot_theme('dark')
155
156 Set to the ParaView theme.
157
158 >>> pv.set_plot_theme('paraview')
159
160 Load a theme from any importable module using a dotted path.
161
162 >>> pv.set_plot_theme('pyvista.plotting.themes:DarkTheme')
163
164 """
165 import pyvista # noqa: PLC0415
166
167 if isinstance(theme, str):
168 if ':' in theme:
169 cls = _resolve_dotted_path(theme)
170 pyvista.global_theme.load_theme(cls())
171 return
172 resolved = _resolve_theme(theme)
173 if resolved is None:
174 allowed = ', '.join(_available_theme_names())
175 msg = (
176 f'Theme "{theme}" not found. Available themes: {allowed}. '
177 'To load from an arbitrary module use "package.module:ClassName".'
178 )
179 raise ValueError(msg)
180 pyvista.global_theme.load_theme(resolved)
181 elif isinstance(theme, Theme):
182 pyvista.global_theme.load_theme(theme)
183 else:
184 msg = (
185 f'Expected a ``pyvista.plotting.themes.Theme`` or ``str``, not {type(theme).__name__}'
186 )
187 raise TypeError(msg)
188
189
190 class _LightingConfig(_ConfigBase):
191 """PyVista lighting configuration.
192
193 This will control the lighting interpolation type, parameters,
194 and Physically Based Rendering (PBR) options
195
196 Examples
197 --------
198 Set global PBR parameters.
199
200 >>> import pyvista as pv
201 >>> pv.global_theme.lighting_params.interpolation = 'pbr'
202 >>> pv.global_theme.lighting_params.metallic = 0.5
203 >>> pv.global_theme.lighting_params.roughness = 0.25
204
205 """
206
207 __slots__ = [
208 '_ambient',
209 '_diffuse',
210 '_emissive',
211 '_interpolation',
212 '_metallic',
213 '_roughness',
214 '_specular',
215 '_specular_power',
216 ]
217
218 def __init__(self):
219 self._interpolation = InterpolationType.FLAT.value
220 self._metallic = 0.0
221 self._roughness = 0.5
222 self._ambient = 0.0
223 self._diffuse = 1.0
224 self._specular = 0.0
225 self._specular_power = 100.0
226 self._emissive = False
227
228 @property
229 def interpolation(self) -> InterpolationType: # numpydoc ignore=RT01
230 """Return or set the default interpolation type.
231
232 See :class:`pyvista.plotting.opts.InterpolationType`.
233
234 Options are:
235
236 * ``'Phong'``
237 * ``'Flat'``
238 * ``'Physically based rendering'``
239
240 This is stored as an integer value of the ``InterpolationType``
241 so that the theme can be JSON-serializable.
242
243 Examples
244 --------
245 >>> import pyvista as pv
246 >>> pv.global_theme.lighting_params.interpolation = 'Phong'
247 >>> pv.global_theme.lighting_params.interpolation
248 <InterpolationType.PHONG: 2>
249
250
251 """
252 return InterpolationType.from_any(self._interpolation)
253
254 @interpolation.setter
255 def interpolation(
256 self,
257 interpolation: str | int | InterpolationType,
258 ):
259 self._interpolation = InterpolationType.from_any(interpolation).value
260
261 @property
262 def metallic(self) -> float: # numpydoc ignore=RT01
263 """Return or set the metallic value.
264
265 This requires that the interpolation be set to ``'Physically based
266 rendering'``. Must be between 0 and 1.
267
268 Examples
269 --------
270 Set the global metallic value used in physically based rendering to
271 ``0.5``.
272
273 >>> import pyvista as pv
274 >>> pv.global_theme.lighting_params.metallic = 0.5
275 >>> pv.global_theme.lighting_params.metallic
276 0.5
277
278 """
279 return self._metallic
280
281 @metallic.setter
282 def metallic(self, metallic: float):
283 _check_range(metallic, (0, 1), 'metallic')
284 self._metallic = metallic
285
286 @property
287 def roughness(self) -> float: # numpydoc ignore=RT01
288 """Return or set the roughness value.
289
290 This value has to be between 0 (glossy) and 1 (rough). A glossy
291 material has reflections and a high specular part. This parameter is
292 only used by PBR interpolation.
293
294 Examples
295 --------
296 Set the global roughness value used in physically based rendering to
297 ``0.25``.
298
299 >>> import pyvista as pv
300 >>> pv.global_theme.lighting_params.roughness = 0.25
301 >>> pv.global_theme.lighting_params.roughness
302 0.25
303
304 """
305 return self._roughness
306
307 @roughness.setter
308 def roughness(self, roughness: float):
309 _check_range(roughness, (0, 1), 'roughness')
310 self._roughness = roughness
311
312 @property
313 def ambient(self) -> float: # numpydoc ignore=RT01
314 """Return or set the ambient value.
315
316 When lighting is enabled, this is the amount of light in the range of 0
317 to 1 that reaches the actor when not directed at the light source
318 emitted from the viewer.
319
320 Examples
321 --------
322 Set the global ambient lighting value to ``0.2``.
323
324 >>> import pyvista as pv
325 >>> pv.global_theme.lighting_params.ambient = 0.2
326 >>> pv.global_theme.lighting_params.ambient
327 0.2
328
329 """
330 return self._ambient
331
332 @ambient.setter
333 def ambient(self, ambient: float):
334 _check_range(ambient, (0, 1), 'ambient')
335 self._ambient = ambient
336
337 @property
338 def diffuse(self) -> float: # numpydoc ignore=RT01
339 """Return or set the diffuse value.
340
341 This is the scattering of light by reflection or
342 transmission. Diffuse reflection results when light strikes an
343 irregular surface such as a frosted window or the surface of a
344 frosted or coated light bulb. Must be between 0 and 1.
345
346 Examples
347 --------
348 Set the global diffuse lighting value to ``0.5``.
349
350 >>> import pyvista as pv
351 >>> pv.global_theme.lighting_params.diffuse = 0.5
352 >>> pv.global_theme.lighting_params.diffuse
353 0.5
354
355 """
356 return self._diffuse
357
358 @diffuse.setter
359 def diffuse(self, diffuse: float):
360 _check_range(diffuse, (0, 1), 'diffuse')
361 self._diffuse = diffuse
362
363 @property
364 def specular(self) -> float: # numpydoc ignore=RT01
365 """Return or set the specular value.
366
367 Specular lighting simulates the bright spot of a light that appears
368 on shiny objects. Must be between 0 and 1.
369
370 Examples
371 --------
372 Set the global specular value to ``0.1``.
373
374 >>> import pyvista as pv
375 >>> pv.global_theme.lighting_params.specular = 0.1
376 >>> pv.global_theme.lighting_params.specular
377 0.1
378
379 """
380 return self._specular
381
382 @specular.setter
383 def specular(self, specular: float):
384 _check_range(specular, (0, 1), 'specular')
385 self._specular = specular
386
387 @property
388 def specular_power(self) -> float: # numpydoc ignore=RT01
389 """Return or set the specular power value.
390
391 Must be between 0.0 and 128.0.
392
393 Examples
394 --------
395 Set the global specular power value to ``50``.
396
397 >>> import pyvista as pv
398 >>> pv.global_theme.lighting_params.specular_power = 50
399 >>> pv.global_theme.lighting_params.specular_power
400 50
401
402 """
403 return self._specular_power
404
405 @specular_power.setter
406 def specular_power(self, specular_power: float):
407 _check_range(specular_power, (0, 128), 'specular_power')
408 self._specular_power = specular_power
409
410 @property
411 def emissive(self) -> bool: # numpydoc ignore=RT01
412 """Return or set if emissive is used with point Gaussian style.
413
414 Examples
415 --------
416 Globally enable emissive lighting when using the point Gaussian style.
417
418 >>> import pyvista as pv
419 >>> pv.global_theme.lighting_params.emissive = True
420 >>> pv.global_theme.lighting_params.emissive
421 True
422
423 """
424 return self._emissive
425
426 @emissive.setter
427 def emissive(self, emissive: bool):
428 self._emissive = bool(emissive)
429
430
431 class _DepthPeelingConfig(_ConfigBase):
432 """PyVista depth peeling configuration.
433
434 Examples
435 --------
436 Set global depth peeling parameters.
437
438 >>> import pyvista as pv
439 >>> pv.global_theme.depth_peeling.number_of_peels = 1
440 >>> pv.global_theme.depth_peeling.occlusion_ratio = 0.0
441 >>> pv.global_theme.depth_peeling.enabled = True
442
443 """
444
445 __slots__ = ['_enabled', '_number_of_peels', '_occlusion_ratio']
446
447 def __init__(self):
448 self._number_of_peels = 4
449 self._occlusion_ratio = 0.0
450 self._enabled = False
451
452 @property
453 def number_of_peels(self) -> int: # numpydoc ignore=RT01
454 """Return or set the number of peels in depth peeling.
455
456 Examples
457 --------
458 >>> import pyvista as pv
459 >>> pv.global_theme.depth_peeling.number_of_peels = 1
460
461 """
462 return self._number_of_peels
463
464 @number_of_peels.setter
465 def number_of_peels(self, number_of_peels: int):
466 self._number_of_peels = int(number_of_peels)
467
468 @property
469 def occlusion_ratio(self) -> float: # numpydoc ignore=RT01
470 """Return or set the occlusion ratio in depth peeling.
471
472 Examples
473 --------
474 >>> import pyvista as pv
475 >>> pv.global_theme.depth_peeling.occlusion_ratio = 0.0
476
477 """
478 return self._occlusion_ratio
479
480 @occlusion_ratio.setter
481 def occlusion_ratio(self, occlusion_ratio: float):
482 self._occlusion_ratio = float(occlusion_ratio)
483
484 @property
485 def enabled(self) -> bool: # numpydoc ignore=RT01
486 """Return or set if depth peeling is enabled.
487
488 Examples
489 --------
490 >>> import pyvista as pv
491 >>> pv.global_theme.depth_peeling.enabled = True
492
493 """
494 return self._enabled
495
496 @enabled.setter
497 def enabled(self, enabled: bool):
498 self._enabled = bool(enabled)
499
500 def __repr__(self):
501 txt = ['']
502 parm = {
503 'Number': 'number_of_peels',
504 'Occlusion ratio': 'occlusion_ratio',
505 'Enabled': 'enabled',
506 }
507 for name, attr in parm.items():
508 setting = getattr(self, attr)
509 txt.append(f' {name:<21}: {setting}')
510 return '\n'.join(txt)
511
512
513 class _SilhouetteConfig(_ConfigBase):
514 """PyVista silhouette configuration.
515
516 Examples
517 --------
518 Set global silhouette parameters.
519
520 >>> import pyvista as pv
521 >>> pv.global_theme.silhouette.enabled = True
522 >>> pv.global_theme.silhouette.color = 'grey'
523 >>> pv.global_theme.silhouette.line_width = 2
524 >>> pv.global_theme.silhouette.feature_angle = 20
525
526 """
527
528 __slots__ = [
529 '_color',
530 '_decimate',
531 '_enabled',
532 '_feature_angle',
533 '_line_width',
534 '_opacity',
535 ]
536
537 def __init__(self):
538 self._color = Color('black')
539 self._line_width = 2
540 self._opacity = 1.0
541 self._feature_angle = None
542 self._decimate = None
543 self._enabled = False
544
545 @property
546 def enabled(self) -> bool: # numpydoc ignore=RT01
547 """Return or set whether silhouette is on or off."""
548 return self._enabled
549
550 @enabled.setter
551 def enabled(self, enabled: bool):
552 self._enabled = bool(enabled)
553
554 @property
555 def color(self) -> Color: # numpydoc ignore=RT01
556 """Return or set the silhouette color.
557
558 Examples
559 --------
560 >>> import pyvista as pv
561 >>> pv.global_theme.silhouette.color = 'red'
562
563 """
564 return self._color
565
566 @color.setter
567 def color(self, color: ColorLike):
568 self._color = Color(color)
569
570 @property
571 def line_width(self) -> float: # numpydoc ignore=RT01
572 """Return or set the silhouette line width.
573
574 Examples
575 --------
576 >>> import pyvista as pv
577 >>> pv.global_theme.silhouette.line_width = 2.0
578
579 """
580 return self._line_width
581
582 @line_width.setter
583 def line_width(self, line_width: float):
584 self._line_width = float(line_width) # type: ignore[assignment]
585
586 @property
587 def opacity(self) -> float: # numpydoc ignore=RT01
588 """Return or set the silhouette opacity.
589
590 Examples
591 --------
592 >>> import pyvista as pv
593 >>> pv.global_theme.silhouette.opacity = 1.0
594
595 """
596 return self._opacity
597
598 @opacity.setter
599 def opacity(self, opacity: float):
600 _check_range(opacity, (0, 1), 'opacity')
601 self._opacity = float(opacity)
602
603 @property
604 def feature_angle(self) -> float | None: # numpydoc ignore=RT01
605 """Return or set the silhouette feature angle.
606
607 Examples
608 --------
609 >>> import pyvista as pv
610 >>> pv.global_theme.silhouette.feature_angle = 20.0
611
612 """
613 return self._feature_angle
614
615 @feature_angle.setter
616 def feature_angle(self, feature_angle: float | None):
617 self._feature_angle = feature_angle
618
619 @property
620 def decimate(self) -> float: # numpydoc ignore=RT01
621 """Return or set the amount to decimate the silhouette.
622
623 Parameter must be between 0 and 1.
624
625 Examples
626 --------
627 >>> import pyvista as pv
628 >>> pv.global_theme.silhouette.decimate = 0.9
629
630 """
631 return self._decimate # type: ignore[return-value]
632
633 @decimate.setter
634 def decimate(self, decimate: float | None):
635 if decimate is None:
636 self._decimate = None
637 else:
638 _check_range(decimate, (0, 1), 'decimate')
639 self._decimate = float(decimate)
640
641 def __repr__(self):
642 txt = ['']
643 parm = {
644 'Color': 'color',
645 'Line width': 'line_width',
646 'Opacity': 'opacity',
647 'Feature angle': 'feature_angle',
648 'Decimate': 'decimate',
649 }
650 for name, attr in parm.items():
651 setting = getattr(self, attr)
652 txt.append(f' {name:<21}: {setting}')
653 return '\n'.join(txt)
654
655
656 class _ColorbarConfig(_ConfigBase):
657 """PyVista colorbar configuration.
658
659 Examples
660 --------
661 Set the colorbar width.
662
663 >>> import pyvista as pv
664 >>> pv.global_theme.colorbar_horizontal.width = 0.2
665
666 """
667
668 __slots__ = ['_height', '_position_x', '_position_y', '_width']
669
670 def __init__(self):
671 self._width = None
672 self._height = None
673 self._position_x = None
674 self._position_y = None
675
676 @property
677 def width(self) -> float: # numpydoc ignore=RT01
678 """Return or set colorbar width.
679
680 Examples
681 --------
682 >>> import pyvista as pv
683 >>> pv.global_theme.colorbar_horizontal.width = 0.2
684
685 """
686 return self._width # type: ignore[return-value]
687
688 @width.setter
689 def width(self, width: float):
690 self._width = float(width)
691
692 @property
693 def height(self) -> float: # numpydoc ignore=RT01
694 """Return or set colorbar height.
695
696 Examples
697 --------
698 >>> import pyvista as pv
699 >>> pv.global_theme.colorbar_horizontal.height = 0.2
700
701 """
702 return self._height # type: ignore[return-value]
703
704 @height.setter
705 def height(self, height: float):
706 self._height = float(height)
707
708 @property
709 def position_x(self) -> float: # numpydoc ignore=RT01
710 """Return or set colorbar x position.
711
712 Examples
713 --------
714 >>> import pyvista as pv
715 >>> pv.global_theme.colorbar_horizontal.position_x = 0.2
716
717 """
718 return self._position_x # type: ignore[return-value]
719
720 @position_x.setter
721 def position_x(self, position_x: float):
722 self._position_x = float(position_x)
723
724 @property
725 def position_y(self) -> float: # numpydoc ignore=RT01
726 """Return or set colorbar y position.
727
728 Examples
729 --------
730 >>> import pyvista as pv
731 >>> pv.global_theme.colorbar_horizontal.position_y = 0.2
732
733 """
734 return self._position_y # type: ignore[return-value]
735
736 @position_y.setter
737 def position_y(self, position_y: float):
738 self._position_y = float(position_y)
739
740 def __repr__(self):
741 txt = ['']
742 parm = {
743 'Width': 'width',
744 'Height': 'height',
745 'X Position': 'position_x',
746 'Y Position': 'position_y',
747 }
748 for name, attr in parm.items():
749 setting = getattr(self, attr)
750 txt.append(f' {name:<21}: {setting}')
751
752 return '\n'.join(txt)
753
754
755 class _AxesConfig(_ConfigBase):
756 """PyVista axes configuration.
757
758 Examples
759 --------
760 Show the default axes configuration values.
761
762 >>> import pyvista as pv
763 >>> pv.global_theme.axes.x_color
764 Color(name='tomato', hex='#ff6347ff', opacity=255)
765
766 >>> pv.global_theme.axes.y_color
767 Color(name='sea_green', hex='#2e8b57ff', opacity=255)
768
769 >>> pv.global_theme.axes.z_color
770 Color(name='blue', hex='#0000ffff', opacity=255)
771
772 >>> pv.global_theme.axes.box
773 False
774
775 >>> pv.global_theme.axes.show
776 True
777
778 Set the x-axis color to black.
779
780 >>> pv.global_theme.axes.x_color = 'black'
781
782 Show the axes orientation widget by default.
783
784 >>> pv.global_theme.axes.show = True
785
786 Use the :func:`axes orientation box <pyvista.create_axes_orientation_box>`
787 as the orientation widget.
788
789 >>> pv.global_theme.axes.box = True
790
791 """
792
793 __slots__ = ['_box', '_show', '_x_color', '_y_color', '_z_color']
794
795 def __init__(self):
796 self._x_color = Color('tomato')
797 self._y_color = Color('seagreen')
798 self._z_color = Color('mediumblue')
799 self._box = False
800 self._show = True
801
802 def __repr__(self):
803 txt = ['Axes configuration']
804 parm = {
805 'X Color': 'x_color',
806 'Y Color': 'y_color',
807 'Z Color': 'z_color',
808 'Use Box': 'box',
809 'Show': 'show',
810 }
811 for name, attr in parm.items():
812 setting = getattr(self, attr)
813 txt.append(f' {name:<21}: {setting}')
814
815 return '\n'.join(txt)
816
817 @property
818 def x_color(self) -> Color: # numpydoc ignore=RT01
819 """Return or set x-axis color.
820
821 Examples
822 --------
823 Get the default x-axis color
824
825 >>> import pyvista as pv
826 >>> pv.global_theme.axes.x_color
827 Color(name='tomato', hex='#ff6347ff', opacity=255)
828
829 Change the default color.
830
831 >>> pv.global_theme.axes.x_color = 'red'
832
833 """
834 return self._x_color
835
836 @x_color.setter
837 def x_color(self, color: ColorLike):
838 self._x_color = Color(color)
839
840 @property
841 def y_color(self) -> Color: # numpydoc ignore=RT01
842 """Return or set y-axis color.
843
844 Examples
845 --------
846 Get the default y-axis color
847
848 >>> import pyvista as pv
849 >>> pv.global_theme.axes.y_color
850 Color(name='sea_green', hex='#2e8b57ff', opacity=255)
851
852 Change the default color.
853
854 >>> pv.global_theme.axes.y_color = 'green'
855
856 """
857 return self._y_color
858
859 @y_color.setter
860 def y_color(self, color: ColorLike):
861 self._y_color = Color(color)
862
863 @property
864 def z_color(self) -> Color: # numpydoc ignore=RT01
865 """Return or set z-axis color.
866
867 Examples
868 --------
869 Get the default z-axis color
870
871 >>> import pyvista as pv
872 >>> pv.global_theme.axes.z_color
873 Color(name='blue', hex='#0000ffff', opacity=255)
874
875 Change the default color.
876
877 >>> pv.global_theme.axes.z_color = 'purple'
878
879 """
880 return self._z_color
881
882 @z_color.setter
883 def z_color(self, color: ColorLike):
884 self._z_color = Color(color)
885
886 @property
887 def box(self) -> bool: # numpydoc ignore=RT01
888 """Use a box axes orientation widget.
889
890 If ``True``, Use the :func:`axes orientation box <pyvista.create_axes_orientation_box>`
891 instead of the :class:`pyvista.AxesActor` as the orientation widget for plots.
892
893 Examples
894 --------
895 >>> import pyvista as pv
896 >>> pv.global_theme.axes.box = True
897
898 """
899 return self._box
900
901 @box.setter
902 def box(self, box: bool):
903 self._box = bool(box)
904
905 @property
906 def show(self) -> bool: # numpydoc ignore=RT01
907 """Show or hide the axes actor.
908
909 Examples
910 --------
911 Hide the axes by default.
912
913 >>> import pyvista as pv
914 >>> pv.global_theme.axes.show = False
915
916 """
917 return self._show
918
919 @show.setter
920 def show(self, show: bool):
921 self._show = bool(show)
922
923
924 class _Font(_ConfigBase):
925 """PyVista plotter font configuration.
926
927 Examples
928 --------
929 Set the default font family to 'arial'. Must be either
930 'arial', 'courier', or 'times'.
931
932 >>> import pyvista as pv
933 >>> pv.global_theme.font.family = 'arial'
934
935 Set the default font size to 20.
936
937 >>> pv.global_theme.font.size = 20
938
939 Set the default title size to 40
940
941 >>> pv.global_theme.font.title_size = 40
942
943 Set the default label size to 10
944
945 >>> pv.global_theme.font.label_size = 10
946
947 Set the default text color to 'grey'
948
949 >>> pv.global_theme.font.color = 'grey'
950
951 Set the string formatter used to format numerical data to '{:.6e}'
952
953 >>> pv.global_theme.font.fmt = '{:.6e}'
954
955 """
956
957 __slots__ = ['_color', '_family', '_fmt', '_label_size', '_size', '_title_size']
958
959 def __init__(self):
960 self._family = 'arial'
961 self._size = 12
962 self._title_size = None
963 self._label_size = None
964 self._color = Color('white')
965 self._fmt = None
966
967 def __repr__(self):
968 txt = ['']
969 parm = {
970 'Family': 'family',
971 'Size': 'size',
972 'Title size': 'title_size',
973 'Label size': 'label_size',
974 'Color': 'color',
975 'Float format': 'fmt',
976 }
977 for name, attr in parm.items():
978 setting = getattr(self, attr)
979 txt.append(f' {name:<21}: {setting}')
980
981 return '\n'.join(txt)
982
983 @property
984 def family(self) -> str: # numpydoc ignore=RT01
985 """Return or set the font family.
986
987 Must be one of the following:
988
989 * ``"arial"``
990 * ``"courier"``
991 * ``"times"``
992
993 Examples
994 --------
995 Set the default global font family to 'courier'.
996
997 >>> import pyvista as pv
998 >>> pv.global_theme.font.family = 'courier'
999
1000 """
1001 return self._family
1002
1003 @family.setter
1004 def family(self, family: str):
1005 parse_font_family(family) # check valid font
1006 self._family = family
1007
1008 @property
1009 def size(self) -> int: # numpydoc ignore=RT01
1010 """Return or set the font size.
1011
1012 Examples
1013 --------
1014 >>> import pyvista as pv
1015 >>> pv.global_theme.font.size = 20
1016
1017 """
1018 return self._size
1019
1020 @size.setter
1021 def size(self, size: int):
1022 self._size = int(size)
1023
1024 @property
1025 def title_size(self) -> int: # numpydoc ignore=RT01
1026 """Return or set the title size.
1027
1028 If ``None``, then VTK uses ``UnconstrainedFontSizeOn`` for titles.
1029
1030 Examples
1031 --------
1032 >>> import pyvista as pv
1033 >>> pv.global_theme.font.title_size = 20
1034
1035 """
1036 return self._title_size # type: ignore[return-value]
1037
1038 @title_size.setter
1039 def title_size(self, title_size: int | None):
1040 if title_size is None:
1041 self._title_size = None
1042 else:
1043 self._title_size = int(title_size)
1044
1045 @property
1046 def label_size(self) -> int: # numpydoc ignore=RT01
1047 """Return or set the label size.
1048
1049 If ``None``, then VTK uses ``UnconstrainedFontSizeOn`` for labels.
1050
1051 Examples
1052 --------
1053 >>> import pyvista as pv
1054 >>> pv.global_theme.font.label_size = 20
1055
1056 """
1057 return self._label_size # type: ignore[return-value]
1058
1059 @label_size.setter
1060 def label_size(self, label_size: int | None):
1061 if label_size is None:
1062 self._label_size = None
1063 else:
1064 self._label_size = int(label_size)
1065
1066 @property
1067 def color(self) -> Color: # numpydoc ignore=RT01
1068 """Return or set the font color.
1069
1070 Examples
1071 --------
1072 >>> import pyvista as pv
1073 >>> pv.global_theme.font.color = 'black'
1074
1075 """
1076 return self._color
1077
1078 @color.setter
1079 def color(self, color: ColorLike):
1080 self._color = Color(color)
1081
1082 @property
1083 def fmt(self) -> str: # numpydoc ignore=RT01
1084 """Return or set the string formatter used to format numerical data.
1085
1086 Examples
1087 --------
1088 Set the string formatter used to format numerical data to '{:.6e}'.
1089
1090 >>> import pyvista as pv
1091 >>> pv.global_theme.font.fmt = '{:.6e}'
1092
1093 """
1094 return self._fmt # type: ignore[return-value]
1095
1096 @fmt.setter
1097 def fmt(self, fmt: str):
1098 self._fmt = fmt
1099
1100
1101 class _SliderStyleConfig(_ConfigBase):
1102 """PyVista configuration for a single slider style."""
1103
1104 __slots__ = [
1105 '_cap_length',
1106 '_cap_opacity',
1107 '_cap_width',
1108 '_name',
1109 '_slider_color',
1110 '_slider_length',
1111 '_slider_width',
1112 '_tube_color',
1113 '_tube_width',
1114 ]
1115
1116 def __init__(self):
1117 """Initialize the slider style configuration."""
1118 self._name = None
1119 self._slider_length = None
1120 self._slider_width = None
1121 self._slider_color = None
1122 self._tube_width = None
1123 self._tube_color = None
1124 self._cap_opacity = None
1125 self._cap_length = None
1126 self._cap_width = None
1127
1128 @property
1129 def name(self) -> str: # numpydoc ignore=RT01
1130 """Return the name of the slider style configuration."""
1131 return self._name # type: ignore[return-value]
1132
1133 @name.setter
1134 def name(self, name: str):
1135 self._name = name
1136
1137 @property
1138 def cap_width(self) -> float: # numpydoc ignore=RT01
1139 """Return or set the cap width.
1140
1141 Examples
1142 --------
1143 >>> import pyvista as pv
1144 >>> pv.global_theme.slider_styles.modern.cap_width = 0.02
1145
1146 """
1147 return self._cap_width # type: ignore[return-value]
1148
1149 @cap_width.setter
1150 def cap_width(self, cap_width: float):
1151 self._cap_width = float(cap_width)
1152
1153 @property
1154 def cap_length(self) -> float: # numpydoc ignore=RT01
1155 """Return or set the cap length.
1156
1157 Examples
1158 --------
1159 >>> import pyvista as pv
1160 >>> pv.global_theme.slider_styles.modern.cap_length = 0.01
1161
1162 """
1163 return self._cap_length # type: ignore[return-value]
1164
1165 @cap_length.setter
1166 def cap_length(self, cap_length: float):
1167 self._cap_length = float(cap_length)
1168
1169 @property
1170 def cap_opacity(self) -> float: # numpydoc ignore=RT01
1171 """Return or set the cap opacity.
1172
1173 Examples
1174 --------
1175 >>> import pyvista as pv
1176 >>> pv.global_theme.slider_styles.modern.cap_opacity = 1.0
1177
1178 """
1179 return self._cap_opacity # type: ignore[return-value]
1180
1181 @cap_opacity.setter
1182 def cap_opacity(self, cap_opacity: float):
1183 _check_range(cap_opacity, (0, 1), 'cap_opacity')
1184 self._cap_opacity = float(cap_opacity)
1185
1186 @property
1187 def tube_color(self) -> Color: # numpydoc ignore=RT01
1188 """Return or set the tube color.
1189
1190 Examples
1191 --------
1192 >>> import pyvista as pv
1193 >>> pv.global_theme.slider_styles.modern.tube_color = 'black'
1194
1195 """
1196 return self._tube_color # type: ignore[return-value]
1197
1198 @tube_color.setter
1199 def tube_color(self, tube_color: ColorLike):
1200 self._tube_color = Color(tube_color)
1201
1202 @property
1203 def tube_width(self) -> float: # numpydoc ignore=RT01
1204 """Return or set the tube_width.
1205
1206 Examples
1207 --------
1208 >>> import pyvista as pv
1209 >>> pv.global_theme.slider_styles.modern.tube_width = 0.005
1210
1211 """
1212 return self._tube_width # type: ignore[return-value]
1213
1214 @tube_width.setter
1215 def tube_width(self, tube_width: float):
1216 self._tube_width = float(tube_width)
1217
1218 @property
1219 def slider_color(self) -> Color: # numpydoc ignore=RT01
1220 """Return or set the slider color.
1221
1222 Examples
1223 --------
1224 >>> import pyvista as pv
1225 >>> pv.global_theme.slider_styles.modern.slider_color = 'grey'
1226
1227 """
1228 return self._slider_color # type: ignore[return-value]
1229
1230 @slider_color.setter
1231 def slider_color(self, slider_color: ColorLike):
1232 self._slider_color = Color(slider_color)
1233
1234 @property
1235 def slider_width(self) -> float: # numpydoc ignore=RT01
1236 """Return or set the slider width.
1237
1238 Examples
1239 --------
1240 >>> import pyvista as pv
1241 >>> pv.global_theme.slider_styles.modern.slider_width = 0.04
1242
1243 """
1244 return self._slider_width # type: ignore[return-value]
1245
1246 @slider_width.setter
1247 def slider_width(self, slider_width: float):
1248 self._slider_width = float(slider_width)
1249
1250 @property
1251 def slider_length(self) -> float: # numpydoc ignore=RT01
1252 """Return or set the slider_length.
1253
1254 Examples
1255 --------
1256 >>> import pyvista as pv
1257 >>> pv.global_theme.slider_styles.modern.slider_length = 0.02
1258
1259 """
1260 return self._slider_length # type: ignore[return-value]
1261
1262 @slider_length.setter
1263 def slider_length(self, slider_length: float):
1264 self._slider_length = float(slider_length)
1265
1266 def __repr__(self):
1267 txt = ['']
1268 parm = {
1269 'Slider length': 'slider_length',
1270 'Slider width': 'slider_width',
1271 'Slider color': 'slider_color',
1272 'Tube width': 'tube_width',
1273 'Tube color': 'tube_color',
1274 'Cap opacity': 'cap_opacity',
1275 'Cap length': 'cap_length',
1276 'Cap width': 'cap_width',
1277 }
1278 for name, attr in parm.items():
1279 setting = getattr(self, attr)
1280 txt.append(f' {name:<17}: {setting}')
1281 return '\n'.join(txt)
1282
1283
1284 class _SliderConfig(_ConfigBase):
1285 """PyVista configuration encompassing all slider styles.
1286
1287 Examples
1288 --------
1289 Set the classic slider configuration.
1290
1291 >>> import pyvista as pv
1292 >>> slider_styles = pv.global_theme.slider_styles
1293 >>> slider_styles.classic.slider_length = 0.02
1294 >>> slider_styles.classic.slider_width = 0.04
1295 >>> slider_styles.classic.slider_color = (0.5, 0.5, 0.5)
1296 >>> slider_styles.classic.tube_width = 0.005
1297 >>> slider_styles.classic.tube_color = (1.0, 1.0, 1.0)
1298 >>> slider_styles.classic.cap_opacity = 1
1299 >>> slider_styles.classic.cap_length = 0.01
1300 >>> slider_styles.classic.cap_width = 0.02
1301
1302 Set the modern slider configuration.
1303
1304 >>> slider_styles.modern.slider_length = 0.02
1305 >>> slider_styles.modern.slider_width = 0.04
1306 >>> slider_styles.modern.slider_color = (0.43, 0.44, 0.45)
1307 >>> slider_styles.modern.tube_width = 0.04
1308 >>> slider_styles.modern.tube_color = (0.69, 0.70, 0.709)
1309 >>> slider_styles.modern.cap_opacity = 0
1310 >>> slider_styles.modern.cap_length = 0.01
1311 >>> slider_styles.modern.cap_width = 0.02
1312
1313 """
1314
1315 __slots__ = ['_classic', '_modern']
1316
1317 def __init__(self):
1318 """Initialize the slider configuration."""
1319 self._classic = _SliderStyleConfig()
1320 self._classic.name = 'classic'
1321 self._classic.slider_length = 0.02
1322 self._classic.slider_width = 0.04
1323 self._classic.slider_color = 'gray'
1324 self._classic.tube_width = 0.005
1325 self._classic.tube_color = 'white'
1326 self._classic.cap_opacity = 1
1327 self._classic.cap_length = 0.01
1328 self._classic.cap_width = 0.02
1329
1330 self._modern = _SliderStyleConfig()
1331 self._modern.name = 'modern'
1332 self._modern.slider_length = 0.02
1333 self._modern.slider_width = 0.04
1334 self._modern.slider_color = (110, 113, 117)
1335 self._modern.tube_width = 0.04
1336 self._modern.tube_color = (178, 179, 181)
1337 self._modern.cap_opacity = 0
1338 self._modern.cap_length = 0.01
1339 self._modern.cap_width = 0.02
1340
1341 @property
1342 def classic(self) -> _SliderStyleConfig: # numpydoc ignore=RT01
1343 """Return the Classic slider configuration."""
1344 return self._classic
1345
1346 @classic.setter
1347 def classic(self, config: _SliderStyleConfig):
1348 if not isinstance(config, _SliderStyleConfig):
1349 msg = 'Configuration type must be `_SliderStyleConfig`' # type: ignore[unreachable]
1350 raise TypeError(msg)
1351 self._classic = config
1352
1353 @property
1354 def modern(self) -> _SliderStyleConfig: # numpydoc ignore=RT01
1355 """Return the Modern slider configuration."""
1356 return self._modern
1357
1358 @modern.setter
1359 def modern(self, config: _SliderStyleConfig):
1360 if not isinstance(config, _SliderStyleConfig):
1361 msg = 'Configuration type must be `_SliderStyleConfig`' # type: ignore[unreachable]
1362 raise TypeError(msg)
1363 self._modern = config
1364
1365 def __repr__(self):
1366 txt = ['']
1367 parm = {
1368 'Classic': 'classic',
1369 'Modern': 'modern',
1370 }
1371 for name, attr in parm.items():
1372 setting = getattr(self, attr)
1373 txt.append(f' {name:<21}: {setting}')
1374 return '\n'.join(txt)
1375
1376 def __iter__(self):
1377 for style in [self._classic, self._modern]:
1378 yield style.name
1379
1380
1381 class _TrameConfig(_ConfigBase):
1382 """PyVista Trame configuration.
1383
1384 Examples
1385 --------
1386 Set global trame view parameters.
1387
1388 >>> import pyvista as pv
1389 >>> pv.global_theme.trame.interactive_ratio = 2
1390 >>> pv.global_theme.trame.still_ratio = 2
1391
1392 """
1393
1394 __slots__ = [
1395 '_default_mode',
1396 '_interactive_ratio',
1397 '_jupyter_extension_available',
1398 '_jupyter_extension_enabled',
1399 '_jupyter_server_name',
1400 '_jupyter_server_port',
1401 '_server_proxy_enabled',
1402 '_server_proxy_prefix',
1403 '_still_ratio',
1404 ]
1405
1406 def __init__(self):
1407 self._interactive_ratio = 1
1408 self._still_ratio = 1
1409 self._jupyter_server_name = 'pyvista-jupyter'
1410 self._jupyter_server_port = 0
1411 self._server_proxy_enabled = 'PYVISTA_TRAME_SERVER_PROXY_PREFIX' in os.environ
1412 # default for ``jupyter-server-proxy``
1413 service = os.environ.get('JUPYTERHUB_SERVICE_PREFIX', '')
1414 prefix = os.environ.get('PYVISTA_TRAME_SERVER_PROXY_PREFIX', '/proxy/')
1415 if service and not prefix.startswith('http'):
1416 # JupyterHub service prefixes are URL paths, not filesystem paths,
1417 # so use PurePosixPath to force forward-slash joining on Windows.
1418 self._server_proxy_prefix = (
1419 str(pathlib.PurePosixPath(service) / prefix.lstrip('/')).rstrip('/') + '/'
1420 )
1421 self._server_proxy_enabled = True
1422 else:
1423 self._server_proxy_prefix = prefix
1424 self._jupyter_extension_available = 'TRAME_JUPYTER_WWW' in os.environ
1425 self._jupyter_extension_enabled = (
1426 self._jupyter_extension_available and not self._server_proxy_enabled
1427 )
1428 # if set, jupyter_mode overwrites defaults
1429 jupyter_mode = os.environ.get('PYVISTA_TRAME_JUPYTER_MODE')
1430 if jupyter_mode == 'extension' and self._jupyter_extension_available: # pragma: no cover
1431 self._server_proxy_enabled = False
1432 self._jupyter_extension_enabled = True
1433 elif jupyter_mode == 'proxy' and self._server_proxy_enabled: # pragma: no cover
1434 self._jupyter_extension_enabled = False
1435 elif jupyter_mode == 'native': # pragma: no cover
1436 self._jupyter_extension_enabled = False
1437 self._server_proxy_enabled = False
1438 self._default_mode = 'trame'
1439
1440 @property
1441 def interactive_ratio(self) -> float: # numpydoc ignore=RT01
1442 """Return or set the interactive ratio for PyVista Trame views.
1443
1444 Examples
1445 --------
1446 >>> import pyvista as pv
1447 >>> pv.global_theme.trame.interactive_ratio = 2
1448
1449 """
1450 return self._interactive_ratio
1451
1452 @interactive_ratio.setter
1453 def interactive_ratio(self, interactive_ratio: float):
1454 self._interactive_ratio = interactive_ratio # type: ignore[assignment]
1455
1456 @property
1457 def still_ratio(self) -> float: # numpydoc ignore=RT01
1458 """Return or set the still ratio for PyVista Trame views.
1459
1460 Examples
1461 --------
1462 >>> import pyvista as pv
1463 >>> pv.global_theme.trame.still_ratio = 2
1464
1465 """
1466 return self._still_ratio
1467
1468 @still_ratio.setter
1469 def still_ratio(self, still_ratio: float):
1470 self._still_ratio = still_ratio # type: ignore[assignment]
1471
1472 @property
1473 def jupyter_server_name(self): # numpydoc ignore=RT01
1474 """Return or set the trame server name PyVista uses in Jupyter.
1475
1476 This defaults to ``'pyvista-jupyter'``.
1477
1478 This must be set before running :func:`pyvista.set_jupyter_backend`
1479 to ensure a server of this name is launched.
1480
1481 Most users should not need to modify this.
1482
1483 """
1484 return self._jupyter_server_name
1485
1486 @jupyter_server_name.setter
1487 def jupyter_server_name(self, name: str):
1488 self._jupyter_server_name = name
1489
1490 @property
1491 def jupyter_server_port(self) -> int: # numpydoc ignore=RT01
1492 """Return or set the port for the Trame Jupyter server."""
1493 return self._jupyter_server_port
1494
1495 @jupyter_server_port.setter
1496 def jupyter_server_port(self, port: int):
1497 self._jupyter_server_port = port
1498
1499 @property
1500 def server_proxy_enabled(self) -> bool: # numpydoc ignore=RT01
1501 """Return or set if use of relative URLs is enabled for the Jupyter interface."""
1502 return self._server_proxy_enabled
1503
1504 @server_proxy_enabled.setter
1505 def server_proxy_enabled(self, enabled: bool):
1506 if enabled and self.jupyter_extension_enabled:
1507 warn_external('Enabling server_proxy will disable jupyter_extension')
1508 self._jupyter_extension_enabled = False
1509
1510 self._server_proxy_enabled = bool(enabled)
1511
1512 @property
1513 def server_proxy_prefix(self): # numpydoc ignore=RT01
1514 """Return or set URL prefix when using relative URLs with the Jupyter interface."""
1515 return self._server_proxy_prefix
1516
1517 @server_proxy_prefix.setter
1518 def server_proxy_prefix(self, prefix: str):
1519 self._server_proxy_prefix = prefix
1520
1521 @property
1522 def jupyter_extension_available(self) -> bool: # numpydoc ignore=RT01
1523 """Return whether the trame_jupyter_extension is detected."""
1524 return self._jupyter_extension_available
1525
1526 @jupyter_extension_available.setter
1527 def jupyter_extension_available(self, _available: bool):
1528 warn_external(
1529 'The jupyter_extension_available flag is read only and is automatically detected.'
1530 )
1531
1532 @property
1533 def jupyter_extension_enabled(self) -> bool: # numpydoc ignore=RT01
1534 """Return or set whether to use the trame_jupyter_extension to communicate with clients."""
1535 return self._jupyter_extension_enabled
1536
1537 @jupyter_extension_enabled.setter
1538 def jupyter_extension_enabled(self, enabled: bool):
1539 if enabled and not self.jupyter_extension_available:
1540 msg = 'The trame_jupyter_extension is not available'
1541 raise ValueError(msg)
1542
1543 if enabled and self.server_proxy_enabled:
1544 warn_external('Enabling jupyter_extension will disable server_proxy')
1545 self._server_proxy_enabled = False
1546
1547 self._jupyter_extension_enabled = bool(enabled)
1548
1549 @property
1550 def default_mode(self): # numpydoc ignore=RT01
1551 """Return or set the default mode of the Trame backend.
1552
1553 * ``'trame'``: Uses a view that can switch between client and server
1554 rendering modes.
1555 * ``'server'``: Uses a view that is purely server rendering.
1556 * ``'client'``: Uses a view that is purely client rendering (generally
1557 safe without a virtual frame buffer)
1558
1559 """
1560 return self._default_mode
1561
1562 @default_mode.setter
1563 def default_mode(self, mode: str):
1564 self._default_mode = mode
1565
1566
1567 class _CameraConfig(_ConfigBase):
1568 """PyVista camera configuration.
1569
1570 Examples
1571 --------
1572 Set global camera parameters.
1573
1574 >>> import pyvista as pv
1575 >>> pv.global_theme.camera.position = [1.0, 1.0, 1.0]
1576 >>> pv.global_theme.camera.viewup = [0.0, 0.0, 1.0]
1577
1578 """
1579
1580 __slots__ = [
1581 '_parallel_projection',
1582 '_parallel_scale',
1583 '_position',
1584 '_viewup',
1585 ]
1586
1587 def __init__(self):
1588 self._position = [1.0, 1.0, 1.0]
1589 self._viewup = [0.0, 0.0, 1.0]
1590 self._parallel_projection = False
1591 self._parallel_scale = 1.0
1592
1593 @property
1594 def position(self) -> VectorLike[float]: # numpydoc ignore=RT01
1595 """Return or set the camera position.
1596
1597 Examples
1598 --------
1599 Set camera position.
1600
1601 >>> import pyvista as pv
1602 >>> pv.global_theme.camera.position = [1.0, 1.0, 1.0]
1603
1604 """
1605 return self._position
1606
1607 @position.setter
1608 def position(self, position: VectorLike[float]):
1609 self._position = position # type: ignore[assignment]
1610
1611 @property
1612 def viewup(self) -> VectorLike[float]: # numpydoc ignore=RT01
1613 """Return or set the camera viewup.
1614
1615 Examples
1616 --------
1617 Set camera viewup.
1618
1619 >>> import pyvista as pv
1620 >>> pv.global_theme.camera.viewup = [0.0, 0.0, 1.0]
1621
1622 """
1623 return self._viewup
1624
1625 @viewup.setter
1626 def viewup(self, viewup: VectorLike[float]):
1627 self._viewup = viewup # type: ignore[assignment]
1628
1629 @property
1630 def parallel_projection(self) -> bool: # numpydoc ignore=RT01
1631 """Return or set parallel projection mode.
1632
1633 Examples
1634 --------
1635 Enable parallel projection.
1636
1637 >>> import pyvista as pv
1638 >>> pv.global_theme.camera.parallel_projection = True
1639
1640 """
1641 return self._parallel_projection
1642
1643 @parallel_projection.setter
1644 def parallel_projection(self, value: bool) -> None:
1645 self._parallel_projection = value
1646
1647 @property
1648 def parallel_scale(self) -> bool: # numpydoc ignore=RT01
1649 """Return or set parallel scale.
1650
1651 Examples
1652 --------
1653 Set parallel scale.
1654
1655 >>> import pyvista as pv
1656 >>> pv.global_theme.camera.parallel_scale = 2.0
1657
1658 """
1659 return self._parallel_scale # type: ignore[return-value]
1660
1661 @parallel_scale.setter
1662 def parallel_scale(self, value: bool) -> None:
1663 self._parallel_scale = value
1664
1665
1666 class _PlotCellConfig(_ConfigBase):
1667 """Internal config for plotting cells."""
1668
1669 __slots__ = ['_font_size', '_line_width', '_normals_scale', '_point_size']
1670
1671 def __init__(self):
1672 self._line_width = 5
1673 self._point_size = 30
1674 self._font_size = 20
1675 self._normals_scale = 0.1
1676
1677
1678 class Theme(_ConfigBase):
1679 """Base VTK theme.
1680
1681 Notes
1682 -----
1683 This section is aimed at theme authors and plugin package
1684 maintainers; end users calling :func:`~pyvista.set_plot_theme` do
1685 not need any of it.
1686
1687 Subclasses that declare a class-level ``_default_name`` are
1688 automatically registered by that name via ``__init_subclass__``
1689 and become available through :func:`~pyvista.set_plot_theme`, the
1690 ``PYVISTA_PLOT_THEME`` environment variable, and
1691 :func:`~pyvista.registered_themes`. Subclasses without
1692 ``_default_name`` are not registered, so ad-hoc subclasses remain
1693 a valid pattern.
1694
1695 For plugin packages distributing themes, the recommended path is to
1696 declare a ``pyvista.themes`` entry point so the theme is discovered
1697 without requiring users to import the package first:
1698
1699 .. code-block:: toml
1700
1701 [project.entry-points.'pyvista.themes']
1702 my_theme = 'my_package.theme:MyTheme'
1703
1704 Subclass-based auto-registration requires the defining module to be
1705 imported before the name resolves, so it is primarily useful for
1706 scripts, notebooks, testing, and local development. Plugin packages
1707 should prefer the entry-point path.
1708
1709 Examples
1710 --------
1711 Change the global default background color to white.
1712
1713 >>> import pyvista as pv
1714 >>> pv.global_theme.color = 'white'
1715
1716 Show edges by default.
1717
1718 >>> pv.global_theme.show_edges = True
1719
1720 Create a new theme from the default theme and apply it globally.
1721
1722 >>> from pyvista.plotting.themes import DocumentTheme
1723 >>> my_theme = DocumentTheme()
1724 >>> my_theme.color = 'red'
1725 >>> my_theme.background = 'white'
1726 >>> pv.global_theme.load_theme(my_theme)
1727
1728 Define a custom theme that auto-registers under a name.
1729
1730 >>> from typing import ClassVar
1731 >>> class MyTheme(DocumentTheme):
1732 ... _default_name: ClassVar[str] = 'my_theme'
1733 >>> pv.set_plot_theme('my_theme') # doctest: +SKIP
1734
1735 """
1736
1737 # ``_plot_cell`` is an internal-only sub-config — exclude it from
1738 # ``to_dict`` output so themes serialize/deserialize round-trip cleanly.
1739 _TO_DICT_SKIP: ClassVar[frozenset[str]] = frozenset({'plot_cell'})
1740
1741 _default_name: ClassVar[str | None] = None
1742
1743 def __init_subclass__(cls, **kwargs: Any) -> None:
1744 """Auto-register ``Theme`` subclasses by ``_default_name``."""
1745 super().__init_subclass__(**kwargs)
1746 # Read from __dict__ directly so inherited _default_name does not
1747 # accidentally re-register a parent theme's name.
1748 if '_default_name' not in cls.__dict__:
1749 # Subclass does not opt into name-based discovery. Silent skip —
1750 # ad-hoc subclasses are a valid pattern.
1751 return
1752 name = cls.__dict__['_default_name']
1753 if not isinstance(name, str) or not name:
1754 warn_external(
1755 f'Theme subclass {cls.__module__}.{cls.__qualname__} declared '
1756 f"an invalid '_default_name' ({name!r}); expected a non-empty "
1757 'string. The subclass will not be discoverable by name.',
1758 )
1759 return
1760 _register_theme_class(
1761 name,
1762 cls,
1763 source=f'{cls.__module__}.{cls.__qualname__}',
1764 )
1765
1766 __slots__ = [
1767 '_above_range_color',
1768 '_allow_empty_mesh',
1769 '_anti_aliasing',
1770 '_auto_close',
1771 '_axes',
1772 '_background',
1773 '_before_close_callback',
1774 '_before_close_callback',
1775 '_below_range_color',
1776 '_camera',
1777 '_cmap',
1778 '_color',
1779 '_color_cycler',
1780 '_colorbar_horizontal',
1781 '_colorbar_orientation',
1782 '_colorbar_vertical',
1783 '_depth_peeling',
1784 '_edge_color',
1785 '_edge_opacity',
1786 '_enable_camera_orientation_widget',
1787 '_floor_color',
1788 '_font',
1789 '_full_screen',
1790 '_hidden_line_removal',
1791 '_image_scale',
1792 '_interactive',
1793 '_interactor_style',
1794 '_interpolate_before_map',
1795 '_jupyter_backend',
1796 '_lighting',
1797 '_lighting_params',
1798 '_line_width',
1799 '_logo_file',
1800 '_multi_rendering_splitting_position',
1801 '_multi_samples',
1802 '_name',
1803 '_nan_color',
1804 '_notebook',
1805 '_opacity',
1806 '_outline_color',
1807 '_plot_cell',
1808 '_point_shape',
1809 '_point_size',
1810 '_render_lines_as_tubes',
1811 '_render_points_as_spheres',
1812 '_resample_environment_texture',
1813 '_return_cpos',
1814 '_sharp_edges_feature_angle',
1815 '_show_edges',
1816 '_show_scalar_bar',
1817 '_show_vertices',
1818 '_silhouette',
1819 '_slider_styles',
1820 '_smooth_shading',
1821 '_split_sharp_edges',
1822 '_title',
1823 '_trame',
1824 '_transparent_background',
1825 '_volume_mapper',
1826 '_window_size',
1827 ]
1828
1829 def __init__(self):
1830 """Initialize the theme."""
1831 self._name = type(self)._default_name or 'default'
1832 self._background = Color([0.3, 0.3, 0.3])
1833 self._full_screen = False
1834 self._camera = _CameraConfig()
1835
1836 self._notebook = None
1837 self._window_size = [1024, 768]
1838 self._image_scale = 1
1839 self._font = _Font()
1840 self._cmap: ColormapOptions = 'viridis'
1841 self._color = Color('white')
1842 self._color_cycler = None
1843 self._nan_color = Color('darkgray')
1844 self._above_range_color = Color('grey')
1845 self._below_range_color = Color('grey')
1846 self._edge_color = Color('black')
1847 self._line_width = 1.0
1848 self._point_size = 5.0
1849 self._outline_color = Color('white')
1850 self._floor_color = Color('gray')
1851 self._colorbar_orientation = 'horizontal'
1852
1853 self._colorbar_horizontal = _ColorbarConfig()
1854 self._colorbar_horizontal.width = 0.6
1855 self._colorbar_horizontal.height = 0.08
1856 self._colorbar_horizontal.position_x = 0.35
1857 self._colorbar_horizontal.position_y = 0.05
1858
1859 self._colorbar_vertical = _ColorbarConfig()
1860 self._colorbar_vertical.width = 0.08
1861 self._colorbar_vertical.height = 0.45
1862 self._colorbar_vertical.position_x = 0.9
1863 self._colorbar_vertical.position_y = 0.02
1864
1865 self._show_scalar_bar = True
1866 self._show_edges = False
1867 self._show_vertices = False
1868 self._lighting = True
1869 self._interactive = False
1870 self._interactor_style = 'trackball_style'
1871 self._render_points_as_spheres = False
1872 self._render_lines_as_tubes = False
1873 self._point_shape = None
1874 self._transparent_background = False
1875 self._title = 'PyVista'
1876 self._axes = _AxesConfig()
1877 self._split_sharp_edges = False
1878 self._sharp_edges_feature_angle = 30.0
1879 self._before_close_callback = None
1880 self._allow_empty_mesh = False
1881
1882 # Grab system flag for anti-aliasing
1883 # Use a default value of 8 multi-samples as this is default for VTK
1884 try:
1885 self._multi_samples = int(os.environ.get('PYVISTA_MULTI_SAMPLES', '8'))
1886 except ValueError: # pragma: no cover
1887 self._multi_samples = 8
1888
1889 # Grab system flag for auto-closing
1890 self._auto_close = os.environ.get('PYVISTA_AUTO_CLOSE', '').lower() != 'false'
1891
1892 self._jupyter_backend: str | None = os.environ.get('PYVISTA_JUPYTER_BACKEND')
1893 self._trame = _TrameConfig()
1894
1895 self._multi_rendering_splitting_position = None
1896 self._volume_mapper = 'smart'
1897 self._smooth_shading = False
1898 self._depth_peeling = _DepthPeelingConfig()
1899 self._silhouette = _SilhouetteConfig()
1900 self._slider_styles = _SliderConfig()
1901 self._return_cpos = True
1902 self._hidden_line_removal = False
1903 self._anti_aliasing = 'msaa'
1904 self._enable_camera_orientation_widget = False
1905
1906 self._lighting_params = _LightingConfig()
1907 self._interpolate_before_map = True
1908 self._opacity = 1.0
1909 self._edge_opacity = 1.0
1910
1911 self._logo_file = None
1912
1913 self._resample_environment_texture: bool | float = False
1914
1915 self._plot_cell = _PlotCellConfig()
1916
1917 @property
1918 def hidden_line_removal(self) -> bool: # numpydoc ignore=RT01
1919 """Return or set hidden line removal.
1920
1921 Wireframe geometry will be drawn using hidden line removal if
1922 the rendering engine supports it.
1923
1924 See Also
1925 --------
1926 pyvista.Plotter.enable_hidden_line_removal
1927
1928 Examples
1929 --------
1930 Enable hidden line removal.
1931
1932 >>> import pyvista as pv
1933 >>> pv.global_theme.hidden_line_removal = True
1934 >>> pv.global_theme.hidden_line_removal
1935 True
1936
1937 """
1938 return self._hidden_line_removal
1939
1940 @hidden_line_removal.setter
1941 def hidden_line_removal(self, value: bool):
1942 self._hidden_line_removal = value
1943
1944 @property
1945 def interpolate_before_map(self) -> bool: # numpydoc ignore=RT01
1946 """Return or set whether to interpolate colors before mapping.
1947
1948 If the ``interpolate_before_map`` is turned off, the color
1949 mapping occurs at polygon points and colors are interpolated,
1950 which is generally less accurate whereas if the
1951 ``interpolate_before_map`` is on (the default), then the scalars
1952 will be interpolated across the topology of the dataset which is
1953 more accurate.
1954
1955 See also :ref:`interpolate_before_map_example`.
1956
1957 Examples
1958 --------
1959 Enable hidden line removal.
1960
1961 >>> import pyvista as pv
1962
1963 Load a cylinder which has cells with a wide spread
1964
1965 >>> cyl = pv.Cylinder(direction=(0, 0, 1), height=2).elevation()
1966
1967 Common display argument to make sure all else is constant
1968
1969 >>> dargs = dict(scalars='Elevation', cmap='rainbow', show_edges=True)
1970
1971 >>> pl = pv.Plotter(shape=(1, 2))
1972 >>> _ = pl.add_mesh(
1973 ... cyl,
1974 ... interpolate_before_map=False,
1975 ... scalar_bar_args={'title': 'Elevation - interpolated'},
1976 ... **dargs,
1977 ... )
1978 >>> pl.subplot(0, 1)
1979 >>> _ = pl.add_mesh(
1980 ... cyl,
1981 ... interpolate_before_map=True,
1982 ... scalar_bar_args={'title': 'Elevation - interpolated'},
1983 ... **dargs,
1984 ... )
1985 >>> pl.link_views()
1986 >>> pl.camera_position = pv.CameraPosition(
1987 ... position=(-1.67, -5.10, 2.06),
1988 ... focal_point=(0.0, 0.0, 0.0),
1989 ... viewup=(0.00, 0.37, 0.93),
1990 ... )
1991 >>> pl.show() # doctest: +SKIP
1992
1993 """
1994 return self._interpolate_before_map
1995
1996 @interpolate_before_map.setter
1997 def interpolate_before_map(self, value: bool):
1998 self._interpolate_before_map = value
1999
2000 @property
2001 def opacity(self) -> float: # numpydoc ignore=RT01
2002 """Return or set the opacity.
2003
2004 Examples
2005 --------
2006 >>> import pyvista as pv
2007 >>> pv.global_theme.opacity = 0.5
2008
2009 """
2010 return self._opacity
2011
2012 @opacity.setter
2013 def opacity(self, opacity: float):
2014 _check_range(opacity, (0, 1), 'opacity')
2015 self._opacity = float(opacity)
2016
2017 @property
2018 def edge_opacity(self) -> float: # numpydoc ignore=RT01
2019 """Return or set the edges opacity.
2020
2021 .. note::
2022 `edge_opacity` uses ``SetEdgeOpacity`` as the underlying method which
2023 requires VTK version 9.3 or higher. If ``SetEdgeOpacity`` is not
2024 available, `edge_opacity` is set to 1.
2025
2026 Examples
2027 --------
2028 >>> import pyvista as pv
2029 >>> pv.global_theme.edge_opacity = 0.5
2030
2031 """
2032 return self._edge_opacity
2033
2034 @edge_opacity.setter
2035 def edge_opacity(self, edge_opacity: float):
2036 _check_range(edge_opacity, (0, 1), 'edge_opacity')
2037 self._edge_opacity = float(edge_opacity)
2038
2039 @property
2040 def above_range_color(self) -> Color: # numpydoc ignore=RT01
2041 """Return or set the default above range color.
2042
2043 Examples
2044 --------
2045 Set the above range color to red.
2046
2047 >>> import pyvista as pv
2048 >>> pv.global_theme.above_range_color = 'r'
2049 >>> pv.global_theme.above_range_color
2050 Color(name='red', hex='#ff0000ff', opacity=255)
2051
2052 """
2053 return self._above_range_color
2054
2055 @above_range_color.setter
2056 def above_range_color(self, value: ColorLike):
2057 self._above_range_color = Color(value)
2058
2059 @property
2060 def below_range_color(self) -> Color: # numpydoc ignore=RT01
2061 """Return or set the default below range color.
2062
2063 Examples
2064 --------
2065 Set the below range color to blue.
2066
2067 >>> import pyvista as pv
2068 >>> pv.global_theme.below_range_color = 'b'
2069 >>> pv.global_theme.below_range_color
2070 Color(name='blue', hex='#0000ffff', opacity=255)
2071
2072 """
2073 return self._below_range_color
2074
2075 @below_range_color.setter
2076 def below_range_color(self, value: ColorLike):
2077 self._below_range_color = Color(value)
2078
2079 @property
2080 def return_cpos(self) -> bool: # numpydoc ignore=RT01
2081 """Return or set the default behavior of returning the camera position.
2082
2083 Examples
2084 --------
2085 Disable returning camera position by ``show`` and ``plot`` methods.
2086
2087 >>> import pyvista as pv
2088 >>> pv.global_theme.return_cpos = False
2089
2090 """
2091 return self._return_cpos
2092
2093 @return_cpos.setter
2094 def return_cpos(self, value: bool):
2095 self._return_cpos = value
2096
2097 @property
2098 def background(self) -> Color: # numpydoc ignore=RT01
2099 """Return or set the default background color of pyvista plots.
2100
2101 Examples
2102 --------
2103 Set the default global background of all plots to white.
2104
2105 >>> import pyvista as pv
2106 >>> pv.global_theme.background = 'white'
2107
2108 """
2109 return self._background
2110
2111 @background.setter
2112 def background(self, new_background: ColorLike) -> None:
2113 self._background = Color(new_background)
2114
2115 @property
2116 def jupyter_backend(
2117 self,
2118 ) -> str | None: # numpydoc ignore=RT01
2119 """Return or set the jupyter notebook plotting backend.
2120
2121 Jupyter backend to use when plotting. Must be one of the
2122 following:
2123
2124 * ``'static'`` : Display a single static image within the
2125 Jupyterlab environment. Still requires that a virtual
2126 framebuffer be set up when displaying on a headless server,
2127 but does not require any additional modules to be installed.
2128
2129 * ``'client'`` : Export/serialize the scene graph to be rendered
2130 with VTK.js client-side through ``trame``. Requires ``trame``
2131 and ``jupyter-server-proxy`` to be installed.
2132
2133 * ``'server'``: Render remotely and stream the resulting VTK
2134 images back to the client using ``trame``. This replaces the
2135 ``'ipyvtklink'`` backend with better performance.
2136 Supports the most VTK features, but suffers from minor lag due
2137 to remote rendering. Requires that a virtual framebuffer be set
2138 up when displaying on a headless server. Must have at least ``trame``
2139 and ``jupyter-server-proxy`` installed for cloud/remote Jupyter
2140 instances. This mode is also aliased by ``'trame'``.
2141
2142 * ``'trame'``: The full Trame-based backend that combines both
2143 ``'server'`` and ``'client'`` into one backend. This requires a
2144 virtual frame buffer.
2145
2146 * ``'html'``: The ``'client'`` backend, but able to be embedded.
2147
2148 * ``'none'`` : Do not display any plots within jupyterlab,
2149 instead display using dedicated VTK render windows. This
2150 will generate nothing on headless servers even with a
2151 virtual framebuffer.
2152
2153 Examples
2154 --------
2155 Just show static images.
2156
2157 >>> pv.set_jupyter_backend('static') # doctest:+SKIP
2158
2159 Disable all plotting within JupyterLab and display using a
2160 standard desktop VTK render window.
2161
2162 >>> pv.set_jupyter_backend('none') # doctest:+SKIP
2163
2164 Reset to auto-detect the best available backend.
2165
2166 >>> pv.set_jupyter_backend(None) # doctest:+SKIP
2167
2168 """
2169 return self._jupyter_backend
2170
2171 @jupyter_backend.setter
2172 def jupyter_backend(self, backend: str | None):
2173 from pyvista.jupyter import _validate_jupyter_backend # noqa: PLC0415
2174
2175 self._jupyter_backend = _validate_jupyter_backend(backend)
2176
2177 @property
2178 def trame(self) -> _TrameConfig: # numpydoc ignore=RT01
2179 """Return or set the default trame parameters."""
2180 return self._trame
2181
2182 @trame.setter
2183 def trame(self, config: _TrameConfig):
2184 if not isinstance(config, _TrameConfig):
2185 msg = 'Configuration type must be `_TrameConfig`.' # type: ignore[unreachable]
2186 raise TypeError(msg)
2187 self._trame = config
2188
2189 @property
2190 def auto_close(self) -> bool: # numpydoc ignore=RT01
2191 """Automatically close the figures when finished plotting.
2192
2193 .. DANGER::
2194 Set to ``False`` with extreme caution.
2195
2196 Examples
2197 --------
2198 >>> import pyvista as pv
2199 >>> pv.global_theme.auto_close = False
2200
2201 """
2202 return self._auto_close
2203
2204 @auto_close.setter
2205 def auto_close(self, value: bool):
2206 self._auto_close = value
2207
2208 @property
2209 def full_screen(self) -> bool: # numpydoc ignore=RT01
2210 """Return if figures are shown in full screen.
2211
2212 Examples
2213 --------
2214 Set windows to be full screen by default.
2215
2216 >>> import pyvista as pv
2217 >>> pv.global_theme.full_screen = True
2218
2219 """
2220 return self._full_screen
2221
2222 @full_screen.setter
2223 def full_screen(self, value: bool):
2224 self._full_screen = value
2225
2226 @property
2227 def enable_camera_orientation_widget(self) -> bool: # numpydoc ignore=RT01
2228 """Enable the camera orientation widget in all plotters.
2229
2230 Examples
2231 --------
2232 >>> import pyvista as pv
2233 >>> pv.global_theme.enable_camera_orientation_widget = True
2234 >>> pv.global_theme.enable_camera_orientation_widget
2235 True
2236
2237 """
2238 return self._enable_camera_orientation_widget
2239
2240 @enable_camera_orientation_widget.setter
2241 def enable_camera_orientation_widget(self, value: bool):
2242 self._enable_camera_orientation_widget = value
2243
2244 @property
2245 def camera(self): # numpydoc ignore=RT01
2246 """Return or set the default camera position.
2247
2248 Examples
2249 --------
2250 Set both the position and viewup of the camera.
2251
2252 >>> import pyvista as pv
2253 >>> pv.global_theme.camera.position = [1.0, 1.0, 1.0]
2254 >>> pv.global_theme.camera.viewup = [0.0, 0.0, 1.0]
2255
2256 """
2257 return self._camera
2258
2259 @camera.setter
2260 def camera(self, camera):
2261 if isinstance(camera, dict):
2262 self._camera = _CameraConfig.from_dict(camera)
2263 elif isinstance(camera, _CameraConfig):
2264 self._camera = camera
2265 else:
2266 msg = f'camera value must either be a `dict` or a `_CameraConfig`, got {type(camera)}'
2267 raise TypeError(msg)
2268
2269 @property
2270 def notebook(self) -> bool | None: # numpydoc ignore=RT01
2271 """Return or set the state of notebook plotting.
2272
2273 Setting this to ``True`` always enables notebook plotting,
2274 while setting it to ``False`` disables plotting even when
2275 plotting within a jupyter notebook and plots externally.
2276
2277 Examples
2278 --------
2279 Disable all jupyter notebook plotting.
2280
2281 >>> import pyvista as pv
2282 >>> pv.global_theme.notebook = False
2283
2284 """
2285 return self._notebook
2286
2287 @notebook.setter
2288 def notebook(self, value: bool | None):
2289 self._notebook = value
2290
2291 @property
2292 def window_size(self) -> list[int]: # numpydoc ignore=RT01
2293 """Return or set the default render window size.
2294
2295 Examples
2296 --------
2297 Set window size to ``[400, 400]``.
2298
2299 >>> import pyvista as pv
2300 >>> pv.global_theme.window_size = [400, 400]
2301
2302 """
2303 return self._window_size
2304
2305 @window_size.setter
2306 def window_size(self, window_size: list[int]):
2307 if len(window_size) != 2:
2308 msg = 'Expected a length 2 iterable for ``window_size``.'
2309 raise ValueError(msg)
2310
2311 # ensure positive size
2312 if window_size[0] < 0 or window_size[1] < 0:
2313 msg = 'Window size must be a positive value.'
2314 raise ValueError(msg)
2315
2316 self._window_size = window_size
2317
2318 @property
2319 def image_scale(self) -> int: # numpydoc ignore=RT01
2320 """Return or set the default image scale factor."""
2321 return self._image_scale
2322
2323 @image_scale.setter
2324 def image_scale(self, value: int):
2325 value = int(value)
2326 if value < 1:
2327 msg = 'Scale factor must be a positive integer.'
2328 raise ValueError(msg)
2329 self._image_scale = int(value)
2330
2331 @property
2332 def font(self) -> _Font: # numpydoc ignore=RT01
2333 """Return or set the default font size, family, and/or color.
2334
2335 Examples
2336 --------
2337 Set the default font family to 'arial'. Must be either
2338 'arial', 'courier', or 'times'.
2339
2340 >>> import pyvista as pv
2341 >>> pv.global_theme.font.family = 'arial'
2342
2343 Set the default font size to 20.
2344
2345 >>> pv.global_theme.font.size = 20
2346
2347 Set the default title size to 40.
2348
2349 >>> pv.global_theme.font.title_size = 40
2350
2351 Set the default label size to 10.
2352
2353 >>> pv.global_theme.font.label_size = 10
2354
2355 Set the default text color to 'grey'.
2356
2357 >>> pv.global_theme.font.color = 'grey'
2358
2359 String formatter used to format numerical data to '{:.6e}'.
2360
2361 >>> pv.global_theme.font.fmt = '{:.6e}'
2362
2363 """
2364 return self._font
2365
2366 @font.setter
2367 def font(self, config: _Font):
2368 if not isinstance(config, _Font):
2369 msg = 'Configuration type must be `_Font`.' # type: ignore[unreachable]
2370 raise TypeError(msg)
2371 self._font = config
2372
2373 @property
2374 def cmap(self) -> ColormapOptions: # numpydoc ignore=RT01
2375 """Return or set the default colormap of pyvista.
2376
2377 See :ref:`named_colormaps` for supported colormaps.
2378 Only applicable when displaying ``scalars``.
2379
2380 You can also specify a list of colors to override an existing
2381 colormap with a custom one. For example, to create a three
2382 color colormap you might specify ``['green', 'red', 'blue']``
2383
2384 Examples
2385 --------
2386 Set the default global colormap to 'jet'.
2387
2388 >>> import pyvista as pv
2389 >>> pv.global_theme.cmap = 'jet'
2390
2391 """
2392 return self._cmap
2393
2394 @cmap.setter
2395 def cmap(self, cmap: ColormapOptions):
2396 get_cmap_safe(cmap) # for validation
2397 self._cmap = cmap
2398
2399 @property
2400 def color(self) -> Color: # numpydoc ignore=RT01
2401 """Return or set the default color of meshes in pyvista.
2402
2403 Used for meshes without ``scalars``.
2404
2405 When setting, the value must be either a string, rgb list,
2406 or hex color string. For example:
2407
2408 * ``color='white'``
2409 * ``color='w'``
2410 * ``color=[1.0, 1.0, 1.0]``
2411 * ``color='#FFFFFF'``
2412
2413 Examples
2414 --------
2415 Set the default mesh color to 'red'.
2416
2417 >>> import pyvista as pv
2418 >>> pv.global_theme.color = 'red'
2419
2420 """
2421 return self._color
2422
2423 @color.setter
2424 def color(self, color: ColorLike):
2425 self._color = Color(color)
2426
2427 @property
2428 def color_cycler(self): # numpydoc ignore=RT01
2429 """Return or set the default color cycler used to color meshes.
2430
2431 This color cycler is iterated over by each renderer to sequentially
2432 color datasets when displaying them through ``add_mesh``.
2433
2434 When setting, the value must be either a list of color-like objects,
2435 or a cycler of color-like objects. If the value passed is a single
2436 string, it must be one of:
2437
2438 * ``'default'`` - Use the default color cycler (matches matplotlib's default)
2439 * ``'matplotlib`` - Dynamically get matplotlib's current theme's color cycler.
2440 * ``'all'`` - Cycle through all available colors in
2441 ``pyvista.plotting.colors.hexcolors``
2442
2443 Setting to ``None`` will disable the use of the color cycler.
2444
2445 Examples
2446 --------
2447 Set the default color cycler to iterate through red, green, and blue.
2448
2449 >>> import pyvista as pv
2450 >>> pv.global_theme.color_cycler = ['red', 'green', 'blue']
2451
2452 >>> pl = pv.Plotter()
2453 >>> _ = pl.add_mesh(pv.Cone(center=(0, 0, 0))) # red
2454 >>> _ = pl.add_mesh(pv.Cube(center=(1, 0, 0))) # green
2455 >>> _ = pl.add_mesh(pv.Sphere(center=(1, 1, 0))) # blue
2456 >>> _ = pl.add_mesh(pv.Cylinder(center=(0, 1, 0))) # red again
2457 >>> pl.show() # doctest: +SKIP
2458
2459 """
2460 return self._color_cycler
2461
2462 @color_cycler.setter
2463 def color_cycler(self, color_cycler):
2464 self._color_cycler = get_cycler(color_cycler)
2465
2466 @property
2467 def nan_color(self) -> Color: # numpydoc ignore=RT01
2468 """Return or set the default NaN color.
2469
2470 This color is used to plot all NaN values.
2471
2472 Examples
2473 --------
2474 >>> import pyvista as pv
2475 >>> pv.global_theme.nan_color = 'darkgray'
2476
2477 """
2478 return self._nan_color
2479
2480 @nan_color.setter
2481 def nan_color(self, nan_color: ColorLike):
2482 self._nan_color = Color(nan_color)
2483
2484 @property
2485 def edge_color(self) -> Color: # numpydoc ignore=RT01
2486 """Return or set the default edge color.
2487
2488 Examples
2489 --------
2490 Set the global edge color to 'blue'.
2491
2492 >>> import pyvista as pv
2493 >>> pv.global_theme.edge_color = 'blue'
2494
2495 """
2496 return self._edge_color
2497
2498 @edge_color.setter
2499 def edge_color(self, edge_color: ColorLike):
2500 self._edge_color = Color(edge_color)
2501
2502 @property
2503 def line_width(self) -> float: # numpydoc ignore=RT01
2504 """Return or set the default line width.
2505
2506 Examples
2507 --------
2508 >>> import pyvista as pv
2509 >>> pv.global_theme.line_width = 2.0
2510
2511 """
2512 return self._line_width
2513
2514 @line_width.setter
2515 def line_width(self, line_width: float):
2516 self._line_width = float(line_width)
2517
2518 @property
2519 def point_size(self) -> float: # numpydoc ignore=RT01
2520 """Return or set the default point size.
2521
2522 Examples
2523 --------
2524 >>> import pyvista as pv
2525 >>> pv.global_theme.line_width = 10.0
2526
2527 """
2528 return self._point_size
2529
2530 @point_size.setter
2531 def point_size(self, point_size: float):
2532 self._point_size = float(point_size)
2533
2534 @property
2535 def outline_color(self) -> Color: # numpydoc ignore=RT01
2536 """Return or set the default outline color.
2537
2538 Examples
2539 --------
2540 >>> import pyvista as pv
2541 >>> pv.global_theme.outline_color = 'white'
2542
2543 """
2544 return self._outline_color
2545
2546 @outline_color.setter
2547 def outline_color(self, outline_color: ColorLike):
2548 self._outline_color = Color(outline_color)
2549
2550 @property
2551 def floor_color(self) -> Color: # numpydoc ignore=RT01
2552 """Return or set the default floor color.
2553
2554 Examples
2555 --------
2556 >>> import pyvista as pv
2557 >>> pv.global_theme.floor_color = 'black'
2558
2559 """
2560 return self._floor_color
2561
2562 @floor_color.setter
2563 def floor_color(self, floor_color: ColorLike):
2564 self._floor_color = Color(floor_color)
2565
2566 @property
2567 def colorbar_orientation(self) -> str: # numpydoc ignore=RT01
2568 """Return or set the default colorbar orientation.
2569
2570 Must be either ``'vertical'`` or ``'horizontal'``.
2571
2572 Examples
2573 --------
2574 >>> import pyvista as pv
2575 >>> pv.global_theme.colorbar_orientation = 'horizontal'
2576
2577 """
2578 return self._colorbar_orientation
2579
2580 @colorbar_orientation.setter
2581 def colorbar_orientation(self, colorbar_orientation: str):
2582 if colorbar_orientation not in ['vertical', 'horizontal']:
2583 msg = 'Colorbar orientation must be either "vertical" or "horizontal"'
2584 raise ValueError(msg)
2585 self._colorbar_orientation = colorbar_orientation
2586
2587 @property
2588 def colorbar_horizontal(self) -> _ColorbarConfig: # numpydoc ignore=RT01
2589 """Return or set the default parameters of a horizontal colorbar.
2590
2591 Examples
2592 --------
2593 Set the default horizontal colorbar width to 0.6.
2594
2595 >>> import pyvista as pv
2596 >>> pv.global_theme.colorbar_horizontal.width = 0.6
2597
2598 Set the default horizontal colorbar height to 0.2.
2599
2600 >>> pv.global_theme.colorbar_horizontal.height = 0.2
2601
2602 """
2603 return self._colorbar_horizontal
2604
2605 @colorbar_horizontal.setter
2606 def colorbar_horizontal(self, config: _ColorbarConfig):
2607 if not isinstance(config, _ColorbarConfig):
2608 msg = 'Configuration type must be `_ColorbarConfig`.' # type: ignore[unreachable]
2609 raise TypeError(msg)
2610 self._colorbar_horizontal = config
2611
2612 @property
2613 def colorbar_vertical(self) -> _ColorbarConfig: # numpydoc ignore=RT01
2614 """Return or set the default parameters of a vertical colorbar.
2615
2616 Examples
2617 --------
2618 Set the default colorbar width to 0.45.
2619
2620 >>> import pyvista as pv
2621 >>> pv.global_theme.colorbar_vertical.width = 0.45
2622
2623 Set the default colorbar height to 0.8.
2624
2625 >>> import pyvista as pv
2626 >>> pv.global_theme.colorbar_vertical.height = 0.8
2627
2628 """
2629 return self._colorbar_vertical
2630
2631 @colorbar_vertical.setter
2632 def colorbar_vertical(self, config: _ColorbarConfig):
2633 if not isinstance(config, _ColorbarConfig):
2634 msg = 'Configuration type must be `_ColorbarConfig`.' # type: ignore[unreachable]
2635 raise TypeError(msg)
2636 self._colorbar_vertical = config
2637
2638 @property
2639 def show_scalar_bar(self) -> bool: # numpydoc ignore=RT01
2640 """Return or set the default color bar visibility.
2641
2642 Examples
2643 --------
2644 Show the scalar bar by default when scalars are available.
2645
2646 >>> import pyvista as pv
2647 >>> pv.global_theme.show_scalar_bar = True
2648
2649 """
2650 return self._show_scalar_bar
2651
2652 @show_scalar_bar.setter
2653 def show_scalar_bar(self, show_scalar_bar: bool):
2654 self._show_scalar_bar = bool(show_scalar_bar)
2655
2656 @property
2657 def show_edges(self) -> bool: # numpydoc ignore=RT01
2658 """Return or set the default edge visibility.
2659
2660 Examples
2661 --------
2662 Show edges globally by default.
2663
2664 >>> import pyvista as pv
2665 >>> pv.global_theme.show_edges = True
2666
2667 """
2668 return self._show_edges
2669
2670 @show_edges.setter
2671 def show_edges(self, show_edges: bool):
2672 self._show_edges = bool(show_edges)
2673
2674 @property
2675 def show_vertices(self) -> bool: # numpydoc ignore=RT01
2676 """Return or set the default vertex visibility.
2677
2678 Examples
2679 --------
2680 Show vertices globally by default.
2681
2682 >>> import pyvista as pv
2683 >>> pv.global_theme.show_vertices = True
2684
2685 """
2686 return self._show_vertices
2687
2688 @show_vertices.setter
2689 def show_vertices(self, show_vertices: bool):
2690 self._show_vertices = bool(show_vertices)
2691
2692 @property
2693 def lighting(self) -> bool: # numpydoc ignore=RT01
2694 """Return or set the default ``lighting``.
2695
2696 Examples
2697 --------
2698 Disable lighting globally.
2699
2700 >>> import pyvista as pv
2701 >>> pv.global_theme.lighting = False
2702
2703 """
2704 return self._lighting
2705
2706 @lighting.setter
2707 def lighting(self, lighting: bool):
2708 self._lighting = lighting
2709
2710 @property
2711 def interactive(self) -> bool: # numpydoc ignore=RT01
2712 """Return or set the default ``interactive`` parameter.
2713
2714 Examples
2715 --------
2716 Make all plots non-interactive globally.
2717
2718 >>> import pyvista as pv
2719 >>> pv.global_theme.interactive = False
2720
2721 """
2722 return self._interactive
2723
2724 @interactive.setter
2725 def interactive(self, interactive: bool):
2726 self._interactive = bool(interactive)
2727
2728 @property
2729 def render_points_as_spheres(self) -> bool: # numpydoc ignore=RT01
2730 """Return or set the default ``render_points_as_spheres`` parameter.
2731
2732 Examples
2733 --------
2734 Render points as spheres by default globally.
2735
2736 >>> import pyvista as pv
2737 >>> pv.global_theme.render_points_as_spheres = True
2738
2739 """
2740 return self._render_points_as_spheres
2741
2742 @render_points_as_spheres.setter
2743 def render_points_as_spheres(self, render_points_as_spheres: bool):
2744 self._render_points_as_spheres = bool(render_points_as_spheres)
2745
2746 @property
2747 def point_shape(self) -> str | None: # numpydoc ignore=RT01
2748 """Return or set the default point sprite shape.
2749
2750 .. versionadded:: 0.48
2751
2752 When set, points are rendered as the specified shape instead of
2753 squares. This automatically disables ``render_points_as_spheres``.
2754
2755 Accepts a :class:`~pyvista.plotting.opts.PointSpriteShape` enum
2756 value or a string. Must be one of ``'circle'``, ``'triangle'``,
2757 ``'hexagon'``, ``'diamond'``, ``'asterisk'``, ``'star'``, or
2758 ``None``.
2759
2760 Examples
2761 --------
2762 Render all points as circles by default globally.
2763
2764 >>> import pyvista as pv
2765 >>> pv.global_theme.point_shape = 'circle'
2766
2767 Or use the enum.
2768
2769 >>> from pyvista.plotting.opts import PointSpriteShape
2770 >>> pv.global_theme.point_shape = PointSpriteShape.CIRCLE
2771
2772 """
2773 return self._point_shape
2774
2775 @point_shape.setter
2776 def point_shape(self, point_shape: PointSpriteShape | str | None):
2777 if point_shape is not None:
2778 try:
2779 point_shape = PointSpriteShape(point_shape)
2780 except ValueError:
2781 valid = ', '.join(s.value for s in PointSpriteShape)
2782 msg = f'Invalid point_shape {point_shape!r}. Must be one of: {valid}'
2783 raise ValueError(msg) from None
2784 point_shape = point_shape.value
2785 self._point_shape = point_shape
2786
2787 @property
2788 def render_lines_as_tubes(self) -> bool: # numpydoc ignore=RT01
2789 """Return or set the default ``render_lines_as_tubes`` parameter.
2790
2791 Examples
2792 --------
2793 Render points as spheres by default globally.
2794
2795 >>> import pyvista as pv
2796 >>> pv.global_theme.render_lines_as_tubes = True
2797
2798 """
2799 return self._render_lines_as_tubes
2800
2801 @render_lines_as_tubes.setter
2802 def render_lines_as_tubes(self, render_lines_as_tubes: bool):
2803 self._render_lines_as_tubes = bool(render_lines_as_tubes)
2804
2805 @property
2806 def transparent_background(self) -> bool: # numpydoc ignore=RT01
2807 """Return or set the default ``transparent_background`` parameter.
2808
2809 Examples
2810 --------
2811 Set transparent_background globally to ``True``.
2812
2813 >>> import pyvista as pv
2814 >>> pv.global_theme.transparent_background = True
2815
2816 """
2817 return self._transparent_background
2818
2819 @transparent_background.setter
2820 def transparent_background(self, transparent_background: bool):
2821 self._transparent_background = transparent_background
2822
2823 @property
2824 def title(self) -> str: # numpydoc ignore=RT01
2825 """Return or set the default ``title`` parameter.
2826
2827 This is the VTK render window title.
2828
2829 Examples
2830 --------
2831 Set title globally to 'plot'.
2832
2833 >>> import pyvista as pv
2834 >>> pv.global_theme.title = 'plot'
2835
2836 """
2837 return self._title
2838
2839 @title.setter
2840 def title(self, title: str):
2841 self._title = title
2842
2843 @property
2844 def anti_aliasing(self) -> str | None: # numpydoc ignore=RT01
2845 """Enable or disable anti-aliasing.
2846
2847 Should be either ``"ssaa"``, ``"msaa"``, ``"fxaa"``, or ``None``.
2848
2849 Examples
2850 --------
2851 Use super-sampling anti-aliasing in the global theme.
2852
2853 >>> import pyvista as pv
2854 >>> pv.global_theme.anti_aliasing = 'ssaa'
2855 >>> pv.global_theme.anti_aliasing
2856 'ssaa'
2857
2858 Disable anti-aliasing in the global theme.
2859
2860 >>> import pyvista as pv
2861 >>> pv.global_theme.anti_aliasing = None
2862
2863 See :ref:`anti_aliasing_example` for more information regarding
2864 anti-aliasing.
2865
2866 """
2867 return self._anti_aliasing
2868
2869 @anti_aliasing.setter
2870 def anti_aliasing(self, anti_aliasing: str | None):
2871 if isinstance(anti_aliasing, str):
2872 if anti_aliasing not in ['ssaa', 'msaa', 'fxaa']:
2873 msg = 'anti_aliasing must be either "ssaa", "msaa", or "fxaa"'
2874 raise ValueError(msg)
2875 elif anti_aliasing is not None:
2876 msg = 'anti_aliasing must be either "ssaa", "msaa", "fxaa", or None' # type: ignore[unreachable]
2877 raise TypeError(msg)
2878
2879 self._anti_aliasing = anti_aliasing # type: ignore[assignment]
2880
2881 @property
2882 def multi_samples(self) -> int: # numpydoc ignore=RT01
2883 """Return or set the default ``multi_samples`` parameter.
2884
2885 Set the number of multisamples to used with hardware anti_aliasing. This
2886 is only used when :attr:`anti_aliasing <Theme.anti_aliasing>` is
2887 set to ``"msaa"``.
2888
2889 Examples
2890 --------
2891 Set the default number of multisamples to 2 and enable ``"msaa"``
2892
2893 >>> import pyvista as pv
2894 >>> pv.global_theme.anti_aliasing = 'msaa'
2895 >>> pv.global_theme.multi_samples = 2
2896
2897 """
2898 return self._multi_samples
2899
2900 @multi_samples.setter
2901 def multi_samples(self, multi_samples: int):
2902 self._multi_samples = int(multi_samples)
2903
2904 @property
2905 def multi_rendering_splitting_position(self) -> float: # numpydoc ignore=RT01
2906 """Return or set the default ``multi_rendering_splitting_position`` parameter.
2907
2908 Examples
2909 --------
2910 Set multi_rendering_splitting_position globally to 0.5 (the
2911 middle of the window).
2912
2913 >>> import pyvista as pv
2914 >>> pv.global_theme.multi_rendering_splitting_position = 0.5
2915
2916 """
2917 return self._multi_rendering_splitting_position # type: ignore[return-value]
2918
2919 @multi_rendering_splitting_position.setter
2920 def multi_rendering_splitting_position(
2921 self,
2922 multi_rendering_splitting_position: float,
2923 ):
2924 self._multi_rendering_splitting_position = multi_rendering_splitting_position
2925
2926 @property
2927 def volume_mapper(self) -> str: # numpydoc ignore=RT01
2928 """Return or set the default ``volume_mapper`` parameter.
2929
2930 Must be one of the following strings, which are mapped to the
2931 following VTK volume mappers.
2932
2933 * ``'fixed_point'`` : :vtk:`vtkFixedPointVolumeRayCastMapper`
2934 * ``'gpu'`` : :vtk:`vtkGPUVolumeRayCastMapper`
2935 * ``'open_gl'`` : :vtk:`vtkOpenGLGPUVolumeRayCastMapper`
2936 * ``'smart'`` : :vtk:`vtkSmartVolumeMapper`
2937
2938 Examples
2939 --------
2940 Set default volume mapper globally to 'gpu'.
2941
2942 >>> import pyvista as pv
2943 >>> pv.global_theme.volume_mapper = 'gpu'
2944
2945 """
2946 return self._volume_mapper
2947
2948 @volume_mapper.setter
2949 def volume_mapper(self, mapper: str):
2950 mappers = ['fixed_point', 'gpu', 'open_gl', 'smart']
2951 if mapper not in mappers:
2952 msg = (
2953 f'Mapper ({mapper}) unknown. Available volume mappers '
2954 f'include:\n {", ".join(mappers)}'
2955 )
2956 raise ValueError(msg)
2957
2958 self._volume_mapper = mapper
2959
2960 @property
2961 def smooth_shading(self) -> bool: # numpydoc ignore=RT01
2962 """Return or set the default ``smooth_shading`` parameter.
2963
2964 Examples
2965 --------
2966 Set the global smooth_shading parameter default to ``True``.
2967
2968 >>> import pyvista as pv
2969 >>> pv.global_theme.smooth_shading = True
2970
2971 """
2972 return self._smooth_shading
2973
2974 @smooth_shading.setter
2975 def smooth_shading(self, smooth_shading: bool):
2976 self._smooth_shading = bool(smooth_shading)
2977
2978 @property
2979 def depth_peeling(self) -> _DepthPeelingConfig: # numpydoc ignore=RT01
2980 """Return or set the default depth peeling parameters.
2981
2982 Examples
2983 --------
2984 Set the global depth_peeling parameter default to be enabled
2985 with 8 peels.
2986
2987 >>> import pyvista as pv
2988 >>> pv.global_theme.depth_peeling.number_of_peels = 8
2989 >>> pv.global_theme.depth_peeling.occlusion_ratio = 0.0
2990 >>> pv.global_theme.depth_peeling.enabled = True
2991
2992 """
2993 return self._depth_peeling
2994
2995 @depth_peeling.setter
2996 def depth_peeling(self, config: _DepthPeelingConfig):
2997 if not isinstance(config, _DepthPeelingConfig):
2998 msg = 'Configuration type must be `_DepthPeelingConfig`.' # type: ignore[unreachable]
2999 raise TypeError(msg)
3000 self._depth_peeling = config
3001
3002 @property
3003 def silhouette(self) -> _SilhouetteConfig: # numpydoc ignore=RT01
3004 """Return or set the default ``silhouette`` configuration.
3005
3006 Examples
3007 --------
3008 Set parameters of the silhouette.
3009
3010 >>> import pyvista as pv
3011 >>> pv.global_theme.silhouette.color = 'grey'
3012 >>> pv.global_theme.silhouette.line_width = 2.0
3013 >>> pv.global_theme.silhouette.feature_angle = 20
3014
3015 """
3016 return self._silhouette
3017
3018 @silhouette.setter
3019 def silhouette(self, config: _SilhouetteConfig):
3020 if not isinstance(config, _SilhouetteConfig):
3021 msg = 'Configuration type must be `_SilhouetteConfig`' # type: ignore[unreachable]
3022 raise TypeError(msg)
3023 self._silhouette = config
3024
3025 @property
3026 def slider_styles(self) -> _SliderConfig: # numpydoc ignore=RT01
3027 """Return the default slider style configurations."""
3028 return self._slider_styles
3029
3030 @slider_styles.setter
3031 def slider_styles(self, config: _SliderConfig):
3032 if not isinstance(config, _SliderConfig):
3033 msg = 'Configuration type must be `_SliderConfig`.' # type: ignore[unreachable]
3034 raise TypeError(msg)
3035 self._slider_styles = config
3036
3037 @property
3038 def axes(self) -> _AxesConfig: # numpydoc ignore=RT01
3039 """Return or set the default ``axes`` configuration.
3040
3041 Examples
3042 --------
3043 Set the x-axis color to black.
3044
3045 >>> import pyvista as pv
3046 >>> pv.global_theme.axes.x_color = 'black'
3047
3048 Show the axes orientation widget by default.
3049
3050 >>> pv.global_theme.axes.show = True
3051
3052 Use the :func:`axes orientation box <pyvista.create_axes_orientation_box>`
3053 as the orientation widget.
3054
3055 >>> pv.global_theme.axes.box = True
3056
3057 """
3058 return self._axes
3059
3060 @axes.setter
3061 def axes(self, config: _AxesConfig):
3062 if not isinstance(config, _AxesConfig):
3063 msg = 'Configuration type must be `_AxesConfig`.' # type: ignore[unreachable]
3064 raise TypeError(msg)
3065 self._axes = config
3066
3067 @property
3068 def before_close_callback(
3069 self,
3070 ) -> Callable[[pyvista.Plotter], None]: # numpydoc ignore=RT01
3071 """Return the default before_close_callback function for Plotter."""
3072 return self._before_close_callback # type: ignore[return-value]
3073
3074 @before_close_callback.setter
3075 def before_close_callback(
3076 self,
3077 value: Callable[[pyvista.Plotter], None],
3078 ):
3079 self._before_close_callback = value
3080
3081 @property
3082 def allow_empty_mesh(self) -> bool: # numpydoc ignore=RT01
3083 """Return or set whether to allow plotting empty meshes.
3084
3085 Examples
3086 --------
3087 Enable plotting of empty meshes.
3088
3089 >>> import pyvista as pv
3090 >>> pv.global_theme.allow_empty_mesh = True
3091
3092 Now add an empty mesh to a plotter
3093
3094 >>> pl = pv.Plotter()
3095 >>> _ = pl.add_mesh(pv.PolyData())
3096 >>> pl.show() # doctest: +SKIP
3097
3098 """
3099 return self._allow_empty_mesh
3100
3101 @allow_empty_mesh.setter
3102 def allow_empty_mesh(self, allow_empty_mesh: bool):
3103 self._allow_empty_mesh = bool(allow_empty_mesh)
3104
3105 def restore_defaults(self):
3106 """Restore the theme defaults.
3107
3108 Examples
3109 --------
3110 >>> import pyvista as pv
3111 >>> pv.global_theme.restore_defaults()
3112
3113 """
3114 self.__init__() # type: ignore[misc]
3115
3116 def __repr__(self):
3117 """User friendly representation of the current theme."""
3118 txt = [f'{self.name.capitalize()} Theme']
3119 txt.append('-' * len(txt[0]))
3120 parm = {
3121 'Background': 'background',
3122 'Jupyter backend': 'jupyter_backend',
3123 'Full screen': 'full_screen',
3124 'Window size': 'window_size',
3125 'Camera': 'camera',
3126 'Notebook': 'notebook',
3127 'Font': 'font',
3128 'Auto close': 'auto_close',
3129 'Colormap': 'cmap',
3130 'Color': 'color',
3131 'Color Cycler': 'color_cycler',
3132 'NaN color': 'nan_color',
3133 'Edge color': 'edge_color',
3134 'Outline color': 'outline_color',
3135 'Floor color': 'floor_color',
3136 'Colorbar orientation': 'colorbar_orientation',
3137 'Colorbar - horizontal': 'colorbar_horizontal',
3138 'Colorbar - vertical': 'colorbar_vertical',
3139 'Show scalar bar': 'show_scalar_bar',
3140 'Show edges': 'show_edges',
3141 'Lighting': 'lighting',
3142 'Interactive': 'interactive',
3143 'Interactor style': 'interactor_style',
3144 'Render points as spheres': 'render_points_as_spheres',
3145 'Transparent Background': 'transparent_background',
3146 'Title': 'title',
3147 'Axes': 'axes',
3148 'Multi-samples': 'multi_samples',
3149 'Multi-renderer Split Pos': 'multi_rendering_splitting_position',
3150 'Volume mapper': 'volume_mapper',
3151 'Smooth shading': 'smooth_shading',
3152 'Depth peeling': 'depth_peeling',
3153 'Silhouette': 'silhouette',
3154 'Slider Styles': 'slider_styles',
3155 'Return Camera Position': 'return_cpos',
3156 'Hidden Line Removal': 'hidden_line_removal',
3157 'Anti-Aliasing': '_anti_aliasing',
3158 'Split sharp edges': '_split_sharp_edges',
3159 'Sharp edges feat. angle': '_sharp_edges_feature_angle',
3160 'Before close callback': '_before_close_callback',
3161 }
3162 for name, attr in parm.items():
3163 setting = getattr(self, attr)
3164 txt.append(f'{name:<25}: {setting}')
3165
3166 return '\n'.join(txt)
3167
3168 @property
3169 def name(self) -> str: # numpydoc ignore=RT01
3170 """Return or set the name of the theme."""
3171 return self._name
3172
3173 @name.setter
3174 def name(self, name: str):
3175 self._name = name
3176
3177 @property
3178 def interactor_style(self) -> str: # numpydoc ignore=RT01
3179 """Return or set the default interactor style.
3180
3181 The value must be the name of a built-in or registered
3182 interactor style. Built-in styles use names that mirror the
3183 public ``enable_*_style`` methods, such as
3184 ``'terrain_style'``.
3185
3186 Returns
3187 -------
3188 str
3189 The default interactor style name.
3190
3191 Examples
3192 --------
3193 Set the default interactor style to terrain.
3194
3195 >>> import pyvista as pv
3196 >>> pv.global_theme.interactor_style = 'terrain_style'
3197
3198 Register and use a custom interactor style.
3199
3200 >>> def custom_style(interactor): ...
3201 >>> pv.register_interactor_style(
3202 ... 'custom_style', custom_style
3203 ... ) # doctest: +SKIP
3204 >>> pv.global_theme.interactor_style = 'custom_style' # doctest: +SKIP
3205
3206 """
3207 return self._interactor_style
3208
3209 @interactor_style.setter
3210 def interactor_style(self, interactor_style: str) -> None:
3211 """Set the default interactor style."""
3212 self._interactor_style = _validate_interactor_style(interactor_style)
3213
3214 def load_theme(self, theme: str | Theme) -> None:
3215 """Overwrite the current theme with a theme.
3216
3217 Parameters
3218 ----------
3219 theme : pyvista.plotting.themes.Theme
3220 Theme to use to overwrite this theme.
3221
3222 Examples
3223 --------
3224 Create a custom theme from the default theme and load it into
3225 the global theme of pyvista.
3226
3227 >>> import pyvista as pv
3228 >>> from pyvista.plotting.themes import DocumentTheme
3229 >>> my_theme = DocumentTheme()
3230 >>> my_theme.font.size = 20
3231 >>> my_theme.font.title_size = 40
3232 >>> my_theme.cmap = 'jet'
3233 >>> pv.global_theme.load_theme(my_theme)
3234 >>> pv.global_theme.font.size
3235 20
3236
3237 Create a custom theme from the dark theme and load it into
3238 pyvista.
3239
3240 >>> from pyvista.plotting.themes import DarkTheme
3241 >>> my_theme = DarkTheme()
3242 >>> my_theme.show_edges = True
3243 >>> pv.global_theme.load_theme(my_theme)
3244 >>> pv.global_theme.show_edges
3245 True
3246
3247 """
3248 if isinstance(theme, str):
3249 theme = load_theme(theme)
3250
3251 if not isinstance(theme, Theme):
3252 msg = '``theme`` must be a pyvista theme like ``pyvista.plotting.themes.Theme``.'
3253 raise TypeError(msg)
3254
3255 for attr_name in Theme.__slots__:
3256 setattr(self, attr_name, getattr(theme, attr_name))
3257
3258 def save(self, filename: str) -> None:
3259 """Serialize this theme to a json file.
3260
3261 ``before_close_callback`` is non-serializable and is omitted.
3262
3263 Parameters
3264 ----------
3265 filename : str
3266 Path to save the theme to. Should end in ``'.json'``.
3267
3268 Examples
3269 --------
3270 Export and then load back in a theme.
3271
3272 >>> import pyvista as pv
3273 >>> theme = pv.themes.DocumentTheme()
3274 >>> theme.background = 'white'
3275 >>> theme.save('my_theme.json') # doctest:+SKIP
3276 >>> loaded_theme = pv.load_theme('my_theme.json') # doctest:+SKIP
3277
3278 """
3279 data = self.to_dict()
3280 # functions are not serializable
3281 del data['before_close_callback']
3282 with Path(filename).open('w') as f:
3283 json.dump(data, f)
3284
3285 @property
3286 def split_sharp_edges(self) -> bool: # numpydoc ignore=RT01
3287 """Set or return splitting sharp edges.
3288
3289 See :ref:`shading_example` for an example showing split sharp edges.
3290
3291 Examples
3292 --------
3293 Enable the splitting of sharp edges globally.
3294
3295 >>> import pyvista as pv
3296 >>> pv.global_theme.split_sharp_edges = True
3297 >>> pv.global_theme.split_sharp_edges
3298 True
3299
3300 Disable the splitting of sharp edges globally.
3301
3302 >>> import pyvista as pv
3303 >>> pv.global_theme.split_sharp_edges = False
3304 >>> pv.global_theme.split_sharp_edges
3305 False
3306
3307 """
3308 return self._split_sharp_edges
3309
3310 @split_sharp_edges.setter
3311 def split_sharp_edges(self, value: bool):
3312 self._split_sharp_edges = value
3313
3314 @property
3315 def sharp_edges_feature_angle(self) -> float: # numpydoc ignore=RT01
3316 """Set or return the angle of the sharp edges feature angle.
3317
3318 See :ref:`shading_example` for an example showing split sharp edges.
3319
3320 Examples
3321 --------
3322 Change the sharp edges feature angle to 45 degrees.
3323
3324 >>> import pyvista as pv
3325 >>> pv.global_theme.sharp_edges_feature_angle = 45.0
3326 >>> pv.global_theme.sharp_edges_feature_angle
3327 45.0
3328
3329 """
3330 return self._sharp_edges_feature_angle
3331
3332 @sharp_edges_feature_angle.setter
3333 def sharp_edges_feature_angle(self, value: float):
3334 self._sharp_edges_feature_angle = float(value)
3335
3336 @property
3337 def lighting_params(self) -> _LightingConfig: # numpydoc ignore=RT01
3338 """Return or set the default lighting configuration."""
3339 return self._lighting_params
3340
3341 @lighting_params.setter
3342 def lighting_params(self, config: _LightingConfig):
3343 if not isinstance(config, _LightingConfig):
3344 msg = 'Configuration type must be `_LightingConfig`.' # type: ignore[unreachable]
3345 raise TypeError(msg)
3346 self._lighting_params = config
3347
3348 @property
3349 def resample_environment_texture(self) -> bool | float: # numpydoc ignore=RT01
3350 """Set or return resampling environment texture.
3351
3352 Resample the environment texture when using
3353 :meth:`~pyvista.Plotter.set_environment_texture`.
3354 Set this to a float to set the sampling rate explicitly or set
3355 to ``True`` to downsample the texture to 1/16th of its original
3356 resolution.
3357
3358 Downsampling the texture can substantially improve performance for
3359 some environments, e.g. headless setups or if GPU support is limited.
3360
3361 .. versionadded:: 0.45
3362
3363 Examples
3364 --------
3365 Enable resampling the environment texture globally.
3366
3367 >>> import pyvista as pv
3368 >>> pv.global_theme.resample_environment_texture = True
3369 >>> pv.global_theme.resample_environment_texture
3370 True
3371
3372 Disable the resampling the environment texture.
3373
3374 >>> import pyvista as pv
3375 >>> pv.global_theme.resample_environment_texture = False
3376 >>> pv.global_theme.resample_environment_texture
3377 False
3378
3379 """
3380 return self._resample_environment_texture
3381
3382 @resample_environment_texture.setter
3383 def resample_environment_texture(self, value: bool | float):
3384 self._resample_environment_texture = value
3385
3386 @property
3387 def logo_file(self) -> str | None: # numpydoc ignore=RT01
3388 """Return or set the logo file.
3389
3390 .. note::
3391
3392 :func:`pyvista.Plotter.add_logo_widget` will default to
3393 PyVista's logo if this is unset.
3394
3395 Examples
3396 --------
3397 Set the logo file to a custom logo.
3398
3399 >>> import pyvista as pv
3400 >>> from pyvista import examples
3401 >>> logo_file = examples.download_file('vtk.png')
3402 >>> pv.global_theme.logo_file = logo_file
3403
3404 Now the logo will be used by default for :func:`pyvista.Plotter.add_logo_widget`.
3405
3406 >>> pl = pv.Plotter()
3407 >>> _ = pl.add_logo_widget()
3408 >>> _ = pl.add_mesh(pv.Sphere(), show_edges=True)
3409 >>> pl.show()
3410
3411 """
3412 return self._logo_file
3413
3414 @logo_file.setter
3415 def logo_file(self, logo_file: str | pathlib.Path | None):
3416 if logo_file is None:
3417 path = None
3418 else:
3419 if not pathlib.Path(logo_file).exists():
3420 msg = f'Logo file ({logo_file}) not found.'
3421 raise FileNotFoundError(msg)
3422 path = str(logo_file)
3423 self._logo_file = path
3424
3425
3426 class DarkTheme(Theme):
3427 """Dark mode theme.
3428
3429 Black background, "viridis" colormap, tan meshes, white (hidden) edges.
3430
3431 Examples
3432 --------
3433 Make the dark theme the global default.
3434
3435 >>> import pyvista as pv
3436 >>> from pyvista import themes
3437 >>> pv.set_plot_theme(themes.DarkTheme())
3438
3439 Alternatively, set via a string.
3440
3441 >>> pv.set_plot_theme('dark')
3442
3443 """
3444
3445 _default_name: ClassVar[str] = 'dark'
3446
3447 def __init__(self):
3448 """Initialize the theme."""
3449 super().__init__()
3450 self.background = 'black'
3451 self.cmap = 'viridis'
3452 self.font.color = 'white'
3453 self.show_edges = False
3454 self.color = 'lightblue'
3455 self.outline_color = 'white'
3456 self.edge_color = 'white'
3457 self.axes.x_color = 'tomato'
3458 self.axes.y_color = 'seagreen'
3459 self.axes.z_color = 'blue'
3460
3461
3462 class ParaViewTheme(Theme):
3463 """A paraview-like theme.
3464
3465 Examples
3466 --------
3467 Make the paraview-like theme the global default.
3468
3469 >>> import pyvista as pv
3470 >>> from pyvista import themes
3471 >>> pv.set_plot_theme(themes.ParaViewTheme())
3472
3473 Alternatively, set via a string.
3474
3475 >>> pv.set_plot_theme('paraview')
3476
3477 """
3478
3479 _default_name: ClassVar[str] = 'paraview'
3480
3481 def __init__(self):
3482 """Initialize theme."""
3483 super().__init__()
3484 self.background = 'paraview'
3485 self.cmap = 'coolwarm'
3486 self.font.family = 'arial'
3487 self.font.label_size = 16
3488 self.font.color = 'white'
3489 self.show_edges = False
3490 self.color = 'white'
3491 self.outline_color = 'white'
3492 self.edge_color = 'black'
3493 self.axes.x_color = 'tomato'
3494 self.axes.y_color = 'gold'
3495 self.axes.z_color = 'green'
3496
3497
3498 class DocumentTheme(Theme):
3499 """A document theme well suited for papers and presentations.
3500
3501 This theme uses:
3502
3503 * A white background
3504 * Black fonts
3505 * The "viridis" colormap
3506 * disables edges for surface plots
3507 * Hidden edge removal
3508
3509 Best used for presentations, papers, etc.
3510
3511 Examples
3512 --------
3513 Make the document theme the global default.
3514
3515 >>> import pyvista as pv
3516 >>> from pyvista import themes
3517 >>> pv.set_plot_theme(themes.DocumentTheme())
3518
3519 Alternatively, set via a string.
3520
3521 >>> pv.set_plot_theme('document')
3522
3523 """
3524
3525 _default_name: ClassVar[str] = 'document'
3526
3527 def __init__(self):
3528 """Initialize the theme."""
3529 super().__init__()
3530 self.background = 'white'
3531 self.cmap = 'viridis'
3532 self.font.size = 18
3533 self.font.title_size = 18
3534 self.font.label_size = 18
3535 self.font.color = 'black'
3536 self.show_edges = False
3537 self.color = 'lightblue'
3538 self.outline_color = 'black'
3539 self.edge_color = 'black'
3540 self.axes.x_color = 'tomato'
3541 self.axes.y_color = 'seagreen'
3542 self.axes.z_color = 'blue'
3543
3544
3545 class DocumentProTheme(DocumentTheme):
3546 """A more professional document theme.
3547
3548 This theme extends the base document theme with:
3549
3550 * Default color cycling
3551 * Rendering points as spheres
3552 * MSAA anti aliassing
3553 * Depth peeling
3554
3555 """
3556
3557 _default_name: ClassVar[str] = 'document_pro'
3558
3559 def __init__(self):
3560 """Initialize the theme."""
3561 super().__init__()
3562 self.anti_aliasing = 'ssaa'
3563 self.color_cycler = get_cycler('default')
3564 self.render_points_as_spheres = True
3565 self.multi_samples = 8
3566 self.depth_peeling.number_of_peels = 4
3567 self.depth_peeling.occlusion_ratio = 0.0
3568 self.depth_peeling.enabled = True
3569
3570
3571 class _DocumentBuildTheme(DocumentTheme):
3572 """Theme used for building the documentation."""
3573
3574 _default_name: ClassVar[str] = 'document_build'
3575
3576 def __init__(self):
3577 """Initialize the theme."""
3578 super().__init__()
3579 self.window_size = [1024, 768]
3580 self.font.size = 22
3581 self.font.label_size = 22
3582 self.font.title_size = 22
3583 self.return_cpos = False
3584 self.resample_environment_texture = True
3585
3586 self._plot_cell._line_width = 10
3587 self._plot_cell._point_size = 80
3588 self._plot_cell._font_size = 50
3589 self._plot_cell._normals_scale = 0.25
3590
3591
3592 class _TestingTheme(Theme):
3593 """Low resolution testing theme for ``pytest``.
3594
3595 Necessary for image regression. Xvfb doesn't support
3596 multi-sampling, it's disabled for consistency between desktops and
3597 remote testing.
3598
3599 Also disables ``return_cpos`` to make it easier for us to write
3600 examples without returning camera positions.
3601
3602 Resampling is also enabled for environment textures since this
3603 can be very slow without a GPU.
3604
3605 """
3606
3607 _default_name: ClassVar[str] = 'testing'
3608
3609 def __init__(self):
3610 super().__init__()
3611 self.multi_samples = 1
3612 self.window_size = [400, 400]
3613 self.axes.show = False
3614 self.return_cpos = False
3615 self.resample_environment_texture = True
3616
3617 self._plot_cell._line_width = 8
3618 self._plot_cell._point_size = 50
3619 self._plot_cell._font_size = 30
3620 self._plot_cell._normals_scale = 0.2
3621
3622
3623 class _NATIVE_THEMES(Enum): # noqa: N801
3624 """Global built-in themes available to PyVista."""
3625
3626 paraview = ParaViewTheme
3627 document = DocumentTheme
3628 document_pro = DocumentProTheme
3629 document_build = _DocumentBuildTheme
3630 dark = DarkTheme
3631 default = document
3632 testing = _TestingTheme
3633 vtk = Theme
3634
3635
3636 # Register legacy name aliases. ``DocumentTheme`` already self-registers as
3637 # ``'document'`` via ``__init_subclass__``; these aliases preserve the
3638 # historical ``'default' -> DocumentTheme`` and ``'vtk' -> Theme`` mappings
3639 # that ``_NATIVE_THEMES`` provided.
3640 _register_alias('default', DocumentTheme)
3641 _register_alias('vtk', Theme)