de.goto3d.freeimage
Class FreeImage

java.lang.Object
  extended by de.goto3d.freeimage.FreeImage

public final class FreeImage
extends java.lang.Object


Field Summary
protected  java.nio.ByteBuffer byteBuffer
           
protected  SWIGTYPE_p_FIBITMAP fiBitmap
           
 
Constructor Summary
FreeImage(java.io.File file)
          Tries to load the specified image and create a new FreeImage instance.
 
Method Summary
 boolean adjustBrightness(double percentage)
          Adjusts the brightness of a 8-, 24- or 32-bit image by a certain amount.
 boolean adjustContrast(double percentage)
          Adjusts the contrast of a 8-, 24- or 32-bit image by a certain amount.
 boolean adjustGamma(double gamma)
          Performs gamma correction on a 8-, 24- or 32-bit image.
 FreeImage colorQuantize(int quantizeAlgorithm)
          Quantizes a high-color 24-bit bitmap to an 8-bit palette color bitmap.
static FreeImage convertFromRawBits(java.nio.ByteBuffer buffer, int width, int height, int pitch, int bpp, int redMask, int greenMask, int blueMask, boolean topDown)
          Converts a raw bitmap somewhere in memory to a FreeImage.
 FreeImage convertTo16Bits555()
          Converts a bitmap to 16 bits, where each pixel has a color pattern of 5 bits red, 5 bits green and 5 bits blue.
 FreeImage convertTo16Bits565()
          Converts a bitmap to 16 bits, where each pixel has a color pattern of 5 bits red, 6 bits green and 5 bits blue.
 FreeImage convertTo24Bits()
          Converts a bitmap to 24 bits.
 FreeImage convertTo32Bits()
          Converts a bitmap to 32 bits.
 FreeImage convertTo4Bits()
          Converts a bitmap to 4 bits.
 FreeImage convertTo8Bits()
          Converts a bitmap to 8 bits.
 FreeImage convertToGreyscale()
          Converts a bitmap to a 8-bit greyscale image with a linear ramp.
 void convertToRawBits(java.nio.ByteBuffer buffer, int pitch, int bpp, int redMask, int greenMask, int blueMask, boolean topDown)
          Converts a FreeImage instance to a raw piece of memory.
 FreeImage dither(int ditherAlgorithm)
          Converts a bitmap to 1-bit monochrome bitmap using a dithering algorithm.
 boolean flipHorizontal()
          Flip the image horizontally along the vertical axis.
 boolean flipVertical()
          Flip the image vertically along the horizontal axis.
 int getBitsPerPixel()
          Returns the size of one pixel in the bitmap in bits.
static java.lang.String getCopyrightMessage()
          Returns a string containing a standard copyright message you can show in your program.
static int[] getFileFormatsByExtension(java.io.File file)
          Tries to determine the bitmap file by its extension.
static int getFileType(java.io.File file)
          Orders FreeImage to analyze the bitmap signature.
 int getHeight()
          Returns the height of the bitmap in pixel units.
 int getPitch()
          Returns the width of the bitmap in bytes, rounded to the next 32-bit boundary, also known as pitch or stride or scan width.
 java.nio.ByteBuffer getPixelBuffer()
          Returns a pointer wrapped in a DirectByteBuffer object to the data-bits of the bitmap.
 int getPixelColor(int x, int y)
          Get the pixel color of a 16-, 24- or 32-bit image at position (x, y), including range check (slow access).
 short getPixelIndex(int x, int y)
          Get the pixel index of a palettized image at position (x, y), including range check (slow access).
static java.lang.String getVersion()
          Returns a string containing the current version of the library.
 int getWidth()
          Returns the width of the bitmap in pixel units.
 boolean invert()
          Inverts each pixel data.
static boolean isLittleEndian()
          This function returns true if the platform running FreeImage uses the Little Endian convention (Intel processors) and returns false if it uses the Big Endian convention (Motorola processors).
 boolean isTransparent()
          Returns true when the transparency table is enabled (1-, 4- or 8-bit images) or when the input dib contains alpha values (32-bit images).
 FreeImage makeThumbnail(int size, boolean convertHDR)
          Creates a thumbnail from a greyscale or RGB(A) image so that the output image fits inside a square of size max_pixel_size, keeping aspect ratio.
 FreeImage rescale(int dstWidth, int dstHeight, int filter)
          This function performs resampling (or scaling, zooming) of a greyscale or RGB(A) image to the desired destination width and height.
 FreeImage rotateClassic(double angle)
          This method rotates the image counter clockwise by the desired angle.
 FreeImage rotateEx(double angle, double xShift, double yShift, double xOrigin, double yOrigin, boolean useMask)
          Counter clockwise rotates the image by some angle around an arbitrary origin, while an additional translation can be performed afterwards.
 void save(java.io.File file)
          Saves the image.
 void save(java.io.File file, int format)
          Saves the image using the specified image format from FREE_IMAGE_FORMAT.
 void setPixelColor(int x, int y, int color)
          Set the pixel color of a 16-, 24- or 32-bit image at position (x, y), including range check (slow access).
 void setPixelIndex(int x, int y, short index)
          Set the pixel index of a palettized image at position (x, y), including range check (slow access).
 FreeImage threshold(int threshold)
          Converts a bitmap to 1-bit monochrome bitmap using a threshold T between [0..255].
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

byteBuffer

protected final java.nio.ByteBuffer byteBuffer

fiBitmap

protected final SWIGTYPE_p_FIBITMAP fiBitmap
Constructor Detail

FreeImage

public FreeImage(java.io.File file)
          throws FreeImageException
Tries to load the specified image and create a new FreeImage instance. If the format is not supported an FreeImageException will be thrown.

Parameters:
file - The image to be loaded.
Throws:
FreeImageException - if the format is not supported
Method Detail

getVersion

public static java.lang.String getVersion()
Returns a string containing the current version of the library.

Returns:
a string containing the current version of the library.

getCopyrightMessage

public static java.lang.String getCopyrightMessage()
Returns a string containing a standard copyright message you can show in your program.

Returns:
a string containing a standard copyright message you can show in your program.

isLittleEndian

public static boolean isLittleEndian()
This function returns true if the platform running FreeImage uses the Little Endian convention (Intel processors) and returns false if it uses the Big Endian convention (Motorola processors).

Returns:
true on intel machine, true on motorola cpus

getFileType

public static int getFileType(java.io.File file)
Orders FreeImage to analyze the bitmap signature. The function then returns one of the predefined FREE_IMAGE_FORMAT constants. Because not all formats can be identified by their header (some images don't have a header or one at the end of the file), getFileType may return FIF_UNKNOWN.

Parameters:
file - The file to be examined.
Returns:
one of the predefined FREE_IMAGE_FORMAT constants.

convertFromRawBits

public static FreeImage convertFromRawBits(java.nio.ByteBuffer buffer,
                                           int width,
                                           int height,
                                           int pitch,
                                           int bpp,
                                           int redMask,
                                           int greenMask,
                                           int blueMask,
                                           boolean topDown)
Converts a raw bitmap somewhere in memory to a FreeImage. The parameters in this function are used to describe the raw bitmap. The first parameter is a pointer to the start of the raw bits wrapped in a ByteBuffer object. The width and height parameter describe the size of the bitmap. The pitch defines the total width of a scanline in the source bitmap, including padding bytes that may be applied. The bpp parameter tells FreeImage what the bit depth of the bitmap is. The red_mask, green_mask and blue_mask parameters tell FreeImage the bit-layout of the color components in the bitmap. The last parameter, topdown, will store the bitmap top-left pixel first when it is true or bottom-left pixel first when it is false. When the source bitmap uses a 32-bit padding, you can calculate the pitch using the following formula: int pitch = ((((bpp * width) + 31) / 32) * 4);

Parameters:
buffer - pointer to the raw bits in memory
width - width of bitmap in pixel units
height - height of bitmap in pixel units
pitch - actual width in bytes
bpp - bits per pixel
redMask - mask for the red channel
greenMask - mask for the green channel
blueMask - mask for the blue channel
topDown - flag to signal whether to store image top down or not
Returns:
a FreeImage instance

convertToRawBits

public final void convertToRawBits(java.nio.ByteBuffer buffer,
                                   int pitch,
                                   int bpp,
                                   int redMask,
                                   int greenMask,
                                   int blueMask,
                                   boolean topDown)
Converts a FreeImage instance to a raw piece of memory. The layout of the memory is described in the passed parameters, which are the same as in the previous function. The last parameter, topdown, will store the bitmap top-left pixel first when it is true or bottom-left pixel first when it is false.

Parameters:
buffer - pointer to the raw bits in memory
pitch - actual width in bytes
bpp - bits per pixel
redMask - mask for the red channel
greenMask - mask for the green channel
blueMask - mask for the blue channel
topDown - flag to signal whether to store image top down or not

getFileFormatsByExtension

public static int[] getFileFormatsByExtension(java.io.File file)
                                       throws FreeImageException
Tries to determine the bitmap file by its extension. This function is particularly useful when saving images. If the filetype is unknown an exception will be thrown

NB: This function returns an array containing possible image formats. Usually there is only one entry in this array because extensions and file formats can be mapped one to one. But there are some special cases, e.g. ppm, where two possible format can be associated, e.g. ppm(ascii) or ppm(raw).

Parameters:
file - The file to be examined.
Returns:
one of the predefined FREE_IMAGE_FORMAT constants.
Throws:
FreeImageException - if the format cannot be determined by its extension

getPixelBuffer

public final java.nio.ByteBuffer getPixelBuffer()
Returns a pointer wrapped in a DirectByteBuffer object to the data-bits of the bitmap. It is up to you to interpret these bytes correctly, according to the results of getBitsPerPixel, getRedMask, getGreenMask and getBlueMask. For a performance reason, the address returned is aligned on a 16 bytes alignment boundary.

Returns:
a pointer wrapped in a DirectByteBuffer object to the data-bits of the bitmap

save

public final void save(java.io.File file)
                throws FreeImageException
Saves the image. It tries to identify the desired file type by calling the method getFileFormatByExtension. If the file type cannot be determined by its extension or the image format is not supported for saving this image an exception will be thrown.

Parameters:
file - the destination file name
Throws:
FreeImageException - If the file type cannot be determined by its extension or the image format is not supported for saving this image an exception will be thrown.

save

public final void save(java.io.File file,
                       int format)
                throws FreeImageException
Saves the image using the specified image format from FREE_IMAGE_FORMAT. If the image format is not supported for saving this image an exception will be thrown.

Parameters:
file - the destination file name
format - the desired destination image format. Must be one of the FREE_IMAGE_FORMAT constants
Throws:
FreeImageException - If the file type cannot be determined by its extension or the image format is not supported for saving this image an exception will be thrown.

getWidth

public final int getWidth()
Returns the width of the bitmap in pixel units.

Returns:
the width of the bitmap in pixel units.

getPitch

public final int getPitch()
Returns the width of the bitmap in bytes, rounded to the next 32-bit boundary, also known as pitch or stride or scan width.
In FreeImage each scanline starts at a 32-bit boundary for performance reasons. This accessor is essential when using low level pixel manipulation functions.

Returns:
the width of the bitmap in bytes, rounded to the next 32-bit boundary

getHeight

public final int getHeight()
Returns the height of the bitmap in pixel units.

Returns:
the height of the bitmap in pixel units.

getBitsPerPixel

public final int getBitsPerPixel()
Returns the size of one pixel in the bitmap in bits. For example when each pixel takes 32-bits of space in the bitmap, this function returns 32. Possible bit depths are 1, 4, 8, 16, 24, 32 for standard bitmaps and 16-, 32-, 48-, 64-, 96- and 128-bit for non standard bitmaps.

Returns:
the size of one pixel in the bitmap in bits

isTransparent

public final boolean isTransparent()
Returns true when the transparency table is enabled (1-, 4- or 8-bit images) or when the input dib contains alpha values (32-bit images). Returns false otherwise.

NB: This method really examines the pixels! So if you change a pixel by directly modifying it in the memory and call this method afterwards the result can change! This is pretty useful. If you think this is too much of a performance penalty go ahead an cache the result yourself ;-)

Returns:
true if there is any transparent pixel, false otherwise.

adjustGamma

public final boolean adjustGamma(double gamma)
Performs gamma correction on a 8-, 24- or 32-bit image. The gamma parameter represents the gamma value to use (gamma > 0). A value of 1.0 leaves the image alone, less than one darkens it, and greater than one lightens it. The function returns true on success. It returns false when gamma is less than or equal to zero or when the bitdepth of the source dib cannot be handled.

Parameters:
gamma - The adjustment amount
Returns:
true on success false otherwise

adjustBrightness

public final boolean adjustBrightness(double percentage)
Adjusts the brightness of a 8-, 24- or 32-bit image by a certain amount. This amount is given by the percentage parameter, where percentage is a value between [-100..100]. A value 0 means no change, less than 0 will make the image darker and greater than 0 will make the image brighter. The function returns true on success, false otherwise (e.g. when the bitdepth of the source dib cannot be handled).

Parameters:
percentage - The adjustment amount
Returns:
true on success false otherwise

adjustContrast

public final boolean adjustContrast(double percentage)
Adjusts the contrast of a 8-, 24- or 32-bit image by a certain amount. This amount is given by the percentage parameter, where percentage is a value between [-100..100]. A value 0 means no change, less than 0 will decrease the contrast and greater than 0 will increase the contrast of the image. The function returns true on success, false otherwise (e.g. when the bitdepth of the source dib cannot be handled).

Parameters:
percentage - The adjustment amount
Returns:
true on success false otherwise

invert

public final boolean invert()
Inverts each pixel data.

Returns:
true on success, false otherwise

rotateClassic

public final FreeImage rotateClassic(double angle)
This method rotates the image counter clockwise by the desired angle. The angle must be specified in degrees. Note that the rotated image may be larger than the original image because this method will always adjust the size of the result so that all pixels are visible.

Parameters:
angle - degrees to be rotated in counter clockwise order
Returns:
new instance of FreeImage

rotateEx

public final FreeImage rotateEx(double angle,
                                double xShift,
                                double yShift,
                                double xOrigin,
                                double yOrigin,
                                boolean useMask)
Counter clockwise rotates the image by some angle around an arbitrary origin, while an additional translation can be performed afterwards. The angle must be given in degrees. For example if you want to rotate an image around its center you can do it this way:

fi.rotateEx(10, 0,0, fi.getWidth()*0.5,fi.getHeight()*0.5, false);

Note that the size of the original image will always be preserved. The useMask flag signals whether empty corners shall be filled with the original image or be just masked away.

Parameters:
angle - degrees to be rotated in counter clockwise order
xShift - Horizontal translation in pixel units
yShift - Vertical translation in pixel units
xOrigin - The horizontal origin of the rotation
yOrigin - The vertical origin of the rotation
useMask - true means empty corners will be masked away.
Returns:
new instance of FreeImage

flipHorizontal

public final boolean flipHorizontal()
Flip the image horizontally along the vertical axis.

Returns:
true on success false otherwise

flipVertical

public final boolean flipVertical()
Flip the image vertically along the horizontal axis.

Returns:
true on success false otherwise

rescale

public final FreeImage rescale(int dstWidth,
                               int dstHeight,
                               int filter)
This function performs resampling (or scaling, zooming) of a greyscale or RGB(A) image to the desired destination width and height. A FreeImageRuntimeException is thrown when the bitdepth cannot be handled or when there’s not enough memory (this may happen with very large images). 16-bit RGB bitmap are returned as 24-bit. Palettized and 4-bit bitmap are returned as 8-bit palettized images, using an internal conversion to 24-bit followed by a color quantization, or are returned as 32-bit if they contain transparency. Resampling refers to changing the pixel dimensions (and therefore display size) of an image. When you downsample (or decrease the number of pixels), information is deleted from the image. When you upsample (or increase the number of pixels), new pixels are added based on color values of existing pixels. You specify an interpolation filter to determine how pixels are added or deleted. The following filters can be used as resampling filters: FILTER_BOX Box, pulse, Fourier window, 1st order (constant) B-Spline
FILTER_BILINEAR Bilinear filter
FILTER_BSPLINE 4th order (cubic) B-Spline
FILTER_BICUBIC Mitchell and Netravali's two-param cubic filter
FILTER_CATMULLROM Catmull-Rom spline, Overhauser spline
FILTER_LANCZOS3 Lanczos-windowed sinc filter

Returns:
new instance of FreeImage

makeThumbnail

public final FreeImage makeThumbnail(int size,
                                     boolean convertHDR)
Creates a thumbnail from a greyscale or RGB(A) image so that the output image fits inside a square of size max_pixel_size, keeping aspect ratio. Downsampling is done using a bilinear filter (see FreeImage_Rescale). 16-bit RGB bitmap are returned as 24-bit. Palettized and 4-bit bitmap are returned as 8-bit or as 32-bit if they contain transparency. When the convert parameter is set to true, High Dynamic Range images (FIT_UINT16, FIT_RGB16, FIT_RGBA16, FIT_FLOAT) are transparently converted to standard images (i.e. 8-, 24 or 32-bit images), using one of the convertToXXX conversion function. As for RBG[A]F images, they are converted to 24-bit using the FreeImage_TmoDrago03 function with default options.

Parameters:
size - the destination size in pixel units
convertHDR -
Returns:
new instance of FreeImage

convertTo4Bits

public final FreeImage convertTo4Bits()
Converts a bitmap to 4 bits. If the bitmap was a high-color bitmap (16, 24 or 32-bit) or if it was a monochrome or greyscale bitmap (1 or 8-bit), the end result will be a greyscale bitmap, otherwise (1-bit palletised bitmaps) it will be a palletised bitmap. A clone of the input bitmap is returned for 4-bit bitmaps.
NB: here "greyscale" means that the resulting bitmap will have grey colors, but the palette won’t be a linear greyscale palette. Thus, FreeImage_GetColorType will return FIC_PALETTE.

Returns:
new instance of FreeImage

convertTo8Bits

public final FreeImage convertTo8Bits()
Converts a bitmap to 8 bits. If the bitmap was a high-color bitmap (16, 24 or 32-bit) or if it was a monochrome or greyscale bitmap (1 or 4-bit), the end result will be a greyscale bitmap, otherwise (1 or 4-bit palletised bitmaps) it will be a palletised bitmap. A clone of the input bitmap is returned for 8-bit bitmaps.
When creating the greyscalepalette, the greyscale intensity of a result pixel is based on red, green, and blue levels of the corresponding source pixel using the following formula:
grey = 0.299 x R + 0.587 x G + 0.114 x B
The values 0.299, 0.587 and 0.114 represent the relative red, green, and blue intensities.
For 16-bit greyscale images (images whose type is FIT_UINT16), conversion is done by dividing the 16-bit channel by 256 (see also convertToStandardType). A FreeImageRuntimeException is thrown for other non-standard bitmap types.

Returns:
new instance of FreeImage

convertToGreyscale

public final FreeImage convertToGreyscale()
Converts a bitmap to a 8-bit greyscale image with a linear ramp. Contrary to the FreeImage_ConvertTo8Bits function, 1-, 4- and 8-bit palletised images are correctly converted, as well as images with a FIC_MINISWHITE color type.

Returns:
new instance of FreeImage

convertTo16Bits555

public final FreeImage convertTo16Bits555()
Converts a bitmap to 16 bits, where each pixel has a color pattern of 5 bits red, 5 bits green and 5 bits blue. One bit in each pixel is unused. A clone of the input bitmap is returned for 16- bit 555 bitmaps

Returns:
new instance of FreeImage

convertTo16Bits565

public final FreeImage convertTo16Bits565()
Converts a bitmap to 16 bits, where each pixel has a color pattern of 5 bits red, 6 bits green and 5 bits blue. A clone of the input bitmap is returned for 16-bit 565 bitmaps

Returns:
new instance of FreeImage

convertTo24Bits

public final FreeImage convertTo24Bits()
Converts a bitmap to 24 bits. A clone of the input bitmap is returned for 24-bit bitmaps. For 48-bit RGB images, conversion is done by dividing each 16-bit channel by 256. A FreeImageRuntimeException is thrown for other non-standard bitmap types.

Returns:
new instance of FreeImage

convertTo32Bits

public final FreeImage convertTo32Bits()
Converts a bitmap to 32 bits. A clone of the input bitmap is returned for 32-bit bitmaps. For 48-bit RGB images, conversion is done by dividing each 16-bit channel by 256 and by setting the alpha channel to an opaque value (0xFF). For 64-bit RGBA images, conversion is done by dividing each 16-bit channel by 256. A FreeImageRuntimeException is thrown for other non-standard bitmap types.

Returns:
new instance of FreeImage

colorQuantize

public final FreeImage colorQuantize(int quantizeAlgorithm)
Quantizes a high-color 24-bit bitmap to an 8-bit palette color bitmap. The quantizeAlgorithm parameter specifies the color reduction algorithm to be used:
FIQ_WUQUANT Xiaolin Wu color quantization algorithm
FIQ_NNQUANT NeuQuant neural-net quantization algorithm by Anthony Dekker
References: Wu, Xiaolin, Efficient Statistical Computations for Optimal Color Quantization. In Graphics Gems, vol. II, p. 126-133. [Online] http://www.ece.mcmaster.ca/~xwu/
Dekker A. H., Kohonen neural networks for optimal color quantization. Network: Computation in Neural Systems, Volume 5, Number 3, Institute of Physics Publishing, 1994. [Online] http:// members.ozemail.com.au/~dekker/NEUQUANT.HTML

Parameters:
quantizeAlgorithm - The algorithm to use (see also FREE_IMAGE_QUANTIZE)
Returns:
new instance of FreeImage

threshold

public final FreeImage threshold(int threshold)
Converts a bitmap to 1-bit monochrome bitmap using a threshold T between [0..255]. The function first converts the bitmap to a 8-bit greyscale bitmap. Then, any brightness level that is less than T is set to zero, otherwise to 1. For 1-bit input bitmaps, the function clones the input bitmap and builds a monochrome palette.

Parameters:
threshold - The threshold to use
Returns:
new instance of FreeImage

dither

public final FreeImage dither(int ditherAlgorithm)
Converts a bitmap to 1-bit monochrome bitmap using a dithering algorithm. For 1-bit input bitmaps, the function clones the input bitmap and builds a monochrome palette. The algorithm parameter specifies the dithering algorithm to be used. The function first converts the bitmap to a 8-bit greyscale bitmap. Then, the bitmap is dithered using one of the following algorithms:

FID_FS Floyd & Steinberg error diffusion algorithm
FID_BAYER4x4 Bayer ordered dispersed dot dithering (order 2 – 4x4 -dithering matrix)
FID_BAYER8x8 Bayer ordered dispersed dot dithering (order 3 – 8x8 -dithering matrix)
FID_BAYER16x16 Bayer ordered dispersed dot dithering (order 4 – 16x16 dithering matrix)
FID_CLUSTER6x6 Ordered clustered dot dithering (order 3 - 6x6 matrix)
FID_CLUSTER8x8 Ordered clustered dot dithering (order 4 - 8x8 matrix)
FID_CLUSTER16x16 Ordered clustered dot dithering (order 8 - 16x16 matrix)

References
Ulichney, R., Digital Halftoning. The MIT Press, Cambridge, MA, 1987.
Hawley S., Ordered Dithering. Graphics Gems, Academic Press, 1990.

Parameters:
ditherAlgorithm - dithering algorithm to use (see also FREE_IMAGE_DITHER)
Returns:
new instance of FreeImage

getPixelColor

public final int getPixelColor(int x,
                               int y)
Get the pixel color of a 16-, 24- or 32-bit image at position (x, y), including range check (slow access). Parameter x is the pixel position in horizontal direction, and parameter y is the pixel position in vertical direction.

Parameters:
x - horizontal position
y - vertical position
Returns:
the color of a pixel

getPixelIndex

public final short getPixelIndex(int x,
                                 int y)
Get the pixel index of a palettized image at position (x, y), including range check (slow access). Parameter x is the pixel position in horizontal direction, and parameter y is the pixel position in vertical direction.

Parameters:
x - horizontal position
y - vertical position
Returns:
pixel index of a palettized image

setPixelColor

public final void setPixelColor(int x,
                                int y,
                                int color)
Set the pixel color of a 16-, 24- or 32-bit image at position (x, y), including range check (slow access). Parameter x is the pixel position in horizontal direction, and parameter y is the pixel position in vertical direction.

Parameters:
x - horizontal position
y - vertical position
color - the RGB color

setPixelIndex

public final void setPixelIndex(int x,
                                int y,
                                short index)
Set the pixel index of a palettized image at position (x, y), including range check (slow access). Parameter x is the pixel position in horizontal direction, and parameter y is the pixel position in vertical direction.

Parameters:
x - horizontal position
y - vertical position
index - the pixel index