|
cfimage
DescriptionCreates
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.
HistoryColdFusion
8: Added this tag.
SyntaxAdd 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">
Note: You can
specify this tag’s attributes in an attributeCollection attribute
whose value is a structure. Specify the structure name in the attributeCollection attribute
and use the tag’s attribute names as structure keys.
Attributes
Attribute
|
Action
|
Req/Opt
|
Default
|
Description
|
action
|
N/A
|
Optional
|
read
|
Action to take. Must be one of the following:
border
captcha
convert
info
read
resize
rotate
write
writeToBrowser
The default
action is read, which you do not need to specify
explicitly.
|
angle
|
rotate
|
Required
|
|
Angle in degrees to rotate the image.
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
section. 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
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 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
|
|
URL of the source image; for
example, "http://www.google.com/images/logo.gif"
Absolute pathname or a pathname relative to the web root;
for example: "c:\images\logo.jpg"
ColdFusion image variable containing another image, BLOB,
or byte array; for example, "#myImage#"
Base64 string; for example, "data:image/jpg;base64,/9j/4AAQSkZJRgABAQA.............."
|
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.
|
UsageColdFusion
provides 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:
Convert an image from one file format to another. For example,
you can convert a BMP file to a JPEG file or a Base64 string to
a GIF.
Enforce consistent sizes on files uploaded to the server.
Enforce size limits on JPEG images (by changing the quality
of the image).
Save a ColdFusion image to a file or write the image directly
to a browser.
Use the ImageGetBlob function within
the cfquery tag to insert a ColdFusion image as
a Binary Large Object Bitmap (BLOB) in a database. Also, you can
extract a BLOB from a database and generate a ColdFusion image from
it.
Create watermark images.
Create thumbnail images.
Create a Completely Automated Public Turing test to tell
Computers and Humans Apart (CAPTCHA) image, a distorted text image
that is human-readable, but not machine-readable, used in a challenge-response
test for preventing spam.
For more detailed examples,
see Creating
and Manipulating ColdFusion Images in the Developing ColdFusion Applications.
File attributesUse the following syntax to specify an in-memory
file, which is not written to disk in the destination and source attributes.
In-memory files speed processing of transient data.
ram:///filepath
The
filepath can include directories, for example ram:///petStore/images/poodle.jpg.
Create the directories in the path before you specify the file.
For more information on using in-memory files, see Optimizing
transient files in the Developing ColdFusion Applications.
Supported image file formatsThe 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.
ColdFusion
supports the following default image formats on Macintosh, Windows,
and Unix operating systems:
ColdFusion does not support the following
image formats:
Animated GIF
Multipage TIFF
PSD
AI
CMYK supportThe 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.
Valid HTML named colorsThe 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, enter the hexadecimal
value. Enter a six-digit value, which specifies the RGB value. Values
between 00 and FF are allowed.
Image qualityBy 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:
ImageResize
ImageRotate
ImageScaleToFit
ImageShear
ImageTranslate
- border action
- Use the border action to create a rectangular
border around the outer edge of an image. You can control the thickness
of the border and its color. For more control, use the ImageAddBorder function.
The following example shows how to set the thickness and color of
a border:
<!--- 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">
- captcha action
- Use the captcha action 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 used for the
CAPTCHA text, and the level of difficulty, which affects readability. The
following example shows how to write a CAPTCHA image directly to
the browser:
<cfimage action="captcha" fontSize="25" width="400" height="150" text="rEadMe"
fonts="Arial,Verdana,Courier New">
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 supports
CAPTCHA images in PNG format only.
Note: 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 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 Developing ColdFusion Applications.
- convert action
- Use the convert action to convert an image
from one file format to another. For more information on file formats,
see the section Supported image file formats. The following example
shows how to convert a JPEG file to a PNG file:
<!--- 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">
Note: Converting
images between one file format to another is time-consuming. Also,
image quality can degrade; for example, PNG images support 24-bit
color, but GIF images support only 256 colors. Converting transparent
images (images with alpha) can degrade image quality.
- info action
- Use the info action to create a ColdFusion
structure that contains information about the image, including the
color model, height, width, and source of the image. The structure
is the same as returned by the ImageInfo function. The following
example shows how to retrieve all of the information about an image:
<!--- 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>
- read action
- Use the read action to read an image from
the specified local file pathname or URL, and create a ColdFusion
image in memory. You can use the ColdFusion image variable as the
source for another cfimage tag or for Image functions.
The read action performs the same operation as
the ImageRead function. The following
example shows how to create a ColdFusion image from a JPEG file
and manipulate it using the ImageGrayscale function:
<!--- This code shows how to create a ColdFusion image from a JPEG file.
--->
<cfimage source="../cfdocs/images/artgallery/jeff01.jpg" name="myImage">
<!--- 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">
- resize action
- Use the 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:
<!--- 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.
- rotate action
- Use the rotate action to rotate an image
by degrees:
<!--- 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.
- write action
- Use the write action to write an image to
the specified path. The new image is converted to the file type
specified in the destination attribute. The write action
performs the same operation as the ImageWrite function. When
you write an image to a JPEG file, the image quality is set to 75%
of the original image by default. To control the image size, use
the quality attribute of the write action.
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">
- writeToBrowser action
- Use the writeToBrowser action to display
one or more ColdFusion images directly to the browser without writing
them to files. Images are displayed in PNG format. The following
example shows how to reduce the size of an image and display it
in the browser:
<!--- 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">
ExampleThis
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">
|