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