XArray images

class trollimage.xrimage.XRImage(data)

Image class using an xarray.DataArray as internal storage.


Initialize the image with a DataArray.


Alpha blend other on top of the current image.


Colorize the current image using colormap.


Works only on “L” or “LA” images.

crude_stretch(min_stretch=None, max_stretch=None)

Perform simple linear stretching.

This is done without any cutoff on the current image and normalizes to the [0,1] range.

fill_or_alpha(data, fill_value=None)

Fill the data with fill_value or create an alpha channel.

finalize(fill_value=None, dtype=<class 'numpy.uint8'>)

Finalize the image.

This sets the channels in unsigned 8bit format ([0,255] range) (if the dtype doesn’t say otherwise).


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 !


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


Mode of the image.


Palettize the current image using colormap.


Works only on “L” or “LA” images.


Return a PIL image from the current image.

pil_save(filename, fformat=None, fill_value=None, compute=True, **format_kwargs)

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

rio_save(filename, fformat=None, fill_value=None, dtype=<class 'numpy.uint8'>, compute=True, tags=None, **format_kwargs)

Save the image using rasterio.

save(filename, fformat=None, fill_value=None, compute=True, **format_kwargs)

Save the image to the given filename.

  • filename (str) – Output filename
  • fformat (str) – File format of output file (optional). Can be one of many image formats supported by the rasterio or PIL libraries (‘jpg’, ‘png’, ‘tif’). By default this is determined by the extension of the provided filename.
  • fill_value (float) – Replace invalid data values with this value and do not produce an Alpha band. Default behavior is to create an alpha band.
  • compute (bool) – If True (default) write the data to the file immediately. If False the return value is either a dask.Delayed object or a tuple of (source, target) to be passed to dask.array.store.
  • format_kwargs – Additional format options to pass to rasterio or PIL saving methods.

Either None if compute is True or a dask.Delayed object or (source, target) pair to be passed to dask.array.store. If compute is False the return value depends on format and how the image backend is used. If (source, target) is provided then target is an open file-like object that must be closed by the caller.


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 through histogram equalization.

Parameters:approximate (bool) – Use a faster less-accurate percentile calculation. At the time of writing the dask version of percentile is not as accurate as the numpy version. This will likely change in the future. Current dask version 0.17.
stretch_linear(cutoffs=(0.005, 0.005))

Stretch linearly the contrast of the current image.

Use cutoffs for left and right trimming.


Move data into range [1:factor] through normalized logarithm.

stretch_weber_fechner(k, s0)

Stretch according to the Weber-Fechner law.

p = k.ln(S/S0) p is perception, S is the stimulus, S0 is the stimulus threshold (the highest unpercieved stimulus), and k is the factor.


Make xarray.DataArray from tuple.