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.

You can also execute transformations asynchronously by invoking execute_transforms_async() .

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

1. Introduction
2. Image()
3. Properties:
   • width
   • height
4. Instance methods:
   • crop()
   • execute_transforms()
   • execute_transforms_async()
   • get_original_metadata()
   • 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 the execute_transforms() or execute_transforms_async() method.

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

Constructor

class Image ( image_data = None , blob_key = None , filename = 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 , or a Google Cloud Storage image file name of 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, file_name must be provided, or else this raises BlobKeyRequiredError .

file_name

A Google Cloud Storage image file name. If not provided, blob_key must be provided, or else this 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 , parse_source_metadata = False , transparent_substitution_rgb = 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.

parse_source_metadata

If you set this to True, the metadata (Exif) of the source image is parsed before any transformations are applied. (You can see the results of the parsing by invoking get_original_metadata .)

transparent_substitution_rgb

If transparent pixels are not supported in the destination image format, the default is to substitute black. You can replace this default color with another substitution by specifying it in 32-bit RGB format.

execute_transforms_async ( output_encoding = images.PNG , quality = None , parse_source_metadata = False , transparent_substitution_rgb = None , rpc = None )

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

parse_source_metadata

If you set this to True, the metadata (Exif) of the source image is parsed before any transformations are applied. (You can see the results of the parsing by invoking get_original_metadata .)

transparent_substitution_rgb

If transparent pixels are not supported in the destination image format, the default is to substitute black. You can replace this default color with another substitution by specifying it in 32-bit RGB format.

rpc

The Images service RPC object used for asynchronous operation.

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 in pixels. Must be an int or long .

height

The desired height in 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.

Except as otherwise noted, the content of this page is licensed under the Creative Commons Attribution 3.0 License , and code samples are licensed under the Apache 2.0 License . For details, see our Site Policies .