For those of you who took a look at the underlying Java methods, you can see that there's a lot of stuff wrapped up in these image objects. The ColdFusion 8 CFImage tag and the related image manipulation functions probably provide some sort of facade that wraps around the underlying methods. For more information about what these do (as they are undocumented), try exploring the java.awt library. Ben Forta stated at the New York ColdFusion Users group that Adobe has built the ColdFusion image manipulation around this library, but that they have also greatly extended it to work around the limits that this library holds.

One of the most exciting features of the new ColdFusion 8 image manipulation is the large number of file formats that can be read in and written out. To give you insight into what is available, ColdFusion 8 has provided two methods: GetReadableImageFormats() and GetWriteableImageFormats(). These return comma-delimited lists of the file types that ColdFusion can deal with.

Calling GetReadableImageFormats() returns:

BMP, GIF, JFIF, JPEG, JPEG 2000, JPEG-LOSSLESS, JPEG-LS, JPEG2000, JPG, PNG, PNM, RAW, TIF, TIFF, WBMP

Calling GetWriteableImageFormats() returns:

BMP, GIF, JFIF, JPEG, JPEG 2000, JPEG-LOSSLESS, JPEG-LS, JPEG2000, JPG, PNG, PNM, RAW, TIF, TIFF, WBMP

Notice that ColdFusion 8 can handle GIF images! Super sweet! I don't know how they handled that one (since I thought Prodigy owned the patent on that or something silly), but it's good to see that we have a huge variety of image formats that we can read and write to.

Now that we have a general overview of what kind of new and exciting image manipulation features are available in ColdFusion 8 and how many image types can be utilized, let's get into the meat of this part of the tutorial: reading and writing images. To start with, let's examine reading images using the CFImage tag. When reading in an image, the source of the image can be any one of the following:

• Absolute path name
• Path name relative to the Web root
• URL
• CFImage variable
• BLOB / Byte array
• Base64 encoded image data
• Binary object

Did anyone else see "URL" and get mentally turned on? 'Cause I did...but, let's not get ahead of ourselves. I want to quickly explore these different source type values and, to do so, I am going to use the INFO action of the CFImage tag. In the first example we are using the CFImage tag in conjunction with an absolute path name to the image.

<!---
Read in the image file. This will read in the binary
image into an object of coldfusion.image.Image.
--->
<cfimage
action="INFO"
source="#ExpandPath( './lady.jpg' )#"
structname="objImageInfo"
/>

<!---
The CFImage tag above stores the image information
into a struct, objImageInfo. Dump out this struct.
--->
<cfdump
var="#objImageInfo#"
label="CFImage : Info Read"
/>

This reads color information, source value, and dimensions into a struct. Running the above code, we get the following CFDump output shown in Figure 1.

The other input types give a similar output, so I won't show the CFDump, however, I will walk through the code. The next one on the list is the Web-relative path:

<!--- Read in the image using a web-relative path. --->
<cfimage
action="INFO"
source="./lady.jpg"
structname="objImageInfo"
/>

This gives us the same output, but the source attribute is "./lady.jpg".

The next input type is a URL (sha-wing!):

<!--- Read in the image using a URL. --->
<cfimage
action="INFO"
source="http://localhost/testing/cf8/lady.jpg"
structname="objImageInfo"
/>

This gives us the same output, but the source attribute is "http://localhost/testing/cf8/lady.jpg". When reading from a URL-based image, you have to be careful about the URL format. It's not just important that the resultant data is image data, it's also important that the last thing in the URL be the file name. For example, using a URL with this query string:

<!--- Read in the image using a URL. --->
<cfimage
action="INFO"
source="http://localhost/testing/cf8/lady.jpg?referrer=bennadel"
structname="objImageInfo"
/>

...will throw the ColdFusion error:

The com image format is not supported on this operating system. Use GetReadableImageFormats() and GetWriteableImageFormats() to see which image formats are supported.