com.google.appengine.api.images
Interface ImagesService

public interface ImagesService

The images service provides methods to apply transformations to images.

Nested Class Summary

static class

ImagesService.OutputEncoding Valid output encoding formats usable for image transforms.

Field Summary

static int	MAX_COMPOSITES_PER_REQUEST
static int	MAX_RESIZE_DIMENSIONS
static int	MAX_TRANSFORMS_PER_REQUEST
static java.util.Set<java.lang.Integer>	SERVING_CROP_SIZES Valid sizes for crop operation with URLs from getServingUrl(BlobKey) and getServingUrl(BlobKey, int, boolean).
static java.util.Set<java.lang.Integer>	SERVING_SIZES Valid sizes for resize operation with URLs from getServingUrl(BlobKey) and getServingUrl(BlobKey, int, boolean).

Method Summary

Image	applyTransform(Transform transform, Image image) Applies the provided transform to the provided image encoding the transformed image stored using PNG file format.
Image	applyTransform(Transform transform, Image image, ImagesService.OutputEncoding encoding) Applies the provided transform to the provided image encoding the transformed image stored using encoding file format.
Image	applyTransform(Transform transform, Image image, OutputSettings settings) Applies the provided transform to the provided image encoding the transformed image stored using settings.
java.util.concurrent.Future<Image>	applyTransformAsync(Transform transform, Image image) Asynchronously applies the provided transform to the provided image encoding the transformed image stored using PNG file format.
java.util.concurrent.Future<Image>	applyTransformAsync(Transform transform, Image image, ImagesService.OutputEncoding encoding) Asynchronously applies the provided transform to the provided image encoding the transformed image stored using encoding file format.
java.util.concurrent.Future<Image>	applyTransformAsync(Transform transform, Image image, OutputSettings settings) Asynchronously applies the provided transform to the provided image encoding the transformed image stored using settings.
Image	composite(java.util.Collection<Composite> composites, int width, int height, long color) Applies the provided Collection of Composites using a canvas with dimensions determined by width and height and background color color.
Image	composite(java.util.Collection<Composite> composites, int width, int height, long color, ImagesService.OutputEncoding encoding) Applies the provided Collection of Composites using a canvas with dimensions determined by width and height and background color color.
Image	composite(java.util.Collection<Composite> composites, int width, int height, long color, OutputSettings settings) Applies the provided Collection of Composites using a canvas with dimensions determined by width and height and background color color.
java.lang.String	getServingUrl(BlobKey blobKey) Obtains a URL that can serve the image stored as a blob dynamically.
java.lang.String	getServingUrl(BlobKey blobKey, int imageSize, boolean crop) Calculates the serving URL for specific size and crop parameters from generic URL returned by getServingUrl(BlobKey).
int[][]	histogram(Image image) Calculates the histogram of the image.

Field Detail

MAX_TRANSFORMS_PER_REQUEST

static final int MAX_TRANSFORMS_PER_REQUEST

See Also:

Constant Field Values

MAX_RESIZE_DIMENSIONS

static final int MAX_RESIZE_DIMENSIONS

See Also:

Constant Field Values

MAX_COMPOSITES_PER_REQUEST

static final int MAX_COMPOSITES_PER_REQUEST

See Also:

Constant Field Values

SERVING_SIZES

static final java.util.Set<java.lang.Integer> SERVING_SIZES

Valid sizes for resize operation with URLs from getServingUrl(BlobKey) and getServingUrl(BlobKey, int, boolean).

Values: 0, 32, 48, 64, 72, 80, 90, 94, 104, 110, 120, 128, 144, 150, 160, 200, 220, 288, 320, 400, 512, 576, 640, 720, 800, 912, 1024, 1152, 1280, 1440, 1600

SERVING_CROP_SIZES

static final java.util.Set<java.lang.Integer> SERVING_CROP_SIZES

Valid sizes for crop operation with URLs from getServingUrl(BlobKey) and getServingUrl(BlobKey, int, boolean).

Values: 32, 48, 64, 72, 80, 104, 136, 144, 150, 160

Method Detail

applyTransform

Image applyTransform(Transform transform,
                     Image image)

Applies the provided transform to the provided image encoding the transformed image stored using PNG file format. The transform is applied in place to the provided image.

Parameters:

transform - transform to be applied

image - image to be transformed

Returns:

transformed image

Throws:

java.lang.IllegalArgumentException - If transform or image are invalid.

ImagesServiceFailureException - If there is a problem with the Images Service

applyTransformAsync

java.util.concurrent.Future<Image> applyTransformAsync(Transform transform,
                                                       Image image)

Asynchronously applies the provided transform to the provided image encoding the transformed image stored using PNG file format. The transform is applied in place to the provided image.

Parameters:

transform - transform to be applied

image - image to be transformed

Returns:

A future containing the transformed image or one of the exceptions documented for applyTransform(Transform, Image).

applyTransform

Image applyTransform(Transform transform,
                     Image image,
                     ImagesService.OutputEncoding encoding)

Applies the provided transform to the provided image encoding the transformed image stored using encoding file format. The transform is applied in place to the provided image.

Parameters:

transform - transform to be applied

image - image to be transformed

encoding - output encoding to be used

Returns:

transformed image

Throws:

java.lang.IllegalArgumentException - If transform, image or encoding are invalid.

ImagesServiceFailureException - If there is a problem with the Images Service

applyTransformAsync

java.util.concurrent.Future<Image> applyTransformAsync(Transform transform,
                                                       Image image,
                                                       ImagesService.OutputEncoding encoding)

Asynchronously applies the provided transform to the provided image encoding the transformed image stored using encoding file format. The transform is applied in place to the provided image.

Parameters:

transform - transform to be applied

image - image to be transformed

encoding - output encoding to be used

Returns:

A future containing the transformed image or one of the exceptions documented for applyTransformAsync(Transform, Image, OutputEncoding).

applyTransform

Image applyTransform(Transform transform,
                     Image image,
                     OutputSettings settings)

Applies the provided transform to the provided image encoding the transformed image stored using settings. The transform is applied in place to the provided image.

Parameters:

transform - transform to be applied

image - image to be transformed

settings - output settings to be used

Returns:

transformed image

Throws:

java.lang.IllegalArgumentException - If transform, image or settings are invalid.

ImagesServiceFailureException - If there is a problem with the Images Service

applyTransformAsync

java.util.concurrent.Future<Image> applyTransformAsync(Transform transform,
                                                       Image image,
                                                       OutputSettings settings)

Asynchronously applies the provided transform to the provided image encoding the transformed image stored using settings. The transform is applied in place to the provided image.

Parameters:

transform - transform to be applied

image - image to be transformed

settings - output settings to be used

Returns:

A future containing the transformed image or one of the exceptions documented for applyTransformAsync(Transform, Image, OutputSettings).

composite

Image composite(java.util.Collection<Composite> composites,
                int width,
                int height,
                long color)

Applies the provided Collection of Composites using a canvas with dimensions determined by width and height and background color color. Uses PNG as its output encoding.

Parameters:

composites - Compositing operations to be applied.

width - Width of the canvas in pixels.

height - Height of the canvas in pixels.

color - Background color of the canvas in ARGB format.

Returns:

A new image containing the result of composition.

Throws:

java.lang.IllegalArgumentException - If width or height is greater than 4000, color is outside the range [0, 0xffffffff], composites contains more than 16 elements or something is wrong with the contents of composites.

ImagesServiceFailureException - If there is a problem with the Images Service

composite

Image composite(java.util.Collection<Composite> composites,
                int width,
                int height,
                long color,
                ImagesService.OutputEncoding encoding)

Applies the provided Collection of Composites using a canvas with dimensions determined by width and height and background color color.

Parameters:

composites - Compositing operations to be applied.

width - Width of the canvas in pixels.

height - Height of the canvas in pixels.

color - Background color of the canvas in ARGB format.

encoding - Encoding to be used for the resulting image.

Returns:

A new image containing the result of composition.

Throws:

java.lang.IllegalArgumentException - If width or height is greater than 4000, color is outside the range [0, 0xffffffff], composites contains more than 16 elements or something is wrong with the contents of composites.

ImagesServiceFailureException - If there is a problem with the Images Service

composite

Image composite(java.util.Collection<Composite> composites,
                int width,
                int height,
                long color,
                OutputSettings settings)

Applies the provided Collection of Composites using a canvas with dimensions determined by width and height and background color color.

Parameters:

composites - Compositing operations to be applied.

width - Width of the canvas in pixels.

height - Height of the canvas in pixels.

color - Background color of the canvas in ARGB format.

settings - OutputSettings to be used for the resulting image.

Returns:

A new image containing the result of composition.

Throws:

java.lang.IllegalArgumentException - If width or height is greater than 4000, color is outside the range [0, 0xffffffff], composites contains more than 16 elements or something is wrong with the contents of composites.

ImagesServiceFailureException - If there is a problem with the Images Service

histogram

int[][] histogram(Image image)

Calculates the histogram of the image.

Parameters:

image - image for which to calculate a histogram

Returns:

An array of 3 arrays of length 256, each containing the image histogram for one color channel. The channels are ordered RGB from entry 0 to 3. Each channel ranges from 0 where the color is not present to 255 where the color is fully bright.

getServingUrl

java.lang.String getServingUrl(BlobKey blobKey)

Obtains a URL that can serve the image stored as a blob dynamically.

This URL is served by a high-performance dynamic image serving infrastructure that is available globally. 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. The URL format also allows dynamic resizing and crop with certain restrictions. To get dynamic resizing and cropping simply append options to the end of the url obtained via this call. Here is an example: getServingUrl -> "http://lh3.ggpht.com/SomeCharactersGoesHere"

To get a 32 pixel sized version (aspect-ratio preserved) simply append "=s32" to the url: "http://lh3.ggpht.com/SomeCharactersGoesHere=s32"

To get a 32 pixel cropped version simply append "=s32-c": "http://lh3.ggpht.com/SomeCharactersGoesHere=s32-c"

Valid sizes are also available as SERVING_SIZES and SERVING_CROP_SIZES sets.

Parameters:

blobKey - blob key of the image to serve by the returned URL.

Returns:

a URL that can serve the image dynamically.

Throws:

java.lang.IllegalArgumentException - If blob key is not valid or doesn't contain an image.

ImagesServiceFailureException - If there is a problem with the Images Service

getServingUrl

java.lang.String getServingUrl(BlobKey blobKey,
                               int imageSize,
                               boolean crop)

Calculates the serving URL for specific size and crop parameters from generic URL returned by getServingUrl(BlobKey).

Parameters:

blobKey - blob key of the image to serve by the returned URL with specified size and crop.

imageSize - size of the served image in pixels.

crop - controls whether the image should be resized or cropped.

Returns:

a URL that can serve the image dynamically.

Throws:

java.lang.IllegalArgumentException - If blob key is not valid or doesn't contain an image or specified size is not supported by the service.

ImagesServiceFailureException - If there is a problem with the Images Service

See Also:

getServingUrl(BlobKey)