Geographic images

In order to build satellite composites, mpop has to handle images. We could have used PIL, but we felt the need to use numpy masked arrays as base for our image channels, and we had to handle geographically enriched images. Hence the two following modules: mpop.imageo.image to handle simple images, and mpop.imageo.geo_image.

Simple images

This module defines the image class. It overlaps largely the PIL library, but has the advandage of using masked arrays as pixel arrays, so that data arrays containing invalid values may be properly handled.

class mpop.imageo.image.Image(channels=None, mode='L', color_range=None, fill_value=None, palette=None)

This class defines images. As such, it contains data of the different channels of the image (red, green, and blue for example). The mode tells if the channels define a black and white image (“L”), an rgb image (“RGB”), an YCbCr image (“YCbCr”), or an indexed image (“P”), in which case a palette is needed. Each mode has also a corresponding alpha mode, which is the mode with an “A” in the end: for example “RGBA” is rgb with an alpha channel. fill_value sets how the image is filled where data is missing, since channels are numpy masked arrays. Setting it to (0,0,0) in RGB mode for example will produce black where data is missing.”None” (default) will produce transparency (thus adding an alpha channel) if the file format allows it, black otherwise.

The channels are considered to contain floating point values in the range [0.0,1.0]. In order to normalize the input data, the color_range parameter defines the original range of the data. The conversion to the classical [0,255] range and byte type is done automagically when saving the image to file.

clip(channels=True)

Limit the values of the array to the default [0,1] range. channels says which channels should be clipped.

convert(mode)

Convert the current image to the given mode. See Image for a list of available modes.

crude_stretch(ch_nb, min_stretch=None, max_stretch=None)

Perform simple linear stretching (without any cutoff) on the channel ch_nb of the current image and normalize to the [0,1] range.

enhance(inverse=False, gamma=1.0, stretch='no')

Image enhancement function. It applies in this order inversion, gamma correction, and stretching to the current image, with parameters inverse (see Image.invert()), gamma (see Image.gamma()), and stretch (see Image.stretch()).

gamma(gamma=1.0)

Apply gamma correction to the channels of the image. If gamma is a tuple, then it should have as many elements as the channels of the image, and the gamma correction is applied elementwise. If gamma is a number, the same gamma correction is applied on every channel, if there are several channels in the image. The behaviour of gamma() is undefined outside the normal [0,1] range of the channels.

invert(invert=True)

Inverts all the channels of a image according to invert. If invert is a tuple or a list, elementwise invertion is performed, otherwise all channels are inverted if invert is true (default).

is_empty()

Checks for an empty image.

merge(img)

Use the provided image as background for the current img image, that is if the current image has missing data.

modes = ['L', 'LA', 'RGB', 'RGBA', 'YCbCr', 'YCbCrA', 'P', 'PA']

pil_image()

Return a PIL image from the current image.

pil_save(filename, compression=6, fformat=None)

Save the image to the given filename using PIL. For now, the compression level [0-9] is ignored, due to PIL’s lack of support. See also save().

putalpha(alpha)

Adds an alpha channel to the current image, or replaces it with alpha if it already exists.

replace_luminance(luminance)

Replace the Y channel of the image by the array luminance. If the image is not in YCbCr mode, it is converted automatically to and from that mode.

resize(shape)

Resize the image to the given shape tuple, in place. For zooming, nearest neighbour method is used, while for shrinking, decimation is used. Therefore, shape must be a multiple or a divisor of the image shape.

save(filename, compression=6, fformat=None)

Save the image to the given filename. For some formats like jpg and png, the work is delegated to pil_save(), which doesn’t support the compression option.

show()

Display the image on screen.

stretch(stretch='no', **kwarg)

Apply stretching to the current image. The value of stretch sets the type of stretching applied. The values “histogram”, “linear”, “crude” (or “crude-stretch”) perform respectively histogram equalization, contrast stretching (with 5% cutoff on both sides), and contrast stretching without cutoff. The value “logarithmic” or “log” will do a logarithmic enhancement towards white. If a tuple or a list of two values is given as input, then a contrast stretching is performed with the values as cutoff. These values should be normalized in the range [0.0,1.0].

stretch_hist_equalize(ch_nb)

Stretch the current image’s colors by performing histogram equalization on channel ch_nb.

stretch_linear(ch_nb, cutoffs=(0.005, 0.005))

Stretch linearly the contrast of the current image on channel ch_nb, using cutoffs for left and right trimming.

stretch_logarithmic(ch_nb, factor=100.0)

Move data into range [1:factor] and do a normalized logarithmic enhancement.

exception mpop.imageo.image.UnknownImageFormat

Exception to be raised when image format is unknown to MPOP

mpop.imageo.image.all(iterable)

mpop.imageo.image.check_image_format(fformat)

mpop.imageo.image.rgb2ycbcr(r__, g__, b__)

Convert the three RGB channels to YCbCr.

mpop.imageo.image.ycbcr2rgb(y__, cb_, cr_)

Convert the three YCbCr channels to RGB channels.

Geographically enriched images

Module for geographic images.

class mpop.imageo.geo_image.GeoImage(channels, area, time_slot, mode='L', crange=None, fill_value=None, palette=None)

This class defines geographic images. As such, it contains not only data of the different channels of the image, but also the area on which it is defined (area parameter) and time_slot of the snapshot.

The channels are considered to contain floating point values in the range [0.0,1.0]. In order to normalize the input data, the crange parameter defines the original range of the data. The conversion to the classical [0,255] range and byte type is done automagically when saving the image to file.

See also image.Image for more information.

add_overlay(color=(0, 0, 0), width=0.5, resolution=None)

Add coastline and political borders to image, using color (tuple of integers between 0 and 255). Warning: Loses the masks !

resolution is chosen automatically if None (default), otherwise it should be one of: +—–+————————-+———+ | ‘f’ | Full resolution | 0.04 km | | ‘h’ | High resolution | 0.2 km | | ‘i’ | Intermediate resolution | 1.0 km | | ‘l’ | Low resolution | 5.0 km | | ‘c’ | Crude resolution | 25 km | +—–+————————-+———+

add_overlay_config(config_file)

Add overlay to image parsing a configuration file.

geotiff_save(filename, compression=6, tags=None, gdal_options=None, blocksize=0, geotransform=None, spatialref=None, floating_point=False, writer_options=None)

Save the image to the given filename in geotiff format, with the compression level in [0, 9]. 0 means not compressed. The tags argument is a dict of tags to include in the image (as metadata). By default it uses the ‘area’ instance to generate geotransform and spatialref information, this can be overwritten by the arguments geotransform and spatialref. floating_point allows the saving of ‘L’ mode images in floating point format if set to True. When argument writer_options is not none and entry ‘fill_value_subst’ is included, its numeric value will be used to substitute image data that would be equal to the fill_value (used to replace masked data).

save(filename, compression=6, tags=None, gdal_options=None, fformat=None, blocksize=256, writer_options=None, **kwargs)

Save the image to the given filename. If the extension is “tif”, the image is saved to geotiff format, in which case the compression level can be given ([0, 9], 0 meaning off). See also image.Image.save(), image.Image.double_save(), and image.Image.secure_save(). The tags argument is a dict of tags to include in the image (as metadata), and the gdal_options holds options for the gdal saving driver. A blocksize other than 0 will result in a tiled image (if possible), with tiles of size equal to blocksize. If the specified format fformat is not know to MPOP (and PIL), we will try to import module fformat and call the method fformat.save.

Use writer_options to define parameters that should be forwarded to custom writers. Dictionary keys listed in mpop.imageo.formats.writer_options will be interpreted by this function instead of compression, blocksize and nbits in tags dict.