plshades: Shade regions on the basis of value

`plshades`: Shade regions on the basis of value
Prev | Chapter 18. The Common API for PLplot | Next

#### `plshades`: Shade regions on the basis of value

`plshades (` | a ,
| nx ,
| ny ,
| defined ,
| xmin ,
| xmax ,
| ymin ,
| ymax ,
| clevel ,
| nlevel ,
| fill_width ,
| cont_color ,
| cont_width ,
| fill ,
| rectangular ,
| pltr ,
| pltr_data `)`;

Shade regions on the basis of value. This is the high-level routine for making continuous color shaded plots with cmap1 while `plshade` should be used to plot individual shaded regions using either cmap0 or cmap1. `examples/;<language>/x16*` shows how to use `plshades` for each of our supported languages.

`a` (``PLFLT_MATRIX``, input)

  A matrix containing function values to plot. Should have dimensions of `nx` by `ny`.

`nx` (``PLINT``, input)

  First dimension of matrix "a".

`ny` (``PLINT``, input)

  Second dimension of matrix "a".

`defined` (``PLDEFINED_callback``, input)

  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.

`xmin, xmax, ymin, ymax` (``PLFLT``, input)

  See the discussion of `pltr` below for how these arguments are used (only for the special case when the callback function `pltr` is not supplied).

`clevel` (``PLFLT_VECTOR``, input)

  A vector containing the data levels corresponding to the edges of each shaded region that will be plotted by this function. To work properly the levels should be monotonic.

`nlevel` (``PLINT``, input)

  Number of shades plus 1 (i.e., the number of shade edge values in ``clevel``).

`fill_width` (``PLFLT``, input)

  Defines the line width used by the fill pattern.

`cont_color` (``PLINT``, input)

  Defines cmap0 pen color used for contours defining edges of shaded regions. The pen color is only temporary set for the contour drawing. Set this value to zero or less if no shade edge contours are wanted.

`cont_width` (``PLFLT``, input)

  Defines line width used for contours defining edges of shaded regions. This value may not be honored by all drivers. The pen width is only temporary set for the contour drawing. Set this value to zero or less if no shade edge contours are wanted.

`fill` (``PLFILL_callback``, input)

  Callback routine used to fill the region. Use `plfill` for this purpose.

`rectangular` (``PLBOOL``, input)

  Set ``rectangular`` to true if rectangles map to rectangles after coordinate transformation with ``pltrl``. Otherwise, set ``rectangular`` to false. If ``rectangular`` 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 ``rectangular`` set to false.

`pltr` (``PLTRANSFORM_callback``, input)

  A callback function that defines the transformation between the zero-based indices of the matrix ``a`` and world coordinates. If `pltr` is not supplied (e.g., is set to NULL in the C case), then the x indices of ``a`` are mapped to the range `xmin` through `xmax` and the y indices of ``a`` are mapped to the range `ymin` through `ymax`.

  For the C case, transformation functions are provided in the PLplot library: `pltr0` for the identity mapping, and `pltr1` and `pltr2` 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 `mypltr` function in `examples/c/x09c.c` which provides a general linear transformation between index coordinates and world coordinates.

  For languages other than C you should consult Part III, “ Supported computer languages ” for the details concerning how `PLTRANSFORM_callback` arguments are interfaced. However, in general, a particular pattern of callback-associated arguments such as a `tr` vector with 6 elements; `xg` and `yg` vectors; or `xg` and `yg` matrices are respectively interfaced to a linear-transformation routine similar to the above `mypltr` function; `pltr1`; and `pltr2`. Furthermore, some of our more sophisticated bindings (see, e.g., Chapter 10, Fortran Language) support native language callbacks for handling index to world-coordinate transformations. Examples of these various approaches are given in `examples/<language>x09*`, `examples/<language>x16*`, `examples/<language>x20*`, `examples/<language>x21*`, and `examples/<language>x22*`, for all our supported languages.

`pltr_data` (``PLPointer``, input)

  Extra parameter to help pass information to `pltr0`, `pltr1`, `pltr2`, or whatever routine that is externally supplied.

Redacted form:

- General: `plshades(a, defined, xmin, xmax, ymin, ymax, clevel, fill_width, cont_color, cont_width, fill, rectangular, pltr, pltr_data)`

- Perl/PDL: `plshades(a, xmin, xmax, ymin, ymax, clevel, fill_width, cont_color, cont_width, fill, rectangular, defined, pltr, pltr_data)`

This function is used in examples 16, 21, and 22.

Prev | Up | Next
`plsfont`: Set family, style and weight of the current font | Home | `plshade`: Shade individual region on the basis of value