This is more of a reference document than anything else, I suggest just skimming through this briefly to get a rough idea of what it is, then delving into a couple of examples. In particular, there is an example supplied in the ASPCanvas archive which covers some of the basics as well as a couple of enhanced features. Above all, if you get stuck send me a mail using the above address, I'll always be happy to help.
ASPCanvas is a means of generating GIF images on an IIS/ASP based server without installing server-side COM objects or fiddling around with client-side Java. It is a purely VBScript class which generates GIF images of any size on the server and passes them onto the web browser client.
Things that have been improved:
On top of this, a few things have been added to the pot:
ASPCanvas works by generating a virtual canvas in memory, drawing to it using its own functions and then generating a binary GIF file which is sent to the web browser. The class manages the pixels and also the colour palette. The generated file is sent in an "uncompressed" mode.
Normally, GIF files employ the LZW compression algorithm to compress the file size. This is a lossless algorithm which works well with binary data. Unfortunately, it can be quite time consuming to compress data in languages such as VBScript because of the lack of binary manipulation functions.
Instead, ASPCanvas tricks the LZW decompression software into thinking that the GIF file is compressed by strategically manipulating the internal compression tables. Essentially what is saved is 7-bit uncompressed data from the image. This results in larger file sizes (most of the time the file size is larger than the bitmap), but at the end of the day you get a W3C compliant image from an ASP script!
The requirements have changed very slightly from version 1.0.x to this version of the script, so pay very careful attention before overwriting your previous version!
These are all important as the internals of ASPCanvas have changed to utilise ADO Streams
Also note that this class will still NOT work under ChiliSoft's ASP package.
Copy canvas.asp and font.asp to your web server. If you require the barcode support, copy the required barcode format along with it. There is a collection of extra fonts that accompany this script and can be used to replace the default font. The folder to which the scripts are copied to must have the correct permissions for running ASP scripts.
I feel at this point that it is important to explain what this class should do, the thing you have to understand is this: You cannot mix image and HTML within a single file, this is not how gateway scripts work. If you want to show an image on an HTML page, you make 2 files, one with the HTML containing a <IMG SRC="image.asp"> tag, and the other file with the canvas code. The canvas code should not send HTML or any text for that matter to the browser.
OK, with that explanation out of the way, lets see a quick example of creating an image and sending it to the browser:
Lets explain what this code is doing in more detail. The first line is what is called a Server-Side-Include, or SSI for short. As an ASP developer you should have seen one of these before, so that's pretty straight forward. One thing to note is that if you want to use the text functions in ASPCanvas, you'll need to include the font.asp pack as well. The same applies to the barcode packs.
The next few lines declare objCanvas and create a new instance of the Canvas class. ASPCanvas is written as a VBScript class, that means that you can create as many canvases as you like (within the limits of VBScripts memory space).
Below this are two lines which assign values to objCanvas.GlobalColourTable,
this is an array of colour values (there are 256 spots, but only the first 128
are actually used by ASPCanvas). Each colour is given and indexed value within
this array when drawing. GIF files only support 256 colours, unlike other image
formats like JPG or PNG which can support millions of colours within the same
image.
To use colours within your image you need to build a palette of Red Green Blue (RGB) values in this way so that they can be referenced by ASPCanvas
The next two lines set the BackgroundColourIndex and ForegroundColourIndex
properties. These numbers correspond to the indexes of colours in the GlobalColourTable
The following line sets the width and height of the image. The third parameter is used to preserve any existing image information on the canvas. In this case we don't care for existing information, so we send False. This makes the resizing a little quicker because it doesn't have to copy the old information
OK, down to business! Draw a circle at position 160,120 with a radius of 110
pixels! This is drawn using the colour speficied in the ForegroundColourIndex
property
Last, but not least, we send the image to the browser using objCanvas.Write
Now, if you've saved this example to an ASP file somewhere on your server, with all the SSI's in the right location, you will be able to call the page using your browser. If you're successfull, you'll see a circle, if not, well, try again.
That's it in a nutshell. Once you understand how the canvas works in this way, then it becomes very easy to draw things like graphs, charts, barcodes, labels, rounded corners, security codes and other snazzy graphics.
Returns a string containing the current version of ASPCanvas
Replaces one colour index in the image with another index. NOTE: Slow to process!
Copies a rectangle of the screen defined by X1,Y1-X2,Y2 to position X3,Y3
Floodfills the image starting at X,Y with the current ForegroundColourIndex colour. NOTE: Slow to process!
Same as Flood but does not contain any boundary checks for the bitmap, which makes it faster. USE WITH CAUTION! Make sure that the object you are flooding does not contain any cracks in the shape to fill, otherwise runtime errors will occur!
Draws a multi-sided polygon from an array of X and Y points in aX and aY. The Join parameter will tell Polygon to join the last point in the array with the first, completing the shape.
Draws a regular polygon centered on lX,lY using lRadius with lSides, tilting the polygon at lAngle
Draws a regular star (every second point is skipped) centered on lX,lY using lRadius with lSides, tilting the star at lAngle
Draws a "slice" of pie on the canvas, the center of the pie is at X,Y. The StartAngle and ArcAngle define the sweep of the slice, and the Filled parameter will make the pie slice solid with the current ForgroundColourIndex. The last parameter uses the FloodFill method, so it can be slow!
Draw a Bezier curve between points X1,Y1 and X2,Y2 using the Bezier modification points CX1,CY1 and CX2,CY2. Point count specifies the "granularity" of the line, the more points, the higher definition of the line.
Draw an arc centered around X,Y with two elliptical radii sweeping from StartAngle through to ArcAngle
Draws a line using pseudo-polar coordinates, starting at X,Y and travelling at Angle through Radius
Draws a straight line from X1,Y1 to X2,Y2
Similar to the Line method, with the addition that this can draw a line following a supplied pattern. sPattern is a string containing an order of colour indexes with which to draw a line. For example "01" will draw a line alternating between colour index 0 and 1 for the lines entire length, and "01234" will draw a line using colour indexes from 0 to 4, repeating
Draws a rectangle from X1,Y1 to X2,Y2
Same as Rectangle, with the exception that this is filled with the current ForegroundColourIndex. This does not use the FloodFill algorithm and is very fast
Draw a circle centered around X,Y
Draw an ellipse centered around X,Y with two radii
Draw text from left to right starting at X,Y. The Size parameter defines the width and height of the text. To make the text twice the normal size, specify 2, three times specify 3 etc.
As with DrawVectorTextWE, this draws text from the top to the bottom
Draw bitmapped (fixed size) text at X,Y from left to right
Draw bitmapped (fixed size) text at X,Y from top to bottom
Return the pixel width of the text running WE with the current font
Return the pixel height of the text running WE with the current font
Return the pixel width of the text running NS with the current font
Return the pixel height of the text running NS with the current font
Clear the canvas using the current BackgroundColourIndex
Resize the image. The preserve parameter indicates that any image currently on the canvas will be preserved
Write the image and appropriate information to the browser
Write the image as a Windows bitmap file
Provides the raw data of the image prior to sending to the browser. Useful for storing in a database
Loads a Windows Bitmap file into the current canvas. The existing image is overwritten and the colour palette is replaces with the bitmaps. Bitmap files MUST by uncompressed with 256 colours only. Images must only use the first 128 colours to work correctly
Saves a Windows Bitmap to a file. You must have appropriate permissions on the folder to perform this action
Parses a BMP file from a text ADO stream (the type must be text, the charset must be x-ansi)
Saves a GIF to file using sFilename
Produce text to create a custom font pack (see the section on creating your own fonts)
Force the palette to a 128 colour palette, remaps colours in the image to match
Loads the standard web-safe palette into ASPCanvas's palette. This will destroy the current palette.
Sets or retrieves the current pixel colour index value at X,Y
Sets or retrieves the current pixel colour index value at X,Y, this is faster because it does not perform and boundary checking. Use with caution!
Retrieves the image width
Retrieves the image height
Array of red/green/blue values for the images colour palette
Index value for the current background colour
Index value for the current pen colour
Index value for the transparent colour. Used in conjunction with UseTransparency when saving GIF's
Saves the image with a transparent colour index. This means that the browser will make the selected index colour transparent on the web page
You can add a comment into your GIF file of up to 255 characters in length
True/False. Write any errors to the Response object
True/False. Write any errors to IIS's log
Halt the script on any error
Send errors to a new image instead of the response object, enables you to view errors in images from the actual page with the img link
Included with version 2.0.0 of ASPCanvas is a suite of barcoding classes. Currently, there are four major types of barcodes supported, Code 3 of 9, Code 3 of 9 extended, Code 128 and non-interleaved 2 of 5.
These are included as seperate class files for inclusion into your application. This gives you the best flexibility
Please be aware that I will not supply any technical support with these barcoding classes.
PLEASE TEST THE CODES WITH YOUR OWN EQUIPMENT BEFORE COMMITTING YOUR APPLICATION TO THE PRODUCTION OF BARCODES!
The following is an example of how to include barcodes into your ASPCanvas project:
This is preliminary support. I have only tested these barcodes on one scanner so far. If you are able to confirm that these codes work/don't work with your scanner, please send me the information on your scanner make/model
Each barcode class supports a handful of different properties and methods:
As of version 2.0.2 of ASPCanvas, some new classes were added to enhance the existing functionality. These are classes designed to simplify the graphing and reporting aspect, which is currently the most common usage for this script.
When you unpack the initial ASPCanvas package, you will see a charts folder containing several ASP files. These contain classes which can be added to your ASPCanvas project to provide flexible and instant graphs and charts.
ASPCanvas comes with the following classes:
The following information will show how to create graphs and charts using these classes, including examples
This is a generic charting class which can produce scatter or line charts with 2 axis. The class contains methods and properties to control the axis formatting, dataset formatting and legend positioning and formatting. All elements on the graph can be hidden or shown.
Along with this main class there are two smaller classes which store information about the datasets. These are the ValueSet and Point class. The following is available for the Point class:
And for the points class there are only two properties
An example of how to use this class:
This is a generic bar charting class which can produce bar charts with 2 axis. The class contains methods and properties to control the axis formatting, dataset formatting and legend positioning and formatting. All elements on the chart can be hidden or shown.
Along with this main class there are two smaller classes which store information about the datasets. These are the ValueSet and Point class. The following is available for the Point class:
And for the points class there are only two properties
An example of how to use this class:
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:
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:
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.
FontMaker is a small utility which can be used to create bitmap fonts from any of the standard Windows fonts
The utility is located in the fontmaker folder within the ASPCanvas archive. To use this, install the aspcanvas archive folder onto your web server. Ensure that the fontmaker folder contains at least the following two files:
Also make sure that canvas.asp is located in the folder above (either that or edit fontmaker.asp so that the SSI points to the right location on the server
In your web browser, run the fontmaker.asp file from the web server. The page will give you an ASCII character set with which you can copy the needed text, it will also prompt you for the file of an uncompressed, 128 colour windows bitmap file for it to load which contains a correctly formatted text image. There is an example in the supplied fontmaker folder.
The bitmap file must have the following attributes:
It doesn't matter how far apart each letter is in the bitmap, as long as the gaps are filled correctly as per the example.
Select the file to upload using the Browse... button, give a width for the space character in pixels, specify a pixel border (if any) to give to each character. Then press "Create Font Pack".
If everything is set correctly, a second text area will appear with the source code for the font pack. You now need to copy this text into an ASP file and it can now be included at the top of you ASPCanvas drawing page instead of the normal font pack.
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:
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:
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.
Due to the way in which ASPCanvas 2.0 internally renders its bitmap, it has become necessary to make sure that certain conditions are met if you are developing for a different Locale ID other than English. It is advised that the LCID of the Session object be set to the value 1033 (US English) for just the image generation page. This ensures that ADO will interpret the x-ansi stream correctly without any character conversions.
If you are attempting to use the LoadBMP method within ASPCanvas and get nothing but garbled image information, there is a likely chance that the image uses colour indexes greater than 127. ASPCanvas will only render the first 128 colours in the BMP palette due to the way in which it creates the GIF file. To fix your image so that it loads correctly, load it into a paint package such as Paint Shop Pro or Photoshop and reduce the number of colours to 128. This will re-index the colours so that it uses only the first 128 colours in the palette. Then expand the colours back to 256 and re-save. Another way of fixing this problem temporarily is to use the TruncatePalette method which will 'fix' the palette so the image does display. However, this method will not provide corrected colours for indexes greater than 128.
Please note that the ChiliSoft ASP package does not support VBScript classes, and will not run this script correctly
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:
The primary location of this source and documentation is at the following address:
http://users.bigpond.net.au/mrjolly/
Pretty much all of this is written by Chris Read, but portions of the code have been kindly donated by the following people:
I feel that I should insert a 'thank you' to the literally thousands of people who have sent me mail about ASPCanvas. I had no idea that this component could be so useful to so many people out there. I respond to every mail I receive and I'm always happy to see the end result of utilising ASPCanvas in a larger project. Your support is always welcome!
ASPCanvas Copyright (c) 2003, Chris Read. All rights reserved.
Redistribution and use in source form, with or without modification, are permitted provided that the following conditions are met:
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:
This contains a great deal of information on each image format, including the CompuServe GIF documentation.
Good portal for image resources.
Contains a wealth of information about some of the basic barcode formats
Generates example barcodes on the fly. Great for comparing results. They also do 2D barcodes.
These are great places to start looking at graphic image formats.