Debian Codegraph @

pyvista/plotting/lookup_table.py

raw
1 """Wrap :vtk:`vtkLookupTable`."""
2
3 from __future__ import annotations
4
5 from typing import TYPE_CHECKING
6 from typing import Any
7 from typing import cast
8
9 import matplotlib as mpl
10 import numpy as np
11
12 import pyvista as pv
13 from pyvista import _vtk
14 from pyvista._deprecate_positional_args import _deprecate_positional_args
15 from pyvista.core._vtk_utilities import DisableVtkSnakeCase
16 from pyvista.core.utilities.arrays import convert_array
17 from pyvista.core.utilities.misc import _NoNewAttrMixin
18
19 from .colors import Color
20 from .colors import get_cmap_safe
21 from .tools import opacity_transfer_function
22
23 if TYPE_CHECKING:
24 from ._typing import ColorLike
25 from ._typing import ColormapOptions
26
27 RAMP_MAP = {0: 'linear', 1: 's-curve', 2: 'sqrt'}
28 RAMP_MAP_INV = {k: v for v, k in RAMP_MAP.items()}
29
30
31 class lookup_table_ndarray(_NoNewAttrMixin, np.ndarray): # noqa: N801
32 """An ndarray which references the owning table and the underlying :vtk:`vtkArray`.
33
34 This class is used to ensure that the internal :vtk:`vtkLookupTable` updates when
35 the values array is updated.
36
37 """
38
39 def __new__(
40 cls,
41 array,
42 table=None,
43 ):
44 """Allocate the array."""
45 obj = convert_array(array).view(cls)
46 obj.VTKObject = array
47
48 obj.table = _vtk.vtkWeakReference()
49 obj.table.Set(table)
50
51 return obj
52
53 def __array_finalize__(self, obj):
54 """Finalize array (associate with parent metadata)."""
55 _vtk.VTKArray.__array_finalize__(self, obj) # type: ignore[arg-type]
56 if np.shares_memory(self, obj):
57 self.table = getattr(obj, 'table', None)
58 self.VTKObject = getattr(obj, 'VTKObject', None)
59 else:
60 self.table = None
61 self.VTKObject = None
62
63 def __setitem__(self, key, value):
64 """Implement [] set operator.
65
66 When the array is changed it triggers "Modified()" which updates
67 all upstream objects, including any render windows holding the
68 object.
69 """
70 super().__setitem__(key, value)
71 if self.VTKObject is not None:
72 self.VTKObject.Modified()
73
74 # the associated dataset should also be marked as modified
75 if self.table is not None and self.table.Get():
76 # this creates a new shallow copy and is necessary to update the
77 # internal VTK array
78 self.table.Get().values = self
79
80 def __array_wrap__(self, out_arr, context=None, return_scalar: bool = False): # noqa: FBT001, FBT002
81 """Return a numpy scalar if array is 0d.
82
83 See https://github.com/numpy/numpy/issues/5819
84
85 """
86 if out_arr.ndim:
87 return np.ndarray.__array_wrap__(self, out_arr, context, return_scalar)
88
89 # Match numpy's behavior and return a numpy dtype scalar
90 return out_arr[()]
91
92 __getattr__ = _vtk.VTKArray.__getattr__
93
94
95 class LookupTable(_NoNewAttrMixin, DisableVtkSnakeCase, _vtk.vtkLookupTable):
96 """Scalar to RGBA mapping table.
97
98 A lookup table is an array that maps input values to output values. When
99 plotting data over a dataset, it is necessary to map those scalars to
100 colors (in the RGBA format), and this class provides the functionality to
101 do so.
102
103 See :vtk:`vtkLookupTable` for more
104 details regarding the underlying VTK API.
105
106 Parameters
107 ----------
108 cmap : str | matplotlib.colors.Colormap, optional
109 Color map from ``matplotlib``, ``colorcet``, or ``cmocean``. Either
110 ``cmap`` or ``values`` can be set, but not both.
111 See :ref:`named_colormaps` for supported colormaps.
112
113 n_values : int, default: 256
114 Number of colors in the color map.
115
116 flip : bool, default: False
117 Flip the direction of cmap. Most colormaps allow ``*_r`` suffix to do this
118 as well.
119
120 values : array_like[float], optional
121 Lookup table values. Either ``values`` or ``cmap`` can be set, but not
122 both.
123
124 value_range : tuple, optional
125 The range of the brightness of the mapped lookup table. This range is
126 only used when creating custom color maps and will be ignored if
127 ``cmap`` is set.
128
129 hue_range : tuple, optional
130 Lookup table hue range. This range is only used when creating custom
131 color maps and will be ignored if ``cmap`` is set.
132
133 alpha_range : tuple, optional
134 Lookup table alpha (transparency) range. This range is only used when
135 creating custom color maps and will be ignored if ``cmap`` is set.
136
137 scalar_range : tuple, optional
138 The range of scalars which will be mapped to colors. Values outside of
139 this range will be colored according to
140 :attr:`LookupTable.below_range_color` and
141 :attr:`LookupTable.above_range_color`.
142
143 log_scale : bool, optional
144 Use a log scale when mapping scalar values.
145
146 nan_color : ColorLike, optional
147 Color to render any values that are NANs.
148
149 above_range_color : ColorLike, optional
150 Color to render any values above :attr:`LookupTable.scalar_range`.
151
152 below_range_color : ColorLike, optional
153 Color to render any values below :attr:`LookupTable.scalar_range`.
154
155 ramp : str, optional
156 The shape of the table ramp. This range is only used when creating
157 custom color maps and will be ignored if ``cmap`` is set.
158
159 annotations : dict, optional
160 A dictionary of annotations. Keys are the float values in the scalars
161 range to annotate on the scalar bar and the values are the string
162 annotations.
163
164 See Also
165 --------
166 :ref:`lookup_table_example`
167
168 Examples
169 --------
170 Plot the lookup table with the default VTK color map.
171
172 >>> import pyvista as pv
173 >>> lut = pv.LookupTable()
174 >>> lut
175 LookupTable (...)
176 Table Range: (0.0, 1.0)
177 N Values: 256
178 Above Range Color: None
179 Below Range Color: None
180 NAN Color: Color(name='maroon', hex='#800000ff', opacity=255)
181 Log Scale: False
182 Color Map: "PyVista Lookup Table"
183 Alpha Range: (1.0, 1.0)
184 Hue Range: (0.0, 0.66667)
185 Saturation Range (1.0, 1.0)
186 Value Range (1.0, 1.0)
187 Ramp s-curve
188 >>> lut.plot()
189
190 Plot the lookup table with the ``'inferno'`` color map.
191
192 >>> import pyvista as pv
193 >>> lut = pv.LookupTable('inferno', n_values=32)
194 >>> lut
195 LookupTable (...)
196 Table Range: (0.0, 1.0)
197 N Values: 32
198 Above Range Color: None
199 Below Range Color: None
200 NAN Color: Color(name='maroon', hex='#800000ff', opacity=255)
201 Log Scale: False
202 Color Map: "inferno"
203 >>> lut.plot()
204
205 """
206
207 _nan_color_set = False
208 _cmap: mpl.colors.Colormap | None = None
209 _values_manual = False
210 _opacity_parm: tuple[Any, bool, str] = (None, False, 'quadratic')
211
212 @_deprecate_positional_args(allowed=['cmap', 'n_values'])
213 def __init__( # noqa: PLR0917
214 self,
215 cmap=None,
216 n_values=256,
217 flip: bool = False, # noqa: FBT001, FBT002
218 values=None,
219 value_range=None,
220 hue_range=None,
221 alpha_range=None,
222 scalar_range=None,
223 log_scale=None,
224 nan_color=None,
225 above_range_color=None,
226 below_range_color=None,
227 ramp=None,
228 annotations=None,
229 ):
230 """Initialize the lookup table."""
231 if cmap is not None and values is not None:
232 msg = 'Cannot set both `cmap` and `values`.'
233 raise ValueError(msg)
234
235 if cmap is not None:
236 self.apply_cmap(cmap, n_values=n_values, flip=flip)
237 elif values is not None:
238 self.values = values
239 else:
240 self.n_values = n_values
241 if value_range is not None:
242 self.value_range = value_range
243 if hue_range is not None:
244 self.hue_range = hue_range
245 if alpha_range is not None:
246 self.alpha_range = alpha_range
247 if ramp is not None:
248 self.ramp = ramp
249
250 if nan_color is not None:
251 self.nan_color = nan_color
252 if above_range_color is not None:
253 self.above_range_color = above_range_color
254 if below_range_color is not None:
255 self.below_range_color = below_range_color
256 if scalar_range is not None:
257 self.scalar_range = scalar_range
258 if log_scale is not None:
259 self.log_scale = log_scale
260 if annotations is not None:
261 self.annotations = annotations
262
263 @property
264 def value_range(self) -> tuple[float, float] | None: # numpydoc ignore=RT01
265 """Return or set the brightness of the mapped lookup table.
266
267 This range is only used when creating custom color maps and will return
268 ``None`` when a color map has been set with :attr:`LookupTable.cmap`.
269
270 This will clear any existing color map and create new values for the
271 lookup table when set.
272
273 Examples
274 --------
275 Show the effect of setting the value range on the default color
276 map.
277
278 >>> import pyvista as pv
279 >>> lut = pv.LookupTable()
280 >>> lut.value_range = (0, 1.0)
281 >>> lut.plot()
282
283 Demonstrate a different value range.
284
285 >>> import pyvista as pv
286 >>> lut = pv.LookupTable()
287 >>> lut.value_range = (0.5, 0.8)
288 >>> lut.plot()
289
290 """
291 if self._cmap:
292 return None
293 return self.GetValueRange()
294
295 @value_range.setter
296 def value_range(self, value: tuple[float, float]):
297 self.SetValueRange(value)
298 self.rebuild()
299
300 @property
301 def hue_range(self) -> tuple[float, float] | None: # numpydoc ignore=RT01
302 """Return or set the hue range.
303
304 This range is only used when creating custom color maps and will return
305 ``None`` when a color map has been set with :attr:`LookupTable.cmap`.
306
307 This will clear any existing color map and create new values for the
308 lookup table when set.
309
310 Examples
311 --------
312 Set the hue range. This allows you to create a lookup table
313 without setting a color map.
314
315 >>> import pyvista as pv
316 >>> lut = pv.LookupTable()
317 >>> lut.hue_range = (0, 0.1)
318 >>> lut.plot()
319
320 Create a different color map.
321
322 >>> import pyvista as pv
323 >>> lut = pv.LookupTable()
324 >>> lut.hue_range = (0.5, 0.8)
325 >>> lut.plot()
326
327 """
328 if self._cmap:
329 return None
330 return self.GetHueRange()
331
332 @hue_range.setter
333 def hue_range(self, value: tuple[float, float]):
334 self.SetHueRange(value)
335 self.rebuild()
336
337 @property
338 def cmap(self) -> mpl.colors.Colormap | None: # numpydoc ignore=RT01
339 """Return or set the color map used by this lookup table.
340
341 See :ref:`named_colormaps` for supported colormaps.
342
343 Examples
344 --------
345 Apply the single Matplotlib color map ``"Oranges"``.
346
347 >>> import pyvista as pv
348 >>> lut = pv.LookupTable()
349 >>> lut.cmap = 'Oranges'
350 >>> lut.plot()
351
352 Apply a list of colors as a colormap.
353
354 >>> import pyvista as pv
355 >>> lut = pv.LookupTable()
356 >>> lut.cmap = ['black', 'red', 'orange']
357 >>> lut.plot()
358
359 """
360 return self._cmap
361
362 @cmap.setter
363 def cmap(self, value: ColormapOptions):
364 self.apply_cmap(value, self.n_values)
365
366 @property
367 def log_scale(self) -> bool: # numpydoc ignore=RT01
368 """Use log scale.
369
370 When ``True`` the lookup table is a log scale to
371 :attr:`LookupTable.scalar_range`. Otherwise, it is linear scale.
372
373 Examples
374 --------
375 Use log scale for the lookup table.
376
377 >>> import pyvista as pv
378 >>> lut = pv.LookupTable()
379 >>> lut.log_scale = True
380 >>> lut.scalar_range = (1, 100)
381 >>> lut.plot()
382
383 """
384 return bool(self.GetScale())
385
386 @log_scale.setter
387 def log_scale(self, value: bool):
388 self.SetScale(value)
389
390 def __repr__(self):
391 """Return the representation."""
392 lines = [f'{type(self).__name__} ({hex(id(self))})']
393 lines.append(f' Table Range: {self.scalar_range}')
394 lines.append(f' N Values: {self.n_values}')
395 lines.append(f' Above Range Color: {self.above_range_color}')
396 lines.append(f' Below Range Color: {self.below_range_color}')
397 lines.append(f' NAN Color: {self.nan_color}')
398 lines.append(f' Log Scale: {self.log_scale}')
399
400 lines.append(f' Color Map: "{self._lookup_type}"')
401 if not (self.cmap or self._values_manual):
402 lines.append(f' Alpha Range: {self.alpha_range}')
403 lines.append(f' Hue Range: {self.hue_range}')
404 lines.append(f' Saturation Range {self.saturation_range}')
405 lines.append(f' Value Range {self.value_range}')
406 lines.append(f' Ramp {self.ramp}')
407
408 return '\n'.join(lines)
409
410 @property
411 def scalar_range(self) -> tuple[float, float]: # numpydoc ignore=RT01
412 """Return or set the table range.
413
414 This is the range of scalars which will be mapped to colors. Values
415 outside of this range will be colored according to
416 :attr:`LookupTable.below_range_color` and
417 :attr:`LookupTable.above_range_color`.
418
419 Examples
420 --------
421 >>> import pyvista as pv
422 >>> lut = pv.LookupTable()
423 >>> lut.scalar_range = (0, 10)
424 >>> lut.scalar_range
425 (0.0, 10.0)
426
427 """
428 return self.GetTableRange()
429
430 @scalar_range.setter
431 def scalar_range(self, value: tuple[float, float]):
432 self.SetTableRange(value)
433
434 @property
435 def alpha_range(self) -> tuple[float, float] | None: # numpydoc ignore=RT01
436 """Return or set the alpha range.
437
438 This range is only used when creating custom color maps and will return
439 ``None`` when a color map has been set with :attr:`LookupTable.cmap`.
440
441 This will clear any existing color map and create new values for the
442 lookup table when set.
443
444 Examples
445 --------
446 Create a custom "blues" lookup table that decreases in opacity.
447
448 >>> import pyvista as pv
449 >>> lut = pv.LookupTable()
450 >>> lut.hue_range = (0.7, 0.7)
451 >>> lut.alpha_range = (1.0, 0.0)
452 >>> lut.plot(background='grey')
453
454 """
455 if self._cmap:
456 return None
457 return self.GetAlphaRange()
458
459 @alpha_range.setter
460 def alpha_range(self, value: tuple[float, float]):
461 self.SetAlphaRange(value)
462 self.rebuild()
463
464 @property
465 def saturation_range(self) -> tuple[float, float] | None: # numpydoc ignore=RT01
466 """Return or set the saturation range.
467
468 This range is only used when creating custom color maps and will return
469 ``None`` when a color map has been set with :attr:`LookupTable.cmap`.
470
471 This will clear any existing color map and create new values for the
472 lookup table when set.
473
474 Examples
475 --------
476 Create a custom "blues" lookup table that increases in saturation.
477
478 >>> import pyvista as pv
479 >>> lut = pv.LookupTable()
480 >>> lut.hue_range = (0.7, 0.7)
481 >>> lut.saturation_range = (0.0, 1.0)
482 >>> lut.plot(background='grey')
483
484 """
485 if self._cmap:
486 return None
487 return self.GetSaturationRange()
488
489 @saturation_range.setter
490 def saturation_range(self, value: tuple[float, float]):
491 self.SetSaturationRange(value)
492 self.rebuild()
493
494 def rebuild(self):
495 """Clear the color map and recompute the values table.
496
497 This is called automatically when setting values like
498 :attr:`LookupTable.value_range`.
499
500 Notes
501 -----
502 This will reset any colormap set with :func:`LookupTable.apply_cmap` or
503 :attr:`LookupTable.values`.
504
505 """
506 self._cmap = None
507 self._values_manual = False
508 self.ForceBuild()
509
510 @property
511 def nan_color(self) -> Color | None: # numpydoc ignore=RT01
512 """Return or set the not a number (NAN) color.
513
514 Any values that are NANs will be rendered with this color.
515
516 Examples
517 --------
518 Set the NAN color to ``'grey'``.
519
520 >>> import pyvista as pv
521 >>> lut = pv.LookupTable()
522 >>> lut.nan_color = 'grey'
523 >>> lut.plot()
524
525 """
526 return Color(self.GetNanColor())
527
528 @nan_color.setter
529 def nan_color(self, value):
530 # NAN value is always set, but make it explicit for example plotting
531 self._nan_color_set = True
532 self.SetNanColor(*Color(value).float_rgba)
533
534 @property
535 def nan_opacity(self): # numpydoc ignore=RT01
536 """Return or set the not a number (NAN) opacity.
537
538 Any values that are NANs will be rendered with this opacity.
539
540 Examples
541 --------
542 Set the NAN opacity to ``0.5``.
543
544 >>> import pyvista as pv
545 >>> lut = pv.LookupTable()
546 >>> lut.nan_color = 'grey'
547 >>> lut.nan_opacity = 0.5
548 >>> lut.plot()
549
550 """
551 color = self.nan_color
552 return color.opacity # type: ignore[union-attr]
553
554 @nan_opacity.setter
555 def nan_opacity(self, value):
556 # Hacky check to prevent auto activation
557 if not self._nan_color_set and (value in (1.0, 255)):
558 return
559 color = self.nan_color
560 if color is None:
561 color = Color(pv.global_theme.nan_color)
562 self.nan_color = Color(self.nan_color, opacity=value)
563
564 @property
565 def ramp(self) -> str: # numpydoc ignore=RT01
566 """Set the shape of the table ramp.
567
568 This attribute is only used when creating custom color maps and will
569 return ``None`` when a color map has been set with
570 :attr:`LookupTable.cmap`. This will clear any existing color map and
571 create new values for the lookup table when set.
572
573 This value may be either ``"s-curve"``, ``"linear"``, or ``"sqrt"``.
574
575 * The default is S-curve, which tails off gradually at either end.
576 * The equation used for ``"s-curve"`` is ``y = (sin((x - 1/2)*pi) +
577 1)/2``, For an S-curve greyscale ramp, you should set
578 :attr:`pyvista.LookupTable.n_values` to 402 (which is ``256*pi/2``) to provide
579 room for the tails of the ramp.
580
581 * The equation for the ``"linear"`` is simply ``y = x``.
582 * The equation for the ``"sqrt"`` is ``y = sqrt(x)``.
583
584 Examples
585 --------
586 Show the default s-curve ramp.
587
588 >>> import pyvista as pv
589 >>> lut = pv.LookupTable()
590 >>> lut.hue_range = (0.0, 0.33)
591 >>> lut.ramp = 's-curve'
592 >>> lut.plot()
593
594 Plot the linear ramp.
595
596 >>> import pyvista as pv
597 >>> lut = pv.LookupTable()
598 >>> lut.hue_range = (0.0, 0.33)
599 >>> lut.ramp = 'linear'
600 >>> lut.plot()
601
602 Plot the ``"sqrt"`` ramp.
603
604 >>> import pyvista as pv
605 >>> lut = pv.LookupTable()
606 >>> lut.hue_range = (0.0, 0.33)
607 >>> lut.ramp = 'sqrt'
608 >>> lut.plot()
609
610 """
611 return RAMP_MAP[self.GetRamp()]
612
613 @ramp.setter
614 def ramp(self, value: str):
615 try:
616 self.SetRamp(RAMP_MAP_INV[value])
617 except KeyError:
618 msg = f'`ramp` must be one of the following:\n{list(RAMP_MAP_INV.keys())}'
619 raise ValueError(msg)
620 self.rebuild()
621
622 @property
623 def above_range_color(self) -> Color | None: # numpydoc ignore=RT01
624 """Return or set the above range color.
625
626 Any values above :attr:`LookupTable.scalar_range` will be rendered with this
627 color.
628
629 Examples
630 --------
631 Enable the usage of the above range color.
632
633 >>> import pyvista as pv
634 >>> lut = pv.LookupTable()
635 >>> lut.above_range_color = 'blue'
636 >>> lut.plot()
637
638 Disable the usage of the above range color.
639
640 >>> import pyvista as pv
641 >>> lut = pv.LookupTable()
642 >>> lut.above_range_color = None
643 >>> lut.plot()
644
645 """
646 if self.GetUseAboveRangeColor():
647 return Color(self.GetAboveRangeColor())
648 return None
649
650 @above_range_color.setter
651 def above_range_color(self, value: bool | ColorLike | None):
652 if value is None or value is False:
653 self.SetUseAboveRangeColor(False)
654 elif value is True:
655 self.SetAboveRangeColor(*Color(pv.global_theme.above_range_color).float_rgba)
656 self.SetUseAboveRangeColor(True)
657 else:
658 self.SetAboveRangeColor(*Color(value).float_rgba)
659 self.SetUseAboveRangeColor(True)
660
661 @property
662 def above_range_opacity(self): # numpydoc ignore=RT01
663 """Return or set the above range opacity.
664
665 Examples
666 --------
667 Set the above range opacity to ``0.5``.
668
669 >>> import pyvista as pv
670 >>> lut = pv.LookupTable()
671 >>> lut.above_range_color = 'grey'
672 >>> lut.above_range_opacity = 0.5
673 >>> lut.plot()
674
675 """
676 color = self.above_range_color
677 return color.opacity # type: ignore[union-attr]
678
679 @above_range_opacity.setter
680 def above_range_opacity(self, value):
681 color = self.above_range_color
682 if color is None:
683 color = Color(pv.global_theme.above_range_color)
684 self.above_range_color = Color(color, opacity=value)
685
686 @property
687 def below_range_color(self) -> Color | None: # numpydoc ignore=RT01
688 """Return or set the below range color.
689
690 Any values below :attr:`LookupTable.scalar_range` will be rendered with this
691 color.
692
693 Examples
694 --------
695 Enable the usage of the below range color.
696
697 >>> import pyvista as pv
698 >>> lut = pv.LookupTable()
699 >>> lut.below_range_color = 'blue'
700 >>> lut.plot()
701
702 Disable the usage of the below range color.
703
704 >>> import pyvista as pv
705 >>> lut = pv.LookupTable()
706 >>> lut.below_range_color = None
707 >>> lut.plot()
708
709 """
710 if self.GetUseBelowRangeColor():
711 return Color(self.GetBelowRangeColor())
712 return None
713
714 @below_range_color.setter
715 def below_range_color(self, value: bool | ColorLike | None):
716 if value is None or value is False:
717 self.SetUseBelowRangeColor(False)
718 elif value is True:
719 self.SetBelowRangeColor(*Color(pv.global_theme.below_range_color).float_rgba)
720 self.SetUseBelowRangeColor(True)
721 else:
722 self.SetBelowRangeColor(*Color(value).float_rgba)
723 self.SetUseBelowRangeColor(True)
724
725 @property
726 def below_range_opacity(self): # numpydoc ignore=RT01
727 """Return or set the below range opacity.
728
729 Examples
730 --------
731 Set the below range opacity to ``0.5``.
732
733 >>> import pyvista as pv
734 >>> lut = pv.LookupTable()
735 >>> lut.below_range_color = 'grey'
736 >>> lut.below_range_opacity = 0.5
737 >>> lut.plot()
738
739 """
740 color = self.below_range_color
741 return color.opacity # type: ignore[union-attr]
742
743 @below_range_opacity.setter
744 def below_range_opacity(self, value):
745 color = self.below_range_color
746 if color is None:
747 color = Color(pv.global_theme.below_range_color)
748 self.below_range_color = Color(color, opacity=value)
749
750 @_deprecate_positional_args(allowed=['cmap', 'n_values'])
751 def apply_cmap(
752 self,
753 cmap: ColormapOptions,
754 n_values: int = 256,
755 flip: bool = False, # noqa: FBT001, FBT002
756 ):
757 """Assign a colormap to this lookup table.
758
759 This can be used instead of :attr:`LookupTable.cmap` when you need to
760 set the number of values at the same time as the color map.
761
762 Parameters
763 ----------
764 cmap : str, list, matplotlib.colors.Colormap
765 Colormap from Matplotlib, colorcet, or cmocean.
766
767 n_values : int, default: 256
768 Number of colors in the color map.
769
770 flip : bool, default: False
771 Flip direction of cmap. Most colormaps allow ``*_r`` suffix to do
772 this as well.
773
774 Examples
775 --------
776 Apply ``matplotlib``'s ``'cividis'`` color map.
777
778 >>> import pyvista as pv
779 >>> lut = pv.LookupTable()
780 >>> lut.apply_cmap('cividis', n_values=32)
781 >>> lut.plot()
782
783 """
784 if isinstance(cmap, list):
785 n_values = len(cmap)
786 cmap_obj = cmap if isinstance(cmap, mpl.colors.Colormap) else get_cmap_safe(cmap)
787 values = cmap_obj(np.linspace(0, 1, n_values)) * 255
788
789 if flip:
790 values = values[::-1]
791
792 self.values = values
793 self._values_manual = False
794
795 # reapply the opacity
796 opacity, interpolate, kind = self._opacity_parm
797 if opacity is not None:
798 self.apply_opacity(opacity=opacity, interpolate=interpolate, kind=kind)
799
800 self._cmap = cmap_obj
801
802 @_deprecate_positional_args(allowed=['opacity'])
803 def apply_opacity(self, opacity, interpolate: bool = True, kind: str = 'quadratic'): # noqa: FBT001, FBT002
804 """Assign custom opacity to this lookup table.
805
806 Parameters
807 ----------
808 opacity : float | array_like[float] | str
809 The opacity mapping to use. Can be a ``str`` name of a predefined
810 mapping including ``'linear'``, ``'geom'``, ``'sigmoid'``,
811 ``'sigmoid_3-10'``. Append an ``'_r'`` to any of those names to
812 reverse that mapping. This can also be a custom array or list of
813 values that will be interpolated across the ``n_color`` range for
814 user defined mappings. Values must be between 0 and 1.
815
816 If a ``float``, simply applies the same opacity across the entire
817 colormap and must be between 0 and 1. Note that ``int`` values are
818 interpreted as if they were floats.
819
820 interpolate : bool, default: True
821 Flag on whether or not to interpolate the opacity mapping for all
822 colors.
823
824 kind : str, default: 'quadratic'
825 The interpolation kind if ``interpolate`` is ``True`` and ``scipy``
826 is available. See :class:`scipy.interpolate.interp1d` for the
827 available interpolation kinds.
828
829 If ``scipy`` is not available, ``'linear'`` interpolation is used.
830
831 Examples
832 --------
833 Apply a user defined custom opacity to a lookup table and plot the
834 random hills example.
835
836 >>> import pyvista as pv
837 >>> from pyvista import examples
838 >>> mesh = examples.load_random_hills()
839 >>> lut = pv.LookupTable(cmap='viridis')
840 >>> lut.apply_opacity([1.0, 0.4, 0.0, 0.4, 0.9])
841 >>> lut.scalar_range = (
842 ... mesh.active_scalars.min(),
843 ... mesh.active_scalars.max(),
844 ... )
845 >>> pl = pv.Plotter()
846 >>> _ = pl.add_mesh(mesh, cmap=lut)
847 >>> pl.show()
848
849 """
850 if isinstance(opacity, (float, int)):
851 if not 0 <= opacity <= 1:
852 msg = f'Opacity must be between 0 and 1, got {opacity}'
853 raise ValueError(msg)
854 self.values[:, -1] = opacity * 255
855 elif len(opacity) == self.n_values:
856 # no interpolation is necessary
857 self.values[:, -1] = np.array(opacity)
858 else:
859 self.values[:, -1] = opacity_transfer_function(
860 opacity,
861 self.n_values,
862 interpolate=interpolate,
863 kind=kind,
864 )
865 self._opacity_parm = (opacity, interpolate, kind)
866
867 @property
868 def values(self) -> lookup_table_ndarray: # numpydoc ignore=RT01
869 """Return or set the lookup table values.
870
871 This attribute is used when creating a custom lookup table. The table
872 must be a RGBA array shaped ``(n, 4)``.
873
874 Examples
875 --------
876 Create a simple four value lookup table ranging from black to red.
877
878 >>> import pyvista as pv
879 >>> lut = pv.LookupTable()
880 >>> lut.values = [
881 ... [0, 0, 0, 255],
882 ... [85, 0, 0, 255],
883 ... [170, 0, 0, 255],
884 ... [255, 0, 0, 255],
885 ... ]
886 >>> lut.values
887 lookup_table_ndarray([[ 0, 0, 0, 255],
888 [ 85, 0, 0, 255],
889 [170, 0, 0, 255],
890 [255, 0, 0, 255]], dtype=uint8)
891 >>> lut.plot()
892
893 """
894 return lookup_table_ndarray(self.GetTable(), table=self)
895
896 @values.setter
897 def values(self, new_values):
898 self._values_manual = True
899 self._cmap = None
900 new_values = np.asarray(new_values).astype(np.uint8, copy=False)
901 self.SetTable(_vtk.numpy_to_vtk(new_values))
902
903 @property
904 def n_values(self) -> int: # numpydoc ignore=RT01
905 """Return or set the number of values in the lookup table.
906
907 Examples
908 --------
909 Plot the ``"reds"`` colormap with 10 values.
910
911 >>> import pyvista as pv
912 >>> lut = pv.LookupTable('reds')
913 >>> lut.n_values = 10
914 >>> lut.plot()
915
916 Plot the default colormap with 1024 values.
917
918 >>> import pyvista as pv
919 >>> lut = pv.LookupTable()
920 >>> lut.n_values = 1024
921 >>> lut.plot()
922
923 """
924 return self.GetNumberOfColors()
925
926 @n_values.setter
927 def n_values(self, value: int):
928 if self._cmap is not None:
929 self.apply_cmap(self._cmap, value)
930 self.SetNumberOfTableValues(value)
931 elif self._values_manual:
932 msg = (
933 'Number of values cannot be set when the values array has been manually set. '
934 'Reassign the values array if you wish to change the number of values.'
935 )
936 raise RuntimeError(msg)
937 else:
938 self.SetNumberOfColors(value)
939 self.ForceBuild()
940
941 @property
942 def annotations(self) -> dict[float, str]: # numpydoc ignore=RT01
943 """Return or set annotations.
944
945 Pass a dictionary of annotations. Keys are the float values in the
946 scalars range to annotate on the scalar bar and the values are the
947 string annotations.
948
949 Examples
950 --------
951 Assign annotations to the lookup table.
952
953 >>> import pyvista as pv
954 >>> lut = pv.LookupTable('magma')
955 >>> lut.annotations = {0: 'low', 0.5: 'medium', 1: 'high'}
956 >>> lut.plot()
957
958 """
959 vtk_values = self.GetAnnotatedValues()
960 if vtk_values is None:
961 return {} # type: ignore[unreachable]
962 n_items = (
963 vtk_values.GetSize()
964 if pv.vtk_version_info < (9, 6, 99) # < (9, 7, 0)
965 else vtk_values.GetCapacity() # type: ignore[attr-defined]
966 )
967 keys = [vtk_values.GetValue(ii).ToFloat() for ii in range(n_items)] # type: ignore[attr-defined]
968
969 vtk_str = self.GetAnnotations()
970 values = [str(vtk_str.GetValue(ii)) for ii in range(n_items)]
971 return dict(zip(keys, values, strict=True))
972
973 @annotations.setter
974 def annotations(self, values: dict[float, str] | None):
975 self.ResetAnnotations()
976 if values is not None:
977 for val, anno in values.items():
978 self.SetAnnotation(float(val), str(anno)) # type: ignore[call-overload]
979
980 @property
981 def _lookup_type(self) -> str:
982 """Return the lookup type."""
983 if self.cmap:
984 if hasattr(self.cmap, 'name'):
985 return f'{self.cmap.name}'
986 else: # pragma: no cover
987 return f'{self.cmap}'
988 elif self._values_manual:
989 return 'From values array'
990 else:
991 return 'PyVista Lookup Table'
992
993 def plot(self, **kwargs):
994 """Plot this lookup table.
995
996 Parameters
997 ----------
998 **kwargs : dict, optional
999 Optional keyword arguments passed to :func:`pyvista.Plotter.show`.
1000
1001 Examples
1002 --------
1003 Plot the ``"viridis"`` colormap with the below and above colors.
1004
1005 >>> import pyvista as pv
1006 >>> lut = pv.LookupTable('viridis', n_values=8)
1007 >>> lut.below_range_color = 'black'
1008 >>> lut.above_range_color = 'grey'
1009 >>> lut.nan_color = 'r'
1010 >>> lut.plot()
1011
1012 Plot only ``"blues"`` colormap.
1013
1014 >>> import pyvista as pv
1015 >>> lut = pv.LookupTable('blues', n_values=1024)
1016 >>> lut.plot()
1017
1018 """
1019 # need a trivial polydata for this
1020 mesh = pv.PolyData(np.zeros((2, 3)))
1021 mesh['Lookup Table'] = self.scalar_range
1022
1023 pl = pv.Plotter(window_size=[800, 230], off_screen=kwargs.pop('off_screen', None))
1024 actor = pl.add_mesh(mesh, scalars=None, show_scalar_bar=False)
1025 actor.mapper.lookup_table = self
1026 actor.visibility = False
1027
1028 scalar_bar_kwargs = {
1029 'color': 'k',
1030 'title': self._lookup_type + '\n',
1031 'outline': False,
1032 'title_font_size': 40,
1033 }
1034 label_level = 0
1035 if self.below_range_color:
1036 scalar_bar_kwargs['below_label'] = 'below'
1037 label_level = 1
1038 if self.above_range_color:
1039 scalar_bar_kwargs['above_label'] = 'above'
1040 label_level = 1
1041
1042 label_level += self._nan_color_set
1043
1044 scalar_bar = pl.add_scalar_bar(**scalar_bar_kwargs)
1045 scalar_bar.SetLookupTable(self)
1046 scalar_bar.SetMaximumNumberOfColors(self.n_values)
1047 scalar_bar.SetPosition(0.03, 0.1 + label_level * 0.1)
1048 scalar_bar.SetPosition2(0.95, 0.9 - label_level * 0.1)
1049 # scalar_bar.SetTextPad(-10)
1050 if self._nan_color_set and self.nan_opacity > 0:
1051 scalar_bar.SetDrawNanAnnotation(self._nan_color_set)
1052
1053 pl.background_color = kwargs.pop('background', 'w')
1054 pl.show(**kwargs)
1055
1056 def to_color_tf(self) -> _vtk.vtkColorTransferFunction:
1057 """Return the VTK color transfer function of this table.
1058
1059 Returns
1060 -------
1061 :vtk:`vtkColorTransferFunction`
1062 VTK color transfer function.
1063
1064 Examples
1065 --------
1066 >>> import pyvista as pv
1067 >>> lut = pv.LookupTable()
1068 >>> tf = lut.to_color_tf()
1069 >>> tf
1070 <vtkmodules.vtkRenderingCore.vtkColorTransferFunction(...) at ...>
1071
1072 """
1073 color_tf = _vtk.vtkColorTransferFunction()
1074 mn, mx = self.scalar_range
1075 for value in np.linspace(mn, mx, self.n_values):
1076 # Be sure to index the point by the value to map the scalar range
1077 color_tf.AddRGBPoint(value, *self.map_value(value, opacity=False))
1078 return color_tf
1079
1080 @_deprecate_positional_args
1081 def to_opacity_tf(
1082 self,
1083 clamping: bool = True, # noqa: FBT001, FBT002
1084 max_clip: float = 0.998,
1085 ) -> _vtk.vtkPiecewiseFunction:
1086 """Return the opacity transfer function of this table.
1087
1088 Parameters
1089 ----------
1090 clamping : bool, optional
1091 When zero range clamping is False, values returns 0.0 when a value is requested
1092 outside of the points specified.
1093
1094 .. versionadded:: 0.44
1095
1096 max_clip : float, default: 0.998
1097 The maximum value to clip the opacity to. This is useful for volume rendering
1098 to avoid the jarring effect of completely opaque values.
1099
1100 .. versionadded:: 0.45
1101
1102 Returns
1103 -------
1104 :vtk:`vtkPiecewiseFunction`
1105 Piecewise function of the opacity of this color table.
1106
1107 Examples
1108 --------
1109 >>> import pyvista as pv
1110 >>> lut = pv.LookupTable()
1111 >>> tf = lut.to_opacity_tf()
1112 >>> tf
1113 <vtkmodules.vtkCommonDataModel.vtkPiecewiseFunction(...) at ...>
1114
1115 """
1116 opacity_tf = _vtk.vtkPiecewiseFunction()
1117 opacity_tf.SetClamping(clamping)
1118 mn, mx = self.scalar_range
1119 for ii, value in enumerate(np.linspace(mn, mx, self.n_values)):
1120 alpha = self.values[ii, 3]
1121 # vtkPiecewiseFunction expects alphas between 0 and 1
1122 # our lookup table is between 0 and 255
1123 alpha = alpha / 255
1124 alpha = min(alpha, max_clip)
1125 opacity_tf.AddPoint(value, alpha)
1126 return opacity_tf
1127
1128 @_deprecate_positional_args(allowed=['value'])
1129 def map_value(
1130 self,
1131 value: float,
1132 opacity: bool = True, # noqa: FBT001, FBT002
1133 ) -> tuple[float, float, float] | tuple[float, float, float, float]:
1134 """Map a single value through the lookup table, returning an RBG(A) color.
1135
1136 Parameters
1137 ----------
1138 value : float
1139 Scalar value to map to an RGB(A) color.
1140
1141 opacity : bool, default: True
1142 Map the opacity as well.
1143
1144 Returns
1145 -------
1146 tuple
1147 Mapped RGB(A) color.
1148
1149 Examples
1150 --------
1151 >>> import pyvista as pv
1152 >>> lut = pv.LookupTable()
1153 >>> rgba_color = lut.map_value(0.0)
1154 >>> rgba_color
1155 (1.0, 0.0, 0.0, 1.0)
1156
1157 """
1158 color = [0.0, 0.0, 0.0]
1159 self.GetColor(value, color)
1160 if opacity:
1161 color.append(self.GetOpacity(value))
1162 return cast(
1163 'tuple[float, float, float] | tuple[float, float, float, float]',
1164 tuple(color),
1165 )
1166
1167 def __call__(self, value):
1168 """Implement a Matplotlib colormap-like call."""
1169 if isinstance(value, (int, float)):
1170 return self.map_value(value)
1171 else:
1172 try:
1173 return np.array([self.map_value(item) for item in value])
1174 except (TypeError, ValueError):
1175 msg = 'LookupTable __call__ expects a single value or an iterable.'
1176 raise TypeError(msg)