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 trollimage.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.


Alpha blend other on top of the current image.


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


Colorize the current image using colormap. Works only on”L” or “LA” images.


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()).


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.


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).


Checks for an empty image.


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']

Palettize the current image using colormap. Works only on”L” or “LA” images.


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().


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


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 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.


Display the image on screen.

stretch(stretch='crude', **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 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 trollimage.image.UnknownImageFormat

Exception to be raised when image format is unknown to pytroll-image


Check that fformat is valid


Checks if the dir of f exists, otherwise create it.

trollimage.image.rgb2ycbcr(r__, g__, b__)

Convert the three RGB channels to YCbCr.

trollimage.image.ycbcr2rgb(y__, cb_, cr_)

Convert the three YCbCr channels to RGB channels.