ASPImage 1.0 Documentation

AspImage 1.x

About ASPImage

ASPImage allows you to create images on the fly from ASP. Features include:

Create GIF* (RLE encoding only. Loading of GIFs not supported) JPG, PNG and BMP format images.

Modify existing images (JPG and BMP)

Gradient fills

Draw methods

ASPImage Installation

To use this ASP component move the DLL into a subdirectory (like \winnt\system32 for NT or \windows\system for Win95). Please use the version of regsvr32 that is included with this component or the version that comes with Microsoft ASP (they are the same version).

To register the component on the system change to the directory where you installed the DLL and type:

regsvr32 aspimage.dll

Simple Image Example

Using the component is as simple as

Creating the object

Setting a few properties

Calling the SaveImage method

The following code demonstrates how to use ASPImage from VBScript. In this example we'll create a text image that say's "Welcome to" with a gradient fill.
  Set Image = Server.CreateObject("AspImage.Image")

  rem Set various font parameters
  Image.FontColor = vbBlack
  Image.Italic = True
  Image.Bold = True
  Image.FontName = "Arial"
  Image.FontSize = 12
  Image.PadSize = 10

  rem Calculate how big our text info is and set the image to this size
  rem  This has to be done since we want to fill the area with a gradient
  strMessage = "Welcome to"
  Image.MaxX = Image.TextWidth (strMessage)
  Image.MaxY = Image.TextHeight (strMessage)

  rem Create a one way gradient
  Image.GradientOneWay vbRed, vbWhite, 0

  rem Print our string to the image
  Image.TextOut strMessage, Image.X, Image.Y, false

  rem Set the filename and save
  rem   NOTE: You should gen the filename dynamically for multiuser usage
  Image.FileName = "d:\inetpub\wwwroot\images\msg1.jpg"
  if Image.SaveImage then
    rem The image was saved so write the <img src> tag out for the browser to pick up
    Response.Write "<img src=""/images/msg1.jpg""><br>"
  else
    rem Something happened and we couldn't save the image so just use an HTML header
    rem   We need to debug the script and find out what went wrong
    Response.Write "<h2>Welcome to</h2>
  end if
By testing the result of the SaveImage method we can determine if the image save was successful or not. If something happened that causes the image not to be saved it probably means the script is saving the image to an invalid directory or a directory where write rights do not exist.

GIF Animations

Images can be loaded or manipulated and then as these modifications occur you can save them to an animated sequence using the call AddImageToAnimation. A simple example of GIF animation can be found in soianim.asp which is included with the eval zip file for AspImage.

About purchasing ASPImage

The license fee covers only one CPU per license. The product may be purchased online from http://www.serverobjects.com/products.htm

About Upgrades

Users can upgrade for free for minor version changes. For example, upgrades from version 1.00 to 1.99 are free. The upgrade from 1.99 to 2.0 may carry an additional license fee.

How to get upgrades

The latest version of the components are always available at http://www.serverobjects.com/products.htm. If a fee is associated with obtaining the upgrade it will be noted on that page.

Upgrade Instructions

To upgrade the component from a previous version please follow these steps:

Stop all IIS related services such as Gopher, FTP and W3SVC.

Change to the directory where the component is located and type "regsvr32 /u aspimage.dll"

Move the new copy of aspimage.dll to the current directory and type "regsvr32 aspimage.dll"

Restart any necessary IIS related services.

Common Problems

Server object error 80040154.
This is the most common error reported. The error means that ASP could not create the object. Causes include:

You never ran regsvr32 on the DLL. See installation section of this document.

You registered the DLL with regsvr32 in one subdirectory and moved it to another.

IIS does not have proper security permissions to access the DLL or the directory you installed it to. See the ASP FAQ (http://www.signmeup.com/faq/) for information on changing security.

Your server may be running low on memory.

Note: Some users have reported that restarting the server after registering the DLL was required to use the component. This should not be necessary but reportedly works in a few cases.

Server object error 'ASP 0177:800401f3'.
This error means "Invalid class string" -- in other words the call to CreateObject failed because the name object cannot be found by the OLE sub-system. Causes include:

You really didn't run regsvr32 on the server after all.

You ran regsvr32 but it reported an error.

Someone modified security on part of the registry that's preventing the OLE subsystem from reading all or part of the HKEY_CLASSES_ROOT tree.

The name of the object you are trying to create was mispelled or is incorrect.

Failures reading and/or writing image files.
Check directory security and make sure that the IIS user (authenticated and/or anonymous) has security permissions that allow read/write to the directories in question. The same problem may occur when using the AddImage method. If this fails make sure the image file is valid and that proper security permissions have been granted for the component to access the file.

Questions about AspImage
The browser is caching the image so my image is not updated on each request. What can I do about that? Web browsers tend to cache images. This is a browser problem, not an AspImage problem. The only solutions we know of are the following:

Set Response.Expires = "0"

Use the Response.BinaryWrite as demo'd in the binwtext.asp sample script included with AspImage. Write an HTML wrapper that calls the ASP file as an image source tag as

<img src="/myapp/myimage.asp">
This method works for most browsers (it fails with some IE / Netscape versions). The only other solution is to...

Create random filenames and then erase the images created during the Session_OnEnd event. This method works for all browsers.

Add a meta tag to your ASP file <meta http-equiv="pragma" content="no-cache">. This will not work in ASP files that use the BinaryWrite call.

Please do not write asking for help with this problem. We cannot do any more than point out the problems associated with these browsers and suggest workarounds. If you need further assistance please contact the browser manufacturer to find out where you can get support for their product. If you want to complain about the problem please contact the browser manufacturer and ask them why their caching algorithms are flawed. ;-)
What color constants are defined by VBScript?
The standard color constants are:

vbBlack

vbRed

vbGreen

vbYellow

vbBlue

vbMagenta

vbCyan

vbWhite
You can, of course, add your own constants to your scripting code. For example:
  vbGrayText = &80000011
I set the AntiAliasText property to false but it still looks like the image is anti-aliased. You are using JPEG encoding and color bleeding is possible with JPEG encoding. The only option is to use another graphic format.
How do I convert HTML colors to RGB colors?
HTML colors are easily converted to RGB values using the VBScript RGB function.
For example the HTML color #E2BBF3 can be converted to RGB as follows
Image.GradientStartColor = vbWhite
Image.GradientEndColor = RGB(&hE2, &hBB, &hF3)
After I load an image how do I find out the Height and Width of the image loaded?
Response.Write 
"Image Height = " & Image.MaxY & " - Image Width = " & Image.MaxX
I add an image but it doesn't automatically resize the image. What's wrong? AspImage only resizes automatically when text is added. There are a number of possible scenarios a user might wish to occur when an image is added and so we do not automatically resize the image in this event. You can manually resize the image if you choose to.

Why doesn't AspImage support GIF? Unisys differentiates between servers and workstations in their GIF licensing policies. In the case of Web servers, they expect the operator of the Web server to pay $1500 a year to allow dynamic generation of GIF images. Because of their policy we cannot ship a GIF enabled version of AspImage to anyone who can't provide proof of owning this $1500 Unisys license. Our suggestion is to avoid GIF.

Is it possible to set the color used by commands such as Rectangle and Ellipse? See the PenColor, PenStyle and PenWidth properties.
Technical Support

If you require technical support please see our tech support page at http://www.serverobjects.com/support.htm

ASPImage Properties
Property Description
AntiAliasText
The AntiAliasText allows you to create anti-aliased text on the image. By default AntiAliasText is false.
Example:
Image.AntiAliasText = True
AutoClear AutoClear is true by default. Once an image is saved the current image is cleared. By setting AutoClear to false you can retain the existing image after a save to continue working with it.
Example:

Image.AutoClear = false
AutoSize
AutoSize determines whether or not an image should be clipped when a draw request that falls outside of the images current coordinates occurs. If AutoSize is true then the image will be enlarged to handle the request. If AutoSize is false then the draw request will be clipped to fit within the current image.
Example:
Image.AutoSize = False
BackgroundColor
Integer value specifies the background color.
Example:
Image.BackgroundColor = vbWhite
Bold
True/false value determines if font is bold or not.
Example:
Image.Bold = True
BrushColor The BrushColor property determines the color of the brush. (available in version >= 1.8)
Image.BrushColor = VbRed

BrushStyle The BrushStyle property determines the pattern painted by the brush.

Value Type Description

0 Solid A solid hatch

1 Clear A "clear"/empty hatch (BS_HOLLOW)

2 Horizontal A horizontal hatch

3 Vertical A vertical hatch

4 FDiagonal A 45-degree downward, left-to-right hatch

5 BDiagonal A 45-degree upward, left-to-right hatch

6 Cross A horizontal and vertical cross-hatch

7 DiagCross A 45-degree crosshatch
Error
The Error property is used to report any errors that may have occurred during various method calls.
Example:
Response.Write "Error: " & Chart.Error
Expires
If the component is an eval or beta version the expires property will return the date that the component quits functioning.
Example:
Response.Write "Component Expires: " & Image.Expires
FileName
The FileName property specifies the physical path where a file will be saved using the SaveImage method.
Example:
Image.FileName = "d:\inetpub\wwwroot\images\abc.jpg"
FontColor
The integer FontColor specifies the color of the font.
Example:
Image.FontColor = vbRed
FontName
The string FontName specifies the name of the font.
Example:
Image.FontName = "MS Sans Serif"
FontSize
The integer FontSize specifies the size of the font.
Example:
Image.FontSize = 12
Image Image is a read only property that contains the binary data for the current Image. You can use this to write the binary data directly to the client rather than using the SaveImage method. Your application design should dictate the best method to use. From ASP you can use Response.BinaryWrite to write this image data to the client. Be sure and set ContentType to the proper content-type. Currently the Image property only supports JPEG or PNG data. See the included file BinWText.asp for an example of how to use this property. Set the ImageFormat property to JPG or PNG before using this property.
ImageFormat
ImageFormat determines what graphics for the image will be saved to. Valid values are

JPG = 1

BMP = 2

PNG = 3

GIF = 5

Example:
Image.ImageFormat = 5
Image.FileName = "c:\inetpub\wwwroot\images\logo.gif"
Italic
True/false value determines if font is italic or not.
Example:
Image.Italic = True
JPEGQuality
If the ImageFormat is set to JPEG then the JPEGQuality property specifies the quality of the JPEG image to be saved. Valid values are 1-100.
Example:
Image.JPEGQuality = 95
MaxX
The MaxX property determines the X size of the image.
Example:
Image.MaxX = 100
MaxY
The MaxY property determines the Y size of the image.
Example:
Image.MaxY = 100
PadSize
The PadSize property allows you to automatically placed horizontal and vertical padding around text.
Example:
Image.PadSize = 5
PenColor
Color determines the color used to draw lines on the canvas.
Example:
Image.PenColor = &h80000011
PenStyle Style determines the style in which the pen draws lines.

Value Type Description

0 Solid A solid line.

1 Dash A line made up of a series of dashes.

2 Dot A line made up of a series of dots.

3 DashDot A line made up of alternating dashes and dots.

4 DashDotDot A line made up of a serious of dash-dot-dot combinations.

5 Clear No line is drawn (used to omit the line around shapes that draw an outline using the current pen).

6 InsideFrame A solid line, but one that may use a dithered color if Width is greater than 1.
PenWidth
Width specifies the maximum width of the pen in pixels.
Example:
Image.PenWidth = 2
ProgressiveJPEGEncoding
ProgressiveJPEGEncoding determines whether an image can be progressively displayed when it is decompressed. ProgressiveJPEGEncoding is off by default.
Example:
ProgressiveJPEGEncoding = true
RegisteredTo Returns the name of the customer or company who purchased the component or "Evaluation" if the component is an evaluation copy.
Strikeout
True/false value determines if font is strikeout or not.
Example:
Image.Strikeout = False
TextAngle
The TextAngle property determines the angle the text written with TextOut is written at. By default TextAngle is 0.
Example:
Image.TextAngle = 90
ThreeDColor
Sets the text color used for 3d text.
Example:
Image.ThreeDColor = &h80000011
TransparentText
Determines whether the TextOut method writes text to the image in transparent mode or not. By default this property is true.
Example:
Image.TransparentText = true
Underline
True/false value determines if font is underlined or not.
Example:
Image.Underline = False
Version
Gets the internal component version number.
Example:
Response.Write "Component Version: " & Image.Version
X
The X property indicates the current X (horizontal) position of the cursor on the image.
Example:
Image.X = 10
Y
The Y property indicates the current Y (vertical) position of the cursor on the image.
Example:
Image.Y = 10
ASPImage Component Methods

Method Parameters Return Value Description

AddAnimationControl intDelay, bolTransparent, intTransparentColor N/A Adds an animation control block to the GIF animation sequence. intDelay is miliseconds to delay till the next image. (available in version >= 1.8)
Image.AddAnimationControl intDelay, false, 0

AddImage strFileName, intX, intY True/False Adds a new image to the canvas using the intX and intY coordinates.

AddImageToAnimation N/A N/A Adds the current image to the GIF animation. StartAnimation must be called before calling AddImageToAnimation. See SaveAnimation. (available in version >= 1.8)
Image.AddImageToAnimation

AddImageTransparent strFileName, intX, intY, intTransparentColor True/False Adds a new image to the canvas using the intX and intY coordinates. intTransparent in the image strFilename is treated as transparent. intTransparentColor is the exact color to make transparent. "Similar" colors are not replaced.
Image.AddImageTransparent "d:\apps\gr3\im.jpg", 5, 12, vbWhite

AngleArc intX, intY, intRadius, dblStartDegrees, dblSweepDegrees N/A The AngleArc function draws a line segment and an arc. The line segment is drawn from the current position to the beginning of the arc. The arc is drawn along the perimeter of a circle with the given radius and center. The length of the arc is defined by the given start and sweep angles. (available in version >= 1.8)
Image.AngleArc 50, 60, 60, 50, 90

Arc intX1, intY1, intX2, intY2, intX3, intY3, intX4, intY4 N/A Draws an arc on the image along the perimeter of the ellipse bounded by the specified rectangle.

BeginPath N/A N/A Opens a path bracket (see EndPath and FillPath). Methods with support paths: Polyline, Polygon, PolyBezier.

BrightenImage intDegree N/A Makes the existing image appear brighter.
Example:

Image.BrightenImage 30

CreateBlackWhite N/A N/A Turns the current image into a greyscale image.

CreateButton
intBorder, bolSoft N/A Creates a button like border around the image for intBorder pixels. If bolSoft is true the button border is softened.
Example:

Image.CreateButton 10, true

CreateNegative N/A N/A Creates a negative image effect of the current image.

CropImage intStartX, intStartY, intWidth, intHeight N/A Crops the image using the X, Y, width and height specified.

Chord intX1, intY1, intX2, intY2, intX3, intY3, intX4, intY4 N/A Draws a closed figure represented by the intersection of a line and an ellipse.

ClearImage N/A N/A Clears the image canvas using the current BackgroundColor as the fill color.

DarkenImage intDegree N/A Makes the existing image appear darker.
Example:

Image.DarkenImage 30

EndPath N/A N/A Closes a path bracket (see BeginPath and FillPath).

Ellipse intX1, intY1, intX2, intY2 N/A Ellipse draws the ellipse defined by a bounding rectangle on the image.

FillPath N/A N/A The FillPath function closes any open figures in the current path and fills the path's interior by using the current brush and polygon-filling mode. (available in version >= 1.8).
Dim aRgnPts(5,1)

aRgnPts(0,0) = 182
aRgnPts(0,1) = 34
aRgnPts(1,0) = 210
aRgnPts(1,1) = 72
aRgnPts(2,0) = 212
aRgnPts(2,1) = 112
aRgnPts(3,0) = 146
aRgnPts(3,1) = 112
aRgnPts(4,0) = 146
aRgnPts(4,1) = 76

Image.BrushStyle = 6
Image.BrushColor = vbRed
Image.BeginPath
Image.Polygon aRgnPts
Image.EndPath
Image.FillPath

FillRect intLeft, intTop, intRight, intBottom N/A FillRect fills the specified rectangle on the image.

FlipImage intDirection N/A Flips the image
Valid values for intDirection are:

1 : Horizontal

2 : Vertical

FloodFill intX, intY, intColor, intFillStyle N/A Use FloodFill to fill a possibly non-rectangular region of the image. The boundaries of the region to be filled are determined by moving outward from the point (X,Y) until a color boundary involving the Color parameter is encountered. Floodfill uses the BackgroundColor and BrushStyle properties.
Legal values for intFillStyle are:

Value Type Description

0 Surface Fills all area that has the color indicated by the intColor parameter but stops when another color intersects.

1 Border Fills all area that does not have the color indicated by the intColor parameter but stops when intColor intersects.

FrameRect intLeft, intTop, intRight, intBottom N/A Draws a 1 pixel wide border around a rectangular region using the points specified.

LoadImage strFileName True/False Loads an existing image into the image canvas. You can load JPG, and BMP files.
LoadImage resets font changes so that changes to the font size, name and characteristics for new text are lost. If you use the LoadImage procedure be sure you make fonts modifications after the call to LoadImage.

GradientOneWay intBeginColor, intEndColor, intDirection N/A Creates a one way gradient beginning with the color intBeginColor and ending in the color specified by intEndColor.

GradientTwoWay intBeginColor, intEndColor, intDirection, intInOut N/A Creates a two way gradient beginning with the color intBeginColor and ending in the color specified by intEndColor.

LineTo intX, intY N/A Creates a line from properties X, Y and going to intX, intY.

LoadBlob ovBlob, intType True/False LoadBlob is designed to allow the loading of binary image data from other AspImage objects (using the .Image property for ovBlob) or from other data sources where binary image data is available via an OLE variant pointer. ovBlob is an OLE variant pointing to raw image data. The raw image data is loaded onto the AspImage canvas.The parameter intType indicates what type of format the binary data is in. Valid intTypes are:

1 : JPEG

2: BMP

Example:

Set Image = Server.CreateObject("AspImage.Image")
Image.LoadImage ("d:\inetpub\wwwroot\images\map.jpg")
Image.FlipImage 2
Image.ImageFormat = 1

Set Image2 = Server.CreateObject("AspImage.Image")
Image2.LoadBlob Image.Image, 1
[Image2 now has a flipped image of map.jpg]

Pie intX1, intY1, intX2, intY2, intX3, intY3, intX4, intY4 N/A Draws a pie-shaped the section of the ellipse bounded by the rectangle (X1, Y1) and (X2, Y2) on the image.

PolyBezier aryPoints N/A Draws one or more Bézier curves. Max of 99 points supported in a single call to PolyBezier. (available in version >= 1.8)
Dim RgnPts(3,1)

RgnPts(0,0) = 79
RgnPts(0,1) = 70
RgnPts(1,0) = 64
RgnPts(1,1) = 86
RgnPts(2,0) = 47
RgnPts(2,1) = 88
Image.PolyBezier RgnPts

Polygon aryPoints N/A Polygon draws a series of lines on the canvas connecting the points passed in and closing the shape by drawing a line from the last point to the first point. (available in version >= 1.8)
Dim RgnPts(4,1)

RgnPts(0,0) = 70
RgnPts(0,1) = 76
RgnPts(1,0) = 310
RgnPts(1,1) = 350
RgnPts(2,0) = 200
RgnPts(2,1) = 450
RgnPts(3,0) = 100
RgnPts(3,1) = 300
Image.Polygon RgnPts

PolyLine aryPoints N/A Polyline draws a series of lines on the canvas with the current pen. Each of the points are connected. (available in version >= 1.8)
Dim RgnPts(3,1)

RgnPts(0,0) = 79
RgnPts(0,1) = 70
RgnPts(1,0) = 64
RgnPts(1,1) = 86
RgnPts(2,0) = 47
RgnPts(2,1) = 88
Image.PolyLine RgnPts

Rectangle intX1, intY1, intX2, intY2 N/A Creates a rectangle using the points specified.

Resize intWidth, intHeight N/A Resizes image to intWidth, intHeight

RotateImage intDegrees N/A Rotates image to specified angle.

RoundRect intX1, intY1, intX2, intY2, intX3, intY3 N/A Creates a round rectangle using the points specified.

SaveAnimation N/A True/False Saves the current GIF animation to the file indicated by the FileName property. (available in version >= 1.8)
Image.SaveAnimation

SaveImage N/A True/False Saves the current image canvas into the file specified in the property FileName.

SetPixel intX, intY, intColor N/A Set the pixel at location intX, intY to intColor. (available in version >= 1.8)
for i = 10 to 50
Image.SetPixel 5+(rnd*10), i, vbGreen
next

StartAnimation bolLoop N/A Starts an animation sequence for animated GIFs. bolLoop indicates whether the animation sequence will loop or not. (available in version >= 1.8)
Image.StartAnimation true

StrokeAndFillPath N/A N/A Closes any open figures in a path, strokes the outline of the path by using the current pen, and fills its interior by using the current brush. (available in version >= 1.8)

TextOut strText, intX, intY, bol3d N/A TextOut writes a text value using the current font, color and other characteristics to the image at the location specified by intX and intY. If bol3d is true then the text is rendered using a 3d look.

TextHeight strValue Integer Returns the text height for strValue using the current font, font size and font characteristics.

TextWidth strValue Integer Returns the text width for strValue using the current font, font size and font characteristics.

TintImage intColor N/A Takes an existing image and shades the image with tints of intColor.
Example:

Image.TintImage vbBlue

The browser is caching the image so my image is not updated on each request. What can I do about that?	Web browsers tend to cache images. This is a browser problem, not an AspImage problem. The only solutions we know of are the following: Set Response.Expires = "0" Use the Response.BinaryWrite as demo'd in the binwtext.asp sample script included with AspImage. Write an HTML wrapper that calls the ASP file as an image source tag as <img src="/myapp/myimage.asp"> This method works for most browsers (it fails with some IE / Netscape versions). The only other solution is to... Create random filenames and then erase the images created during the Session_OnEnd event. This method works for all browsers. Add a meta tag to your ASP file <meta http-equiv="pragma" content="no-cache">. This will not work in ASP files that use the BinaryWrite call. Please do not write asking for help with this problem. We cannot do any more than point out the problems associated with these browsers and suggest workarounds. If you need further assistance please contact the browser manufacturer to find out where you can get support for their product. If you want to complain about the problem please contact the browser manufacturer and ask them why their caching algorithms are flawed. ;-)
What color constants are defined by VBScript?	The standard color constants are: vbBlack vbRed vbGreen vbYellow vbBlue vbMagenta vbCyan vbWhite You can, of course, add your own constants to your scripting code. For example: vbGrayText = &80000011
I set the AntiAliasText property to false but it still looks like the image is anti-aliased.	You are using JPEG encoding and color bleeding is possible with JPEG encoding. The only option is to use another graphic format.
How do I convert HTML colors to RGB colors?	HTML colors are easily converted to RGB values using the VBScript RGB function. For example the HTML color #E2BBF3 can be converted to RGB as follows Image.GradientStartColor = vbWhite Image.GradientEndColor = RGB(&hE2, &hBB, &hF3)
After I load an image how do I find out the Height and Width of the image loaded?	Response.Write "Image Height = " & Image.MaxY & " - Image Width = " & Image.MaxX
I add an image but it doesn't automatically resize the image. What's wrong?	AspImage only resizes automatically when text is added. There are a number of possible scenarios a user might wish to occur when an image is added and so we do not automatically resize the image in this event. You can manually resize the image if you choose to.
Why doesn't AspImage support GIF?	Unisys differentiates between servers and workstations in their GIF licensing policies. In the case of Web servers, they expect the operator of the Web server to pay $1500 a year to allow dynamic generation of GIF images. Because of their policy we cannot ship a GIF enabled version of AspImage to anyone who can't provide proof of owning this $1500 Unisys license. Our suggestion is to avoid GIF.
Is it possible to set the color used by commands such as Rectangle and Ellipse?	See the PenColor, PenStyle and PenWidth properties.