Whitebeam GraphicImage Class

Subject

The GraphicImage class is part of the core Whitebeam Presentation Engine - running as part of the Whitebeam Apache module. An instance of this class represents a graphical image and then methods on that object manipulate that image.

This document covers the following aspects of using the GraphicImage class :

1. How to create images
2. Dealing with colours
3. Drawing methods
4. Pens and styles
5. Drawing text
6. Other functions
7. Summary

Creating Images

All images are represented by an instance of the GraphicImage class so the first step in any image manipulation is to create an instance of that class :

The object thus created doesn't yet contain an image. You have two ways of getting an image into the object: Load an existing image or create an empty canvas onto which to draw.

New images

The create method creates an empty image of the specified size. Two basic image types are supported :

• true-colour
  This is the default and, as the name implies, allows you to use the full range of 24bit colour (red-green-blue).
• palette
  Palette images have at most 256 colours. For a new image none of the colours are allocated. You add new colours to the palette as required using the colourAlloc and colourResolve methods

Generally it's recommended that you stick with true-colour images.

Loading images

Images can be loaded in one of two ways - either directly from the servers file system, or alternatively from a Binary object.

Both mechanisms use the make method.

    var img = new GraphicImage;

    if (img.make('/images/myimage.gif','images/gif')) {
       // Process image here
    }
  

Note : as with most Whitebeam operations that deal with the file system, the root of the pathname is the 'documentRoot' of the virtual server running your application. You can not access files outside of your virtual server.

Initialising an image from a Binary object is often the result of a user uploading a file on a form. The following example illustrates this :

    // Data posted by the application
    var params = rb.page.formdata();

    if (param.uploadImage instanceof Binary) {
      var img = new GraphicImage;

      if (img.make(params.uploadImage)) {
        // Make a thumbnail - 100x100 pixels
        var thumb = new GraphicImage;
        thumb.create(100,100);

        img.copyRect(thumb, null, {x:0,y:0,w:100,h:100});

        // Thumb nail can now be saved in the file template or the file system.
      }
    }
  

Colours

All methods that deal with colours treat those colours as numbers. How those numbers are generated depends on whether the image in question is true-colour (the default) or colour based image.

Representing colours

The GraphicImage class represents 'colours' using four values. The standard red, green and blue components and an 'alpha' component. The alpha component tells the system how transparent the colour is, and therefore how much of the underlying colour will shine through.

Red, green and blue components have a range of zero (0) through to 255. The alpha value has a range of 0 (opaque) through 127 (fully transparent).

Palette based colours

These image have a limit of 256 distinct colours (the palette). Before you use a colour you have to find a vacant location in the palette. There are two calls to enable you to do this : colourAlloc and colourResolve.

The first of these, colourAlloc, looks for the first unused palette entry and assigns to that entry the requested colour, returning the index to be used in drawing functions. Note that this method does not check whether the requested colour is already set in another slot in the palette! If the palette is full (256 colours all assigned) this method returns -1.

The second option, colourResolve, is more intelligent and arguably the most sensible. Given a requested colour the following steps are taken :

1. A search is made of existing colours. If there is an exact match with the requested colour then that is returned to the application
2. If there is no exact match, but the palette is not full then a new palette slot is allocated for the requested colour and that is returned to the application
3. If there is no exact match and the palette is full then the set of existing colours is compared against the requested colour and the best match is returned to the application

True Colour images

Both colourAlloc and colourResolve can be used to generate a colour for true-colour images. Because of the 24 bit colour range though there is no colour mapping involved. Any colour requested will be allocated. For this reason both routines behave in exactly the same way.

Drawing methods

The GraphicImage class provides routines for drawing points, lines, rectangles and arcs as follows :

• drawPixels
• drawLine
• drawRectangle
• drawPolygon
• drawArc

See the descriptions of each individual method for details.

Pen Styles

A number of the drawing methods use the concept of a 'pen' to render their image. The default pen is a single pixel wide and uses the colour specified in the drawing method call. Two additional methods allow the default pen to be changed in thickness and in how they are rendered, allowing for example dashed lines.

setPenThickness allows the pen thickness to be adjusted. There is a single numeric parameter. Once set the requested thickness remains until set or reset be a subsequent call.

setPenStyle is more complicated but allows aribtrarily complex 'dashed' lines to be drawn. Details for how to do this with an example are in the documentation for the setPenStyle method.

Unlike the pen thickness, which applies to all drawing methods, the 'style' must be specifically requested in the drawing call. This is achieved by setting the colour to the special value of GraphicImage.styled.

Drawing text

A single method allows text to be placed into an image : drawText. This method allows you to use any suitable font-file, for example true-type fonts. Fonts are refered to by the file name of the file that contains the font.

For security reasons you are not permitted to specify any file in the system as the font. You have two options :

• Specify a path to the font
  If you specify a path (the font parameter contains at least one '/') then the parameter identifies a specific font file within your virtual servers document root.
• Specify just the font file name - no path
  If you do not specify a path then the Whitebeam will look in configured 'system' font areas. These may be well know directories (known and compiled into the graphics library) or specified by the 'GDFONTPATH' environment variable

The method description covers other aspects of how to draw text into your image.

Other methods...

The GraphicImage class provides a number of additional methods to manipulate images. These are documented separately and simple listed here :

• clean : delete data stored in this image. Useful if you're manipulating very large images
• write : for sending an image directly to the clients browser
• copyRect : copying and resizing areas of one image into another image
• copyRectRotate : rotate an area of one image into another image
• setClipRegion : Restrict drawing operations to a specific subset of the drawing 'canvas'
• sharpen : apply a sharpenning algorithm to an image

Summary

The GraphicImage library is intended to provide a simple, straightforward means of manipulating images within the Whitebeam Presentation Engine. At the moment most basic operations are supported, we expect the library to be extended over time to incorporate more sophisticated tools.

As usual, comments from users are much appreciated!