{
  "cells": [
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "%matplotlib inline"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "# Customize Scalar Bars {#scalar_bar_example}\n\nWalk through of all the different capabilities of scalar bars and how a\nuser can customize scalar bars.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "import pyvista as pv\nfrom pyvista import examples"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "By default, when plotting a dataset with a scalar array, a scalar bar\nfor that array is added. To turn off this behavior, a user could specify\n`show_scalar_bar=False` when calling `.add_mesh()`. Let\\'s start with a\nsample dataset provide via PyVista to demonstrate the default behavior\nof scalar bar plotting:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# Load St Helens DEM and warp the topography\nmesh = examples.download_st_helens().warp_by_scalar()\n\n# First a default plot with jet colormap\np = pv.Plotter()\n# Add the data, use active scalar for coloring, and show the scalar bar\np.add_mesh(mesh)\n# Display the scene\np.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "We could also plot the scene with an interactive scalar bar to move\naround and place where we like by specifying passing keyword arguments\nto control the scalar bar via the `scalar_bar_args` parameter in\n`pyvista.Plotter.add_mesh`{.interpreted-text role=\"func\"}. The keyword\narguments to control the scalar bar are defined in\n`pyvista.Plotter.add_scalar_bar`{.interpreted-text role=\"func\"}.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# create dictionary of parameters to control scalar bar\nsargs = dict(interactive=True)  # Simply make the bar interactive\n\np = pv.Plotter(notebook=False)  # If in IPython, be sure to show the scene\np.add_mesh(mesh, scalar_bar_args=sargs)\np.show()\n# Remove from plotters so output is not produced in docs\npv.plotting.plotter._ALL_PLOTTERS.clear()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "![](../../images/gifs/scalar-bar-interactive.gif)\n\nOr manually define the scalar bar\\'s location:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# Set a custom position and size\nsargs = dict(height=0.25, vertical=True, position_x=0.05, position_y=0.05)\n\np = pv.Plotter()\np.add_mesh(mesh, scalar_bar_args=sargs)\np.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "The text properties of the scalar bar can also be controlled:\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# Controlling the text properties\nsargs = dict(\n    title_font_size=20,\n    label_font_size=16,\n    shadow=True,\n    n_labels=3,\n    italic=True,\n    fmt=\"%.1f\",\n    font_family=\"arial\",\n)\n\np = pv.Plotter()\np.add_mesh(mesh, scalar_bar_args=sargs)\np.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Labelling values outside of the scalar range\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "p = pv.Plotter()\np.add_mesh(mesh, clim=[1000, 2000], below_color='blue', above_color='red', scalar_bar_args=sargs)\np.show()"
      ]
    },
    {
      "cell_type": "markdown",
      "metadata": {},
      "source": [
        "Annotate values of interest using a dictionary. The key of the\ndictionary must be the value to annotate, and the value must be the\nstring label.\n"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "metadata": {
        "collapsed": false
      },
      "outputs": [],
      "source": [
        "# Make a dictionary for the annotations\nannotations = {\n    2300: \"High\",\n    805.3: \"Cutoff value\",\n}\n\np = pv.Plotter()\np.add_mesh(mesh, scalars='Elevation', annotations=annotations)\np.show()"
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "codemirror_mode": {
        "name": "ipython",
        "version": 3
      },
      "file_extension": ".py",
      "mimetype": "text/x-python",
      "name": "python",
      "nbconvert_exporter": "python",
      "pygments_lexer": "ipython3",
      "version": "3.12.2"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 0
}