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
20       optional) 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,
26       position,  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,
28       labels, 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
57              PL_LABEL_BOTTOM.  If no label position bit is set then no  label
58              will  be  drawn. If more than one of this list of bits is speci‐
59              fied, only the first one on the list is  honored.  End-caps  for
60              the  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_POSI‐
78              TION_INSIDE, and PL_POSITION_OUTSIDE bits specifies one  of  the
79              16 possible standard positions (the 4 corners and centers of the
80              4 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
84              PL_POSITION_BOTTOM bits while the sides are specified by a  sin‐
85              gle  value  of  one  of those bits.  The adopted coordinates are
86              normalized viewport coordinates if the PL_POSITION_VIEWPORT  bit
87              is set or normalized subpage coordinates if the PL_POSITION_SUB‐
88              PAGE bit is set. Default position  bits:  If  none  of  PL_POSI‐
89              TION_LEFT,   PL_POSITION_RIGHT,   PL_POSITION_TOP,  or  PL_POSI‐
90              TION_BOTTOM are set, then use PL_POSITION_RIGHT. If  neither  of
91              PL_POSITION_INSIDE  or  PL_POSITION_OUTSIDE is set, use PL_POSI‐
92              TION_OUTSIDE. If neither  of  PL_POSITION_VIEWPORT  or  PL_POSI‐
93              TION_SUBPAGE is set, 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
148              directly to plshades(3plplot), so it will be interpreted accord‐
149              ing 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
159              labels for the color bar.  Ignored if no label position is spec‐
160              ified  with  one  of  the   PL_COLORBAR_LABEL_RIGHT,   PL_COLOR‐
161              BAR_LABEL_TOP, PL_COLORBAR_LABEL_LEFT, or PL_COLORBAR_LABEL_BOT‐
162              TOM 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
195              elements  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
198              interpreted 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                                November, 2019             PLCOLORBAR(3plplot)
Impressum