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