eu.id3.document

Class DocumentImage

java.lang.Object

eu.id3.document.DocumentImage

All Implemented Interfaces:

java.io.Serializable, java.lang.AutoCloseable

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

Represents a document image.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor and Description
DocumentImage() Creates a new instance of the DocumentImage class.
DocumentImage(long handle) Creates a new instance of the DocumentImage class.

Method Summary

Modifier and Type	Method and Description
DocumentImage	clone() Creates a copy of the DocumentImage object.
void	close() Releases all resources used by this DocumentImage.
float	compare(DocumentImage cmpDocumentImage) Computes the difference with another image.
void	correctGamma(int contrast, int brightness, float gamma) Applies a gamma correction to the image.
DocumentImage	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(DocumentImage dstDocumentImage, int maxSize) Downscales the image so that its maximum dimension equals the given maximum size, while preserving the aspect ratio.
DocumentImage	extractRoi(Rectangle bounds) Extracts a region of interest in the image according to the given bounds.
DocumentImage	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, DocumentImage dstDocumentImage) Flips the image.
static DocumentImage	fromBuffer(byte[] data, PixelFormat pixelFormat) Creates an Image from the specified data buffer.
static DocumentImage	fromFile(java.lang.String filepath, PixelFormat pixelFormat) Creates an Image from the specified file.
static DocumentImage	fromRawBuffer(byte[] pixels, int width, int height, int stride, PixelFormat srcPixelFormat, PixelFormat dstPixelFormat) Creates an Image from the specified raw data buffer.
static DocumentImage	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, DocumentImage dstDocumentImage) 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, DocumentImage dstDocumentImage) Rotates the image to the specified angle.
byte[]	toBuffer(ImageFormat documentImageFormat, float compressionLevel) Exports the image to a buffer.
void	toBufferObject(ImageFormat documentImageFormat, 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

DocumentImage

public DocumentImage()
              throws DocumentException

Creates a new instance of the DocumentImage class.

Throws:

DocumentException - An error has occurred during Document Library execution.

DocumentImage

public DocumentImage(long handle)
              throws DocumentException

Creates a new instance of the DocumentImage class.

Parameters:

handle - Handle to the DocumentImage.

Throws:

DocumentException - An error has occurred during Document Library execution.

Method Detail

close

public void close()

Releases all resources used by this DocumentImage.

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 DocumentImage clone()
                    throws DocumentException

Creates a copy of the DocumentImage object.

Overrides:

clone in class java.lang.Object

Returns:

The newly created DocumentImage object.

Throws:

DocumentException - An error has occurred during Document Library execution.

getData

public byte[] getData()
               throws DocumentException

Gets the raw data buffer of the image.

Returns:

Raw data buffer of the image.

Throws:

DocumentException - An error has occurred during Document Library execution.

getHeight

public int getHeight()
              throws DocumentException

Gets the height in pixels.

Returns:

Height in pixels.

Throws:

DocumentException - An error has occurred during Document Library execution.

getPixelDepth

public int getPixelDepth()
                  throws DocumentException

Gets the pixel depth.

Returns:

Pixel depth.

Throws:

DocumentException - An error has occurred during Document Library execution.

getPixelFormat

public PixelFormat getPixelFormat()
                           throws DocumentException

Gets the pixel format.

Returns:

Pixel format.

Throws:

DocumentException - An error has occurred during Document Library execution.

getStride

public int getStride()
              throws DocumentException

Gets the stride in bytes.

Returns:

Stride in bytes.

Throws:

DocumentException - An error has occurred during Document Library execution.

getWidth

public int getWidth()
             throws DocumentException

Gets the width in pixels.

Returns:

Width in pixels.

Throws:

DocumentException - An error has occurred during Document Library execution.

compare

public float compare(DocumentImage cmpDocumentImage)
              throws DocumentException

Computes the difference with another image.

Parameters:

cmpDocumentImage - The image to compare.

Returns:

Comparison result in percent (0% is same, 100% is full different).

Throws:

DocumentException - An error has occurred during Document Library execution.

correctGamma

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

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:

DocumentException - An error has occurred during Document Library execution.

crop

public DocumentImage crop(int left,
                          int top,
                          int width,
                          int height)
                   throws DocumentException

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:

DocumentException - An error has occurred during Document Library execution.

downscale

public float downscale(int maxSize)
                throws DocumentException

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:

DocumentException - An error has occurred during Document Library execution.

downscaleTo

public float downscaleTo(DocumentImage dstDocumentImage,
                         int maxSize)
                  throws DocumentException

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:

dstDocumentImage - 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:

DocumentException - An error has occurred during Document Library execution.

extractRoi

public DocumentImage extractRoi(Rectangle bounds)
                         throws DocumentException

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:

DocumentException - An error has occurred during Document Library execution.

extractRoiWithColor

public DocumentImage extractRoiWithColor(Rectangle bounds,
                                         int colorRed,
                                         int colorGreen,
                                         int colorBlue)
                                  throws DocumentException

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:

DocumentException - An error has occurred during Document Library execution.

flip

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

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:

DocumentException - An error has occurred during Document Library execution.

flipTo

public void flipTo(boolean flipHorizontally,
                   boolean flipVertically,
                   DocumentImage dstDocumentImage)
            throws DocumentException

Flips the image.

Parameters:

flipHorizontally - Value indicating whether the image should be flipped horizontally.

flipVertically - Value indicating whether the image should be flipped vertically.

dstDocumentImage - The destination Image object that receives the flipped image.

Throws:

DocumentException - An error has occurred during Document Library execution.

fromBuffer

public static DocumentImage fromBuffer(byte[] data,
                                       PixelFormat pixelFormat)
                                throws DocumentException

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 document image.

Throws:

DocumentException - An error has occurred during Document Library execution.

fromFile

public static DocumentImage fromFile(java.lang.String filepath,
                                     PixelFormat pixelFormat)
                              throws DocumentException

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 document image.

Throws:

DocumentException - An error has occurred during Document Library execution.

fromRawBuffer

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

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 document image.

Throws:

DocumentException - An error has occurred during Document Library execution.

fromYuvPlanes

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

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 document image.

Throws:

DocumentException - An error has occurred during Document Library execution.

pad

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

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:

DocumentException - An error has occurred during Document Library execution.

reallocate

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

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:

DocumentException - An error has occurred during Document Library execution.

resize

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

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:

DocumentException - An error has occurred during Document Library execution.

resizeTo

public void resizeTo(int width,
                     int height,
                     DocumentImage dstDocumentImage)
              throws DocumentException

Resizes the image to the specified width and height.

Parameters:

width - The new width, in pixels.

height - The new height, in pixels.

dstDocumentImage - The destination image that receives the resized image.

Throws:

DocumentException - An error has occurred during Document Library execution.

rotate

public void rotate(int angle)
            throws DocumentException

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:

DocumentException - An error has occurred during Document Library execution.

rotateTo

public void rotateTo(int angle,
                     DocumentImage dstDocumentImage)
              throws DocumentException

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].

dstDocumentImage - The destination Image that receives the rotated image.

Throws:

DocumentException - An error has occurred during Document Library execution.

toBuffer

public byte[] toBuffer(ImageFormat documentImageFormat,
                       float compressionLevel)
                throws DocumentException

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:

documentImageFormat - The image format to export the image to.

compressionLevel - The compression level to be applied.

Returns:

Buffer that receives the image data.

Throws:

DocumentException - An error has occurred during Document Library execution.

toBufferObject

public void toBufferObject(ImageFormat documentImageFormat,
                           float compressionLevel,
                           ImageBuffer buffer)
                    throws DocumentException

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:

documentImageFormat - The output image format.

compressionLevel - The compression level to be applied.

buffer - The image buffer that receives the image data.

Throws:

DocumentException - An error has occurred during Document Library execution.

toFile

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

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:

DocumentException - An error has occurred during Document Library execution.

toRawBuffer

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

Copies image pixels in the specified format into a buffer.

Parameters:

pixelFormat - The pixel format.

buffer - Buffer that receives the raw image data.

Throws:

DocumentException - An error has occurred during Document Library execution.

transpose

public void transpose()
               throws DocumentException

Transposes the image object.

Throws:

DocumentException - An error has occurred during Document Library execution.