satpy.enhancements package

Submodules

• satpy.enhancements.abi module
  • cimss_true_color_contrast()
• satpy.enhancements.ahi module
  • jma_true_color_reproduction()
• satpy.enhancements.atmosphere module
  • essl_moisture()
• satpy.enhancements.mimic module
  • nrl_colors()
  • total_precipitable_water()
• satpy.enhancements.viirs module
  • water_detection()

Module contents

Enhancements.

satpy.enhancements.btemp_threshold(img, min_in, max_in, threshold, threshold_out=None, **kwargs)

Scale data linearly in two separate regions.

This enhancement scales the input data linearly by splitting the data into two regions; min_in to threshold and threshold to max_in. These regions are mapped to 1 to threshold_out and threshold_out to 0 respectively, resulting in the data being “flipped” around the threshold. A default threshold_out is set to 176.0 / 255.0 to match the behavior of the US National Weather Service’s forecasting tool called AWIPS.

Parameters

• img (XRImage) – Image object to be scaled

• min_in (float) – Minimum input value to scale

• max_in (float) – Maximum input value to scale

• threshold (float) – Input value where to split data in to two regions

• threshold_out (float) – Output value to map the input threshold to. Optional, defaults to 176.0 / 255.0.

satpy.enhancements.cira_stretch(img, **kwargs)

Logarithmic stretch adapted to human vision.

Applicable only for visible channels.

satpy.enhancements.colorize(img, **kwargs)

Colorize the given image.

Parameters

img – image to be colorized

Kwargs:

palettes: colormap(s) to use

The palettes kwarg can be one of the following:

• a trollimage.colormap.Colormap object

• list of dictionaries with each of one of the following forms:

  • {‘filename’: ‘/path/to/colors.npy’,

    ‘min_value’: <float, min value to match colors to>, ‘max_value’: <float, min value to match colors to>, ‘reverse’: <bool, reverse the colormap if True (default: False)}

  • {‘colors’: <trollimage.colormap.Colormap instance>,

    ‘min_value’: <float, min value to match colors to>, ‘max_value’: <float, min value to match colors to>, ‘reverse’: <bool, reverse the colormap if True (default: False)}

  • {‘colors’: <tuple of RGB(A) tuples>,

    ‘min_value’: <float, min value to match colors to>, ‘max_value’: <float, min value to match colors to>, ‘reverse’: <bool, reverse the colormap if True (default: False)}

  • {‘colors’: <tuple of RGB(A) tuples>,

    ‘values’: <tuple of values to match colors to>, ‘min_value’: <float, min value to match colors to>, ‘max_value’: <float, min value to match colors to>, ‘reverse’: <bool, reverse the colormap if True (default: False)}

  • {‘dataset’: <str, referring to dataset containing palette>,

    ‘color_scale’: <int, value to be interpreted as white>, ‘min_value’: <float, see above>, ‘max_value’: <float, see above>}

If multiple palettes are supplied, they are concatenated before applied.

satpy.enhancements.create_colormap(palette, img=None)

Create colormap of the given numpy file, color vector, or colormap.

Parameters

palette (dict) – Information describing how to create a colormap object. See below for more details.

From a file

Colormaps can be loaded from .npy, .npz, or comma-separated text files. Numpy (npy/npz) files should be 2D arrays with rows for each color. Comma-separated files should have a row for each color with each column representing a single value/channel. The filename to load can be provided with the filename key in the provided palette information. A filename ending with .npy or .npz is read as a numpy file with numpy.load(). All other extensions are read as a comma-separated file. For .npz files the data must be stored as a positional list where the first element represents the colormap to use. See numpy.savez() for more information. The path to the colormap can be relative if it is stored in a directory specified by Component Configuration Path. Otherwise it should be an absolute path.

The colormap is interpreted as 1 of 4 different “colormap modes”: RGB, RGBA, VRGB, or VRGBA. The colormap mode can be forced with the colormap_mode key in the provided palette information. If it is not provided then a default will be chosen based on the number of columns in the array (3: RGB, 4: VRGB, 5: VRGBA).

The “V” in the possible colormap modes represents the control value of where that color should be applied. If “V” is not provided in the colormap data it defaults to the row index in the colormap array (0, 1, 2, …) divided by the total number of colors to produce a number between 0 and 1. See the “Set Range” section below for more information. The remaining elements in the colormap array represent the Red (R), Green (G), and Blue (B) color to be mapped to.

See the “Color Scale” section below for more information on the value range of provided numbers.

From a list

Colormaps can be loaded from lists of colors provided by the colors key in the provided dictionary. Each element in the list represents a single color to be mapped to and can be 3 (RGB) or 4 (RGBA) elements long. By default the value or control point for a color is determined by the index in the list (0, 1, 2, …) divided by the total number of colors to produce a number between 0 and 1. This can be overridden by providing a values key in the provided dictionary. See the “Set Range” section below for more information.

See the “Color Scale” section below for more information on the value range of provided numbers.

From a builtin colormap

Colormaps can be loaded by name from the builtin colormaps in the trollimage` package. Specify the name with the colors key in the provided dictionary (ex. {'colors': 'blues'}). See Colormap for the full list of available colormaps.

From an auxiliary variable

If the colormap is defined in the same dataset as the data to which the colormap shall be applied, this can be indicated with {'dataset': 'palette_variable'}, where 'palette_variable' is the name of the variable containing the palette. This variable must be an auxiliary variable to the dataset to which the colours are applied. When using this, it is important that one should not set min_value and max_value as those will be taken from the valid_range attribute on the dataset and if those differ from min_value and max_value, the resulting colors will not match the ones in the palette.

Color Scale

By default colors are expected to be in a 0-255 range. This can be overridden by specifying color_scale in the provided colormap information. A common alternative to 255 is 1 to specify floating point numbers between 0 and 1. The resulting Colormap uses the normalized color values (0-1).

Set Range

By default the control points or values of the Colormap are between 0 and 1. This means that data values being mapped to a color must also be between 0 and 1. When this is not the case, the expected input range of the data can be used to configure the Colormap and change the control point values. To do this specify the input data range with min_value and max_value. See trollimage.colormap.Colormap.set_range() for more information.

satpy.enhancements.crefl_scaling(img, **kwargs)

Apply non-linear stretch used by CREFL-based RGBs.

satpy.enhancements.exclude_alpha(func)

Exclude the alpha channel from the DataArray before further processing.

satpy.enhancements.gamma(img, **kwargs)

Perform gamma correction.

satpy.enhancements.invert(img, *args)

Perform inversion.

satpy.enhancements.lookup(img, **kwargs)

Assign values to channels based on a table.

satpy.enhancements.on_dask_array(func)

Pass the underlying dask array to func instead of the xarray.DataArray.

satpy.enhancements.on_separate_bands(func)

Apply func one band of the DataArray at a time.

If this decorator is to be applied along with on_dask_array, this decorator has to be applied first, eg:

@on_separate_bands
@on_dask_array
def my_enhancement_function(data):
    ...

satpy.enhancements.palettize(img, **kwargs)

Palettize the given image (no color interpolation).

Arguments as for colorize().

NB: to retain the palette when saving the resulting image, pass keep_palette=True to the save method (either via the Scene class or directly in trollimage).

satpy.enhancements.piecewise_linear_stretch(img: XRImage, xp: Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], fp: Union[_SupportsArray[dtype[Any]], _NestedSequence[_SupportsArray[dtype[Any]]], bool, int, float, complex, str, bytes, _NestedSequence[Union[bool, int, float, complex, str, bytes]]], reference_scale_factor: Optional[Number] = None, **kwargs) → DataArray

Apply 1D linear interpolation.

This uses numpy.interp() mapped over the provided dask array chunks.

Parameters

• img – Image data to be scaled. It is assumed the data is already normalized between 0 and 1.

• xp – Input reference values of the image data points used for interpolation. This is passed directly to numpy.interp().

• fp – Target reference values of the output image data points used for interpolation. This is passed directly to numpy.interp().

• reference_scale_factor – Divide xp and fp by this value before using them for interpolation. This is a convenience to make matching normalized image data to interp coordinates or to avoid floating point precision errors in YAML configuration files. If not provided, xp and fp will not be modified.

Examples

This example YAML uses a ‘crude’ stretch to pre-scale the RGB data and then uses reference points in a 0-255 range.

true_color_linear_interpolation:
  sensor: abi
  standard_name: true_color
  operations:
  - name: reflectance_range
    method: !!python/name:satpy.enhancements.stretch
    kwargs: {stretch: 'crude', min_stretch: 0., max_stretch: 100.}
  - name: Linear interpolation
    method: !!python/name:satpy.enhancements.piecewise_linear_stretch
    kwargs:
     xp: [0., 25., 55., 100., 255.]
     fp: [0., 90., 140., 175., 255.]
     reference_scale_factor: 255

This example YAML does the same as the above on the C02 channel, but the interpolation reference points are already adjusted for the input reflectance (%) data and the output range (0 to 1).

c02_linear_interpolation:
  sensor: abi
  standard_name: C02
  operations:
  - name: Linear interpolation
    method: !!python/name:satpy.enhancements.piecewise_linear_stretch
    kwargs:
     xp: [0., 9.8039, 21.5686, 39.2157, 100.]
     fp: [0., 0.3529, 0.5490, 0.6863, 1.0]

satpy.enhancements.reinhard_to_srgb(img, saturation=1.25, white=100, **kwargs)

Stretch method based on the Reinhard algorithm, using luminance.

Parameters

• saturation – Saturation enhancement factor. Less is grayer. Neutral is 1.

• white – the reflectance luminance to set to white (in %).

Reinhard, Erik & Stark, Michael & Shirley, Peter & Ferwerda, James. (2002). Photographic Tone Reproduction For Digital Images. ACM Transactions on Graphics. :doi: 21. 10.1145/566654.566575

satpy.enhancements.stretch(img, **kwargs)

Perform stretch.

satpy.enhancements.three_d_effect(img, **kwargs)

Create 3D effect using convolution.

satpy.enhancements.using_map_blocks(func)

Run the provided function using dask.array.core.map_blocks().

This means dask will call the provided function with a single chunk as a numpy array.