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

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.