Index of /xtras/img_xtra/win
Name Last modified Size Description
![[PARENTDIR]](/icons/back.gif)
Parent Directory -
![[DIR]](/icons/folder.gif)
demos/ 2014-06-03 23:11 -
![[TXT]](/icons/text.gif)
readme.txt 2020-09-07 20:02 48K
![[ ]](/icons/compressed.gif)
imgxtra_v0.25.zip 2020-09-07 20:05 6.8M
-- xtra ImgXtra
-- v0.25 (c) 2020 Valentin Schmidt
-- based on FreeImage 3.18.0 and jhead 2.84
ImgXtra is a scripting xtra based on the FreeImage graphic library (http://freeimage.sourceforge.net/).
1. Features
===========
Apart from supporting additional image formats, its main benefits/additions to directors own graphic support are:
• loading (big) images in a new thread (asynchronous, without "freezing" director while loading)
• extracting embedded thumbnails and metadata from EXIF headers of JPGs and TIFFs
• saving images in the following file formats: BMP, EXR, GIF, HDR, ICO, J2K, JP2, JPEG, JXR, PBM, PBMRAW, PFM, PGM, PGMRAW, PNG, PPM, PPMRAW, TARGA, TIFF, WBMP, WEBP, XPM
• performing lossless transformations (rotation or flipping) and cropping on JPEG files (e.g. rotate a JPEG by 90° without losing quality by re-encoding)
• image scaling with various resampling filters (algorithms)
• advanced rotation/translation
• loading/saving of image files to the memory (e.g. to save JPEG data to a database)
• raw zlib-compression
• extracting/replacing individual channels of RGB images
• color manipulations (gamma, brightness, contrast, arbitray color mappings defined by LUTs)
• histogramm calculation
• reading and changing colors of palette members
• read and write support for multipage file formats (animated gif, mutipage tiff, ico)
• quantizing/color reduction to arbitrary number of colors (either using a predefined palette, or create a palette from the image data)
• importing 8-bit palettized images at runtime, either with mapping to an existing palette or with importing the image's palette as new palette member
• acquire images from scanners and other devices that support the TWAIN interface
2. Supported image file formats
===============================
The xtra supports the following image file formats.
formats can be can either be specified as string, e.g. "PNG", or as number, e.g. 13:
• BMP = 0
• ICO = 1
• JPEG = 2
• JNG = 3 (read only)
• KOALA = 4 (read only)
• LBM = 5 (read only)
• MNG = 6 (read only)
• PBM = 7
• PBMRAW = 8
• PCD = 9 (read only)
• PCX = 10 (read only)
• PGM = 11
• PGMRAW = 12
• PNG = 13
• PPM = 14
• PPMRAW = 15
• RAS = 16 (read only)
• TARGA = 17
• TIFF = 18
• WBMP = 19
• PSD = 20 (read only)
• CUT = 21 (read only)
• XBM = 22 (read only)
• XPM = 23
• DDS = 24 (read only)
• GIF = 25
• HDR = 26
• FAXG3 = 27 (read only)
• SGI = 28 (read only)
• EXR = 29
• J2K = 30
• JP2 = 31
• PFM = 32
• PICT = 33 (read only)
• RAW = 34 (read only)
• WEBP = 35
• JXR = 36
3. Interface
============
-- CONSTRUCTOR:
new object me
-- UTILITIES:
ix_lastError object me
-- LOAD IMAGES ASYNCHRONOUSLY:
ix_threadSetCallback object me, object props
ix_threadStart object me
ix_threadStop object me
ix_threadLoadImage object me, object props
ix_threadLoadData object me, object props
ix_threadLoadMemory object me, object props
ix_threadMultiPageExtractPage object me, object props
-- LOAD/SAVE TO FILE:
ix_loadImage object me, object props
ix_saveImage object me, object props
-- LOAD/SAVE TO MEMORY:
ix_loadMemoryImage object me, object props
ix_saveMemoryImage object me, object props
-- IMAGE TO STRING:
ix_imageToRaw object me, object props
ix_rawToImage object me, object props
-- RESCALE:
ix_rescaleImage object me, object props
-- ROTATION:
ix_rotate object me, object props
ix_rotateEx object me, object props
ix_flipHorizontal object me, object props
ix_flipVertical object me, object props
-- LOSSLESS JPEG OPERATIONS:
ix_jpegTransform object me, object props
ix_jpegCrop object me, object props
-- IMAGE INFO:
ix_getInfo object me, object props
ix_getHistogramm object me, object props
ix_getICCProfile object me, object props
-- ZLIB-COMPRESSION:
ix_zlibCompress object me, object props
ix_zlibUncompress object me, object props
-- PALETTES:
ix_getPaletteColors object me, object props
ix_setPaletteColors object me, object props
-- COLOR MANIPULATION:
ix_adjustCurve object me, object props
ix_adjustGamma object me, object props
ix_adjustBrightness object me, object props
ix_adjustContrast object me, object props
ix_invert object me, object props
ix_applyICCProfile object me, object props
-- QUANTIZE:
ix_quantizeImage object me, object props
ix_convertToGreyscale object me, object props
-- CHANNELS:
ix_getChannel object me, object props
ix_setChannel object me, object props
-- MULTIPAGE:
ix_multiPageAddPages object me, object props
ix_multiPageGetPageCount object me, object props
ix_multiPageExtractPage object me, object props
-- TWAIN:
ix_twainSetCallback object me, object props
ix_twainSelectSource object me
ix_twainAcquireFile object me, object props
ix_twainAcquireImage object me, *props
-- OTHER:
ix_getExplorerIcon object me, object props
ix_getExplorerThumb object me, object props
ix_xCrc32String object me, object props
4. Function Overview
====================
--**************************************
-- CONSTRUCTOR
--**************************************
----------------------------------------
-- new object me
----------------------------------------
--**************************************
-- UTLITIES
--**************************************
----------------------------------------
-- ix_lastError object me
----------------------------------------
Returns: #string
--**************************************
-- LOAD IMAGES ASYNCHRONOUSLY
--**************************************
----------------------------------------
-- ix_threadSetCallback object me, props
----------------------------------------
Assigns a lingo callback handler that will be called by the xtra when an image file was loaded by ix_threadLoadImage. Either an image object (success) or 0 (failure) will be passed to this callback handler.
If a reference to a script object or a script is passed as optional parameter "target", this object/script will be called, otherwise the callback is called on movie level (i.e. it's assumed to be in a movie script).
Parameters:
===========
REQUIRED:
"callback": #symbol
OPTIONAL:
"target": #object (#instance or #_movie)
Returns: void
----------------------------------------
-- ix_threadStart object me
----------------------------------------
Starts a secondary thread. Has to be called before ix_threadLoadImage can be used.
Returns: 1 or 0
----------------------------------------
-- ix_threadStop object me
----------------------------------------
Stops the secondary thread, in case it was running.
Returns: void
----------------------------------------
-- ix_threadLoadImage object me, props
----------------------------------------
Starts loading an external image file in a secondary thread. ix_threadStart has to be called before. When the image is loaded, it's passed as image object to a callback function that was previously defined with ix_threadSetCallback.
Parameter flags (default = 0) can be used to adjust file format specific options (see table below).
If parameters width and height are specified (and >0), the resulting image is automatically rescaled to those dimensions.
Parameter resize_filter can be used to specify a certain resampling method (default = bicubic). For available filters see rescale_filter constants below, and for a more detailed description of the resampling filters see FreeImagexxx.pdf.
Notice: all 8-bit images are interpreted as grayscale images.
Parameters:
===========
REQUIRED:
"filename": #string
OPTIONAL:
"format": #integer or #string
"flags": #integer
"use_profile"
"width": #integer
"height": #integer
"filter": #integer
"map": paletteRef (#member or #symbol) -> map to this (8-bit) palette
"palette": paletteRef (#member or #symbol): use this as paletteRef (no mapping!)
"colors": (empty) #list: filled with colors of actual palette (8 bit only)
"transparency": (empty) #list filled with transparency index (later: transparency table?) (8 bit only)
"offset": #integer
Returns: 1 or 0
----------------------------------------
-- ix_threadLoadData object me, props
----------------------------------------
Parameters:
===========
REQUIRED:
"filename": #string
OPTIONAL:
"offset": #integer
"size": #integer
Returns: 1 or 0
----------------------------------------
-- ix_threadLoadMemory object me, props
----------------------------------------
Parameters:
===========
REQUIRED:
"data": #string or #bytearray
OPTIONAL:
"offset": #integer
"size": #integer
"format": #integer or #string
"flags": #integer
Returns: 1 or 0
----------------------------------------
-- ix_threadMultiPageExtractPage object me, props
----------------------------------------
Parameters:
===========
REQUIRED:
"filename": #string
OPTIONAL:
"page": #integer
"format": #integer or #string
"flags": #integer
"use_profile": #integer
"width": #integer
"height": #integer
"filter": #integer
"map": paletteRef (#member or #symbol) -> map to this (8-bit) palette
"palette": paletteRef (#member or #symbol): use this as paletteRef (no mapping!)
"colors": (empty) #list: filled with colors of actual palette (8 bit only)
"transparency": (empty) #list filled with transparency index (later: transparency table?) (8 bit only)
Returns: 1 or 0
--**************************************
-- LOAD/SAVE TO FILE
--**************************************
----------------------------------------
-- ix_loadImage object me, props
----------------------------------------
Loads an external image file and directly returns it as image object.
Parameter "flags" can be used to (default = 0) adjust file format specific options (see table below).
If the image is 8-bit, you can optionally specify a "palette" (either be a memberRef to a palette-member or a symbol for a build-in palette, e.g. #systemWin) for the image. if you don't specify a palette (parameter palette_member_ref_or_symbol omitted or set to 0), the internal palette from the original file is imported as new palette member, and the new image uses this new palette.
If parameters "width" and "height" are specified (and >0), the resulting image is automatically rescaled to those dimensions.
Parameter "filter" can be used to specify a certain resampling method (default = bicubic). For available filters see rescale_filter constants below, and for a more detailed description of the resampling filters see FreeImagexxx.pdf.
Parameters:
===========
REQUIRED:
"filename": #string
OPTIONAL:
"format": #integer or #string
"flags": #integer
"icc_file": #string
"icc_data": #string or #bytearray
"use_profile": #integer
"width": #integer
"height": #integer
"filter": #integer
"map": paletteRef (#member or #symbol) -> map to this (8-bit) palette
"palette": paletteRef (#member or #symbol): use this as paletteRef (no mapping!)
"colors": (empty) #list: filled with colors of actual palette (8 bit only)
"transparency": (empty) #list filled with transparency index (later: transparency table?) (8 bit only)
"offset": #integer
Returns: #image (success) or 0 (failure)
----------------------------------------
-- ix_saveImage object me, props
----------------------------------------
Saves a lingo image as external file in a certain file format specified by "format" (either as integer or string, see section Supported image file formats). If image_file_format is omitted, the format is determined by the filename, if possible.
Parameter "flags" (default = 0) can be used to adjust file format specific options (see table below).
If the image is 8-bit and the specified a file format supports 8-bit (like e.g. PNG or GIF), you can specify a palette" (either be a memberRef to a palette-member or a symbol for a build-in palette, e.g. #systemWin) that will be used in the saved image file. If you don't specify a palette, the saved image uses the grayscale palette.
Parameters:
===========
REQUIRED:
"image": #image
"filename": #string
OPTIONAL:
"format": #integer or #string
"flags": #integer
"icc_file": #string
"icc_data": #string or #bytearray
"palette": #member or #symbol or #list: use this as paletteRef (no mapping!)
"transparency": #integer (later: #list?) -> make color transparent!
"resX": #integer -> hor. resolution in pixels-per-meter (ppm = dpi * 10000 / 254)
"resY": #integer -> vert. resolution in pixels-per-meter (ppm = dpi * 10000 / 254)
Returns: 1 (success) or 0 (failure)
--**************************************
-- LOAD/SAVE TO MEMORY
--**************************************
----------------------------------------
-- ix_loadMemoryImage object me, props
----------------------------------------
Loads an image file from the memory (string "data") and directly returns it as image object.
Parameters:
===========
REQUIRED:
"data": #string
OPTIONAL:
"format": #integer or #string
"flags": #integer
"icc_file": #string
"icc_data": #string or #bytearray
"use_profile": #integer
"width": #integer
"height": #integer
"filter": #integer (was: rescale_filter)
"map": paletteRef (#member or #symbol) -> map to this (8-bit) palette
"palette": paletteRef (#member or #symbol): use this as paletteRef (no mapping!)
"colors": (empty) #list: filled with colors of actual palette (8 bit only)
"transparency": (empty) #list filled with transparency index (later: transparency table?) (8 bit only)
"offset": #integer
Returns: #image (success) or 0 (failure)
----------------------------------------
-- ix_saveMemoryImage object me, props
----------------------------------------
Like ix_saveImage(), but the image file data is not saved to the file system, but returned as bytearray.
Parameters:
===========
REQUIRED:
"image": #image
"format": #integer or #string
OPTIONAL:
"flags": #integer
"icc_file": #string
"icc_data": #string or #bytearray
"palette": #member or #symbol or #list: use this as paletteRef (no mapping!)
"transparency": #integer (later: #list?) -> make color transparent!
"resX": #integer -> hor. resolution in pixels-per-meter (ppm = dpi * 10000 / 254)
"resY": #integer -> vert. resolution in pixels-per-meter (ppm = dpi * 10000 / 254)
Returns: #bytearray (success) or 0 (failure)
--**************************************
-- IMAGE TO STRING
--**************************************
----------------------------------------
-- ix_imageToRaw object me, props
----------------------------------------
Returns a bytearray that represents the image. In case of 24-bit images (or 32-bit but without real alpha-channel), the color components are interleaved, i.e. each pixel is represented by 3 bytes in the byte-order BGR. In case of 32-bit-images with alpha-channel the byte-order is BGRA.
Parameters:
===========
REQUIRED:
"image": #image
Returns: #bytearray (success) or 0 (failure)
----------------------------------------
-- ix_rawToImage object me, props
----------------------------------------
Converts a binary string/bytearray "data" to an image object. If optional parameter "pattern" (default = "BGRA") is not specified, the data is interpreted as interleaved data for a 32-bit image with the the byte-order "BGRA". If the byte-order is different, or if the original image had no alpha-channel, another byte-order has to be specified here, e.g. "BGR" or "RGB". The function also supports CMYK image-data, which is converted to RGB on the fly. For such CMYK data you have to specify e.g. "CMYK" or "CMYKA". And for 8-bit image pass "K" as pattern.
The optional parameter "interleaved" (default = 1) specifies if the image data is arranged pixel-wise or channel-wise, i.e. if the byte stream represents e.g. BGRABGRABGRA... (interleaved=1) or BBBB...GGGG....RRRR....AAAA....(interleaved=0).
Parameters:
===========
REQUIRED:
"data": #string or #bytearray
"width": #integer
"height": #integer
OPTIONAL:
"pattern": #integer
"interleaved": #integer
Returns: #image (success) or 0 (failure)
--**************************************
-- RESCALE
--**************************************
----------------------------------------
-- ix_rescaleImage object me, props
----------------------------------------
Can be used to scale (upsample / downsample) an image with a certain resampling "filter" (algorithm). For available filters see rescale_filter constants below, and for a more detailed description of the resampling filters see FreeImagexxx.pdf for details.
Parameters:
===========
REQUIRED:
"image": #image
"width": #integer
"height": #integer
OPTIONAL:
"filter": #integer
Returns: #image (success) or 0 (failure)
--**************************************
-- ROTATION:
--**************************************
----------------------------------------
-- ix_rotate object me, props
----------------------------------------
Rotates an image and returns the result as new image (see FreeImage_RotateClassic in FreeImagexxx.pdf for details).
Parameters:
===========
REQUIRED:
"image": #image
"angle": #float
Returns: #image (success) or 0 (failure)
----------------------------------------
-- ix_rotateEx object me, props
----------------------------------------
Rotates and/or translates an image and returns the result as new image (see FreeImage_RotateEx in FreeImagexxx.pdf for details).
Parameters:
===========
REQUIRED:
"image": #image
"angle": #float
"x_shift": #float
"y_shift": #float
"x_origin": #float
"y_origin": #float
OPTIONAL:
"use_mask": #integer
Returns: #image (success) or 0 (failure)
----------------------------------------
-- ix_flipHorizontal object me, props
----------------------------------------
Parameters:
===========
REQUIRED:
"image": #image
Returns: #image (success) or 0 (failure)
----------------------------------------
-- ix_flipVertical object me, props
----------------------------------------
Parameters:
===========
REQUIRED:
"image": #image
Returns: #image (success) or 0 (failure)
--**************************************
-- LOSSLESS JPEG OPERATIONS:
--**************************************
----------------------------------------
-- ix_jpegTransform object me, props
----------------------------------------
Performs a lossless rotation or flipping on a JPEG file. Upon entry, "src_filename" is the source JPEG file and "dest_filename" the destination JPEG file. Using the same file for source and destination is allowed: the source file will be transformed and overwritten. For details see FreeImage_JPEGTransform in FreeImagexxx.pdf, for available transformations see "jpeg_operation constants" below.
Parameters:
===========
REQUIRED:
"src_filename": #string
"dest_filename": #string
"operation": #integer
OPTIONAL:
"perfect": #integer
Returns: 1 (success) or 0 (failure)
----------------------------------------
-- ix_jpegCrop object me, props
----------------------------------------
Performs a lossless crop on a JPEG file. Upon entry, "src_filename" is the source JPEG file and "dest_filename" the destination JPEG file. Using the same file for source and destination is allowed: the source file will be transformed and overwritten.
Parameters:
===========
REQUIRED:
"src_filename": #string
"dest_filename": #string
"left": #integer
"top": #integer
"right": #integer
"bottom": #integer
Returns: 1 (success) or 0 (failure)
--**************************************
-- IMAGE INFO
--**************************************
----------------------------------------
-- ix_getInfo object me, props
----------------------------------------
Returns a lingo propertyList containing information about an image file:
If the parameter "general" is set and true (<>0), the list contains the following properties (all values as integers, for imageFileFormat and imageColorType see constants below):
#width
#height
#bitsPerPixel
#paletteSize
#imageFileFormat
#imageColorType
If the parameter "exif" is set and true (<>0), the list contains the property #exif with a (long!) string of all EXIF infos found in the file (JPEG and TIFF only).
If the parameter "thumbnail" is set and true (<>0), the list contains the property #thumbnail with the embedded EXIF thumbail (if there was any) as image object (JPEG and TIFF only).
If the the file contains a 8-bit image and the parameter "transparency" is set and true (<>0), the list contains the property #transparency with the color value of the transparency color, or 0 if there is no transparency.
Parameter "flags" (default = 0) can be used to adjust file format specific options (see table below).
Parameters:
===========
REQUIRED:
"filename": #string
OPTIONAL:
"general": #integer
"exif": #integer
"thumbnail": #integer
"thumbnail_data": #string or #bytearray
"transparency": #integer
"flags": #integer
Returns: #propList (success) or 0 (failure)
----------------------------------------
-- ix_getHistogramm object me, props
----------------------------------------
Computes the histogram of a 8-bit grayscale or 32-bit RGB image and returns it as lingo list. For 32-bit images, the optional parameter "channel" specifies which channel to use (1=R, 2=G, 3=B or 5=Use"Black Channel"=default). For 8-bit images the channel parameter is ignored.
Parameters:
===========
REQUIRED:
"image": #image
OPTIONAL:
"channel": #integer
Returns: #list (success) or 0 (failure)
----------------------------------------
-- ix_getICCProfile object me, props
----------------------------------------
Parameters:
===========
REQUIRED:
"filename": #string
OPTIONAL:
"icc_filename": #string
"format": #integer or #string
"flags": #integer
-> 1 / #bytearray or 0
--**************************************
-- ZLIB-COMPRESSION
--**************************************
----------------------------------------
-- ix_zlibCompress object me, props
----------------------------------------
Compresses the string "data" using the ZLib library.
Parameters:
===========
REQUIRED:
"data": #string or #bytearray
Returns: #bytearray (success) or 0 (failure)
----------------------------------------
-- ix_zlibUncompress object me, props
----------------------------------------
Decompressed a Zlib-compressed string specified as "data". The size of the uncompressed string has to be specified as parameter "uncompressed_size". This value can be higher than the actual size, but not lower, otherwise the data is truncated, since this value determines the allocated memory.
Parameters:
===========
REQUIRED:
"data": #string or #bytearray
"uncompressed_size": #integer
Returns: #bytearray (success) or 0 (failure)
--**************************************
-- PALETTES
--**************************************
----------------------------------------
-- ix_getPaletteColors object me, props
----------------------------------------
Returns the colors of a "palette" as lingo list. The palette can either be specified as memberRef of a palette member or as symbol for a build-in palette, e.g. #systemWin.
Parameters:
===========
REQUIRED:
"palette": #member or #symbol
Returns: #list (success) or 0 (failure)
----------------------------------------
-- ix_setPaletteColors object me, props
----------------------------------------
Changes the colors of a "palette" specified as palette memberRef to the colors specified as list of color objects. If the color-list contains less than 256 colors, it will be padded with black = color(0,0,0).
Notice: Since in Director all palettes must have white at position 1 and black at position 256, those colors will be used at those positions, no matter what colors you actually specified.
Parameters:
===========
REQUIRED:
"palette": #member
"colors": #list
Returns: 1 (success) or 0 (failure)
Example:
========
paletteMem = new(#palette)
colorList = [RGB(255,255,255), RGB(255,0,0), RGB(0,255,0),RGB(0,0,255)]
xtraInst.ix_setPaletteColors( ["palette":paletteMem, "colors":colorList] )
--**************************************
-- COLOR MANIPULATION
--**************************************
----------------------------------------
-- ix_adjustCurve object me, props
----------------------------------------
Perfoms an histogram transformation on a 8-bit grayscale or 32-bit RGB image according to the values of a lookup table "lut".
The transformation changes one or more channels according to the following equation:
channel(x, y) = LUT[1+ channel(x, y)]
"lut" should be a lingo list of 256 values in the range of 0 and 255. If it has less than 256 elements, it's padded with zeros.
The color channel to be transformed is specified by the channel parameter. The transformation is done as follows:
• 8-bit grayscale images: the transformation is applied to the grey values, the channel parameter is not used.
• 32-bit images: if "channel"=0 (default), the same transformation is applied to each color plane (R, G, and B), otherwise, the it's applied to the specified channel only (1=R, 2=G, 3=B or 4=A).
Notice: call be reference!
Parameters:
===========
REQUIRED:
"image": #image
"lut": #list
OPTIONAL:
"channel": #integer
Returns: 1 (success) or 0 (failure)
----------------------------------------
-- ix_adjustGamma object me, props
----------------------------------------
Performs gamma correction on a 8-bit grayscale or 32-bit RGB 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 (call be reference!).
The color channel to be transformed is specified by the channel parameter. The transformation is done as follows:
• 8-bit grayscale images: the transformation is applied to the grey values, the channel parameter is not used.
• 32-bit images: if "channel"=0 (default), the same transformation is applied to each color plane (R, G, and B), otherwise, the it's applied to the specified channel only (1=R, 2=G, 3=B or 4=A).
Notice: call be reference!
Parameters:
===========
REQUIRED:
"image": #image
"gamma": #float
OPTIONAL:
"channel": #integer
Returns: 1 (success) or 0 (failure)
----------------------------------------
-- ix_adjustBrightness object me, props
----------------------------------------
Adjusts the brightness of a 8-bit grayscale or 32-bit RGB 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 color channel to be transformed is specified by the channel parameter. The transformation is done as follows:
• 8-bit grayscale images: the transformation is applied to the grey values, the channel parameter is not used.
• 32-bit images: if "channel"=0 (default), the same transformation is applied to each color plane (R, G, and B), otherwise, the it's applied to the specified channel only (1=R, 2=G, 3=B or 4=A).
Notice: call be reference!
Parameters:
===========
REQUIRED:
"image": #image
"percentage": #float
OPTIONAL:
"channel": #integer
Returns: 1 (success) or 0 (failure)
----------------------------------------
-- ix_adjustContrast object me, props
----------------------------------------
Adjusts the contrast of a 8-bit grayscale or 32-bit RGB 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 color channel to be transformed is specified by the channel parameter. The transformation is done as follows:
• 8-bit grayscale images: the transformation is applied to the grey values, the channel parameter is not used.
• 32-bit images: if "channel"=0 (default), the same transformation is applied to each color plane (R, G, and B), otherwise, the it's applied to the specified channel only (1=R, 2=G, 3=B or 4=A).
Notice: call be reference!
Parameters:
===========
REQUIRED:
"image": #image
"percentage": #float
OPTIONAL:
"channel": #integer
Returns: 1 (success) or 0 (failure)
----------------------------------------
-- ix_invert object me, props
----------------------------------------
Inverts the image.
The color channel to be transformed is specified by the channel parameter. The transformation is done as follows:
• 8-bit grayscale images: the transformation is applied to the grey values, the channel parameter is not used.
• 32-bit images: if "channel"=0 (default), the same transformation is applied to each color plane (R, G, and B), otherwise, the it's applied to the specified channel only (1=R, 2=G, 3=B or 4=A).
Notice: call be reference!
Parameters:
===========
REQUIRED:
"image": #image
OPTIONAL:
"channel": #integer
Returns: 1 (success) or 0 (failure)
----------------------------------------
-- ix_applyICCProfile object me, props
----------------------------------------
Applies an ICC profile to the image.
The profile can either be specified as file ("icc_file") or as binary string/bytearray ("icc_data").
Notice: call be reference!
Parameters:
===========
REQUIRED:
"image": #image
OPTIONAL:
"icc_file": #string
"icc_data": #string or #bytearray
Returns: 1 (success) or 0 (failure)
--**************************************
-- QUANTIZE
--**************************************
----------------------------------------
-- ix_quantizeImage object me, props
----------------------------------------
Quantizes a high-color 24-bit bitmap to an 8-bit palette color bitmap. The optional "method" parameter specifies the color reduction algorithm to be used:
0 = Xiaolin Wu color quantization algorithm (=default)
1 = NeuQuant neural-net quantization algorithm by Anthony Dekker
Parameter "palette_size" (should be an integer in the range 2..256) specifies the number of colors of the resulting image (default=256). To make the palette of the resulting image director compatible, it will contain white and black, even if those colors don't appear in the image, so in this case the actual colors are effectively reduced to paletteSize-2.
If the optional parameter "reserved_colors" either contains a palette memberRef, a system palette as symbol, or a list of color objects, those colors are used for quantization (and paletteSize is ignored).
Parameters:
===========
REQUIRED:
"image": #image
OPTIONAL:
"method": #integer
"palette": #member or #symbol or #list: =INPUT-PALETTE! use this as paletteRef (no mapping!)
"palette_size": #integer
"reserved_colors": #member or #symbol or #list
Returns: #image (success) or 0 (failure)
----------------------------------------
-- ix_convertToGreyscale object me, object props
----------------------------------------
Converts a 24- or 32bit RGB image to grayscale, using the following formula (known as Rec. 709 formula):
grey = (0.2126 x R + 0.7152 x G + 0.0722 x B)
Parameters:
===========
REQUIRED:
"image": #image
Returns: #image (success) or 0 (failure)
--**************************************
-- CHANNELS
--**************************************
----------------------------------------
-- ix_getChannel object me, props
----------------------------------------
Retrieves the red, green, blue or alpha channel of a 32-bit image. Paremeter "channel" can be 1 (red), 2 (green), 3 (blue) or 4 (alpha).
Parameters:
===========
REQUIRED:
"image": #image
"channel": #integer
Returns: #image (success) or 0 (failure)
----------------------------------------
-- ix_setChannel object me, props
----------------------------------------
Replaces a certain channel specified by integer "channel" (see ix_getChannel) in a 32-bit image with the 8-bit image "channel_image". Both images must have the same width and height.
Parameters:
===========
REQUIRED:
"image": #image
"channel": #integer
"channel_image": #image
Returns: 1 (success) or 0 (failure)
--**************************************
-- MULTIPAGE
--**************************************
----------------------------------------
-- ix_multiPageAddPages object me, props
----------------------------------------
Adds one or more images (specified as lingo list) as new pages/frames to a multipage image (soecified via "filename"). If the optional parameter "create_new"=1, a new multipage image file is created. Parameter "flags" can be used to specify file format specific settings (see table flags at the end of this document). "fps" can be used for an animated gif to specify the time that this frame/those frames are shown.
Parameters:
===========
REQUIRED:
"filename": #string
"images": #list
OPTIONAL:
"create_new": #integer
"flags": #integer
"fps": #integer
"palette": #member or #symbol or #list
"transparency": #integer (later: #list?) -> make color transparent!
Returns: 1 (success) or 0 (failure)
----------------------------------------
-- ix_multiPageGetPageCount object me, props
----------------------------------------
Returns the number of pages/frames of a multipage image (or 0 for failure).
Parameters:
===========
REQUIRED:
"filename": #string
OPTIONAL:
"format": #integer or #string
"flags": #integer
Returns: #integer or 0
----------------------------------------
-- ix_multiPageExtractPage object me, props
----------------------------------------
Extracts an individual page/frame from a multipage image. The page number is specified by "page" (counting starts with 1). In case of 8-bit images, if the optional parameter "palette" contains either a palette memberRef or a system palette as symbol (e.g. #grayscale), the result image will use this palette, otherwise a new palette member is created.
Parameters:
===========
REQUIRED:
"filename": #string
OPTIONAL:
"page": #integer
"format": #integer or #string
"flags": #integer
"map": paletteRef (#member or #symbol) -> map to this (8-bit) palette
"palette": paletteRef (#member or #symbol): use this as paletteRef (no mapping!)
"colors": (empty) #list: filled with colors of actual palette (8 bit only)
"transparency": (empty) #list filled with transparency index (later: transparency table?) (8 bit only)
Returns: #image (success) or 0 (failure)
Example:
========
cnt = xtraInst.ix_multipage_getPageCount( ["filename": "c:\anim.gif"] )
-- import palette of frame 1 as new palette member
img = xtraInst.ix_multiPageExtractPage( ["filename": "c:\anim.gif", "page": 1] )
if ilk(img)=#image then
m = new(#bitmap, castLib("frames"))
m.image = img
repeat with i = 2 to cnt
-- assume all frames use the same palette, so map all other images
-- to the same new palette member
-- this only works if the original palette in the GIF has color
-- RGB(255,255,255) at position 0
img = xtraInst.ix_multiPageExtractPage( ["filename": "c:\anim.gif", "page": i, "palette":m.paletteRef] )
if ilk(img)=#image then
new(#bitmap, castlib("frames")).image = img
end if
end repeat
end if
--**************************************
-- TWAIN
--**************************************
Notice:
The TWAIN interface is typically used for scanners and digital cameras. Using cameras or other non-scanner devices will propably only work in interactive dialog mode (parameter "dialog"=1), since the settings that can be directly specified in propertyList props are specific to scanners.
----------------------------------------
-- ix_twainSetCallback object me, props
----------------------------------------
Assigns a lingo "callback" handler that will be called by the xtra when an image was scanned/acquired by ix_twainAcquireImage. Either an image object (success) or 0 (failure) will be passed to this callback handler.
If a reference to a script object or a script is passed as optional parameter "target":, this object/script will be called, otherwise the callback is called on movie level (i.e. it's assumed to be in a movie script).
Parameters:
===========
REQUIRED:
"callback": #symbol
OPTIONAL:
"target": #object (#instance or #_movie)
Returns: 1 (success) or 0 (failure)
----------------------------------------
-- ix_twainSelectSource object me
----------------------------------------
If the TWAIN interface was succesfully initialized, a (synchronous) dialog for selecting a TWAIN source (a scanner or a digital camera) is displayed. It's required to select a source before ix_twainAcquireFile or ix_twainAcquireImage can be used.
Returns: name of source as #string (success) or EMPTY (dialog was canceled) or 0 (failure)
----------------------------------------
-- ix_twainAcquireFile object me, props
----------------------------------------
Scans an image and saves is to a file (specified by "filename", "format", "flags"). If parameter "dialog" is 0, no scan dialog is displayed, instead the settings specified in propertyList props are used (or some default values for any setting that's missing in props).
Parameters:
===========
REQUIRED:
"filename": #string
OPTIONAL:
"format": #string or #integer
"flags": #integer
"dialog": #integer
"type": 0 for RGB-Color, 1 for Grayscale, 2 for Black&White (default = 1)
"resolution": resolution in dpi as integer (default = 72)
"brightness": brightness as integer in range -1000 to 1000 (default=0)
"contrast": brightness as integer in range -1000 to 1000 (default=0)
"left": position in cm as float (default = 0.0)
"top": position in cm as float (default = 0.0)
"right": position in cm as float (default = 21.0)
"bottom": position in cm as float (default = 29.7)
Returns: 1 (success) or 0 (failure)
----------------------------------------
-- ix_twainAcquireImage object me, *props
----------------------------------------
Scans an image and passes it as image object to the lingo callback function (of the target object) that was previously specified by ix_twainSetCallback().
If "dialog"=1, a scan dialog is displayed, otherwise the settings found in props are used.
Parameters:
===========
OPTIONAL:
"dialog": #integer
"type": 0 for RGB-Color, 1 for Grayscale, 2 for Black&White (default = 1)
"resolution": resolution in dpi as integer (default = 72)
"brightness": brightness as integer in range -1000 to 1000 (default=0)
"contrast": brightness as integer in range -1000 to 1000 (default=0)
"left": position in cm as float (default = 0.0)
"top": position in cm as float (default = 0.0)
"right": position in cm as float (default = 21.0)
"bottom": position in cm as float (default = 29.7)
Returns: 1 (success) or 0 (failure)
--**************************************
-- OTHER
--**************************************
----------------------------------------
-- ix_getExplorerIcon object me, object props
----------------------------------------
Returns icon image (32-bit with alpha channel) for file/folder.
Parameters:
===========
REQUIRED:
"filename": #string
OPTIONAL:
"size": #integer
-- SHGFI_LARGEICON = 0 (=default)
-- SHGFI_SMALLICON = 1
-- SHGFI_SHELLICONSIZE = 4
Returns: #image (success) or VOID (failure)
----------------------------------------
-- ix_getExplorerThumb object me, object props
----------------------------------------
Returns thumbnail image (32-bit with alpha channel) for file/folder.
Parameters:
===========
REQUIRED:
"filename": #string
OPTIONAL:
"size": #integer (default: 256, i.e. a 256x256 image is returned)
"flags": #integer (default: 0 = SIIGBF_RESIZETOFIT)
Returns: #image (success) or VOID (failure)
"flags" can be any combination (using bitOr) of the following values:
SIIGBF_RESIZETOFIT = 0
SIIGBF_BIGGERSIZEOK = 1
SIIGBF_MEMORYONLY = 2
SIIGBF_ICONONLY = 4
SIIGBF_THUMBNAILONLY = 8
SIIGBF_INCACHEONLY = 16
SIIGBF_CROPTOSQUARE = 32
SIIGBF_WIDETHUMBNAILS = 64
SIIGBF_ICONBACKGROUND = 128
SIIGBF_SCALEUP = 256
For more details about those flags see:
https://docs.microsoft.com/en-us/windows/win32/api/shobjidl_core/nf-shobjidl_core-ishellitemimagefactory-getimage
----------------------------------------
-- ix_xCrc32String object me, object props
----------------------------------------
Parameters:
===========
REQUIRED:
"data": #string or #bytearray
OPTIONAL:
"offset": #integer
Returns: #string or #bytearray (CRC32 checksum as 4 bytes)
5. Appendix
===========
Numeric Constants:
5.1 image_color_type
====================
FIC_MINISWHITE = 0 // min value is white
FIC_MINISBLACK = 1 // min value is black
FIC_RGB = 2 // RGB color model
FIC_PALETTE = 3 // color map indexed
FIC_RGBALPHA = 4 // RGB color model with alpha channel
FIC_CMYK = 5 // CMYK color model
5.2 flags (Used for load/save-operations)
=========================================
NAME VALUE DESCRIPTION
BMP_DEFAULT 0
BMP_SAVE_RLE 1
CUT_DEFAULT 0
DDS_DEFAULT 0
EXR_DEFAULT 0 save data as half with piz-based wavelet compression
EXR_FLOAT 0x0001 save data as float instead of as half (not recommended)
EXR_NONE 0x0002 save with no compression
EXR_ZIP 0x0004 save with zlib compression, in blocks of 16 scan lines
EXR_PIZ 0x0008 save with piz-based wavelet compression
EXR_PXR24 0x0010 save with lossy 24-bit float compression
EXR_B44 0x0020 save with lossy 44% float compression - goes to 22% when combined with EXR_LC
EXR_LC 0x0040 save images with one luminance and two chroma channels, rather than as RGB (lossy compression)
FAXG3_DEFAULT 0
GIF_DEFAULT 0
GIF_LOAD256 1 Load the image as a 256 color image with ununsed palette entries, if it's 16 or 2 color
GIF_PLAYBACK 2 'Play' the GIF to generate each frame (as 32bpp) instead of returning raw frame data when loading
HDR_DEFAULT 0
ICO_DEFAULT 0
ICO_MAKEALPHA 1 convert to 32bpp and create an alpha channel from the AND-mask whenloading
IFF_DEFAULT 0
J2K_DEFAULT 0 save with a 16:1 rate
JP2_DEFAULT 0 save with a 16:1 rate
JPEG_DEFAULT 0 loading (see JPEG_FAST); saving (see JPEG_QUALITYGOOD|JPEG_SUBSAMPLING_420)
JPEG_FAST 0x0001 load the file as fast as possible, sacrificing some quality
JPEG_ACCURATE 0x0002 load the file with the best quality, sacrificing some speed
JPEG_CMYK 0x0004 load separated CMYK "as is" (use | to combine with other load flags)
JPEG_EXIFROTATE 0x0008 load and rotate according to Exif 'Orientation' tag if available
JPEG_GREYSCALE 0x0010 load and convert to a 8-bit greyscale image
JPEG_QUALITYSUPERB 0x80 save with superb quality (100:1)
JPEG_QUALITYGOOD 0x0100 save with good quality (75:1)
JPEG_QUALITYNORMAL 0x0200 save with normal quality (50:1)
JPEG_QUALITYAVERAGE 0x0400 save with average quality (25:1)
JPEG_QUALITYBAD 0x0800 save with bad quality (10:1)
JPEG_PROGRESSIVE 0x2000 save as a progressive-JPEG (use | to combine with other save flags)
JPEG_SUBSAMPLING_411 0x1000 save with high 4x1 chroma subsampling (4:1:1)
JPEG_SUBSAMPLING_420 0x4000 save with medium 2x2 medium chroma subsampling (4:2:0) - default value
JPEG_SUBSAMPLING_422 0x8000 save with low 2x1 chroma subsampling (4:2:2)
JPEG_SUBSAMPLING_444 0x10000 save with no chroma subsampling (4:4:4)
JPEG_OPTIMIZE 0x20000 on saving, compute optimal Huffman coding tables (can reduce a few percent of file size)
JPEG_BASELINE 0x40000 save basic JPEG, without metadata or any markers
JXR_DEFAULT 0 save with quality 80 and no chroma subsampling (4:4:4)
JXR_LOSSLESS 0x0064 save lossless
JXR_PROGRESSIVE 0x2000 save as a progressive-JXR (use | to combine with other save flags)
KOALA_DEFAULT 0
LBM_DEFAULT 0
MNG_DEFAULT 0
PCD_DEFAULT 0
PCD_BASE 1 load the bitmap sized 768 x 512
PCD_BASEDIV4 2 load the bitmap sized 384 x 256
PCD_BASEDIV16 3 load the bitmap sized 192 x 128
PCX_DEFAULT 0
PFM_DEFAULT 0
PICT_DEFAULT 0
PNG_DEFAULT 0
PNG_IGNOREGAMMA 1 loading: avoid gamma correction
PNG_Z_BEST_SPEED 0x0001 save using ZLib level 1 compression flag (default value is 6)
PNG_Z_DEFAULT_COMPRESSION 0x0006 save using ZLib level 6 compression flag (default recommended value)
PNG_Z_BEST_COMPRESSION 0x0009 save using ZLib level 9 compression flag (default value is 6)
PNG_Z_NO_COMPRESSION 0x0100 save without ZLib compression
PNG_INTERLACED 0x0200 save using Adam7 interlacing (use | to combine with other save flags)
PNM_DEFAULT 0
PNM_SAVE_RAW 0 Saves the bitmap as a binary file
PNM_SAVE_ASCII 1 Saves the bitmap as an ASCII file
PSD_DEFAULT 0
PSD_CMYK 1 reads tags for separated CMYK (default is conversion to RGB)
PSD_LAB 2 reads tags for CIELab (default is conversion to RGB)
PSD_NONE 0x0100 save without any compression
PSD_RLE 0x0200 save using RLE compression
PSD_PSB 0x2000 save using Adobe Large Document Format (use | to combine with other save flags)
RAS_DEFAULT 0
RAW_DEFAULT 0 load the file as linear RGB 48-bit
RAW_PREVIEW 1 try to load the embedded JPEG preview with included Exif Data or default to RGB 24-bit
RAW_DISPLAY 2 load the file as RGB 24-bit
RAW_HALFSIZE 4 output a half-size color image
RAW_UNPROCESSED 8 output a FIT_UINT16 raw Bayer image
SGI_DEFAULT 0
TARGA_DEFAULT 0
TARGA_LOAD_RGB888 1 if set the loader converts RGB555 and ARGB8888 -> RGB888.
TARGA_SAVE_RLE 2 if set, the writer saves with RLE compression
TIFF_DEFAULT 0
TIFF_CMYK 0x0001 reads/stores tags for separated CMYK (use bitOr() to combine with compression flags)
TIFF_PACKBITS 0x0100 save using PACKBITS compression
TIFF_DEFLATE 0x0200 save using DEFLATE compression (a.k.a. ZLIB compression)
TIFF_ADOBE_DEFLATE 0x0400 save using ADOBE DEFLATE compression
TIFF_NONE 0x0800 save without any compression
TIFF_CCITTFAX3 0x1000 save using CCITT Group 3 fax encoding
TIFF_CCITTFAX4 0x2000 save using CCITT Group 4 fax encoding
TIFF_LZW 0x4000 save using LZW compression
TIFF_JPEG 0x8000 save using JPEG compression
TIFF_LOGLUV 0x10000 save using LogLuv compression
WBMP_DEFAULT 0
WEBP_DEFAULT 0 save with good quality (75:1)
WEBP_LOSSLESS 0x100 save in lossless mode
XBM_DEFAULT 0
XPM_DEFAULT 0
5.3 jpeg_operation
==================
FIJPEG_OP_NONE = 0 // no transformation
FIJPEG_OP_FLIP_H = 1 // horizontal flip
FIJPEG_OP_FLIP_V = 2 // vertical flip
FIJPEG_OP_TRANSPOSE = 3 // transpose across UL-to-LR axis
FIJPEG_OP_TRANSVERSE = 4 // transpose across UR-to-LL axis
FIJPEG_OP_ROTATE_90 = 5 // 90-degree clockwise rotation
FIJPEG_OP_ROTATE_180 = 6 // 180-degree rotation
FIJPEG_OP_ROTATE_270 = 7 // 270-degree clockwise (or 90 ccw)
5.4 rescale_filter
==================
Upsampling / downsampling filters used in FreeImage_Rescale.
FILTER_BOX = 0 // Box, pulse, Fourier window, 1st order (constant) b-spline
FILTER_BICUBIC = 1 // Mitchell & Netravali's two-param cubic filter
FILTER_BILINEAR = 2 // Bilinear filter
FILTER_BSPLINE = 3 // 4th order (cubic) b-spline
FILTER_CATMULLROM = 4 // Catmull-Rom spline, Overhauser spline
FILTER_LANCZOS3 = 5 // Lanczos3 filter