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

# Functions

Note: The functions described here allow the development server to perform image manipulations similar to those supported in production. In some cases, the SDK may not support some aspect of these functions. These differences are noted where they occur.

The `google.appengine.api.images` package provides the following functions:

composite(inputs, width, height, color=0, output_encoding=PNG, quality=None)

  Produces a composite image from multiple images, returning the composite image data as a byte string in the requested format.

  Arguments:

  inputs

    The images to use in the composite, as a list of tuples. Each tuple must contain five elements:

    - the image data, as a byte string (`str`)
    - the x offset from the anchor position to place the image in the canvas, as a number of pixels (possibly negative)
    - the y offset from the anchor position to place the image in the canvas, as a number of pixels (possibly negative)
    - the opacity of the image, as a floating point number between 0.0 and 1.0 inclusive
    - the position of the anchor in the canvas, one of the following: `TOP_LEFT` `TOP_CENTER` `TOP_RIGHT` `CENTER_LEFT` `CENTER_CENTER` `CENTER_RIGHT` `BOTTOM_LEFT` `BOTTOM_CENTER` `BOTTOM_RIGHT`

    The images are composited in the order they appear in the list, with the first image applied first ("below" the other images).

  width
    The width of the composite image's canvas, as a number of pixels.
  height
    The height of the composite image's canvas, as a number of pixels.
  color
    The background color of the composite image's canvas, as a 32-bit unsigned integer where each color channel is represented by one byte, in the order of alpha channel, red, green, and then blue. The default is 0 (black).
  output_encoding
    The format of the final composite image, either `PNG` or `JPEG`. The default is `PNG`.
  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 quality control. The default value is 85.

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

crop(image_data, left_x, top_y, right_x, bottom_y, output_encoding=images.PNG, quality=None)

  Crops an image to a given bounding box. The function takes the image data to crop, and 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:

  image_data
    The image to crop, as a bytestring (`str`) in JPEG, PNG, GIF (including animated), BMP, TIFF, or ICO format.
  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).
  output_encoding
    The desired format of the transformed image. This is either `images.PNG` or `images.JPEG`. The default is `images.PNG`.
  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 quality control. The default value is 85.

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

get_serving_url(blob_key, size=None, crop=False)

  Returns a URL that serves the image. This URL format allows dynamic resizing and cropping, so you don't need to store different image sizes on the server. Images are served with low latency from a highly optimized, cookieless infrastructure.

  The URL returned by this method is always public, but not guessable; private URLs are not currently supported. If you wish to stop serving the URL, delete the underlying blob key. This takes up to 24 hours to take effect.

  If you supply the arguments below, this method returns a URL encoded with the arguments specified. If you do not supply any arguments, this method returns the default URL for the image, which you can then modify to get the desired size and crop parameters.

  Arguments:

  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.

  size

    An integer supplying the size of resulting images.

    When resizing or cropping an image, you must specify the new size using an integer 0 to 1600. The maximum size is defined in `IMG_SERVING_SIZES_LIMIT`. The API resizes the image to the supplied value, applying the specified size to the image's longest dimension and preserving the original aspect ratio.

  crop

    Specify `true` for a cropped image, and `false` for a resized image. If you specify true, but do not provide a pixel value from 0–1600, the API raises a BadRequestError.

  URL Modifications:

  =sXX

    To resize an image, append `=sXX` to the end of the image URL, where `XX` is an integer from 0–1600 representing the new image size in pixels. The maximum size is defined in `IMG_SERVING_SIZES_LIMIT`. The API resizes the image to the supplied value, applying the specified size to the image's longest dimension and preserving the original aspect ratio. For example, if you use `=s32` to resize a 1200x1600 image, the resulting image is a 24x32. If that image were 1600x1200, the resized image would be 32x24 pixels.

  =sXX-c

    To crop and resize an image, append `=sXX-c` to the end of the image URL, where `XX` is an integer from 0–1600 representing the new image size in pixels. The maximum size is defined in `IMG_SERVING_SIZES_LIMIT`. The API resizes the image to the supplied value, applying the specified size to the image's longest dimension and preserving the original aspect ratio. If the image is portrait, the API slices evenly from the top and bottom to make a square. If the image is landscape, the API slices evenly from the left and right to make a square. After cropping, the API resizes the image to the specified size.

histogram(image_data)

  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.

horizontal_flip(image_data, output_encoding=images.PNG, quality=None)

  Flips an image horizontally. The edge that was the left becomes the right edge, and vice versa. The function takes the image data to flip, and returns the transformed image in the same format.

  Arguments:

  image_data
    The image to flip, as a bytestring (`str`) in JPEG, PNG, GIF (including animated), BMP, TIFF, or ICO format.
  output_encoding
    The desired format of the transformed image. This is either `images.PNG` or `images.JPEG`. The default is `images.PNG`.
  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 quality control. The default value is 85.

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

im_feeling_lucky(image_data, output_encoding=images.PNG, quality=None)

  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 function takes the image data to adjust, and returns the transformed image in the same format.

  Arguments:

  image_data
    The image to adjust, as a bytestring (`str`) in JPEG, PNG, GIF (including animated), BMP, TIFF, or ICO format.
  output_encoding
    The desired format of the transformed image. This is either `images.PNG` or `images.JPEG`. The default is `images.PNG`.
  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 quality control. The default value is 85.

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

resize(image_data, width=0, height=0, output_encoding=images.PNG, quality=None)

  Resizes an image, scaling down or up to the given width and height. The function takes the image data to resize, and returns the transformed image in the same format.

  Arguments:

  image_data
    The image to resize, as a bytestring (`str`) in JPEG, PNG, GIF (including animated), BMP, TIFF, or ICO format.
  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`.
  output_encoding
    The desired format of the transformed image. This is either `images.PNG` or `images.JPEG`. The default is `images.PNG`.
  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 quality control. The default value is 85.

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

rotate(image_data, degrees, output_encoding=images.PNG, quality=None)

  Rotates an image. The amount of rotation must be a multiple of 90 degrees. The function takes the image data to rotate, and returns the transformed image in the same format.

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

  Arguments:

  image_data
    The image to rotate, as a bytestring (`str`) in JPEG, PNG, GIF (including animated), BMP, TIFF, or ICO format.
  degrees
    The amount to rotate the image, as a number of degrees, in multiples of 90 degrees.
  output_encoding
    The desired format of the transformed image. This is either `images.PNG` or `images.JPEG`. The default is `images.PNG`.
  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 quality control. The default value is 85.

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

vertical_flip(image_data, output_encoding=images.PNG, quality=None)

  Flips an image vertically. The edge that was the top becomes the bottom edge, and vice versa. The function takes the image data to flip, and returns the transformed image in the same format.

  Arguments:

  image_data
    The image to flip, as a bytestring (`str`) in JPEG, PNG, GIF (including animated), BMP, TIFF, or ICO format.
  output_encoding
    The desired format of the transformed image. This is either `images.PNG` or `images.JPEG`. The default is `images.PNG`.
  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 quality control. The default value is 85.

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