Manipulating ColdFusion images

You can perform a few common manipulation operations on ColdFusion images. For more information on manipulating ColdFusion images, see the CFML Reference.

Adding borders to images

To create a simple border, use the cfimage tag. The following example creates a ColdFusion image with a 5-pixel blue border:

The border is added to the outside edge of the source image. This increases the area of the image.
To create complex borders, use the ImageAddBorder function. The following example shows how to nest borders:

<cfset myImage=ImageNew("../cfdocs/images/artgallery/jeff01.jpg")>

<cfset ImageAddBorder(myImage,5,"blue")>

<cfset ImageAddBorder(myImage,10,"magenta")>

<cfset ImageAddBorder(myImage,20,"green")>

<cfset ImageWrite(myImage,"testMyImage.jpg")>
<img src="testMyImage.jpg"/>

Also, with the ImageAddBorder function, you can add a border that is an image effect. For example, you can use the wrap parameter to create a tiled border from the source image. The wrap parameter creates a tiled border by adding the specified number of pixels to each side of the image, as though the image were tiled.
In the following example, 20 pixels from the outside edge of the source image are tiled to create the border:

For examples of other border types, see the ImageAddBorder function in the CFML Reference.

Creating text images

You can create two types of text images:

A CAPTCHA image, in which ColdFusion randomly distorts the text
A text image, in which you control the text attributes

Creating a CAPTCHA image

You use the captcha action of the cfimage tag to create a distorted text image that is human-readable but not machine readable. When you create a CAPTCHA image, you specify the text that is displayed in the CAPTCHA image; ColdFusion randomly distorts the text. You can specify the height and width of the text area, which affects the spacing between letters, the font size, the fonts to use for the CAPTCHA text, and the level of difficulty, which affects readability. Do not use spaces in the text string specified for the text attribute: users cannot detect the spaces as part of the CAPTCHA image.
The following example shows how to write a CAPTCHA image directly to the browser.

image directly to the browser. --->
<cfimage action="captcha" fontSize="25" width="162" height="75" text="rEadMe"
fonts="Verdana,Arial,Courier New,Courier">

Note: For the CAPTCHA image to display, the width value must be greater than: fontSize times the number of characters specified in text times 1.08. In this example, the minimum width is 162.

ColdFusion 9 supports CAPTCHA images in PNG format only.

Note: If you specify the destination attribute to write CAPTCHA images to files, use unique names for the CAPTCHA image files so that when multiple users access the CAPTCHA images, the files are not overwritten.

The following example shows how to create CAPTCHA images with a high level of text distortion.

For a detailed example, see Using CAPTCHA to verify membership in Application examples that use ColdFusion images.
The following image shows three CAPTCHA images with low, medium, and high levels of difficulty, respectively:

Using the ImageDrawText function

To create a text image by using the ImageDrawText function, specify the text string and the x and y coordinates for the location of the beginning of the text string. You can draw the text on an existing image or on a blank image, as the following examples show:

In the previous examples, the text is displayed in the default system font and font size. To control the appearance of the text, you specify a collection of text attributes, as the following example shows:

To apply the text attributes to the text string, include the attribute collection name in the ImageDrawText definition. In the following examples, the "attr" text attribute collection applies the text string "Congratulations!":

To change the color of the text, use the ImageSetDrawingColor function. This function controls the color of all subsequent drawing objects on an image. In the following example, two lines of text, "Congratulations!" and "Gabriella", inherit the color magenta.

For a list of valid named colors, see the cfimage tag in the CFML Reference.

Drawing lines and shapes

ColdFusion provides several functions for drawing lines and shapes. For shapes, the first two values represent the x and y coordinates, respectively, of the upper-left corner of the shape. For simple ovals and rectangles, the two numbers following the coordinates represent the width and height of the shape in pixels. For a line, the values represent the x and y coordinates of the start point and end point of the line, respectively. To create filled shapes, set the filled attribute to true. The following example shows how to create an image with several drawing objects:

Note: To draw a sequence of connected lines, use the ImageDrawLines function. For more information, see the CFML Reference.

Setting drawing controls

ColdFusion provides several functions for controlling the appearance of drawing objects. As shown in the ImageDrawText example, you use the ImageSetDrawingColor function to define the color of text in an image. This function also controls the color of lines and shapes. To control line attributes (other than color), use the ImageSetDrawingStroke function. The ImageSetDrawingStroke function uses a collection to define the line attributes.
Drawing controls apply to all subsequent drawing functions in an image; therefore, order is important. In the following example, the drawing stroke attributes defined in the attribute collection apply to the square and the two lines. Similarly, the color green applies to the rectangle and the square, while the color red applies only to the two lines. You can reset a drawing control as many times as necessary within an image to achieve the desired effect.

Resizing images

ColdFusion makes it easy to resize images. You can reduce the file size of an image by changing its dimensions, enforce uniform sizes on images, and create thumbnail images. The following table describes the ways to resize images in ColdFusion:

Task	Functions and actions
Resize an image	ImageResize function, or the resize action of the cfimage tag
Resize images so that they fit in a defined square or rectangle and control the interpolation method	ImageScaleToFit function
Resize an image and control the interpolation method	ImageResize function

Using the cfimage tag resize action

Use the cfimage tag resize action to resize an image to the specified height and width. You can specify the height and width in pixels or as a percentage of the original dimensions of the image. To specify a percentage, include the percent symbol (%) in the height and width definitions.

The cfimage tag requires that you specify both the height and the width for the resize action.
The cfimage tag resize action uses the highestQuality interpolation method for the best quality image (at the cost of performance). For faster display, use the ImageResize function or the ImageScaleToFit function.

Using the ImageResize function

The ImageResize function is like the cfimage tag resize action. To ensure that the resized image is proportional, specify a value for the height or width and enter a blank value for the other dimension:

proportionately to the new width. The height value is blank. --->
<cfset myImage=ImageNew("http://www.google.com/images/logo_sm.gif")>
<cfset ImageResize(myImage,"50%","")>

<cfimage source="#myImage#" action="write" destination="test_myImage.jpeg" overwrite="yes">

<img src="http://www.google.com/images/logo_sm.gif"/>
<img src="test_myImage.jpeg"/>

The ImageResize function also lets you specify the type of interpolation used to resize the image. Interpolation lets you control the trade-off between performance and image quality. By default, the ImageResize function uses the highestQuality interpolation method. To improve performance (at the cost of image quality), change the interpolation method. Also, you can set the blur factor for the image. The default value is 1 (not blurred). The highest blur factor is 10 (very blurry). The following example shows how to resize an image using the highPerformance form of interpolation with a blur factor of 10:

Note: Increasing the blur factor reduces performance.

For a complete list of interpolation methods, see ImageResize in the CFML Reference.

Using the ImageScaleToFit function

To create images of a uniform size, such as thumbnail images or images displayed in a photo gallery, use the ImageScaleToFit function. You specify the area of the image in pixels. ColdFusion resizes the image to fit the square or rectangle and maintains the aspect ratio of the source image. Like the ImageResize function, you can specify the interpolation, as the following example shows:

To fit an image in a defined rectangular area, specify the width and height of the rectangle, as the following example shows:

wide and 100 pixels high, while maintaining the aspect ratio of the source image. --->
<cfimage source="../cfdocs/images/artgallery/jeff05.jpg" name="myImage">

<cfset ImageSetAntialiasing(myImage)>
<cfset ImageScaleToFit(myImage,200,100)>

<cfimage source="#myImage#" action="writeToBrowser">

In this example, the width of the resulting image is less than or equal to 200 pixels and the height of the image is less than or equal to 100 pixels.
Also, you can specify just the height or just the width of the rectangle. To do so, specify an empty string for the undefined dimension. The following example resizes the image so that the width is exactly 200 pixels and the height of the image is proportional to the width:

maintaining the aspect ratio of the source image. The interpolation method is set to
maximize performance (which reduces image quality). --->
<cfimage source="../cfdocs/images/artgallery/jeff05.jpg" name="myImage">

<cfset ImageSetAntialiasing(myImage)>
<cfset ImageScaleToFit(myImage,200,"","highestPerformance")>

<cfimage source="#myImage#" action="writeToBrowser">

For more information, see ImageScaleToFit in the CFML Reference.

Creating watermarks

A watermark is a semitransparent image that is superimposed on another image. One use for a watermark is for protecting copyrighted images. To create a watermark in ColdFusion, you use the ImageSetDrawingTransparency function with the ImagePaste function. You can create a watermark image in one of three ways:

Create a watermark from an existing image file. For example, you can use a company logo as a watermark.
Create a text image in ColdFusion and apply the image as a watermark. For example, you can create a text string, such as Copyright or PROOF and apply it to all the images in a photo gallery.
Create a drawing image in ColdFusion and use it as a watermark. For example, you can use the drawing functions to create a green check mark and apply it to images that have been approved.

Creating a watermark from an image file

The following example shows how to create a watermark from an existing GIF image located on a website:

<cfimage source="../cfdocs/images/artgallery/raquel05.jpg" name="myImage">
<cfimage source="http://www.google.com/images/logo_sm.gif" name="myImage2">
<cfimage source="#myImage#" action="write" destination="logo.jpg" overwrite="yes">
<cfset ImageSetDrawingTransparency(myImage,50)>

<cfset ImagePaste(myImage,myImage2,0,0)>

<cfimage source="#myImage#" destination="watermark.jpg" action="write" overwrite="yes">

<img src="watermark.jpg"/>

Creating a watermark from a text image

The following example shows how to create a text image in ColdFusion and use it as a watermark:

Creating a watermark from a ColdFusion drawing

The following example shows how to draw an image in ColdFusion and use it as a watermark. You use the ImageSetDrawingStroke function to define the attributes of lines and shapes you create with drawing functions and the ImageSetDrawingColor function to define the color.

watermark. --->

<cfset myImage=ImageNew("",201,201)>

<cfset ImageSetDrawingTransparency(myImage,30)>

<cfset ImageSetDrawingColor(myImage,"red")>

<cfset attr=StructNew()>
<cfset attr.width = 10>

<cfset ImageSetDrawingStroke(myImage,attr)>

<cfset ImageDrawLine(myImage,40,40,165,165)>

<cfset ImageDrawOval(myImage,5,5,190,190)>

<cfimage source="../cfdocs/images/artgallery/raquel05.jpg" name="myImage2">

<cfset ImageScaleToFit(myImage2,200,200)>

<cfset ImagePaste(myImage,myImage2,0,0)>

<cfimage source="#myImage#" action="write" destination="test_watermark.jpg" overwrite="yes">

<img src="test_watermark.jpg"/>

Get help faster and easier

New user?