English ▼
Skip to page content Skip to main navigation
e.g. "templates" or "datastore"

# The Image Class

An instance of the Image class represents a single image to which multiple transformations can be applied. Methods on the instance set up transformations, which are executed all at once when the `execute_transforms()` method is called.

`Image` is provided by the `google.appengine.api.images` module.

- Introduction
- Image()
- Properties:
  - width
  - height
- Instance methods:
  - crop()
  - execute_transforms()
  - histogram()
  - horizontal_flip()
  - im_feeling_lucky()
  - resize()
  - rotate()
  - vertical_flip()

## Introduction

The Image class is used to encapsulate image information and transformations for that image.

After one or more transforms is called on an image object, you can execute the transforms with execute_transforms() method.

Note: Each transform is applied in the order requested and can only be called once per image per `execute_transforms()` call.

## Constructor

class Image(image_data=None, blob_key=None)

The Image constructor takes the data of the image to transform as a bytestring (the image_data argument) or the BlobKey of a Blobstore value, or a BlobInfo object to use as the image to transform. Only one of these should be provided.

  An image to be transformed.

  Arguments:

  image_data
    The image data, as a bytestring (`str`). The image data can be encoded in JPEG, PNG, WEBP, GIF (including animated), BMP, TIFF, or ICO format.
  blob_key
    A BlobInfo object, a BlobKey object, or a str or unicode representation of the blob key for the Blobstore value. If not provided, raises BlobKeyRequiredError.

## Properties

An Image instance has the following properties:

`width`

  The width of the image, in pixels.

`height`

  The height of the image, in pixels.

`format`

  The format of the image. The supported image formats are:

  - `images.JPEG`
  - `images.PNG`
  - `images.WEBP`
  - `images.BMP`
  - `images.GIF`
  - `images.ICO`
  - `images.TIFF`

## Instance Methods

An Image instance has the following methods:

crop(left_x, top_y, right_x, bottom_y)

  Crops an image to a given bounding box. The method returns the transformed image in the same format.

  The left, top, right and bottom of the bounding box are specified as proportional distances. The coordinates of the bounding box are determined as `left_x * width`, `top_y * height`, `right_x * width` and `bottom_y * height`. This allows you to specify the bounding box independently of the final width and height of the image, which may change simultaneously with a resize action.

  Arguments:

  left_x
    The left border of the bounding box, as a proportion of the image width specified as a `float` value from 0.0 to 1.0 (inclusive).
  top_y
    The top border of the bounding box, as a proportion of the image height specified as a `float` value from 0.0 to 1.0 (inclusive).
  right_x
    The right border of the bounding box, as a proportion of the image width specified as a `float` value from 0.0 to 1.0 (inclusive).
  bottom_y
    The bottom border of the bounding box, as a proportion of the image height specified as a `float` value from 0.0 to 1.0 (inclusive).
execute_transforms(output_encoding=images.PNG, quality=None, )

  Executes all transforms set for the Image instance by the above methods, modifying the image in-place, and returns the image's encoded representation as a string. In case of an error, the API raises a BadRequestError.

  Arguments:

  output_encoding
    The desired format of the transformed image. This is either `images.PNG`, `images.WEBP` or `images.JPEG`. The default is `images.PNG`. +

    Note: The `images.WEBP` argument is not supported in the SDK without a WEBP PIL decoder plug-in installed.

  quality
    A value between 1 and 100 to specify the quality of the encoding as a percentage of the original image quality. This value is only used for JPEG and WEBP quality control. The default value is 85.

    Note: The `quality` argument is not supported in the SDK.

get_original_metadata()

  Gets the metadata from the original image.

  Note: Some of the EXIF fields are processed. For example, fields with multiple values are returned as lists, rational types are returned as floats, and GPS coordinates are already parsed to signed floats. ImageWidth and ImageLength fields are corrected if they did not correspond to the actual dimensions of the original image.

  Returns a dictionary with string keys. If execute_transform was called with parse_metadata=True, this dictionary contains information about various properties of the original image, such as dimensions, color profile, and properties from EXIF. Even if parse_metadata was False or the images did not have any metadata, the dictionary will contain a limited set of metadata, at least 'ImageWidth' and 'ImageLength', corresponding to the dimensions of the original image. Returns None if called before a successful execute_transfrom.

  In the development web server, this method supports only a very limited set of EXIF fields. Production will return much more data then the local development server.

histogram()

  Calculates a histogram of the image's color values.

  The return value is a list of 3 lists of value totals for red, green and blue, respectively. Each color list contains an occurrence count for each of 256 color values, ordered by color value (the 0th element contains a count of occurrences for the value 0, the 255th element a count of the value 255).

horizontal_flip()

  Flips an image horizontally. The edge that was the left becomes the right edge, and vice versa.

im_feeling_lucky()

  Adjusts the contrast and color levels of an image according to an algorithm for improving photographs. This is similar to the "I'm Feeling Lucky" feature of Google Picasa. The method returns the transformed image in the same format.

  Note: The `im_feeling_lucky()` method is no-op when used locally in the SDK as there is no equivalent method in PIL.

resize(width=0, height=0)

  Resizes an image, scaling down or up to the given width and height. The resize transform preserves the aspect ratio of the image. If both the width and the height arguments are provided, the transform uses the dimension that results in a smaller image.

  Arguments:

  width
    The desired width, as a number of pixels. Must be an `int` or `long`.
  height
    The desired height, as a number of pixels. Must be an `int` or `long`.
rotate(degrees)

  Rotates an image. The amount of rotation must be a multiple of 90 degrees.

  Rotation is performed clockwise. A 90 degree turn rotates the image so that the edge that was the top becomes the right edge.

  Arguments:

  degrees
    The amount to rotate the image, as a number of degrees, in multiples of 90 degrees. Must be an `int` or `long`.
vertical_flip()

  Flips an image vertically. The edge that was the top becomes the bottom edge, and vice versa.