Version 1.0.5 documentation (Sunday the 23rd February, 2003)
What is ASPCanvas?
How does it work?
Requirements
Installation instructions
Usage
Methods
Properties
Current limitations
Sample code
How to include the image within HTML
UNISYS and GIF royalties
Technical notes
Defining your own fonts
Including multiple images from your ASP files
ASP Client side debugging
GIF Files not rendering correctly in non-IE browsers
I'm running the script but all I'm getting is a page with 'GIF87a x÷ÿÿÿÿÿÿ, xÿ...' in the top left
ChiliSoft ASP package
Why doesn't this use the FileSystemObject for file I/O?
Extra font packs
Contacting the author
Planned modifications
Credits
Copyright
Pointers in the right direction
Version history
ASPCanvas is a graphic device class for use on ASP enabled web servers. This class is written in pure ASP and requires no server components or COM objects to be installed on the web server. This class can be used to draw graphics in ASP and display the output on any web browser.
ASPCanvas creates a drawing device in memory where various graphical functions can take place, such as defining colour palettes, drawing lines and rendering text. Once the canvas is ready to be sent from the web server to the web client, ASPCanvas creates a GIF file and sends it to the ASP response object.
You will require a web server which supports ASP, with version 5.0 or higher of Microsofts VBScript library. NOTE: This class will NOT work on ChiliSoft's ASP package. Please see notes.
Install "canvas.asp" and "font.asp" to a folder on the ASP enabled web server. The folder must have the correct permissions to run ASP pages.
To create a simple canvas, simply use the code below:
Dim objCanvas
Set objCanvas = New Canvas
... (Various drawing methods)
objCanvas.Write
Set objCanvas = Nothing
The above code will start a canvas with an initial width of 20 pixels, and an initial height of 20 pixels.
Replace ColourIndex1,ColourIndex2
Finds and replaces all occurances of ColourIndex1 with ColourIndex2
Copy X1,Y1,X2,Y2,X3,Y3
Copies a block from X1,Y1 with endpoints at X2,Y2 to the point at X3,Y3
Flood X,Y
Floodfill an area within the canvas with the current foreground colour index
Polygon X Array,Y Array,Join
Draws a polygon. Two VBScript arrays are passed with X and Y coords. The two arrays must be the same size, and there must be more than one point. Join specifies that the function should close the last part of the polygon automatically.
Line X1,Y1,X2,Y2
Draw a line between X1,Y1 and X2,Y2 using the current foreground colour index
AngleLine X,Y,Radius,Angle
Draws a line of a fixed radius at an angle starting at X,Y. Useful for pie charts. Angles from 0-360.
Rectangle X1,Y1,X2,Y2
Draw a rectangle between X1,Y1 and X2,Y2 using the current foreground colour index
Circle X,Y,Radius
Draw a circle at X,Y using Radius
Ellipse X,Y,Radius1,Radius2
Draw an ellipse at X,Y using Radius1 (width) and Radius2 (height)
Arc X,Y,Radius1,Radius2,Angle
Draw an arc centered around X,Y with Radius1 and Radius2, following clockwise through Angle.
Bezier X1,Y1,CX1,CY1,CX2,CY2,X2,Y2,Points
Draw a Bezier curve between X1,Y1 and X2,Y2 using control points CX1,CY1 and CX2,CY2. Points is the number of points in the line, the more there are, the better the curve.
PieSlice X,Y,Radius,Start Angle,Angle,Filled
Draw a pie slice with the center of X,Y with Radius through Angle. Setting Filled to true fills the slice with the current foregound colour index.
DrawVectorTextWE X,Y,Text,Scale
Draw scaleable text running West->East to the canvas with the font set defined in font.asp. The top left of the text starts at X,Y, the text is scaled from any size, 1 is actual size, 2 is twice the size and so on. 1.5 would be 1.5 times the size etc.
DrawVectorTextNS X,Y,Text,Scale
Draw scaleable text running North->South to the canvas with the font set defined in font.asp. The top left of the text starts at X,Y, the text is scaled from any size, 1 is actual size, 2 is twice the size and so on. 1.5 would be 1.5 times the size etc.
DrawTextWE X,Y,Text
Draw text running West->East to the canvas from the font set provided in font.asp. The top left of the text starts at X,Y and the text is a string variable.
DrawTextNS X,Y,Text
Draw text running North->South to the canvas from the font set provided in font.asp. The top left of the text starts at X,Y and the text is a string variable.
Clear
Clears the canvas using the current BackgroundColourIndex
Resize Width,Height,Preserve
Resizes the canvas to a new Width and Height. To keep the existing image information, send "true" as the preserve parameter, else send "false". NOTE: preserving the image can be a time intensive task as the class has to make a duplicate of the existing image within the new canvas sizes.
Write
Send the canvas information to the Response object, rendering the image.
LoadBMP Filename
Loads a windows bitmap file from disk, requires ADODB 2.5 and higher, does not require the FileSystemObject . This method will destroy any current image settings. Filename is the filepath to load from the server side, ie: C:\InetPub\wwwroot\file.bmp". The bitmap must be uncompressed (no RLE encoding), it must also be of 256 colours but only use the first 128.
SaveBMP Filename
Saves a windows bitmap to disk, requires ADODB 2.5 and higher, does not require the FileSystemObject . Also requires write permissions to the files directory for the IUSR_webservername user. Filename is the filepath to save to on the server, ie: C:\InetPub\wwwroot\file.bmp". NOTE: due to the intensive conversion process, this method can take considerable time to complete.
EncodeBMP
Encodes the current canvas as a bitmap string. Returns an ASCII string.
DecodeBMP Bitmap Data
Decodes a binary string as a bitmap and reconfigures the canvas. This method will destroy any current image settings. Bitmap Data is an ASCII string loaded from a bitmap file. See LoadBMP for the bitmap format restrictions.
WebSafePalette
Resets the colour palette to the standard 216 web safe colours. These colours contain RGB combinations of the numbers 0xFF, 0xCC, 0x99, 0x66, 0x33 and 0x00. Colour index 0 is 0xFFFFFF (White), colour index 216 is 0x000000 (black).
Pixel(X,Y)
Sets/retrieves the pixel colour index at X,Y
GlobalColourTable(Index)
Array. Sets/retrieves the RGB value at Index. To set, use the RGB(red,green,blue) function in VBScript.
LocalColourTable(Index)
Array. Not supported yet.
ForegroundColourIndex
Long. Sets/retrieves the current pen drawing colour index (0-127)
BackgroundColourIndex
Long. Sets/retrieves the current background colour index (0-127)
TransaparentColourIndex
Long. Sets/retrieves the current transparency colour index (0-127)
UseTransparency
Boolean. Includes transparency information with the GIF file
GIF89a
Boolean. Writes a GIF89a format file, needs to be true to include transparency support.
Version
Retrieves the current version of the ASPCanvas object
ImageData
Returns the GIF image data as an 8 bit string of characters
TextImageData
Returns the GIF image data as a VBScript variant/string object. Useful for dumping contents using the FileSystemObject
Width
Long, read-only. Current width of the image.
Height
Long, read-only. Current height of the image.
Comment
String, 255 characters max. Inserts a comment string into the GIF data. Requires GIF89a data.
Practically everyone who has written to me about this product has asked for some kind of compression within the GIF data. This will not be happening any time soon for one clear reason. VBScript is too slow! In order to provide a level of compression (LZW compression in this case) the application needs to manipulate data on a bit by bit level. This includes rotating and shifting byte structures. Although these operations are possible in VBScript, they are are not native to the language and are inherantly slow and cumbersome. The bottom line is that adding compression to the code will increase the processing time considerably , rendering any form of compression useless in terms of balancing processing time and bandwidth.
I have also received several requests for adding a form of image resizing. To enable this to effectively be added to the script it requires two processes - colour mapping and bit manipulations. Both functions are possible in VBScript, but both suffer in terms of available processing time in VBScript. This will not be added to ASPCanvas.
Currently, due to speed restrictions, ASPCanvas only supports 128 colour GIF files (this is because it is faster to write 8 bits per pixel, or 7 bits for colour and 1 bit for a clearcode)
Please bear in mind that too many graphical operations will slow the image rendering, especially resizing the canvas and preserving the existing image. Large images do take a while to be rendered to a GIF file. Hopefully, as version numbers increase, this code will become more efficient!
Previously, this code was encoded using the MS script encoder. This release of the software has not been encoded. This version of the software DOES NOT contains any patented UNISYS LZW algorithms. The GIF's produced in this release of the software are effectively uncompressed. If your version of ASPCanvas contains any portion of the LZW compression algorithm it has been added by a third party.
The following code creates a canvas, and draws a few things (please be careful with the copy and paste functions from your browser to your editing program, sometimes line breaks can go a little stray during translation causing unforseen problems! ):
<!--#include file="canvas.asp"-->
<%
Dim objCanvas
Dim lLastY,lCurrentY
Dim iTemp
Set objCanvas = New Canvas
objCanvas.GlobalColourTable(0) = RGB(255,255,255) ' White
objCanvas.GlobalColourTable(1) = RGB(0,0,0) ' Black
objCanvas.GlobalColourTable(2) = RGB(255,0,0) ' Red
objCanvas.GlobalColourTable(3) = RGB(0,255,0) ' Green
objCanvas.GlobalColourTable(4) = RGB(0,0,255) ' Blue
objCanvas.Resize 160,120,false ' Resize without preserving the image
lLastY = 0
Randomize Time
objCanvas.ForegroundColourIndex = 2 ' Set the pen to red
For iTemp = 20 To 160 Step 10 ' Draw random lines to simulate a graph
lCurrentY = Int(Rnd * 100)
objCanvas.Line iTemp - 10,110 - lLastY,iTemp,110 - lCurrentY
lLastY = lCurrentY
Next
objCanvas.ForegroundColourIndex = 1 ' Set the pen to black
objCanvas.Line 10,1,10,110 ' Draw the graph axis
objCanvas.Line 10,110,160,110
For iTemp = 20 To 160 Step 10 ' Draw the horizontal measures
objCanvas.Line iTemp,110,iTemp,108
Next
For iTemp = 10 To 110 Step 10 ' Draw the vertical measures
objCanvas.Line 10,iTemp,12,iTemp
Next
objCanvas.DrawTextWE 1,115,"Time" ' Annotate the axis
objCanvas.DrawTextNS 1,1,"Volume"
objCanvas.Ellipse 100,100,30,20 ' Draw an ellipse
objCanvas.Circle 50,50,10 ' Draw a circle
objCanvas.Write ' Write the image to the browser
%>
Including the generated images within an HTML page is quite simple, it requires two files, one with the ASPCanvas code such as listed in the section directly above, and another page with the HTML code for the image to be placed in. The ASPCanvas page is then included using the HTML <IMG> tag. An example which uses the code above would be:
<HTML>
<HEAD>
<TITLE>Example ASPCanvas Page</TITLE>
</HEAD>
<BODY>
<TABLE WIDTH=98% BORDER=1>
<TR>
<TD>Cell 1</TD>
<TD><IMG SRC="canvas_code.asp"></TD>
<TD>Cell 3</TD>
</TR>
</TABLE>
</BODY>
</HTML>
In this example, the browser will use the image generated by canvas_code.asp and include it into the table. The browser can tell the type of file from the data generated by the ASP code and will render the image. ASPCanvas actually generates uncompressed GIF files through it's code on the fly, and the browser treats the files as GIF's.
ASPCanvas currently only supports uncompressed GIF's (that is, the GIF's structure is created without the use of the LZW compression algorithm which is patented by UNISYS until 2003). See earlier in this document for reasons why LZW compression will not be implemented. As this code stands, it is not necessary to pay any royalties to UNISYS if you plan to use this in your web implementation.
The following technical information relates to ASPCanvas
GIF output type: GIF87a, non-interlaced
Maximum canvas size: 65535 pixels square
Line drawing method: Bresenham point to point (no mid point problems)
Elliptical drawing method: Bresenham (symmetrical, no mid point problems)
Flood fill method: 4 point NSEW fill, non-recursive
Text type: Bitmap and vector fonts
Boundaries: The upper left of the image is (1,1)
File I/O: Uses ADO's Stream object to load and save bitmaps.
The font.asp file contains the information needed to render bitmap and vector fonts to the canvas. The standard font pack which accompanies this release contains definitions for all characters in the standard ASCII character set from numbers 32 to 126 inclusive. The standard bitmap font size in this pack is defined on a 5x5 grid, but can be expanded by adjusting the font information if need be.
ASPCanvas needs a dictionary object called "Font" to be declared, this contains keys to each letter in the ASCII set, which in turn contains an array of strings with the font information. The declaration of the standard font pack shows the following code:
Dim Font
Dim Letter(5)
Set Font = Server.CreateObject("Scripting.Dictionary")Letter(0) = "01100"
Letter(1) = "10010"
Letter(2) = "10010"
Letter(3) = "11110"
Letter(4) = "10010"
Font.Add "A",Letter
To increase the height of the font pack, change the initial dimensions of the Letter array and add the extra lines to the letter definition. To increase the width, simply add the extra 0's to the arrays strings. Both upper and lower case letters can be added in this way, as the dictionary object is case sensitive with its keys.
Also note that the fonts can support up to 9 colours, the standard font pack will utilise colour index 1. By inserting numbers from 1-9, the rendering engine will use the corresponding index from the GlobalColourTable array.
Vector fonts are supported in version 1.0.3 of ASPCanvas, and can be changed from the same font.asp file. It is similar in many respects to the bitmap fonts from above, but instead of defining a flat bitmap for each character, it uses points to draw lines on the canvas to form a character. To define a vector font set of your own is relatively simple as with the bitmap fonts, you need a dictionary of vector characters containing an array of values. Vector fonts can be of any size and width, the width of each character is worked out by the code when a character is drawn onto the screen. The font pack which comes with this version is designed around the existing 5x5 bitmap font. The declaration of the vector fonts are as follows:
Dim VFont
Dim VLetter()
Set VFont =
Server.CreateObject("Scripting.Dictionary")
ReDim VLetter(8,3)
VLetter(0,0) = 1 : VLetter(0,1) = 5 : VLetter(0,2) = 1
VLetter(1,0) = 1 : VLetter(1,1) = 2 : VLetter(1,2) = 1
VLetter(2,0) = 2 : VLetter(2,1) = 1 : VLetter(2,2) = 1
VLetter(3,0) = 3 : VLetter(3,1) = 1 : VLetter(3,2) = 1
VLetter(4,0) = 4 : VLetter(4,1) = 2 : VLetter(4,2) = 1
VLetter(5,0) = 4 : VLetter(5,1) = 5 : VLetter(5,2) = 1
VLetter(6,0) = 1 : VLetter(6,1) = 4 : VLetter(6,2) = 0
VLetter(7,0) = 4 : VLetter(7,1) = 4 : VLetter(7,2) = 1
VFont.Add "A",VLetter
This example is taken from the font pack and defines the letter "A" (ASCII 65). VFont is a dictionary object which holds definitions for each character, VLetter is used to build an array of values for each point. VLetter is re-dimensioned for each character in accordance to the number of lines necessary to build a character, some characters require more, some less.
The first dimension in the array is the line number and defines the order in which the lines are drawn, the second dimension in the array contains the X, Y and "Pen down" value for the point. In the first line, the X position is 0, the Y position is 5 and the Pen is down from the last point to this current point (as this is the first point, nothing is actually drawn).
You will notice that the 7th line (the line starting with (6,0)) that the pen value is 0, which means that the pen is up and the line from the last point is not drawn. This is useful if you have characters such as "!" where the current position needs to "jump" from one position to the next without drawing anything.
Currently, there is an issue with caching image data from MS IIS servers and MS IE browsers. This consists of the browser assuming that the same filename will contains exactly the same image data if the file is re-used multiple times on a single page. To stop IE from displaying the same image over and over again on the same page, simply add a bogus parameter to the end of the ASP page location. As in the following example:
<imgsrc="test.asp?bogus=1"><imgsrc="test.asp?bogus=2"><imgsrc="test.asp?bogus=3">
This will ensure that the image data is always recalculated.
If you have this option turned on in IIS for the web site which ASPCanvas is running on, the integration between IE and IIS will cause IE to see the ASP page as simply text, and will only render the image as text. Ensure that client-side debugging is disabled in the IIS MMC before testing ASPCanvas. You can find this option in Default Web Site->Properties->Home-> directory->Configuration->App debugging->Enable ASP client-side script debugging.
Due to the different ways in which browsers interpret the MIME types and file extensions from a web server, some non-IE browsers will not render the GIF files directly from an ASP file. It is advised that all images produced by ASPCanvas be rendered through a <IMG> tag within an HTML page. Care has been taken to ensure the correct content disposition of the file is sent to the browser.
There is a likely chance that you maybe mixing the ASPCanvas with HTML code. This is quite a common mistake to make and usually appears with code like this:
<!--#include file="canvas.asp"-->
<HTML>
<HEAD>
<TITLE>Test ASPCanvas page that won't work</TITLE>
</HEAD>
<BODY>
<%
Dim objCanvas
Set objCanvas = New Canvas
... ASPCanvas code
objCanvas.Write ' The HTML headers have already been sent, so this will send garbage to the browser
%>
</BODY>
</HTML>
This simply will not work because GIF code cannot be mixed with HTML. Create two pages, one with the HTML, the other with the ASPCanvas code and then include the ASPCanvas page into your HTML page with the <IMG SRC="canvas_code.asp"> tag.
Please note that the ChiliSoft ASP package does not support VBScript classes, and will not run this script correctly .
There are two reasons why the FileSystemObject is not used for the file I/O on bitmap data:
It seems odd that some ISP's will restrict access to the object in the first place, but then do not restrict the services available through ADO's Stream object. The reasons I have been given in the past are generally along the lines of stopping people reading other peoples shared areas on a shared server, which is fair enough, so in that case they really should be aware of ADO's ability to do the same thing.
With thanks to Tony Stefano, ASPCanvas now contains extra font packs. These are located in the "extra_fonts" folder. Tony has been kind enough to allow me to include these with the current script pack. These are bitmap fonts, with fixed point sizes:
To use a font from the list, copy the file from the "extra_fonts" folder into the same folder as canvas.asp and adjust the first code line in canvas.asp, replacing "font.asp" to the name of the font file you wish to use:
Please be aware that these are bitmap fonts. Replacing the standard font pack will mean that the vector fonts will be unavailable
Chris Read can be contacted using the following e-mail address:
Chris Read is a lead software engineer for a well respected web development company in Australia. He has several years experience in ASP, but has a greater experience (15+ years) in other areas such as medical imaging, operating systems, communications, DSP, data warehousing and also consults companies on their IT needs. He may not be able to answer your questions immediately, but he does care and will help you out if you need assistance (providing you've read the documentation fully!)
If you're looking for someone to hire to do your web work, drop me a line, my rates are reasonable and my services are always professional.
The primary location of this source and documentation is at the following address:
http://users.bigpond.net.au/mrjolly/
Have fun! I'm always looking for suggestions to improve stuff, tell me what's right, and tell me what's wrong!
Changes that will take place eventually:
Nice things, may do if provoked:
Highly unlikely, but you could cross your fingers:
Things that simply won't go into ASPCanvas.
ASPCanvas Copyright (c) 2002, Chris Read. All rights
reserved.
Redistribution and use in source form, with or
without modification, are permitted provided that the following
conditions are met:
-
Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
-
All advertising materials mentioning features or use of this software must display the following acknowledgement: This product includes software developed by Chris Read with portions contributed by Richard Deeming.
-
The name of the author may not be used to endorse or promote products derived from this software without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANT ABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Quite a number of people have written to me asking how they can get information on the various image formats such as GIF, JPEG, PNG and so forth. Most of the information about image formats was gained from several years working with a lot of different formats, but more of the technical information was gathered from the following sites:
The University of Edinburgh 2D image format page - This contains a great deal of information on each image format, including the CompuServe GIF documentation.
The Indiana University Knowledge Base - Good portal for image resources.
These are great places to start looking at graphic image formats.