Module `fipImage`

Corona wrapper for fipImage, a class used to manage all photo related images and all image types used by the library.

fipImage encapsulates the FIBITMAP format. It relies on the FreeImage library, especially for loading / saving images and for bit depth conversion.

Functions

fipImage:accessPixels ()	Returns a pointer to the bitmap bits.
fipImage:adjustBrightness (percentage)	Adjusts the brightness of a 8, 24 or 32-bit image by a certain amount.
fipImage:adjustBrightnessContrastGamma (brightness, constrast, gamma)	Adjusts an image's brightness, contrast and gamma within a single operation.
fipImage:adjustContrast (percentage)	Adjusts the contrast of a 8, 24 or 32-bit image by a certain amount.
fipImage:adjustCurve (LUT, channel)	Perfoms an histogram transformation on a 8, 24 or 32-bit image according to the values of a lookup table (LUT).
fipImage:adjustGamma (gamma)	Performs gamma correction on a 8, 24 or 32-bit image.
fipImage:assign (image)	Assign one image to another.
fipImage:clear ()	Destroy image data.
fipImage:clearThumbnail ()	Clear the thumbnail possibly attached to the bitmap.
fipImage:clone (image)	Creates a new image that is a copy of another.
fipImage:colorQuantize (algorithm)	Quantizes a full colour 24-bit bitmap to a palletised 8-bit bitmap.
fipImage:combineChannels (red, green, blue)	Builds a 24-bit RGB image given its red, green and blue channel.
fipImage:convertTo4Bits ()	Converts the bitmap to 4 bits.
fipImage:convertTo8Bits ()	Converts the bitmap to 8 bits.
fipImage:convertTo16Bits555 ()	Converts the bitmap to 16 bits.
fipImage:convertTo16Bits565 ()	Converts the bitmap to 16 bits.
fipImage:convertTo24Bits ()	Converts the bitmap to 24 bits.
fipImage:convertTo32Bits ()	Converts the bitmap to 32 bits.
fipImage:convertToFloat ()	Converts the bitmap to a 32-bit float image.
fipImage:convertToGrayscale ()	Converts the bitmap to 8 bits.
fipImage:convertToRGB16 ()	Converts the bitmap to a 48-bit RGB16 image.
fipImage:convertToRGBA16 ()	Converts the bitmap to a 64-bit RGBA16 image.
fipImage:convertToRGBAF ()	Converts the bitmap to a 128-bit RGBAF image.
fipImage:convertToRGBF ()	Converts the bitmap to a 96-bit RGBF image.
fipImage:convertToType (image_type, scale_linearImage)	Converts an image to a type supported by FreeImage.
fipImage:convertToUINT16 ()	Converts the bitmap to a 16-bit unsigned short image.
fipImage:copySubImage (left, top, right, bottom)	Copy a sub part of the current image and returns it as a fipImage object.
fipImage:crop (left, top, right, bottom)	Crop a sub part of the current image and update it accordingly.
fipImage:dither (algorithm)	Converts a 8-bit image to a monochrome 1-bit image using a dithering algorithm.
fipImage:flipHorizontal ()	Flip the image horizontally along the vertical axis.
fipImage:flipVertical ()	Flip the image vertically along the horizontal axis.
fipImage:getBitsPerPixel ()	Returns the bitdepth of the bitmap.
fipImage:getChannel (channel)	Retrieves the red, green, blue or alpha channel of a 24- or 32-bit BGR[A] image.
fipImage:getColorsUsed ()	Retrieves the number of colours used in the bitmap.
fipImage:getColorType ()	Investigates the colour type of the bitmap.
fipImage:getFileBkColor ()	Retrieves the file background color of an image.
fipImage:getHeight ()	Returns the image height in pixels.
fipImage:getHistogram (pointer[, channel="BLACK"])	Computes image histogram.
fipImage:getHorizontalResolution ()	Returns the bitmap resolution along the X axis, in pixels / cm.
fipImage:getImageMemorySize ()	Returns the memory footprint of a bitmap, in bytes.
fipImage:getImageSize ()	Returns the size of the bitmap in bytes.
fipImage:getImageType ()	Returns the data type of the image.
fipImage:getInfo ()	Returns a pointer to the bitmap's BITMAPINFO header.
fipImage:getInfoHeader ()	Returns a pointer to the bitmap's BITMAPINFOHEADER.
fipImage:getLine ()	Returns the width of the bitmap in bytes.
fipImage:getMetadata (model, key)	Retrieve a metadata attached to the dib.
fipImage:getMetadataCount (model)	Returns the number of tags contained in the model metadata model attached to the dib.
fipImage:getPalette ()	Returns a pointer to the bitmap's palette.
fipImage:getPaletteSize ()	Returns the palette size in bytes.
fipImage:getPixelColor (x, y)	Get the pixel color of a 16-, 24- or 32-bit image at position (x, y), including range check (slow access).
fipImage:getPixelIndex (x, y)	Get the pixel index of a 1-, 4- or 8-bit palettized image at position (x, y), including range check (slow access).
fipImage:getThumbnail ()	Retrieves a copy the thumbnail possibly attached to the bitmap.
fipImage:getScanLine (scanline)	Returns a pointer to the start of the given scanline in the bitmap's data-bits.
fipImage:getTransparencyCount ()	8-bit transparency: get the number of transparent colors.
fipImage:getTransparencyTable ()	8-bit transparency: get the bitmap's transparency table.
fipImage:getScanWidth ()	Returns the width of the bitmap in bytes rounded to the nearest DWORD.
fipImage:getVerticalResolution ()	Returns the bitmap resolution along the Y axis, in pixels / cm.
fipImage:getWidth ()	Returns the image width in pixels.
fipImage:hasFileBkColor ()	Getter.
fipImage:hasThumbnail ()	Check if the image has an embedded thumbnail.
fipImage:invert ()	Inverts each pixel data.
fipImage:isGrayscale ()	Getter.
fipImage:isModified ()	Get the image status.
fipImage:isTransparent ()	Getter.
fipImage:isValid ()	Indicates whether the image is valid for use.
fipImage:load (name, flags)	Loads an image from disk, given its file name and an optional flag.
fipImage:loadFromMemory (memIO, flags)	Loads an image using the specified memory stream and an optional flag.
fipImage:makeThumbnail (max_size[, convert=true])	Creates a thumbnail image keeping aspect ratio.
fipImage:newTexture ()	Get an external texture from the current state that may be used in Corona.
fipImage:pasteSubImage (src, left, top[, alpha=256])	Alpha blend or combine a sub part image with the current image.
fipImage:rescale (new_width, new_height, filter)	Rescale the image to a new width / height.
fipImage:rotate (angle, bkcolor)	Image rotation by means of three shears.
fipImage:rotateEx (angle, x_shift, y_shift, x_origin, y_origin, use_mask)	Image translation and rotation using B-Splines.
fipImage:save (name, flags)	Saves an image to disk, given its file name and an optional flag.
fipImage:saveToMemory (memIO, flags)	Saves an image using the specified memory stream and an optional flag.
fipImage:setChannel (image, channel)	Insert an 8-bit dib into a 24- or 32-bit image.
fipImage:setFileBkColor ([bkcolor])	Set the file background color of an image.
fipImage:setHorizontalResolution (value)	Set the bitmap resolution along the X axis, in pixels / cm.
fipImage:setMetadata (key, tag)	Attach a new FreeImage tag to the dib.
fipImage:setModified ([bStatus=true])	Set the image status as 'modified'.
fipImage:setPixelColor (x, y, value)	Set the pixel color of a 16-, 24- or 32-bit image at position (x, y), including range check (slow access).
fipImage:setPixelIndex (x, y, value)	Set the pixel index of a 1-, 4- or 8-bit palettized image at position (x, y), including range check (slow access).
fipImage:setSize (type, w, h, bpp[, rmask=0[, gmask=0[, bmask=0]]])	Image allocator.
fipImage:setThumbnail (image)	Attach a thumbnail to the bitmap.
fipImage:setTransparencyTable ()	8-bit transparency: set the bitmap's transparency table.
fipImage:setVerticalResolution (value)	Set the bitmap resolution along the Y axis, in pixels / cm.
fipImage:splitChannels ()	Split a 24-bit RGB image into 3 greyscale images corresponding to the red, green and blue channels.
fipImage:threshold (T)	Converts the bitmap to 1 bit using a threshold T.
fipImage:toneMapping (tmo[, first=0[, second=0[, third=1[, fourth=0]]]])	Converts a High Dynamic Range image (48-bit RGB or 96-bit RGB Float) to a 24-bit RGB image.

Functions

fipImage:accessPixels ()

Returns a pointer to the bitmap bits.

It is up to you to interpret these bytes correctly, according to the results of FreeImageGetBPP and GetRedMask, FreeImageGetGreenMask and FreeImage_GetBlueMask. Use this function with fipImage:getScanWidth to iterates through the pixels.

Returns:

string

fipImage:adjustBrightness (percentage)

Adjusts the brightness of a 8, 24 or 32-bit image by a certain amount.

Parameters:

percentage number Where -100 <= percentage <= 100.

A value 0 means no change, less than 0 will make the image darker and greater than 0 will make the image brighter.

Returns:

boolean

Parameters:

brightness number
constrast number
gamma number

Returns:

boolean

Parameters:

percentage number Where -100 <= percentage <= 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.

Returns:

boolean

Parameters:

LUT Lookup table. The size of 'LUT' is assumed to be 256.
channel The color channel to be processed (only used with 24 & 32-bit DIB).

Returns:

boolean

fipImage:adjustGamma (gamma)

Performs gamma correction on a 8, 24 or 32-bit image.

Parameters:

gamma number Gamma value to use. A value of 1.0 leaves the image alone, less than one darkens it, and greater than one lightens it.

Returns:

boolean

Parameters:

image fipImage or userdata Image to assign. (TODO: userdata kind of shaky)

fipImage:clear ()

Destroy image data.

fipImage:clearThumbnail ()

Clear the thumbnail possibly attached to the bitmap.

Returns:

boolean

fipImage:clone (image)

Creates a new image that is a copy of another.

Parameters:

image fipImage Image to clone.

Returns:

fipImage

fipImage:colorQuantize (algorithm)

Quantizes a full colour 24-bit bitmap to a palletised 8-bit bitmap.

The quantize parameter specifies which colour reduction algorithm should be used.

Parameters:

algorithm string Color quantization algorithm to use, cf. enums.FREE_IMAGE_QUANTIZE.

Returns:

boolean

fipImage:combineChannels (red, green, blue)

Builds a 24-bit RGB image given its red, green and blue channel.

Parameters:

red fipImage Input red channel.
green fipImage Input green channel.
blue fipImage Input blue channel.

Returns:

boolean

false

true

fipImage:convertTo4Bits ()

Converts the bitmap to 4 bits.

Returns:

boolean

fipImage:convertTo8Bits ()

Converts the bitmap to 8 bits.

If the bitmap is 24 or 32-bit RGB, the colour values are converted to greyscale.

Returns:

boolean

fipImage:convertTo16Bits555 ()

Converts the bitmap to 16 bits.

The resulting bitmap has a layout of 5 bits red, 5 bits green, 5 bits blue and 1 unused bit.

Returns:

boolean

fipImage:convertTo16Bits565 ()

Converts the bitmap to 16 bits.

The resulting bitmap has a layout of 5 bits red, 6 bits green and 5 bits blue.

Returns:

boolean

fipImage:convertTo24Bits ()

Converts the bitmap to 24 bits.

Returns:

boolean

fipImage:convertTo32Bits ()

Converts the bitmap to 32 bits.

Returns:

boolean

fipImage:convertToFloat ()

Converts the bitmap to a 32-bit float image.

Returns:

boolean

image_type string New image type, cf. enums.FREE_IMAGE_TYPE.
scale_linearImage bool pixels must be scaled linearly when converting to a standard bitmap?

Returns:

boolean

fipImage:convertToUINT16 ()

Converts the bitmap to a 16-bit unsigned short image.

Returns:

boolean

fipImage:copySubImage (left, top, right, bottom)

Copy a sub part of the current image and returns it as a fipImage object.

This method works with any bitmap type.

Parameters:

left int Specifies the left position of the cropped rectangle.
top int Specifies the top position of the cropped rectangle.
right int Specifies the right position of the cropped rectangle.
bottom int Specifies the bottom position of the cropped rectangle.

Returns:

boolean Operation was successful?
fipImage On success, output subimage.

fipImage:crop (left, top, right, bottom)

Crop a sub part of the current image and update it accordingly.

This method works with any bitmap type.

Parameters:

left int Specifies the left position of the cropped rectangle.
top int Specifies the top position of the cropped rectangle.
right int Specifies the right position of the cropped rectangle.
bottom int Specifies the bottom position of the cropped rectangle.

Returns:

boolean

fipImage:dither (algorithm)

Converts a 8-bit image to a monochrome 1-bit image using a dithering algorithm.

Parameters:

algorithm string Dithering algorithm to use, cf. enums.FREE_IMAGE_DITHER.

Returns:

boolean

fipImage:flipHorizontal ()

Flip the image horizontally along the vertical axis.

Returns:

boolean

fipImage:flipVertical ()

Flip the image vertically along the horizontal axis.

Returns:

boolean

fipImage:getBitsPerPixel ()

Returns the bitdepth of the bitmap.

When the image type is BITMAP, valid bitdepth can be 1, 4, 8, 16, 24 or 32.

Returns:

uint

Parameters:

channel string Color channel to extract, cf. enums.FREE_IMAGE_COLOR_CHANNEL.

Returns:

boolean Operation was successful?
fipImage On success, the output image to be extracted.

fipImage:getColorsUsed ()

Retrieves the number of colours used in the bitmap.

If the bitmap is non-palletised, 0 is returned.

Returns:

uint

fipImage:getColorType ()

Investigates the colour type of the bitmap.

Returns:

string

enums.FREE_IMAGE_COLOR_TYPE

fipImage:getFileBkColor ()

Retrieves the file background color of an image.

For 8-bit images, the color index in the palette is returned in the rgbReserved member of the result.

Returns:

boolean Operation was successful?
RGBQUAD On success, a color quad. (TODO?)

fipImage:getHeight ()

Returns the image height in pixels.

Returns:

uint

fipImage:getHistogram (pointer[, channel="BLACK"])

Computes image histogram.

For 24-bit and 32-bit images, histogram can be computed from red, green, blue and black channels. For 8-bit images, histogram is computed from the black channel. Other bit depth is not supported.

NYI

Parameters:

pointer PDWORD to an histogram array. Size of this array is assumed to be 256. (TODO!)
channel string Color channel to use, cf. enums.FREE_IMAGE_COLOR_CHANNEL. (default "BLACK")

Returns:

boolean

fipImage:getHorizontalResolution ()

Returns the bitmap resolution along the X axis, in pixels / cm.

Returns:

number

fipImage:getImageMemorySize ()

Returns the memory footprint of a bitmap, in bytes.

Returns:

uint

fipImage:getImageSize ()

Returns the size of the bitmap in bytes.

The size of the bitmap is the BITMAPINFOHEADER + the size of the palette + the size of the bitmap data.

Returns:

uint

fipImage:getImageType ()

Returns the data type of the image.

Returns:

string

enums.FREE_IMAGE_TYPE

fipImage:getInfo ()

Returns a pointer to the bitmap's BITMAPINFO header. NYI

fipImage:getInfoHeader ()

Returns a pointer to the bitmap's BITMAPINFOHEADER. NYI

fipImage:getLine ()

Returns the width of the bitmap in bytes.

This is not the size of the scanline.

Returns:

uint

Parameters:

model string Metadata model to look for, cf. enums.FREE_IMAGE_MDMODEL.
key string Metadata field name.

Returns:

boolean Operation was successful?
fipTag On success, the tag.

fipImage:getMetadataCount (model)

Returns the number of tags contained in the model metadata model attached to the dib.

Parameters:

model string Metadata model to look for, cf. enums.FREE_IMAGE_MDMODEL.

Returns:

uint

fipImage:getPalette ()

Returns a pointer to the bitmap's palette.

If the bitmap doesn't have a palette, getPalette returns NULL. (TODO!)

Returns:

array

fipImage:getPaletteSize ()

Returns the palette size in bytes.

Returns:

uint

fipImage:getPixelColor (x, y)

Get the pixel color of a 16-, 24- or 32-bit image at position (x, y), including range check (slow access).

Parameters:

x uint Pixel position in horizontal direction.
y uint Pixel position in vertical direction.

Returns:

boolean Operation was successful?
RGBQUAD On success, pixel color. (TODO?)

fipImage:getPixelIndex (x, y)

Get the pixel index of a 1-, 4- or 8-bit palettized image at position (x, y), including range check (slow access).

Parameters:

x uint Pixel position in horizontal direction.
y uint Pixel position in vertical direction.

Returns:

boolean Operation was successful?
BYTE On success, pixel index. (TODO?)

fipImage:getThumbnail ()

Retrieves a copy the thumbnail possibly attached to the bitmap.

Returns:

boolean Operation was successful?
fipImage On success (and a thumbnail was present), the image.

fipImage:getScanLine (scanline)

Returns a pointer to the start of the given scanline in the bitmap's data-bits.

This pointer can be cast according to the result returned by fipImage:getImageType.

Use this function with fipImage:getScanWidth to iterates through the pixels. NYI

Parameters:

scanline uint

Returns:

boolean

Returns:

boolean

fipImage:isValid ()

Indicates whether the image is valid for use.

max_size uint Maximum width or height in pixel units.
convert bool Convert the image to a standard type? (default true)

Returns:

boolean

fipImage:newTexture ()

Get an external texture from the current state that may be used in Corona.

TODO: More thorough, caveats about threading

Returns:

CoronaExternalTexture

display

filename

baseDir

fipImage:pasteSubImage (src, left, top[, alpha=256])

Alpha blend or combine a sub part image with the current image.

The bit depth of dst bitmap must be greater than or equal to the bit depth of src. Upper promotion of src is done internally. Supported bit depth equals to 4, 8, 16, 24 or 32.

Parameters:

src fipImage Source subimage.
left int Specifies the left position of the sub image.
top int Specifies the top position of the sub image.
alpha int Alpha blend factor. The source and destination images are alpha blended if alpha = 0..255. If alpha > 255, then the source image is combined to the destination image. (default 256)

Returns:

boolean

fipImage:rescale (new_width, new_height, filter)

Rescale the image to a new width / height.

Parameters:

new_width uint New image width.
new_height uint New image height.
filter string The filter parameter specifies which resampling filter should be used. (TODO: FREEIMAGEFILTER)

Returns:

boolean

fipImage:rotate (angle, bkcolor)

Image rotation by means of three shears. NYI

Parameters:

angle number Image rotation angle, in degree.
bkcolor Background color (image type dependent), default to black background. (TODO)

Returns:

Returns rotated dib if successful, returns NULL otherwise. (TODO: bool in docs)

fipImage:rotateEx (angle, x_shift, y_shift, x_origin, y_origin, use_mask)

Image translation and rotation using B-Splines.

Parameters:

angle number Image rotation angle, in degree.
x_shift number Image horizontal shift.
y_shift number Image vertical shift.
x_origin number Origin of the x-axis.
y_origin number Origin of the y-axis.
use_mask bool Mask the image? Image mirroring is applied when use_mask is false.

Returns:

Returns the translated & rotated dib if successful, returns NULL otherwise. (TODO: bool in docs)

fipImage:save (name, flags)

Saves an image to disk, given its file name and an optional flag.

Parameters:

name string Path and file name of the image to save.
flags {string,...}, string or nil Format-dependent flags.

Returns:

boolean

fipImage:saveToMemory (memIO, flags)

Saves an image using the specified memory stream and an optional flag.

Parameters:

memIO fipMemoryIO FreeImage memory stream.
flags {string,...}, string or nil Format-dependent flags.

Returns:

boolean

fipImage:setChannel (image, channel)

Insert an 8-bit dib into a 24- or 32-bit image.

Parameters:

image fipImage Input 8-bit image to insert.
channel string Color channel to replace, cf. enums.FREE_IMAGE_COLOR_CHANNEL.

Returns:

boolean

fipImage:setFileBkColor ([bkcolor])

Set the file background color of an image.

When saving an image to PNG, this background color is transparently saved to the PNG file. When the bkcolor parameter is absent, the background color is removed from the image.

Parameters:

bkcolor string (TODO: RGBQUAD)

Returns:

boolean

fipImage:setHorizontalResolution (value)

Set the bitmap resolution along the X axis, in pixels / cm.

Parameters:

value number

fipImage:setMetadata (key, tag)

Attach a new FreeImage tag to the dib.

Sample use (TODO: Lua version):

 fipImage image;
 -- ...
 fipTag tag;
 tag.setKeyValue("Caption/Abstract", "my caption");
 image.setMetadata(FIMD_IPTC, tag.getKey(), tag);
 tag.setKeyValue("Keywords", "FreeImage;Library;Images;Compression");
 image.setMetadata(FIMD_IPTC, tag.getKey(), tag);

Parameters:

key string Tag field name.
tag fipTag Tag to be attached.

Returns:

Operation

fipImage:setModified ([bStatus=true])

Set the image status as 'modified'.

When using the fipWinImage class, the image status is used to refresh the display. It is changed to FALSE whenever the display has just been refreshed. NYI (missed it :) )

Parameters:

bStatus bool The image should be marked as modified? (default true)

Parameters:

x uint Pixel position in horizontal direction.
y uint Pixel position in vertical direction.
value RGBQUAD Pixel color. (TODO: RGBQUAD *)

Returns:

Operation

fipImage:setPixelIndex (x, y, value)

Set the pixel index of a 1-, 4- or 8-bit palettized image at position (x, y), including range check (slow access).

Parameters:

x uint Pixel position in horizontal direction.
y uint Pixel position in vertical direction.
value BYTE Pixel index. (TODO: BYTE *)

Returns:

Operation

fipImage:setSize (type, w, h, bpp[, rmask=0[, gmask=0[, bmask=0]]])

Image allocator.

Parameters:

type string Image type, cf. enums.FREE_IMAGE_TYPE.
w uint Width.
h uint Height.
bpp uint Bitdepth.
rmask uint Red mask... (default 0)
gmask uint ...green... (default 0)
bmask uint ...and blue. (default 0)

Returns:

Operation

fipImage:setThumbnail (image)

Attach a thumbnail to the bitmap.

Parameters:

image fipImage

Returns:

Operation

fipImage:setTransparencyTable ()

8-bit transparency: set the bitmap's transparency table. NYI

fipImage:setVerticalResolution (value)

Set the bitmap resolution along the Y axis, in pixels / cm.

Parameters:

value number

fipImage:splitChannels ()

Split a 24-bit RGB image into 3 greyscale images corresponding to the red, green and blue channels.

Returns:

boolean Returns false if the dib isn't a valid image, if it's not a 24-bit image or if one of the output channel can't be allocated; otherwise true.
fipImage On success, output red channel...
fipImage ...green channel...
fipImage ...and blue channel.

fipImage:threshold (T)

Converts the bitmap to 1 bit using a threshold T.

Parameters:

T byte Threshold value in [0..255].

Returns:

boolean

fipImage:toneMapping (tmo[, first=0[, second=0[, third=1[, fourth=0]]]])

Converts a High Dynamic Range image (48-bit RGB or 96-bit RGB Float) to a 24-bit RGB image.

Parameters:

tmo string Tone mapping operator, cf. enums.FREE_IMAGE_TMO.
first number First tone mapping algorithm parameter (algorithm dependant). (default 0)
second number Second tone mapping algorithm parameter (algorithm dependant). (default 0)
third number Third tone mapping algorithm parameter (algorithm dependant). (default 1)
fourth number Fourth tone mapping algorithm parameter (algorithm dependant). (default 0)

Returns:

boolean

FreeImage

Contents

Modules

Module fipImage

Functions

Functions

Returns:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

See also:

Parameters:

Returns:

Parameters:

Returns:

See also:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Returns:

Returns:

Returns:

Returns:

Returns:

Returns:

Returns:

Returns:

Returns:

Returns:

Returns:

Parameters:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Returns:

Returns:

See also:

Parameters:

Returns:

Returns:

Returns:

Returns:

Returns:

Parameters:

Returns:

Returns:

Returns:

Returns:

Returns:

Returns:

See also:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Returns:

Parameters:

Returns:

Parameters:

Returns:

Returns:

Parameters:

Module `fipImage`