fixing refdocs for comments, and adding error for incorrect call to outpainting

Author: David Motsonashvili

firebase-ai/src/main/kotlin/com/google/firebase/ai/ImagenModel.kt

@@ -93,8 +93,8 @@ internal constructor(
    * Generates an image from a single or set of base images, returning the result directly to the
    * caller.
    *
-   * @param prompt the text input given to the model as a prompt
    * @param referenceImages the image inputs given to the model as a prompt
+   * @param prompt the text input given to the model as a prompt
    * @param config the editing configuration settings
    */
   public suspend fun editImage(
@@ -112,12 +112,14 @@ internal constructor(
     }
 
   /**
-   * Generates an image by inpainting a masked off part of a base image.
+   * Generates an image by inpainting a masked off part of a base image. Inpainting is the process
+   * of filling in missing or masked off parts of the image using context from the original image
+   * and prompt.
    *
    * @param image the base image
    * @param prompt the text input given to the model as a prompt
-   * @param mask the mask which defines where in the image can be painted by imagen.
-   * @param config the editing configuration settings, its important to include an [ImagenEditMode]
+   * @param mask the mask which defines where in the image can be painted by Imagen.
+   * @param config the editing configuration settings, it should include an [ImagenEditMode]
    */
   public suspend fun inpaintImage(
     image: ImagenInlineImage,
@@ -129,15 +131,16 @@ internal constructor(
   }
 
   /**
-   * Generates an image by outpainting the image, extending its borders
+   * Generates an image by outpainting the given image, extending its content beyond the original
+   * borders using context from the original image, and optionally, the prompt.
    *
    * @param image the base image
    * @param newDimensions the new dimensions for the image, *must* be larger than the original
    * image.
    * @param newPosition the placement of the base image within the new image. This can either be
    * coordinates (0,0 is the top left corner) or an alignment (ex:
    * [ImagenImagePlacement.BOTTOM_CENTER])
-   * @param prompt optional, but can be used to specify the background generated if context is
+   * @param prompt optional, can be used to specify the background generated if context is
    * insufficient
    * @param config the editing configuration settings
    * @see [ImagenMaskReference.generateMaskAndPadForOutpainting]

firebase-ai/src/main/kotlin/com/google/firebase/ai/java/ImagenModelFutures.kt

@@ -65,7 +65,7 @@ public abstract class ImagenModelFutures internal constructor() {
    * @param image the base image
    * @param prompt the text input given to the model as a prompt
    * @param mask the mask which defines where in the image can be painted by imagen.
-   * @param config the editing configuration settings, its important to include an [ImagenEditMode]
+   * @param config the editing configuration settings, it should include an [ImagenEditMode]
    */
   public abstract fun inpaintImage(
     image: ImagenInlineImage,

firebase-ai/src/main/kotlin/com/google/firebase/ai/type/ImagenControlType.kt

@@ -18,17 +18,15 @@ package com.google.firebase.ai.type
 /** Represents a control type for controlled Imagen generation/editing */
 public class ImagenControlType internal constructor(internal val value: String) {
   public companion object {
-    /** Canny Control uses edge detection to ensure the new image follow the same outlines */
+    /** Use edge detection to ensure the new image follow the same outlines */
     public val CANNY: ImagenControlType = ImagenControlType("CONTROL_TYPE_CANNY")
-    /**
-     * Scribble Control uses enhanced edge detection to ensure the new image follow similar outlines
-     */
+    /** Use enhanced edge detection to ensure the new image follow similar outlines */
     public val SCRIBBLE: ImagenControlType = ImagenControlType("CONTROL_TYPE_SCRIBBLE")
-    /** Face mesh control is used to ensure that the new image has the same facial expressions */
+    /** Use face mesh control to ensure that the new image has the same facial expressions */
     public val FACE_MESH: ImagenControlType = ImagenControlType("CONTROL_TYPE_FACE_MESH")
     /**
-     * Color superpixels are a control mechanism used to ensure that the new image looks similar in
-     * shape and color to the original
+     * Use color superpixels to ensure that the new image is similar in shape and color to the
+     * original
      */
     public val COLOR_SUPERPIXEL: ImagenControlType =
       ImagenControlType("CONTROL_TYPE_COLOR_SUPERPIXEL")

firebase-ai/src/main/kotlin/com/google/firebase/ai/type/ImagenEditMode.kt

@@ -19,14 +19,11 @@ package com.google.firebase.ai.type
 public class ImagenEditMode private constructor(internal val value: String) {
 
   public companion object {
-    /** Inpainting insertion is used when inserting a new element into an image */
+    /** Inserts a new element into an image */
     public val INPAINT_INSERTION: ImagenEditMode = ImagenEditMode("EDIT_MODE_INPAINT_INSERTION")
-    /**
-     * Inpainting removal is used when removing an element from an image, and replacing it with
-     * background
-     */
+    /** Removes an element from an image */
     public val INPAINT_REMOVAL: ImagenEditMode = ImagenEditMode("EDIT_MODE_INPAINT_REMOVAL")
-    /** Outpainting is used to extend the borders of an image outwards */
+    /** Extend the borders of an image outwards */
     public val OUTPAINT: ImagenEditMode = ImagenEditMode("EDIT_MODE_OUTPAINT")
   }
 }

firebase-ai/src/main/kotlin/com/google/firebase/ai/type/ImagenImagePlacement.kt

@@ -16,8 +16,8 @@
 package com.google.firebase.ai.type
 
 /**
- * Represents where the placement of an image within a new, larger image, usually in the context of
- * an outpainting request.
+ * Represents where the placement of an image is within a new, larger image, usually in the context
+ * of an outpainting request.
  */
 public class ImagenImagePlacement
 private constructor(public val x: Int? = null, public val y: Int? = null) {
@@ -67,7 +67,7 @@ private constructor(public val x: Int? = null, public val y: Int? = null) {
 
   public companion object {
     /**
-     * Creates an [ImagenImagePlacement] that represents a placement in the described by two
+     * Creates an [ImagenImagePlacement] that represents a placement in an image described by two
      * coordinates. The coordinate system has 0,0 in the top left corner, and the x and y
      * coordinates represent the location of the top left corner of the original image.
      * @param x the x coordinate of the top left corner of the original image
@@ -77,37 +77,23 @@ private constructor(public val x: Int? = null, public val y: Int? = null) {
       return ImagenImagePlacement(x, y)
     }
 
-    /**
-     * This [ImagenImagePlacement] is centered horizontally and vertically within the larger image
-     */
+    /** Center the image horizontally and vertically within the larger image */
     public val CENTER: ImagenImagePlacement = ImagenImagePlacement()
-    /**
-     * This [ImagenImagePlacement] is centered horizontally and aligned with the top edge of the
-     * larger image
-     */
+    /** Center the image horizontally and aligned with the top edge of the larger image */
     public val TOP_CENTER: ImagenImagePlacement = ImagenImagePlacement()
-    /**
-     * This [ImagenImagePlacement] is centered horizontally and aligned with the bottom edge of the
-     * larger image
-     */
+    /** Center the image horizontally and aligned with the bottom edge of the larger image */
     public val BOTTOM_CENTER: ImagenImagePlacement = ImagenImagePlacement()
-    /**
-     * This [ImagenImagePlacement] is centered vertically and aligned with the left edge of the
-     * larger image
-     */
+    /** Center the image vertically and aligned with the left edge of the larger image */
     public val LEFT_CENTER: ImagenImagePlacement = ImagenImagePlacement()
-    /**
-     * This [ImagenImagePlacement] is centered vertically and aligned with the right edge of the
-     * larger image
-     */
+    /** Center the image vertically and aligned with the right edge of the larger image */
     public val RIGHT_CENTER: ImagenImagePlacement = ImagenImagePlacement()
-    /** This [ImagenImagePlacement] is aligned with the top left corner of the larger image */
+    /** Align the image with the top left corner of the larger image */
     public val TOP_LEFT: ImagenImagePlacement = ImagenImagePlacement(0, 0)
-    /** This [ImagenImagePlacement] is aligned with the top right corner of the larger image */
+    /** Align the image with the top right corner of the larger image */
     public val TOP_RIGHT: ImagenImagePlacement = ImagenImagePlacement()
-    /** This [ImagenImagePlacement] is aligned with the bottom left corner of the larger image */
+    /** Align the image with the bottom left corner of the larger image */
     public val BOTTOM_LEFT: ImagenImagePlacement = ImagenImagePlacement()
-    /** This [ImagenImagePlacement] is caligned with the bottom right corner of the larger image */
+    /** Align the image with the bottom right corner of the larger image */
     public val BOTTOM_RIGHT: ImagenImagePlacement = ImagenImagePlacement()
   }
 }

firebase-ai/src/main/kotlin/com/google/firebase/ai/type/ImagenReferenceImage.kt

@@ -73,7 +73,7 @@ internal constructor(
 }
 
 /**
- * Represents a refrence image (provided or generated) to bound the created image via ControlNet
+ * Represents a reference image (provided or generated) to bound the created image via ControlNet
  * @param image the image provided, required if enableComputation is false
  * @param type the type of ControlNet reference image
  * @param referenceId the reference ID for this image, to be referenced in the prompt
@@ -112,7 +112,7 @@ internal constructor(maskConfig: ImagenMaskConfig, image: ImagenInlineImage? = n
 
   public companion object {
     /**
-     * Generates two reference images:
+     * Generates these two reference images in order:
      * * One [ImagenRawImage] containing the original image, padded out to the new dimensions with
      * black pixels, with the original image placed at the given placement
      * * One [ImagenRawMask] of the same dimensions containing white everywhere except at the
@@ -131,6 +131,15 @@ internal constructor(maskConfig: ImagenMaskConfig, image: ImagenInlineImage? = n
       newPosition: ImagenImagePlacement = ImagenImagePlacement.CENTER,
     ): List<ImagenReferenceImage> {
       val originalBitmap = image.asBitmap()
+      if (
+        originalBitmap.width > newDimensions.width || originalBitmap.height > newDimensions.height
+      ) {
+        throw IllegalArgumentException(
+          "New Dimensions must be strictly larger than original image dimensions. Original image " +
+            "is:${originalBitmap.width}x${originalBitmap.height}, new dimensions are " +
+            "${newDimensions.width}x${newDimensions.height}"
+        )
+      }
       val normalizedPosition =
         newPosition.normalizeToDimensions(
           Dimensions(originalBitmap.width, originalBitmap.height),