Plotter.add_scalar_bar

Plotter.add_scalar_bar(

title='',

mapper=None,

lookup_table=None,

cmap=None,

clim=None,

n_labels=5,

italic: bool = False,

bold: bool = False,

title_font_size=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,

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.

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.

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. 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.

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.

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.

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.

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

See Also

Customize Scalar Bars

Used In

Gallery Examples

Multi-Window Plot

Multi-Window Plot

2 uses