Creates a ColdFusion image. You can use the cfimage tag to perform common image manipulation operations as a shortcut to Image functions. You can use the cfimage tag independently or in conjunction with Image functions.
ColdFusion 8: Added this tag.
Other tag
Add a border to an image <cfimage required action = "border"source = "absolute pathname|pathname relative to the web root|URL|#cfimage variable#"
optional color = "hexadecimal value
|web color
" destination = "absolute pathname
|pathname relative to the web root
" isBase64 = "yes|no" name = "cfimage variable
" overwrite = "yes|no" thickness = "number of pixels
"> Create a CAPTCHA image <cfimage required action = "captcha" height = "number of pixels
" text = "text string
" width = "number of pixels
" optional destination = "absolute pathname
|pathname relative to the web root
" difficulty = "high|medium|low" overwrite = "yes|no" fonts = "comma-separated list of font names
" fontSize = "point size
"> Convert an image file format <cfimage required action = "convert" destination = "absolute pathname
|pathname relative to the web root
"source = "absolute pathname|pathname relative to the web root"|URL|#cfimage variable#
optional isBase64 = "yes|no" name = "cfimage variable
" overwrite = "yes|no"> Retrieve information about an image <cfimage required action = "info"source = "absolute pathname|pathname relative to the web
root|URL|#cfimage variable#" structname = "structure name
" optional isBase64 = "yes|no"> Read an image into memory <cfimage required name = "cfimage variable
"source = "absolute pathname|pathname relative to the web
root|URL|#cfimage variable#" optional action = "read" isBase64 = "yes|no"> Resize an image <cfimage required action = "resize" height = "number of pixels
|percent%
"source = "absolute pathname|pathname relative to the web
root|URL|#cfimage variable#" width = "number of pixels
|percent%
" optional destination = "absolute pathname
|pathname relative to the web root
" isBase64 = "yes|no" name = "cfimage variable
" overwrite = "yes|no"> Rotate an image <cfimage required action = "rotate" angle = "angle in degrees
"source = "absolute pathname|pathname relative to the web
root|URL|#cfimage variable#" optional destination = "absolute pathname
|pathname relative to the web root
" isBase64= "yes|no" name = "cfimage variable
" overwrite = "yes|no"> Write an image to a file <cfimage required action = "write" destination = "absolute pathname
|pathname relative to the web root
" source = "absolute or relative pathname
|URL
|#cfimage variable#
" optional isBase64= "yes|no" overwrite = "yes|no" quality = "JPEG image quality
"> Write an image to the browser <cfimage required action = "writeToBrowser"source = "absolute pathname|pathname relative to the web
root|URL|#cfimage variable#" optional format = "png|jpg|jpeg" isBase64= "yes|no">
ImageAddBorder, ImageInfo, ImageNew, ImageRead, ImageReadBase64, ImageResize, ImageRotate, ImageWrite, ImageWriteBase64, "Creating and Manipulating ColdFusion Images" in the ColdFusion Developer's Guide
Attribute |
Action |
Req/Opt |
Default |
Description |
---|---|---|---|---|
action |
N/A |
Optional |
read |
Action to take. Must be one of the following:
The default action is read, which you do not need to specify explicitly. |
angle |
rotate |
Required |
Angle in degrees to rotate the image. You must specify an integer for the value. |
|
color |
border |
Optional |
black |
Border color. Hexadecimal value or supported named color; see the name list in Valid HTML named colors. For a hexadecimal value, use the form "##xxxxxx" or "xxxxxx", where x = 0-9 or A-F; use two number signs or none. |
destination |
border captcha convert resize rotate write |
Optional (see Description) |
Absolute or relative pathname where the image output is written. The image format is determined by the file extension. The convert and write actions require a destination attribute. The border, captcha, resize, and rotate actions require a name attribute or a destination attribute. You can specify both. ColdFusion 8 supports only CAPTCHA images in PNG format. If you do not enter a destination, the CAPTCHA image is placed inline in the HTML output and displayed in the web browser. |
|
difficulty |
captcha |
Optional |
low |
Level of complexity of the CAPTCHA text. Specify one of the following levels of text distortion:
|
fonts |
captcha |
Optional |
One or more valid fonts to use for the CAPTCHA text. Separate multiple fonts with commas. ColdFusion supports only the system fonts that the JDK can recognize. For example, TTF fonts in the Windows directory are supported on Windows. |
|
fontSize |
captcha |
Optional |
24 |
Font size of the text in the CAPTCHA image. The value must be an integer. |
format |
writeToBrowser |
Optional |
PNG |
Format of the image displayed in the browser. If you do not specify a format, the image is displayed in PNG format. You cannot display a GIF image in a browser. GIF images are displayed in PNG format. |
height |
captcha resize |
Required |
|
Height in pixels of the image. For the resize attribute, you also can specify the height as a percentage (an integer followed by the percent (%) symbol). When you resize an image, if you specify a value for the width, you can let ColdFusion calculate the aspect ratio by specifying "" as the height. If specified, the value must be an integer. |
isBase64 |
border convert info read resize rotate write writeToBrowser |
Optional |
no |
Specifies whether the source is a Base64 string:
|
name |
border convert read resize rotate |
Optional (see Description) |
|
Name of the ColdFusion image variable to create. The read action requires a name attribute. The border, resize, and rotate actions require a name attribute or a destination attribute. You can specify both. |
overwrite |
border captcha convert read resize rotate write |
Optional |
no |
Valid only if the destination attribute is specified. The overwrite values are:
If the destination file already exists, ColdFusion generates an error if the overwrite action is not set to yes. |
quality |
write |
Optional |
0.75 |
Quality of the JPEG destination file. Applies only to files with an extension of JPG or JPEG. Valid values are fractions that range from 0 through 1 (the lower the number, the lower the quality). |
source |
border convert info read resize rotate write writeToBrowser |
Required |
|
|
structName |
info |
Required |
|
Name of the ColdFusion structure to be created. |
text |
captcha |
Required |
|
Text string displayed in the CAPTCHA image. Use capital letters for better readability. Do not include spaces because users cannot detect them in the resulting CAPTCHA image. |
thickness |
border |
Optional |
1 |
Border thickness in pixels. The border is added to the outside edge of the source image, increasing the image area accordingly. The value must be an integer. |
width |
captcha resize |
Required |
|
Width in pixels of the image. For resize, you also can specify the width as a percentage (an integer followed by the % symbol). When you resize an image, if you specify a value for the height, you can let ColdFusion calculate the aspect ratio by specifying "" as the width. If specified, the value must be an integer. |
ColdFusion 8 introduced the cfimage tag and the ColdFusion image, a construct native to ColdFusion that contains image data. You can manipulate ColdFusion images in memory and write them to a file, a database, or directly to a browser. You use the cfimage tag to create ColdFusion images from existing image files and perform simple image actions, such as rotating or resizing. Alternatively, you can use the ImageNew function to create a ColdFusion image from the beginning or from an existing image. You can use the Image functions to perform complex image manipulation operations on ColdFusion images that you create with the cfimage tag or with the ImageNew function.
You can perform the following tasks with ColdFusion images:
For more detailed examples, see "Creating and Manipulating ColdFusion Images" in the ColdFusion Developer's Guide.
The cfimage tag operates on a number of different file formats. To list the formats that are supported on the server where the ColdFusion application is deployed, use the GetReadableImageFormats function and the GetWriteableImageFormats function.
Scorpio supports the following default image formats on Macintosh, Windows, and Unix operating systems:
Scorpio does not support the following image formats:
The cfimage tag supports reading and writing CMYK images, but does not support actions that require converting the images. For example, you can use CMYK images with the read, write, writeToBrowser, resize, rotate, and info actions. You cannot use CMYK images with the convert, captcha, and border actions. The same rule applies to image functions. For example, the ImageNew, ImageRead, and ImageWrite functions support CMYK images, but the ImageAddBorder function does not.
The following table lists the W3C HTML 4 named color value or hexadecimal values that the color attribute accepts:
Color name |
RGB value |
---|---|
Black |
##000000 |
Blue |
##0000FF |
Red |
##FF0000 |
Gray |
##808080 |
LightGray |
##D3D3D3 |
DarkGray |
##A9A9A9 |
Green |
##008000 |
Pink |
##FFC0CB |
Cyan |
##00FFFF |
Magenta |
##FF00FF |
Orange |
##FFA500 |
White |
##FFFFFF |
Yellow |
##FFFF00 |
For all other color values, you must enter the hexadecimal value. Enter a six-digit value, which specifies the RGB value. Values between 00 and FF are allowed.
By default, the cfimage tag generates images with antialiasing turned on (to remove the appearance of jagged edges). The interpolation method is set to highestQuality: this produces a high-quality image, but decreases processing speed. To turn off antialiasing, use the ImageSetAntialiasing function. To change the interpolation method or for more control over image attributes, use the following functions:
<!--- This example shows how to create a ColdFusion image from an existing JPEG file, add a five-pixel-wide red border to the image, and save it to a new JPEG file. ---> <cfimage source="../cfdocs/images/artgallery/jeff05.jpg" action="border" thickness="5" destination="jeff05.jpg" color="red" overwrite="yes">
<cfimage action="captcha" fontSize="25" width="400" height="150" text="rEadMe" fonts="Arial,Verdana,Courier New">
ColdFusion 8 supports CAPTCHA images in PNG format only.
The following example shows how to create CAPTCHA images with a medium level of difficulty that are written to files:
<!--- Use the GetTickCount function to generate unique names for the CAPTCHA files. ---> <cfset tc = GetTickCount()> <cfimage action="captcha" fontSize="15" width="180" height="50" text="rEadMe" destination="images/rEadMe#tc#.png" difficulty="medium">
For a detailed example, see the "Creating and Manipulating ColdFusion Images" in the ColdFusion Developer's Guide.
<!--- This example shows how to convert a JPEG image to a PNG image. ---> <cfimage source="../cfdocs/images/artgallery/aiden02.jpg" action="convert" destination="aiden02.png">
<!--- This example shows how to retrieve and display image information. ---> <cfimage source="../cfdocs/images/artgallery/viata03.jpg" action="info" structName="viatoInfo"> <cfdump var="#viatoInfo#"> <!--- Alternatively, you can use the cfoutput tag to display specific image information, as shown in the following example. ---> <cfoutput> <p>height: #viatoInfo.height# pixels</p> <p>width: #viatoInfo.width# pixels</p> <p>source: #viatoInfo.source#</p> <p>transparency: #viatoInfo.colormodel.transparency#</p> <p>pixel size: #viatoInfo.colormodel.pixel_size#</p> <p>color model: #viatoInfo.colormodel.colormodel_type#</p> <p>alpha channel support: #viatoInfo.colormodel.alpha_channel_support#</p> <p>color space: #viatoInfo.colormodel.colorspace#</p> </cfoutput>
<!--- This code shows how to create a ColdFusion image from a JPEG file. ---> <cfimage source="../cfdocs/images/artgallery/jeff01.jpg" name="myLogo"> <!--- This code shows how to convert the image to grayscale. ---> <cfset ImageGrayscale(myImage)> <!--- This code shows how to write the grayscale image to a JPEG file. ---> <cfimage source="#myImage#" action="write" destination="myGrayscaleImage.jpg" overwrite="yes">
<!--- This example shows how to specify the height and width of an image in pixels. ---> <cfimage source="../cfdocs/images/artgallery/jeff01.jpg" action="resize" width="100" height="100" destination="jeff01_thumbnail.jpg" overwrite="yes"> <!--- This example shows how to specify the height and width of an image as percentages. ---> <cfimage source="../cfdocs/images/artgallery/jeff02.jpg" action="resize" width="50%" height="50%" destination="jeff02_thumbnail.jpg" overwrite="yes"> <!--- This example shows how to specify the height of an image in pixels and its width as a percentage. ---> <cfimage source="../cfdocs/images/artgallery/jeff03.jpg" action="resize" width="50%" height="100" destination="jeff03_thumbnail.jpg" overwrite="yes">
For more control of resize attributes, use the ImageResize function.
<!--- This example shows how to rotate an image by 30 degrees. ---> <cfimage source="../cfdocs/images/artgallery/maxwell01.jpg" action="rotate" angle="30" name="maxwellAngle"> <!--- Display the rotated image in a browser. ---> <cfimage source="#maxwellAngle#" action="writeToBrowser">
For more control of the rotate attributes, use the ImageRotate function.
You can use the write action to change the quality of a JPEG image to reduce file size. The following example shows how to change image quality to .5:
<!--- This example shows how to create a PNG file from a JPEG file by using the write action. ---> <cfimage source="../cfdocs/images/artgallery/aiden01.jpg" action="write" destination="aiden01.png"> <!--- This example shows how to create a low-quality JPEG image. ---> <cfimage source="../cfdocs/images/artgallery/jeff05.jpg" action="write" destination="jeff05_lq.jpg" quality=".5"> <!--- This example shows how to write a JPEG file to a new location. ---> <cfimage source="../cfdocs/images/artgallery/jeff05.jpg" action="write" destination="jeff05.jpg">
<!--- This example shows how to create a ColdFusion image from a JPEG file, resize it, and then display it in the browser as a PNG image. ---> <cfimage source="../cfdocs/images/artgallery/jeff05.jpg" action="resize" width="50%" height="50%" name="smLogo"> <cfimage source="#smLogo#" action="writeToBrowser">
This example shows how to create a ColdFusion image and manipulate it by using Image functions:
<!--- Create the ColdFusion image variable "myImage" from a JPEG file. ---> <cfimage source="../cfdocs/images/artgallery/jeff05.jpg" name="myImage"> <!--- Pass the ColdFusion image to the Image functions to blur the image by a radius of 5, flip the image 90 degrees, and convert the image to grayscale. ---> <cfset ImageBlur(myImage,5)> <cfset ImageFlip(myImage,"90")> <cfset ImageGrayscale(myImage)> <!--- Write the transformed image to a browser. ---> <cfimage source="#myImage#" action="writeToBrowser">