ImageScaleToFit

Description

Creates a resized image with the aspect ratio maintained.

Returns

Nothing.

Function syntax

ImageScaleToFit(name, fitWidth, fitHeight [, interpolation , blurFactor])

History

ColdFusion 8: Added this function.

Parameters

Parameter

Description

name

Required. The ColdFusion image on which this operation is performed.

fitWidth

Required. The width of the bounding box in pixels. You can specify an integer, or an empty string ("") if the fitHeight is specified. See the Usage section for more information.

fitHeight

Required. The height of the bounding box in pixels. You can specify an integer, or an empty string ("") if the fitWidth is specified. See the Usage section for more information.

interpolation

Optional. The interpolation method for resampling. You can specify a specific interpolation algorithm by name (for example, hamming), by image quality (for example, mediumQuality), or by performance (for example, highestPerformance). Valid values are:

  • highestQuality (default)

  • highQuality

  • mediumQuality

  • highestPerformance

  • highPerformance

  • mediumPerformance

  • nearest

  • bilinear

  • bicubic

  • bessel

  • blackman

  • hamming

  • hanning

  • hermite

  • lanczos

  • mitchell

  • quadratic

See Interpolation algorithms in the Usage section for more information.

blurFactor

Optional. The blur factor used for resampling. The higher the blur factor, the more blurred the image (also, the longer it takes to resize the image). Valid values are 1–10.

Usage

Use this operation to resize images or create thumbnail images while maintaining the aspect ratio. Specify the fitWidth and FitHeight parameters; either the fitWidth or the fitHeight can be an empty string:

<cfset ImageScaleToFit(myImage,100,"")>

In this example, the ImageScaleToFit function resizes the image so that it fits in a 100x100-pixel square; the width of the resulting image is 100 pixels and the height is less than or equal to 100 pixels. For example, if the source image is 400x200 pixels, the resulting image is 100x50 pixels.

Likewise, if you specify the fitHeight parameter and an empty string for the fitWidth parameter, the ImageScaleToFit function resizes the image so that the height equals the fitHeight parameter and the width of the image is scaled proportionately:

<cfset ImageScaleToFit(myImage,"",100)>

In this example, a 400x200-pixel source image is resized to 200x100 pixels, and a 200x400-pixel image is resized to 50x100 pixels.

If you set both the fitWidth and the fitHeight parameters, the ImageScaleToFit function resizes the image proportionately so that both conditions are true: the width of the resulting image is less than or equal to the fitWidth, and the height is less than or equal to the fitHeight:

<cfset ImageScaleToFit(myImage,100,200)>

In this example, a 400x200-pixel source image is resized to 100x50 pixels, and a 200x400-pixel source image is resized to 100x200 pixels.

Use the ImageSetAntialiasing function to improve the quality of the rendered image.

Example

<!--- This example shows how to resize an image to fit a 100x100-pixel square while maintaining the aspect ratio. ---> 
<!--- Create a ColdFusion image from an existing JPEG file. ---> 
<cfimage source="../cfdocs/images/artgallery/jeff05.jpg" name="myImage"> 
<!--- Turn on antialiasing to improve image quality. ---> 
<cfset ImageSetAntialiasing(myImage,"on")> 
<cfset ImageScaleToFit(myImage,100,"","lanczos")> 
<!--- Display the modified image in a browser. ---> 
<cfimage source="#myImage#" action="writeToBrowser">