23.3.2012 1/47

CFX_OPENIMAGE 1.4.4 INSTALLATION AND SYNTAX

Jukka Manner 2012

23.3.2012 2/47

CFX_OPENIMAGE 1.4.4 INSTALLATION AND SYNTAX........................................................ 1 INSTALLATION ........................................................................................................................... 4 SYNTAX........................................................................................................................................ 6

ACTION: READ......................................................................................................................... 7 ACTION: PING........................................................................................................................ 12 ACTION: CONVERT............................................................................................................... 14 ACTION: SCALE..................................................................................................................... 16 ACTION: RESIZE.................................................................................................................... 18 ACTION: ROTATE.................................................................................................................. 20 ACTION: IML.......................................................................................................................... 22 ACTION: ENUMFONTS ......................................................................................................... 24 ACTION: PASTE_IPTC........................................................................................................... 25

IML Commands............................................................................................................................ 27 IML Memory images .................................................................................................................... 43

23.3.2012 3/47

This version CFX_OPENIMAGE is using an engine, GraphicsMagick 1.3.14. GraphicsMagick (www.graphicsmagick.org) maintains a stable release branch, maintains a detailed Change Log, and maintains a stable source repository with complete version history so that changes are controlled, and changes between releases are accurately described. GraphicsMagick provides continued support for a release branch.

23.3.2012 4/47

INSTALLATION Note: If you are installing 64bit version of the tag, please download and install Microsoft Visual C++ 2010 Redistributable Package (x64) from Microsoft (http://www.microsoft.com/download/en/details.aspx?id=14632). The x64 version has been compiled and written in Visual Studio 2010. CFX_OPENIMAGE installation steps common to both versions: Create an environment variable Since GraphicsMagick needs read configuration files (*.mgk files), we need to tell the tag where those files are located. In order to do that, a system or cold fusion runtime user specific environment variable must be set. The name of this variable is CFX_OPENIMAGE_FULLPATH. CFX_OPENIMAGE_FULLPATH environment variable should contain full pathname which points to a directory where all mgk-files and cfx_openimage.ini file are kept. A default value for this is “c:\cfx_openimage\”. Notice that the last “\” character is needed too. You may install the actual dll where ever you like, it’s up to you to register is anyway via CF admin page. For keeping the security settings for all the files equal, it is recommended to keep cfx_openimage.dll in the same directory that the *.mgk and cfx_openimage.ini directory.

23.3.2012 5/47

The GraphicsMagick files (*.mgk) These files guide the whole GraphicsMagick image processing and these are mandatory files. You must install them to the same directory as your CFX_OPENIMAGE_FULLPATH environment variable is set for. CFX_OPENIMAGE configuration (cfx_openimage.ini file) This allows administrators to restrict write access to only some directories. Currently this ini-configuration file contains only two sections: Security and SecKeys. Security section can contain two settings, UseSecKeys and NonSecKeyPath. “UseSecKeys = 1” means that the tag is expecting users to pass a new attribute; SECKEY (comes from words Security Key). One can not use cfx_openimage for writing unless administrator has provided a security key to him/her. UseSecKeys = 0 or when commented, the SECKEY attribute is not mandatory. Example: [Security] UseSecKeys = 1 NonSecKeyPath = a full pathname This optional setting which restricts all user related write actions under certain path only Example [Security] UseSecKeys = 0 NonSecKeyPath = c:\demo\ SecKeys section contains security keys generated by the admin. The security key holds a value to the path that user is allowed to write to, e.g. [SecKeys] 5w457k1q2l0y0bvkqufc264utn5q8uqzx4dd4twv = c:\demo\ User calls cfx_openimage like this <cfx_openimage SECKEY=”5w457k1q2l0y0bvkqufc264utn5q8uqzx4dd4twv”….. etc.> Seckey attribute is not mandatory if UseSecKeys config value is other that “1”. So, a short summary what to do…

1. Install the tag and all the other files to some directory 2. set a system enviroment variable CFX_OPENIMAGE_FULLPATH with value of full

pathname to the installation folder 3. register the dll to Cold Fusion via CF admin page 4. Try out the samples

If something fails, try restarting Cold Fusion, so it can read the newly created environment variable.

23.3.2012 6/47

SYNTAX CFX_OpenImage tag syntax is based on ACTION attributes and action based subattributes: <CFX_OpenImage ACTION=”{READ | PING | CONVERT | SCALE | RESIZE | ROTATE |

IML | ENUMFONTS | PASTE_IPTC}” [<Subattributes…>] [HELP] [COPYRIGHT] [DEBUG]

[SECKEY=”security key value”] >

HELP Shows simple syntax for all the actions COPYRIGHT Show copyright text for the tag.

23.3.2012 7/47

ACTION: READ You can use the READ action to read existing image file information. The READ action doesn't only read the image file header, but decompresses the file, and then returns the information. The actual file is not saved in any dynamic CFML variable. Syntax: <CFX_OPENIMAGE ACTION="READ" FILE="full_pathname+filename" [NAME="output query name"] [AUTODETECT="YES/NO(default)"] [ANIMATION_SUPPORT="FULL/READ/NO(default)"] [READ_CMYK="YES/NO(default)"] [DEBUG] [SECKEY="security key value"] > Attributes: FILE: Required. The full pathname of the image file to be read. Hint: Use expandpath-CFML function to get the path. Wildcards are accepted e.g #expandpath('images/*.jpg')# NAME: Optional. A query name in which the resultset will be exposed. Use CFOUTPUT QUERY or CFLOOP QUERY in order to get the column values. AUTODETECT: Optional. Use this attribute with value "NO" if you don't want the CFX_OPENIMAGE to determine the image format. By default CFX_OPENIMAGE determines the image format by its file extension. This attribute overrides the default behaviour and uses ImageMagick's detection. ANIMATION_SUPPORT: Optional. Forces to count the number of animation frames from the image. Attribute value "FULL" or "READ" are functionally the same in READ action. READ_CMYK: By default CFX_OPENIMAGE converts images from CMYK into RGB. If this attribute is set to "YES", CFX_OPENIMAGE retains the image in CMYK mode. DEBUG: Optional. Debugging only. Shows CFX_OPENIMAGE version number and dumps out the image information to the web page or any internal error messages. SECKEY

23.3.2012 8/47

SecKeys section contains security keys generated by the admin. This is not a mandatory attribute by default. Outputs: Note: If the READ action fails to open the file (e.g file does not exist) the execution won't display any errors unless there is something seriously wrong with your image file. To determine whether the READ action succeeded or not, examine the IMG_READ status. When it succeeds IMG_READ is "TRUE", when not, it is "FALSE". More detailed information (e.g file not found) can be then found in the IMG_ERROR variable. You may also have IMG_WARNING variable, which holds some warnings that may occur. You may check successfull read by: <cfif img_read is "TRUE"> ok <cfelse> not ok </cfif> or just <cfif isdefined("img_error") is "False"> ok <cfelse> not ok </cfif> Note that IMG_ERROR exists only when IMG_READ is FALSE. In some cases the CFX_OPENIMAGE will throw an exception, but usually it tries to maintain good will and be invisible to the users. CFML variables: IMG_READ: status information. "TRUE" if successfull, "FALSE" if there was an error. IMG_ERROR: Error information. Only exists when IMG_READ is FALSE. IMG_WARNING: Warning information. Only exists when a warning has been detected. IMG_FILE: Full pathname of the file read. IMG_WIDTH: Image width in pixels. If IMG_READ is "FALSE" this field is empty although this variable exists.

23.3.2012 9/47

IMG_HEIGHT: Image height in pixels. If IMG_READ is "FALSE" this field is empty although this variable exists. IMG_SIZE: Image size in bytes. IMG_ATIME: Last access time. Contains the last access time of this file (provided by the operating system) Time is represented in ODBC Datetime string format: {ts 'YYYY-MM-DD HH:MM:SS'} IMG_CTIME: File creation time. Contains the file creation time of this file (provided by the operating system) Time is represented in ODBC Datetime string format: {ts 'YYYY-MM-DD HH:MM:SS'} IMG_MTIME: Last modified time. Contains the last modified time of this file (provided by the operating system) Time is represented in ODBC Datetime string format: {ts 'YYYY-MM-DD HH:MM:SS'} IMG_COMMENT: Image comment string. Certain images can contain special string information, usually copyright notices or other information. This variable contains such information if one exists. IMG_TYPE: Image type (a.k.a extension): gif,jpeg,png,bmp,etc... Useful when using CFCONTENT TYPE="image/#IMG_TYPE#" IMG_TYPE_DESCRIPTION: Image type description in plain text. IMG_COLORS: A number of colors in image. IMG_CLASSTYPE: Image color class information. PseudoClass = palette colors, DirectClass = non-palette colors IMG_TRANSPARENT: Tranparent color present (matte). Value is either TRUE or FALSE. IMG_ANIMATED: Animation information. "TRUE" if the image is animated, "FALSE" if not. IMG_FRAMES: The number of animation frames. Only relevant when image is animated and ANIMATION_SUPPORT is set to either "FULL" or "READ". IMG_DPI: Dots per inch value.

23.3.2012 10/47

IMG_INTERLACE: Interlace information. "TRUE" if the image is interlaced, "FALSE" if not. IMG_IPTC_LENGTH: Number of IPTC information bytes present. IPTC fields: The International Press Telecommunications Council information fields. IPTC_OBJECT_NAME: IPTC_EDIT_STATUS: IPTC_EDITORIAL_UPDATE: IPTC_URGENCY: IPTC_CATEGORY: IPTC_SUPPLEMENTAL_CATEGORY_LIST IPTC_FIXTURE_IDENTIFIER IPTC_KEYWORD_LIST IPTC_RELEASE_DATE IPTC_RELEASE_TIME IPTC_EXPIRATION_DATE IPTC_EXPIRATION_TIME IPTC_SPECIAL_INSTRUCTIONS IPTC_ACTION_ADVICED IPTC_REFERENCE_SERVICE IPTC_REFERENCE_DATE IPTC_REFERENCE_NUMBER IPTC_DATE_CREATED IPTC_TIME_CREATED IPTC_DIGITAL_CREATION_DATE IPTC_DIGITAL_CREATION_TIME IPTC_ORIGINATING_PROGRAM IPTC_PROGRAM_VERSION IPTC_OBJECT_CYCLE IPTC_BYLINE IPTC_BYLINE_TITLE IPTC_CITY IPTC_SUBLOCATION IPTC_PROVINCE_STATE IPTC_COUNTRY_CODE IPTC_COUNTRY_NAME IPTC_ORIGINAL_TRANSMISSION_REFERENCE IPTC_HEADLINE IPTC_CREDIT IPTC_SOURCE IPTC_COPYRIGHT_NOTICE IPTC_CONTACT IPTC_CAPTION IPTC_WRITER IPTC_IMAGE_TYPE IPTC_IMAGE_ORIENTATION

23.3.2012 11/47

IPTC_LANGUAGE_IDENTIFIER found EXIF keys will generate CFML variables with this syntax: IMG_EXIF_<VARIABLENAME> … IMG_EXIF_KEYS: A comma separated list of EXIF information keys (a.k.a names) IMG_EXIF_VALUES: A comma separated list of EXIF information values. Same sequence as IMG_EXIF_KEYS

23.3.2012 12/47

ACTION: PING You can use the PING action to read existing image file information. The PING action only reads the image file header and then returns the information. It is then faster than READ. Syntax: <CFX_OPENIMAGE ACTION="PING" FILE="full_path_name+filename" [NAME="output query name"] [AUTODETECT="YES/NO(default)"] [DEBUG] [SECKEY="security key value"] > Attributes: FILE: Required. The full path name of the image file to be read. Hint: Use expandpath-CFML function to get the path. Wildcards are accepted e.g #expandpath('images/*.jpg')# NAME: Optional. A query name in which the resultset will be exposed. Use CFOUTPUT QUERY or CFLOOP QUERY in order to get the column values. AUTODETECT: Optional. Use this attribute with value "NO" if you don't want the CFX_OPENIMAGE to determine the image format. By default CFX_OPENIMAGE determines the image format by its file extension. This attribute overrides the default behaviour and uses ImageMagick's detection. DEBUG: Optional. Debugging only. Shows CFX_OPENIMAGE version number and dumps out the image information to the web page or any internal error messages. SECKEY SecKeys section contains security keys generated by the admin. This is not a mandatory attribute by default. Outputs: Note: If the PING action fails to open the file (e.g file does not exist) the execution won't display any errors unless there is something seriously wrong with your image file.

23.3.2012 13/47

To determine whether the PING action succeeded or not, examine the IMG_READ status. When it succeeds IMG_READ is "TRUE", when not, it is "FALSE". More detailed information (e.g file not found) can be then found in the IMG_ERROR variable. You may also have IMG_WARNING variable, which holds some warnings that may occur. You may check successfull read by: <cfif img_read is "TRUE"> ok <cfelse> not ok </cfif> or just <cfif isdefined("img_error") is "False"> ok <cfelse> not ok </cfif> Note that IMG_ERROR exists only when IMG_READ is FALSE. In some cases the CFX_OPENIMAGE will throw an exception, but usually it tries to maintain good will and be invisible to the users. Outputs the same CFML variables as READ-action does.

23.3.2012 14/47

ACTION: CONVERT CONVERT action is for converting files to different formats. You might use IML action and iml command “write” as well, but this action is meant to executed just the convertion, nothing else. Syntax: <CFX_OPENIMAGE ACTION="CONVERT" FILE={ "full_path_name+filename” | “NEW]" [X="image width" (when FILE="NEW")] [Y="image height" (when FILE="NEW")] [BGCOLOR="image backgroundcolor" (when FILE="NEW")] OUTPUT="full_path_name+filename" [NAME="output query name"] [AUTODETECT="YES/NO(default)"] [READ_CMYK="YES/NO(default)"] [WRITE_CMYK="YES/NO(default)"] [QUALITY="a number between 0 - 100"] [NOPROFILE] [DEBUG] > [SECKEY="security key value"] > Attributes: FILE=”full pathname+filename” Required. The full pathname of the image file to be read. Hint: Use expandpath-CFML function to get the path. Wildcards are not accepted with CONVERT action. FILE="NEW": Created IML memory image from scratch. Mandatory parameters follows: X: NEW image's width Y: NEW image's height Optional BGCOLOR: NEW image's backgroundcolor OUTPUT Required. The full pathname of the image file to be created. The new format will be determined by the image extension. NAME: Optional. A query name in which the resultset will be exposed. Use CFOUTPUT QUERY or CFLOOP QUERY in order to get the column values. AUTODETECT: Optional. Use this attribute with value "NO" if you don't want the CFX_OPENIMAGE to determine the image format. By default CFX_OPENIMAGE determines the image format by its file extension. This attribute overrides the default behaviour and uses ImageMagick's detection. READ_CMYK:

23.3.2012 15/47

By default CFX_OPENIMAGE converts images from CMYK into RGB. If this attribute is set to "YES", CFX_OPENIMAGE retains the image in CMYK mode. WRITE_CMYK: By default CFX_OPENIMAGE converts images from CMYK into RGB. If this attribute is set to "YES", CFX_OPENIMAGE retains the image in CMYK mode. You should use READ_CMYK with WRITE_CMYK. QUALITY: Optional. Quality setting for written image. (GraphicMagick’s image quality attribute). NOPROFILE: Strip IPTC and EXIF profiles from the original and result images. DEBUG: Optional. Debugging only. Shows CFX_OPENIMAGE version number and dumps out the image information to the web page or any internal error messages. Outputs the same CFML variables as READ-action does.

23.3.2012 16/47

ACTION: SCALE If you are familiar with ImageMagick or GraphicMagicks image geometry, you could use SCALE action for resizing. It resizes image by using simple ratio algorithm which provides good quality. You might use IML action and iml resizing commands for more control. Syntax: <CFX_OPENIMAGE ACTION="SCALE" FILE= "full_path_name+filename” OUTPUT="full_path_name+filename" GEOMETRY="GraphicMagicks geometry format" [NAME="output query name"] [ANIMATION_SUPPORT="FULL/ NO(default)"] [AUTODETECT="YES/NO(default)"] [READ_CMYK="YES/NO(default)"] [WRITE_CMYK="YES/NO(default)"] [QUALITY="a number between 0 - 100"] [NOPROFILE] [DEBUG] > [SECKEY="security key value"] > Attributes: FILE=”full pathname+filename” Required. The full pathname of the image file to be read. Hint: Use expandpath-CFML function to get the path. OUTPUT Required. The full pathname of the image file to be created. The new format will be determined by the image extension. GEOMETRY: "<width>x<height>{+-}<xoffset>{+-}<yoffset>{%}{!}{<}{>}" see: http://www.graphicsmagick.org/Magick++/Geometry.html NAME: Optional. A query name in which the resultset will be exposed. Use CFOUTPUT QUERY or CFLOOP QUERY in order to get the column values. ANIMATION_SUPPORT: Optional. Attribute value "FULL" scales all the animation frames by given geometry. AUTODETECT: Optional. Use this attribute with value "NO" if you don't want the CFX_OPENIMAGE to determine the image format. By default CFX_OPENIMAGE determines the image format by its file extension. This attribute overrides the default behaviour and uses ImageMagick's detection.

23.3.2012 17/47

READ_CMYK: By default CFX_OPENIMAGE converts images from CMYK into RGB. If this attribute is set to "YES", CFX_OPENIMAGE retains the image in CMYK mode. WRITE_CMYK: By default CFX_OPENIMAGE converts images from CMYK into RGB. If this attribute is set to "YES", CFX_OPENIMAGE retains the image in CMYK mode. You should use READ_CMYK with WRITE_CMYK. QUALITY: Optional. Quality setting for written image. (GraphicMagick’s image quality attribute). NOPROFILE: Strip IPTC and EXIF profiles from the original and result images. DEBUG: Optional. Debugging only. Shows CFX_OPENIMAGE version number and dumps out the image information to the web page or any internal error messages. Outputs the same CFML variables as READ-action does.

23.3.2012 18/47

ACTION: RESIZE The resize action is added to support CFX_IMAGE users, internally it generates IML commands and executes them. You might use IML action and iml resizing commands for more control. Syntax: <CFX_OPENIMAGE ACTION="RESIZE" FILE= "full_path_name+filename” OUTPUT="full_path_name+filename" X=”width” Y=”height” [THUMBNAIL=”YES”] [COMMENT=”height”] [NAME="output query name"] [ANIMATION_SUPPORT="FULL/ NO(default)"] [AUTODETECT="YES/NO(default)"] [READ_CMYK="YES/NO(default)"] [WRITE_CMYK="YES/NO(default)"] [QUALITY="a number between 0 - 100"] [NOPROFILE] [DEBUG] > [SECKEY="security key value"] > Attributes: FILE=”full pathname+filename” Required. The full pathname of the image file to be read. Hint: Use expandpath-CFML function to get the path. OUTPUT Required. The full pathname of the image file to be created. The new format will be determined by the image extension. X Required. Resize image to to this width. If this value is empty, value “-1” is used. Y Required. Resize image to to this width. If this value is empty, value “-1” is used. THUMBNAIL Optional. If set to YES, resizes will make a thumbnail image (with grey frames). COMMENT Optional. Additional comment that will be embedded inside the image file. This depends on the what the output format supports. NAME: Optional. A query name in which the resultset will be exposed.

23.3.2012 19/47

Use CFOUTPUT QUERY or CFLOOP QUERY in order to get the column values. ANIMATION_SUPPORT: Optional. Attribute value "FULL" scales all the animation frames by given geometry. AUTODETECT: Optional. Use this attribute with value "NO" if you don't want the CFX_OPENIMAGE to determine the image format. By default CFX_OPENIMAGE determines the image format by its file extension. This attribute overrides the default behaviour and uses ImageMagick's detection. READ_CMYK: By default CFX_OPENIMAGE converts images from CMYK into RGB. If this attribute is set to "YES", CFX_OPENIMAGE retains the image in CMYK mode. WRITE_CMYK: By default CFX_OPENIMAGE converts images from CMYK into RGB. If this attribute is set to "YES", CFX_OPENIMAGE retains the image in CMYK mode. You should use READ_CMYK with WRITE_CMYK. QUALITY: Optional. Quality setting for written image. (GraphicMagick’s image quality attribute). NOPROFILE: Strip IPTC and EXIF profiles from the original and result images. DEBUG: Optional. Debugging only. Shows CFX_OPENIMAGE version number and dumps out the image information to the web page or any internal error messages. Outputs the same CFML variables as READ-action does.

23.3.2012 20/47

ACTION: ROTATE The rotate action is added to support CFX_IMAGE users; internally it generates IML commands and executes them. You might use IML action and iml rotate command for more control. Syntax: <CFX_OPENIMAGE ACTION="ROTATE" FILE= "full_path_name+filename” OUTPUT="full_path_name+filename" ANGLE=”rotation angle” [NAME="output query name"] [ANIMATION_SUPPORT="FULL/ NO(default)"] [AUTODETECT="YES/NO(default)"] [READ_CMYK="YES/NO(default)"] [WRITE_CMYK="YES/NO(default)"] [QUALITY="a number between 0 - 100"] [NOPROFILE] [DEBUG] > [SECKEY="security key value"] > Attributes: FILE=”full pathname+filename” Required. The full pathname of the image file to be read. Hint: Use expandpath-CFML function to get the path. OUTPUT Required. The full pathname of the image file to be created. The new format will be determined by the image extension. ANGLE Required. Rotate image counter-clockwise by specified number of degrees. degrees 0 - 360 are allowed NAME: Optional. A query name in which the resultset will be exposed. Use CFOUTPUT QUERY or CFLOOP QUERY in order to get the column values. ANIMATION_SUPPORT: Optional. Attribute value "FULL" rotates all the animation frames by given angle. AUTODETECT: Optional. Use this attribute with value "NO" if you don't want the CFX_OPENIMAGE to determine the image format. By default CFX_OPENIMAGE determines the image format by its file extension. This attribute overrides the default behaviour and uses ImageMagick's detection. READ_CMYK:

23.3.2012 21/47

By default CFX_OPENIMAGE converts images from CMYK into RGB. If this attribute is set to "YES", CFX_OPENIMAGE retains the image in CMYK mode. WRITE_CMYK: By default CFX_OPENIMAGE converts images from CMYK into RGB. If this attribute is set to "YES", CFX_OPENIMAGE retains the image in CMYK mode. You should use READ_CMYK with WRITE_CMYK. QUALITY: Optional. Quality setting for written image. (GraphicMagick’s image quality attribute). NOPROFILE: Strip IPTC and EXIF profiles from the original and result images. DEBUG: Optional. Debugging only. Shows CFX_OPENIMAGE version number and dumps out the image information to the web page or any internal error messages. Outputs the same CFML variables as READ-action does.

23.3.2012 22/47

ACTION: IML IML action is the key action when manipulating images. The most important action! COMMANDS attribute holds the set of image manipulation commands, see Open_IML_commands.xls for their usage. Syntax: <CFX_OPENIMAGE ACTION="IML" FILE="[full_path_name+filename or NEW]" [X="image width" (FILE="NEW")] [Y="image height" (FILE="NEW")] [BGCOLOR="image backgroundcolor" (FILE="NEW")] COMMANDS="a set of IML commands" [NAME="output query name"] [ANIMATION_SUPPORT="FULL/ NO(default)"] [AUTODETECT="YES/NO(default)"] [READ_CMYK="YES/NO(default)"] [WRITE_CMYK="YES/NO(default)"] [QUALITY="a number between 0 - 100"] [NOPROFILE] [DEBUG] > [SECKEY="security key value"] > Attributes: FILE: Required. The full path name of the image file to be read. Hint: Use expandpath-CFML function to get the path. Wildcards are accepted e.g #expandpath('images/*.jpg')# FILE="NEW": Created IML memory image from scratch. Mandatory parameters follows: X: NEW image's width Y: NEW image's height Optional BGCOLOR: NEW image's backgroundcolor COMMANDS=”a set of IML commands” see Open_IML_commands.xls NAME: Optional. A query name in which the resultset will be exposed. Use CFOUTPUT QUERY or CFLOOP QUERY in order to get the column values. AUTODETECT: Optional. Use this attribute with value "NO" if you don't want the CFX_OPENIMAGE to determine the image format. By default CFX_OPENIMAGE determines the image format by its file extension. This attribute overrides the default behaviour and

23.3.2012 23/47

uses ImageMagick's detection. ANIMATION_SUPPORT: Optional. Forces to count the number of animation frames from the image. Attribute value "FULL" or "READ" are functionally the same in READ action. READ_CMYK: By default CFX_OPENIMAGE converts images from CMYK into RGB. If this attribute is set to "YES", CFX_OPENIMAGE retains the image in CMYK mode. WRITE_CMYK: By default CFX_OPENIMAGE converts images from CMYK into RGB. If this attribute is set to "YES", CFX_OPENIMAGE retains the image in CMYK mode. You should use READ_CMYK with WRITE_CMYK. NOPROFILE: Strip IPTC and EXIF profiles from the original and result images. DEBUG: Optional. Debugging only. Shows CFX_OPENIMAGE version number and dumps out the image information to the web page or any internal error messages. Outputs: IML exposes the same image information as READ action does - but only when using write, writeframes or writeanimate IML commands.

23.3.2012 24/47

ACTION: ENUMFONTS This action enumerates Windows fonts installed in the server. It is merely used as a helping hand where choosing fonts for IML action 'setfont' command. Syntax: <CFX_OPENIMAGE ACTION="ENUMFONTS" NAME="Cold Fusion Query name to be generated" [DEBUG] > Attributes: NAME: Required. Cold FUsion Query name to be generated. DEBUG: Optional. Debugging only. Shows CFX_OPENIMAGE version number and dumps out the image information to the web page or any internal error messages. Outputs: A Cold Fusion Query named by the NAME attribute. Column names: FACENAME, FONTTYPE, CHARSET columns: FACENAME: Font face name e.g 'Arial' FONTTYPE: Font types are 'RASTER','TRUETYPE','VECTOR' CHARSET: Character set of the font (numeric value).

23.3.2012 25/47

ACTION: PASTE_IPTC PASTE_IPTC command is meant only for jpeg images and is limited to support IPTC profile information only excluding currently so common EXIF profile information. Also it does not support all the new IPTC tags, but only these listed. IPTC_CAPTION IPTC_WRITER IPTC_HEADLINE IPTC_SPECIAL_INSTRUCTIONS IPTC_BYLINE IPTC_BYLINE_TITLE IPTC_CREDIT IPTC_SOURCE IPTC_OBJECT_NAME IPTC_DATE_CREATED IPTC_CITY IPTC_PROVINCE_STATE IPTC_COUNTRY_NAME IPTC_ORIGINAL_TRANSMISSION_REFERENCE IPTC_CATEGORY IPTC_SUPPLEMENTAL_CATEGORY_LIST IPTC_URGENCY IPTC_KEYWORD_LIST IPTC_COPYRIGHT_NOTICE The benefit for using this action is that it is one of the very few tools that have an ability to edit an image's IPTC header without having to write the file (effectively compressing again). Syntax: <CFX_OPENIMAGE ACTION="PASTE_IPTC" FILE= "full_path_name+filename” OUTPUT="full_path_name+filename" <IPTC VARIABLE>=”variable value” [DEBUG] > > Attributes: FILE=”full pathname+filename” Required. The full pathname of the image file to be read. Hint: Use expandpath-CFML function to get the path. OUTPUT Required. The full pathname of the image file to be created. The new format will be determined by the image extension. IPTC_VARIABLE

23.3.2012 26/47

Syntax is IPTC_xxxxx = “value” Attributes supported: IPTC_CAPTION=”value” IPTC_WRITER=”value” IPTC_HEADLINE=”value” IPTC_SPECIAL_INSTRUCTIONS=”value” IPTC_BYLINE=”value” IPTC_BYLINE_TITLE=”value” IPTC_CREDIT=”value” IPTC_SOURCE=”value” IPTC_OBJECT_NAME=”value” IPTC_DATE_CREATED=”value” IPTC_CITY=”value” IPTC_PROVINCE_STATE=”value” IPTC_COUNTRY_NAME=”value” IPTC_ORIGINAL_TRANSMISSION_REFERENCE=”value” IPTC_CATEGORY=”value” IPTC_SUPPLEMENTAL_CATEGORY_LIST=”value” IPTC_URGENCY=”value” IPTC_KEYWORD_LIST=”value” IPTC_COPYRIGHT_NOTICE=”value” DEBUG: Optional. Debugging only. Shows CFX_OPENIMAGE version number and dumps out the image information to the web page or any internal error messages.

23.3.2012 27/47

IML Commands Syntax notation: [a|b|c] mandatory: choose either a,b or c {,a} optional: a is an optional parameter {,[a|b|c]} optional: if parameter is passed, you must choose from a,b, or c xxxcolor means that you must give a color color syntax: rrggbb red, green and blue colors in hex format (e.g. FF0000) r,g,b red, green and blue colors in integer syntax (0 - 255), e.g 255,0,0 [r,g,b] red, green and blue in quantum syntax (0 - 65535), e.g [65535,0,0] examples: resize { [x | -1,y | x,y {,thumbnail {,color} | , stretch | bounds | fit | canvas }] } resize command parameters are all optional options are: resize x use only x value resize -1,y use only y value resize x,y use both x and y resize x,y,thumbnail make a thumbnail resize x,y,thumbnail,color make a thumbnail with special color resize x,y,stretch stretch the image resize x,y,bounds resize inside given size resize x,y,canvas resize the canvas and center the image inside the canvas

23.3.2012 28/47

IML command Description Syntax ## comment line, free text format ## comment text adaptivethreshold Apply adaptive thresholding to the image.

Adaptive thresholding is useful if the ideal threshold level is not known in advance, or if the illumination gradient is not constant across the image. Adaptive thresholding works by evaulating the mean (average) of a pixel region (size specified by width and height) and using the mean as the thresholding value. In order to remove residual noise from the background, the threshold may be adjusted by subtracting a constant offset (default zero) from the mean to compute the threshold.

adaptivethreshold width,height,offset width = positive integer height = positive integer offset = positive double

addanimate add an image to the animation sequence. The sequence must be started with startanimate.

addanimate x,y,delay,disposal,imagename{,framenumber} x = integer y = integer delay = integer ( 0 - n), milliseconds disposal = integer values 0 - 3 imagename = iml memory image name or file image (use full path) framenumber = integer, sequence number of the frame. This way you can add extra frames to certain slot in the animation

addnoise Add some noise to the image. This command does not work with animated images

addnoise [0|1|2|3|4|5]

antialias Antialias (blur) an image antialias arc draws an arc with given color arc start_x,start_y,end_x,end_y,start_degrees,end_degrees,strokecolor bline draws a line by using Bresenham method as

presented in Foley & Van Dam. bline x,y,x2,y2,strokecolor

bfpoly filled polygon bfpoly strokecolor,fillcolor,x,y,x1,y1,x2,y2,...xn,yn bfrect bordered filled rectangle bfrect x,y,x2,y2,strokecolor{,fillcolor}

23.3.2012 29/47 bfrrect bordered filled round rectangle bfrrect x,y,x2,y2,strokecolor{,fillcolor} bfsquare bordered filled square bfsquare y,y,side,strokecolor{,fillcolor} blackandwhite convert to black and white image blackandwhite blur blur the image blur {factor{,sigma}} border Add a border to image. The color of the

border is specified by the borderColor attribute

border x,y{,bordercolor}

channel Extract channel from image. Use this option to extract a particular channel from the image. Matte for example, is useful for extracting the opacity values from an image.

channel [red|blue|green|matte]

charcoal Charcoal effect image (looks like charcoal sketch). The radius parameter specifies the radius of the Gaussian, in pixels, not counting the center pixel. The sigma parameter specifies the standard deviation of the Laplacian, in pixels.

charcoal {radius{,sigma}}

chop chopping removes the interior of the area. e.g chop 134,0,160,0 -note: this example means that height is maintained (y and y2 are set to zero)

chop x,y,x2,y2

circle draw a circle circle x,y,r,strokecolor colorize Colorize image with pen color, using

specified percent opacity for red, green, and blue quantums

colorize opacity_red,opacity_green,opacity_blue,pencolor

colorpixel color one or more pixels with given color and paintmethod. Paintmethods are Point (default),Replace,FloodFill,FilltoBorder,Reset

colorpixel x,y,fillcolor{,paintmethod}

copy copy an image on top of another copy x,y,file/memory image

23.3.2012 30/47 copymerge copy an image on top of another by blending

the colors copymerge x,y,percentage,file/memory image

crop crop an image crop x,y,x1,y2 cyclecolormap Cycle image colormap cyclecolormap amount dline draw a dashed line to the image. Dasharray

parameter is a comma separated list of integers (max: 10 values, default: 5,3,2,0)

dline x,y,x2,y2,color{,dasharray}

edge Edge image (hilight edges in image). The radius is the radius of the pixel neighborhood.. Specify a radius of zero for automatic radius selection.

edge {radius}

emboss Emboss image (hilight edges with 3D effect). The radius parameter specifies the radius of the Gaussian, in pixels, not counting the center pixel. The sigma parameter specifies the standard deviation of the Laplacian, in pixels.

emboss {radius{,sigma}}

enhance Enhance image (minimize noise) enhance equalize Equalize image (histogram equalization) equalize

erase Set all image pixels to the current background color.

erase

eraseframe erase one frame from the animation sequence. Frame numbers start from 1

eraseframe framenumber

farc draws an filled arc with given color arc start_x,start_y,end_x,end_y,start_degrees,end_degrees,color{,fillcolor}

fcircle filled circle fcircle x,y,r,color

23.3.2012 31/47 fill Flood-fill color across pixels that match the

color of the target pixel and are neighbors of the target pixel. Uses current fuzz setting when determining color match.

fill x,y{,fillcolor}

fillopacity Floodfill pixels matching color (within fuzz factor) of target pixel(x,y) with replacement opacity value using method.

fillopacity x,y,opacity{,paintmethod}

filltexture Flood-fill texture across pixels starting at target-pixel and stopping at pixels matching specified border color. Uses current fuzz setting when determining color match.

filltexture x,y,[memoryimage|file image]{,bordercolor}

filltoborder Flood-fill color across pixels that match the color of the target pixel and are neighbors of the target pixel. Uses current fuzz setting when determining color match.

filltoborder x,y{,fillcolor,bordercolor}

fliphorizontal flip horizontally fliphorizontal flipvertical flip vertically flipvertical fpoly filled polygon fpoly stroke_and_fillcolor,x,y,x1,y1,x2,y2,...xn,yn frame Add decorative frame around image frame width,height{,innerBevel{,outerBevel{,framecolor}}}

frect filled rectangle frect x,y,x2,y2,strokecolor{,fillcolor} fsquare filled square fsquare x,y,side,strokecolor{,fillcolor} gamma Gamma correct red, green, and blue

channels of image. gamma [gamma|red,green,blue]

23.3.2012 32/47 gaussianblur Gaussian blur image. The number of

neighbor pixels to be included in the convolution mask is specified by 'width'. For example, a width of one gives a (standard) 3x3 convolution mask. The standard deviation of the gaussian bell curve is specified by 'sigma'.

gaussianblur width,sigma

getpixel get information from a pixel into variables getpixel x,y

getsize get image size into variable getsize grayscale grey/grayscale an image grayscale implode Implode image (special effect) implode factor interlace set interlacing to given interlacetype:

undefined,no,line,plane (default),partition interlace {interlacetype}

invert invert image colors invert killbordercolor set bordercolor to default value

(233,233,233) killbordercolor

killbrush stop using brush killbrush killdash disable the drawable dash usage killdrawabledash killfillcolor disable fillcolor killfillcolor killfontantialias stop using font antialiasing killfontantialias killfontitalic stop using font italics killfontitalic killfontspacing stop using modified text spacing killspacing killfontstrikeout stop using font strikeout killfontstrikeout killfontunderline stop using font underline killfontunderline killimage delete image from memory killimage memoryimage killinterlace set interlacing off killinterlace killlockfont allow tag to determine the text size suitable

(default) killlockfont

killstrokeantialias stop using antialias when drawing line, rectangle, polygons, arcs, etc.

killstrokeantialias

killtextshadow stop using text shadows killtextshadow killtile stop using tile killtile

23.3.2012 33/47 killtransparent remove transparency from the image killtransparent

line draw a line line x,y,x2,y2,strokecolor lockfont force the text size to given size lockfont magnify Magnify image by integral size magnify map Remap image colors with closest color from

reference image. Set dither to true in to apply Floyd/Steinberg error diffusion to the image. By default, color reduction chooses an optimal set of colors that best represent the original image. Alternatively, you can choose a particular set of colors from an image file with this option. If image parameter NETSCAPE is given the image will be remapped to netscape safety palette.

map [memoryimage|file image|NETSCAPE]{,dither}

medianfilter Filter image by replacing each pixel component with the median color in a circular neighborhood

medianfilter radius

minify Minify image by integral size minify modulate Modulate percent brightness, saturation and

360 part hue of an image. Differs a bit from replacebrightness, replacesaturation and replacehue (those are my functions). hue is bit odd: in order to rotate the hue by, say 20 degrees, use 100+(360*0.2). If your rotation is over 100 (e.g 130), use (360*1.3).

modulate brightness,saturation,hue

negate invert image colors negate

23.3.2012 34/47 noprofile removes profiles (EXIF, ICC, IPTC etc) from

the image noprofile

normalize Normalize image (increase contrast by normalizing the pixel values to span the full range of color values).

normalize

oilpaint Oilpaint image (image looks like oil painting) oilpaint {radius}

poly draw a polygon. Note: does not auto-close the polygon.

poly strokecolor,x,y,x1,y1,x2,y2,...xn,yn

raise Raise image (lighten or darken the edges of an image to give a 3-D raised or lowered effect)

raise width,height{,raisedflag}

rect draw a rectangle rect x,y,x2,y2,strokecolor reducecolors reduce colors from the image reducecolors quant_to{,dither} reducenoise Reduce noise in image using a noise peak

elimination filter. reducenoise {order}

replacebrightness replace the image brightness by (-100 - 0 - +100)

replacebrightness value

replacecolor replace a color with another color replacecolor thiscolor,withcolor,tolerance,use_luminosity replacecontrast replace the image contrast (value 0 =

decrease, 1 = increase) replaceconstrast value

replacehue rotate the color hue by (-360 - 0 -+360) replacehue degrees

replacelightness replace lightness by (-100 - 0 - +100) replacelightness value

replaceopacity replace the opacity value of each pixel in the image. 0 = opaque…. maximum quantum value (transparent)

replaceopacity value

replacesaturation replace saturation by (-100 - 0 - +100) replacesaturation value

resize resize an image resize { [x | -1,y | x,y {,thumbnail {,color} | , stretch | bounds | fit | canvas }] }

resizeif resize an image if it is greater than desired bounds

resizeif if_x,if_y

23.3.2012 35/47 roll Roll image (rolls image vertically and

horizontally) by specified number of columns (x) and rows (y))

roll x,y

rotate Rotate image counter-clockwise by specified number of degrees. degrees 0 - 360 are allowed

rotate degree

rrect round rectangle rrect x,y,x2,y2,strokecolor {,width,height } sample resize an image using sampling segment {clusterThreshold, smoothingThresHold} segment Segment (coalesce similar image

components) by analyzing the histograms of the color components and identifying units that are homogeneous with the fuzzy c-means technique. Also uses quantizeColorSpace and verbose image attributes. Specify clusterThreshold, as the number of pixels each cluster must exceed the cluster threshold to be considered valid. SmoothingThreshold_ eliminates noise in the second derivative of the histogram. As the value is increased, you can expect a smoother second derivative. The default is 1.5.

sample { [x | -1,y | x,y {,thumbnail {,color} | , stretch | bounds | canvas }] }

set_iptc_action_adviced image extra information set_iptc_action_adviced text set_iptc_byline image extra information set_iptc_byline text set_iptc_byline_title image extra information set_iptc_byline_title text set_iptc_caption image extra information set_iptc_caption text set_iptc_category image extra information set_iptc_category text set_iptc_city image extra information set_iptc_city text set_iptc_contact image extra information set_iptc_contact text set_iptc_copyright_notice image extra information set_iptc_copyright_notice text set_iptc_country_code image extra information set_iptc_country_code text set_iptc_country_name image extra information set_iptc_country_name text

23.3.2012 36/47 set_iptc_credit image extra information set_iptc_credit text set_iptc_date_created image extra information set_iptc_date_created datetime set_iptc_digital_creation_date image extra information set_iptc_digital_creation_date datetime set_iptc_digital_creation_time image extra information set_iptc_digital_creation_time iptc_timeformat set_iptc_edit_status image extra information set_iptc_edit_status text set_iptc_editorial_update image extra information set_iptc_editorial_update text set_iptc_expiration_date image extra information set_iptc_expiration_date datetime set_iptc_expiration_time image extra information set_iptc_expiration_time iptc_timeformat set_iptc_fixture_identifier image extra information set_iptc_fixture_identifier text set_iptc_headline image extra information set_iptc_headline text set_iptc_image_orientation image extra information set_iptc_image_orientation text set_iptc_image_type image extra information set_iptc_image_type text set_iptc_keyword_list image extra information set_iptc_keyword_list comma-separated list set_iptc_language_identifier image extra information set_iptc_language_identifier text set_iptc_object_cycle image extra information set_iptc_object_cycle text set_iptc_object_name image extra information set_iptc_object_name text set_iptc_original_transmission_reference image extra information set_iptc_original_transmission_reference text set_iptc_origination_program image extra information set_iptc_originating_program text set_iptc_program_version image extra information set_iptc_program_version text set_iptc_province_state image extra information set_iptc_province_state text set_iptc_reference_date image extra information set_iptc_reference_date datetime set_iptc_reference_number image extra information set_iptc_reference_number text set_iptc_reference_service image extra information set_iptc_reference_service text set_iptc_release_date image extra information set_iptc_release_date datetime set_iptc_release_time image extra information set_iptc_release_time iptc_timeformat set_iptc_source image extra information set_iptc_source text set_iptc_special_instructions image extra information set_iptc_special_instructions text set_iptc_sublocation image extra information set_iptc_sublocation text set_iptc_supplemental_category_list image extra information set_iptc_supplemental_category_list comma-separated list set_iptc_time_created image extra information set_iptc_time_created iptc_timeformat set_iptc_urgency image extra information set_iptc_urgency text set_iptc_writer image extra information set_iptc_writer text setbackgroundcolor Set a new Image background color setbackgroundcolor color

23.3.2012 37/47 setbackgroundtexture Image physical file name to use as the

background texture. Does not modify image pixels.

setbackgroundtexture file_image

setbordercolor sets a border color setbordercolor color setbrush load a brush image to be used when drawing setbrush file/memory image

setcachethreshold Pixel cache threshold in megabytes. Once this threshold is exceeded, all subsequent pixels cache operations are to/from disk. This is a static method and the attribute it sets is shared by all Image objects.

setcachethreshold amount_in_megabytes

setcfmlvar set a cold fusion variable setcfmlvar cfmlvariablename value setcolorfuzz Colors within this distance are considered

equal. A number of algorithms search for a target color. By default the color must be exact. Use this option to match colors that are close to the target color in RGB space.

setcolorfuzz value

setcomment image extra information setcomment text setdrawabledash setting a common drawable dash pattern setdash value1,value2...value9,0

setfillcolor setting a common fill color setfillcolor fillcolor setfillpattern same as settile setfont set text font attributes setfont height,italic,underline,weight,face setfontantialias set font antialiasing on (default) setfontantialias setfontescapement set font escapement ( not recommended ) setfontescapement degree

setfontface set font face (e.g Verdana) setfontface facename setfontheight set font height setfontheigth n setfontitalic set font italics on setfontitalic setfontstrikeout set font strikeout on setfontstrikeout setfontunderline set font underline on setfontunderline

23.3.2012 38/47 setfontweight set font weight setfontweight {

THIN|EXTRALIGHT|LIGHT|NORMAL|MEDIUM|SEMIBOLD|BOLD|EXTRABOLD|HEAVY|DEFAULT }

setfontwidth set font width (works only if lockfont is used) setfontwidth number

setimage set a memory image into memory setimage { imagename=x,y {,bgcolor } | imagename=file | imagename=memory image }

setjpegdpi set image dots per inch value (xResolution and yResolution will be same)

setjpegdpi value

setjpegquality set jpeg quality to 0 - 100 values [setjpegquality value | setquality value] setlinecap set a common linecap: butt (default), round,

square setlinecap {linecap}

setlinejoin set a common linejoin: Miter (default) ,Round,Bevel

setlinejoin {linejoin}

setpixel change a color of one pixel setpixel x,y,color setshadowopacity set text shadow opacity setshadowopacity value setshadowsize set text shadow size setshadowsize x,y setspacing set text spacing setspacing value setstrokeantialias setting stroke antialiasing on. Used with

drawing commands setstrokeantialias

setstrokecolor Setting a common strokecolor if strokecolor is not given

setstrokecolor strokecolor

setstrokepattern same as setbrush setstrokewidth setting a stroke width (e.g. line width) setstrokewidth value

settextalign set text alignment, combinations allowed settextalign { LEFT|RIGHT|TOP|BOTTOM|HCENTER|VCENTER }

settextopacity set text opacity value ( 0 (default) - maximum quantum value).

settextopacity value

settextshadow set text shadow on by using given shadow color

settextshadow color

settextshadowopacity set text shadow opacity ( 0 (default) - maximum quantum value)

settextshadowopacity value

settile set a tile image settile { file | memory image }

23.3.2012 39/47 settransparent set a transparency color. You can actually

use this more than once during the time of iml commands. When writing the image, the first transparent color will be used (gif format). This setting also modifies only the current colors in the image, using the transparent color after this color will not be automatically transparent.

transparent color{,colorfuzz}

setvar set a iml variable or do some calculations. Special use: setvar variablename=getpixel x,y

setvar variable=[expression|'string value'|getpixel x,y]

shade Shade image using distant light source. Specify azimuth and elevation as the position of the light source. By default, the shading results as a grayscale image.. Set colorShading to 1 to shade the red, green, and blue components of the image.

shade {azimuth,elevation{,colorShade}}

sharpen sharpen image sharpen {radius{,sigma}} shave Shave pixels from image edges. shave x,y

23.3.2012 40/47 shear Shear image (create parallelogram by sliding

image by X or Y axis). Shearing slides one edge of an image along the X or Y axis, creating a parallelogram. An X direction shear slides an edge along the X axis, while a Y direction shear slides an edge along the Y axis. The amount of the shear is controlled by a shear angle. For X direction shears, x degrees is measured relative to the Y axis, and similarly, for Y direction shears y degrees is measured relative to the X axis. Empty triangles left over from shearing the image are filled with the color defined as setborderColor.

shear xAngle,yAngle

solarize Solarize image (similar to effect seen when exposing a photographic film to light during the development process)

solarize {factor}

spread Spread pixels randomly within image by specified amount

spread {amount}

square draw a square square x,y,side,color startanimate start animation sequence with current image.

delay in milliseconds, disposal = 0 (remove nothing), 1 (leave as is), 2 (removed by background), 3 (removed by previous),loops = 0, infinitive loop

startanimate delay,disposal{,loops}

stegano Add a digital watermark to the image (based on second image)

stegano [memory image|file image]

23.3.2012 41/47 stereo Create an image which appears in stereo

when viewed with red-blue glasses (Red image on left, blue on right). Images must have equal dimensions.

stereo [memory image|file image]

swirl Swirl image (image pixels are rotated by degrees)

swirl degrees degrees = double

text plot text to image text x,y,x2,y2,color,text textdown plot text to image (down) textdown x,y,x2,y2,color,text textup plot text to image (up) textup x,y,x2,y2,color,text texture Name of texture to tile onto the image

background texture [memory image|file image]

transform Transform image based on image and crop geometries. Crop geometry is optional.

transform imageGeometry{,cropGeometry}

trim Trim edges that are the background color from the image.

trim

unsharpmask Replace image with a sharpened version of the original image using the unsharp mask algorithm. The radius parameter specifies the radius of the Gaussian, in pixels, not counting the center pixel. The sigma parameter specifies the standard deviation of the Gaussian, in pixels. The amount parameter specifies the percentage of the difference between the original and the blur image that is added back into the original. The threshold parameter specifies the threshold in pixels needed to apply the diffence amount.

unsharpmask radius, sigma, amount, threshold

updateframe replace a single frame in the animation sequence

updateframe framenumber,memoryimage

23.3.2012 42/47 useimage set a memory image as active image useimage imagename

wave Alter an image along a sine wave. wave {amplitude{,wavelength}}

write write image to file write filename writeanimate write an animated image to file writeanimate filename writeframes write animation frames to files. basefile

name will be used to produce <basefile>_FRAME<number>.<basefile extension> images. If basefilename is not given, memoryimage name will be used and the files will be in gif format.

writeframes {basefilename}

zoom resize an image using zooming zoom { [x | -1,y | x,y {,thumbnail {,color} | , stretch | bounds | canvas }] }

23.3.2012 43/47

IML Memory images IML uses internal memory images that you can refer via IML commands. There are actually two kinds of images: active (current) and non-active memory images. The current image is the image that you are currently using and memory images are the images allocated by the coder via setimage command. By default, the first current image is always the image set by FILE argument given along the tag call. IML command setimage allocates an image into the memory with coder chosen name. Syntax is simple: <> = parameter [] = options, delimiter = | {} = optional parameters setimage <coder chosen name>=[<full path + filename>|<memory image name>|<x>,<y>{,<background color>}] Example 1: Allocate a new image from file setimage myfileimage=#expandpath('myfile.jpg')# Example 2: Allocate a new image from already allocated memory image setimage myoriginal=original Example 3: Allocate a new image from scratch width=100, height=120, background color=white setimage temp=100,120,ffffff The allocation only sets the image to the "stack", it does not change the current image, e.g if you are using the same memory image already and set an image with the same name, the current image won't be affected until you use another command, useimage. Useimage command searches the memory image from the allocated image stack and sets the found image as current image. The current image will be saved back to the stack if you change the memory image. If don't change the memory image name and use this command, the current image will be refreshed to the initial memory image saved with that name. Therefore you can reuse the same image.

23.3.2012 44/47

Syntax: useimage {<memory image name>} Example 1: set an image and set is as current image setimage temp=#expandpath('myfile.jpg')# useimage temp Example 2: revert back to the original image. ORIGINAL is a special name which is the image that as passed via FILE attribute. useimage Note that you don't need to do "useimage original", simply useimage will be enough that time Example 3: set an image, do some actions and refresh the image from the memory setimage temp=100,100,ffffff useimage temp rect 10,10,70,70,FF0000 write #expandpath('rectangle.gif')# ## this refreshes the image from the memory useimage temp write #expandpath('norectangle.gif')# The second useimage will revert back to the setimage command image and won't contain the rectangle. Example 4: do the same but prior but change the image to another image in between the useimage temp commands. This will effect the temp image. setimage temp=100,100,ffffff useimage temp rect 10,10,70,70,FF0000

23.3.2012 45/47

write #expandpath('rectangle.gif')# ## this will update the temp image to the memory because the image will change useimage ## the temp image will contain the rectangle useimage temp write #expandpath('norectangle.gif')# The "ORIGINAL" image had been retrieved from the memory prior the "useimage temp" command thus making the temp image to be saved back with its changes. You can overwrite to by using yet another setimage before the "useimage" command: setimage temp=100,100,ffffff useimage temp rect 10,10,70,70,FF0000 write #expandpath('rectangle.gif')# ## this will update the temp image to the memory because the image will change setimage temp2=temp useimage ## this command would make the rectangle to apper ## setimage temp2=temp ## the temp2 image will not contain the rectangle useimage temp2 write #expandpath('norectangle.gif')# There are some other special names used by the useimage command, related to animations. If you have properly set animation_support attribute, you can fetch a single frame from the sequence with <memory image name>_FRAME<frame number>: useimage original_frame2 This command will fetch the second frame from the animation sequence. Yet another special name is CURRENT, which refers to the current image. This can only be used with setimage command. setimage copyofcurrent=current

23.3.2012 46/47

All the changes to the current image are effective. Summary of special memory images, please do not use them as coder given names: ORIGINAL = the image referred by the FILE attribute (cfx_openimage file="thisisit.ext") CURRENT= the current active image <memory image name>_FRAME<framenumber> = An image in the animation sequence Other IML commands can make use of memory images too. If an IML command needs a file as a parameter, a memory image can also be used. Commands like copy, copymerge, addanimate, setbrush,settile, updateframe can take memory image names as parameters: copy 0,0,temp This command copies the temp image on top of the current image starting from the position 0,0 CFX_OPENIMAGE vs. CFX_IMAGE Notes: The usage of memory image is bit different in CFX_IMAGE and CFX_OPENIMAGE. CFX_IMAGE memory images are actually pointers to pointers thus the current image and the memory images are being changed at the same time. In CFX_IMAGE the setimage command makes a true copy of an image, in CFX_OPENIMAGE a copy CFX_IMAGE example: setimage temp=100,100,ffffff setimage thisworks=temp useimage temp rect 10,10,70,70,FF0000 write #expandpath('rectangle.gif')# ## this does not refresh the image from the memory useimage temp ## nor this setimage temp2=temp ## but this would work

23.3.2012 47/47

## setimage temp2=thisworks useimage temp2 write #expandpath('norectangle.gif')# The temp memory image in the stack will always be changed when it is the current image. Therefore there is not support for "setimage xxx=current"-like command since it is the same as "settemp xxx=<memory image name>" command. In CFX_OPENIMAGE memory images are pointers to class objects that contain a reference to imageref class. I decided to separate setimage from the current image, but not from the useimage command. Useimage command will make changes to the memory image if the image to be used will be changed. The reason for this is just that I wouldn't like to use a command "setimage <original current memory image name>=current" before changing to another image and loosing all the changes.