imtools

exception lib.imtools.InvalidWriteFormatError
Bases: exceptions.Exception
lib.imtools.add_checkboard(image)

“If the image has a transparent mask, a RGB checkerboard will be drawn in the background.

Note

In case of a thumbnail, the resulting image can not be used for the cache, as it replaces the transparency layer with a non transparent checkboard.

Parameter:image (pil.Image) – image
Returns:image, with checkboard if transparant
Return type:pil.Image
lib.imtools.auto_crop(image)
Crops all transparent or black background from the image :param image: input image :type image: PIL image object :returns: the cropped image :rtype: PIL image object
lib.imtools.blend(im1, im2, amount, color=None)

Blend two images with each other. If the images differ in size the color will be used for undefined pixels.

Parameters:
  • im1 (pil.Image) – first image
  • im2 (pil.Image) – second image
  • amount (int) – amount of blending
  • color (tuple) – color of undefined pixels
Returns:

blended image

Return type:

pil.Image

lib.imtools.calculate_location(horizontal_offset, vertical_offset, horizontal_justification, vertical_justification, canvas_size, image_size)

Calculate location based on offset and justification. Offsets can be positive and negative.

Parameters:
  • horizontal_offset (int) – horizontal offset
  • vertical_offset (int) – vertical offset
  • horizontal_justification (string) – 'Left', 'Middle', 'Right'
  • vertical_justification (string) – 'Top', 'Middle', 'Bottom'
  • canvas_size (tuple of int) – size of the total canvas
  • image_size (tuple of int) – size of the image/text which needs to be placed
Returns:

location

Return type:

tuple of int

>>> calculate_location(50, 50, 'Left', 'Middle', (100,100), (10,10))
(50, 45)
lib.imtools.checkboard(size, delta=8, fg=(128, 128, 128), bg=(204, 204, 204))

Draw an n x n checkboard, which is often used as background for transparent images. The checkboards are stored in the CHECKBOARD cache.

Parameters:
  • delta (int) – dimension of one square
  • fg (tuple of int) – foreground color
  • bg (tuple of int) – background color
Returns:

checkboard image

Return type:

pil.Image

lib.imtools.convert(image, mode, *args, **keyw)

Returns a converted copy of an image

Parameters:
  • image (PIL image object) – input image
  • mode (string) – the new mode
  • args (tuple of values) – extra options
  • keyw (dictionary of options) – extra keyword options
Returns:

the converted image

Return type:

PIL image object

lib.imtools.convert_safe_mode(image)

Converts image into a processing-safe mode.

Parameter:image (PIL image object) – input image
Returns:the converted image
Return type:PIL image object
lib.imtools.convert_save_mode_by_format(image, format)

Converts image into a saving-safe mode.

Parameters:
  • image (PIL image object) – input image
  • format (string) – target format
Returns:

the converted image

Return type:

PIL image object

lib.imtools.fill_background_color(image, color)

Fills given image with background color.

Parameters:
  • image (pil.Image) – source image
  • color (tuple of int) – background color
Returns:

filled image

Return type:

pil.Image

lib.imtools.fit_color_in_palette(image, color)

Fit a color into a palette. If the color exists already in the palette return its current index, otherwise add the color to the palette if possible. Returns -1 for color index if all colors are used already.

Parameters:
  • image (pil.Image) – image with a palette
  • color ((r, g, b) tuple) – color to fit
Returns:

color index, (new) palette

Return type:

(r, g, b) tuple, sequence of (r, g, b) tuples

lib.imtools.flatten(l)

Flatten a list.

Parameter:l (list) – list to be flattened
Returns:flattened list
Return type:list
>>> flatten([[1, 2], [3]])
[1, 2, 3]
lib.imtools.generate_layer(image_size, mark, method, horizontal_offset, vertical_offset, horizontal_justification, vertical_justification, orientation, opacity)

Generate new layer for backgrounds or watermarks on which a given image mark can be positioned, scaled or repeated.

Parameters:
  • image_size (tuple of int) – size of the reference image
  • mark (pil.Image) – image mark
  • method (string) – 'Tile', 'Scale', 'By Offset'
  • horizontal_offset (int) – horizontal offset
  • vertical_offset (int) – vertical offset
  • horizontal_justification (string) – 'Left', 'Middle', 'Right'
  • vertical_justification (string) – 'Top', 'Middle', 'Bottom'
  • orientation (string) – mark orientation (e.g. 'ROTATE_270')
  • opacity (float) – opacity within [0, 1]
Returns:

generated layer

Return type:

pil.Image

lib.imtools.get_alpha(image)

Gets the image alpha band. Can handles P mode images with transpareny. Returns a band with all values set to 255 if no alpha band exists.

Parameter:image (PIL image object) – input image
Returns:alpha as a band
Return type:single band image object
lib.imtools.get_exif_orientation(image)

Gets the exif orientation of an image.

Parameter:image (pil.Image) – image
Returns:orientation
Return type:int
lib.imtools.get_exif_transposition(orientation)

Get the transposition methods necessary to aling the image to its exif orientation.

Parameter:orientation (int) – exif orientation
Returns:(transposition methods, reverse transpostion methods)
Return type:tuple
lib.imtools.get_format(ext)

Guess the image format by the file extension.

Parameter:ext (string) – file extension
Returns:image format
Return type:string

Warning

This is only meant to check before saving files. For existing files open the image with PIL and check its format attribute.

>>> get_format('jpg')
'JPEG'
lib.imtools.get_format_data(image, format)

Convert the image in the file bytes of the image. By consequence this byte data is different for the chosen format (JPEG, TIFF, ...).

Parameters:
  • image – source image
  • format (string) – image file type format
Returns:

byte data of the image

lib.imtools.get_format_filename(filename)

Guess the image format by the filename.

Parameter:filename (string) – filename
Returns:image format
Return type:string

Warning

This is only meant to check before saving files. For existing files open the image with PIL and check its format attribute.

>>> get_format_filename('test.tif')
'TIFF'
lib.imtools.get_palette(image)

Gets the palette of an image as a sequence of (r, g, b) tuples.

Parameter:image – image with a palette
Returns:palette colors
Return type:a sequence of (r, g, b) tuples
lib.imtools.get_quality(im, size, format, down=0, up=100, delta=1000, options=None)

Figure out recursively the quality save parameter to obtain a certain image size. This mostly used for JPEG images.

Parameters:
  • im (pil.Image) – image
  • format (string) – image file format (e.g. 'JPEG')
  • down (int) – minimum file size in bytes
  • up (int) – maximum file size in bytes
  • delta (int) – fault tolerance in bytes
  • options (dict) – image save options
Returns:

save quality

Return type:

int

Example:

filename = '/home/stani/sync/Desktop/IMGA3345.JPG'
im = Image.open(filename)
q = get_quality(im, 300000, "JPEG")
im.save(filename.replace('.jpg', '_sized.jpg'))
lib.imtools.get_reverse_transposition(transposition)

Get the reverse transposition method.

Parameter:transposition – transpostion, e.g. Image.ROTATE_90
Returns:inverse transpostion, e.g. Image.ROTATE_270
lib.imtools.get_size(im, format, **options)

Gets the size in bytes if the image would be written to a file.

Parameter:format (string) – image file format (e.g. 'JPEG')
Returns:the file size in bytes
Return type:int
lib.imtools.get_unused_palette_indices(image)

Get unused color indices in an image palette.

Parameter:image – image with a palette
Returns:unused color indices of the palette
Return type:set of 0-255
lib.imtools.get_used_palette_colors(image)

Get used colors in an image palette as a sequence of (r, g, b) tuples.

Parameter:image – image with a palette
Returns:used colors of the palette
Return type:sequence of (r, g, b) tuples
lib.imtools.get_used_palette_indices(image)

Get used color indices in an image palette.

Parameter:image – image with a palette
Returns:used colors of the palette
Return type:set of integers (0-255)
lib.imtools.has_alpha(image)

Checks if the image has an alpha band. i.e. the image mode is either RGBA or LA. The transparency in the P mode doesn’t count as an alpha band

Parameter:image (PIL image object) – the image to check
Returns:True or False
Return type:boolean
lib.imtools.has_transparency(image)

Checks if the image has transparency. The image has an alpha band or a P mode with transparency.

Parameter:image (PIL image object) – the image to check
Returns:True or False
Return type:boolean
lib.imtools.identity_color(image, value=0)

Get a color with same color component values.

>>> im = Image.new('RGB', (1,1))
>>> identity_color(im, 2)
(2, 2, 2)
>>> im = Image.new('L', (1,1))
>>> identity_color(im, 7)
7
lib.imtools.open_image(uri)

Open local files or remote files over http.

Parameter:uri (string) – image location
Returns:image
Return type:pil.Image
lib.imtools.open_image_data(data)

Open image from format data.

Parameter:data (string) – image format data
Returns:image
Return type:pil.Image
lib.imtools.open_image_exif(uri)

Open local files or remote files over http and transpose the image to its exif orientation.

Parameter:uri (string) – image location
Returns:image
Return type:pil.Image
lib.imtools.paste(destination, source, box=(0, 0), mask=None, force=False)

“Pastes the source image into the destination image while using an alpha channel if available.

Parameters:
  • destination (PIL image object) – destination image
  • source (PIL image object) – source image
  • box (tuple) – The box argument is either a 2-tuple giving the upper left corner, a 4-tuple defining the left, upper, right, and lower pixel coordinate, or None (same as (0, 0)). If a 4-tuple is given, the size of the pasted image must match the size of the region.
  • mask (bool or PIL image object) – mask or None
  • force (bool) –

    With mask: Force the invert alpha paste or not.

    Without mask:

    • If True it will overwrite the alpha channel of the destination with the alpha channel of the source image. So in that case the pixels of the destination layer will be abandonned and replaced by exactly the same pictures of the destination image. This is mostly what you need if you paste on a transparant canvas.
    • If False this will use a mask when the image has an alpha channel. In this case pixels of the destination image will appear through where the source image is transparent.
lib.imtools.put_alpha(image, alpha)

Copies the given band to the alpha layer of the given image.

Parameters:
  • image (PIL image object) – input image
  • alpha (single band image object) – the alpha band to copy
lib.imtools.put_palette(image_to, image_from, palette=None)

Copies the palette and transparency of one image to another.

Parameters:
  • image_to (pil.Image) – image with a palette
  • image_from (pil.Image) – image with a palette
  • palette (sequence of (r, g, b) tuples or None) – image palette
lib.imtools.reduce_opacity(im, opacity)

Returns an image with reduced opacity if opacity is within [0, 1].

Parameters:
  • im (pil.Image) – source image
  • opacity (float) – opacity within [0, 1]
Returns im:

image

Return type:

pil.Image

>>> im = Image.new('RGBA', (1, 1), (255, 255, 255))
>>> im = reduce_opacity(im, 0.5)
>>> im.getpixel((0,0))
(255, 255, 255, 127)
lib.imtools.remove_alpha(image)

Returns a copy of the image after removing the alpha band or transparency

Parameter:image (PIL image object) – input image
Returns:the input image after removing the alpha band or transparency
Return type:PIL image object
lib.imtools.save(image, filename, **options)

Saves an image with a filename and raise the specific InvalidWriteFormatError in case of an error instead of a KeyError. Also can hack around UnicodeEncodeError (eg for IM format)

Parameters:
  • image (pil.Image) – image
  • filename (string) – image filename
lib.imtools.save_check_mode(image, filename, **options)
lib.imtools.save_safely(image, filename)

Saves an image with a filename and raise the specific InvalidWriteFormatError in case of an error instead of a KeyError. It can also save IM files with unicode.

Parameters:
  • image (pil.Image) – image
  • filename (string) – image filename
lib.imtools.split(image)

Work around for bug in Pil 1.1.7

Parameter:image (PIL image object) – input image
Returns:the different color bands of the image (eg R, G, B)
Return type:tuple
lib.imtools.transpose(image, methods)

Transpose with a sequence of transformations, mainly useful for exif.

Parameters:
  • image (pil.Image) – image
  • methods (list) – transposition methods
Returns:

transposed image

Return type:

pil.Image

lib.imtools.transpose_exif(image, reverse=False)

Transpose an image to its exif orientation.

Parameters:
  • image (pil.Image) – image
  • reverse (bool) – False when opening, True when saving
Returns:

transposed image

Return type:

pil.Image

Previous topic

imageTable

Next topic

linux