A great feature set of ColdFusion is its image functionality. ColdFusion has the ability to easily manipulate images, create new images, draw images, and write them back to the file system. All this functionality comes right out of the box with ColdFusion without need of any extra plugins or installs.
There are so many pieces of image related functionality that it is not feasible to explain all of them in this section. For the purpose of this section, we will review a few of the more common functions used. To see a full list of image functionality available, go to: http://help.adobe.com/en_US/ColdFusion/10.0/CFMLRef/WSc3ff6d0ea77859461172e0811cbec1a60c-7ffc.html#WSc3ff6d0ea77859461172e0811cbec22c24-66e4.
Before you start manipulating an image, the first thing is to read the image into memory by calling the ImageRead function. The ImageRead function accepts one argument as the path to the image. The argument can either be a path to an images location on your server, the path to an image in the virtual file system, or a URL to the image located on a different server. If you want to manipulate an image provided by the user, the image must be already uploaded to the server, which was discussed in the previous section.
The imageRead function returns an image object which can then be stored in a variable. This image object will be needed for the other image functions. Once you have this image object, you can start to manipulate the image.
The most used image functions are the functions that will resize and crop images. This functionality will allow you to reduce the size of an image so that it will display better on your web site. Rather than resizing an image using the img tag on your web site and scaling it down, the best course of action is to resize the image programmatically.
The best function to use when resizing an image is the ImageScaleToFit function. This function accepts a number of arguments, the first being the image object of which the action will be performed on; the ensuing options are the desired width followed by the desired height. When run, the function will proportionally resize the image so that it is no wider than the specified width and no taller than the specified height.
As an option, the function also accepts values for interpolation and blur factor. The interpolation value controls the quality of the image created. There is a list of a number of algorithms available which can be found in the documentation. The blur factor value specifies how much blur to add to the image. The value is between one and ten, where ten is the blurriest.
Below is an example of an image object being scaled to a 150px by 200px area.
ImageScaleToFit(imageObj,150,200);
If, when scaling an image, your concern is fitting the image into one of the proportions, such as width, then you can opt to pass in an empty string into the other value, as ColdFusion will only scale the image for the specified value. For example, if you only wanted to scale the image to fit into a 100px wide area, you could use the following code:
ImageScaleToFit(imageObj,100,'');
In some situations, it might be necessary to crop an image so that it fits the desired output area. To do this, you will use the imageCrop function. The imageCrop function accepts a number of arguments, all which are required. Along with the image object, you will need to pass in the height and width of the cropped image you are generating as well as the x and y coordinates of where the cropping should begin. For example, if you ran the code sample below, you would generate an image that is 200px high and 150px wide. It was cropped from the image contained in imageObj, and the cropping started 10px from the top and 20px from the left.
ImageCrop(imageObj,20,10,150,200);
At some point in your image manipulation process, you may need to gather certain information about the image, such as width and height. Perhaps you will be using it for logic decisions, or possibly you wish to store it in the database along with a record of the image. Whatever the reason, ColdFusion makes it very simple to do.
The ImageInfo function accepts an image object and returns a struct containing information about the image. In addition to outputting the usually expected information like width and height, it also provides additional information about the image, such as transparency and color space. Here is an example of the information returned when doing ImageInfo on the Google logo:
Optionally, if you just care about the image dimensions, you can call the ImageGetWidth and ImageGetHeight functions, passing in your image object, to get the width and height values of your image.
In the above examples, we have assumed that the image being manipulated is an image that already exists. However, with ColdFusion you can create a new image and manipulate this new image.
To create a new image, you would call the ImageNew function. This function returns an image object. ImageNew has no required arguments; if no arguments are passed, a blank image object will be created and additional functions will need to be called to set its width, height, etc. ImageNew does have a number of optional arguments which are explained below.
- source: The source argument is another image. It can be another image object, a file path, or a URL. If the source argument is used, then the width and height will automatically be set to the dimensions of this image. It cannot be overridden in this function call, but can be changed later. Using the source argument is similar to copying the image, as this will make an entirely new image.
- width: Sets the width of the image, if the source argument has not been provided.
- height: Sets the height of the image, if the source argument has not been provided.
- imageType: This argument allows you to specify the type of image you are creating. You are able to create RBG, ARBG, and grayscale images.
- canvasColor: The background color for the image. This argument accepts a hexidecimal value (such as FFFFFF), a string value (such as Blue), or a list of 3 RGB numbers.
When you have your image object, either via loading in an image or creating a new image, you have the ability to draw on the image. Using the drawing functionality is slightly different than the previous functions you have encountered. Most of the other functions you have reviewed so far have always encapsulated all their data. Other settings that you can control do not affect the output of those functions; when it comes to image functions, that is not the case.
When thinking of the image functions, think of them as if you were using your favorite design software. When you are drawing a line on the page, you would first select the color, then the line thickness, then you would draw the line from point A to point B. That is how it is when using the image functions. Rather than calling a function to draw a line and passing in the line color, the line thickness, and the x and y coordinates of point A and point B, you will set the basic information first, then call the functionality to draw the line.
For example, say you wanted to draw a red line that is 2px thick. The first thing to do is call the ImageSetDrawingColor function, and pass in the image object and the color red. Then you would call the ImageSetDrawingStroke function and pass in the image object and a struct containing our stroke properties. Once that is done, then call the ImageDrawLine function and pass it in the image object, the x and y coordinates of our start point, and the x and y coordinates of our end point, which will then draw the line.
The advantage of calling ImageSetDrawingColor and ImageSetDrawingStrike is that once we draw the first line, we can draw multiple ones and they will all have the same color and stroke styles. If we ever need to change the color, we simply call the ImageSetDrawingColor function with the new color, then draw the next line.
Here is the code for the example discussed above:
imageObj = ImageNew('','200','200','rgb');
ImageSetDrawingColor(imageObj,'Red');
ImageSetDrawingStroke(imageObj,{width=2});
ImageDrawLine(imageObj,50,50,150,150);
And here is the image generated:
Once you have finished manipulating your image, the next thing is to write the image. To write an image to the file system, you will use the ImageWrite function. If the image object you are trying to write was created by reading in an image from the file system, you can call the ImageWrite function and only pass in the image object; it will overwrite the old image with this new one. If you created the image by calling ImageNew or if you do not wish to overwrite the original image, you can also pass in a destination, which is an absolute file path, and a file name of where to save the image. Additionally, ImageWrite has two option arguments that can be passed. The first is if the image should overwrite another image if it already exists; the second is the quality that should be used when encoding the image. The available quality values range from 0 to 1 and only apply to JPG and JPEG images.
During the development process, it can be cumbersome to constantly be writing files to the file system, opening them up in an image editor, and checking if they are correct or not. To speed up the process for development, you can use the cfimage tag and provide an action of writetobrowser. In addition to the action, you provide a source attribute and pass in the image object. The cfimage tag will then output the image to the browser for you rather than having to constantly write it to the file system. Here is an example:
<cfimage action="writeToBrowser" source="#imageObj#" />