Image Manipulation Library

revIgniter's Image Manipulation library lets you perform the following actions:

Initializing the Library

Initialize the library in your controller using the rigLoaderLoadLibrary handler:

rigLoaderLoadLibrary "Image"

Once the library is loaded it will be ready for use.

Processing an Image

Regardless of the type of processing you would like to perform (resizing, cropping, rotation, or watermarking), the general process is identical. You will set some preferences corresponding to the action you intend to perform, then call one of four available processing functions. For example, to create an image thumbnail you'll do this:

put "path/to/image/mypic.jpg" into tConfig["sourceImage"]
put TRUE into tConfig["createThumb"]
put TRUE into tConfig["maintainRatio"]
put "75" into tConfig["width"]
put "50" into tConfig["height"]

rigLoaderLoadLibrary "Image", tConfig
-- rigLoadStack "Image", tConfig -- respectively

put rigImageResize() into gData["imageOutput"]

The above code tells the imageResize function to look for an image called mypic.jpg located in the sourceImage folder, then create a thumbnail that is 75 X 50 pixels. The path to the source image is relative to your index.lc file. Since the maintainRatio option is enabled, the thumb will be as close to the target width and height as possible while preserving the original aspect ratio. The thumbnail will be called mypic_thumb.jpg

Note: In order for the image library to be allowed to do any processing, the folder containing the image files must have write permissions.

Dynamic Output of Processed Image

If you set the dynamicOutput option to TRUE, the resulting image data will not be written to disk. Instead a .lc file is saved, which is used as the source for an image tag in your view file. For example, to watermark an image without storing the image you'll do this:

put "overlay" into tConfig["WMtype"]
put "path/to/image/mypic.jpg" into tConfig["sourceImage"]
put "path/to/watermarkImage/wmarkImg.png" into tConfig["WMoverlaypath"]
put TRUE into tConfig["dynamicOutput"]
put "temp/dynOverlay" into tConfig["dynamicOutputURI"]
put "north" into tConfig["WMalignment"]
put "20" into  tConfig["WMvrtOffset"]
put "70" into tConfig["WMopacity"]

rigLoaderLoadLibrary "Image", tConfig
-- rigLoadStack "Image", tConfig -- respectively

put rigImageWatermark() into gData["imageOutput"]

The above code tells the imageWatermark function to use an image overlay as watermark, to look for an image called mypic.jpg located in the sourceImage folder and to look for an overlay image in the watermarkImage folder. Then place the watermark at the top of the source image with a vertical offset of 20 pixels and an opacity of 70% and save the source for your image tag in the "temp" folder located in your controllers folder. Assuming segment-based URLs are used, the returned value looks like this: <img src="http://yourdomain.com/temp/dynOverlay" width="480" height="312" />.

Note: The file defined in the dynamicOutputURI option, used as source in the image tag has to be in the scope of the controllers directory. In the example above the file dynOverlay is located in a subdirectory (called temp) of the controllers directory.

Use the returned value in your view file like in the following example:

<html>
  <head>
  </head>
  <body>
    <p>My watermarked image:</p>
    [[gData["imageOutput"] ]]
  </body>
</html>

Processing Functions

There are four available processing functions:

These functions return TRUE or img tags upon success and FALSE for failure. If they fail you can retrieve the error message using this function:

put rigDisplayImgErrors() into gData["errorsToDisplay"]

A good practice is to use the processing function conditionally, showing an error upon failure, like this:

put rigImageResize() into tImageOutput
if tImageOutput is FALSE then
  put rigDisplayImgErrors() into gData["imageOutput"]
else
  put tImageOutput into gData["imageOutput"]
end if

Note: You can optionally specify the HTML formatting to be applied to the errors, by submitting the opening/closing tags in the function, like this:

get rigDisplayImgErrors("<p>", "</p>")

Preferences

The preferences described below allow you to tailor the image processing to suit your needs.

Note that not all preferences are available for every function. For example, the x/y axis preferences are only available for image cropping. Likewise, the width and height preferences have no effect on cropping. The "availability" column indicates which functions support a given preference.

Availability Legend:

Preference Default Value Options Description Availability
sourceImage None None Sets the source image name/path. The path must be a relative or absolute server path, not a URL. R, C, X, W
dynamicOutput FALSE TRUE/FALSE Determines whether the new image file should be written to disk or generated dynamically. R, C, X, W
dynamicOutputURI imageSrc None Dynamic output image source file path, must be in the scope of the controllers directory. R, C, X, W
exportFormat JPEG JPEG, GIF, PNG Sets the format of the processed image. This preference applies to the stack file version only. R, C, X, W
quality 90 1 - 100 Sets the quality of the image (applies to JPEG only). The higher the quality the larger the file size. R, C, X, W
newImage None None Sets the destination image name/path. You'll use this preference when creating an image copy. The path must be a relative or absolute server path, not a URL. R, C, X, W
width None None Sets the width you would like the image set to. R
height None None Sets the height you would like the image set to. R
createThumb FALSE TRUE/FALSE Tells the image processing function to create a thumb. R
thumbMarker _thumb None Specifies the thumbnail indicator. It will be inserted just before the file extension, so mypic.jpg would become mypic_thumb.jpg R
maintainRatio TRUE TRUE/FALSE Specifies whether to maintain the original aspect ratio when resizing or use hard values. R
cropToFit FALSE TRUE/FALSE Specifies whether the new image should be cropped if the target width/height is not in correct proportion with the source. R
masterDim auto auto, width, height Specifies what to use as the master axis when resizing or creating thumbs. For example, let's say you want to resize an image to 100 X 75 pixels. If the source image size does not allow perfect resizing to those dimensions, this setting determines which axis should be used as the hard value. "auto" sets the axis automatically based on whether the image is taller than wider, or vice versa. R
rotationAngle None 90, 180, 270, vrt, hor Specifies the angle of rotation when rotating images. Note that rotation is counter-clockwise, so a 90 degree rotation to the right must be specified as 270. X
cropAlignment Center Center, North, East, South, West, NorthEast, SouthEast, SouthWest, NorthWest Sets the alignment for image cropping when percentage values are used. C
Xaxis None None Sets the X coordinate in pixels for image cropping. For example, a setting of 30 will crop an image 30 pixels from the left. You can use percentages, then the cropAlignment preference applies. C
Yaxis None None Sets the Y coordinate in pixels for image cropping. For example, a setting of 30 will crop an image 30 pixels from the top. You can use percentages, then the cropAlignment preference applies. C

Setting Preferences in a Config File

If you prefer not to set preferences using the above method, you can instead put them into a config file. Simply create a new file called image.lc, add the tConfig array in that file. Then save the file in: config/image.lc and it will be used automatically. Add rigRunInitialImageConfig tConfig as last line in the file.

rigImageResize()

The image resizing function lets you resize the original image, create a copy (with or without resizing), or create a thumbnail image.

The difference between creating a copy and creating a thumbnail is that thumbnail creation is optimized for shrinking very large images to small thumbnails and that a thumb will have the thumbnail marker as part of the name (ie, mypic_thumb.jpg).

All preferences listed in the table above are available for this function except these four: rotationAngle, cropAlignment, Xaxis, and Yaxis.

Creating a Thumbnail

The resizing function will create a thumbnail file (and preserve the original) if you set this preference to TRUE:

put TRUE into tConfig["createThumb"]

This single preference determines whether a thumbnail is created or not. Setting it to TRUE is the recommended way to resize large images for thumbnail creation.

Creating a Copy

The resizing function will create a copy of the image file (and preserve the original) if you set a path and/or a new filename using this preference:

put "/path/to/new_image.jpg" into tConfig["newImage"]

Notes regarding this preference:

Resizing the Original Image

If neither of the two preferences listed above (createThumb, and newImage) are used, the resizing function will instead target the original image for processing.

rigImageCrop()

The cropping function works nearly identically to the resizing function except it requires that you set preferences for the X and Y axis (in pixels or as percentages) specifying where to crop, like this:

put "100" into tConfig["Xaxis"]
put "40" into tConfig["Yaxis"]

All preferences listed in the table above are available for this function except these: masterDim, rotationAngle, width, height, createThumb, thumbMarker.

Here's an example showing how you might crop an image using percentages:

put "path/to/image/mypic.jpg" into tConfig["sourceImage"]
put "North" into tConfig["cropAlignment"]
put "50%" into tConfig["Xaxis"]
put "80%" into tConfig["Yaxis"]

rigLoaderLoadLibrary "Image", tConfig
-- rigLoadStack "Image", tConfig -- respectively

put rigImageCrop() into tImageOutput
if tImageOutput is FALSE then
  put rigDisplayImgErrors() into gData["imageOutput"]
else
  put tImageOutput into gData["imageOutput"]
end if

Note: Without a visual interface it is difficult to crop images, so this function is not very useful unless you intend to build such an interface.

rigImageRotate()

The image rotation function requires that the angle of rotation be set via its preference:

put "90" into tConfig["rotationAngle"]

There are 5 rotation options:

  1. 90 - rotates counter-clockwise by 90 degrees.
  2. 180 - rotates counter-clockwise by 180 degrees.
  3. 270 - rotates counter-clockwise by 270 degrees.
  4. hor - flips the image horizontally.
  5. vrt - flips the image vertically.

Here's an example showing how you might rotate an image:

put "path/to/image/mypic.jpg" into tConfig["sourceImage"]
put "hor" into tConfig["rotationAngle"]

rigLoaderLoadLibrary "Image", tConfig
-- rigLoadStack "Image", tConfig -- respectively

put rigImageRotate() into tImageOutput
if tImageOutput is FALSE then
  put rigDisplayImgErrors() into gData["imageOutput"]
else
  put tImageOutput into gData["imageOutput"]
end if

rigImgClear

The rigImgClear handler resets all of the values used when processing an image. You will want to call this if you are processing images in a loop.

rigImgClear

 

rigImageNewSettings

Use this handler when calling image manipulation handlers repeatedly.

rigImageNewSettings tConfig

 

rigKnownFonts()

Use this function to check which fonts are available for text watermarking. This function is maintained for compatibility reasons. Of course you can use the fontNames too.

put rigKnownFonts() into tAllFonts

 

Image Watermarking

Two Types of Watermarking

There are two types of watermarking that you can use:

Watermarking an Image

Just as with the other functions (resizing, cropping, and rotating) the general process for watermarking involves setting the preferences corresponding to the action you intend to perform, then calling the watermark function. Here is an example:

put "path/to/image/mypic.jpg" into tConfig["sourceImage"]
put "text" into tConfig["WMtype"]
put "Copyright 2014 - John Doe" into tConfig["WMtext"]
put "18" into tConfig["WMfontsize"]
put "Times" into tConfig["sImgWMfont"]
put "F6F6F6" into tConfig["WMfontcolor"]
put "656565" into tConfig["WMshadowcolor"]
put "North" into tConfig["WMalignment"]
put "20" into  tConfig["WMvrtOffset"]

rigLoaderLoadLibrary "Image", tConfig
-- rigLoadStack "Image", tConfig -- respectively

put rigImageWatermark() into tImageOutput

The above example will use a 18 pixel font to create the text "Copyright 2014 - John Doe". The watermark will be positioned at the top/center of the image, 20 pixels from the top of the image.

Note: In order for the image library to be allowed to do any processing, the image file must have "write" file permissions.

Watermarking Preferences

This table shows the preferences that are available for both types of watermarking (text or overlay)

Preference Default Value Options Description
WMtype text text, overlay Sets the type of watermarking that should be used.
sourceImage None None Sets the source image name/path. The path must be a relative or absolute server path, not a URL.
dynamicOutput FALSE TRUE/FALSE Determines whether the new image file should be written to disk or generated dynamically.
dynamicOutputURI imageSrc None Dynamic output image source file path, must be in the scope of the controllers directory.
exportFormat JPEG JPEG, GIF, PNG Sets the format of the processed image. This preference applies to the stack file version only.
quality 90 1 - 100 Sets the quality of the image (applies to JPEG only). The higher the quality the larger the file size.
WMalignment South Center, North, East, South, West, NorthEast, SouthEast, SouthWest, NorthWest Sets the alignment for the watermark image.
WMhorOffset 0 None You may specify a horizontal offset (in pixels) to apply to the watermark position.
WMvrtOffset 10 None You may specify a vertical offset (in pixels) to apply to the watermark position.

Text Preferences

This table shows the preferences that are available for the text type of watermarking.

Preference Default Value Options Description
WMtext None None The text you would like shown as the watermark. Typically this will be a copyright notice.
WMfont Helvetica None The font.
WMfontsize 16 None The size of the text.
WMfontcolor f6f6f6 None The font color, specified in hex. Note, you must use the full 6 character hex value (ie, 993300), rather than the three character abbreviated version (ie fff). The stack file version of the library allows additionally to use RGB values like 248,248,248.
WMshadowcolor 656565 None The color of the drop shadow, specified in hex. If you leave this blank a drop shadow will not be used. Note, you must use the full 6 character hex value (ie, 993300), rather than the three character abbreviated version (ie fff). The stack file version of the library allows additionally to use RGB values like 120,120,120.
WMshadowdistance 1 None The distance (in pixels) from the font that the drop shadow should appear.
WMshadowsize 1 None The size of the drop shadow should. This preference applies to the stack file version of the library only.
WMshadowopacity 180 1 - 255 Drop shadow opacity. This preference applies to the stack file version of the library only.

Overlay Preferences

This table shows the preferences that are available for the overlay type of watermarking.

Preference Default Value Options Description
WMoverlaypath None None The server path to the image you wish to use as your watermark. Required only if you are using the overlay method.
WMopacity 15 1 - 100 Image opacity. You may specify the opacity (i.e. transparency) of your watermark image. This allows the watermark to be faint and not completely obscure the details from the original image behind it.