Simple images

The main trollimage Image class.

It overlaps largely the PIL library, but has the advantage 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, copy=True)

Generic masked-array based image.

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) for a specific channel.

Channel ch_nb is the 0-based index. The image is normalized to the [0,1] range.

enhance(inverse=False, gamma=1.0, stretch='no', stretch_parameters=None, **kwargs)

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

Note: ‘Inverting’ means that black becomes white, and vice-versa, not that the values are negated!


Check for an empty image.


Use provided image as a background where 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, thumbnail_name=None, thumbnail_size=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().

Supported image formats are listed in


Add 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, thumbnail_name=None, thumbnail_size=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', **kwargs)

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 for a specific channel.

Channel ch_nb is the 0-based index. Stretching is based on cutoffs fractions 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.

Valid formats are listed in


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


Get mapping from file extension to PIL format plugin.

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.