AspJpeg 1.2 Programmer's Manual

Copyright (c) 2000 - 2002 Persits Software, Inc.
All Rights Reserved.

This software is based in part on the work of the Independent JPEG Group (IJG)

Your First Thumbnail

To create a thumbnail of a JPEG image using AspJpeg, you should take the following simple steps:
  • Create an instance of the AspJpeg object via Server.CreateObject (or New if used in VB).
  • Open your image file via the Jpeg.Open method.
  • Set new image dimensions via the properties Jpeg.Width and Jpeg.Height. You may use read-only properties Jpeg.OriginalWidth and Jpeg.OriginalHeight to preserve the original width/height ratio.
  • Optional: You may include calls to any or all of the following methods: Jpeg.Sharpen to apply sharpening to the resultant thumbnail, Jpeg.Crop to crop it, Jpeg.FlipV and Jpeg.FlipH to flip an image vertically and/or horizontally.
  • Save the resultant thumbnail to disk via the Jpeg.Save method.

Here is the underlying ASP script:

<% ' Create instance of AspJpeg
Set Jpeg = Server.CreateObject("Persits.Jpeg")

' Compute path to source image
Path = Server.MapPath("images") & "\clock.jpg"

' Open source image
Jpeg.Open Path

' Decrease image size by 50%
Jpeg.Width = Jpeg.OriginalWidth / 2
Jpeg.Height = Jpeg.OriginalHeight / 2

' Apply sharpening if necessary
' Jpeg.Sharpen 1, 130

' create thumbnail and save it to disk
Jpeg.Save Server.MapPath("images") & "\clock_small.jpg"
%>

<IMG SRC="images/clock.jpg"><P>
<IMG SRC="images/clock_small.jpg">

This code snippet opens the image clock.jpg located in the images subdirectory, creates a reduced version of the image, and saves it in the same directory under the name clock_small.jpg. It then displays both images via <IMG> tags.

Opening Images from Memory New in Version 1.2

Starting with version 1.2, AspJpeg offers the method OpenBinary which opens an image from a binary memory source (such as an ADO recordset) rather than a file. You may use this method to create thumbnails from images residing in a database as blobs.
<%
' Using ADO, open database with an image blob
strConnect = "DRIVER={Microsoft Access Driver (*.mdb)};DBQ=" & Server.MapPath("db\aspjpeg.mdb")

Set rs = Server.CreateObject("adodb.recordset")
SQL = "select image_blob from images2 where id = " & Request("id")
rs.Open SQL, strConnect, 1, 3

Set Jpeg = Server.CreateObject("Persits.Jpeg")

' Open image directly from recordset
Jpeg.OpenBinary rs("image_blob").Value

...
%>

The source image for this code sample comes from the table images2 residing in the sample Microsoft Access database located in the folder \Samples\db of the installation.

Setting Resizing Algorithms
AspJpeg supports three popular image resizing algorithms: Nearest-Neighbor, Bilinear and Bicubic.

The Nearest-Neighbor algorithm is the fastest of the three, but produces relatively low-quality thumbnails. The Bilinear algorithm offers a much better quality but is about twice as slow as Nearest-Neighbor. And finally, the Bicubic algorithm provides the highest quality but is approximately twice as slow as Bilinear and, therefore, 4 times as slow as Nearest-Neighbor.

A resizing algorithm for your thumbnails can be specified via the property Jpeg.Interpolation. Valid values for this property are: 0 (Nearest-Neighbor), 1 (Bilinear), and 2 (Bicubic). The default value is 1 (Bilinear). For this property to take effect, it must be set before calling Save.

The following table illustrates the effect of setting the Interpolation property. Notice how much smoother the thumbnails produced by the Bilinear and Bicubic algorithms are in comparison to Nearest-Neighbor. Notice also that in many cases (such as this one) Bicubic provides little, if any, improvement over Bilinear.

Algorithmjpeg.InterpolationEffect
Nearest Neighbor0
Bilinear1
Bicubic2

Image Sharpening
Starting with Version 1.1, AspJpeg is capable of applying a sharpening filter to an image being resized via the method Sharpen. A regular thumbnail and two thumbnails with various degrees of sharpening applied to them are shown below.

No sharpeningSharpen(1, 120)Sharpen(1, 250)

The Sharpen method uses two Double arguments: Radius and Amount. Radius controls the size (in pixels) of an area around every pixel that the sharpening algorithm examines. This argument should normally be set to 1 or 2. Amount (expressed in %) specifies the degree of sharpness. This argument must be greater than 100.

Image Cropping
AspJpeg 1.1+ is also capable of cutting off edges from, or cropping, the resultant thumbnails via the method Crop(x0, y0, x1, y1). The size of the cropped image is specified by the coordinates of the upper-left and lower-right corners within the resultant thumbnail, not the original large image.

Image Flipping and Rotation
With AspJpeg 1.2, you can invert an image horizontally and/or vertically by calling the methods FlipH and FlipV, respectively.

New in Version 1.2 You can also rotate an image 90 degrees clockwise and counter-clockwise by calling the methods RotateR and RotateL, respectively.

Drawing and Writing Text Over Images New in Version 1.2
AspJpeg 1.2+ offers a new property, Canvas which enables you to programmatically write text phrases and draw geometric figures over the image. Text size, font and color, as well as pen width and color are customizable.

The following code sample prints the text "Copyright (c) XYZ, Inc." on an image in red color and Courier New font (size 10) in the upper-left corner. It also draws a 2-pixel-wide black frame around the image.

<%
Set Jpeg = Server.CreateObject("Persits.Jpeg")

' Open source image
Jpeg.Open Server.MapPath("images/dodge_viper.jpg")

' Resizing is optional. None in this code sample.

' Draw text
Jpeg.Canvas.Font.Color = &HFF0000' red
Jpeg.Canvas.Font.Family = "Courier New"
Jpeg.Canvas.Font.Bold = True
Jpeg.Canvas.Print 10, 10, "Copyright (c) XYZ, Inc."

' Draw frame: black, 2-pixel width
Jpeg.Canvas.Pen.Color = &H000000' black
Jpeg.Canvas.Pen.Width = 2
Jpeg.Canvas.Brush.Solid = False
' or a solid bar would be drawn
Jpeg.Canvas.Bar 1, 1, Jpeg.Width, Jpeg.Height

Jpeg.Save Server.MapPath("images/dodge_viper_framed.jpg")
%>

A full description of the Canvas object and its sub-objects (Canvas.Pen, Canvas.Font and Canvas.Brush) can be found in the end of the AspJpeg Object Reference section.

Adjusting Image Compression (advanced users only)
The JPEG format uses "lossy" compression methods. This means that some minor details of an image saved as a JPEG are lost during compression. The degree of loss can be adjusted via the jpeg.Quality property. This property accepts an integer in the range 0 to 100, with 0 being the highest degree of loss (and hence, the lowest quality) and 100 being the lowest degree of loss and highest quality.

The lower the loss, the larger the resultant file size. The property jpeg.Quality is set to 80 by default which provides a close-to-optimal combination of quality and file size. Changing this property is generally not recommended.

AspJpeg Object Reference
AspJpeg Properties
Canvas As Object (read-only)
Returns the Canvas object which, along with its sub-objects Canvas.Font, Canvas.Pen and Canvas.Brush, enables writing and drawing over an image. The full description of the Canvas object can be found in the end of this section.
Expires As Date (read-only)
Returns the component's expiration date. If a valid registration key is installed, returns 9/9/9999.
Height As Long (read/write)
Specifies a new image height (in pixels). Must be called after an image is opened via the Open method.
Interpolation As Long (read/write)
Specifies an image resizing algorithm. The following values are currently supported: 0 (Nearest-Neighbor), 1 (Bilinear, default) and 2 (Bicubic).

The Nearest-Neighbor (NN) is the fastest but provides low-quality thumbnails.

The Bilinear method offers much better thumbnail quality but is approximately 2 times as slow as NN.

The Bicubic method is approximately twice as slow as Bilinear and 4 times as slow as NN, but supposedly offers the highest quality. In many cases, however, it provides little, if any, noticeable improvement over the Bilinear method.

Default: 1 (Bilinear).

OriginalHeight As Long (read-only)
Returns the original image height (in pixels). Can only be called after an image is opened via the Open method. Use this property to preserve the original aspect ratio of an image.
OriginalWidth As Long (read-only)
Returns the original image width (in pixels).Can only be called after an image is opened via the Open method. Use this property to preserve the original aspect ratio of an image.
Quality As Long (read/write)
Specifies the degree of compression loss. Affects the resultant image quality and file size.

Accepts an integer value in the range 0 to 100, 0 being the lowest quality, highest loss and smallest file size. The higher the value the higher the image quality, and the larger the file size.

The property Quality is set to 80 by default which offers a close-to-optimal combination of image quality and file size. Changing this property is generally not recommended.

RegKey As String (write-only)
Specifies the registration key. If this property is not set, AspJpeg looks for a registration key in the system registry.
Version As String (read-only)
Returns the current version of the component in the format "1.2.0.0".
Width As Long (read/write)
Specifies a new image width (in pixels). Must be called after an image is opened via the Open method.
AspJpeg Methods
Sub Close()
Closes a file opened via the Open method. This method is called automatically upon the destruction of the AspJpeg object, so you do not have to call it explicitly, unless there is an immediate need to free the file handle (such as, if you need to delete the file).
Sub Crop(x0 As Long, y0 As Long, x1 As Long, y1 As Long)
Cuts edges off of a thumbnail. For this method to take effect, you must call it before calling .Save.

The arguments (x0, y0) and (x1, y1) are the coordinates of the upper-left and lower-right corners of the desired cropped image within the thumbnail. For example, if the original large image is 300 pixels wide and 200 pixels high, the following sequence will produce a cropped thumbnail which is 60 pixels wide and 40 pixels high:

Jpeg.Width = 120
Jpeg.Height = 80
' Crop 20 pixels from left, 30 from top.
' Make image size 60 by 40.
Jpeg.Crop 20, 30, 80, 70

Sub FlipH()
Flips the resultant thumbnail horizontally. For this method to take effect, you must call it before calling .Save.
Sub FlipV()
Flips the resultant thumbnail vertically. For this method to take effect, you must call it before calling .Save.
Sub Open(Path As String)
Opens a JPEG image for resizing. Path must be a physical path to the image.
Sub OpenBinary(ImageBlob As Variant)
Same as Open, but the image is opened from a binary memory source (such as an ADO recordset) rather than a file. Use this function to resize images residing in a database as blobs, e.g.

Set rs = Server.CreateObject("adodb.recordset")
SQL = "select myimage from images where id = 1"
rs.Open SQL, strConnect, 1, 3

Set Jpeg = Server.CreateObject("Persits.Jpeg")

' Open image directly from recordset
Jpeg.OpenBinary rs("image_blob").Value

...

Sub Save(Path As String)
Resizes the currently opened image using parameters specified by various properties. Save the resultant image thumbnail to a file specified by Path. If a file with this name already exists it will be overwritten.

Sub Sharpen(Radius As Double, Amount As Double)

Sharpens an image. Radius specifies the radius of scanning (in pixels) around each pixel. This argument should normally be set to 1 or 2. Amount specifies the degree of sharpness (in %). This argument must be greater than 100. For this method to take effect, you must call it before calling .Save.
Sub RotateL
Rotates the image 90 degrees counter-clockwise. This method also causes the properties Width and Height to switch values. For this method to take effect, you must call it before calling .Save.
Sub RotateR
Rotates the image 90 degrees clockwise. This method also causes the properties Width and Height to switch values. For this method to take effect, you must call it before calling .Save.
Jpeg.Canvas Object Description
Property/MethodDescription
Canvas.Brush.Color As Long Specifies a brush color, e.g. &HFF0000 for red. 0 (black) by default. Affects the inside areas of a bar, circle, ellipse and arc, unless Brush.Solid is set to False.
Canvas.Brush.Solid As Boolean Specifies whether a brush is solid or transparent. True by default.
Canvas.Font.BkColor As Long Specifies a font's background color. Font.BkMode must be set to anything other that "transparent" for this property to take effect.
Canvas.Font.BkMode As String "Transparent" by default. If set to any other value, the font's background is colored with Font.BkColor.
Canvas.Font.Bold As Boolean Specifies whether a bold font should be used. False by default.
Canvas.Font.Color As Long Specifies font color, e.g. &H00FF00 for green. 0 (black) by default.
Canvas.Font.Family As String Specifies font family such as "Arial" or "Courier New". A system-default font is used if this property is not specified, or the specified font is not found.
Canvas.Font.Italic As Boolean Specifies whether an italic font should be used. False by default.
Canvas.Font.Rotation As Long Specifies text rotation angle (in degrees, rotation is counter-clock-wise). 0 (horizontal) by default.
Canvas.Font.ShadowColor As Long Specifies the color of a text shadow, if present.
Canvas.Font.ShadowXOffset As Long Specifies horizontal offset of a text shadow, in pixels. 0 by default (no shadow).
Canvas.Font.ShadowYOffset As Long Specifies vertical offset of a text shadow, in pixels. 0 by default (no shadow).
Canvas.Font.Size As Long Specifies font size, in pixels.
Canvas.Font.Underlined As Boolean Specifies whether an underlined font should be used. False by default.
Canvas.Pen.Color As Long Specifies a pen color, e.g. &HFF0000 for red. 0 (black) by default. Affects the color of a line, bar, circle, ellipse and arc.
Canvas.Pen.Width As Long Specifies a pen width. Affects the width of a line, bar, circle, ellipse and arc.
Canvas.Arc(X, Y, Radius, StartAngle, ArcAngle) Draws an circular arc with a center in (X, Y). The arc radius is specified by Radius (in pixels). StartAngle specifies the angle of the arc's starting point, and ArcAngle specifies the arc's span. Uses the current pen and brush.
Canvas.Bar(Left, Top, Right, Bottom) Draws a rectanle specified by the coordinates of its upper-left and lower-right corners (in pixels) using the current pen and brush.
Canvas.Circle(X, Y, Radius) Draws a circle specified by its center coordinates and radius (in pixels) using the current pen and brush.
Canvas.Ellipse(Left, Top, Right, Bottom) Draws an ellipse specified by the coordinates of its bounding rectangle (in pixels) using the current pen and brush.
Canvas.Line(Left, Top, Right, Bottom) Draws a line specified by the coordinates of its starting and ending points (in pixels) using the current pen.
Canvas.Print(X, Y, TextString, Optional Language) Prints TextString starting at (X, Y) using the current font.

Language is an optional parameter which should be used when TextString is in a language other than US ASCII. Valid values are:

0 (ANSI_CHARSET)
1 (DEFAULT_CHARSET)
2 (SYMBOL_CHARSET) 2
128 (SHIFTJIS_CHARSET)
129 (HANGEUL_CHARSET)
134 (GB2312_CHARSET)
136 (CHINESEBIG5_CHARSET)
255 (OEM_CHARSET)
130 (JOHAB_CHARSET)
177 (HEBREW_CHARSET)
178 (ARABIC_CHARSET)
161 (GREEK_CHARSET)
162 (TURKISH_CHARSET)
163 (VIETNAMESE_CHARSET)
222 (THAI_CHARSET)
238 (EASTEUROPE_CHARSET)
204 (RUSSIAN_CHARSET)
77 (MAC_CHARSET)
186 (BALTIC_CHARSET)