PLSHADE(3plplot)

📦
version 5.15.0 · 12 versions
, in ubuntu stonking

💅 PLSHADE — the PLplot API, bestie edition ✨

okay so real talk, this page is from the PLplot API manual (that's the manual name, iykyk), and it's all about PLSHADE(3plplot) — one function, so many arguments, and honestly? It ate. Let's get into it 🎀

✨ NAME ✨

plshade — shade a single region based on its value. That's it. That's the vibe. 💖

🌸 SYNOPSIS 🌸

plshade(a, nx, ny, 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)

🦋 DESCRIPTION 🦋

So you wanna shade one individual region on the basis of value? Periodt, that's literally what this does. 💅

But listen — if you want to shade a bunch of contiguous regions using continuous colors, you want plshades(3plplot) instead. Fr fr. In particular, the edge contours are treated properly in plshades(3plplot). And here's the tea: if you try to do contiguous regions with plshade(3plplot), the contours at the edge of the shade get partially obliterated by subsequent plots of contiguous shaded regions. 😭 Not a cute look, so just use plshades for that.

Redacted form (the glow-up version, lowkey): General: 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)

Also bestie, this function is used in example 15. Go look at it. 👑

🌈 ARGUMENTS 🌈

  • a (PLFLT_MATRIX(3plplot), input) — a matrix holding the function values you wanna plot. It should have dimensions of nx by ny. Your main character matrix. 🌟
  • nx (PLINT(3plplot), input) — the first dimension of the matrix a.
  • ny (PLINT(3plplot), input) — the second dimension of the matrix a.
  • defined (PLDEFINED_callback(3plplot), input) — a callback function that specifies which region should be plotted in the shade plot. It takes 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, and honestly the chillest one), set this argument to NULL. 🙈
  • xmin, xmax, ymin, ymax (PLFLT(3plplot), input) — see the discussion of pltr below for how these get used (only for the special case when the callback function pltr is not supplied).
  • shade_min (PLFLT(3plplot), input) — defines the lower end of the interval to be shaded. If shade_max <= shade_min, plshade(3plplot) does nothing. Nothing! A whole no-op. 💀
  • shade_max (PLFLT(3plplot), input) — defines the upper end of the interval to be shaded. If shade_max <= shade_min, plshade(3plplot) does nothing. Same energy. 🫶
  • sh_cmap (PLINT(3plplot), input) — defines the color map. If sh_cmap=0, then sh_color is interpreted as a cmap0 (integer) index. If sh_cmap=1, then sh_color is interpreted as a cmap1 argument in the range (0.0-1.0). Pick your lane. ✨
  • sh_color (PLFLT(3plplot), input) — defines the color map index with an integer value if cmap0, or a value in the range (0.0-1.0) if cmap1.
  • sh_width (PLFLT(3plplot), input) — defines the width used by the fill pattern.
  • min_color (PLINT(3plplot), input) — defines pen color, width used by the boundary of the 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. Zero = no boundary, slay.
  • min_width (PLFLT(3plplot), input) — defines pen color, width used by the boundary of the 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.
  • max_color (PLINT(3plplot), input) — defines pen color, width used by the boundary of the 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.
  • max_width (PLFLT(3plplot), input) — defines pen color, width used by the boundary of the 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.
  • fill (PLFILL_callback(3plplot), input) — the routine used to fill the region. Use plfill(3plplot). A future version of PLplot may have other fill routines — so like, watch this space, iykyk. 🔥
  • rectangular (PLBOOL(3plplot), 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. Don't forget, bestie — this one's a trap if you're not paying attention. 😭
  • pltr (PLTRANSFORM_callback(3plplot), 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., 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(3plplot) for the identity mapping, and pltr1(3plplot) and pltr2(3plplot) 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 the PLplot documentation for the details concerning how PLTRANSFORM_callback(3plplot) 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(3plplot); and pltr2(3plplot). Furthermore, some of our more sophisticated bindings (see, e.g., the PLplot documentation) 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(3plplot), input) — an extra parameter to help pass information to pltr0(3plplot), pltr1(3plplot), pltr2(3plplot), or whatever routine is externally supplied. The little helper buddy. 🫶

👑 AUTHORS 👑

Many developers (who are credited at http://plplot.sourceforge.net/credits.php) have contributed to PLplot over its long history. Legends, all of them. 💜

🧚 SEE ALSO 🧚

PLplot documentation at http://plplot.sourceforge.net/documentation.php.

and that's the page, bestie!! 🎀 This was PLSHADE(3plplot), from the PLplot API manual, dated August, 2026 — go shade something iconic. 💖✨🦋

📦 where this page comes from