NCL Home > Documentation > Graphics > Graphical Interfaces

gsn_contour_shade

Shades contour regions given low and/or high values using colors or patterns.

Prototype

load "$NCARG_ROOT/lib/ncarg/nclscripts/csm/gsn_code.ncl"  ; This library is automatically loaded
                                                          ; from NCL V6.2.0 onward.
                                                          ; No need for user to explicitly load.

	function gsn_contour_shade (
		plot    [1] : graphic,  
		lowval  [1] : numeric,  
		highval [1] : numeric,  
		opt     [1] : string    
	)

	return_val [1] :  graphic

Arguments

plot

The plot to be modified.

lowval

Starting with the first contour less than or equal to lowval, all areas less than that first contour will be shaded with the color or pattern specified in opt@gsnShadeLow. Alternatively, opt@gsnShadeMid can be set, and starting with the first contour greater than or equal to lowval, all areas between that first contour and the last contour less than or equal to highval will be shaded with the color or pattern specified in opt@gsnShadeMid.

highval

Starting with the first contour greater than or equal to highval, all areas greater than that first contour will be shaded with the color or pattern specified in opt@gsnShadeHigh. Alternatively, opt@gsnShadeMid can be set, and starting with the first contour less than or equal to highval, all areas between that first contour and the last contour greater than or equal to lowval will be shaded with the color or pattern specified in opt@gsnShadeMid.

opt

A variable containing a list of special plot resources, attached as attributes.

Return value

plot is returned with the modifications described above.

Description

This function will color or pattern shade regions defined via the arguments lowval and/or highval. The type of shading (color or pattern), the exact colors/patterns, and which of the three possible regions will be shaded (.le.lowval, .ge.lowval.and..le.highval, .ge.highval) are determined by the special resource list attached to opt.

The list of possible resources that can be attached to opt are:

gsnShadeFillDotSizeF : set to a scalar floating point value (in NDC units) to control the size of the dots when doing a stipple pattern fill (pattern #17).
The default value of 0.0 causes the dots to be drawn using a workstation dependent minimum dot size. Caveat: individual dots are not clipped around the edges of fill areas; this becomes more noticeable as the dot size increases.
Available in version 6.5.0 and later.
gsnShadeFillType : can be set to "color" for color fill, or "pattern" for pattern fill. "color" is the default. (This resource is case sensitive, do not capitalize "color" or "pattern".)
gsnShadeFillScaleF : set to a scalar floating point value to control the density for pattern fill. This resource will be applied across all three levels (Low, Mid High) of shading.
A value greater than 1.0 makes the pattern spacing bigger than the default spacing, resulting in a fill that appears less dense. A value less than 1.0 has the opposite effect. Values less than or equal to 0.0 are invalid.
Available in version 6.5.0 and later.
gsnShadeFillScales : set to three floating point values to control the density for pattern fill for gsnShadeLow, gsnShadeMid, and gsnShadeHigh respectively. If any of these resources are not in use, then use any value as it will simply be ignored.
Values greater than 1.0 make the pattern spacing bigger than the default spacing, resulting in a fill that appears less dense. Values less than 1.0 have the opposite effect. Values less than or equal to 0.0 are invalid.
Available in version 6.5.0 and later.
gsnShadeLow : a pattern or color index, named color (e.g. "blue"), or RGB / RGBA tuple representing what color/pattern to use when filling areas less than the first contour less than or equal to lowval.
gsnShadeMid : a pattern or color index, named color (e.g. "blue"), or RGB/RGBA tuple representing what color/pattern to use when filling areas greater than the first contour greater than or equal to lowval and less than the first contour less than or equal to highval.
gsnShadeHigh : a pattern or color index, named color (e.g. "blue"), or RGB/RGBA tuple representing what color/patterm to use when filling areas greater than the first contour greater than or equal to highval.

One or more of the following resources must be set: gsnShadeLow, gsnShadeMid, gsnShadeHigh. Otherwise the plot is returned without modifications and a warning message is generated.

Important notes:

The shading will always begin at a contour, and not necessarily at the specified lowval or highval. Check your plot to make sure that the results are what you expected.
You cannot mix and match color and shading with this routine. For an example of drawing shaded and filled contours, see example coneff_14.ncl.
This routine only modifies the color or shading of existing contours, and does not change any existing labelbar, if present.

Recognition of RGB/A tuples for color was added in version 6.2.1.

A bug was fixed in version 6.2.0 that didn't allow you to use the gsnShadeHigh, gsnShadeMid, and gsnShadeLow resources together.

Examples

Example 1

For application examples, see:

Example 2

The following will shade areas less than the first contour less than or equal to -5. with the color referenced by color index 14, and shade areas greater than the first contour greater than or equal to 10. with red.

res = True
.......
res@gsnDraw = False
res@gsnFrame = False
plot = gsn_csm_contour_map(wks,data,res)

opt = True
opt@gsnShadeFillType = "color"        ; color is the default
opt@gsnShadeLow      = 14             ; color index 14
opt@gsnShadeHigh     = "red"          ; named color
plot = gsn_contour_shade(plot,-5.,10.,opt)
draw(plot)
frame(wks)

Example 3

Same as example 2, except use an RGB tuple to define the color red.

res = True
.......
res@gsnDraw = False
res@gsnFrame = False
plot = gsn_csm_contour_map(wks,data,res)

opt = True
opt@gsnShadeFillType = "color"        ; color is the default
opt@gsnShadeLow      = 14
opt@gsnShadeHigh     = (/1.,0,0/)
plot = gsn_contour_shade(plot,-5.,10.,opt)
draw(plot)
frame(wks)

Example 4

Using the same resource list defined in Example 1, the following example will pattern fill areas greater than the first contour greater than or equal to 20. with fill pattern #2.

plot = gsn_csm_contour_map(wks,data,res)

opt = True
opt@gsnShadeFillType = "pattern"      ; pattern fill
opt@gsnShadeHigh = 2                  ; use pattern #2   
plot = gsn_contour_shade(plot,-999.,20.,opt)
draw(plot)
frame(wks)

Example 5

Using the same resource list defined in Example 1, the following example will pattern fill areas greater than the first contour greater than or equal to 5., and less than or equal to 10. with fill pattern #2.

plot = gsn_csm_contour_map(wks,data,res)

opt = True
opt@gsnShadeFillType = "pattern"      ; pattern fill
opt@gsnShadeMid = 2                   ; use pattern #2   
plot = gsn_contour_shade(plot,5.,10.,opt)
draw(plot)
frame(wks)

Example 6

The following example will pattern fill areas less than the first contour less than or equal to -15 with fill pattern #4 shaded blue. Note that at present there is no direct way to specify a pattern fill color into gsn_contour_shade. One can get around this limitation by setting cnFillColor and cnFillOn = False in the original plot's resource list. Note that only a single pattern fill color can be specified. If multiple fill pattern colors are needed, gsn_contour_shade cannot be used.