1PLCOLORBAR(3plplot)               PLplot API               PLCOLORBAR(3plplot)
2
3
4

NAME

6       plcolorbar - Plot color bar for image, shade or gradient plots
7

SYNOPSIS

9       plcolorbar(p_colorbar_width,  p_colorbar_height,  opt,  position, x, y,
10       x_length,  y_length,  bg_color,  bb_color,   bb_style,   low_cap_color,
11       high_cap_color,  cont_color,  cont_width, n_labels, label_opts, labels,
12       naxes, axis_opts, ticks, sub_ticks, n_values, values)
13

DESCRIPTION

15       Routine for creating a continuous color bar for image, shade, or gradi‐
16       ent  plots. (See pllegend(3plplot) for similar functionality for creat‐
17       ing legends with discrete elements). The arguments of  plcolorbar  pro‐
18       vide control over the location and size of the color bar as well as the
19       location and characteristics of the elements (most  of  which  are  op‐
20       tional)  within  that color bar.  The resulting color bar is clipped at
21       the boundaries of the current subpage.  (N.B.  the  adopted  coordinate
22       system  used for some of the parameters is defined in the documentation
23       of the position parameter.)
24
25       Redacted form: plcolorbar(p_colorbar_width, p_colorbar_height, opt, po‐
26       sition,   x,  y,  x_length,  y_length,  bg_color,  bb_color,  bb_style,
27       low_cap_color, high_cap_color, cont_color, cont_width, label_opts,  la‐
28       bels, axis_opts, ticks, sub_ticks, values)
29
30       This function is used in examples 16 and 33.
31

ARGUMENTS

33       p_colorbar_width (PLFLT_NC_SCALAR(3plplot), output)
34              Returned  value of the labelled and decorated color bar width in
35              adopted coordinates.
36
37       p_colorbar_height (PLFLT_NC_SCALAR(3plplot), output)
38              Returned value of the labelled and decorated color bar height in
39              adopted coordinates.
40
41       opt (PLINT(3plplot), input)
42              opt contains bits controlling the overall color bar.  The orien‐
43              tation (direction of the maximum value)  of  the  color  bar  is
44              specified  with  PL_ORIENT_RIGHT, PL_ORIENT_TOP, PL_ORIENT_LEFT,
45              or PL_ORIENT_BOTTOM.  If none of these bits are  specified,  the
46              default  orientation is toward the top if the colorbar is placed
47              on the left or right of the viewport or toward the right if  the
48              colorbar  is placed on the top or bottom of the viewport. If the
49              PL_COLORBAR_BACKGROUND bit  is  set,  plot  a  (semitransparent)
50              background  for  the  color bar. If the PL_COLORBAR_BOUNDING_BOX
51              bit is set, plot a bounding box for the color bar. The  type  of
52              color  bar  must  be  specified  with  one of PL_COLORBAR_IMAGE,
53              PL_COLORBAR_SHADE, or PL_COLORBAR_GRADIENT. If more than one  of
54              those  bits  is set only the first one in the above list is hon‐
55              ored. The position of the (optional) label/title can  be  speci‐
56              fied with PL_LABEL_RIGHT, PL_LABEL_TOP, PL_LABEL_LEFT, or PL_LA‐
57              BEL_BOTTOM.  If no label position bit is set then no label  will
58              be  drawn.  If  more than one of this list of bits is specified,
59              only the first one on the list  is  honored.  End-caps  for  the
60              color  bar  can  added  with  PL_COLORBAR_CAP_LOW  and PL_COLOR‐
61              BAR_CAP_HIGH. If a particular color bar cap option is not speci‐
62              fied  then  no cap will be drawn for that end. As a special case
63              for PL_COLORBAR_SHADE, the option PL_COLORBAR_SHADE_LABEL can be
64              specified.  If  this  option is provided then any tick marks and
65              tick labels will be placed at the  breaks  between  shaded  seg‐
66              ments. TODO: This should be expanded to support custom placement
67              of tick marks and tick labels at custom value locations for  any
68              color bar type.
69
70       position (PLINT(3plplot), input)
71              position contains bits which control the overall position of the
72              color bar and the definition of the adopted coordinates used for
73              positions  just  like what is done for the position argument for
74              pllegend(3plplot). However, note that the defaults for the posi‐
75              tion  bits  (see below) are different than the pllegend(3plplot)
76              case.  The  combination  of   the   PL_POSITION_LEFT,   PL_POSI‐
77              TION_RIGHT, PL_POSITION_TOP, PL_POSITION_BOTTOM, PL_POSITION_IN‐
78              SIDE, and PL_POSITION_OUTSIDE bits specifies one of the 16  pos‐
79              sible  standard  positions  (the  4 corners and centers of the 4
80              sides for both the inside and outside cases) of  the  color  bar
81              relative  to the adopted coordinate system. The corner positions
82              are specified by the  appropriate  combination  of  two  of  the
83              PL_POSITION_LEFT, PL_POSITION_RIGHT, PL_POSITION_TOP, and PL_PO‐
84              SITION_BOTTOM bits while the sides are  specified  by  a  single
85              value of one of those bits.  The adopted coordinates are normal‐
86              ized viewport coordinates if the PL_POSITION_VIEWPORT bit is set
87              or normalized subpage coordinates if the PL_POSITION_SUBPAGE bit
88              is set. Default position  bits:  If  none  of  PL_POSITION_LEFT,
89              PL_POSITION_RIGHT,  PL_POSITION_TOP,  or  PL_POSITION_BOTTOM are
90              set, then use PL_POSITION_RIGHT. If neither  of  PL_POSITION_IN‐
91              SIDE  or PL_POSITION_OUTSIDE is set, use PL_POSITION_OUTSIDE. If
92              neither of PL_POSITION_VIEWPORT or PL_POSITION_SUBPAGE  is  set,
93              use PL_POSITION_VIEWPORT.
94
95       x (PLFLT(3plplot), input)
96              X  offset  of the color bar position in adopted coordinates from
97              the specified standard position of the color bar.  For  positive
98              x,  the  direction  of motion away from the standard position is
99              inward/outward from the standard corner  positions  or  standard
100              left  or  right  positions  if  the  PL_POSITION_INSIDE/PL_POSI‐
101              TION_OUTSIDE bit is set in position.  For the  standard  top  or
102              bottom positions, the direction of motion is toward positive X.
103
104       y (PLFLT(3plplot), input)
105              Y  offset  of the color bar position in adopted coordinates from
106              the specified standard position of the color bar.  For  positive
107              y,  the  direction  of motion away from the standard position is
108              inward/outward from the standard corner  positions  or  standard
109              top  or  bottom  positions  if  the  PL_POSITION_INSIDE/PL_POSI‐
110              TION_OUTSIDE bit is set in position.  For the standard  left  or
111              right positions, the direction of motion is toward positive Y.
112
113       x_length (PLFLT(3plplot), input)
114              Length  of  the  body  of  the  color  bar in the X direction in
115              adopted coordinates.
116
117       y_length (PLFLT(3plplot), input)
118              Length of the body of the  color  bar  in  the  Y  direction  in
119              adopted coordinates.
120
121       bg_color (PLINT(3plplot), input)
122              The  cmap0  color of the background for the color bar (PL_COLOR‐
123              BAR_BACKGROUND).
124
125       bb_color (PLINT(3plplot), input)
126              The cmap0 color of the  bounding-box  line  for  the  color  bar
127              (PL_COLORBAR_BOUNDING_BOX).
128
129       bb_style (PLINT(3plplot), input)
130              The  pllsty(3plplot)  style number for the bounding-box line for
131              the color bar (PL_COLORBAR_BACKGROUND).
132
133       low_cap_color (PLFLT(3plplot), input)
134              The cmap1 color of the low-end color bar cap,  if  it  is  drawn
135              (PL_COLORBAR_CAP_LOW).
136
137       high_cap_color (PLFLT(3plplot), input)
138              The  cmap1  color  of the high-end color bar cap, if it is drawn
139              (PL_COLORBAR_CAP_HIGH).
140
141       cont_color (PLINT(3plplot), input)
142              The cmap0 contour color for  PL_COLORBAR_SHADE  plots.  This  is
143              passed  directly to plshades(3plplot), so it will be interpreted
144              according to the design of plshades(3plplot).
145
146       cont_width (PLFLT(3plplot), input)
147              Contour width for PL_COLORBAR_SHADE plots. This  is  passed  di‐
148              rectly to plshades(3plplot), so it will be interpreted according
149              to the design of plshades(3plplot).
150
151       n_labels (PLINT(3plplot), input)
152              Number of labels to place around the color bar.
153
154       label_opts (PLINT_VECTOR(3plplot), input)
155              A vector of options for each of n_labels labels.
156
157       labels (PLCHAR_MATRIX(3plplot), input)
158              A vector of n_labels UTF-8 character strings containing the  la‐
159              bels  for the color bar.  Ignored if no label position is speci‐
160              fied with one of  the  PL_COLORBAR_LABEL_RIGHT,  PL_COLORBAR_LA‐
161              BEL_TOP,   PL_COLORBAR_LABEL_LEFT,  or  PL_COLORBAR_LABEL_BOTTOM
162              bits in the corresponding label_opts field.
163
164       n_axes (PLINT(3plplot), input)
165              Number of axis definitions provided. This value must be  greater
166              than  0.  It  is typically 1 (numerical axis labels are provided
167              for one of the long edges of the  color  bar),  but  it  can  be
168              larger  if  multiple numerical axis labels for the long edges of
169              the color bar are desired.
170
171       axis_opts (PLCHAR_MATRIX(3plplot), input)
172              A vector of n_axes ascii character  strings  containing  options
173              (interpreted  as  for  plbox(3plplot))  for the color bar's axis
174              definitions.
175
176       ticks (PLFLT_VECTOR(3plplot), input)
177              A vector of n_axes values of the spacing of the major tick marks
178              (interpreted  as  for  plbox(3plplot))  for the color bar's axis
179              definitions.
180
181       sub_ticks (PLINT_VECTOR(3plplot), input)
182              A vector of n_axes values of the number of subticks (interpreted
183              as for plbox(3plplot)) for the color bar's axis definitions.
184
185       n_values (PLINT_VECTOR(3plplot), input)
186              A vector containing the number of elements in each of the n_axes
187              rows of the values matrix.
188
189       values (PLFLT_MATRIX(3plplot), input)
190              A matrix containing the numeric values for the data range repre‐
191              sented  by  the  color bar. For a row index of i_axis (where 0 <
192              i_axis < n_axes), the number of elements in the row is specified
193              by  n_values[i_axis]. For PL_COLORBAR_IMAGE and PL_COLORBAR_GRA‐
194              DIENT the number of elements is 2, and the corresponding row el‐
195              ements  of  the  values matrix are the minimum and maximum value
196              represented by the colorbar.  For PL_COLORBAR_SHADE, the  number
197              and  values of the elements of a row of the values matrix is in‐
198              terpreted the  same  as  the  nlevel  and  clevel  arguments  of
199              plshades(3plplot).
200
201

AUTHORS

203       Many  developers  (who  are  credited at http://plplot.org/credits.php)
204       have contributed to PLplot over its long history.
205

SEE ALSO

207       PLplot documentation at http://plplot.org/documentation.php.
208
209
210
211                                February, 2022             PLCOLORBAR(3plplot)
Impressum