1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
|
<html><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"><title>plshade: Shade individual region on the basis of value</title><link rel="stylesheet" type="text/css" href="stylesheet.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="index.html" title="Documentation of the PLplot plotting software"><link rel="up" href="API.html" title="Chapter 17. The Common API for PLplot"><link rel="prev" href="plshades.html" title="plshades: Shade regions on the basis of value"><link rel="next" href="plslabelfunc.html" title="plslabelfunc: Assign a function to use for generating custom axis labels"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">
<code class="function">plshade</code>: Shade individual region on the basis of value
</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="plshades.html">Prev</a> </td><th width="60%" align="center">Chapter 17. The Common API for PLplot</th><td width="20%" align="right"> <a accesskey="n" href="plslabelfunc.html">Next</a></td></tr></table><hr></div><div class="sect1"><div class="titlepage"><div><div><h4 class="title"><a name="plshade"></a>
<code class="function">plshade</code>: Shade individual region on the basis of value
</h4></div></div></div><p>
</p><div class="funcsynopsis"><table border="0" class="funcprototype-table" summary="Function synopsis" style="cellspacing: 0; cellpadding: 0;"><tr><td><code class="funcdef">
<b class="fsfunc">plshade</b>
(</code></td><td>
<var class="pdparam">a</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">nx</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">ny</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">defined</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">xmin</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">xmax</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">ymin</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">ymax</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">shade_min</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">shade_max</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">sh_cmap</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">sh_color</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">sh_width</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">min_color</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">min_width</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">max_color</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">max_width</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">fill</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">rectangular</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">pltr</var>
, </td></tr><tr><td> </td><td>
<var class="pdparam">pltr_data</var>
<code>)</code>;</td></tr></table><div class="funcprototype-spacer"> </div></div><p>
</p><p>Shade individual region on the basis of value. Use <a class="link" href="plshades.html" title="plshades: Shade regions on the basis of value"><code class="function">plshades</code></a>
if you want to shade a number of contiguous regions using continuous
colors. In particular the edge contours are treated properly in
<a class="link" href="plshades.html" title="plshades: Shade regions on the basis of value"><code class="function">plshades</code></a>. If you attempt to do contiguous regions with <a class="link" href="plshade.html" title="plshade: Shade individual region on the basis of value"><code class="function">plshade</code></a>
the contours at the edge of the shade are partially obliterated by
subsequent plots of contiguous shaded regions.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term">
<em class="parameter"><code>a</code></em>
(<code class="literal"><a class="link" href="c.html#PLFLT_MATRIX-type"><code class="function">PLFLT_MATRIX</code></a></code>, input)
</span></dt><dd><p>
A matrix containing function values to plot. Should have
dimensions of <em class="parameter"><code>nx</code></em> by <em class="parameter"><code>ny</code></em>.
</p></dd><dt><span class="term">
<em class="parameter"><code>nx</code></em>
(<code class="literal"><a class="link" href="c.html#PLINT-type"><code class="function">PLINT</code></a></code>, input)
</span></dt><dd><p>
First dimension of the matrix "a".
</p></dd><dt><span class="term">
<em class="parameter"><code>ny</code></em>
(<code class="literal"><a class="link" href="c.html#PLINT-type"><code class="function">PLINT</code></a></code>, input)
</span></dt><dd><p>
Second dimension of the matrix "a".
</p></dd><dt><span class="term">
<em class="parameter"><code>defined</code></em>
(<code class="literal"><a class="link" href="c.html#PLDEFINED_callback-type"><code class="function">PLDEFINED_callback</code></a></code>, input)
</span></dt><dd><p>Callback function specifying the region that should be plotted in
the shade plot. This function accepts x and y coordinates as input
arguments and must return 1 if the point is to be included in the
shade plot and 0 otherwise. If you want to plot the entire
shade plot (the usual case), this argument should be set to NULL.
</p></dd><dt><span class="term">
<em class="parameter"><code>xmin, xmax, ymin, ymax</code></em>
(<code class="literal"><a class="link" href="c.html#PLFLT-type"><code class="function">PLFLT</code></a></code>, input)
</span></dt><dd><p>See the discussion of <em class="parameter"><code>pltr</code></em>
below for how these arguments are used (only for the special case when
the callback function <em class="parameter"><code>pltr</code></em> is not
supplied).</p></dd><dt><span class="term">
<em class="parameter"><code>shade_min</code></em>
(<code class="literal"><a class="link" href="c.html#PLFLT-type"><code class="function">PLFLT</code></a></code>, input)
</span></dt><dd><p>
Defines the lower end of the interval to be shaded. If
shade_max ≤ shade_min, <a class="link" href="plshade.html" title="plshade: Shade individual region on the basis of value"><code class="function">plshade</code></a> does nothing.
</p></dd><dt><span class="term">
<em class="parameter"><code>shade_max</code></em>
(<code class="literal"><a class="link" href="c.html#PLFLT-type"><code class="function">PLFLT</code></a></code>, input)
</span></dt><dd><p>
Defines the upper end of the interval to be shaded. If
shade_max ≤ shade_min,
<a class="link" href="plshade.html" title="plshade: Shade individual region on the basis of value"><code class="function">plshade</code></a> does nothing.
</p></dd><dt><span class="term">
<em class="parameter"><code>sh_cmap</code></em>
(<code class="literal"><a class="link" href="c.html#PLINT-type"><code class="function">PLINT</code></a></code>, input)
</span></dt><dd><p>
Defines color map. If
<code class="literal"><em class="parameter"><code>sh_cmap</code></em>=0</code>, then
<code class="literal"><em class="parameter"><code>sh_color</code></em></code>
is interpreted as a cmap0 (integer) index. If
<code class="literal"><em class="parameter"><code>sh_cmap</code></em>=1</code>, then
<code class="literal"><em class="parameter"><code>sh_color</code></em></code>
is interpreted as a cmap1 argument in the range (0.0-1.0).
</p></dd><dt><span class="term">
<em class="parameter"><code>sh_color</code></em>
(<code class="literal"><a class="link" href="c.html#PLFLT-type"><code class="function">PLFLT</code></a></code>, input)
</span></dt><dd><p>
Defines color map index with integer value if cmap0 or
value in range (0.0-1.0) if cmap1.
</p></dd><dt><span class="term">
<em class="parameter"><code>sh_width</code></em>
(<code class="literal"><a class="link" href="c.html#PLFLT-type"><code class="function">PLFLT</code></a></code>, input)
</span></dt><dd><p>
Defines width used by the fill pattern.
</p></dd><dt><span class="term">
<em class="parameter"><code>min_color</code></em>
(<code class="literal"><a class="link" href="c.html#PLINT-type"><code class="function">PLINT</code></a></code>, input)
</span></dt><dd><p>
Defines pen color, width used by the boundary of shaded region.
The min values are used for the shade_min boundary, and the max
values are used on the shade_max boundary. Set color and width
to zero for no plotted boundaries.
</p></dd><dt><span class="term">
<em class="parameter"><code>min_width</code></em>
(<code class="literal"><a class="link" href="c.html#PLFLT-type"><code class="function">PLFLT</code></a></code>, input)
</span></dt><dd><p>
Defines pen color, width used by the boundary of shaded region.
The min values are used for the shade_min boundary, and the max
values are used on the shade_max boundary. Set color and width
to zero for no plotted boundaries.
</p></dd><dt><span class="term">
<em class="parameter"><code>max_color</code></em>
(<code class="literal"><a class="link" href="c.html#PLINT-type"><code class="function">PLINT</code></a></code>, input)
</span></dt><dd><p>
Defines pen color, width used by the boundary of shaded region.
The min values are used for the shade_min boundary, and the max
values are used on the shade_max boundary. Set color and width
to zero for no plotted boundaries.
</p></dd><dt><span class="term">
<em class="parameter"><code>max_width</code></em>
(<code class="literal"><a class="link" href="c.html#PLFLT-type"><code class="function">PLFLT</code></a></code>, input)
</span></dt><dd><p>
Defines pen color, width used by the boundary of shaded region.
The min values are used for the shade_min boundary, and the max
values are used on the shade_max boundary. Set color and width
to zero for no plotted boundaries.
</p></dd><dt><span class="term">
<em class="parameter"><code>fill</code></em>
(<code class="literal"><a class="link" href="c.html#PLFILL_callback-type"><code class="function">PLFILL_callback</code></a></code>, input)
</span></dt><dd><p>
Routine used to fill the region. Use <a class="link" href="plfill.html" title="plfill: Draw filled polygon"><code class="function">plfill</code></a>. Future version of
PLplot may have other fill routines.
</p></dd><dt><span class="term">
<em class="parameter"><code>rectangular</code></em>
(<code class="literal"><a class="link" href="c.html#PLBOOL-type"><code class="function">PLBOOL</code></a></code>, input)
</span></dt><dd><p>
Set <code class="literal">
<em class="parameter"><code>rectangular</code></em>
</code> to true
if rectangles map to rectangles after coordinate transformation
with <code class="literal"><em class="parameter"><code>pltrl</code></em></code>. Otherwise,
set <code class="literal"><em class="parameter"><code>rectangular</code></em></code> to false.
If <code class="literal"><em class="parameter"><code>rectangular</code></em></code>
is set to true, plshade tries to save time by
filling large rectangles. This optimization fails if
the coordinate transformation distorts the shape of rectangles.
For example a plot in polar coordinates has to have
<code class="literal"><em class="parameter"><code>rectangular</code></em></code>
set to false.
</p></dd><dt><span class="term">
<em class="parameter"><code>pltr</code></em>
(<code class="literal"><a class="link" href="c.html#PLTRANSFORM_callback-type"><code class="function">PLTRANSFORM_callback</code></a></code>, input)
</span></dt><dd><p> A callback function that defines the transformation
between the zero-based indices of the matrix
<code class="literal"><em class="parameter"><code>a</code></em></code> and world coordinates.
If <em class="parameter"><code>pltr</code></em> is not supplied (e.g., is set to NULL
in the C case), then the x indices of
<code class="literal"><em class="parameter"><code>a</code></em></code> are mapped to the range
<em class="parameter"><code>xmin</code></em> through <em class="parameter"><code>xmax</code></em> and
the y indices of <code class="literal"><em class="parameter"><code>a</code></em></code> are
mapped to the range <em class="parameter"><code>ymin</code></em> through
<em class="parameter"><code>ymax</code></em>.</p><p>For the C case, transformation functions are provided
in the PLplot library: <a class="link" href="pltr0.html" title="pltr0: Identity transformation for matrix index to world coordinate mapping"><code class="function">pltr0</code></a> for the identity mapping, and <a class="link" href="pltr1.html" title="pltr1: Linear interpolation for matrix index to world coordinate mapping using singly dimensioned coordinate arrays"><code class="function">pltr1</code></a>
and <a class="link" href="pltr2.html" title="pltr2: Linear interpolation for grid to world mapping using doubly dimensioned coordinate arrays (row-major order as per normal C 2d arrays)"><code class="function">pltr2</code></a> for arbitrary mappings respectively defined by vectors and
matrices. In addition, C callback routines for the transformation can
be supplied by the user such as the <code class="literal">mypltr</code> function
in <code class="filename">examples/c/x09c.c</code> which provides a general
linear transformation between index coordinates and world
coordinates.</p><p>For languages other than C you should consult <a class="xref" href="part_bindings.html" title="Part III. Supported computer languages">Part III, “ Supported computer languages ”</a> for the details concerning how
<a class="link" href="c.html#PLTRANSFORM_callback-type"><code class="function">PLTRANSFORM_callback</code></a> arguments are interfaced.
However, in general, a particular pattern of
callback-associated arguments such as a <code class="literal">tr</code> vector
with 6 elements; <code class="literal">xg</code> and <code class="literal">yg</code>
vectors; or <code class="literal">xg</code> and <code class="literal">yg</code> matrices
are respectively interfaced to a linear-transformation routine similar
to the above <code class="literal">mypltr</code> function; <a class="link" href="pltr1.html" title="pltr1: Linear interpolation for matrix index to world coordinate mapping using singly dimensioned coordinate arrays"><code class="function">pltr1</code></a>; and <a class="link" href="pltr2.html" title="pltr2: Linear interpolation for grid to world mapping using doubly dimensioned coordinate arrays (row-major order as per normal C 2d arrays)"><code class="function">pltr2</code></a>.
Furthermore, some of our more sophisticated bindings (see, e.g., <a class="xref" href="fortran.html" title="Chapter 10. Fortran Language">Chapter 10, <i>Fortran Language</i></a>) support native language callbacks for handling
index to world-coordinate transformations. Examples of these various
approaches are given in
<code class="filename">examples/<language>x09*</code>,
<code class="filename">examples/<language>x16*</code>,
<code class="filename">examples/<language>x20*</code>,
<code class="filename">examples/<language>x21*</code>, and
<code class="filename">examples/<language>x22*</code>, for all our
supported languages.</p></dd><dt><span class="term">
<em class="parameter"><code>pltr_data</code></em>
(<code class="literal"><a class="link" href="c.html#PLPointer-type"><code class="function">PLPointer</code></a></code>, input)
</span></dt><dd><p>
Extra parameter to help
pass information to <a class="link" href="pltr0.html" title="pltr0: Identity transformation for matrix index to world coordinate mapping"><code class="function">pltr0</code></a>, <a class="link" href="pltr1.html" title="pltr1: Linear interpolation for matrix index to world coordinate mapping using singly dimensioned coordinate arrays"><code class="function">pltr1</code></a>, <a class="link" href="pltr2.html" title="pltr2: Linear interpolation for grid to world mapping using doubly dimensioned coordinate arrays (row-major order as per normal C 2d arrays)"><code class="function">pltr2</code></a>, or whatever routine
that is externally supplied.
</p></dd></dl></div><p>
Redacted form:
</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><p>
General: <code class="function">plshade(a, defined, xmin, xmax, ymin, ymax, shade_min, shade_max, sh_cmap, sh_color, sh_width, min_color, min_width, max_color, max_width, fill, rectangular, pltr, pltr_data)</code>
</p></li></ul></div><p>
</p><p>
This function is used in example 15.
</p></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="plshades.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="API.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="plslabelfunc.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">
<code class="function">plshades</code>: Shade regions on the basis of value
</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">
<code class="function">plslabelfunc</code>: Assign a function to use for generating custom axis labels
</td></tr></table></div></body></html>
|
