1.4.2012 1/65

CFX_OPENIMAGE 1.4.5 INSTALLATION AND SYNTAX

Jukka Manner 2012

1.4.2012 2/65

CFX_OPENIMAGE 1.4.5 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 Syntax notation: ........................................................................................................................ 28 VARIABLES............................................................................................................................ 30 TEXT STRINGS....................................................................................................................... 31 TEXT COMMAND .................................................................................................................. 32 OTHER TEXT RELATED FUNCTIONS................................................................................. 33 BATCHING! ............................................................................................................................ 37 OUTPUT-VARIABLES............................................................................................................ 39 Optional output ......................................................................................................................... 40 DEBUGGING........................................................................................................................... 41

IML Commands............................................................................................................................ 45 IML Memory images .................................................................................................................... 61

1.4.2012 3/65

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.

1.4.2012 4/65

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.

1.4.2012 5/65

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.

1.4.2012 6/65

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.

1.4.2012 7/65

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 SecKeys section contains security keys generated by the admin. This is not a mandatory attribute

1.4.2012 8/65

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.

1.4.2012 9/65

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. IMG_INTERLACE:

1.4.2012 10/65

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 IPTC_LANGUAGE_IDENTIFIER

1.4.2012 11/65

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

1.4.2012 12/65

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. To determine whether the PING action succeeded or not, examine the IMG_READ status.

1.4.2012 13/65

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.

1.4.2012 14/65

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: By default CFX_OPENIMAGE converts images from CMYK into RGB. If this attribute

1.4.2012 15/65

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.

1.4.2012 16/65

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. READ_CMYK:

1.4.2012 17/65

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.

1.4.2012 18/65

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. Use CFOUTPUT QUERY or CFLOOP QUERY in order to get the column values.

1.4.2012 19/65

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.

1.4.2012 20/65

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: By default CFX_OPENIMAGE converts images from CMYK into RGB. If this attribute

1.4.2012 21/65

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.

1.4.2012 22/65

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 uses ImageMagick's detection.

1.4.2012 23/65

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.

1.4.2012 24/65

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

1.4.2012 25/65

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 Syntax is IPTC_xxxxx = “value”

1.4.2012 26/65

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.

1.4.2012 27/65

IML Commands IML is an abbriviation for Image Management Language, which is build in CFX_OPENIMAGE Cold Fusion Tag. Tag Parameter ACTION="IML" and additional COMMANDS=".." activates the IML parser. COMMANDS-parameter is a linefeed separated (chr(10) or in C/C++ = '\n') list of IML commands: COMMANDS=" line FF0000,0,0,-1,1 write #expandpath(‘myfile.gif’)#" The above feeds two commands to the IML parser: line drawing and write functions. What is also needed is a FILE, which can be either gif or jpeg file or a special name "NEW" ( with X="width" and Y="height" ). IML is very powerful language. It can hold several images in its memory and they can be referenced by user given names, I refer them as memory image variables. IML also includes variables that can contain almost anything - some functions can output their results to cold fusion variables too. A memory image variable, as said, is referenced by user given name. The first image ( FILE-parameter ) is always referenced as "ORIGINAL", which then is also a forbidden name for user images. The mandatory parameters for IML are: <CFX_OPENIMAGE ACTION="IML" FILE="full path and filename" COMMANDS="set of commands"> or <CFX_OPENIMAGE ACTION="IML" FILE="NEW" X="width" Y="height" BGCOLOR="RGBcolor (hex or r,g,b)" COMMANDS="set of commands">

1.4.2012 28/65

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 Commands can be commented: A comment is a line, which starts with double pound sign (##). This line, as well as all uninterpreted lines will be skipped. Uninterpreted line is a line which has a unknown command to be executed. ## this is a comment line Each command has at least one thing in common, a function, the name of function to be executed. -- A command line always starts with a function. -- A function usually accepts parameters, which are *always* separated from the function name by space,comma or equal sign ( in some cases ).Using a space between the function name and its parameters is working for sure. Commands example: ------------------- ## Flood fill from 0,0 ( x, y) with color 255,255,0 fill 0,0,FFFF00 fill = function name 0,0,FFFF00 = parameters

1.4.2012 29/65

Each function is expecting certain parameters, like the above one, fill, is expecting x and y and color values. x and y values are expected to be numeric and color as a color value. A color value does not need to be the usual hex - it also accepts red,green,blue values. So, fill 0,0,255,255,0 would give the same results. The latter version is handy when doing some color manipulation, but I like doing hexes. I took a certain point of view with the ordering of parameters - the rule of thumb is this: 'Positional parameters such as x and y values are first, then comes color and then the rest' One exception: polygons - color are the first and then come the positional parameters.

1.4.2012 30/65

VARIABLES Variables are arbitrary memory strings that can hold some needed data. Some of the functions can return values if they are called with this flag on. The syntax is similar to setimage: setvar tmp=100 This sets variable tmp to 100. To reference this variable: fill 0,<tmp>,FFFF000 The <tmp> is interpreted as 100. The IML includes a simple calculator too. fill 0,<tmp>-10,FFFF00 will give fill 0,90,FFFF00. +,-,*,/ and ^ (power) are currently accepted. You can use multiple calculation primitives too (e.g. <tmp>-10/2+3 ) setvar tmp=100+30 sets tmp to 130 setvar tmp=’100+30’ sets tmp to 100+30

1.4.2012 31/65

TEXT STRINGS SETFONT: -------- SYNTAX: setfont height,italic,underlined,type,face height = font height, for example 24 italic = 0/1 underline = 0/1 type = EXTRALIGHT|LIGHT|NORMAL|SEMIBOLD|BOLD|EXTRABOLD|HEAVY Note that not all the fonts handle these. face=The *desired* face name. You may also want to use a specific charset if your native language uses some non-standard characters. This setting is font specific and may not work all the time. ( setcharset ANSI|OEM|SYMBOL|SYSTEM|CHINESE|HEBREW|ARABIC|SHIFTJIS... ) Examples: setfont 48,0,0,NORMAL,Arial ## This needs a different charset, but the tag automatically seeks it for you ## setcharset OEM setfont 16,0,0,NORMAL,Script SETFONTALIGN: -------------- SYNTAX:setfontalign type type = LEFT|HCENTER|RIGHT|TOP|VCENTER|BOTTOM Combinations are accepted Example: setfontalign VCENTER,HCENTER

1.4.2012 32/65

TEXT COMMAND SYNTAX: text x,y,x2,y2,color,string x = left corner of the rectangle y = top x2 = right ( width ) y2 = bottom ( height ) color: a hex or RGB color string = A string of text. NO NOT SET LINEFEEDS DIRECTLY TO THE TEXT!, Use \n to them. Tabs are always expanded, but you can set tabs with \t too. Examples: text 0,0,400,100,FF0000,Hello, world.\nThis is me talking - again\n\t1\t2\t3\t4 text 0,0,400,100,FF0000,#Replace(textarea,chr(10),'\n','ALL')# The text uses the font that setfont previously defined. If you define a font too large to be fitted in the given rectangle, your font can be automaticly scaled to fit with prior UNLOCKFONT command. This though is quite heavy operation. You can toggle this automatic scaling with LOCKFONT and UNLOCKFONT (setlockfont/killlockfont are also accepted ). The text is wrapped from word breaks - you can add wrapping on you own with \n ( linefeed ). The rectangle x,y,x2,y2 understands negative values: 5,5,-5,-5 sets a rectangle from 5,5 to width - 5, height - 5. If you need to output to the bottom right corner of the image: use 5,5,-1,-1 and setfontalign it to BOTTOM,RIGHT. This shows the execution cycles that your script is doing as well as noninterpreted lines.

1.4.2012 33/65

OTHER TEXT RELATED FUNCTIONS setfontheigth n - same as in setfont height setfontwidth n - sets width ( this causes some alignment difficulties though ) setfontweight weight - same as in setfont setfontface facename - same as in setfont setfontcharset charsetname - set a character set to be used - forces a charset (non-ANSI) to be used setfontitalic - sets italic on setfontspacing - sets intercharacter spacing ( negative or positive ) killfontitalic - sets italic off setfontunderline - sets underline on killfontiunderline - sets underline off settextshadow color - sets shadow and its color settextshadowsize x,y - set shadow size ( negative values are accepted too ) setstyle color,color,color - sets a color sequence for all functions killstyle - swithes style off settile imagefile - sets a tile image for all functions killtile - swithes tile image off setbrush imagefile - sets a brush image for all functions - font height is the maximum size of the brush. killbrush - swithes brush image off Examples: ======================================= Text with line breaks - Note that text is scaled to fit in the rectangle. Scaling is working correcly here, but tabulars causes calculations ( Windows fault ) to give wrong answers. <CFSET #TEXT# = "1. Line 2. Line 3. Line"> <CFX_OPENIMAGE ACTION="IML" DEBUG FILE="NEW" X="200" Y="100" BGCOLOR="cccccc" COMMENT="Your button" COMMANDS=" ## height,italic,underline,weight,face setfont 48,0,0,NORMAL,Arial setfontalign HCENTER,TOP text 1,1,-1,-1,000000,#Replace(text,chr(10),'\n','ALL')# write #ExpandPath('mybutton.gif')#" > <CFOUTPUT> <IMG SRC="#GetFileFromPath(IMG_FILE)#"> </CFOUTPUT>

1.4.2012 34/65

This produces an image

Now, let’s add one extra line <CFSET #TEXT# = "1. Line 2. Line 3. Line 4. Line"> It scales the text automatically:

We could manually change the size, but in order to do that, we stop cfx_openimage autoscaling using lockfont command: setfont 48,0,0,NORMAL,Arial lockfont

Well, though the result is not necessary ideal here, you probably got the point with lockfont. To go back to the autoscaling, use unlockfont command. setfont 48,0,0,NORMAL,Arial lockfont unlockfont

1.4.2012 35/65

Adding styles and shadows <CFSET #TEXT# = "Bold"> <CFX_OPENIMAGE ACTION="IML" DEBUG FILE="NEW" X="200" Y="100" BGCOLOR="cccccc" COMMENT="Your button" COMMANDS=" ## height,italic,underline,weight,face setfont 64,0,0,BOLD,Arial setfontalign HCENTER,VCENTER setstyle ff0000,00ff00,00ff00,0000ff,0000ff settextshadow 0,0,0 setshadowsize 2 text 1,1,-1,-1,000000,#Replace(text,chr(10),'\n','ALL')# write #ExpandPath('mybutton.gif')#" > <CFOUTPUT> <IMG SRC="#GetFileFromPath(IMG_FILE)#"> </CFOUTPUT>

1.4.2012 36/65

Using tiles I’m creating a memory image just to show how tiling work. <CFSET #TEXT# = "TILE THIS"> <CFX_OPENIMAGE ACTION="IML" DEBUG FILE="NEW" X="200" Y="200" COMMENT="Your button" COMMANDS=" ## height,italic,underline,weight,face setfont 74,0,0,BOLD,Arial ## Tile setimage mytile = 10,10,ff00ff useimage mytile frect 0,0,2,2,000000 line 0,2,10,10,00ff00 frect 8,8,10,10,ffffff ## back to original image useimage settile mytile text 1,1,-1,-1,000000,#Replace(text,chr(10),'\n','ALL')# write #ExpandPath('mybutton2.gif')#" > <CFOUTPUT> <IMG SRC="#GetFileFromPath(IMG_FILE)#"> </CFOUTPUT>

1.4.2012 37/65

BATCHING! The FILE-parameter accepts wildcards, like the “dir” command. Each file gets to be processed. You can refer the file in case with these IML-variables, note, they are variable names, not imagenames. <ORIGINAL> = file.extension <ORIGINAL_PATH> = file's path <ORIGINAL_NAME> = file without extension <ORIGINAL_EXTENSION> = file's extension This example reads every file in the currenct directory and if the file is an image file, it will be copied as thumbnail to the thumbnails-directory. I decided to use original extensions, but you can write them all to JPEG,GIF or even PNG. <CFIF #FileExists(Expandpath('.\thumbnails\nul'))# is "No"> <CFDIRECTORY ACTION="CREATE" DIRECTORY="#ExpandPath('.\thumbnails')#"> </CFIF> <CFX_OPENIMAGE ACTION="IML" FILE="#ExpandPath('*.*')#" COMMANDS=" ## thumbnail sizes setvar x=100 setvar y=100 ## label area size setvar bottom=20 ## Resizing to thumbnail resize <x>,<y>,thumbnail ## I need to allocate yet another image in memory to make the label underneath setimage tmp=<x>,<y>+<bottom> useimage tmp ## filled rectangle frect 0,<y>,<x>,<y>+<bottom>,CCCCCC ## copy the original ( thumbnail ) copy 0,0,original ## height, italic, underline, weight (NORMAL, BOLD ,etc ), Face setfont 12,0,0,NORMAL,Arial ## White shadow settextshadow FFFFFF ## one pixels width settextshadowsize 1,1 ## align vertically and horizotally centered setfontalign VCENTER,HCENTER ## black text in rectangle, (text is the file's name ) text 0,<y>,<x>,<y>+<bottom>,000000,<ORIGINAL> ## write it! write <ORIGINAL_PATH>\thumbnails\<ORIGINAL_NAME>.<ORIGINAL_EXTENSION>">

1.4.2012 38/65

This script creates thumbnail images of all found image files to thumbnails subfolder (if created).

1.4.2012 39/65

OUTPUT-VARIABLES IMG_FILE: full path + filename.extension IMG_WIDTH: image width in pixels IMG_HEIGHT: image height in pixels IMG_COLORS: colors or color space ( jpeg, bmp, png ) IMG_DPI ( jpeg only ): dots per inch IMG_ANIMATED: true/false IMG_TRANSPARENT: transparent color (#rrggbb), empty if the image has no transparency set IMG_INTERLACED: true/false IMG_COMMENT: Use defined comment IMG_SIZE: image size in kB's IMG_ATIME: datetime of access IMG_CTIME: datetime of creation IMG_MTIME: datetime of modification IMG_TYPE: gif/jpeg/png/bmp IMG_TYPE_DESCRIPTION: description text of the image type IMG_COLORS: number of colors in the image IMG_CLASSTYPE: Direct of Pseudo IMG_TRANSPARENT: Yes/No IMG_ANIMATED: Yes/No IMG_FRAMES: Number of frames in the image IMG_DPI: Image DPI value IMG_INTERLACE: Yes/No IPTC-variables: ( Photoshop File Info ) IMG_IPTC_LENGTH: Length of IPTC data (zero = no IPTC data) 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:

1.4.2012 40/65

Optional output if you have used IML command: setvar variable_name=getpixel x,y then the tag exposes also VARIABLE_NAME_RGB: reg,blue,green list of colors VARIABLE_NAME_HEX: #rrggbb color if you have used IML command: getsize then the tag exposes also current imagename_WIDTH ( eg. ORIGINAL_WIDTH ): image width current imagename_HEIGHT ( eg. ORIGINAL_HEIGHT ): image height

1.4.2012 41/65

DEBUGGING The tag includes a debugging feature that allows one to check what the tag does and where might be the reason for some odd behaviour The debugging can be started with <CFX_OPENIMAGE DEBUG ..etc> Looking back to the tile example we had, I’ve added DEBUG there too <CFX_OPENIMAGE ACTION="IML" DEBUG FILE="NEW" X="200" Y="200" COMMENT="Your button" COMMANDS=" ## height,italic,underline,weight,face setfont 74,0,0,BOLD,Arial ## Tile setimage mytile = 10,10,ff00ff useimage mytile frect 0,0,2,2,000000 line 0,2,10,10,00ff00 frect 8,8,10,10,ffffff ## back to original image useimage settile mytile text 1,1,-1,-1,000000,#Replace(text,chr(10),'\n','ALL')# write #ExpandPath('mybutton2.gif')#" > The output shows the version of the tag and the version of underlying GraphicsMagick version: CFX_OPENIMAGE v. 1.4.5 Jukka Manner 2012, build on GraphicsMagick 1.3.14 It shows the input parameters (view page source if you want to see them in rows): Input parameters: COMMENT = Your button COMMANDS = # height,italic,underline,weight,face setfont 74,0,0,BOLD,Arial # Tile setimage mytile = 10,10,ff00ff useimage mytile frect 0,0,2,2,000000 line 0,2,10,10,00ff00 frect 8,8,10,10,000000 # back to original image useimage settile mytile text 1,1,-1,-1,000000,TILE THIS write C:\demo\mybutton2.gif FILE = NEW Y = 200

1.4.2012 42/65

DEBUG = true X = 200 ACTION = IML Creating NEW: successfully created image in memory, size (200x200) canvascolor= (Quantum: 65535,65535,65535), (RGB: 255,255,255) (HEX: #ffffff) It also show all the IML command executions and the calculated values, colors etc. You might find your possible typo’s here… IML-Commands: Command lines to be processed: 13 ## height,italic,underline,weight,face setfont: Set Windows font ( Height 74 Italic 0 Underline 0 weight BOLD Face: Arial) ## Tile setimage: New image (MYTILE) in memory ( 10 x 10 ) setimage: IML variable MYTILE_WIDTH set to 10 setimage: IML variable MYTILE_HEIGHT set to 10 useimage: Temporary image (MYTILE) fetched from memory ( 10 x 10 ) frect: drawing a filled rectangle (0x0) - (2x2) frect:fillcolor: color = (Quantum: 0,0,0), (RGB: 0,0,0), (HEX: #000000), (Opacity: 0) line: drawing line from (0x2) to (10x10) frect: drawing a filled rectangle (8x8) - (10x10) frect:fillcolor: color = (Quantum: 0,0,0), (RGB: 0,0,0), (HEX: #000000), (Opacity: 0) ## back to original image useimage: Temporary image (ORIGINAL) fetched from memory ( 200 x 200 ) settile: Temporary image "MYTILE" (10x10) fetched from memory and set as a fill pattern settile: enabling the fillpattern usage. text: Write Windows font string ( at rectangle: 1,1 - 199, 199 ) Calculated plot area: top=1, left=1, bottom=199, right=196 Mapped textmetrics: height=99, Avg.Width=41, Weight=700, Italic=FALSE, Underlined=FALSE, Struckout=FALSE, CharSet=0, Face=Arial text: IML variable LEFT set to 2 text: IML variable TOP set to 18 text: IML variable RIGHT set to 192 text: IML variable BOTTOM set to 181 write: Writing ORIGINAL to C:\demo\mybutton2.gif writing image:CompuServe graphics interchange format

1.4.2012 43/65

After each written image, it shows the image information: Image Information: IMG_FILE: C:\demo\mybutton2.gif IMG_WIDTH: 200 IMG_HEIGHT: 200 IMG_SIZE: 3460 IMG_ATIME: {ts '2012-04-01 13:08:51'} IMG_CTIME: {ts '2012-04-01 11:11:32'} IMG_MTIME: {ts '2012-04-01 13:08:51'} IMG_COMMENT: IMG_TYPE: gif IMG_TYPE_DESCRIPTION: CompuServe graphics interchange format IMG_COLORS: 86 IMG_CLASSTYPE: PseudoClass IMG_TRANSPARENT: FALSE IMG_ANIMATED: FALSE IMG_FRAMES: IMG_DPI: 0 IMG_INTERLACE: UNDEFINED IMG_IPTC_LENGTH: 0 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:

1.4.2012 44/65

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: IPTC_LANGUAGE_IDENTIFIER: IMG_EXIF_KEYS: IMG_EXIF_VALUES: And finally the number of IML commands processed: End of Image Information Command lines processed: 13

1.4.2012 45/65

IML Commands Following IML commands table contains all the available IML commands that you can use. I’ve created some examples in the iml_examples folder in order to help one to study these commands. Special thanks to James Moberg for sharing his index.cfm for that folder.

1.4.2012 46/65

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}

1.4.2012 47/65 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

1.4.2012 48/65 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

1.4.2012 49/65 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]

1.4.2012 50/65 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

1.4.2012 51/65 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

1.4.2012 52/65 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

1.4.2012 53/65 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

1.4.2012 54/65 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

1.4.2012 55/65 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

1.4.2012 56/65 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 }

1.4.2012 57/65 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

1.4.2012 58/65 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]

1.4.2012 59/65 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

1.4.2012 60/65 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 }] }

1.4.2012 61/65

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.

1.4.2012 62/65

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

1.4.2012 63/65

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

1.4.2012 64/65

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 were actually pointers to pointers thus the current image and the memory images are being changed at the same time. In CFX_OPENIMAGE the setimage command makes a true copy of an image. 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

1.4.2012 65/65

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