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(3plplot) 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.)
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.
- p_colorbar_width
(PLFLT_NC_SCALAR(3plplot), output)
- Returned value of the labelled and decorated color bar width in adopted
coordinates.
- p_colorbar_height
(PLFLT_NC_SCALAR(3plplot), output)
- Returned value of the labelled and decorated color bar height in adopted
coordinates.
- opt
(PLINT(3plplot), 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(3plplot), 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(3plplot). However, note that the defaults for the position
bits (see below) are different than the pllegend(3plplot) 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(3plplot),
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(3plplot),
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(3plplot), input)
- Length of the body of the color bar in the X direction in adopted
coordinates.
- y_length
(PLFLT(3plplot), input)
- Length of the body of the color bar in the Y direction in adopted
coordinates.
- bg_color
(PLINT(3plplot), input)
- The cmap0 color of the background for the color bar
(PL_COLORBAR_BACKGROUND).
- bb_color
(PLINT(3plplot), input)
- The cmap0 color of the bounding-box line for the color bar
(PL_COLORBAR_BOUNDING_BOX).
- bb_style
(PLINT(3plplot), input)
- The pllsty(3plplot) style number for the bounding-box line for the
color bar (PL_COLORBAR_BACKGROUND).
- low_cap_color
(PLFLT(3plplot), input)
- The cmap1 color of the low-end color bar cap, if it is drawn
(PL_COLORBAR_CAP_LOW).
- high_cap_color
(PLFLT(3plplot), input)
- The cmap1 color of the high-end color bar cap, if it is drawn
(PL_COLORBAR_CAP_HIGH).
- cont_color
(PLINT(3plplot), input)
- The cmap0 contour color for PL_COLORBAR_SHADE plots. This is passed
directly to plshades(3plplot), so it will be interpreted according
to the design of plshades(3plplot).
- cont_width
(PLFLT(3plplot), input)
- Contour width for PL_COLORBAR_SHADE plots. This is passed directly to
plshades(3plplot), so it will be interpreted according to the
design of plshades(3plplot).
- n_labels
(PLINT(3plplot), input)
- Number of labels to place around the color bar.
- label_opts
(PLINT_VECTOR(3plplot), input)
- A vector of options for each of n_labels labels.
- labels
(PLCHAR_MATRIX(3plplot), 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(3plplot), 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(3plplot), input)
- A vector of n_axes ascii character strings containing options
(interpreted as for plbox(3plplot)) for the color bar's axis
definitions.
- ticks
(PLFLT_VECTOR(3plplot), input)
- A vector of n_axes values of the spacing of the major tick marks
(interpreted as for plbox(3plplot)) for the color bar's axis
definitions.
- sub_ticks
(PLINT_VECTOR(3plplot), input)
- A vector of n_axes values of the number of subticks (interpreted as for
plbox(3plplot)) for the color bar's axis definitions.
- n_values
(PLINT_VECTOR(3plplot), input)
- A vector containing the number of elements in each of the n_axes
rows of the values matrix.
- values
(PLFLT_MATRIX(3plplot), 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(3plplot).
Many developers (who are credited at
http://plplot.org/credits.php) have contributed to PLplot over its long
history.
PLplot documentation at http://plplot.org/documentation.php.