eu.id3.face

## Class Image

- java.lang.Object
- - eu.id3.face.Image

- All Implemented Interfaces:
    java.io.Serializable, java.lang.AutoCloseable

      public class Image
      extends java.lang.Object
      implements java.lang.AutoCloseable, java.io.Serializable

  Represents an image.
  See Also:
    Serialized Form

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `Image()` Creates a new instance of the Image class.
    `Image(long handle)` Creates a new instance of the Image class.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Image` | `clone()` Creates a copy of the Image object.
    `void` | `close()` Releases all resources used by this Image.
    `float` | `compare(Image cmpImage)` Computes the difference with another image.
    `void` | `correctGamma(int contrast, int brightness, float gamma)` Applies a gamma correction to the image.
    `Image` | `crop(int left, int top, int width, int height)` Crop a rectangular region of interest in the image according to the given bounds.
    `float` | `downscale(int maxSize)` Downscales the image in-place so that its maximum dimension is equal to the given maximum size, while preserving the aspect ratio.
    `float` | `downscaleTo(Image dstImage, int maxSize)` Downscales the image so that its maximum dimension equals the given maximum size, while preserving the aspect ratio.
    `Image` | `extractRoi(Rectangle bounds)` Extracts a region of interest in the image according to the given bounds.
    `Image` | `extractRoiWithColor(Rectangle bounds, int colorRed, int colorGreen, int colorBlue)` Extracts a region of interest in the image according to the given bounds.
    `protected void` | `finalize()` Finalizer for this class.
    `void` | `flip(boolean flipHorizontally, boolean flipVertically)` Flips the image in-place.
    `void` | `flipTo(boolean flipHorizontally, boolean flipVertically, Image dstImage)` Flips the image.
    `static Image` | `fromBuffer(byte[] data, PixelFormat pixelFormat)` Creates an Image from the specified data buffer.
    `static Image` | `fromFile(java.lang.String filepath, PixelFormat pixelFormat)` Creates an Image from the specified file.
    `static Image` | `fromRawBuffer(byte[] pixels, int width, int height, int stride, PixelFormat srcPixelFormat, PixelFormat dstPixelFormat)` Creates an Image from the specified raw data buffer.
    `static Image` | `fromYuvPlanes(byte[] yPlane, byte[] uPlane, byte[] vPlane, int yWidth, int yHeight, int uvPixelStride, int uvRowStride, PixelFormat dstPixelFormat)` Creates an Image from the specified YUV planes.
    `byte[]` | `getData()` Gets the raw data buffer of the image.
    `long` | `getHandle()` Gets the native handle.
    `int` | `getHeight()` Gets the height in pixels.
    `int` | `getPixelDepth()` Gets the pixel depth.
    `PixelFormat` | `getPixelFormat()` Gets the pixel format.
    `int` | `getStride()` Gets the stride in bytes.
    `int` | `getWidth()` Gets the width in pixels.
    `void` | `pad(int top, int left, int bottom, int right, int colorRed, int colorGreen, int colorBlue)` Add padding around the image Only works for BGR 24 bits, RGB 24 bits and Grayscale 8bits images.
    `void` | `reallocate(int width, int height, PixelFormat pixelFormat)` Reallocates the internal memory of the Image from parameters.
    `void` | `resize(int width, int height)` Resizes the image in-place to the required width and height.
    `void` | `resizeTo(int width, int height, Image dstImage)` Resizes the image to the specified width and height.
    `void` | `rotate(int angle)` Rotates the image in-place to the specified angle.
    `void` | `rotateTo(int angle, Image dstImage)` Rotates the image to the specified angle.
    `byte[]` | `toBuffer(ImageFormat imageFormat, float compressionLevel)` Exports the image to a buffer.
    `void` | `toBufferObject(ImageFormat imageFormat, float compressionLevel, ImageBuffer buffer)` Copies the image to a buffer in the specified format.
    `void` | `toFile(java.lang.String filepath, float compressionLevel)` Saves the image to the specified file.
    `void` | `toRawBuffer(PixelFormat pixelFormat, ImageBuffer buffer)` Copies image pixels in the specified format into a buffer.
    `void` | `transpose()` Transposes the image object.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### Image

          public Image()
                throws FaceException

      Creates a new instance of the Image class.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### Image

          public Image(long handle)
                throws FaceException

      Creates a new instance of the Image class.
      Parameters:
        `handle` - Handle to the Image.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

  - ### Method Detail

    - #### close

          public void close()

      Releases all resources used by this Image.
      Specified by:
        `close` in interface `java.lang.AutoCloseable`

    - #### finalize

          protected void finalize()

      Finalizer for this class. Finalizers are deprecated since Java 9+. This method is not guaranteed to be called. To release all memory held by this class please be sure to call the close() method.
      Overrides:
        `finalize` in class `java.lang.Object`

    - #### getHandle

          public long getHandle()

      Gets the native handle.
      Returns:
        The native handle.

    - #### clone

          public Image clone()
                      throws FaceException

      Creates a copy of the Image object.
      Overrides:
        `clone` in class `java.lang.Object`
      Returns:
        The newly created Image object.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### getData

          public byte[] getData()
                         throws FaceException

      Gets the raw data buffer of the image.
      Returns:
        Raw data buffer of the image.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### getHeight

          public int getHeight()
                        throws FaceException

      Gets the height in pixels.
      Returns:
        Height in pixels.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### getPixelDepth

          public int getPixelDepth()
                            throws FaceException

      Gets the pixel depth.
      Returns:
        Pixel depth.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### getPixelFormat

          public PixelFormat getPixelFormat()
                                     throws FaceException

      Gets the pixel format.
      Returns:
        Pixel format.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### getStride

          public int getStride()
                        throws FaceException

      Gets the stride in bytes.
      Returns:
        Stride in bytes.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### getWidth

          public int getWidth()
                       throws FaceException

      Gets the width in pixels.
      Returns:
        Width in pixels.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### compare

          public float compare(Image cmpImage)
                        throws FaceException

      Computes the difference with another image.
      Parameters:
        `cmpImage` - The image to compare.
      Returns:
        Comparison result in percent (0% is same, 100% is full different).
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### correctGamma

          public void correctGamma(int contrast,
                                   int brightness,
                                   float gamma)
                            throws FaceException

      Applies a gamma correction to the image.
      Parameters:
        `contrast` - Contrast coefficient, from -255 to 255, to be applied to the image.
        `brightness` - Brightness coefficient, from -255 to 255, to be applid to the image.
        `gamma` - Gamma coefficient, from 0.25 to 2.50, to be applied to the image.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### crop

          public Image crop(int left,
                            int top,
                            int width,
                            int height)
                     throws FaceException

      Crop a rectangular region of interest in the image according to the given bounds.
      Parameters:
        `left` - Left bound of the crop to extract.
        `top` - Top bound of the crop to extract.
        `width` - Width of the crop to extract.
        `height` - Height of the crop to extract.
      Returns:
        The extracted region of interest.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### downscale

          public float downscale(int maxSize)
                          throws FaceException

      Downscales the image in-place so that its maximum dimension is equal to the given maximum size, while preserving the aspect ratio. Note: If the maximum dimension is already smaller than the given maximum size, the function does nothing and the scaling ration returned is 1.
      Parameters:
        `maxSize` - Maximum image size, in pixels. The value must be greater than 0.
      Returns:
        The scaling ratio applied to the image. Range is ]0:1].
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### downscaleTo

          public float downscaleTo(Image dstImage,
                                   int maxSize)
                            throws FaceException

      Downscales the image so that its maximum dimension equals the given maximum size, while preserving the aspect ratio. Note: If the maximum dimension is already smaller than the given maximum size, the function does nothing and the returned scale ratio is 1.
      Parameters:
        `dstImage` - Destination image.
        `maxSize` - Maximum image size, in pixels. The value must be greater than 0.
      Returns:
        The scaling ratio applied to the image. Range is ]0:1].
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### extractRoi

          public Image extractRoi(Rectangle bounds)
                           throws FaceException

      Extracts a region of interest in the image according to the given bounds.
      Parameters:
        `bounds` - Bounds of the crop to extract.
      Returns:
        The extracted region of interest.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### extractRoiWithColor

          public Image extractRoiWithColor(Rectangle bounds,
                                           int colorRed,
                                           int colorGreen,
                                           int colorBlue)
                                    throws FaceException

      Extracts a region of interest in the image according to the given bounds.
      Parameters:
        `bounds` - Bounds of the crop to extract.
        `colorRed` - Background color red (from 0 to 255)
        `colorGreen` - Background color green (from 0 to 255)
        `colorBlue` - Background color blue (from 0 to 255)
      Returns:
        The extracted region of interest.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### flip

          public void flip(boolean flipHorizontally,
                           boolean flipVertically)
                    throws FaceException

      Flips the image in-place.
      Parameters:
        `flipHorizontally` - Value indicating whether the image should be flipped horizontally.
        `flipVertically` - Value indicating whether the image should be flipped vertically.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### flipTo

          public void flipTo(boolean flipHorizontally,
                             boolean flipVertically,
                             Image dstImage)
                      throws FaceException

      Flips the image.
      Parameters:
        `flipHorizontally` - Value indicating whether the image should be flipped horizontally.
        `flipVertically` - Value indicating whether the image should be flipped vertically.
        `dstImage` - The destination Image object that receives the flipped image.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### fromBuffer

          public static Image fromBuffer(byte[] data,
                                         PixelFormat pixelFormat)
                                  throws FaceException

      Creates an Image from the specified data buffer.
      Parameters:
        `data` - A buffer that contains the image data.
        `pixelFormat` - The destination pixel format to convert the input to.
      Returns:
        The newly created image.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### fromFile

          public static Image fromFile(java.lang.String filepath,
                                       PixelFormat pixelFormat)
                                throws FaceException

      Creates an Image from the specified file.
      Parameters:
        `filepath` - A string that contains the name of the file from which to create the Image.
        `pixelFormat` - The pixel format into which to convert the input image.
      Returns:
        The newly created image.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### fromRawBuffer

          public static Image fromRawBuffer(byte[] pixels,
                                            int width,
                                            int height,
                                            int stride,
                                            PixelFormat srcPixelFormat,
                                            PixelFormat dstPixelFormat)
                                     throws FaceException

      Creates an Image from the specified raw data buffer.
      Parameters:
        `pixels` - A buffer that contains image pixels.
        `width` - The width, in pixels, of the image.
        `height` - The height, in pixels, of the image.
        `stride` - The stride, in pixels, of the image.
        `srcPixelFormat` - The pixel format of the input image.
        `dstPixelFormat` - The pixel format into which to convert the input image.
      Returns:
        The newly created image.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### fromYuvPlanes

          public static Image fromYuvPlanes(byte[] yPlane,
                                            byte[] uPlane,
                                            byte[] vPlane,
                                            int yWidth,
                                            int yHeight,
                                            int uvPixelStride,
                                            int uvRowStride,
                                            PixelFormat dstPixelFormat)
                                     throws FaceException

      Creates an Image from the specified YUV planes.
      Parameters:
        `yPlane` - A buffer that contains the Y plane.
        `uPlane` - A buffer that contains the U plane.
        `vPlane` - A buffer that contains the V plane.
        `yWidth` - The width, in pixels, of the Y plane.
        `yHeight` - The height, in pixels, of the Y plane.
        `uvPixelStride` - The pixel-level stride, in pixels, of the U and V planes.
        `uvRowStride` - The row-level stride, in pixels, of the U and V planes.
        `dstPixelFormat` - The pixel format into which to convert the input image.
      Returns:
        The newly created image.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### pad

          public void pad(int top,
                          int left,
                          int bottom,
                          int right,
                          int colorRed,
                          int colorGreen,
                          int colorBlue)
                   throws FaceException

      Add padding around the image Only works for BGR 24 bits, RGB 24 bits and Grayscale 8bits images. For grayscale image, the padding color is the red component.
      Parameters:
        `top` - Padding on top.
        `left` - Padding on left.
        `bottom` - Padding on bottom.
        `right` - Padding on right.
        `colorRed` - Padding color red (from 0 to 255)
        `colorGreen` - Padding color green (from 0 to 255)
        `colorBlue` - Padding color blue (from 0 to 255)
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### reallocate

          public void reallocate(int width,
                                 int height,
                                 PixelFormat pixelFormat)
                          throws FaceException

      Reallocates the internal memory of the Image from parameters. Note: If the given parameters are the same as the ones of the object, then there is nothing done in this function.
      Parameters:
        `width` - The new width, in pixels.
        `height` - The new height, in pixels.
        `pixelFormat` - The new pixel format.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### resize

          public void resize(int width,
                             int height)
                      throws FaceException

      Resizes the image in-place to the required width and height.
      Parameters:
        `width` - The new width, in pixels.
        `height` - The new height, in pixels.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### resizeTo

          public void resizeTo(int width,
                               int height,
                               Image dstImage)
                        throws FaceException

      Resizes the image to the specified width and height.
      Parameters:
        `width` - The new width, in pixels.
        `height` - The new height, in pixels.
        `dstImage` - The destination image that receives the resized image.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### rotate

          public void rotate(int angle)
                      throws FaceException

      Rotates the image in-place to the specified angle. Note: The rotation is performed counter-clockwise.
      Parameters:
        `angle` - The rotation angle, in degree. Supported values are [0, 90, 180, 270].
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### rotateTo

          public void rotateTo(int angle,
                               Image dstImage)
                        throws FaceException

      Rotates the image to the specified angle. Note: The rotation is performed counter-clockwise.
      Parameters:
        `angle` - The rotation angle, in degree. Supported values are [0, 90, 180, 270].
        `dstImage` - The destination Image that receives the rotated image.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### toBuffer

          public byte[] toBuffer(ImageFormat imageFormat,
                                 float compressionLevel)
                          throws FaceException

      Exports the image to a buffer. The compression level meaning depends on the algorithm used: - For JPEG compression, the value is the expected quality and may vary from 1 to 100. - For JPEG2000 compression, the value is the compression rate and may vary from 1 to 512. - For PNG compression, the value is the compression rate and may vary from 1 to 10. - For all other formats, the value is ignored.
      Parameters:
        `imageFormat` - The image format to export the image to.
        `compressionLevel` - The compression level to be applied.
      Returns:
        Buffer that receives the image data.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### toBufferObject

          public void toBufferObject(ImageFormat imageFormat,
                                     float compressionLevel,
                                     ImageBuffer buffer)
                              throws FaceException

      Copies the image to a buffer in the specified format. The compression level meaning depends on the algorithm used: - For JPEG compression, the value is the expected quality and may vary from 1 to 100. - For JPEG2000 compression, the value is the compression rate and may vary from 1 to 512. - For PNG compression, the value is the compression rate and may vary from 1 to 10. - For all other formats, the value is ignored.
      Parameters:
        `imageFormat` - The output image format.
        `compressionLevel` - The compression level to be applied.
        `buffer` - The image buffer that receives the image data.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### toFile

          public void toFile(java.lang.String filepath,
                             float compressionLevel)
                      throws FaceException

      Saves the image to the specified file. The compression level meaning depends on the algorithm used: - For JPEG compression, the value is the expected quality and may vary from 1 to 100. - For JPEG2000 compression, the value is the compression rate and may vary from 1 to 512. - For PNG compression, the value is the compression rate and may vary from 1 to 10. - For all other formats, the value is ignored.
      Parameters:
        `filepath` - A string that contains the name of the file to which to save the image.
        `compressionLevel` - The compression level to be applied.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### toRawBuffer

          public void toRawBuffer(PixelFormat pixelFormat,
                                  ImageBuffer buffer)
                           throws FaceException

      Copies image pixels in the specified format into a buffer.
      Parameters:
        `pixelFormat` - The pixel format.
        `buffer` - Buffer that receives the raw image data.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

    - #### transpose

          public void transpose()
                         throws FaceException

      Transposes the image object.
      Throws:
        `FaceException` - An error has occurred during Face Library execution.

Copyright © id3 Technologies. All rights reserved. eu.id3.face