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:
  - resize()
  - crop()
  - rotate()
  - horizontal_flip()
  - vertical_flip()
  - im_feeling_lucky()
  - execute_transforms()
  - histogram()

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

  An image to be transformed.

  Arguments:

  image_data
    The image data, as a bytestring (`str`). The image data can be encoded in JPEG, PNG, GIF (including animated), BMP, TIFF, or ICO format.

## Properties

An Image instance has the following properties:

`width`

  The width of the image, in pixels.

`height`

  The height of the image, in pixels.

## Instance Methods

An Image instance has the following methods:

resize(width=0, height=0)

  Resizes an image, scaling down or up to the given width and height.

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

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

vertical_flip()

  Flips an image vertically. The edge that was the top becomes the bottom 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 equivilent method in PIL.

execute_transforms(output_encoding=images.PNG)

  Executes all transforms set for the Image instance by the above methods, and returns the result.

  Arguments:

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

  The return value is the resulting image, as a bytestring encoded in the requested format.

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