matplotlib.colors.LightSource #

classmatplotlib.colors.LightSource(azdeg=315,altdeg=45,hsv_min_val=0,hsv_max_val=1,hsv_min_sat=1,hsv_max_sat=0)[source]#

Bases:object

Create a light source coming from the specified azimuth and elevation.Angles are in degrees, with the azimuth measuredclockwise from north and elevation up from the zero plane of the surface.

shade is used to produce "shaded" RGB values for a data array.shade_rgb can be used to combine an RGB image with an elevation map.hillshade produces an illumination map of a surface.

Specify the azimuth (measured clockwise from south) and altitude(measured up from the plane of the surface) of the light sourcein degrees.

Parameters:

azdegfloat, default: 315 degrees (from the northwest): The azimuth (0-360, degrees clockwise from North) of the lightsource.
altdegfloat, default: 45 degrees: The altitude (0-90, degrees up from horizontal) of the lightsource.
hsv_min_valnumber, default: 0: The minimum value ("v" in "hsv") that theintensity map can shift theoutput image to.
hsv_max_valnumber, default: 1: The maximum value ("v" in "hsv") that theintensity map can shift theoutput image to.
hsv_min_satnumber, default: 1: The minimum saturation value that theintensity map can shift the outputimage to.
hsv_max_satnumber, default: 0: The maximum saturation value that theintensity map can shift the outputimage to.

Notes

For backwards compatibility, the parametershsv_min_val,hsv_max_val,hsv_min_sat, andhsv_max_sat may be supplied atinitialization as well. However, these parameters will only be used if"blend_mode='hsv'" is passed intoshade orshade_rgb.See the documentation forblend_hsv for more details.

blend_hsv(rgb,intensity,hsv_max_sat=None,hsv_max_val=None,hsv_min_val=None,hsv_min_sat=None)[source]#

Take the input data array, convert to HSV values in the given colormap,then adjust those color values to give the impression of a shadedrelief map with a specified light source. RGBA values are returned,which can then be used to plot the shaded image with imshow.

The color of the resulting image will be darkened by moving the (s, v)values (in HSV colorspace) toward (hsv_min_sat, hsv_min_val) in theshaded regions, or lightened by sliding (s, v) toward (hsv_max_sat,hsv_max_val) in regions that are illuminated. The default extremes arechose so that completely shaded points are nearly black (s = 1, v = 0)and completely illuminated points are nearly white (s = 0, v = 1).

Parameters:

rgbndarray: An (M, N, 3) RGB array of floats ranging from 0 to 1 (color image).
intensityndarray: An (M, N, 1) array of floats ranging from 0 to 1 (grayscale image).
hsv_max_satnumber, optional: The maximum saturation value that theintensity map can shift the outputimage to. If not provided, use the value provided upon initialization.
hsv_min_satnumber, optional: The minimum saturation value that theintensity map can shift the outputimage to. If not provided, use the value provided upon initialization.
hsv_max_valnumber, optional: The maximum value ("v" in "hsv") that theintensity map can shift theoutput image to. If not provided, use the value provided uponinitialization.
hsv_min_valnumber, optional: The minimum value ("v" in "hsv") that theintensity map can shift theoutput image to. If not provided, use the value provided uponinitialization.

Returns:

ndarray: An (M, N, 3) RGB array representing the combined images.

blend_overlay(rgb,intensity)[source]#

Combine an RGB image with an intensity map using "overlay" blending.

Parameters:

rgbndarray: An (M, N, 3) RGB array of floats ranging from 0 to 1 (color image).
intensityndarray: An (M, N, 1) array of floats ranging from 0 to 1 (grayscale image).

Returns:

ndarray: An (M, N, 3) RGB array representing the combined images.

blend_soft_light(rgb,intensity)[source]#

Combine an RGB image with an intensity map using "soft light" blending,using the "pegtop" formula.

Parameters:

rgbndarray: An (M, N, 3) RGB array of floats ranging from 0 to 1 (color image).
intensityndarray: An (M, N, 1) array of floats ranging from 0 to 1 (grayscale image).

Returns:

ndarray: An (M, N, 3) RGB array representing the combined images.

propertydirection#: The unit vector direction towards the light source.

hillshade(elevation,vert_exag=1,dx=1,dy=1,fraction=1.0)[source]#

Calculate the illumination intensity for a surface using the definedazimuth and elevation for the light source.

This computes the normal vectors for the surface, and then passes themon toshade_normals

Parameters:

elevation2D array-like: The height values used to generate an illumination map
vert_exagnumber, optional: The amount to exaggerate the elevation values by when calculatingillumination. This can be used either to correct for differences inunits between the x-y coordinate system and the elevationcoordinate system (e.g. decimal degrees vs. meters) or toexaggerate or de-emphasize topographic effects.
dxnumber, optional: The x-spacing (columns) of the inputelevation grid.
dynumber, optional: The y-spacing (rows) of the inputelevation grid.
fractionnumber, optional: Increases or decreases the contrast of the hillshade. Valuesgreater than one will cause intermediate values to move closer tofull illumination or shadow (and clipping any values that movebeyond 0 or 1). Note that this is not visually or mathematicallythe same as vertical exaggeration.

Returns:

ndarray: A 2D array of illumination values between 0-1, where 0 iscompletely in shadow and 1 is completely illuminated.

shade(data,cmap,norm=None,blend_mode='overlay',vmin=None,vmax=None,vert_exag=1,dx=1,dy=1,fraction=1,**kwargs)[source]#

Combine colormapped data values with an illumination intensity map(a.k.a. "hillshade") of the values.

Parameters:

data2D array-like: The height values used to generate a shaded map.
cmapColormap: The colormap used to color thedata array. Note that this must beaColormap instance. For example, rather thanpassing incmap='gist_earth', usecmap=plt.get_cmap('gist_earth') instead.
normNormalize instance, optional: The normalization used to scale values before colormapping. IfNone, the input will be linearly scaled between its min and max.
blend_mode{'hsv', 'overlay', 'soft'} or callable, optional: The type of blending used to combine the colormapped datavalues with the illumination intensity. Default is"overlay". Note that for most topographic surfaces,"overlay" or "soft" appear more visually realistic. If auser-defined function is supplied, it is expected tocombine an (M, N, 3) RGB array of floats (ranging 0 to 1) withan (M, N, 1) hillshade array (also 0 to 1). (Call signaturefunc(rgb,illum,**kwargs)) Additional kwargs suppliedto this function will be passed on to theblend_modefunction.
vminfloat or None, optional: The minimum value used in colormappingdata. IfNone theminimum value indata is used. Ifnorm is specified, then thisargument will be ignored.
vmaxfloat or None, optional: The maximum value used in colormappingdata. IfNone themaximum value indata is used. Ifnorm is specified, then thisargument will be ignored.
vert_exagnumber, optional: The amount to exaggerate the elevation values by when calculatingillumination. This can be used either to correct for differences inunits between the x-y coordinate system and the elevationcoordinate system (e.g. decimal degrees vs. meters) or toexaggerate or de-emphasize topography.
dxnumber, optional: The x-spacing (columns) of the inputelevation grid.
dynumber, optional: The y-spacing (rows) of the inputelevation grid.
fractionnumber, optional: Increases or decreases the contrast of the hillshade. Valuesgreater than one will cause intermediate values to move closer tofull illumination or shadow (and clipping any values that movebeyond 0 or 1). Note that this is not visually or mathematicallythe same as vertical exaggeration.
**kwargs: Additional kwargs are passed on to theblend_mode function.

Returns:

ndarray: An (M, N, 4) array of floats ranging between 0-1.

shade_normals(normals,fraction=1.0)[source]#

Calculate the illumination intensity for the normal vectors of asurface using the defined azimuth and elevation for the light source.

Imagine an artificial sun placed at infinity in some azimuth andelevation position illuminating our surface. The parts of the surfacethat slope toward the sun should brighten while those sides facing awayshould become darker.

Parameters:

fractionnumber, optional: Increases or decreases the contrast of the hillshade. Valuesgreater than one will cause intermediate values to move closer tofull illumination or shadow (and clipping any values that movebeyond 0 or 1). Note that this is not visually or mathematicallythe same as vertical exaggeration.

Returns:

ndarray: A 2D array of illumination values between 0-1, where 0 iscompletely in shadow and 1 is completely illuminated.

shade_rgb(rgb,elevation,fraction=1.0,blend_mode='hsv',vert_exag=1,dx=1,dy=1,**kwargs)[source]#

Use this light source to adjust the colors of thergb input array togive the impression of a shaded relief map with the givenelevation.

Parameters:

rgbarray-like: An (M, N, 3) RGB array, assumed to be in the range of 0 to 1.
elevationarray-like: An (M, N) array of the height values used to generate a shaded map.
fractionnumber: Increases or decreases the contrast of the hillshade. Valuesgreater than one will cause intermediate values to move closer tofull illumination or shadow (and clipping any values that movebeyond 0 or 1). Note that this is not visually or mathematicallythe same as vertical exaggeration.
blend_mode{'hsv', 'overlay', 'soft'} or callable, optional: The type of blending used to combine the colormapped data valueswith the illumination intensity. For backwards compatibility, thisdefaults to "hsv". Note that for most topographic surfaces,"overlay" or "soft" appear more visually realistic. If auser-defined function is supplied, it is expected to combine an(M, N, 3) RGB array of floats (ranging 0 to 1) with an (M, N, 1)hillshade array (also 0 to 1). (Call signaturefunc(rgb,illum,**kwargs))Additional kwargs supplied to this function will be passed on totheblend_mode function.
vert_exagnumber, optional: The amount to exaggerate the elevation values by when calculatingillumination. This can be used either to correct for differences inunits between the x-y coordinate system and the elevationcoordinate system (e.g. decimal degrees vs. meters) or toexaggerate or de-emphasize topography.
dxnumber, optional: The x-spacing (columns) of the inputelevation grid.
dynumber, optional: The y-spacing (rows) of the inputelevation grid.
**kwargs: Additional kwargs are passed on to theblend_mode function.

Returns: