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

   1 // Copyright 2012 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.Collection;
   8
   9 /**
  10  * Factory for creating an {@link ImagesService}, {@link Image}s and
  11  * {@link Transform}s.
  12  *
  13  */
  14 public interface IImagesServiceFactory {
  15
  16   /**
  17    * Creates an implementation of the ImagesService.
  18    * @return an images service
  19    */
  20    ImagesService getImagesService();
  21
  22   /**
  23    * Creates an image from the provided {@code imageData}.
  24    * @param imageData image data to store in the image
  25    * @return an Image containing the supplied image data
  26    * @throws IllegalArgumentException If {@code imageData} is null or empty.
  27    */
  28    Image makeImage(byte[] imageData);
  29
  30   /**
  31    * Create an image backed by the specified {@code blobKey}.  Note
  32    * that the returned {@link Image} object can be used with all
  33    * {@link ImagesService} methods, but most of the methods on the
  34    * Image itself will currently throw {@link
  35    * UnsupportedOperationException}.
  36    *
  37    * @param blobKey referencing the image
  38    * @return an Image that references the specified blob data
  39    */
  40    Image makeImageFromBlob(BlobKey blobKey);
  41
  42   /**
  43    * Create an image backed by the specified {@code filename}. Note
  44    * that the returned {@link Image} object can be used with all
  45    * {@link ImagesService} methods, but most of the methods on the
  46    * Image itself will currently throw {@link
  47    * UnsupportedOperationException}.
  48    *
  49    * @param filename referencing the image. Currently only Google Storage files
  50    * in the format "/gs/bucket_name/object_name" are supported.
  51    * @return an Image that references the specified blob data
  52    * @throws IllegalArgumentException If {@code filename} is not in the format
  53    * "/gs/bucket_name/object_name".
  54    * @throws BlobstoreFailureException If there is an error obtaining the Google
  55    * Storage access token for the {@code filename}.
  56    */
  57    Image makeImageFromFilename(String filename);
  58
  59   /**
  60    * Creates a transform that will resize an image to fit within a box with
  61    * width {@code width} and height {@code height}.
  62    * @param width width of the bounding box
  63    * @param height height of the bounding box
  64    * @return a resize transform
  65    * @throws IllegalArgumentException If {@code width} or {@code height} are
  66    * negative or greater than {@code MAX_RESIZE_DIMENSIONS} or if both
  67    * {@code width} and {@code height} are 0.
  68    */
  69    Transform makeResize(int width, int height);
  70
  71   /**
  72    * Creates a resize transform that will resize an image to fit within a box
  73    * of width {@code width} and height {@code height}. If {@code allowStretch}
  74    * is {@code true}, the aspect ratio of the original image will be ignored.
  75    *
  76    * @param width width of the bounding box
  77    * @param height height of the bounding box
  78    * @param allowStretch allow the image to be resized ignoring the aspect ratio
  79    * @return a resize transform
  80    * @throws IllegalArgumentException If {@code width} or {@code height} are negative or greater
  81    *         than {@code MAX_RESIZE_DIMENSIONS}, if both {@code width} and {@code height} are 0 or
  82    *         if {@code allowStretch} is True and either {@code width} or {@code height} are 0.
  83    */
  84    Transform makeResize(int width, int height, boolean allowStretch);
  85
  86   /**
  87    * Creates a transform that will resize an image to exactly fit a box with
  88    * width {@code width} and height {@code height} by resizing to the less
  89    * constraining dimension and cropping the other. The center of the crop
  90    * region is controlled by {@code cropOffsetX} and {@code cropOffsetY}.
  91    * @param width width of the bounding box
  92    * @param height height of the bounding box
  93    * @param cropOffsetX the relative horizontal position of the center
  94    * @param cropOffsetY the relative vertical position of the center
  95    * @return a resize transform
  96    * @throws IllegalArgumentException If {@code width} or {@code height} are
  97    * negative or greater than {@code MAX_RESIZE_DIMENSIONS}, if either of
  98    * {@code width} and {@code height} are 0 or if {@code cropOffsetX} or
  99    * {@code cropOffsetY} are outside the range 0.0 to 1.0.
 100    */
 101    Transform makeResize(int width, int height, float cropOffsetX, float cropOffsetY);
 102
 103   /**
 104    * Creates a transform that will resize an image to exactly fit a box with
 105    * width {@code width} and height {@code height} by resizing to the less
 106    * constraining dimension and cropping the other. The center of the crop
 107    * region is controlled by {@code cropOffsetX} and {@code cropOffsetY}.
 108    * @param width width of the bounding box
 109    * @param height height of the bounding box
 110    * @param cropOffsetX the relative horizontal position of the center
 111    * @param cropOffsetY the relative vertical position of the center
 112    * @return a resize transform
 113    * @throws IllegalArgumentException If {@code width} or {@code height} are
 114    * negative or greater than {@code MAX_RESIZE_DIMENSIONS}, if either of
 115    * {@code width} and {@code height} are 0 or if {@code cropOffsetX} or
 116    * {@code cropOffsetY} are outside the range 0.0 to 1.0.
 117    */
 118    Transform makeResize(int width, int height, double cropOffsetX,
 119                                      double cropOffsetY);
 120
 121   /**
 122    * Creates a transform that will crop an image to fit within the bounding
 123    * box specified.
 124    *
 125    * The arguments define the top left and bottom right corners of the
 126    * bounding box used to crop the image as a percentage of the total image
 127    * size. Each argument should be in the range 0.0 to 1.0 inclusive.
 128    * @param leftX X coordinate of the top left corner of the bounding box
 129    * @param topY Y coordinate of the top left corner of the bounding box
 130    * @param rightX X coordinate of the bottom right corner of the bounding box
 131    * @param bottomY Y coordinate of the bottom right corner of the bounding box
 132    * @return a crop transform
 133    * @throws IllegalArgumentException If any of the arguments are outside the
 134    * range 0.0 to 1.0 or if {@code leftX >= rightX} or {@code topY >= bottomY}.
 135    */
 136    Transform makeCrop(float leftX, float topY, float rightX,
 137                                    float bottomY);
 138
 139   /**
 140    * Creates a transform that will crop an image to fit within the bounding
 141    * box specified.
 142    *
 143    * The arguments define the top left and bottom right corners of the
 144    * bounding box used to crop the image as a percentage of the total image
 145    * size. Each argument should be in the range 0.0 to 1.0 inclusive.
 146    * @param leftX X coordinate of the top left corner of the bounding box
 147    * @param topY Y coordinate of the top left corner of the bounding box
 148    * @param rightX X coordinate of the bottom right corner of the bounding box
 149    * @param bottomY Y coordinate of the bottom right corner of the bounding box
 150    * @return a crop transform
 151    * @throws IllegalArgumentException If any of the arguments are outside the
 152    * range 0.0 to 1.0 or if {@code leftX >= rightX} or {@code topY >= bottomY}.
 153    */
 154    Transform makeCrop(double leftX, double topY,
 155                                    double rightX, double bottomY);
 156
 157   /**
 158    * Creates a transform that will vertically flip an image.
 159    * @return a vertical flip transform
 160    */
 161    Transform makeVerticalFlip();
 162
 163   /**
 164    * Creates a transform that will horizontally flip an image.
 165    * @return a horizontal flip transform
 166    */
 167    Transform makeHorizontalFlip();
 168
 169   /**
 170    * Creates a transform that rotates an image by {@code degrees} degrees
 171    * clockwise.
 172    *
 173    * @param degrees The number of degrees by which to rotate. Must be a
 174    *                multiple of 90.
 175    * @return a rotation transform
 176    * @throws IllegalArgumentException If {@code degrees} is not divisible by 90
 177    */
 178    Transform makeRotate(int degrees);
 179
 180   /**
 181    * Creates a transform that automatically adjust contrast and color levels.
 182    *
 183    * This is similar to the "I'm Feeling Lucky" button in Picasa.
 184    * @return an ImFeelingLucky autolevel transform
 185    */
 186    Transform makeImFeelingLucky();
 187
 188   /**
 189    * Creates a composite transform that can represent multiple transforms
 190    * applied in series.
 191    *
 192    * @param transforms Transforms for this composite transform to apply.
 193    * @return a composite transform containing the provided transforms
 194    */
 195    CompositeTransform makeCompositeTransform(
 196       Collection<Transform> transforms);
 197
 198   /**
 199    * Creates a composite transform that can represent multiple transforms
 200    * applied in series.
 201    * @return an empty composite transform
 202    */
 203    CompositeTransform makeCompositeTransform();
 204
 205   /**
 206    * Creates an image composition operation.
 207    * @param image The image to be composited.
 208    * @param xOffset Offset in the x axis from the anchor point.
 209    * @param yOffset Offset in the y axis from the anchor point.
 210    * @param opacity Opacity to be used for the image in range [0.0, 1.0].
 211    * @param anchor Anchor position from the enum {@link Composite.Anchor}.
 212    * The anchor position of the image is aligned with the anchor position of
 213    * the canvas and then the offsets are applied.
 214    * @return A composition operation.
 215    * @throws IllegalArgumentException If {@code image} is null or empty,
 216    * {@code xOffset} or {@code yOffset} is outside the range
 217    * [-{@value
 218    * com.google.appengine.api.images.ImagesService#MAX_RESIZE_DIMENSIONS},
 219    * {@value
 220    * com.google.appengine.api.images.ImagesService#MAX_RESIZE_DIMENSIONS}],
 221    * {@code opacity} is outside the range [0.0, 1.0] or {@code anchor} is null.
 222    */
 223    Composite makeComposite(Image image, int xOffset, int yOffset,
 224                                         float opacity,
 225                                         Composite.Anchor anchor);
 226 }