This version of CFX_ImageCR 3 has a total of 49 attributes from which to choose imaging operations. The following is a simple example of ImageCR use which resizes "load.jpg" to 100x100 and saves the result to "save.jpg"

<cfx_imagecr3 load="c:\load.jpg" save="c:\save.jpg" resize="100x100">

These attributes accept one or more the following values: integer, string, RectString, MathString, and ColorString. Some of the attributes will assume a default value unless another is defined. All of this is detailed below.

For your convenience we have categorized the attributes as follows:

Converting	load, save, format
Resizing	load, save, resize, resample
Cropping	load, save, crop, recrop, anchor, autocrop
Procedures	border, bordercolor, rotate, prerotate, flip, flop, autocrop, background
Adjustment	contrast, decontrast, brightness, hue, saturation, colorize, sepia, grayscale
Filters	autocontrast, sharpen, blur, quantize, colorspace
Optimization	format, quality, resample, quantize, strip, returnextras, cache
Format Settings	format, quality, quantize, colorspace
Tag Settings	detectchanges, returnextras, cache, setdefaultsave, throwexceptions
Mode Related	getimageinfo, getimagedetails, getversion, getdefaultsave, setdefaultsave
Metadata	dpi, strip, getimageinfo, getimagedetails, getexif, getiptc, comment, getcomment

anchor - autocontrast - autocrop - background - blur - border - bordercolor - brightness - cache - colorize - colorspace - comment - contrast - crop - decontrast - detectchanges - dpi - flip - flop - format - getcomment - getdefaultsave - getexif - getimagedetails - getimageinfo - getiptc - getversion - grayscale - hue - load - prerotate - quality - quantize - recrop - resample - resize - returnextras - root - rotate - saturation - save - savedata - sepia - setdefaultsave - sharpen - strip - throwexceptions

Name	Default Value	Possible values
LOAD	default: N/A	C:\input.jpg http://efflare.com/media/square.jpg #expandpath('image.jpg')# etc..
Load specified file or url. Determines file type regardless of extension.
returns: imagecr.width, imagecr.height, imagecr.filename, imagecr.directory, imagecr.format, imagecr.filesize, imagecr.existed, imagecr.created, imagecr.loadfailed, imagecr.savefailed, imagecr.error, imagecr.errortype, imagecr.errormessage, imagecr.returnvalues see also: How does it work?, detectchanges, root, ExpandPath, getimageinfo, getimagedetails, imagecr.loadfailed
SAVE	default: (special)	C:\output.jpg C:\thumbnails\thumb123.jpg D:\Web\Site\_cache\ #expandpath('image.jpg')# #expandpath('/_cache/')# etc..
Save to specified file or directory. If this is a directory, a unique reproduceable filename is created. If the value ends with "\" or "/" it assumed to be a directory and will be created if it does not exist. If undefined, the defaultsave value is used.
see also: How does it work?, cache, root, format, strip, ExpandPath, Autonaming, Caching, DefaultSave, setdefaultsave, getdefaultsave v3.5.0: saving over the loaded file no longer requires cache=0
RESIZE	default: N/A	#width#x#height# 200x200 x200 200x !100x100 >200x 50% etc..
Resize image to specified RectString's width and height. If either width or height are not specified, it is calculated automatically. By default, the calculation maintains aspect ratio. To override this behaviour, prefix the command with "!". Prefix with "<" to resize only if the input image is smaller than the provided width and height. Prefix with ">" to for the opposite. Width and height may also be specified as percentages with the "%" postfix. By default, images smaller than the specified dimensions are not resized.
see also: RectString, crop
CROP	default: N/A	#width#x#height# 100x100 100x100+20+10
Crop image with specified RectString. The RectString width and height values determine the width and height of the resulting crop. The crop can be anchored to a side, corner, the middle, and more with the anchor attribute. The RectString's optional x and y values can offset the crop for more precise positioning. Finally, the force modifier, !, is applied automatically when cropping.
see also: RectString, anchor v3.5.0: the force modifier, !, is now applied by default
RECROP	default: N/A	#width#x#height# 100x100 100x100+20+10
Exactly the same as crop, but the cropping will occur after resize instead of before.
see also: RectString, anchor, Operation Precedence
ANCHOR	default: N/A	none center northwest north northeast west center east southwest south southeast
When an image is cropped, the crop rectangle can anchored to the side, corner or center of the image. Set this attribute to define the anchor.
see also: crop
BORDER	default: N/A	!#width#x#height# !10x10 0x4 4 etc..
Creates a border around the image defined by specified RectString. Use of the force modifier, !, is usually desired.
see also: bordercolor, RectString, crop
BORDERCOLOR	default: black	#FF0000 #f00 red rgb(255,0,0) rgba(255,0,0,1) hsl(0,100,50) hsla(0,100,50,1) etc..
Color of the border, if any.
see also: ColorString, Color Names
ROTATE	default: N/A	0-360
Rotate by specified number of degrees.
see also: prerotate, background, flip, flop
PREROTATE	default: N/A	0-360
Exactly the same as rotate, but the rotate will occur before resize instead of after.
see also: rotate, flip, flop, Operation Precedence v3.5.0: added
FLIP	default: N/A	None 1 0 True False
Flip horizontally. Top becomes bottom.
see also: flop, rotate
FLOP	default: N/A	None 1 0 True False
Flip vertically. Right becomes left.
see also: flip, rotate
AUTOCONTRAST	default: N/A	None 1 0 True False
Adjust contrast in the image to optimum range. This is the best algorithm to try on subpar photos before adjusting contrast or brightness.
see also: contrast, decontrast, brightness, saturation
CONTRAST	default: N/A	None 1 0 True False
Increase contrast in the image.
see also: autocontrast, decontrast, brightness, saturation
DECONTRAST	default: N/A	None 1 0 True False
Decrease contrast in the image.
see also: autocontrast, contrast, brightness, saturation
SHARPEN	default: N/A	#value# #radius#x#power# 1 2 3 4x2 3x1 0x2 etc..
Sharpen the image using specified MathString, the MathString radius represents the pixel radius of the filter and the MathString power represents the spread of that filter in the radius, or power. For reasonable results radius should be greater than power. If radius is 0, a suitable value will be calculated automatically.
see also: autocontrast, contrast, blur, MathString
BLUR	default: N/A	#value# #radius#x#power# 1 2 3 4x2 3x1 0x2 etc..
Blur the image using specified MathString, the MathString radius represents the pixel radius of the filter and the MathString power represents the spread of that filter in the radius, or power. For reasonable results radius should be greater than power. If radius is 0, a suitable value will be calculated automatically.
see also: decontrast, sharpen, MathString
BRIGHTNESS	default: N/A	0-100 100 and above
Adjust image brightness by integer representing percentage. 100 is normal.
see also: autocontrast, saturation, contrast, decontrast
FORMAT	default: (special)	jpg gif png etc..
Format to save image as. The default is determined by the extension in the value of the SAVE attribute. If the SAVE attribute is a directory, the default is "jpg".
see also: Popular Formats, Supported Formats, DefaultSave, Optimizing
QUALITY	default: 80	0-100
The quality of the resulting image. The exact meaning of this value is specific to the output format.
see also: Popular Formats, Optimizing
DPI	default: N/A	72 96 300 600 etc..
The DPI setting of the resulting image. The exact meaning of this value is specific to the output format. Note that DPI is a setting within some formats which certain output devices will use when deciding how to display the file. It does not change the image data.
see also: getimageinfo, getimagedetails, getexif, imagecr_exif
RESAMPLE	default: lanczos	point box triangle hermite hanning hamming blackman gaussian quadratic cubic catrom mitchell lanczos bessel sinc
When ImageCR needs to resize an image to a different resolution, it needs to interpolate the old image grid to a new one. This is resampling. ImageCR allows you to choose from one of fifteen pixel interpolation algorithms. They are ordered here by processing time, from fastest to slowest, but this is also generally from lowest to highest quality. The default filter, lanczos, produces resampled images of higher quality than most commercial imaging applications.
see also: Resampling Algorithms, Optimizing
FILTER	default: N/A
Deprecated in favor of RESAMPLE.
see also: resample v3.5.0: officially deprecated
QUANTIZE	default: N/A	2 32 256 etc..
Quantize reduces the number of colors in an image. The exact meaning of this value is specific to the output format. For example, specify 32 to save GIF with an efficient 32 color palette.
COLORSPACE	default: N/A	cmyk gray hsl hwb ohta rgb srgb transparent xyz ycbcr ycc yiq ypbpr yuv
Transform the colorspace of the image. In some cases, such as CMYK to RGB conversions, naive algorithms are used. ICC/ICM color profiles are the usual solution to CMYK<->RGB dilemmas.
see also: strip
DETECTCHANGES	default: 1	None 1 0 True False
When true and using autonames, the tag will automatically detect changes to loaded images, reloading and operating on them as necessary to update the output file. Images generated while detectchanges is enabled are not autoname-compatible with images generated while detectchanges is disabled. Files loaded via url do not support detectchanges.
see also: Autonaming, How does it work?
STRIP	default: 1	None 1 0 True False
When true, excess data will be removed from the saved image. Excess data is any data not needed to display the image as it was meant to be displayed. This includes iptc, exif, color profiles, comments, attributes, pen paths, markerlist and more.
see also: Optimizing
RETURNEXTRAS	default: 1	None 1 0 True False
When false, no return values are returned, as a matter of efficiency.
see also: How does it work?, Optimizing
CACHE	default: 1	None 1 0 True False
Cache is enabled by default. With cache enabled, ImageCR will create an output image if the output image does not already exist -or- if it is the same path as the input image. Because of this, invoking ImageCR where you would normally just display images is an efficient and capable technique. Cache is bypassed when overwriting the input image. Finally, autonaming with cache enabled can be useful in certain implementations.
see also: How does it work?, Optimizing, Caching, Autonaming, detectchanges v3.1.0: replaced nocache v3.5.0: saving over the loaded file no longer requires cache=0
NOCACHE	default: N/A
see also: cache v3.5.0: officially deprecated
GETIMAGEINFO	default: N/A	C:\image.jpg http://efflare.com/media/square.jpg #expandpath('image.jpg')# etc..
Returns basic details about the image without loading the file entirely, as a matter of efficiency.
returns: imagecr.width, imagecr.height, imagecr.filename, imagecr.directory, imagecr.format, imagecr.filesize, imagecr.filecreated, imagecr.filemodified, imagecr.fileaccessed, imagecr.dpi, imagecr.loadfailed, imagecr.error, imagecr.errortype, imagecr.errormessage, imagecr.returnvalues see also: getimagedetails, root, ExpandPath, Modes v3.5.0: additional return values v3.5.2: added file timestamp return values
GETIMAGEDETAILS	default: N/A	C:\image.jpg http://efflare.com/media/square.jpg #expandpath('image.jpg')# etc..
Returns extended details about the image, including everything returned by GETIMAGEINFO. However, this attribute will fully load and decode the image file making it slower than GETIMAGEINFO.
returns: imagecr.width, imagecr.height, imagecr.filename, imagecr.directory, imagecr.format, imagecr.filesize, imagecr.filecreated, imagecr.filemodified, imagecr.fileaccessed, imagecr.dpi, imagecr.comment, imagecr_exif, imagecr_iptc, imagecr.loadfailed, imagecr.error, imagecr.errortype, imagecr.errormessage, imagecr.returnvalues see also: getimageinfo, root, ExpandPath, Modes v3.5.0: added v3.5.2: added file timestamp return values
GETVERSION	default: N/A	None 1 0 True False
When true, returns the current version number.
returns: imagecr.version see also: Modes
GETDEFAULTSAVE	default: N/A	None 1 0 True False
When true, returns the value of the default save.
returns: imagecr.defaultsave see also: DefaultSave, Modes
SETDEFAULTSAVE	default: N/A
Sets default save to the specified value. It is expected this will be done in a cached global section of your application.
see also: DefaultSave, Modes, Cached Global Section
THROWEXCEPTIONS	default: 1	None 1 0 True False
This options determines whether or not ImageCR will throw exceptions on defined errors. Undefined errors will still throw exceptions.
see also: imagecr.error, imagecr.errortype, imagecr.errormessage v3.1.0: added
GETEXIF	default: N/A	None 1 0 True False
Retrieve EXIF details when image loaded in load/save mode.
returns: imagecr_exif see also: getimagedetails, getiptc, strip v3.5.0: added
GETIPTC	default: N/A	None 1 0 True False
Retrieve IPTC details when image loaded in load/save mode.
returns: imagecr_iptc see also: getimagedetails, getexif, strip v3.5.0: added
HUE	default: N/A	-180 to 180 270 30 -90 -145 etc..
Adjust hue of image in HSL colorspace. Hue is measured in degrees from -180 to 180 with 0 resulting in no change. Values outside acceptable range are accepted and converted for your convenience.
see also: saturation, colorize, sepia, grayscale v3.5.0: added
SATURATION	default: N/A	-100 to 100+ 30 -100 200 400
Adjust saturation of image in HSL colorspace. Saturation is measured as a percentage from -100 to 100 with 0 resulting in no change. Values above 100 are allowed, but yield diminishing returns.
see also: hue, colorize, sepia, grayscale v3.5.0: changed default from 100 to 0
COLORIZE	default: N/A	0 to 360 270 30 -90 -145 etc..
Color the image with HSL transform. Specify hue in degrees to color, as on a color wheel. Sets constant saturation. Values outside acceptable range are accepted and converted for your convenience.
see also: hue, saturation, sepia, grayscale v3.5.0: added
SEPIA	default: N/A	None 1 0 True False
Adjusts image with traditional sepia tone.
see also: hue, saturation, colorize, grayscale v3.5.0: added
GRAYSCALE	default: N/A	None 1 0 True False
Removes all color from image.
see also: hue, saturation, colorize, sepia v3.5.0: added
AUTOCROP	default: N/A	None 1 0 True False
Performs an automatic crop of the image. Calculates background color and crops out unnecessary edges.
see also: crop, recrop v3.5.0: added
COMMENT	default: N/A	My comment #mycomment#
Sets a text comment in the image file. Works in load/save mode.
see also: getcomment, imagecr.comment, strip, load, save v3.5.0: added
GETCOMMENT	default: N/A	None 1 0 True False
Reads comment attribute in image file and returns the result. Works in load/save mode.
returns: imagecr.comment see also: comment, strip, load v3.5.0: added
SAVEDATA	default: N/A	None 1 0 True False
Saves output image to a Base64String and returns it. Works in load/save mode.
returns: imagecr.data see also: Base64String v3.5.0: added
ROOT	default: N/A	C:\web\images\thumbnails\ #expandpath('.')#
LOAD, SAVE, GETIMAGEINFO, and GETIMAGEDETAILS values are automatically prefixed with ROOT. A directory path is expected. A "/" is appended to the value if it does not end in a slash already. Use of ROOT does not inhibit autonaming. Use of ROOT provides a base for relative paths in relevant attributes, allowing this for example: SAVE="..\..\image.jpg".
see also: load, save, getimageinfo, getimagedetails, ExpandPath, Autonaming, DefaultSave, Caching, How does it work? v3.5.0: added
BACKGROUND	default: (special)	#FF0000 #f00 red rgb(255,0,0) rgba(255,0,0,1) hsl(0,100,50) hsla(0,100,50,1) etc..
Specify a ColorString to define the fill color used when operations, such as rotate, create new undefined areas. Background defaults to the value of the upper-left pixel (0,0).
see also: ColorString, Color Names, rotate, prerotate v3.5.0: added v3.5.1: default alpha from upper-left pixel

The ImageCR RectString allows the developer a more intuitive method of defining dimensions. At first glance, a RectString is simply a width and height delimited by an `x` (eg. '100x100'). Previously, developers using ImageCR defined dimensions absolutely with separate width and height attributes. The RectString allows everything that was previously possible and much more with modifiers.

Syntactically, a RectString can be defined as follows:

Possible values include:

If the width is not specified, it is calculated proportionately based on the height.

If the height is not specified, it is calculated proportionately based on the width.

Append "%" to denote the width and height are percentages, not pixels.

Prefix with "[" to resize so result occupies at most the square region with dimensions defined by the provided value. For example, "[300" will yield dimensions such that both sides are less than, or equal to, 300. Basically, this defines maximum width/height, or "shortest side" logic. (added in v3.5.0)

Prefix with "]" to resize so result occupies at least the square region with dimensions defined by the provided value. For example, "]300" will yield dimensions such that both sides are greater than, or equal to, 300. Basically, this defines minimum width/height, or "longest side" logic. (added in v3.5.0)

Prefix with "<" to resize only if the input image is smaller than the provided width and height.

Prefix with ">" for the opposite

By default, a RectString maintains aspect ratio. To override this, prefix the RectString with the force modifier. This is often the desired effect when cropping.

The optional X value allows a relative offset to be defined for some operations, ie. crop

The optional Y value allows a relative offset to be defined for some operations, ie. crop

Referenced by: resize, crop, recrop, border

The ImageCR MathString defines mathematical dimensions per se, usually for filters. A MathString is simply two real numbers delimited by an 'x' (eg. '2x4'), similar to a basic RectString. However, a MathString differs in that it can accept floating point values for maximum precision.

Syntactically, a MathString can be defined as follows:

Possible values include:

A floating point value often used to represent radius.

A floating point value often used to represent power.

Referenced by: sharpen, blur

The ImageCR ColorString allows color definition by name, hex string, rgb bytes and hsl. ColorString was extended in ImageCR 3.5 to support a superset of CSS3 color units.

Syntactically, a ColorString can be defined as any of the following:

Possible values include all CSS3 color units:

A hexadecimal, html-style string representing color. Both 3 and 6 hex characters are accepted. Just as in HTML, 3 characters are expanded to 6 by duplicating each character, so #FFF becomes #FFFFFF not #F0F0F0.

Note: Coldfusion uses # to denote CFML expressions. As such, you will often need to type # twice in CFX attribute value literals to get the desired results. eg. "##FF0000".

An English color name, see Color Names. Color names come from the 16 HTML4 colors, 147 X11 colors, and two special colors, "transparent" and "efflarered". "transparent" is defined as rgb(0,0,0,0) by CSS3, and "efflarered" is rgb(255,50,0).

Byte values between 0 and 255 representing the intensity of red, green and blue channels.

The same as r,g,b except with an additional value, a, representing alpha. The value of a is between 0 and 1 with 0 being transparent and 1 being opaque.

Hue, saturation and lightness values. Hue ranges from 0 to 360 and represents the hue position, in degrees, on the color wheel where 0 and 360 are red. Saturation and lightness range between 0 and 100.

The same as h,s,l except with an additional value, a, representing alpha. The value of a is between 0 and 1 with 0 being transparent and 1 being opaque.

All values also accept percentages, 0 to 100 with trailing %, and decimal/floating-point values. Additionally, parsing of the a (alpha) value is performed regardless of whether or not the prefix is rgb/rgba or hsl/hsla. In these ways an ImageCR ColorString is a more flexible superset of CSS3 color units.

Referenced by: bordercolor, background

The ImageCR Base64String allows ImageCR to return binary data.

ImageCR encodes the data as a base64 string then prefixes that string with "base64://".

The Coldfusion function ToBinary can be used to decode the data portion of this string back to binary.

Referenced by: savedata