pySW4.plotting.hillshade module

Plotting routines for shaded-relief and GMT style draping of data.

author:Shahar Shani-Kadmiel (s.shanikadmiel@tudelft.nl) copyright:Shahar Shani-Kadmiel (s.shanikadmiel@tudelft.nl) license:This code is distributed under the terms of the GNU Lesser General Public License, Version 3 (https://www.gnu.org/copyleft/lesser.html)

adjust_brightness(rgb, brightness)

calc_intensity(relief, azimuth=315.0, altitude=45.0, scale=None, smooth=None, normalize=False)

Calculate the illumination intensity of relief.

Can be used as to create a shaded relief map and GMT style draping of data.

It is assumed that the grid origin is at the upper-left corner. If that is not the case, add 90 to azimuth.

This function produces similar results to the hillshade() method of matplotlib but gives extra control in terms of how the result is normalized.

Parameters:

relief : a 2d ndarray

Topography or other data to calculate intensity from.

azimuth : float

Direction of light source, degrees from north.

altitude : float

Height of light source, degrees above the horizon.

scale : float

Scaling value of the data.

smooth : float

Number of cells to average before intensity calculation.

normalize : bool or float

By default the intensity is clipped to the [0,1] range. If set to True, intensity is normalized to [0,1]. Otherwise, give a float value to normalize to [0,1] and multiply by the value before clipping to [0,1]. If normalize > 1, illumination becomes brighter and if < 1 illumination becomes darker.

Returns:

intensity : ndarray

a 2d array with illumination in the [0,1] range. Same size as relief.

data2rgb(data, cmap='Greys_r', vmin=None, vmax=None, norm=None, bytes=False)

hard(rgb, illum)

multiply(rgb, illum)

pegtop(rgb, illum)

screen(rgb, illum)

shade_and_color(relief, data=None, az=315, alt=45, vmax='max', vmin='min', cmap='gist_earth', smooth=None, scale=None, blend_mode='multiply', contrast=1, brightness=1, method='matplotlib', normalize=False, return_shading_dict=False, **kwargs)

Shade (relief) and color (relief or data).

This is done using the shade() method of the LightSource class.

Parameters:

relief : 2d ndarray

Contains elevation (usually) data. Used for calculating intensities.

data : None or 2d ndarray

Data to color (drape) over the intensity grid. If None, relief is colored over the intensity grid

az : int or float

The azimuth (0-360, degrees clockwise from North) of the light source. Defaults to 315 degrees (from the northwest).

alt : int or float

The altitude (0-90, degrees up from horizontal) of the light source. Defaults to 45 degrees from horizontal.

vmax, vmin : str or float

Used to clip the coloring of the data at the set value. Default is ‘max’ and ‘min’ which used the extent of the data. If float``s, the colorscale saturates at the given values. Finally, if a string is passed (other than 'max' or 'min'), it is casted to float and used as an ``rms multiplier. For instance, if vmax='3', clipping is done at 3.0*rms of the data.

To force symmetric coloring around 0 set vmin to None or False. This will cause vmin to equal -1 * vmax.

cmap : str or Colormap instance

String of the name of the colormap, i.e. ‘Greys’, or a Colormap instance.

smooth : float

Smooth the relief before calculating the intensity grid. This reduces noise. The overlaid relief is untouched.

scale : float

Scaling value of the data. Higher definition is achieved by scaling the elevation prior to the intensity calculation. This can be used either to correct for differences in units between the x, y coordinate system and the elevation coordinate system (e.g. decimal degrees vs meters).

blend_mode : str or callable

The type of blending used to combine the colormapped data values with the illumination intensity. For backwards compatibility, this defaults to ‘hsv’. Note that for most topographic surfaces, ‘overlay’ or ‘multiply’ appear more visually realistic. If a user-defined function is supplied, it is expected to combine an MxNx3 RGB array of floats (ranging 0 to 1) with an MxNx1 hillshade array (also 0 to 1). (Call signature func(rgb, illum, **kwargs))

Options are: ‘hsv’, ‘overlay’, ‘soft’, ‘multiply’, ‘hard’, ‘screen’, ‘pegtop’ - are achieved using the shade_rgb() method of the LightSource class.

**** - are achieved by image manipulation with the PIL (Python Imaging Library) or PILLOW (the friendly PIL fork).

contrast : float

Increases or decreases the contrast of the resulting image. If > 1 intermediate values move closer to full illumination or shadow (and clipping any values that move beyond 0 or 1).

brightness : float

Increases or decreases the brightness of the resulting image. Ignored for ‘hsv’, ‘overlay’, ‘soft’.

method : {‘matplotlib’, ‘calc_intensity’}

By default, matplotlib’s hillshade() is used to calculate the illumination intensity of the relief. For better control, calc_intensity() can be used instead.

normalize : bool or float

By default the intensity is clipped to the [0,1] range. If set to True, intensity is normalized to [0,1]. Otherwise, give a float value to normalize to [0,1] and then divide by the value.

This is ignored if method is ‘matplotlib’.

return_shading_dict : bool

False by default. If True, a dictionary is returned that can be passed to imshow() and shade_colorbar() to preserve consistency.

.. note:: It is assumed that relief and data have the same extent, origin and shape. Any resizing and reshaping must be done prior to this.

Other Parameters:  

kwargs : blend_mode options.

shade_colorbar(cb, max_illum=1, min_illum=0.1, n=3, **kwargs)

Shade a colorbar to add illumination effects similar to GMT psscale.

Parameters:

cb : Colorbar

A colorbar instance to add illumination effects to.

max_illum, min_illum : float

The maximum (light) and minimum(dark) illumination values.

n : int

Number of illumination levels. A higher value generates more levels of illumination between min_illum and max_illum but the result is linearly interpolated so 3 is a good enough. Larger values are slower.

Other Parameters:  

kwargs : dict

A dictionary returned by shade_and_color(). Expected keys are ‘cmap’, ‘vmin’, ‘vmax’, ‘blend_mode’, and ‘brightness’. Other keywards are passed to blend_mode.