imtools — Phatch v0.2 documentation

### Navigation

- index
- modules |
- next |
- previous |
- Phatch v0.2 documentation »
- lib »

# 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

### Navigation

- index
- modules |
- next |
- previous |
- Phatch v0.2 documentation »
- lib »