Overview:

The image component is a COM object  DLL that allows ASP code to:

• Determine the image size of the image without decompressing the image. 
• Load and decompress jpg, gif or bmp image types.
• Change the image's size
• Draw text on the image
• Save a new copy of the image in compressed jpeg format
• Obtain the EXIF tags from an image

The following example shows how to open an image and just obtain it's size:

Image = Server.CreateObject("SImageUtil.Image");
Image.OpenImageFile("test.jpg");
Response.Write("Size:"+Image.Width+"x"+Image.Height);

The library does not decompress the image unless the image is buffer is touched, either by ChangeSize(),  SaveJpgImage(), or TextBox(). Once the image buffer is touched, the original image is decompress into memory and retained until the Image object is destroyed or until Close() is used.  This is important since image buffers can be large.

General Image object methods and properties are:

Text image object methods and properties are:

EXIF Image methods and properties:

Installation:

1. Make a directory and copy the "SImageUtil.dll" into it.

2. Install the SImageUtil.dll by running "regsrv32 SImageUtil.dll"

Image.PhysicalPath

Boolean which indicates if file names provided to OpenImageFile(), SaveJpgFile(), and Thumb() methods are either IIS filenames or physical filenames.  The default for this value is 'false' which is IIS filenames. 

Remarks:

When using IIS filenames (false) the filename path separator is a foreword slash '/', the path starts at the root of the website, and may contain IIS virtual directories.  This is the same style of filename that appears in a HTML hyperlink.  When  using an IIS name relative filenames are allowed from the current ASP page.  IIS filenames are limited to filenames that appear on the local web site.

When using physical filenames (true) the filename path separartor is a backslash,  may contain a local driver letter or server name, and starts at the root of the drive/device.  This is the type of filename typically used in windows.  When using a physical path the entire filename must be specified.

Example:

The following example opens an image in the preview sub-directory:

Image.OpenImageFile("preview/test.jpg");

The following example opens a image in the "C:\Images" directory on the server:

Image.PhysicalPath = TRUE;
Image.OpenImageFile("C:\\Images\\test.jpg");

If you set the PhysicalPath to true on an Image object you can always set it back to false to use IIS paths, or you can perform the conversion from an IIS pathname to a physical one in your ASP code directly.  For example, the following opens the same file as the first example but does so when using physical paths instead of IIS paths.

Image.PhysicalPath = TRUE;
FileName = Server.MapPath("preview/test.jpg");
Image.OpenImageFile(FileName);

The primary reason to set PhysicalPath to true is to be able to specify filenames that are outside the website. 

Image.ErrorOutput

Boolean which indicates if error text is to be automatically written to the IIS output.  The default for this value is TRUE.

Remarks:

When an error occurs by default the SImageUtil component will output error test to the IIS output stream.  If you set this value to FALSE this will not occur.  In either case, the last error message that was generated is available as LastError.

Image.LastError

A string that contains the last error message.  The message is per open interface instance (e.g., the Image handle).  

Remarks:

If no error has occurred in the open interface instance this value is an empty string.   If an error has occurred, this string contains the error message that was generated.   Note this value may be reset to an empty string when this occurs in order to detect the next failure if needed.

Example:

The following example opens an image and checks to see if the operation caused an error.

Image.OpenImageFile("preview/test.jpg");
if (Image.LastError != "") {
    Response.Write("Image Error: " + Image.LastError);
    return FALSE;
}
return TRUE;

Image.OpenImageFile()

Opens an image file.

Syntax:
Object.OpenImageFile( ImageName)

Parameters:

Remarks:

This function opens an image file and reads the image's attributes (such as width and height).  It does not decompress or read the image itself.  The image is decompress when the image buffer is first accessed. 

The ImageName is a local URL style path name or a physical pathname based on the PhysicalPath setting.  The default is a local URL style name.

Currently only JPEG, GIF and BMP image file formats are supported. 

Example:

The following example reads the image's width and height.

Image.OpenImageFile("photos/test.jpg");
Response.Write("The image width is: " + Image.Width + "<BR>");
Response.Write("The image height is: " + Image.Height + "<BR>");
Image.Close();

Image.Width
Image.Height

The Width and Height properties are read-only properties that returns the image's current width and height.   When the image is first opened the Width and Height are that of the original image.  If the image size is changes, the Width and Height are the new image's size.

Example:

The following example reports the image's width and height after changing its size.

Image.OpenImageFile("photos/test.jpg");
Image.ChangeSize(320,240);
Response.Write("The new width is: " + Image.Width + "<BR>");
Response.Write("The new height is: " + Image.Height + "<BR>");

Image.AllowEnlarge

By default a change size operation will not allow either vertices of an image to be enlarged over the original image's size.  To disable this, set this property to true.

Example:

Image.AllowEnlarge = true;
Image.OpenImageFile("photos/test.jpg");
Image.ChangeSize(Image.Width*2, Image.Height*2);

Note that the AllowEnlarge property can be set on the image object at any time.  An image does not have to be opened to set this property. 

Image.KeepAspect

By default a change size operation will not allow either vertices of an image to be changed disproportionate to one another.   To disable this, set this property to true.

Example:

The follow example reads the image's width and height.

Image.KeepAspect = false;
Image.OpenImageFile("photos/test.jpg");
Image.ChangeSize(Image.Width/2, Image.Height);

Note that the KeepAspect property can be set on the image object at any time.  An image does not have to be opened to set this property. 

Image.ChangeSize()

This function changes the size of the image.

Syntax:
Object.ChageSize( NewWidth, NewHeight)

Parameters:

Remarks:

By using ChangeSize() the image buffer will be decompressed if not already done so.  Once the image buffer is decompressed it remains in memory until the Image object is destroyed or until a Close() is performed. 

ChangeSize() creates a new image buffer from the original image and this becomes the new image for the object.  The size of the new image will be bounded by the current AllowEnlarge and KeepAspect property settings.  Reading Width and Height after calling ChangeSize() will yield the actual width and height of the new image.  

Example:

The following example creates a thumbnail from the image

Image.OpenImageFile("photos/test.jpg");
Image.ChangeSize(150,150);
Image.SaveJpgFile("thumbs/test.jpg", 75);
Image.Close();

Since ChangeSize() always creates the new image from the original image, it can be used to create more then one image at a time without lose of quality due to multiple sizing operations.  This can be useful in removing decompression steps (which can be time consuming). For example, the following to sequences yield the same results but the first is quicker:

// Example #1:
Image.OpenImageFile("photos/test.jpg");
Image.ChangeSize(150,150);
Image.SaveJpgFile("thumbs/test.jpg", 75);
Image.ChangeSize(400,400);
Image.SaveJpgFile("preview/test.jpg", 75);
Image.Close();

// Example #2:
Image.OpenImageFile("photos/test.jpg");
Image.ChangeSize(150,150);
Image.SaveJpgFile("thumbs/test.jpg", 75);

Image.OpenImageFile("photos/test.jpg");
Image.ChangeSize(400,400);
Image.SaveJpgFile("preview/test.jpg", 75);
Image.Close();

Image.SaveJpgFile()

Saves the current image as a JPEG file.

Syntax:
Object.SaveJpgFile( ImageName, Quality)

Parameters:

Remarks:

The current image is compressed based on the Quality setting and saved to ImageName. Note that SaveJpgFile() will create the entire directory tree to the destination filename if it does not already exist.  If the destination ImageName file already exists, it will be replaced. The ImageName is either a local URL path name or a physical pathname as determined by the PhysicalPath setting.  The default is a local URL path name. 

Note if you put text on the image with TextBox() you will likely want a very high quality setting when saving in JPEG format.

Example:

The following example creates a copy of the image with a lower then normal quality setting.

Image.OpenImageFile("photos/test.jpg");
Image.SaveJpgFile("lowqual/test.jpg", 50);
Image.Close();

Image.Close()

Closes the opened image file and release any associated memory for the image.

Syntax:
Object.Close()

Remarks:

There is an implicit close when the Image object is destroyed; however, depending on the size of the source image uncompressed image buffers can be quite large and  if the image is no longer needed a Close() can be perform to free memory right away.

Image.Crop()

Crops the image.

Syntax:
Object.Crop( X, Y, DX, DY )

Parameters:

Remarks:

This functions crops the image such that the new image contains the image formed by the rectangle X,Y,X+DX,Y+DY of the original image.  

Example:

Pull out a 100 x 100 image from the center of the original and then save it.

Image.Crop(Image.Width/2-50, Image.Height/2-50, 100, 100);
Image.SaveJpgFile("test.jpg", 75);

Image.GetPel()

Returns the pixel value at the selected coordinates.

Syntax:
Object.GetPel( X, Y, RGB)

Parameters:

Remarks:

This function is not used by ASP but is instead used by other C++ components.  It returns the 24 bit RGB value of the selected pixel.

Image.Thumb()

The do-it-all function.  Creates the DstImage from the SrcImage if the DstImage does not already exist.

Syntax:
Object.Thumb( SrcImage, NewWidth, NewHeight, DstImage, Quality)

Parameters:

Remarks:

This function first checks to see if DstImage exists. If such a file exists, no further operation is performed and control is returned to the running script.

If DstImage does not exist, the function opens the SrcImage with OpenImageFile(), applies a ChangeSize() on it for NewWidth and NewHeight, and then a SaveJpgImage()  with Quality, and finally a Close().  This sequence is performed on at most one thread at a time on the local server as to not swamp the server.  (E.g., if multiple threads call Image.Thumb() currently for DstImage's that do not exist, they will be decompressed, sized, recompressed and saved one a time.  Serialization only occurs if the DstImage does not exist).

The current set rules for AllowEnlarge and KeepAspect are used during the ChangeSize(), and the PhysicalPath setting determines the SrcImage and DstImage pathname type.

Example:

Make sure we have the preview image, else create it.

Image.Thumb("test.jpg", 320, 240, "preview/test.jpg", 75);

 

Image.TextBox()

Draws text on the image. 

Syntax:
Object.TextBox(Position, Text)

Parameters:

Remarks:

The Text is formatted and fitted into a box.  The entire box of text is then placed on the image according to Position. The background color of the box is set with SetBoxColor() and may be set to any color and opacity - including clear (e.g., no background).  The color of the text defaults to SetTextColor(), and again may be set to any color and opacity. In addition, the color of the text can also be controlled with a <font> tag in the Text string. 

The Text string may include the following escape sequences:

The Text string may include the following tagged modifiers:

The <font> tag may include the following attributes:

The default font and colors are: Arial 10 pts black with a 60% white background.

The colors  available by name are: black, white, red, green, blue, yellow, magenta, cyan, gray, darkred, darkgreen, darkblue, lightbrown, darkmagenta, daycyan.

The Position argument is used to determine the relative position of the text on the image.  The TextBox() function automatically determines the absolute drawing position based on the size of the text being drawn and the Position selected.  There are nine positions:

A ChangeSize() will erase the text draw on the image.  All text must be drawn after the size of the image has been changed (if the size is being changed).

Examples:

Example of position:

Image.TextBox(0, "Pos 0"); Image.TextBox(1, "Pos 1"); Image.TextBox(2, "Pos 2"); Image.TextBox(3, "Pos 3"); Image.TextBox(4, "Pos 4"); Image.TextBox(5, "Pos 5"); Image.TextBox(6, "Pos 6"); Image.TextBox(7, "Pos 7"); Image.TextBox(8, "Pos 8");

Produces:

Example of formatting and alignment::

Str = "On the <u>left</u><br>"; Str += "<Center>In the<br><b>center</b><br>"; Str += "<Right><i>right</i><br></right>"; Str += "<small><small>bye.. bye.."; Image.TextBox(0, Str);

Produces:

Example of font tag:

Str ="<font color=blue size=12>1 Flowers<br>"; Str+="<font color=#cc66ff face='comic sans ms'>2 Flowers<br>"; Str+="<font color=darkgreen face=georgia>3 Flowers<br>"; Str+="<font color=#12456 face=impact>4 Flowers<br>"; Str+="<font color=black face='times new roman'>5 Flowers<br>"; Image.TextBox(3, Str);

Produces:

Note: You can only use fonts that are installed on the server (or whatever machine you are running your code from).  Supplying a font name that does not exist will cause the system to pick a default font for your.  

Image.BoxMargin

The number of pixels between the text box and the image.  The default is 5.

Examples:

Example shows setting the BoxMargin to zero before putting text at position #8 causing no margin between the text and the edge of the image.

Image.TextBox(0, "Pos 0"); Image.BoxMargin = 0; Image.TextBox(8, "Pos 8");

Produces:

Image.SetBoxColor()

Sets the color of the text box. 

Syntax:
Object.SetBoxColor(ColorStr, Opacity)

Parameters:

Examples:

The following images show a different background opacities for a white and black background.  

// Black background, white text sample
Image.SetTextColor("white", 100);
for(i=0;i<9;i++) {
    p = Math.min(100,i*13);
    Image.SetBoxColor("black", p);
    Image.TextBox(i,String(p+"%"));
}

White background, black text

Black background, white text

Note that 0% opacity is no background, and 100% opacity is a solid background.

Image.TextMargin

The number of pixels between the text and the text box.  The default is 3.

Examples:

The example shows a TextMargin of 0 and 10.

Image.TextMargin = 0; Image.TextBox(0, "Pos 0"); Image.TextMargin = 10; Image.TextBox(8, "Pos 8");

Produces:

Image.SetTextColor()

Sets the color of the text. 

Syntax:
Object.SetBoxColor(ColorStr, Opacity)

Parameters:

Remarks

The SetTextColor() function can also be performed with the <font> tag in the text being displayed. 

Examples:

Sold white text with no background Image.SetBoxColor("black", 0); Image.SetTextColor("white", 100); Image.TextBox(4,"<font size=24><b>Flowers");

Produces:

50% opaque white text with no background Image.SetBoxColor("black", 0); Image.SetTextColor("white", 50); Image.TextBox(4,"<font size=24><b>Flowers"); Or.. Image.SetBoxColor("black", 0); Str="<font color=white opacity=50 size=24><b>Flowers"; Image.TextBox(4,Str);

Produces:

Image.GetExif()

Returns the requested Exif tag. 

Syntax:
Object.GetExif(ShortName)

Parameters:

Remarks

This function returns the requested Exif information as a string.   If the Exif information is not found, then an empty string is returned.  

The ShortName is formatted as: Prefix.Name.  Where Prefix is "Main.", "Sub.", an OEM ID, or "".  Following the Prefix is the name of the requested field.  Each prefix has its own list of possible fields that are currently understood by simageutil.  "Main" and "Sub" fields are standardized Exif tags that many camera manufactures supply.  An OEM specific prefix are fields that are specific to an OEM type. 

A field with a prefix is an internally produced field that simageutil creates from the Main, Sub, and OEM prefixes that it found.  This makes life a lot easier for displaying common data as these fields.

The comprehensive list of fields that are understood are in the Exif.cpp source file.  To get a listing of the Exif fields that your camera is providing use DumpExif().  If Name (of Prefix.Name) is a number then that is a tagged field that simageutil doesn't not understand.  You can still obtain the field with GetExif() by using the ShortName as it appears in DumpExif().

For more information see the Exif notes and web sample page.

Example:

// display the camera model
ResponseWrite("Camera Model: "+Image.GetExif("Model")+"<br>");

// display the Nikon specific focus mode
ResponseWrite("Focus Mode: "+Image.GetExif("Nikon.Focus")+"<br>");

Image.DumpExif()

Returns the requested Exif tag. 

Syntax:
Object.DumpExif()

Remarks

This function dumps all the found Exif information from the image to the HTML output device.  This function is used for debugging.  Refer too the Exif notes and web sample page to see a sample output from this function.

Example:

// dump all Exif information
Image.DumpExif();