Plotter.add_scalar_bar

Plotter.add_scalar_bar(

title='',

*,

mapper=None,

lookup_table=None,

cmap=None,

clim=None,

n_labels=5,

tick_locations=None,

italic: bool = False,

bold: bool = False,

title_font_size=None,

title_pad=None,

label_font_size=None,

color=None,

font_family=None,

shadow: bool = False,

width=None,

height=None,

position_x=None,

position_y=None,

vertical=None,

stacking_gap: float | None = None,

rotate_title: bool | None = None,

interactive=None,

fmt=None,

use_opacity: bool = True,

outline: bool = False,

nan_annotation: bool = False,

below_label=None,

above_label=None,

background_color=None,

n_colors=None,

fill: bool = False,

render: bool = False,

theme=None,

unconstrained_font_size: bool = False,

unique_bar: bool = False,

)

Create a scalar bar.

Uses the ranges as set by the last input mesh or, alternatively, the ones set by clim, mapper, or lookup_table.

Parameters:

titlestr, default: “”

Title of the scalar bar. Default is rendered as an empty title.

mappervtkMapper, optional

Mapper used for the scalar bar. Defaults to the last mapper created by the plotter if neither mapper, lookup_table, or cmap is provided. Raises ValueError if more than one of mapper, lookup_table, or cmap is provided.

lookup_tablevtkLookupTable, optional

Lookup table used for the scalar bar. Raises ValueError if more than one of mapper, lookup_table, or cmap is provided.

Added in version 0.49.

cmapstr | list, optional

Colormap used for the scalar bar. Raises ValueError if more than one of mapper, lookup_table, or cmap is provided.

Added in version 0.49.

climsequence[float], optional

Two item range for the scalar bar. Only used if cmap is specified.

Added in version 0.49.

n_labelsint, default: 5

Number of labels to use for the scalar bar.

tick_locationssequence[float], optional

Scalar values to label, instead of n_labels evenly spaced values. The label text comes from fmt. Values outside the scalar range are not drawn.

Added in version 0.50.

italicbool, default: False

Italicises title and bar labels.

boldbool, default: False

Bolds title and bar labels.

title_font_sizefloat, optional

Sets the size of the title font. Defaults to None and is sized according to pyvista.plotting.themes.Theme.font.

title_padfloat, optional

Space between the title and the tick labels, as a multiple of the title font size. Defaults to None and is sized according to pyvista.plotting.themes.Theme.colorbar_horizontal or pyvista.plotting.themes.Theme.colorbar_vertical. Has no effect when the font size is constrained, or on a box given a size of its own, which pads its title with whatever height it has spare.

Added in version 0.50.

label_font_sizefloat, optional

Sets the size of the title font. Defaults to None and is sized according to pyvista.plotting.themes.Theme.font.

colorColorLike, optional

Either a string, rgb list, or hex color string. Default set by pyvista.plotting.themes.Theme.font. Can be in one of the following formats:

• color='white'

• color='w'

• color=[1.0, 1.0, 1.0]

• color='#FFFFFF'

font_family{‘courier’, ‘times’, ‘arial’}

Font family. Default is set by pyvista.plotting.themes.Theme.font.

shadowbool, default: False

Adds a black shadow to the text.

widthfloat, optional

The percentage (0 to 1) width of the window for the colorbar. Giving a width, or a height, keeps a box drawn by fill or outline exactly that size rather than growing it around the text, though only a height holds a horizontal box whose text is not unconstrained_font_size. Default set by pyvista.plotting.themes.Theme.colorbar_vertical or pyvista.plotting.themes.Theme.colorbar_horizontal depending on the value of vertical.

heightfloat, optional

The percentage (0 to 1) height of the window for the colorbar. Default set by pyvista.plotting.themes.Theme.colorbar_vertical or pyvista.plotting.themes.Theme.colorbar_horizontal depending on the value of vertical.

position_xfloat, optional

The percentage (0 to 1) along the window’s horizontal direction to place the bottom left corner of the colorbar. Default set by pyvista.plotting.themes.Theme.colorbar_vertical or pyvista.plotting.themes.Theme.colorbar_horizontal depending on the value of vertical.

position_yfloat, optional

The percentage (0 to 1) along the window’s vertical direction to place the bottom left corner of the colorbar. Default set by pyvista.plotting.themes.Theme.colorbar_vertical or pyvista.plotting.themes.Theme.colorbar_horizontal depending on the value of vertical.

verticalbool, optional

Use vertical or horizontal scalar bar. Default set by pyvista.plotting.themes.Theme.colorbar_orientation.

stacking_gapfloat, optional

Distance between stacked scalar bars, as a fraction of the window. Defaults to None, which spaces them as tightly as their titles and tick labels allow, and is taken from pyvista.plotting.themes.Theme.colorbar_horizontal or pyvista.plotting.themes.Theme.colorbar_vertical. A value small enough to overlap is used as given. Has no effect when the font size is constrained.

Added in version 0.50.

rotate_titlebool, optional

Turn the title alongside the bar instead of drawing it across the end, so that stacked bars sit closer together. Defaults to None and is taken from pyvista.plotting.themes._VerticalColorbarConfig.rotate_title. Applies to vertical bars only. Requires VTK 9.4.0 or newer, and has no effect when the font size is constrained.

Added in version 0.50.

interactivebool, optional

Use a widget to control the size and location of the scalar bar. Default set by pyvista.plotting.themes.Theme.interactive.

fmtstr, optional

printf format for labels. Default set by pyvista.plotting.themes.Theme.font.

use_opacitybool, default: True

Optionally display the opacity mapping on the scalar bar.

outlinebool, default: False

Optionally outline the scalar bar to make opacity mappings more obvious.

nan_annotationbool, default: False

Annotate the NaN color.

below_labelstr, optional

String annotation for values below the scalars range.

above_labelstr, optional

String annotation for values above the scalars range.

background_colorColorLike, optional

The color used for the background in RGB format. Only drawn when fill is True.

n_colorsint, optional

The maximum number of color displayed in the scalar bar.

fillbool, default: False

Draw a filled box behind the scalar bar with the background_color.

renderbool, default: False

Force a render when True.

themepyvista.plotting.themes.Theme, optional

Plot-specific theme. By default, calling from the Plotter, will use the plotter theme. Setting to None will use the global theme.

unconstrained_font_sizebool, default: False

Whether the font size of title and labels is unconstrained. When it is constrained, the size of the scalar bar will constrain the font size. When it is not, the size of the font will always be respected. Using custom labels will force this to be True. A box drawn around a horizontal bar sizes the text itself unless this is True.

Added in version 0.44.0.

unique_barbool, default: False

Whether to create a scalar bar which is unique to the subplot. If True, the scalar bar will be created with a unique key which is not shared with other subplots, even if the input title is the same.

Note

Scalar bars are managed by a dictionary with the title as the key. By default, if a scalar bar with the same title already exists, the scalar bar will be shared. If unique_bar is True, the scalar bar will be created with a unique key which is the title suffixed with _UNIQUE_ID_{active_renderer_index}, where active_renderer_index is the index of the active renderer in the plotter. This allows for multiple scalar bars with the same title to be created across different subplots.

Added in version 0.48.0.

Returns:

vtkScalarBarActor

Scalar bar actor.

Notes

Setting title_font_size, or label_font_size disables automatic font sizing for both the title and label. A box drawn around a horizontal bar sizes the text itself, so the box is laid out to keep the text at the size asked for, or one size larger where two sizes measure the same height; a box given too small a height, or too narrow for its text, shrinks the text to fit.

The mapper, lookup_table, and cmap parameters can be used to set a custom color map for the scalar bar; otherwise, the bar will default to the last mapper created by the plotter - for example, when a mesh with scalars is added by pyvista.Plotter.add_mesh(). See examples. Only one parameter can be used to set the color mapping, so ValueError will be raised if more than one of mapper, lookup_table, or cmap is provided.

Examples

Download Python source code | Download Jupyter notebook

Add a custom interactive scalar bar that is horizontal, has an outline, and has a custom formatting.

>>> import pyvista as pv
>>> sphere = pv.Sphere()
>>> sphere['Data'] = sphere.points[:, 2]
>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(sphere, show_scalar_bar=False)
>>> _ = pl.add_scalar_bar(
...     'Data',
...     interactive=True,
...     vertical=False,
...     title_font_size=35,
...     label_font_size=30,
...     outline=True,
...     fmt='%10.5f',
... )
>>> pl.show()

Static Scene

Interactive Scene

Add a custom scalar bar without (or before) plotting data using the cmap and clim parameters:

>>> import pyvista as pv
>>> pl = pv.Plotter()
>>> _ = pl.add_scalar_bar('Height', cmap='viridis', clim=(-2, 2))
>>> pl.show()

Static Scene

Interactive Scene

Stack three scalar bars with titles of different lengths. They are spaced so that nothing overlaps.

>>> import pyvista as pv
>>> sphere = pv.Sphere()
>>> sphere['Data'] = sphere.points[:, 2]
>>> titles = ['A bit long', 'Short', 'Super duper long']
>>> pl = pv.Plotter()
>>> pl.theme.colorbar_vertical.position_x = 0.75
>>> _ = pl.add_mesh(sphere, show_scalar_bar=False)
>>> for title in titles:
...     _ = pl.add_scalar_bar(
...         title,
...         vertical=True,
...         title_font_size=30,
...         label_font_size=30,
...         mapper=pl.mapper,
...     )
>>> pl.show()

Static Scene

Interactive Scene

Turn the titles alongside the bars to stack them closer together.

>>> pl = pv.Plotter()
>>> pl.theme.colorbar_vertical.position_x = 0.75
>>> _ = pl.add_mesh(sphere, show_scalar_bar=False)
>>> for title in titles:
...     _ = pl.add_scalar_bar(
...         title,
...         vertical=True,
...         rotate_title=True,
...         title_font_size=30,
...         label_font_size=30,
...         mapper=pl.mapper,
...     )
>>> pl.show()

Static Scene

Interactive Scene

Space the bars evenly instead, whatever their titles measure.

>>> pl = pv.Plotter()
>>> pl.theme.colorbar_vertical.position_x = 0.75
>>> _ = pl.add_mesh(sphere, show_scalar_bar=False)
>>> for title in titles:
...     _ = pl.add_scalar_bar(
...         title,
...         vertical=True,
...         stacking_gap=0.2,
...         title_font_size=30,
...         label_font_size=30,
...         mapper=pl.mapper,
...     )
>>> pl.show()

Static Scene

Interactive Scene

A box drawn around a bar grows to hold the title and the tick labels, as long as the bar was not given a size of its own.

>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(sphere, show_scalar_bar=False)
>>> _ = pl.add_scalar_bar(
...     'Elevation (m)',
...     vertical=True,
...     outline=True,
...     title_font_size=30,
...     label_font_size=30,
...     mapper=pl.mapper,
... )
>>> pl.show()

Static Scene

Interactive Scene

A horizontal bar’s ramp and tick labels are laid out inside its box, and the box grows to hold the padding the title is given.

>>> pl = pv.Plotter()
>>> _ = pl.add_mesh(sphere, show_scalar_bar=False)
>>> _ = pl.add_scalar_bar(
...     'Elevation (m)',
...     vertical=False,
...     outline=True,
...     title_font_size=30,
...     label_font_size=30,
...     mapper=pl.mapper,
... )
>>> pl.show()

Static Scene

Interactive Scene

See Also

Customize Scalar Bars

Used In

Gallery Examples

Multi-Window Plot

Multi-Window Plot

2 uses