App Engine provides the ability to manipulate image data using a dedicated Images service. The Images service can resize, rotate, flip, and crop images; it can composite multiple images into a single image; and it can convert image data between several formats. It can also enhance photographs using a predefined algorithm. The API can also provide information about an image, such as its format, width, height, and a histogram of color values.
The Images service can accept image data directly from the app, or it can use a Blobstore value or a Google Cloud Storage value. When the source is the Blobstore or Google Cloud Storage, the size of the image to transform can be up to the maximum size of a Blobstore value or Google Cloud Storage value. However, the transformed image is returned directly to the app, and so must be no larger than 32 megabytes. This is potentially useful for making thumbnail images of photographs uploaded to the Blobstore or Google Cloud Storage by users.
- Transforming images in Java
- Available image transformations
- Image formats
- Transforming images from the Blobstore
- Images and the development server
- Quotas and limits
Transforming images in Java
The Image service Java API lets you apply transformations to images, using a service instead of performing image processing on the application server. The app prepares an
Image
object with the image data to transform, and a
Transform
object with instructions on how to transform the image. The app gets an
ImagesService
object, then calls its
applyTransform()
method with the
Image
and the
Transform
objects. The method returns an
Image
object of the transformed image.
The app gets
ImagesService
,
Image
and
Transform
instances using the
ImagesServiceFactory
.
import com.google.appengine.api.images.Image;
import com.google.appengine.api.images.ImagesService;
import com.google.appengine.api.images.ImagesServiceFactory;
import com.google.appengine.api.images.Transform;
// ...
byte[] oldImageData; // ...
ImagesService imagesService = ImagesServiceFactory.getImagesService();
Image oldImage = ImagesServiceFactory.makeImage(oldImageData);
Transform resize = ImagesServiceFactory.makeResize(200, 300);
Image newImage = imagesService.applyTransform(resize, oldImage);
byte[] newImageData = newImage.getImageData();
Multiple transforms can be combined into a single action using a
CompositeTransform
instance. See
the images API reference
.
Available image transformations
The Images service can resize, rotate, flip, and crop images, and enhance photographs. It can also composite multiple images into a single image.
Resize
You can resize the image while maintaining the same aspect ratio. Neither the width nor the height of the resized image can exceed 4000 pixels.
Rotate
You can rotate the image in 90 degree increments.
Flip horizontally
You can flip the image horizontally.
Flip vertically
You can flip the image vertically.
Crop
You can crop the image with a given bounding box.
I'm Feeling Lucky
The "I'm Feeling Lucky" transform enhances dark and bright colors in an image and adjusts both color and contrast to optimal levels.
Image formats
The service accepts image data in the JPEG, PNG, WEBP, GIF (including animated GIF), BMP, TIFF and ICO formats.
It can return transformed images in the JPEG, WEBP and PNG formats. If the input format and the output format are different, the service converts the input data to the output format before performing the transformation.
Transforming images from the Blobstore
The Images service can use a value from the Blobstore as the source for a transformation. You have two ways to transform images from the Blobstore:
- Using the ImageServiceFactory() class allows you to perform simple image transformations, such as crop, flip, and rotate.
- Using getServingUrl() allows you to dynamically resize and crop images, so you don't need to store different image sizes on the server. This method returns a URL that serves the image, and transformations to the image are encoded in this URL.
Using the ImageServiceFactory() Class
You can transform images from the Blobstore as long as the image size is smaller than the maximum Blobstore value size. Note, however, that the result of the transformation is returned directly to the app, and must therefore not exceed the API response limit of 32 megabytes. You can use this to make thumbnail images of photographs uploaded by users.
To transform an image from the Blobstore in Java, you create the
Image
object by calling the static method
ImageServiceFactory.makeImageFromBlob()
, passing it a
blobstore.BlobKey
value. The rest of the API behaves as expected. The
applyTransform()
method returns the result of the transforms, or throws an
ImageServiceFailureException
if the result is larger than the maximum size of 32 megabytes.
import com.google.appengine.api.images.Image;
import com.google.appengine.api.images.ImagesService;
import com.google.appengine.api.images.ImagesServiceFactory;
import com.google.appengine.api.images.Transform;
// ...
BlobKey blobKey; // ...
ImagesService imagesService = ImagesServiceFactory.getImagesService();
Image oldImage = ImagesServiceFactory.makeImageFromBlob(blobKey);
Transform resize = ImagesServiceFactory.makeResize(200, 300);
Image newImage = imagesService.applyTransform(resize, oldImage);
byte[] newImageData = newImage.getImageData();
Using getServingUrl()
The getServingUrl() method allows you to generate a stable, dedicated URL for serving web-suitable image thumbnails. You simply store a single copy of your original image in Blobstore, and then request a high-performance per-image URL. This special URL can serve that image resized and/or cropped automatically, and serving from this URL does not incur any CPU or dynamic serving load on your application (though bandwidth is still charged as usual). 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 it using the deleteServingUrl method.
If you supply the arguments, 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, for example:
http://your_app_id.appspot.com/randomStringImageId
You can then add arguments to this URL to get the desired size and crop parameters. The available arguments are:
-
=sxx
wherexx
is an integer from 0–1600 representing the length, in pixels, of the image's longest side. For example, adding=s32
resizes the image so its longest dimension is 32 pixels. -
=sxx-c
where xx is an integer from 0–1600 representing the cropped image size in pixels, and-c
tells the system to crop the image.
// Resize the image to 32 pixels (aspect-ratio preserved) http://your_app_id.appspot.com/randomStringImageId=s32 // Crop the image to 32 pixels http://your_app_id.appspot.com/randomStringImageId=s32-c
Images and the development server
The development server uses your local machine to perform the capabilities of the Images service.
The Java development server uses the ImageIO framework to simulate the Image service. The "I'm Feeling Lucky" photo enhancement feature is not supported. The WEBP image format is only supported if a suitable decoder plugin has been installed. The Java VP8 decoder plugin can be used, for example.
Quotas and limits
Each Images service request counts toward the Image Manipulation API Calls quota. An app can perform multiple transformations of an image in a single API call.
Data sent to the Images service counts toward the Data Sent to (Images) API quota. Data received from the Images service counts toward the Data Received from (Images) API quota.
Each transformation of an image counts toward the Transformations Executed quota.
For more information on quotas, see Quotas , and the "Quota Details" section of the Admin Console .
In addition to quotas, the following limits apply to the use of the Images service:
Limit | Amount |
---|---|
maximum data size of image sent to service | 32 megabytes |
maximum data size of image received from service | 32 megabytes |
maximum size of image sent or received from service | 50 megapixels |