1PLCOLORBAR(3plplot) PLplot API PLCOLORBAR(3plplot)
2
6 plcolorbar - Plot color bar for image, shade or gradient plots
7
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
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 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 This function is used in examples 16 and 33.
31
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 p_colorbar_height (PLFLT_NC_SCALAR(3plplot), output)
38 Returned value of the labelled and decorated color bar height in
39 adopted coordinates.
40 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 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 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 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 x_length (PLFLT(3plplot), input)
114 Length of the body of the color bar in the X direction in
115 adopted coordinates.
116 y_length (PLFLT(3plplot), input)
118 Length of the body of the color bar in the Y direction in
119 adopted coordinates.
120 bg_color (PLINT(3plplot), input)
122 The cmap0 color of the background for the color bar (PL_COLOR‐
123 BAR_BACKGROUND).
124 bb_color (PLINT(3plplot), input)
126 The cmap0 color of the bounding-box line for the color bar
127 (PL_COLORBAR_BOUNDING_BOX).
128 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 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 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 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 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 n_labels (PLINT(3plplot), input)
152 Number of labels to place around the color bar.
153 label_opts (PLINT_VECTOR(3plplot), input)
155 A vector of options for each of n_labels labels.
156 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 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 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 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 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 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 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
203 Many developers (who are credited at http://plplot.org/credits.php)
204 have contributed to PLplot over its long history.
205
207 PLplot documentation at http://plplot.org/documentation.php.
208 January, 2021 PLCOLORBAR(3plplot)