`plcolorbar`: Plot color bar for image, shade or gradient plots
Prev | Chapter 18. The Common API for PLplot | Next

#### `plcolorbar`: Plot color bar for image, shade or gradient plots

`plcolorbar (` | p_colorbar_width,
| p_colorbar_height,
| opt,
| position,
| x,
| y,
| x_length,
| y_length,
| bg_color,
| bb_color,
| bb_style,
| low_cap_color,
| high_cap_color,
| cont_color,
| cont_width,
| n_labels,
| label_opts,
| labels,
| naxes,
| axis_opts,
| ticks,
| sub_ticks,
| n_values,
| values`)`;

Routine for creating a continuous color bar for image, shade, or gradient plots. (See `pllegend` for similar functionality for creating legends with discrete elements). The arguments of plcolorbar provide control over the location and size of the color bar as well as the location and characteristics of the elements (most of which are optional) within that color bar. The resulting color bar is clipped at the boundaries of the current subpage. (N.B. the adopted coordinate system used for some of the parameters is defined in the documentation of the ``position`` parameter.)

`p_colorbar_width` (``PLFLT_NC_SCALAR``, output)

  Returned value of the labelled and decorated color bar width in adopted coordinates.

`p_colorbar_height` (``PLFLT_NC_SCALAR``, output)

  Returned value of the labelled and decorated color bar height in adopted coordinates.

`opt` (``PLINT``, input)

  ``opt`` contains bits controlling the overall color bar. The orientation (direction of the maximum value) of the color bar is specified with `PL_ORIENT_RIGHT`, `PL_ORIENT_TOP`, `PL_ORIENT_LEFT`, or `PL_ORIENT_BOTTOM`. If none of these bits are specified, the default orientation is toward the top if the colorbar is placed on the left or right of the viewport or toward the right if the colorbar is placed on the top or bottom of the viewport. If the `PL_COLORBAR_BACKGROUND` bit is set, plot a (semitransparent) background for the color bar. If the `PL_COLORBAR_BOUNDING_BOX` bit is set, plot a bounding box for the color bar. The type of color bar must be specified with one of `PL_COLORBAR_IMAGE`, `PL_COLORBAR_SHADE`, or `PL_COLORBAR_GRADIENT`. If more than one of those bits is set only the first one in the above list is honored. The position of the (optional) label/title can be specified with `PL_LABEL_RIGHT`, `PL_LABEL_TOP`, `PL_LABEL_LEFT`, or `PL_LABEL_BOTTOM`. If no label position bit is set then no label will be drawn. If more than one of this list of bits is specified, only the first one on the list is honored. End-caps for the color bar can added with `PL_COLORBAR_CAP_LOW` and `PL_COLORBAR_CAP_HIGH`. If a particular color bar cap option is not specified then no cap will be drawn for that end. As a special case for `PL_COLORBAR_SHADE`, the option `PL_COLORBAR_SHADE_LABEL` can be specified. If this option is provided then any tick marks and tick labels will be placed at the breaks between shaded segments. TODO: This should be expanded to support custom placement of tick marks and tick labels at custom value locations for any color bar type.

`position` (``PLINT``, input)

  ``position`` contains bits which control the overall position of the color bar and the definition of the adopted coordinates used for positions just like what is done for the position argument for `pllegend`. However, note that the defaults for the position bits (see below) are different than the `pllegend` case. The combination of the `PL_POSITION_LEFT`, `PL_POSITION_RIGHT`, `PL_POSITION_TOP`, `PL_POSITION_BOTTOM`, `PL_POSITION_INSIDE`, and `PL_POSITION_OUTSIDE` bits specifies one of the 16 possible standard positions (the 4 corners and centers of the 4 sides for both the inside and outside cases) of the color bar relative to the adopted coordinate system. The corner positions are specified by the appropriate combination of two of the `PL_POSITION_LEFT`, `PL_POSITION_RIGHT`, `PL_POSITION_TOP`, and `PL_POSITION_BOTTOM` bits while the sides are specified by a single value of one of those bits. The adopted coordinates are normalized viewport coordinates if the `PL_POSITION_VIEWPORT` bit is set or normalized subpage coordinates if the `PL_POSITION_SUBPAGE` bit is set. Default position bits: If none of `PL_POSITION_LEFT`, `PL_POSITION_RIGHT`, `PL_POSITION_TOP`, or `PL_POSITION_BOTTOM` are set, then use `PL_POSITION_RIGHT`. If neither of `PL_POSITION_INSIDE` or `PL_POSITION_OUTSIDE` is set, use `PL_POSITION_OUTSIDE`. If neither of `PL_POSITION_VIEWPORT` or `PL_POSITION_SUBPAGE` is set, use `PL_POSITION_VIEWPORT`.

`x` (`PLFLT`, input)

  X offset of the color bar position in adopted coordinates from the specified standard position of the color bar. For positive x, the direction of motion away from the standard position is inward/outward from the standard corner positions or standard left or right positions if the `PL_POSITION_INSIDE`/`PL_POSITION_OUTSIDE` bit is set in ``position``. For the standard top or bottom positions, the direction of motion is toward positive X.

`y` (``PLFLT``, input)

  Y offset of the color bar position in adopted coordinates from the specified standard position of the color bar. For positive y, the direction of motion away from the standard position is inward/outward from the standard corner positions or standard top or bottom positions if the `PL_POSITION_INSIDE`/`PL_POSITION_OUTSIDE` bit is set in ``position``. For the standard left or right positions, the direction of motion is toward positive Y.

`x_length` (`PLFLT`, input)

  Length of the body of the color bar in the X direction in adopted coordinates.

`y_length` (``PLFLT``, input)

  Length of the body of the color bar in the Y direction in adopted coordinates.

`bg_color` (``PLINT``, input)

  The cmap0 color of the background for the color bar (`PL_COLORBAR_BACKGROUND`).

`bb_color` (``PLINT``, input)

  The cmap0 color of the bounding-box line for the color bar (`PL_COLORBAR_BOUNDING_BOX`).

`bb_style` (``PLINT``, input)

  The `pllsty` style number for the bounding-box line for the color bar (`PL_COLORBAR_BACKGROUND`).

`low_cap_color` (``PLFLT``, input)

  The cmap1 color of the low-end color bar cap, if it is drawn (`PL_COLORBAR_CAP_LOW`).

`high_cap_color` (``PLFLT``, input)

  The cmap1 color of the high-end color bar cap, if it is drawn (`PL_COLORBAR_CAP_HIGH`).

`cont_color` (``PLINT``, input)

  The cmap0 contour color for `PL_COLORBAR_SHADE` plots. This is passed directly to `plshades`, so it will be interpreted according to the design of `plshades`.

`cont_width` (``PLFLT``, input)

  Contour width for `PL_COLORBAR_SHADE` plots. This is passed directly to `plshades`, so it will be interpreted according to the design of `plshades`.

`n_labels` (``PLINT``, input)

  Number of labels to place around the color bar.

`label_opts` (``PLINT_VECTOR``, input)

  A vector of options for each of `n_labels` labels.

`labels` (``PLCHAR_MATRIX``, input)

  A vector of `n_labels` UTF-8 character strings containing the labels for the color bar. Ignored if no label position is specified with one of the `PL_COLORBAR_LABEL_RIGHT`, `PL_COLORBAR_LABEL_TOP`, `PL_COLORBAR_LABEL_LEFT`, or `PL_COLORBAR_LABEL_BOTTOM` bits in the corresponding label_opts field.

`n_axes` (``PLINT``, input)

  Number of axis definitions provided. This value must be greater than 0. It is typically 1 (numerical axis labels are provided for one of the long edges of the color bar), but it can be larger if multiple numerical axis labels for the long edges of the color bar are desired.

`axis_opts` (``PLCHAR_MATRIX``, input)

  A vector of `n_axes` ascii character strings containing options (interpreted as for `plbox`) for the color bar's axis definitions.

`ticks` (``PLFLT_VECTOR``, input)

  A vector of n_axes values of the spacing of the major tick marks (interpreted as for `plbox`) for the color bar's axis definitions.

`sub_ticks` (``PLINT_VECTOR``, input)

  A vector of n_axes values of the number of subticks (interpreted as for `plbox`) for the color bar's axis definitions.

`n_values` (``PLINT_VECTOR``, input)

  A vector containing the number of elements in each of the ``n_axes`` rows of the ``values`` matrix.

`values` (``PLFLT_MATRIX``, input)

  A matrix containing the numeric values for the data range represented by the color bar. For a row index of ``i_axis`` (where 0 < ``i_axis`` < ``n_axes``), the number of elements in the row is specified by ``n_values``[``i_axis``]. For `PL_COLORBAR_IMAGE` and `PL_COLORBAR_GRADIENT` the number of elements is 2, and the corresponding row elements of the ``values`` matrix are the minimum and maximum value represented by the colorbar. For `PL_COLORBAR_SHADE`, the number and values of the elements of a row of the ``values`` matrix is interpreted the same as the ``nlevel`` and ``clevel`` arguments of `plshades`.

Redacted form: `plcolorbar(p_colorbar_width, p_colorbar_height, opt, position, x, y, x_length, y_length, bg_color, bb_color, bb_style, low_cap_color, high_cap_color, cont_color, cont_width, label_opts, labels, axis_opts, ticks, sub_ticks, values)`

This function is used in examples 16 and 33.

Prev | Up | Next
`plcol1`: Set color, cmap1 | Home | `plconfigtime`: Configure the transformation between continuous and broken-down time for the current stream