java/src/main/com/google/appengine/api/images/ImagesService.java

   1 // Copyright 2009 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.api.images;
   4
   5 import com.google.appengine.api.blobstore.BlobKey;
   6
   7 import java.util.Arrays;
   8 import java.util.Collection;
   9 import java.util.Set;
  10 import java.util.TreeSet;
  11 import java.util.concurrent.Future;
  12
  13 /**
  14  * The images service provides methods to apply transformations to images.
  15  *
  16  */
  17 public interface ImagesService {
  18
  19   public static final int MAX_TRANSFORMS_PER_REQUEST = 10;
  20   public static final int MAX_RESIZE_DIMENSIONS = 4000;
  21   public static final int MAX_COMPOSITES_PER_REQUEST = 16;
  22   public static final int SERVING_SIZES_LIMIT = 1600;
  23
  24   @Deprecated
  25   public static final Set<Integer> SERVING_SIZES = new TreeSet<Integer>(
  26       Arrays.asList(
  27           0, 32, 48, 64, 72, 80, 90, 94, 104, 110, 120, 128, 144,
  28           150, 160, 200, 220, 288, 320, 400, 512, 576, 640, 720,
  29           800, 912, 1024, 1152, 1280, 1440, 1600));
  30
  31   @Deprecated
  32   public static final Set<Integer> SERVING_CROP_SIZES = new TreeSet<Integer>(
  33       Arrays.asList(
  34           32, 48, 64, 72, 80, 104, 136, 144, 150, 160));
  35
  36   /**
  37    * Valid output encoding formats usable for image transforms.
  38    * @see <a href="http://www.libpng.org/pub/png/">PNG Image Format.</a>
  39    * @see <a href="http://en.wikipedia.org/wiki/JPEG">JPEG Image Format.</a>
  40    * @see <a href="http://code.google.com/speed/webp/">WEBP Image Format.</a>
  41    */
  42   public static enum OutputEncoding {PNG, JPEG, WEBP}
  43
  44   /**
  45    * Applies the provided {@code transform} to the provided {@code image}
  46    * encoding the transformed image stored using PNG file format. The
  47    * transform is applied in place to the provided image.
  48    *
  49    * @param transform transform to be applied
  50    * @param image     image to be transformed
  51    * @return transformed image
  52    * @throws IllegalArgumentException If {@code transform} or {@code image}
  53    * are invalid.
  54    * @throws ImagesServiceFailureException If there is a problem with the
  55    * Images Service
  56    */
  57   public Image applyTransform(Transform transform, Image image);
  58
  59   /**
  60    * Asynchronously applies the provided {@code transform} to the
  61    * provided {@code image} encoding the transformed image stored using
  62    * PNG file format. The transform is applied in place to the provided image.
  63    *
  64    * @param transform transform to be applied
  65    * @param image     image to be transformed
  66    * @return A future containing the transformed image or one of the
  67    * exceptions documented for {@link #applyTransform(Transform, Image)}.
  68    */
  69   public Future<Image> applyTransformAsync(Transform transform, Image image);
  70
  71   /**
  72    * Applies the provided {@code transform} to the provided {@code image}
  73    * encoding the transformed image stored using {@code encoding} file
  74    * format. The transform is applied in place to the provided image.
  75    *
  76    * @param transform transform to be applied
  77    * @param image     image to be transformed
  78    * @param encoding  output encoding to be used
  79    * @return transformed image
  80    * @throws IllegalArgumentException If {@code transform}, {@code image} or
  81    * {@code encoding} are invalid.
  82    * @throws ImagesServiceFailureException If there is a problem with the
  83    * Images Service
  84    */
  85   public Image applyTransform(Transform transform, Image image,
  86                               OutputEncoding encoding);
  87
  88   /**
  89    * Asynchronously applies the provided {@code transform} to the provided
  90    * {@code image} encoding the transformed image stored using {@code encoding}
  91    * file format. The transform is applied in place to the provided image.
  92    *
  93    * @param transform transform to be applied
  94    * @param image     image to be transformed
  95    * @param encoding  output encoding to be used
  96    * @return A future containing the transformed image or one of the
  97    * exceptions documented for {@link #applyTransform(Transform, Image, OutputEncoding)}.
  98    */
  99   public Future<Image> applyTransformAsync(Transform transform, Image image,
 100                               OutputEncoding encoding);
 101
 102   /**
 103    * Applies the provided {@code transform} to the provided {@code image}
 104    * encoding the transformed image stored using {@code settings}.
 105    * The transform is applied in place to the provided image.
 106    *
 107    * @param transform transform to be applied
 108    * @param image     image to be transformed
 109    * @param settings output settings to be used
 110    * @return transformed image
 111    * @throws IllegalArgumentException If {@code transform}, {@code image} or
 112    * {@code settings} are invalid.
 113    * @throws ImagesServiceFailureException If there is a problem with the
 114    * Images Service
 115    */
 116   public Image applyTransform(Transform transform, Image image,
 117                               OutputSettings settings);
 118
 119   /**
 120    * Asynchronously applies the provided {@code transform} to the provided
 121    * {@code image} encoding the transformed image stored using {@code settings}.
 122    * The transform is applied in place to the provided image.
 123    *
 124    * @param transform transform to be applied
 125    * @param image     image to be transformed
 126    * @param settings  output settings to be used
 127    * @return A future containing the transformed image or one of the
 128    * exceptions documented for {@link #applyTransform(Transform, Image, OutputSettings)}.
 129    */
 130   public Future<Image> applyTransformAsync(Transform transform, Image image,
 131                                            OutputSettings settings);
 132
 133   /**
 134    * Applies the provided {@code transform} to the provided {@code image}
 135    * encoding the transformed image stored using {@code outputSettings}
 136    * interpreting {@code image} according to {@code inputSettings}.
 137    * The transform is applied in place to the provided image.
 138    *
 139    * @param transform transform to be applied
 140    * @param image     image to be transformed
 141    * @param inputSettings input settings to be used
 142    * @param outputSettings output settings to be used
 143    * @return transformed image
 144    * @throws IllegalArgumentException If {@code transform}, {@code image},
 145    * {@code inputSettings} or {@code outputSettings} are invalid.
 146    * @throws ImagesServiceFailureException If there is a problem with the
 147    * Images Service
 148    */
 149   public Image applyTransform(Transform transform, Image image,
 150                               InputSettings inputSettings, OutputSettings outputSettings);
 151
 152   /**
 153    * Asynchronously applies the provided {@code transform} to the provided
 154    * {@code image} encoding the transformed image stored using {@code settings}
 155    * interpreting {@code image} according to {@code inputSettings}.
 156    * The transform is applied in place to the provided image.
 157    *
 158    * @param transform transform to be applied
 159    * @param image     image to be transformed
 160    * @param inputSettings input settings to be used
 161    * @param outputSettings  output settings to be used
 162    * @return A future containing the transformed image or one of the
 163    * exceptions documented for
 164    * {@link #applyTransform(Transform, Image, InputSettings, OutputSettings)}.
 165    */
 166   public Future<Image> applyTransformAsync(Transform transform, Image image,
 167                                            InputSettings inputSettings,
 168                                            OutputSettings outputSettings);
 169
 170   /**
 171    * Applies the provided {@link Collection} of {@link Composite}s using a
 172    * canvas with dimensions determined by {@code width} and {@code height}
 173    * and background color {@code color}. Uses PNG as its output encoding.
 174    * @param composites Compositing operations to be applied.
 175    * @param width Width of the canvas in pixels.
 176    * @param height Height of the canvas in pixels.
 177    * @param color Background color of the canvas in ARGB format.
 178    * @return A new image containing the result of composition.
 179    * @throws IllegalArgumentException If {@code width} or {@code height} is
 180    * greater than {@value #MAX_RESIZE_DIMENSIONS}, color is outside the range
 181    * [0, 0xffffffff], {@code composites} contains more than
 182    * {@value #MAX_COMPOSITES_PER_REQUEST} elements or something is wrong with
 183    * the contents of {@code composites}.
 184    * @throws ImagesServiceFailureException If there is a problem with the
 185    * Images Service
 186    */
 187   public Image composite(Collection<Composite> composites, int width,
 188                          int height, long color);
 189
 190   /**
 191    * Applies the provided {@link Collection} of {@link Composite}s using a
 192    * canvas with dimensions determined by {@code width} and {@code height}
 193    * and background color {@code color}.
 194    * @param composites Compositing operations to be applied.
 195    * @param width Width of the canvas in pixels.
 196    * @param height Height of the canvas in pixels.
 197    * @param color Background color of the canvas in ARGB format.
 198    * @param encoding Encoding to be used for the resulting image.
 199    * @return A new image containing the result of composition.
 200    * @throws IllegalArgumentException If {@code width} or {@code height} is
 201    * greater than {@value #MAX_RESIZE_DIMENSIONS}, color is outside the range
 202    * [0, 0xffffffff], {@code composites} contains more than
 203    * {@value #MAX_COMPOSITES_PER_REQUEST} elements or something is wrong with
 204    * the contents of {@code composites}.
 205    * @throws ImagesServiceFailureException If there is a problem with the
 206    * Images Service
 207    */
 208   public Image composite(Collection<Composite> composites, int width,
 209                          int height, long color,
 210                          OutputEncoding encoding);
 211
 212   /**
 213    * Applies the provided {@link Collection} of {@link Composite}s using a
 214    * canvas with dimensions determined by {@code width} and {@code height}
 215    * and background color {@code color}.
 216    * @param composites Compositing operations to be applied.
 217    * @param width Width of the canvas in pixels.
 218    * @param height Height of the canvas in pixels.
 219    * @param color Background color of the canvas in ARGB format.
 220    * @param settings OutputSettings to be used for the resulting image.
 221    * @return A new image containing the result of composition.
 222    * @throws IllegalArgumentException If {@code width} or {@code height} is
 223    * greater than {@value #MAX_RESIZE_DIMENSIONS}, color is outside the range
 224    * [0, 0xffffffff], {@code composites} contains more than
 225    * {@value #MAX_COMPOSITES_PER_REQUEST} elements or something is wrong with
 226    * the contents of {@code composites}.
 227    * @throws ImagesServiceFailureException If there is a problem with the
 228    * Images Service
 229    */
 230   public Image composite(Collection<Composite> composites, int width,
 231                          int height, long color,
 232                          OutputSettings settings);
 233
 234   /**
 235    * Calculates the histogram of the image.
 236    *
 237    * @param image image for which to calculate a histogram
 238    * @return An array of 3 arrays of length 256, each containing the image
 239    *   histogram for one color channel. The channels are ordered RGB from
 240    *   entry 0 to 3. Each channel ranges from 0 where the color is not
 241    *   present to 255 where the color is fully bright.
 242    */
 243   public int[][] histogram(Image image);
 244
 245   /**
 246    * Obtains a URL that can serve the image stored as a blob dynamically.
 247    * <p>
 248    * This URL is served by a high-performance dynamic image serving
 249    * infrastructure that is available globally. The URL returned by this method
 250    * is always public, but not guessable; private URLs are not currently
 251    * supported. If you wish to stop serving the URL, delete the underlying blob
 252    * key. This takes up to 24 hours to take effect.
 253    *
 254    * The URL format also allows dynamic resizing and crop with certain
 255    * restrictions. To get dynamic resizing and cropping simply append options to
 256    * the end of the url obtained via this call. Here is an example: {@code
 257    * getServingUrl -> "http://lh3.ggpht.com/SomeCharactersGoesHere"}
 258    * <p>
 259    * To get a 32 pixel sized version (aspect-ratio preserved) simply append
 260    * "=s32" to the url:
 261    * {@code "http://lh3.ggpht.com/SomeCharactersGoesHere=s32"}
 262    * <p>
 263    * To get a 32 pixel cropped version simply append "=s32-c":
 264    * {@code "http://lh3.ggpht.com/SomeCharactersGoesHere=s32-c"}
 265    * <p>
 266    * Valid sizes are any integer in the range [0, 1600] and is available as
 267    * SERVING_SIZES_LIMIT.
 268    *
 269    * @param blobKey blob key of the image to serve by the returned URL.
 270    *
 271    * @return a URL that can serve the image dynamically.
 272    * @throws IllegalArgumentException If blob key is not valid or doesn't contain
 273    * an image.
 274    * @throws ImagesServiceFailureException If there is a problem with the Images Service
 275    *
 276    * @deprecated Replaced by {@link #getServingUrl(ServingUrlOptions)}.
 277    */
 278   @Deprecated
 279   public String getServingUrl(BlobKey blobKey);
 280
 281   /**
 282    * Obtains a URL that can serve the image stored as a blob dynamically.
 283    * <p>
 284    * This URL is served by a high-performance dynamic image serving
 285    * infrastructure that is available globally. The URL returned by this method
 286    * is always public, but not guessable; private URLs are not currently
 287    * supported. If you wish to stop serving the URL, delete the underlying blob
 288    * key. This takes up to 24 hours to take effect.
 289    *
 290    * The URL format also allows dynamic resizing and crop with certain
 291    * restrictions. To get dynamic resizing and cropping simply append options to
 292    * the end of the url obtained via this call. Here is an example: {@code
 293    * getServingUrl -> "http://lh3.ggpht.com/SomeCharactersGoesHere"}
 294    * <p>
 295    * To get a 32 pixel sized version (aspect-ratio preserved) simply append
 296    * "=s32" to the url:
 297    * {@code "http://lh3.ggpht.com/SomeCharactersGoesHere=s32"}
 298    * <p>
 299    * To get a 32 pixel cropped version simply append "=s32-c":
 300    * {@code "http://lh3.ggpht.com/SomeCharactersGoesHere=s32-c"}
 301    * <p>
 302    * Valid sizes are any integer in the range [0, 1600] and is available as
 303    * SERVING_SIZES_LIMIT.
 304    *
 305    * @param blobKey blob key of the image to serve by the returned URL.
 306    * @param secureUrl controls if the url scheme should be https or http.
 307    *
 308    * @return a URL that can serve the image dynamically.
 309    * @throws IllegalArgumentException If blob key is not valid or doesn't contain
 310    * an image.
 311    * @throws ImagesServiceFailureException If there is a problem with the Images Service
 312    *
 313    * @deprecated Replaced by {@link #getServingUrl(ServingUrlOptions)}.
 314    */
 315   @Deprecated
 316   public String getServingUrl(BlobKey blobKey, boolean secureUrl);
 317
 318   /**
 319    * Calculates the serving URL for specific size and crop parameters from
 320    * generic URL returned by {@link #getServingUrl(BlobKey)}.
 321    *
 322    * @param blobKey blob key of the image to serve by the returned URL with
 323    * specified size and crop.
 324    * @param imageSize size of the served image in pixels.
 325    * @param crop controls whether the image should be resized or cropped.
 326    *
 327    * @return a URL that can serve the image dynamically.
 328    * @throws IllegalArgumentException If blob key is not valid or doesn't contain
 329    * an image or specified size is not supported by the service.
 330    * @throws ImagesServiceFailureException If there is a problem with the Images Service
 331    * @see ImagesService#getServingUrl(BlobKey)
 332    *
 333    * @deprecated Replaced by {@link #getServingUrl(ServingUrlOptions)}.
 334    */
 335   @Deprecated
 336   public String getServingUrl(BlobKey blobKey, int imageSize, boolean crop);
 337
 338   /**
 339    * Calculates the serving URL for specific size and crop parameters from
 340    * generic URL returned by {@link #getServingUrl(BlobKey)}.
 341    *
 342    * @param blobKey blob key of the image to serve by the returned URL with
 343    * specified size and crop.
 344    * @param imageSize size of the served image in pixels.
 345    * @param crop controls whether the image should be resized or cropped.
 346    * @param secureUrl controls if the url scheme should be https or http.
 347    *
 348    * @return a URL that can serve the image dynamically.
 349    * @throws IllegalArgumentException If blob key is not valid or doesn't contain
 350    * an image or specified size is not supported by the service.
 351    * @throws ImagesServiceFailureException If there is a problem with the Images Service
 352    * @see ImagesService#getServingUrl(BlobKey)
 353    *
 354    * @deprecated Replaced by {@link #getServingUrl(ServingUrlOptions)}.
 355    */
 356   @Deprecated
 357   public String getServingUrl(BlobKey blobKey, int imageSize, boolean crop, boolean secureUrl);
 358
 359   /**
 360    * Obtains a URL that can dynamically serve the image stored as a blob.
 361    * <p>
 362    * This URL is served by a high-performance dynamic image serving
 363    * infrastructure that is available globally. The URL returned by this method
 364    * is always public, but not guessable; private URLs are not currently
 365    * supported. If you wish to stop serving the URL, delete the underlying blob
 366    * key. This takes up to 24 hours to take effect.
 367    *
 368    * The URL format also allows dynamic resizing and crop with certain
 369    * restrictions. To get dynamic resizing and cropping simply append options to
 370    * the end of the url obtained via this call. Here is an example: {@code
 371    * getServingUrl -> "http://lh3.ggpht.com/SomeCharactersGoesHere"}
 372    * <p>
 373    * To get a 32 pixel sized version (aspect-ratio preserved) simply append
 374    * "=s32" to the url:
 375    * {@code "http://lh3.ggpht.com/SomeCharactersGoesHere=s32"}
 376    * <p>
 377    * To get a 32 pixel cropped version simply append "=s32-c":
 378    * {@code "http://lh3.ggpht.com/SomeCharactersGoesHere=s32-c"}
 379    * <p>
 380    * Valid sizes are any integer in the range [0, 1600] (maximum is available as
 381    * {@link #SERVING_SIZES_LIMIT}).
 382    *
 383    * @param options Specific options for generating the serving URL.
 384    *
 385    * @return a URL that can serve the image dynamically.
 386    * @throws IllegalArgumentException If options does not contain a valid blobKey or
 387    * googleStorageFileName.
 388    * @throws ImagesServiceFailureException If there is a problem with the Images Service
 389    */
 390   public String getServingUrl(ServingUrlOptions options);
 391
 392   /**
 393    * Deletes a URL that was previously generated by {@code getServingUrl(BlobKey)}.
 394    *
 395    * @param blobKey blob key that was previously used in the call to create the
 396    * serving URL.
 397    *
 398    * @throws IllegalArgumentException If blob key is not valid.
 399    */
 400   public void deleteServingUrl(BlobKey blobKey);
 401 }