csImageFile Version 8.5 - Online Manual

Introduction

These instructions are also available in pdf format. We recommend using the PDF version if a printable manual is required.

This is a COM object that enables images of various formats to be created, resized or edited. It is a non-visual component developed for server side scripting, especially Active Server Pages, and functionality allows dynamically produced images to be sent straight to the browser. It can also be used by other COM enabled tools including Cold Fusion and ASP.NET.

A free, fully functional trial version of csImageFile is available. This trial version has a built in expiry date that causes most of the functions to stop working after that time. This is the only difference in functionality between the trial and full versions. This means that you can fully test if this component is suitable for your application before considering whether to license the full version.

Version 8 is supplied as two different DLL files. One is 32 bit and the other 64 bit. Refer to the next section for more details of registration and component instantiation.

Using these Instructions

These instructions are divided into a number of sections with the relevant methods and properties described in each. There are quick links to some sections below. A full Table of Contents is available on the next page and an index listing all commands in alphabetical order is included at the back for easy reference. The PDF version also has bookmarks for direct navigation to each heading.

Click on one of the links below to go directly to the section of interest:

Table of Contents

1. Registering the Component and Getting Started

1.1. Registration and Server Permissions

Before the component can be used the DLL file, must be registered on the server. This can be done using the command line tool REGSVR32.EXE. Take care to use the correct version of this tool as there is a 64 bit version in the Windows\System32 folder and a 32 bit version in the Windows\SysWOW64 folder. The syntax is:

regsvr32 dllname

where dllname is the path and name of the DLL to register.

There will be two DLL files supplied in the zip archive, one for 32 bit systems and one for 64 bit. The 32 bit file is called csImageFile.dll (csImageFileTrial.dll for the trial version). The 64 bit file is called csImageFile64.dll (csImageFile64Trial.dll for the trial version). The 64 bit file cannot be used on 32 bit systems. Chestysoft has a free utility that performs this function through a Windows interface instead of using regsvr32. This tool can be downloaded from the Chestysoft web site: www.chestysoft.com/dllregsvr/default.asp.

We suggest creating a folder specifically for component dlls rather than using the Windows System folder as this makes them easier to manage and avoids the naming confusion on 64 bit systems.

The application that uses the component must have permission to read and execute the DLL. In a web application like ASP this means giving the Internet Guest User account Read and Execute permission on the file. This account must also have the appropriate permissions for file handling. Read permission is required to read/open an image from disk. Write permission is required to create a new file and Modify is required to edit or delete an existing file. These permissions can be set in Windows Explorer and applied to either a folder or individual files.

1.2. Object Creation

In any script or programme that uses the component an object instance must be created. The syntax in ASP is as follows.

For the full 32 bit version:

For the trial 32 bit version:

For the full 64 bit version:

For the trial 64 bit version:

In each case the object name is "Image", but any variable name could be used.

1.3. The Trial Version

The trial version of the component is supplied as a separate DLL called csImageFileTrial.dll (or csImageFile64Trial.dll). This trial version is fully functional but it has an expiry date, after which time it will stop working. The object can still be created after the expiry date but it cannot load or create images.

The expiry date can be found by reading the Version property.

Version - String, read only. This returns the version information and for the trial, the expiry date.

Example:

Visit the Chestysoft web site for details of how to buy the full version - www.chestysoft.com.

1.4. Using csImageFile with Component Services

A COM component can be added to a COM+ Application in Component Services. One reason to do this is to be able to run a 32 bit DLL on a 64 bit system. Another is to specify a Windows account to use the component to allow that component to access network files that would be unavailable if the component was called by the default internet guest user.

An online description of configuring Component Services is available here:

https://www.chestysoft.com/component-services.asp.

On Windows 2008 and later it is necessary to “Allow intrinsic IIS properties” in the COM+ component properties. csImageFile will run without this but some of the utility functions and the StreamToBrowser method require IIS intrinsic properties.

1.5. System Requirements

Version 8.0 does not support earlier Windows operating systems. It requires Windows 2003 or later for a server or Windows XP or later for a desktop. It will not register or run on Windows 2000. We can still provide version 7 for any users of an older operating system.

2. Import and Export of Images

An image must be loaded into memory if it is to be processed in some way or converted to another format. Images can be loaded from disk, from a variant array variable (which may be a database field or a file uploaded through our csASPUpload component), from a remote URL or by using the handle to a Windows bitmap.

The image in memory can be exported by saving to disk, or as a variant array variable (which may be sent to the browser using the ASP Response.BinaryWrite function, or saved into a binary database field). The image can be exported using the Windows bitmap handle and this is an efficient way of copying images between instances of csImageFile.

Supported file formats are BMP, GIF, JPG, PCX, PNG, PSD, TIF and WBMP. Images can be exported to PDF format. Some description of these formats is provided in Section 14.

2.1. Methods for Import and Export

ReadFile Path - This loads an image into memory from disk where Path must be the full physical path and filename of the image.

Example:

WriteFile Path - This saves the current image to disk, where Path is the full physical path and filename of the new file. The file extension determines the format used and it must be one of the supported formats. It can be a different extension to that of the original file and this is how images can be converted between formats.

ReadVariant FileData - This reads an image into memory from binary data. FileData must be a variant array containing the file information in one of the supported image formats. The variant array (or OLE Variant) is an ActiveX data type commonly used in ASP but it is not supported in all programming environments. ReadVariant may be used to read from our csASPUpload component, another instance of csImageFile, a VBScript variable or a binary database field.

Example of reading a file directly from csASPUpload:

This will read the file from the csASPUpload object called "Upload" assuming it is the first file in the array, or the only uploaded file. If the file is not a valid image it will generate an error.

Example of reading a file from a binary database field:

The data must first be passed to a VBScript variable before the ReadVariant command will accept it. The field name is called "Image" and the recordset is called "RS".

ReadStream ImgType, FileData - This command has been replaced by ReadVariant although it is still supported to retain compatibility. FileData is the image as a variant array variable and ImgType is a string containing the extension of the file format, e.g. "jpg", "bmp" etc. ReadStream could be used if it is important to verify that a file is in a particular format.

ReadURL URL - This loads an image into memory from a remote web server where URL is the location of the image complete with the protocol prefix "http://" or "https://". Version 5 of csImageFile will read the image if it is in a supported format regardless of the extension or content type. A username and password can be sent with the request by setting the URLUsername and URLPassword properties before calling ReadURL. The user agent request header can be specified by setting the HTTPUserAgent property before calling ReadURL. The timeout for ReadURL, in seconds, is specified by the HTTPTimeout property, which defaults to zero, or unlimited. If any characters in the URL are escaped they can be unescaped by setting the HTTPUnescapeURL property to true. The default value is false.

Note that if the computer running the script is connecting to the internet through a proxy, csImageFile must be added to a COM+ Application as described in Section 1.4. If a firewall is restricting which applications are allowed to access the internet it is "inetinfo.exe" which must be given permission for a script running in IIS. Refer to your firewall documentation for more information.

DPMToDPI(dpm) - Integer return value. Converts a dots per metre value, dpm, to dots per inch. dpm is an integer.

DPIToDPM(dpi) - Integer return value. Converts a dots per inch value, dpi, to dots per metre. dpi is an integer.

2.2. Properties for Import and Export

The following properties are related to the import and export of images and they include general properties such as Width, Height and DPI. Some are specific to certain formats such as JpegQuality and ProgressiveJpeg. Some are set when the image is read or created while others can be set before export to alter some feature of the image.

Height - Integer, read only. The height of the currently loaded image in pixels. This is read only. To change the size use Resize, Scale or ResizeFit.

Width - Integer, read only. The width of the currently loaded image in pixels. This is read only. To resize the image use Resize, Scale or ResizeFit. To check if an image is loaded in memory, test for either the Width or Height having a non zero value.

ColorDepth - Integer, must be 1, 4, 8 or 24. This is the bits per pixel for the current image where 1 bit is a 2 colour image, 4 bit is 16 colours, 8 bit is 256 colours and 24 bit is 16 million RGB colour. These are the only colour depths supported by csImageFile. The property is set when an image is imported and it defaults to 24 for an image created with NewImage. ColorDepth can be edited. Reducing the colour depth may reduce the memory requirement of the image while some image processing requires a 24 bit setting. Use ConvertToBW to convert to 1-bit black and white.

DPI - Integer. The pixel density of the image in dots per inch. csImageFile has one property for the pixel density so setting DPI sets both X and Y pixel density and when an image is loaded it is the X pixel density that sets the property. Note that GIF and WBMP images do not use this property and it is an optional extension for PNG.

When an image contains Exif data which includes the XResolution and YResolution tags, these values are changed when the DPI property is changed. This was introduced in version 5.

YDPI - Integer, read only. This will return the vertical pixel density but it is read only. It is not possible to save an image with csImageFile and set different values for horizontal and vertical pixel densities.

JpegQuality - Integer in the range 1 to 100. This determines the amount of compression used when an image is exported in JPEG format. A high value is a high quality, large file size. Saving files with a lower value for JpegQuality is one method of reducing file size but it does reduce image quality. (Default = 90)

ProgressiveJpeg - Boolean. If true a JPG will be saved using progressive compression instead of baseline. This property is set when a JPG is loaded. (Default = false)

JpegGrayScale - Boolean. JPG images can be stored in an 8-bit greyscale format and this property is set when a JPG is loaded. Setting JpegGrayScale to true will convert a colour image to 8 bit greyscale and it will be exported in this format if saved as a JPG. (Default = false)

JpegHigherSpeed - Boolean. When set to true any JPG will be loaded using a reduced colour depth. The image will load at a higher speed at the expense of some image quality. Set the property before calling ReadFile, ReadVariant or ReadURL. (Default = false)

TransparentColor - String, as a six character "RRGGBB" colour. This is used as the transparent colour when an image is exported in GIF or PNG format, if the Transparent property is set. TransparentColor is set when a GIF or PNG image with transparency is loaded. TransparentColor is used in the merge functions when foreground transparency is used. It also determines the background colour of rotations that are not multiples of 90 degrees and when the Crop method is used to enlarge the image area. (Default = white, "FFFFFF")

This property was called BGColor in versions of csImageFile earlier than 6.2. BGColor can still be used but it always takes the same value as TransparentColor.

*** Note *** Colours in csImageFile are always specified as a string value, in the same way as HTML. For example, red is "FF0000" and blue is "0000FF". These strings are not case sensitive and any leading "#" character will be automatically removed.

Transparent - Boolean. When true any image output in GIF or PNG format will contain a transparent colour and this colour is specified by TransparentColor. This property is set when a GIF or PNG is loaded. Transparent is also used in the merge functions to allow foreground transparency. (Default = false)

FileSize - Integer, read only. This is the size of the image in memory when it was first loaded from disk or a binary variable.

OriginalimageType - Integer, read only. When an image is loaded this property is assigned an integer value to represent the format of that image. It can be used to identify the format if the image was loaded with ReadVariant or ReadURL, or if the original file was saved using the wrong extension. The possible values are: -1 - no image loaded, 0 - BMP, 1 - GIF, 2 - JPG, 3 - PCX, 4 - PNG, 5 - WBMP, 6 - PSD, 7 - TIF.

IgnoreInputFileType - Boolean. csImageFile after version 5 can read an image that has the wrong extension, and this is the default behaviour. Set IgnoreInputFileType to false to raise an error if an image format does not match the extension. (Default = true)

OverwriteMode - Integer, must be 0, 1 or 2. Used with the WriteFile method to determine what to do with duplicate file names. The default is 0 and this causes files to be saved with the name specified in WriteFile, even if a file by that name already exists. 1 will prevent WriteFile from saving a file if the file name exists. 2 to will cause the file to be renamed if the name is already used and ~n is added to the end of the name where n is the lowest available number. A typical use of OverwriteMode is to set it to 2 when reading in files from our csASPUpload component to prevent deletion of duplicate file names. (Default = 0)

OverwriteChr - String. If OverwriteMode is set to 2 and a numbered suffix is added to the file name the value of OverwriteChr is used to separate the file name and the suffix number. The default is "~" but sometimes URLs containing this character are blocked for security reasons. (Default = "~")

FileName - String, read only. After saving a file with WriteFile the full path and name actually used for the file is stored in this property. This may be different from the path specified if OverwriteMode is used.

NewFileSize(Type) - Integer, read only. This is the file size that will be produced if the current image is exported in the format specified by Type. Type must be the string value "jpg", "bmp", "png", "pcx", "psd", "gif", "tif" or "wbmp".

WasCMYK - Boolean, read only. This gets set to true if a JPG, TIF or PSD image is read in CMYK format. It indicates that the image has been converted to RGB.

2.3. Properties for Binary Image Export and Streaming

The following properties return the current image as a variant array, which is the format used by the ASP Response.BinaryWrite command. They are used to stream an image to the browser, as described in more detail in Section 10. This format can also be used to copy an image into a binary database field. Not all programming environments support the variant array data type.

A separate property is used for each supported image type.

JPGData - Variant array, read only. The image in JPG format.

Example of sending a JPG to the browser:

This would be used inside a script that is called from inside a <img> tag, as described in Section 8.

GIFData - Variant array, read only. The image in GIF format.

Example of saving a GIF into a binary database field:

This assumes the binary database field is called "ImageField" and that the recordset is called "RS".

BMPData - Variant array, read only. The image in bitmap format.

PNGData - Variant array, read only. The image in PNG format.

TIFData - Variant array, read only. The image in TIF format.

PCXData - Variant array, read only. The image in PCX format.

PSDData - Variant array, read only. The image in PSD format.

WBMPData - Variant array, read only. The image in wireless bitmap format.

PDFData - Variant array, read only. The image in PDF format.

Version 8.0 introduced a single method for streaming to the browser, taking a string parameter to specify the file type.

StreamToBrowser (ImgType) - Streams the current image to a browser where ImgType is the string value "jpg", "bmp", "png", "pcx", "psd", "gif", "tif" or "wbmp". This is used instead of Response.BinaryWrite but Response.ContentType must still be set. This uses the ASP Response object so it can only be used in classic ASP scripts.

Example of sending a JPG to the browser:

StreamToBrowser should be used for larger files because it buffers the data into smaller blocks than BinaryWrite. Note that not all image types can be displayed in a browser.

The following property is used for import and export .

BMPHandle - Integer. The Windows handle of the image stored in memory. This can be used to exchange images with other COM enabled tools, such as Visual Basic, but it is also an efficient way to pass an image between instances of csImageFile. Reading the property returns the handle to a copy of the image so any modifications done to the exported image do not affect the image in memory.

Example of copying images between instances of csImageFile:

This copies the image from an instance called Image2 to the instance called Image1. It does not copy any of the properties, such as DPI, Transparent or any of the metadata. Use ReadVariant with one of the above properties to copy the image and the associated properties.

2.4. TIFF Compression and Multipage Support

This section mostly applies to TIF files, except for ImageCount, ImageCountBinary and ReadImageNumber, which can also be used with GIFs.

CompressionType - Integer, must be 0, 1 or 2. This specifies the compression type that will be used when a TIF file is saved. 0 is no compression, 1 is Packbits compression and 2 is Group 4 compression, which can only be used on black and white images. If a colour image is saved as Group 4 (CompressionType = 2) it will be converted to black and white if it is not already. CompressionType is set when an image is loaded. (Default = 0)

CompressionType can also take the values 3 and 4 when a TIF is loaded and these indicate that the original compression was Group 3 and LZW respectively. csImageFile does not save TIFs using these compression types and attempting to do so will result in Group 3 compression saved as Group 4 and LZW compression saved as Packbits.

The TIF format allows for multiple images, or pages, to be saved in a single file. This is most commonly used with black and white images that have been scanned or faxed but it can be used with any TIF images. csImageFile provides functionality to count the number of pages, extract a specified page, or manipulate the pages within the file.

ImageCount (FileName) - Integer property, read only. This returns the number of images contained within a file. FileName is a string and must be a complete physical path to the file, including the file extension. Note that reading of multiple images is currently only possible with TIF and GIF files, so for other files this function will normally return the value 1. FileName can alternatively be a remote URL, beginning with "http://".

ImageCountBinary (ImageData) - Integer property, read only. This returns the number of images contained within a TIF or GIF stored in the variant array variable, ImageData. It could be used when the image is stored in a binary database field or after uploading with our csASPUpload component.

ReadImageNumber - Integer property. Specifies the image that will be read from a TIF file or variant array in TIF or GIF format, containing multiple images. This property is used by the ReadFile, ReadURL and ReadVariant methods, as well as the merge functions. (Default = 1).

Example of reading the last page from a multipage TIF:

In summary the number of pages is found using ImageCount or ImageCountBinary. The required page is specified by setting the ReadImageNumber property before calling one of the methods that loads an image.

The InsertTIF and DeleteTIF methods are used to manipulate the pages of an existing TIF file that is stored on disk.

InsertTIF Source, Destination, Page - Inserts the image as an additional page into an existing TIF file. The existing file is read from disk, and a new file is saved with the additional image added. The new file can either overwrite the existing one, or be saved with a different name. Source must be a complete path to the existing file, Destination is a complete path to the new file to be created, and Page is the position in the TIF file where the image will be inserted with the first image in the file being Page = 1. Source and Destination are strings, Page is an integer.

Source and Destination can be identical, in which case, the existing file is replaced. If Destination is an empty string, the existing file will be replaced. If Source is an empty string or if it cannot be found, Destination will be created new with only the single image. If Page is set to zero, the image will be inserted at the end of the file.

DeleteTIF Source, Destination, First, Count - Deletes a range of consecutive images from an existing TIF file and saves the file, either overwriting the existing file, or creating a new file. Source must be a complete path to the existing file, Destination is a complete path to the new file to be created, First is the position in the TIF file of the first image to be deleted and Count is the number of images to be deleted. For example, if First is 4 and Count is 3, the images numbered 4, 5 & 6 would be deleted. Source and Destination are strings, First and Count are positive integers. If First and Count are invalid values, no deletion will take place but no error will be generated.

Source and Destination can be identical, in which case, the existing file is replaced. If Destination is an empty string, the existing file will be replaced.

The AddToTIF method allows a multipage TIF to be built in memory so that it can be exported as a full file. The pages stored in memory are compressed as specified by CompressionType. A black and white image using Group 4 compression should not take up much memory but using AddToTIF with coloured images can use up large amounts of memory so this function should be used with caution.

AddToTIF Page - Stores the image temporarily in memory as a page which is ready to be written to a TIF file. Page is the number of the page in the TIF file where the image will be saved. If Page is set to zero, the image will be positioned at the end of the file. Any TIF exported by WriteFile or TIFData will include all the pages added by AddToTIF. AddToTIF does not need to be called when working with single page TIFs. Page is an integer.

ClearTIF - Clears all the images from memory that have been stored using AddToTIF.

2.5. 2.5. Multi Frame GIFs (Animations)

This section only applies to GIF files.

By default, csImageFile will load the first frame of a GIF and discard the rest. Setting ImageCount or ImageCountBinary, described in the previous section, will load a specified frame. The way that an animated GIF is stored allows for a frame to be smaller than the overall dimensions of the GIF (the logical screen), and for it to be displayed over the previous frame or the background. When csImageFile extracts the frame it will "unoptimise" the GIF, and produce the image that would be displayed in a browser when that particular frame is visible. This means it is the same size as the logical screen and it may have been merged with previous frames or the background colour.

Loading a frame from a GIF sets the Transparent and TransparentColor properties, as well as the following which only apply to GIFs.

GIFDelay - Integer. The length of time the frame will be displayed before moving to the next frame. This is measured in 1/100ths of a second. (Default = 0)

Most web browsers will not show more than 10 frames per second, so when values of less than 10 are used for GIFDelay, the animation may run slower than expected. The same animation may run at the correct speed when viewed in other image viewing software.

GIFLoopCount - Integer. The number of times the entire animation will repeat. When this value is zero it will repeat indefinitely. The maximum value is 65536. The first run through the animation is not counted so setting GIFLoopCount to 1 results in two complete iterations. (Default = 0).

GIFHideLoopCount - Boolean. The data block inside the GIF that specifies the loop count can be omitted if necessary by setting this property to true. Technically it is not a standard part of the GIF format and was added by Netscape so that Netscape 2.0 could display animations, but most GIF readers use it. Set GIFHideLoopCount to true if only one pass through the animation is required. (Default = false).

GIFDisposeMethod - Integer value 0 - 3. This property describes what should happen to the frame when the next image is displayed. The exact behaviour depends on the GIF reader.

0 - Unspecified. This is usually interpreted in the same way as 1, No Disposal.

1 - No Disposal. The image remains in the display and will still be visible if the next image is smaller or offset. (Default)

2 - Restore Background. The image is removed and the background behind the GIF is displayed.

3 - Restore Previous. This restores the display to whatever was there before the current frame.

The AddToGIF method allows a multiframe GIF to be built in memory so that it can be exported as a full file. The properties Transparent, TransparentColor, GIFDelay and GIFDisposeMethod apply to each frame individually so they should be set before calling AddToGIF.

AddToGIF Frame - Stores the image temporarily in memory as a frame which is ready to be written to a GIF file. Frame is the number of the frame in the GIF file where the image will be saved. If Frame is set to zero, the image will be positioned at the end of the file. Any GIF exported by WriteFile or GIFData will include all the frames added by AddToGIF. AddToGIF does not need to be called when working with single frame GIFs. Frame is an integer.

ClearGIF - Clears all the images from memory that have been stored using AddToGIF.

GIFOptimize - This method can reduce the output size of the GIF stored using AddToGIF. It applies to the entire multi frame image and would be called once, after adding the last frame. It works by cropping frames and allowing the previous frame or background to show through. It also merges the colour tables into a single global colour table. It is not guaranteed to reduce the file size, but it usually does. It can be time consuming.

2.6. Export to PDF

This section only applies to the export of PDF files.

Single images can be exported to PDF format by using the WriteFile method described earlier, if an extension of ".pdf" is specified. They can be streamed to a browser or database field using the PDFData property, also described earlier. The following methods are used to create multipage documents.

AddToPDF Page - Stores the image temporarily in memory as a page which is ready to be written to a PDF file. Page is the number of the page in the PDF file where the image will be saved. If Page is set to zero, the image will be positioned at the end of the file. Any PDF exported by WriteFile or PDFData will include all the pages added by AddToPDF. AddToPDF does not need to be called to produce single page PDFs. Page is an integer.

ClearPDF - Clears all the images from memory that have been stored using AddToPDF.

When creating PDF documents the value of the DPI property will affect the size of the image when it is displayed.

2.7. Reading Images Embedded in PDF Files

PDF files are not images and csImageFile cannot read them. However, they can contain images and if the ImageCount or ImageCountBinary methods described in Section 2.4 are used with PDFs, they may indicate that one or more images are available for reading. If these methods return a value of zero, there are no images inside the PDF that can be read by csImageFile. If there are images inside the file, setting the ReadImageNumber property before reading the file will specify which image will be loaded.

2.8. Base64 Encoding

csImageFile can import and export images using base64 encoding. The methods used are Base64In and Base64Out.

Base64In Input - Loads an image that is a base64 encoded string, Input.

Base64Out ImgType - Returns a string using base64 encoding. ImgType is the image format as a string, e.g. "jpg" or "png".

Base64 was traditionally used for attaching binary data to documents such as emails. It can be used to store binary data in a string field in a database and it can be used to display an image in a browser, as in the following example.

Example:

If an instance of csImageFile is called Image the above code will display the loaded image in a browser img tag as a jpeg, and it avoids the need for a separate script to display the image. It is approximately 33% larger in size than the equivalent as a binary stream.

3. Image Resize and Manipulation

3.1. Methods for Image Manipulation

The most common type of image manipulation for which csImageFile is used is the resizing of images. Three methods are provided for this, Resize, ResizeFit and Scale.

Resize Width, Height - The current image will be resized to new pixel dimensions Width and Height. If either parameter is zero the other will be used to determine the new size and the aspect ratio will be maintained. Width and Height are integers.

Example:

This resizes the image to 100 pixels wide while maintaining the aspect ratio. In VBScript there are no brackets around method parameters. There is no equals sign because it is a method call.

ResizeFit MaxWidth, MaxHeight - If the current image has a width or height greater than MaxWidth or MaxHeight it will be resized to fit within those dimensions while maintaining aspect ratio. If the image already fits within MaxWidth and MaxHeight it will be unchanged. MaxWidth and MaxHeight are integers.

Scale Factor - The current image will be scaled by Factor percent, where Factor is an integer. Images that are scaled always maintain aspect ratio.

Example:

This scales the current image to 50% of original size. (The width is scaled by 50% and the height is scaled by 50% so the area is reduced to 25% of its original size.)

NewScale Factor - This is identical to the Scale function and was introduced to avoid a clash of names for Visual Basic users.

The following method, NewImage, is important because it is used to create a blank image which can be used for drawing or writing onto or as a background with one of the merge functions.

NewImage Width, Height, Color - This loads a blank image into memory, deleting any previously loaded image. It is Width x Height pixels in size and the colour is determined by the Color parameter. ColorDepth is set to 24 after calling NewImage. Width and Height are integers and Color is a 6 character string representing the "RRGGBB" colour value.

The following methods provide simple image manipulation functions.

Crop X1, Y1, X2, Y2 - The parts of the rectangle outside the area defined by the opposite corners (X1, Y1) and (X2, Y2) will be removed. Note that coordinates are measured across and down from the top left corner of the image. The parameters are integers.

Crop can also be used to increase the area of the image by specifying coordinates that are outside the image. In this case the new area will be the colour of TransparentColor.

Rotate Angle - Rotates the image by Angle degrees anticlockwise. If the angle is not a right angle the new image will be centred on a larger rectangle, the colour of which will be defined by the TransparentColor property. If Resample is true and if the image has a colour depth of 24 bit the image will be smoothed during rotation. Angle is a floating point number.

FlipX - The image is reflected about an axis parallel to the x-axis running through the centre of the image. The top row of pixels becomes the bottom row and the bottom becomes the top.

FlipY - The image is reflected about an axis parallel to the y-axis running through the centre of the image. The left column of pixels becomes the right column and the left becomes the right.

The following methods perform image effects and colour adjustments.

Brightness Value - This adjusts the brightness of the image. Value is an integer between 0 and 100 where 0 is very dark, 100 is very bright and 50 is unchanged.

Contrast Value - This adjusts the contrast of the image. Value is an integer between 0 and 100 where 0 is zero contrast, 100 is maximum contrast and 50 is unchanged.

ColorAdjust Value, Red, Green, Blue - This adjusts the brightness of one or more of the primary colours. Value is an integer between 0 and 100 which describes the adjustment to the brightness. 0 is very dark, 100 is very bright and 50 is unchanged. Red, Green and Blue are Boolean values and specify which colours are adjusted. If all three are true it is identical to the Brightness method. When used after a GrayScale command ColorAdjust produces an image that appears to be viewed through a coloured filter.

Example:

This would give the image a kind of sepia tinge. Two ColorAdjust commands could be used to adjust the colours by different amounts of red and green.

HLSAdjust Hue, Lightness, Saturation - This can adjust one or more of the components in HLS colour space. The parameters are floating point numbers between -100 and +100, where 0 is no change. Hue is measured on a circular scale and an adjustment of 100% in either direction brings it back to the starting point. Adjusting Lightness or Saturation by -100% will set them to zero while adjusting by +100% will double the existing value.

Example:

This would increase the colour saturation of the image by 30%, leaving hue and lightness unchanged.

CombineColors Color, DeltaRed, DeltaGreen, DeltaBlue - This converts similar colours in a range to a single colour. The new colour is specified by Color, which is a string in the form "RRGGBB". The range of colours that will be combined is defined relative to Color by the difference in RGB components DeltaRed, DeltaGreen and DeltaBlue, which are integer values between 0 and 255.

ColorReplace OldColor, NewColor - This will replace any pixels coloured OldColor and change them to NewColor. These parameters are strings. This command applies to 24 bit colour images only. Use PaletteEntry to edit the colour palette for low colour images.

Sharpen - Applies a sharpening filter to the image.

SharpenBy Value - Applies a sharpening filter where the amount of sharpening is defined by Value, which is an integer between 1 and 10. 1 is low sharpening, 10 is high and 5 is the same as the Sharpen method.

Blur - Applies a blurring filter to the image.

BlurBy Value - Applies a blurring filter where the amount of blurring is defined by Value, which is an integer between 1 and 10. 1 is the least blurring, 10 is the most and 5 is the same as the Blur method.

GrayScale - Converts the image to a 256 colour greyscale image. The alternative spelling "GreyScale" is also accepted.

ConvertToBW - Converts the image to a 2 colour black and white image.

The following functions can convert between OLE_COLOR values and the 6 character strings that csImageFile uses for colours.

OLEColorToStr(Color) - This function takes a 4 byte OLE_COLOR value, Color, and returns a 6 character string of the form "RRGGBB".

StrToOLEColor(ColorStr) - This function takes a 6 character string of the form "RRGGBB" and returns a 4 byte OLE_COLOR value.

The following functions convert between RGB and HLS colour space values. RGB values are always expressed as a 6 character string.

RGBToHue(RGB) - This takes a RGB colour value as a string and returns the equivalent hue as a floating point value between 0 and 360.

RGBToLightness(RGB) - This takes a RGB colour value as a string and returns the equivalent lightness as a floating point value between 0 and 1.

RGBToSaturation(RGB) - This takes a RGB colour value as a string and returns the equivalent saturation as a floating point value between 0 and 1.

HLSToRGB(Hue, Lightness, Saturation) - This takes three H, L, S, parameters and returns the equivalent RGB colour value as a string. Hue is a floating point number between 0 and 360. Lightness and Saturation are floating point numbers between 0 and 1.

Invert - Converts the image to its negative by changing the colour of each pixel to the opposite colour, i.e., black is changed to white, white to black, etc.

3.2. Properties for Image Manipulation

The properties listed in this section can be used to control resampling of resized and rotated images.

Resample - Boolean. When true a resampling filter will be applied during an image resize or rotation. The filter used during resizing is specified by the FilterType property. When resampling is used the image will be converted to 24 bit colour.

For image resizing the quality is usually high enough when applied to 24 bit images and Resample does not need to be set.

For rotations using an angle that is not a multiple of 90 degrees the image will develop some jagged edges and setting Resample can reduce this effect.

FilterType - Integer in the range 1 to 6. Determines the filter algorithm used when the image is resampled during a resize or scale operation (but not for rotations). This filter is also used when drawing shapes or lines with antialiasing or when BlurText is used with the Text method. The values for FilterType are 1 - Bilinear, 2 - Hermite, 3 - Bell, 4 - B-Spline, 6 - Mitchell. (Default = 1)

3.3. Restricting Image Manipulation to a Selected Area

Some of the image manipulation methods can be applied to a rectangular area instead of the whole image. This area is set using the SetSelection method and cleared with the ClearSelection method.

SetSelection X1, Y1, X2, Y2 - (X1, Y1) and (X2, Y2) are integer coordinates measured form the top left of the current image and they specify opposite corners of a rectangle. When this method has been called, the image manipulation methods in the list below will be applied to this rectangular area only. This selection will remain until a new image is loaded or ClearSelection is called.

ClearSelection - This clears any selection rectangle and all future manipulations will apply to the entire image.

The methods to which the selection applies are: Brightness, Contrast, ColorAdjust, HLSAdjust, Sharpen, SharpenBy, Blur, BlurBy and Invert. Only 24 bit images will be affected because on low colour images adjustments are made to the palette, not the pixels.

The selection rectangle will also be used on any image exported using BMPHandle.

3.4. The Merge Methods and Properties

There are 6 methods available for combining the current image with a second image. MergeFront and MergeBack take the second image from a file stored on disk. MergeFrontBin and MergeBackBin take the second image as a binary data stream which can come from a database or an upload. MergeFrontHDC and MergeBackHDC take the second image as a Windows handle which can come from another instance of the component. The "Front" methods make the current image the foreground and the "Back" methods make the current image the background. The foreground image can be partially transparent by setting the TransPercent property. TransPercent is a percentage, taking a value between 0 and 100 where 0 is fully opaque and 100 is fully transparent (invisible). A single colour in the foreground can be fully transparent by setting the Transparent property to true and setting BGColor to the required colour.

The foreground image can be partially transparent by setting the TransPercent property. TransPercent is a percentage, taking a value between 0 and 100 where 0 is fully opaque and 100 is fully transparent (invisible). A single colour in the foreground can be fully transparent by setting the Transparent property to true and setting TransparentColor to the required colour. If the foreground image contains alpha transparency, this will be used in producing the composite image, in addition to the transparency options specified by TransPercent and TransparentColor. If both the foreground and background images contain alpha transparency the default behaviour will produce a composite image with no alpha transparency. To maintain alpha transparency set the KeepAlpha property to true.

For versions of csImageFile prior to 6.2, the property defining the transparent colour was BGColor. This property is still supported and can be used as an alternative name for TransparentColor.

The foreground image can be made to tile over the background by setting the Tile property to true. This ignores the X and Y coordinates and completely covers the background image. It would often be used with some transparency settings to create a watermark.

If the foreground image is 24 bit and the background image uses a palette the result will only contain the colours of the palette. This can be prevented by using the MergeBack method and using ColorDepth to change the paletted image to 24 bit before merging. If the background image uses a palette, any foreground alpha transparency will be ignored.

If the foreground image specified in MergeBack and MergeBackBin contains transparency, this will be used during the merge and will overrule the settings of Transparent and TransparentColor.

MergeFront Background, X, Y - Background is the full physical path and filename for another image. The current image in memory is placed onto this background image. The top left corner is X and Y pixels across and down from the top left of the background image. Background is a string, X and Y are integers.

MergeBack Foreground, X, Y - Foreground is the full physical path and filename for another image. This foreground image is placed onto the current image. The top left corner is X and Y pixels across and down from the top left of the current image. Foreground is a string, X and Y are integers.

MergeFrontBin BackgroundData, ImgType, X, Y - This is the same as the MergeFront command except that it reads the background image from binary data. BackgroundData is a variant array containing another image (see also ReadVariant). The current image in memory is placed onto this background image. The top left corner is X and Y pixels across and down from the top left of the background image. ImgType is a string indicating the format of the background image and it must be one of "jpg", "gif", "bmp", "png", "psd", "pcx", "tif", "wbmp". Version 5 or later will also accept an empty string for ImgType and it will use the image if it is a supported format. X and Y are integers.

Example:

This places the current image onto another JPG image read from a database field. The top left corner of the current image will be at coordinates 25, 50 on the background image.

MergeBackBin ForegroundData, ImgType, X, Y - This is the same as the MergeBack method except it reads the foreground image from binary data. ForegroundData is a variant array containing another image (see also ReadVariant). This image is placed on top of the current image. The top left corner is X and Y pixels across and down from the top left of the current image. ImgType is a string indicating the format of the foreground image and it must be one of "jpg", "gif", "bmp", "png", "psd", "pcx", "tif", "wbmp". Version 5 or later will also accept an empty string for ImgType and it will use the image if it is a supported format. X and Y are integers.

MergeFrontHDC BackgroundHandle, X, Y - This is the same as the MergeFront method except that it reads the background image from a Windows bitmap handle. The current image is placed onto this background image. The top left corner is X and Y pixels across and down from the top left of the background image.

Example:

This places the image stored in the first instance of csImageFile (Image1) onto an image stored in a second instance of csImageFile (Image2). The top left corner of the first image will be at coordinates 25, 50 on the second image. Note that the resulting image is stored in Image1 and the image in Image2 is unchanged.

MergeBackHDC ForegroundHandle, X, Y - This is the same as the MergeBack method except that it reads the foreground image from a Windows bitmap handle. This image is placed on top of the current image. The top left corner is X and Y ixels across and down from the top left of the current image.

The following properties affect image merging.

TransPercent - Floating point number between 0 and 100. When images are merged this specifies the percentage transparency of the foreground image. By setting this to a high value a watermark is produced. The background image needs to be 24 bit colour for this to be effective.

Tile - Boolean. Used with the merge functions. When true the foreground image is tiled to fill the background and the coordinates are ignored. (Default = false)

3.4. Colour Palettes

Images that have a colour depth of 1 bit, 4 bit or 8 bit will use a palette or colour table. Only colours defined in the palette can be used in the image. When a colour is used that is not already in the palette, it will be added automatically if there is an unused entry in the palette. The following methods and properties can be used to find information about the palette and to set colour entries in the palette.

3.4.1. Palette Properties

PaletteEntry (Index) - String. The colour used by entry Index in the colour palette for the current image. The colour is a 6 digit hexadecimal string. Index is an integer between 0 and 255 and an error will be generated if a value outside this range is used. Images with 24 bit colour depths do not have a palette and PaletteEntry will always return "000000" in this case. For 1 bit and 4 bit images the palette contains 2 entries and 16 entries respectively. The higher entries are undefined but reading and writing them does not raise an error.

Example:

This sets the first palette entry to red. Palette entries may be set before drawing on a low colour image, or they may be set to change a single colour within the image.

PaletteSize - Integer, read only. Returns the number of palette entries. This value can be found from the ColorDepth property because 1 bit, 4 bit and 8 bit images will have a PaletteSize of 2, 16 or 256. 24 bit images have a PaletteSize of 0.

3.4.2. Palette Methods

ColorIndex (Colour) - Returns the first index used by Colour, which is a 6 digit hexadecimal string. If the colour is not present in the palette the return value is -1.

FindUnusedColor - Returns the index of the first entry in the palette that is not used by any pixels. The return value is -1 if all the palette entries are used by pixels or if the image is 24 bit.

4. Drawing on the Image

Lines and shapes can be drawn on the image. Shapes and areas can be filled with a choice of simple fill patterns. The colour and thickness of lines is defined by the pen properties, PenColor, PenThickness and PenStyle. The fill colour and patterns are defined by the brush properties, BrushColor and BrushStyle. Individual pixels can be read or written to using the Pixel property. An image must be loaded, or created with NewImage, before any of these functions can be used.

All coordinate parameters are integers.

4.1. Methods for Drawing

Arc X1, Y1, X2, Y2, X3, Y3, X4, Y4 - Draws an elliptically curved line the colour of PenColor. The arc follows the perimeter of the ellipse bounded by (X1, Y1) and (X2, Y2), and moves anticlockwise from the start point to the end point. The start point is defined by the intersection of the ellipse with a line drawn from the centre to the point (X3, Y3). The end point is defined by the intersection of the ellipse with a line drawn from the centre to the point (X4, Y4).

Arc3XY X1, Y1, X2, Y2, X3, Y3 - Draws a an arc which traverses the perimeter of a circle between the points (X1, Y1) and (X2, Y2), passing through (X3, Y3). The shape is filled using the pattern defined by BrushStyle and the colour defined by BrushColor.

Chord X1, Y1, X2, Y2, X3, Y3, X4, Y4 - Draws a shape bounded by an arc and a line that joins the endpoints of the arc. The arc is an elliptically curved line that follows the perimeter of the ellipse bounded by (X1, Y1) and (X2, Y2), and moves anticlockwise from the start point to the end point. The start point is defined by the intersection of the ellipse with a line drawn from the centre to the point (X3, Y3). The end point is defined by the intersection of the ellipse with a line drawn from the centre to the point (X4, Y4). The shape is filled using the pattern defined by BrushStyle and the colour defined by BrushColor.

Ellipse X1, Y1, X2, Y2 - Draws a circle or ellipse that fits into the rectangle defined by the top left corner (X1, Y1) and the bottom right corner (X2, Y2). The shape is filled using the pattern defined by BrushStyle and the colour defined by BrushColor.

Circle3XY X1, Y1, X2, Y2, X3, Y3 - Draws a circle which passes through the points (X1, Y1), (X2, Y2) and (X3, Y3). The shape is filled using the pattern defined by BrushStyle and the colour defined by BrushColor.

CircleCR X, Y, R - Draws a circle with centre (X, Y) and radius R. The shape is filled using the pattern defined by BrushStyle and the colour defined by BrushColor.

Pie X1, Y1, X2, Y2, X3, Y3, X4, Y4 - Draws a pie shaped wedge defined by an arc of an ellipse and lines joining the ends of the arc with the centre of the ellipse. The arc follows the perimeter of the ellipse bounded by (X1, Y1) and (X2, Y2), and moves anticlockwise from the start point to the end point. The start point is defined by the intersection of the ellipse with a line drawn from the centre to the point (X3, Y3). The end point is defined by the intersection of the ellipse with a line drawn from the centre to the point (X4, Y4). The shape is filled using the pattern defined by BrushStyle and the colour defined by BrushColor.

Rectangle X1, Y1, X2, Y2 - Draws a rectangle defined by the top left corner (X1, Y1) and the bottom right corner (X2, Y2). The shape is filled using the pattern defined by BrushStyle and the colour defined by BrushColor.

RoundRect X1, Y1, X2, Y2, X3, Y3 - Draws a rectangle defined by the top left corner (X1, Y1) and the bottom right corner (X2, Y2). The corners will be rounded with a curve matching an ellipse with width X3 and height Y3. The shape is filled using the pattern defined by BrushStyle and the colour defined by BrushColor.

Line X1, Y1, X2, Y2 - Draws a line from point (X1, Y1) up to but not including the point (X2, Y2). The style, colour and width of the line are determined by the properties PenStyle, PenColor and PenThickness.

DrawLine X1, Y1, X2, Y2 - Alternative name for the Line method for Visual Basic users.

FloodFill X, Y - Fills an area on the current image with BrushColor spreading outward from the point (X, Y) until a different colour is reached. All the pixels filled will have the same original colour as the pixel at (X, Y).

FillToBorder X, Y, Color - Fills an area on the current image with BrushColor spreading outward from the point (X, Y) until a boundary of Color is reached. Color must be a 6 character string representing the hexadecimal "RRGGBB" value.

For both FloodFill and FillToBorder the BrushStyle property must be changed from its default value of 1 (clear). Use 0 for solid.

PointAdd X, Y - Adds a point to use as a vertex by the Polygon method.

Polygon - Draws a polygon using the points added by PointAdd as vertices. The shape is filled using the pattern defined by BrushStyle and the colour defined by BrushColor. The points stored by PointAdd are cleared after the polygon is drawn.

BezierPointAdd X, Y - Adds a point to be used by the PolyBezier method.

PolyBezier - Draws a set of cubic Bezier curves using the points added by BezierPointAdd. The first curve is drawn from the first point to the fourth point, using the second and third points as control points. Each subsequent curve in the sequence requires exactly three more points. The ending point of the previous curve is used as the starting point, the next two points in the sequence are control points and the third is the ending point. The style, colour and width of the line are determined by the properties PenStyle, PenColor and PenThickness. The points stored by BezierPointAdd are cleared after calling PolyBezier.

SetBitmapBrush Path - Sets a bitmap to be the pattern used for filling shapes. The bitmap used is defined by Path which is the physical path and filename for the file. This will override the BrushStyle and BrushColor settings.

Example:

This will draw a rectangle and fill it with the image "pattern.bmp". If this is smaller than the rectangle it will be tiled.

SetBitmapBrushHandle Handle - Sets a bitmap to be the pattern used for filling shapes. The bitmap is defined by its Windows handle, Handle, which is an integer value. This could be used with the BMPHandle property to get the pattern from another instance of csImageFile. The BrushStyle and BrushColor properties are overridden.

ClearBitmapBrush - This removes any bitmap that was used as a fill pattern and reverts back to using BrushStyle and BrushColor.

Note that using a bitmap as the fill pattern will not work adequately for full colour pattern images unless the server is running in a full colour mode.

4.2. Properties for Drawing

The pen and brush properties are used to define the lines and filled shapes from the previous section.

PenColor - String. The colour used for drawing lines and the outlines of shapes. This is a 6 character string of the form "RRGGBB". (Default = "000000", black)

PenThickness - Integer. The width in pixels for lines and shape outlines. Line widths greater than one are only shown for solid pen styles. (Default = 1)

PenStyle - Integer in the range 0 to 5. This determines the pattern used to draw a line or shape outline. Use Clear (PenStyle = 5) when the outline is not required on filled shapes. (Default = 0, solid)

BrushColor - String. The colour used for filling shapes when the BrushStyle is not clear. This is a 6 character string of the form "RRGGBB". (Default = "FFFFFF", white)

BrushStyle - Integer in the range 0 to 7. BrushStyle determines the pattern used when filling shapes. The fill pattern is the same colour as BrushColor. Use Clear (BrushStyle = 1) when no fill is required. (Default = 1, clear)

The Pixel property allows access to read or set the colour of individual pixels.

Pixel(X, Y) - String. The colour of the pixel at (X, Y) as a 6 character hexadecimal string. X and Y are integers.

Example 1:

This makes the pixel at (10, 10) black.

Example 2:

This sets the BGColor property to the same colour as the pixel at the top left of the image.

Avoid filling large areas of an image by using Pixel in a loop because it is not particularly fast.

Antialias - Boolean. When true, text, lines or shapes drawn will be antialiased. (Default = false)

In the case of text it will only appear antialiased if the font is large enough or small enough to support it and if the image is 24 bit colour depth. If necessary the ColorDepth property should be set to 24 before drawing the text. If the computer running csImageFile has the display properties set to smooth screen fonts this will overrule the Antialias property and text will be antialiased even when the property is false. There is an alternative type of text antialiasing provided by the BlurText property, described in the next section.

For lines and shapes the exact appearance will be controlled by the value of the FilterType property and setting this to 3 or 4 will give a smoother appearance. Drawing an antialiased line or shape will automatically convert the image to 24 bit colour depth.

PixelArray (Row) - Variant array. This provides access to a complete row of pixels as an array of bytes. Row is measured from the top of the image where 0 is the top row and (Height - 1) is the bottom row. The exact format of the bytes will depend on the colour depth. For a 24 bit image there will be three bytes per pixel with the first being the blue component, the second the green and the third the red component. For an 8 bit image there will be one byte per pixel which represents the palette index. For a 4 bit image each byte represents the palette index for two pixels. For a 1 bit image, each byte represents 8 pixels. PixelArray is not easy to use in ASP as the language is not designed to work with arrays of bytes in this way. This property has been added by request.

BytesPerRow - Integer, read only. Used with PixelArray this property returns the number of bytes used by a row of pixels. It is the size of the variable returned by PixelArray.

5. Adding Text to an Image

Text can be placed on the current image using the Text method. Properties are available to control the font, style, size, colour and angle of rotation. Unicode characters can be used if the font supports them. Carriage returns can be placed in the string to allow the text to span multiple lines and there is a choice of justification options for this multi-line text.

Two methods of antialiasing are available. Setting the Antialias property to true enables Windows font smoothing. This requires the text to be above a certain size before antialiasing takes place, for example the Arial font does not antialias until the size is at least 18. Setting BlurText to true uses a resampling filter to blend the text with the background. This applies to all text sizes and fonts but the results are not as clear as when using the Antialias property. Either method should be avoided if the image is to be exported as a GIF with background transparency because the antialiased pixels are not the same colour as the background and are therefore visible.

Text X, Y, TextString - This places a string of text onto the image. The string is TextString, and the top left corner of the text is positioned at the point (X, Y). The text will break onto the next line if the string contains a carriage return, line feed or CRLF pair (in VBScript the constant vbCRLF can be used). Unicode characters will be displayed if the font specified by TextFont supports them. X and Y are integers, TextString is a string.

TextFont - String. The name of the font to be used. It defaults to the system font for the server and this font will be used if TextFont specifies an unavailable font. Note that if a font is installed on a remote server using Terminal Services, the server must be rebooted before csImageFile will be able to use the font. Use the AddFont method to temporarily install a font.

TextColor - String. The colour of the text as a 6 character string. (Default = "000000", black)

TextSize - Integer. The height of the text in pixels. (Default = 16)

TextBG - String. The colour of the text background as a 6 character string. (Default = "FFFFFF", white)

TextOpaque - Boolean. When true the text is drawn on a background the colour of TextBG. When false the background is transparent. (Default = true).

TextBold, TextItalic, TextUnderline, TextStrikeout - Boolean values to set text styles. All default to false.

TextAngle - Integer. The angle of rotation of the text, in degrees, measured anticlockwise from the horizontal. Only true type fonts can be drawn rotated. (Default = 0)

TextJustify - Integer, must be 0, 1 or 2. This applies to text spanning multiple lines and determines the justification. Text on a single line is not affected. The X parameter of the Text method always specifies the left position of the text string, even when text is right justified. 0 - Left, 1 - Centre, 2 - Right. (Default = 0, Left)

Text example:

This sets the size and the font and sets the style to bold before drawing some text at coordinates (100, 50). TextOpaque is set to false so that the text background is transparent. Note that the text properties require an equals sign to assign a value but Text is a method and does not use an equals sign.

BlurText - Boolean. When true, a resampling filter is applied to the text to soften the edges. The filter used is determined by the FilterType property. It will overrule the Antialias property. This effect is identical to the antialiased text used by csImageFile before version 4.4. (Default = false)

FontNames - Collection. This returns a list of all the fonts installed on the server in alphabetical order. It is a collection and so it can be accessed using For..Each. FontName.Count returns the total number of fonts available, and FontNames.Item(X) returns the name of the font at position X in the list.

Example:

This will list all the fonts installed on the server.

The TextHeight and TextWidth functions return the height and width of a text string. This can be useful when positioning an item of text because the X and Y parameters of the Text method always set the top left corner of the text.

TextHeight(Text) - Integer return value. This returns the height in pixels if the string Text is to be drawn using the current font and size settings.

TextWidth(Text) - Integer return value. This returns the width in pixels if the string Text is to be drawn using the current font and size settings.

Text can be made to span multiple lines by adding carriage returns to the string in the Text method. Alternatively, text can be made to fit into a rectangle.

TextWrap - Boolean. When true the text will wrap onto multiple lines depending on the length and the values of the TextRectX and TextRectY properties. The line will only break at a space between characters and it will be justified as specified by the TextJustify property. (false)

TextRectX - Integer. When TextWrap is true TextRectX is the width of the rectangle containing the text, in pixels. If zero, the text will extend to the right of the image before wrapping to the next line. (Default = 0)

TextRectY - Integer. When TextWrap is true TextRectY is the height of the rectangle containing the text in pixels. If zero, the text will fill as many lines as required up to the height of the image. (Default = 0)

Text can be made partially transparent by setting the TextTransPercent property before drawing the text.

TextTransPercent - Integer in the range 0 to 100. This specifies an amount of transparency for text where 0 is completely opaque and 100 is invisible. Setting it to a high value makes the text appear as a watermark. The image must be 24 bit colour for this property to have any effect. (Default = 0)

Text can also be drawn along the path of an arc by using the ArcText method.

ArcText X, Y, R, Angle, Text, Internal, Clockwise - Draws the text string Text around the arc with centre at X, Y and radius R. The starting position for the text on the arc is given by the integer Angle which is the angle measured anticlockwise from a line extending to the right from the centre of the circle. Internal and Clockwise are both Boolean parameters. When Internal is true the top of the text will be aligned with the arc and when Internal is false the bottom of the text will be aligned with the arc. The Clockwise parameter specifies the direction of the text.

For best results, set Antialias to true before calling ArcText and use a font size that is large enough for this to take effect. The spacing of the characters will be comparable to the normal spacing for the current font. The background for the text will always be transparent.

5.1. Dynamically Installing a Font

If a font file is available on the server and its location is known, it can be installed temporarily by calling AddFont.

AddFont FileName - FileName is the physical path to the font file on the server. That font will become available to csImageFile even if it has not been installed.

FreeAddedFonts - This will remove any fonts added by AddFont.

6. IPTC Text / File Info

The JPEG file format allows for additional data to be embedded in the file header and this is called meta data. One type of JPEG meta data is IPTC text (the initials stand for the International Press Telecommunications Council), which is a range of text fields that describe the image. csImageFile exposes each of these fields as properties for reading and writing. Adobe Photoshop supports some of these properties and refers to them as File Info and we have also used this terminology and our IPTC methods and properties are prefixed with "FFO_".

The HasFileInfo property indicates whether the current image contains File Info. It is set when an image is loaded. It is set to true if any FFO_ properties are written to, and set to clear if they are removed by calling the FFO_Clear or ClearMetaData methods.

The File Info properties can be read from or written to a separate file, either the older .FFO format or the newer XML based .XMP format.

Although IPTC text is most commonly used with JPEGs because it is aimed at digital photographs, the PSD and TIF formats also support it.

Version 6.3 of csImageFile extended IPTC support to the IPTC Core properties that are embedded inside files in the XMP data format. These properties are described later in this section. Their presence is indicated by the HasXMP property and they are cleared using the XMPClear method. These properties were only supported in JPEG files in version 6.3 but version 6.4 extended support to TIFF files and in January 2011 XMP support was extended to PSD files. Version 7.0 introduces support for "people tagging" as well as the tags used by Windows XP and the tag defining a rating for the image.

Many of the IPTC / File Info properties shown below are also stored inside the file in XMP format. If the values are different, the version used is determined by the value of the XMPPriority property. When this is true (the default) the XMP version is used.

Version 8.5 of csImageFile introduced support for some PNG meta data. This includes the textual information that is defined in the PNG specification, and consists of some named properties. It also includes Exif, which is defined in an extension to PNG, and the XMP properties, described in Sections 6.2 and 6.3. IPTC is not supported and the XMP support is not a standard part of the PNG specification.

6.1. IPTC / File Info Properties

HasFileInfo - Boolean. When an image is loaded that contains File Info this property is set to true. Setting any File Info property will set HasFileInfo to true. To remove the File Info from an image use the FFO_Clear method, which also sets HasFileInfo to false. (Default = false)

These properties are the IPTC / File Info fields.

FFO_Caption - String.
FFO_CaptionWriter - String.
FFO_Headline - String.
FFO_Specialinstructions - String.
FFO_Category - String.
FFO_Byline - String.
FFO_BylineTitle - String.
FFO_Credit - String.
FFO_Source - String.
FFO_ObjectName - String.
FFO_City - String.
FFO_ProvinceState - String.
FFO_CountryName - String.
FFO_OTR - String. (Original Transmission Reference)
FFO_CopyrightNotice - String.
FFO_ImageURL - String.
FFO_Urgency - Integer in the range 0 - 7. Not saved/empty if set to 0.
FFO_DateCreated - Date.
FFO_CopyrightFlag - Boolean.

The following three properties are aliases of properties shown above. They reflect the fact that Adobe Photoshop 7 uses different property names from previous versions.

FFO_Title - String. Alias of FFO_ObjectName.
FFO_Author - String. Alias of FFO_Byline.
FFO_AuthorsPosition - String. Alias of FFO_BylineTitle.

Setting one property value also sets the corresponding alias property, so FFO_Title will always have the same value as FFO_ObjectName.

The following properties extend the copyright status to work with Adobe Photoshop 7 where three copyright states are possible, "Copyrighted Work", "Public Domain" and "Unmarked". FFO_Marked is stored in the XMP block and although it can be true or false, it can also be undefined (not present).

FFO_Marked - Boolean. Defaults to true.

FFO_MarkedDefined - Boolean. This determines whether the FFO_Marked property is defined in the file.

"Copyrighted Work" corresponds to FFO_CopyrightFlag = true or FFO_Marked = true.
"Public Domain" corresponds to FFO_Marked = false and either value for FFO_CopyrightFlag.
"Unmarked" corresponds to FFO_CopyrightFlag = false and FFO_Marked is undefined (FFO_MarkedDefined = false).

The Keywords and Supplemental Categories properties are zero based arrays of strings. Some additional properties and methods are needed to read and write them.

FFO_Keywords(Index) - String. The keyword defined by the integer Index.
FFO_KeywordsCount - Integer, read only. The number of items in the list.
FFO_KeywordsAdd Keyword - Adds the string Keyword to the end of the list. Returns the new number of items in the list as an integer.
FFO_KeywordsDelete Index - Deletes the keyword defined by the integer Index.
FFO_KeywordsInsert Index, Keyword - Inserts the string Keyword at position Index in the list. Index is an integer.
FFO_KeywordsClear - Deletes all the keywords.

FFO_SuppCat(Index) - String. The category defined by the integer Index.
FFO_ SuppCatCount - Integer, read only. The number of items in the list.
FFO_ SuppCatAdd Cat - Adds the string Cat to the end of the list. Returns the new number of items in the list as an integer.
FFO_ SuppCatDelete Index - Deletes the category defined by the integer Index.
FFO_ SuppCatInsert Index, Cat - Inserts the string Cat at position Index in the list. Index is an integer.
FFO_ SuppCatClear - Deletes all the categories.

Version 4.3 of csImageFile introduced support for more IPTC fields. These are shown separately as fewer software packages support these fields.

FFO_EditStatus - String.
FFO_FixtureIdentifier - String.
FFO_DateReleased - Date.
FFO_TimeReleased - Date.
FFO_ReferenceService - String.
FFO_ReferenceDate - Date.
FFO_ReferenceNumber - String.
FFO_TimeCreated - Date.
FFO_OriginatingProgram - String.
FFO_ProgramVersion - String.
FFO_ObjectCycle - String.
FFO_Sublocation - String.
FFO_CountryCode - String.
FFO_LocalCaption - String.
FFO_CustomField1 - String.
FFO_CustomField2 - String.
  There are 20 custom fields in total.
FFO_CustomField19 - String.
FFO_CustomField20 - String.
FFO_ImageNotes - String.

6.2. IPTC Core Properties (XMP)

Version 6.3 of csImageFile introduced support for the following properties, which are defined by the IPTC Core Schema for XMP. Some care should be taken when using them because it is a more recent standard and not all software with IPTC support will support these properties.

FFO_CiAdrExtAdr - String. Extra address field for creator contact info.
FFO_CiAdrCity - String. City field for creator contact info.
FFO_CiAdrRegion - String. Region field for creator contact info.
FFO_CiAdrCtry - String. Country field for creator contact info.
FFO_CiAdrPcode - String. Postal code field for creator contact info.
FFO_CiTelWork - String. Creator contact telephone number.
FFO_CiEmailWork - String. Creator contact email address.
FFO_CiUrlWork - String. Creator contact URL.
FFO_HasContactInfo - Boolean, read only. This property is true if any of the above creator contact fields are present.
FFO_IntellectualGenre - String.
FFO_RightsUsageTerms - String.

The Scene and SubjectCode properties are zero based arrays of strings. Some additional properties and methods are needed to read and write them.

FFO_Scene(Index) - String. The scene defined by the integer Index.
FFO_SceneCount - Integer, read only. The number of items in the list.
FFO_SceneAdd Scene - Adds the string Scene to the end of the list. Returns the new number of items in the list as an integer.
FFO_SceneDelete Index - Deletes the scene defined by the integer Index.
FFO_SceneInsert Index, Scene - Inserts the string Scene at position Index in the list. Index is an integer.
FFO_SceneClear - Deletes all the items in the list.

FFO_SubjectCode(Index) - String. The subject code defined by the integer Index.
FFO_SubjectCodeCount - Integer, read only. The number of items in the list.
FFO_SubjectCodeAdd Code - Adds the string Code to the end of the list. Returns the new number of items in the list as an integer.
FFO_SubjectCodeDelete Index - Deletes the subject code defined by the integer Index.
FFO_SubjectCodeInsert Index, Code - Inserts the string Code at position Index in the list. Index is an integer.
FFO_SubjectCodeClear - Deletes all the items in the list.

Many of the properties defined in the IPTC Core are duplicates of existing IPTC properties, for example Description (FFO_Caption), City (FFO_City) and the keywords. These duplicate properties can be accessed through the properties described in section 6.1 above. There are many other properties stored in the XMP data block which are not supported by csImageFile.

The following properties are used to manage the XMP data.

HasXMP - Boolean, read only. This is set to true when XMP properties are present.

KeepXMP - Boolean. When this is true, XMP data will be saved with a JPEG, TIFF or PNG file. Set this property to false to prevent the data from being saved. (Default = true)

XMPPriority - Boolean. If the same property is stored as both IPTC/IIMV4 and XMP inside a JPG or TIFF, XMPPriority determines which version is used when the image is loaded. When true, the XMP version will be used. This only applies to reading images and csImageFile will use the same value for both formats when writing. (Default = true)

6.3. IPTC Extended Properties

Version 8.4 of csImageFile introduced support for many of the IPTC Extended Properties. We have changed the naming convention for these properties and they have the prefix "IPTC" or "PLUS", depending on the namespace to which they belong, although they are XMP and are stored in the same way as the Core Properties described above.

Many of the properties are defined as structures rather than simple text or numeric fields, and an image can contain a variable number of these structures. Some structures contain fields that are also variable in number. This has resulted in a large number of properties and methods, some requiring an index, to be able to read and write the data. All indices are zero based and calling an invalid index will raise an exception.

An example of a structure, which may appear multiple times, is the ArtworkOrObject. There is a Count property, Add and Clear methods and each field can be accessed by index. Three of the fields, AOCreator, AOCreatorId and AOStylePeriod may contain multiple values so each of these needs its own Count, Add and Clear.

IPTCArtworkOrObjectCount - Integer, read only. The number of ArtworkOrObject structures in the image.

IPTCArtworkOrObjectAdd - Adds an empty ArtworkOrObject structure.

IPTCArtworkOrObjectClear - Deletes all the ArtworkOrObject structures.

IPTCAOCopyrightNotice(Index) - String. AOCopyrightNotice field defined by the integer Index.

IPTCAOCurrentCopyrightOwnerName(Index) - String.

IPTCAOCurrentCopyrightOwnerId(Index) - String.

IPTCAOCurrentLicensorName(Index) - String.

IPTCAOCurrentLicensorId(Index) - String.

IPTCAOCreatorCount(Index) - Integer, read only. The number of AOCreator items in the ArtworkOrObject structure specified by Index.

IPTCAOCreatorClear(Index) - Deletes the AOCreator items in the ArtworkOrObject structure specified by Index.

IPTCAOCreatorAdd(Index, Value) - Adds a new AOCreator item and assigns it the string Value. Index specifies the ArtworkOrObject structure to which it belongs.

IPTCAOCreator AOIndex, CreatorIndex - String. The value of the AOCreator item specified by AOIndex and CreatorIndex.

IPTCAOCreatorIdCount(Index) - Integer, read only. The number of AOCreatorId items in the ArtworkOrObject structure specified by Index.

IPTCAOCreatorIdClear(Index) - Deletes the AOCreatorId items in the ArtworkOrObject structure specified by Index.

IPTCAOCreatorIdAdd(Index, Value) - Adds a new AOCreatorId item and assigns it the string Value. Index specifies the ArtworkOrObject structure to which it belongs.

IPTCAOCreatorId AOIndex, CreatorIdIndex - String. The value of the AOCreatorId item specified by AOIndex and CreatorIdIndex.

IPTCAODateCreated(Index) - Date.

IPTCAOCircaDateCreated(Index) - String.

IPTCAOStylePeriodCount(Index) - Integer, read only. The number of AOStylePeriod items in the ArtworkOrObject structure specified by Index.

IPTCAOStylePeriodClear(Index) - Deletes the AOStylePeriod items in the ArtworkOrObject specified by Index.

IPTCAOStylePeriodAdd(Index, Value) - Adds a new AOStylePeriod item and assigns it the string Value. Index specifies the ArtworkOrObject structure to which it belongs.

IPTCAOStylePeriod(AOIndex, StylePeriodIndex) - String. The value of the AOStylePeriod item specified by AOIndex and StylePeriodIndex.

IPTCAOSource(Index) - String.

IPTCAOSourceInvNo(Index) - String.

IPTCAOSourceInvURL(Index) - String.

IPTCAOContentDescription(Index) - String.

IPTCAOContributionDescription(Index) - String.

IPTCAOPhysicalDescription(Index) - String.

IPTCAOTitle(Index) - String.

The OrganisationInImageCode is a string value but there may be multiple values.

IPTCOrganisationInImageCodeCount - Integer, read only. The number of OrganisationInImageCode items in the image.

IPTCOrganisationInImageCodeAdd(Value) - Adds a new OrganisationInImageCode item and assigns it the string Value.

IPTCOrganisationInImageCodeClear - Deletes the OrganisationInImageCode items.

IPTCOrganisationInImageCode(Index) - String. The value of the OrganisationInImageCode item specified by Index.

The LocationShown is a structure containing several text properties and there may be more than one of these structures. One property, the LocationId, can also appear more than once.

IPTCLocationShownCount - Integer, read only. The number of LocationShown structures in the image.

IPTCLocationShownAdd - Adds an empty LocationShown structure.

IPTCLocationShownClear - Deletes all the LocationShown structures.

IPTCLocationShownCity(Index) - String. City field defined by the integer Index.

IPTCLocationShownCountryCode(Index) - String.

IPTCLocationShownCountryName(Index) - String.

IPTCLocationShownLocationIdCount(Index) - Integer, read only. The number of LocationId items in the LocationShown structure specified by Index.

IPTCLocationShownLocationIdClear(Index) - Deletes the LocationId items in the LocationShown structure specified by Index.

IPTCLocationShownLocationIdAdd(Index, Value) - Adds a new LocationId item and assigns it the string Value. Index specifies the LocationShown structure to which it belongs.

IPTCLocationShownLocationId(LSIndex, IdIndex) - String. The value of the LocationId item specified by LSIndex and IdIndex.

IPTCLocationShownProvinceState(Index) - String. ProvinceState field defined by Index.

IPTCLocationShownSublocation(Index) - String.

IPTCLocationShownWorldRegion(Index) - String.

The OrganisationInImageName is a string value but there may be multiple values.

IPTCOrganisationInImageNameCount - Integer, read only. The number of OrganisationInImageName items in the image.

IPTCOrganisationInImageNameAdd(Value) - Adds a new OrganisationInImageName item and assigns it the string Value.

IPTCOrganisationInImageNameClear - Deletes the OrganisationInImageName items.

IPTCOrganisationInImageName(Index) - String. The value of the OrganisationInImageName item specified by Index.

The PersonInImage is a string value but there may be multiple values.

IPTCPersonInImageCount - Integer, read only. The number of PersonInImage items in the image.

IPTCPersonInImageAdd(Value) - Adds a new PersonInImage item and assigns it the string Value.

IPTCPersonInImageClear - Deletes the PersonInImage items.

IPTCPersonInImage(Index) - String. The value of the PersonInImage item specified by Index.

The RegistryId is a structure containing two text properties and there may be more than one of these structures.

IPTCRegistryIdCount - Integer, read only. The number of RegistryId structures in the image.

IPTCRegistryIdAdd - Adds an empty RegistryId structure.

IPTCRegistryIdClear - Deletes all the RegistryId structures.

IPTCRegistryIdRegItemId(Index) - String. RegItemId field specified by Index.

IPTCRegistryIdRegOrgId(Index) - String. RegOrgId field specified by Index.

The LocationCreated is a structure containing several text properties and there may be more than one of these structures. One property, the LocationId, can also appear more than once.

IPTCLocationCreatedCount - Integer, read only. The number of LocationCreated structures in the image.

IPTCLocationCreatedAdd - Adds an empty LocationCreated structure.

IPTCLocationCreatedClear - Deletes all the LocationCreated structures.

IPTCLocationCreatedCity(Index) - String. City field defined by the integer Index.

IPTCLocationCreatedCountryCode(Index) - String.

IPTCLocationCreatedCountryName(Index) - String.

IPTCLocationCreatedLocationIdCount(Index) - Integer, read only. The number of LocationId items in the LocationCreated structure specified by Index.

IPTCLocationCreatedLocationIdClear(Index) - Deletes the LocationId items in the LocationCreated structure specified by Index.

IPTCLocationCreatedLocationIdAdd(Index, Value) - Adds a new LocationId item and assigns it the string Value. Index specifies the LocationCreated structure to which it belongs.

IPTCLocationCreatedLocationId(LCIndex, IdIndex) - String. The value of the LocationId item specified by LCIndex and IdIndex.

IPTCLocationCreatedProvinceState(Index) - String. ProvinceState field defined by Index.

IPTCLocationCreatedSublocation(Index) - String.

IPTCLocationCreatedWorldRegion(Index) - String.

The following properties are single fields.

IPTCEvent - String. The Event property.

IPTCMaxAvailHeight - Integer. The maximum height in pixels of the original image.

IPTCMaxAvailWidth - Integer. The maximum width in pixels of the original image.

The remaining properties are part of the PLUS namespace (Picture Licensing Universal System).

PLUSVersion - String. If not specified, this will be added automatically when any PLUS property is saved, and it will be set to "1.2.0".

The PLUS CopyrightOwner is a structure containing two text properties and there may be more than one of these structures.

PLUSCopyrightOwnerCount - Integer, read only. The number of PLUS CopyrightOwner structures in the image.

PLUSCopyrightOwnerAdd - Adds an empty PLUS CopyrightOwner structure.

PLUSCopyrightOwnerClear - Deletes all the PLUS CopyrightOwner structures.

PLUSCopyrightOwnerName(Index) - String. Name field specified by Index.

PLUSCopyrightOwnerID(Index) - String. ID field specified by Index.

The PLUS Licensor is a structure containing several text properties and there may be more than one of these structures.

PLUSLicensorCount - Integer, read only. The number of PLUS Licensor structures in the image.

PLUSLicensorAdd - Adds an empty PLUS Licensor structure.

PLUSLicensorClear - Deletes all the PLUS Licensor structures.

PLUSLicensorName(Index) - String. Name field specified by Index.

PLUSLicensorID(Index) - String. ID field specified by Index.

PLUSLicensorStreetAddress(Index) - String.

PLUSLicensorExtendedAddress(Index) - String.

PLUSLicensorCity(Index) - String.

PLUSLicensorRegion(Index) - String.

PLUSLicensorPostalCode(Index) - String.

PLUSLicensorCountry(Index) - String.

PLUSLicensorTelephoneType1(Index) - String.

PLUSLicensorTelephone1(Index) - String.

PLUSLicensorTelephoneType2(Index) - String.

PLUSLicensorTelephone2(Index) - String.

PLUSLicensorEmail(Index) - String.

PLUSLicensorURL(Index) - String.

The PLUS ModelReleaseID is a string value but there may be multiple values.

PLUSModelReleaseIDCount - Integer, read only. The number of PLUS ModelReleaseID structures in the image.

PLUSModelReleaseIDAdd(Value) - Adds a new ModelReleaseID item and assigns it the string Value.

PLUSModelReleaseIDClear - Deletes all the PLUS ModelReleaseID structures.

PLUSModelReleaseID(Index) - String. The value of the ModelReleaseID field specified by Index.

The PLUS PropertyReleaseID is a string value but there may be multiple values.

PLUSPropertyReleaseIDCount - Integer, read only. The number of PLUS PropertyReleaseID structures in the image.

PLUSPropertyReleaseIDAdd(Value) - Adds a new PropertyReleaseID item and assigns it the string Value.

PLUSPropertyReleaseIDClear - Deletes all the PLUS PropertyReleaseID structures.

PLUSPropertyReleaseID(Index) - String. The value of the PropertyReleaseID field specified by Index.

The following properties are single fields.

PLUSMinorModelAgeDisclosure - String. The MinorModelAgeDisclosure property.

PLUSModelReleaseStatus - String. The ModelReleaseStatus property.

PLUSPropertyReleaseStatus - String. The PropertyReleaseStatus property.

6.4. IPTC / File Info Methods

FFO_Clear - Deletes all IPTC / File Info values and sets HasFileInfo to false.

FFO_Save FileName - Writes the File Info data to a file. FileName is the physical path and file name, complete with extension. The extension must be either .ffo or .xmp and this determines the format used. FileName is a string.

FFO_Load FileName - Loads File Info data from a file. FileName is the physical path and file name, complete with extension. The file must be either FFO or XMP format. FileName is a string.

OverwriteMetaData FileName - This writes the File Info and Exif data of the current image to the JPG file specified by FileName. It leaves the image part of FileName unchanged and so prevents the loss caused by recompressing the image. It must only be used if FileName is a JPG file. For TIF and PSD files, save the file using WriteFile. FileName is a string.

Example:

This will change the Caption property of the image and modify it on disk without changing the image data. It will lose any meta data that is not supported by csImageFile.

OverwriteMetaDataBin FileData - Variant array return value. This writes the File Info and Exif data of the current image to the JPG file FileData, which is a variant array. The resulting file is returned as a variant array. As with OverwriteMetaData it leaves the image part of the input file unchanged to prevent loss on recompression. It can be used when JPG images are stored in binary fields in databases.

Example:

This assumes that RS is an open recordset, ImageData is a binary data field containing an image in JPG format and Image is an instance of csImageFile which contains some meta data. It will write the meta data to the image and write it back to the recordset. Note that csImageFile cannot read an image directly from the recordset and it is written into a temporary VBScript variable first.

ReadMetaData FileName - This loads the File Info and Exif data from the JPG, TIF or PSD file specified by FileName into the csImageFile object, without loading the image itself. Any image already loaded will remain unchanged except for the meta data and the DPI property.

XMPClear - This clears any data stored in the XMP block.

ClearMetaData - This clears all the meta data from the image, and is the equivalent of calling FFO_Clear, XMPClear and ExifClear.

6.5. People Tagging

People can be "tagged" in an image using meta data as specified in the Microsoft Photo Schema and this method is used by Windows Live. The names of one or more people can be written to the image meta data and each name can optionally include the specification of a rectangle within that image. The following methods and properties allow this meta data to be read and edited.

6.5.1. People Tagging Methods

AddXMPPersonTag(Name) - Integer return value. This adds a new person tag called Name, which is a string. The return value is the index of this tag, which is needed to read or edit the tag in the future.

DeleteXMPPersonTag(Index) - Deletes the person tags specified by Index. The first tag has an Index of zero.

ClearXMPPersonTags - Removes all person tags from the image.

SetXMPRectangle Index, X, Y, Width, Height - Creates a rectangle for the person tag specified by Index. X and Y is the position of the top left corner of the rectangle and the size is given by Width and Height. The dimensions are floating point values between zero and one and they are fractions of the width and height of the image. This is how the values are stored inside the file.

SetXMPRectanglePX Index, X, Y, Width, Height - Creates a rectangle for the person tag specified by Index. X and Y is the position of the top left corner of the rectangle and the size is given by Width and Height. The dimensions are pixels and are integer values.

6.5.2. People Tagging Properties

All the people tagging meta data properties are stored in a zero based array, specified with an index.

XMPPersonTagCount - Integer, read only. The number of person tags in the image.

XMPPersonTag(Index) - String. The name of the person. This property can be set to change the name of an existing tag but use AddXMPPersonTag to add a new tag.

XMPRectangleX(Index) - Integer, read only. The x-coordinate of the top left of the rectangle specified by Index. This is measured in pixels.

XMPRectangleY(Index) - Integer, read only. The y-coordinate of the top left of the rectangle specified by Index. This is measured in pixels.

XMPRectangleWidth(Index) - Integer, read only. The width of the rectangle specified by Index. This is measured in pixels.

XMPRectangleHeight(Index) - Integer, read only. The height of the rectangle specified by Index. This is measured in pixels.

To set the coordinates of a rectangle, use SetXMPRectangle or SetXMPRectanglePX.

XMPPersonEmailDigest(Index) - String. This is used by Windows Live and is the hash of an email address. It is not an actual email address.

XMPPersonLiveIdCID(Index) - String. The decimal representation of a Windows Live CID.

The above two properties cannot be used directly but are included to allow the contents of an existing image file to be copied.

The people tagging properties are XMP and are cleared by XMPClear and are used with the properties HasXMP and KeepXMP.

People tagging is not included in PNG images.

6.6. Other XMP Properties – Rating and Rating Percent

Two other meta data properties are supported and these come under the category of XMP. The property names have the prefix FFO_ like the IPTC properties described above although they are not part of the IPTC specification.

FFO_Rating - Integer. This is the rating that is recognised in Windows 7 and Vista and is usually shown as a number of stars. It should have a value between 1 and 5. If it is zero it is null and will not be stored.

FFO_RatingPercent - Integer. This is part of the Microsoft Photo Schema and should have a value between 1 and 100. If it is zero it is null and will not be stored.

Note that csImageFile does not verify the range of values when either FFO_Rating or FFO_RatingPercent are set, so it is possible to give them unsuitable values. They are cleared by setting them to zero and are also cleared when XMPClear is called.

6.7. PNG Textual Information

PNG images can store some specific meta data values. Each of these is exposed by csImageFile as a property. They are all strings except for the creation date, which is a date. The suggested use is shown next to each property. csImageFile will preserve this data when a PNG image is saved, unless it is specifically cleared by calling the ClearPNGText method.

PNGTitle - String. Short (one line) title or caption for the image.

PNGAuthor - String. Name of the creator of the image.

PNGDescription - String. Description of the image.

PNGCopyright - String. Copyright notice.

PNGCreationTime - Date. Time and date of the original image creation.

PNGSoftware - String. Software used to create the image.

PNGDisclaimer - String. Legal disclaimer.

PNGWarning - String. Warning of the nature of the content.

PNGSource - String. Device used to create the image.

PNGComment - String. Miscellaneous comment.

PNGCollection - String. Name of a collection to which an image belongs.

The following properties apply to PNG textual information.

HasPNGText - Boolean, read only. This is set when an image is loaded and it indicates the presence of textual information.

The following method is used to clear PNG textual information.

ClearPNGText - Sets all text properties to empty strings and the creation time to zero.

7. EXIF Attributes

Another form of meta data that can be stored inside JPEG files are EXIF attributes (Exchangeable Image File Format). These are typically recorded by a digital camera at the time the image is created and many of them describe the camera and its configuration. csImageFile will preserve this data when a JPG image is saved, unless it is specifically cleared by calling the ExifClear method.

The Exif attributes (or tags) can be read, written or deleted using csImageFile. As there are over 100 different attributes we have not provided a property for each, in the way we have with IPTC text. Instead the attributes are held in an indexed array as strings. Each attribute can be accessed by its index in this array, or by name. Attributes can be written using the attribute name, which is not case sensitive.

csImageFile supports reading and writing Exif attributes with JPEG, TIFF and PNG files.

7.1. Reading Exif Attributes

ExifValueByIndex(Index) - Returns the value of the Exif attribute as a string given the index within the array. Index is an integer.

ExifValueByName(Name) - Returns the value of the Exif attribute as a string given the name of the attribute. Name is a string.

ExifName(Index) - Returns the name of the Exif attribute as a string given the index within the array. Index is an integer.

ExifCount - Integer property, read only. The number of Exif attributes.

ExifClear - This method clears all the Exif attributes. After calling ExifClear any image saved will have no Exif attributes.

Example:

This uses the trial version of csImageFile to list all the Exif attributes stored in the image.

7.2. Writing Exif Attributes

Individual Exif attributes can be written or deleted. They are always specified by the name of the attribute.

ExifSetAttribute Name, Value - Boolean return value. The Exif attribute Name is set to Value. Name and Value are both strings. If the attribute is set successfully the return value is true, otherwise it is false. If the name is invalid or if the value is not in the correct format the attribute will not be set.

ExifDelete Name - Boolean return value. The Exif attribute Name is deleted. Name is a string. If the deletion is successful the return value will be true. If Name is not a valid attribute name the return value will be false.

7.3. Exif Data Types

Each Exif attribute is stored as one of the data types listed below.

BYTE - An 8 bit unsigned integer.

ASCII - An ASCII character.

SHORT - A 16 bit (2 byte) unsigned integer.

LONG - A 32 bit (4 byte) unsigned integer.

RATIONAL - Two LONGs. The first is the numerator and the second is the denominator. The RationalToReal function can convert one of these values to a real number. The ExifSetAttribute function can accept either a real number or a rational number, in string format. So "3/2" and "1.5" would both be accepted by ExifSetAttribute. On systems where the comma character is used as a decimal point, this automatic conversion from real to rational will not work so the RealToRational method should be used if a conversion is required.

UNDEFINED - An 8 bit byte that can take any meaning depending on the field definition. This will be returned as a 2 character string of the hexadecimal byte value. Where multiple values are stored in the same attribute they are returned as a comma separated string. The ExifVersion attribute would return "30,32,32,30" for Exif 2.2. The ExifVersion attribute is defined to contain 4 bytes and each byte represents an ASCII character, so the bytes shown here translate to "0220". Other "Undefined" attributes will have different meanings and will not necessary represent ASCII characters.

SLONG - A 32 bit (4 byte) signed integer.

SRATIONAL - Two SLONGs. The first is the numerator and the second the denominator.

Date and time attributes are stored as strings in the format "YYYY:MM:DD HH:MM:SS". The ExifStringToDate and ExifDateToString functions can convert between this string format and the date/time format used by ActiveX components.

7.4. Exif Helper Functions

The following functions convert data from values stored in the Exif attributes into more usable forms, or convert data into a string value for use with the ExifSetAttribute method.

RationalToReal(Value) - Value is a string of the form "A/B" where A and B are integers and it returns a real number. It is used for converting a value stored as RATIONAL or SRATIONAL into a real number for further processing.

RealToRational(Value) - Value is a double precision real number and it returns a string of the form "A/B" where A and B are integers. It can be used to convert a number into a string that can be used where a RATIONAL or SRATIONAL number is required.

ExifStringToDate(Value) - Value is a string containing a date/time of the form "YYYY:MM:DD HH:MM:SS", which is how date/time Exif attributes are stored. The return value is in the format of an ActiveX date/time variable. If Value is not in the correct format the return value will be zero. It will not generate an error.

ExifDateToString(Value) - Value is an ActiveX date/time and the return value is the date and time in the form "YYYY:MM:DD HH:MM:SS". This can be used for converting a date/time into a string that can be used by the ExifSetAttribute function.

The following functions return information about the Exif attributes. This information can be found in the Exif specification but these functions can provide a useful reference and also clarify the values that csImageFile uses.

ExifAttributeName(Tag) - Tag is the 2 byte integer ID for the attribute. The return value is the string value of the attribute name as it is used by the other functions in this section.

ExifDataType(Name) - This returns the Exif data type for the Name attribute. Possible return values are 1 - BYTE, 2 - ASCII, 3 - SHORT, 4 - LONG, 5 - RATIONAL, 7 - UNDEFINED, 9 - SLONG, 10 - SRATIONAL. Name is a string, the return value is an integer.

ExifDataCount(Name) - This returns the size of the Name attribute. It is the number of data items, not the number of bytes occupied. For ASCII and UNDEFINED data types of variable length this value is zero. Name is a string.

The UserComment attribute is stored using the UNDEFINED data type so it is returned as a comma separated string of hexadecimal values. It is really a string preceded by a header which identifies the format as ANSI or Unicode. To allow easy reading and writing of this attribute the ExifUserComment property is provided.

ExifUserComment - String property. The value of the Exif UserComment attribute, which may optionally contain Unicode characters.

7.5. Exif Thumbnails

In JPG images a smaller copy of the image, or thumbnail, can be stored with the EXIF data. csImageFile does not store this by default but this behaviour can be controlled by setting the KeepExifThumbnail property.

KeepExifThumbnail - Boolean property. When true, JPG images will be saved with a thumbnail inside the EXIF data block. The OverwriteMetaData method will preserve any EXIF thumbnail while replacing the metadata. The thumbnail will only be stored if the image contains at least one EXIF property. (Default = false)

7.6. XP Summary Information

Windows XP allows some JPG meta data to be edited through Windows Explorer by selecting file properties. This data is stored with the Exif data although it is not stored using the recognised Exif standard. Five additional properties allow this data to be accessed with csImageFile.

XP_Title - String.

XP_Comments - String.

XP_Keywords - String.

XP_Author - String.

XP_Subject - String.

These values also appear in the list of Exif attributes and are cleared by calling ExifClear. It is difficult to read and write them correctly because they do not obey the Exif specification so it is recommended to use the properties provided.

These properties are also supported in later versions of Windows from Vista onwards but some of the properties set are stored as XMP and will appear as IPTC (File Info) properties when read using csImageFile. In later versions of Windows, TIFF images can have these properties inserted through Windows Explorer.

7.7. Trailing Meta Data

It has come to our attention that some meta data editing software incorrectly stores meta data at the end of JPG images. This results in the same software being unable to read changes made using our OverwriteMetaData method, as it inserts the meta data into the header and leaves the rest of the file untouched. We have introduced a method to remove this data from the end of JPG files.

DeleteTrailingData(FileName) - FileName is the physical path to a JPG file and is a string. Calling this method will remove any bytes from the file that are after the end of image marker.

DeleteTrailingDataBin(FileData) - FileData is a variant array containing a JPG image. The method has a return value which is also a variant array and it is the same JPG image but with the bytes after the end of image marker removed.

Example:

This example shows how DeleteTrailingDataBin could be used with our csASPUpload component to remove the extra bytes from the end of a JPG file during a file upload and before saving to a database. If the file was to be saved on disk it would be easier to save the file first and then use DeleteTrailingData.

These two methods should not be needed under normal circumstances. They are provided to deal with a known issue caused by some meta data editing software when the images are edited using OverwriteMetaData.

8. Embedded Colour Profiles

JPEG images can contain information that defines how the colours should appear when displayed. A system that is frequently used is defined by the International Color Consortium (ICC) and csImageFile can preserve this information when editing JPEG and TIFF images. A description of colour profiles and colour management is beyond the scope of these instructions.

The default behaviour of csImageFile is to discard the colour profile on opening a JPEG or TIFF. To overrule this, set the KeepICCProfile property to true before loading the image. If the current image contains an ICC colour profile, the HasICCProfile property will be set to true. An existing profile can be removed by calling the ClearICCProfile method.

The support for ICC profiles is limited to preserving or discarding existing information. There is no functionality to read information about the profile or to edit it in any way.

KeepICCProfile - Boolean. This property determines whether an embedded ICC colour profile will be stored when opening a JPEG or TIFF image. This property must be set to true to save an existing profile with a JPEG or TIFF image. (default = false)

HasICCProfile - Boolean, read only. This property indicates whether the current image contains an ICC colour profile. It will only return true if KeepICCProfile has been set before loading the image.

ClearICCProfile - This method clears an ICC colour profile from the current image.

9. Alpha Transparency and PNG Images

Some PNG images contain an "alpha channel" which describes a level of transparency for each individual pixel. csImageFile can extract this when a PNG image is loaded. If the image is saved again in PNG format, this alpha channel will be saved as part of the image.

The alpha channel will be preserved if the image is resized, cropped, rotated or flipped. Other edits will cause the alpha channel to be discarded unless the KeepAlpha property is first set to true. Before discarding any alpha channel the image will be merged with the background.

A PNG image can specify a background colour. This is to be shown behind transparent pixels if the viewer is unable to show whatever is behind the image. csImageFile will merge a PNG containing an alpha channel with this background when the image is exported to another format, or when the alpha channel is removed due to editing as described above. If no background colour is specified, white will be used by default.

The following properties are related to alpha transparency and background colours.

HasAlpha - Boolean, read only. This is set to true if the image currently loaded contains an alpha channel. Use ClearAlpha to remove an alpha channel.

KeepAlpha - Boolean. When true, edits applied to the image will not remove the alpha channel. This property is also used to maintain the background alpha channel when two images with alpha channels are merged. (Default = false)

BackgroundColor - String. The colour of the background that will be shown behind transparent pixels when an image containing an alpha channel is exported. (Default = "FFFFFF", white)

HasBackground - Boolean. This determines whether the current image contains a background colour which will be stored when the image is exported in PNG format. (Default = false)

ExtraAlphaValue - Integer in the range 0 - 255. When an image containing an alpha channel is rotated by an angle that is not a multiple of 90 degrees, or cropped to coordinates that make the image bigger, the new area created will have an alpha value specified by this property. 0 is fully transparent and 255 is fully opaque. (Default = 0)

AlphaPixel (X, Y) - Integer in the range 0 – 255. This property allows the alpha value of a specified pixel to be read or written.

The following methods are related to alpha transparency and background colours.

ClearAlpha - This removes any alpha channel from the current image without merging it with the background.

NewAlpha Value - This creates an alpha channel for the current image and sets the value for each pixel to Value, which is an integer between 0 and 255 where 0 is fully transparent and 255 is fully opaque. This will convert the image to 24 bit colour if it is not already.

CombineAlphaWithBG - This combines the image with the background colour, if it contains an alpha channel. The alpha channel is then removed.

AlphaText X, Y, TextOut - This draws antialiased text on an image with an alpha channel. X and Y are the coordinates of the text and TextOut is the text string. It uses the same properties for controlling the font, size and colour as the Text command in Section 5. An exception will be raised if there is no alpha channel in the current image.

PNG images containing a colour palette (colour images that are 8 bit or less) can specify a variable amount of transparency for each palette entry. This information is also preserved when loading and saving, but it is removed when the image is edited, except for resize, crop, rotate and flip operations. These images will not be merged with a background when exported or edited, but the transparency is used in merge functions. csImageFile versions before 8.1 cannot edit this type of transparency information except for the simple case where only one colour is fully transparent. See section 9.2 for details of reading and editing palette transparency.

9.1. Editing the Alpha Channel

There is some very limited support for editing the alpha channel, but this includes the ability to import and export the alpha channel as a greyscale bitmap. It is possible to export an alpha channel to another instance of csImageFile, edit it, and then import it again. In this greyscale bitmap a white pixel represents fully opaque and a black pixel represents fully transparent.

The following methods load and save the alpha channel as a bitmap.

SaveAlphaAsBMP FileName - If the current image contains an alpha channel this will save it as a greyscale bitmap. Full transparency is shown as black and full opacity is shown as white. FileName is the physical path to the saved file and it should have the extension .bmp. If no alpha channel is present in the image an exception will be raised.

LoadAlphaAsBMP FileName - This will load an alpha channel into the current image where FileName is the physical path to a greyscale bitmap file. This bitmap must be exactly the same width and height as the current image or an exception will be raised.

The alpha channel can also be loaded and saved as a greyscale bitmap directly from memory as a Windows handle.

AlphaHDC - Integer. This property gives access to the bitmap handle of the alpha channel. It can be used for import and export. It is compatible with the BMPHandle property so it can be used to pass an alpha channel between instances of csImageFile so it can be edited using the full range of component methods and properties. Importing an alpha channel with AlphaHDC will raise an exception if the imported image is not exactly the same dimensions as the current image.

Example:

This example shows how to use a second instance of csImageFile to edit an alpha channel. An image is loaded from disk and an alpha channel created using NewAlpha. The alpha channel is passed to the second component instance using AlphaHDC where a filled rectangle is drawn in a mid grey colour. This is passed back as the new alpha channel where it will show as a partially transparent rectangle.

Note that the background colour is not passed with the alpha channel and the BackgroundColor property must be set unless the default white colour is to be used.

9.2. Palette Transparency

csImageFile can now identify the case where an image contains a palette (or colour table) which has a variable amount of transparency for one or more palette entries. These entries can be read or edited and an image of this type can be converted to a 24 bit RGB image with an alpha channel.

TransparentPalette - Boolean. When true, the image contains a partially transparent palette. At the time of writing only PNG images support this. Setting TransparentPalette to true automatically sets Transparent to false and setting Transparent to true sets TransparentPalette to false. (Default = false)

TransparentArray (Index) - Integer. The values for palette transparency are stored in a zero based array where 0 is fully transparent and 255 is fully opaque. The first entry in TransparentArray corresponds to the first palette colour and the second to the second palette colour, and so on. csImageFile stores values with Index from 0 to 255, although 1 bit and 4 bit images will not use all of them.

PaletteToAlpha - This method will convert a paletted image with transparency to a 24 bit colour image with an alpha channel. It can be used with single colour transparency and variable palette transparency. It will have no effect if Transparent and TransparentPalette are both false or if the colour depth is 24 bit.

Loading an image will set TransparentPalette and populate TransparentArray. A new image will default to TransparentArray containing all values of 255 and TransparentPalette will be false.

Example:

This code would make the current image use a transparent palette and would set the first white palette entry to be fully transparent and the first green palette entry to be 50% transparent. This will only apply if the colour depth is less than 24 bit and only images exported in PNG format can save this information. This transparency can be used in a merge operation if the current image is used as the foreground.

10. Streaming an Image to the Browser

An active server page will return HTML output by default. An HTML page is formatted text which can include spaces to display images. The images themselves are not part of the HTML but are separate files, the location of which is specified inside the <img> tag. An ASP page can be an image if the ContentType is set to "image/gif" or "image/jpeg" and the binary data of the image is output using the Response.BinaryWrite command. The ASP image is generated by placing the path to the script inside the <img> tag.

For example, this page will display the image produced by "resize.asp":

Resize.asp may look like this:

When the first HTML page is loaded it looks for the image at "resize.asp", runs the script and is sent a stream of binary data in JPG format, so the browser displays the image. It is not possible to place the BinaryWrite command inside the <img> tag to produce the image, it must be in a separate file.

If the line setting the ContentType is missing the image should still display in Internet Explorer but it might not in other browsers. It is important to specify the correct ContentType to maintain compatibility.

It is useful to know that parameters can be passed to the ASP image script using the URL string and this can be read using Request.QueryString and used somewhere in the script.

Example:

This can be used by resize.asp:

Version 8.0 introduces the StreamToBrowser method which can be used instead of Response.BinaryWrite. If large images or multipage PDFs are to be displayed in the browser, StreamToBrowser may be preferreable because it puts less data into the response buffer at any time.

Example:

An alternative to streaming the image from a script specified in the <img> tag is to use Base64 encoding and the Base64Out command. This produces a larger output file size but removes the need for a separate script to stream the image.For details of using Base64 output, see Section 2.8.

11. Language Specific Issues

All the examples that are shown so far in these instructions use ASP and VBScript. The csImageFile component is a COM object and can be used in most COM enabled environments running on a Windows platform. We cannot begin to cover all the possible development environments here so instead we concentrate on ASP and in this section we show the syntax for Cold Fusion, Visual Basic and ASP.NET.

11.1. Active Server Pages

ASP and VBScript is already covered in these instructions but the following points are worth noting.

Calls to methods (functions) do not use brackets, although their use does not generate an error if there is only one parameter. For example the correct syntax for Resize is:

These instructions show methods without brackets surrounding the parameters, unless that method has a return value.

If the method has a return value that is assigned to another variable, the brackets are required. For example:

If the return value is not assigned, the brackets will give an error.

Assigning a property value requires an equals sign. Missing the equals sign results in the unhelpful error "Object doesn't support this property or method". The correct syntax is:

A lot of ASP syntax errors are caused by adding brackets when they are not required, or missing them when they are required, missing equals signs when assigning a property, or accidentally including an equals sign in a method call.

11.1.1. ASP with Javascript

We do not provide any examples of using ASP with other scripting languages, other than VBScript. We will mention the following about using Javascript with ASP.

Brackets are needed around function parameters.

The backslash character is used as an escape character in Javascript and two should be used together when a backslash is needed:

11.2. Cold Fusion

In Cold Fusion, a COM object is created using the <cfobject> tag:

Each command must be placed inside a <cfset> tag and all method parameters must be enclosed by brackets:

Alternatively, the commands can be put inside a <cfscript> block:

Cold Fusion version 5 does not support variant arrays and so commands such as GIFData, JPGData and ReadVariant cannot be used. Without these commands, images cannot be streamed directly to the browser so any dynamically produced image must be saved to a temporary file first and then displayed using a <cfcontent> tag.

It is possible to stream images using Cold Fusion without saving to a temporary file first. The following commands will stream an image in jpeg format assuming an image is loaded into a csImageFile object called "Image".

For more on using csImageFile with Cold Fusion visit www.chestysoft.com/imagefile/cf.htm.

Initially, 64 bit versions of Cold Fusion had no support for COM objects. COM support was added with Cold Fusion 10 Update 11.

11.3. Visual Basic

For best results import the csImageFile type library into VB by selecting "Project" from the menu bar, then "References". The dialogue box will then show available type libraries. Scroll down to "csImageFile Library", check the box and click OK. This will add the "Manage" class from csImageFile to the Object Browser, making it available for early binding.

To create an instance of the object called "Image" use the following code:

Displaying an image from csImageFile in a VB picture box is not simple as it involves an API call to create a bitmap. There is a description of this and some sample code on our web site at: www.chestysoft.com/imagefile/vbimage.asp.

Visual Basic 5 or 6 is a 32 bit application and so the 32 bit version of csImageFile must be used.

We have an OCX control called csXImage which is much more suited for use with Visual Basic: www.chestysoft.com/ximage/default.asp.

11.4. ASP.NET

csImageFile can be used with ASP.NET. The component must be registered on the server as described earlier and it can be called using Server.CreateObject. For example:

The object is created using Dim instead of Set. For the trial version the class name is "csImageFileTrial.Manage".

The image cannot be streamed to the browser in a single line because of incompatibilities between ActiveX and .NET, but there is a workaround which we describe in the VB.NET example below.

This creates a new image and draws some text onto it. In order to stream it to the browser the output from the GIFData property needs to be passed to an array of bytes so that it can be sent out through BinaryWrite. Brackets are used to enclose function parameters.

csImageFile can be used in C# scripts, but early binding must be used as described in the next section. The code needed to stream the image is shown below:

11.4.1. Early Binding

The previous example used late binding, which is the easier way of calling an ASP component in ASP.NET. It is more efficient to use early binding, but this requires the creation of a .NET Framework Interop Assembly using the TLBIMP tool, supplied with the Framework. This assembly is a DLL which acts as a wrapper for the ASP component.

After registering the component, run TLBIMP.exe from the command prompt or from the Run box in the Start Menu. The syntax is:

TLBIMP ComponentName.dll /out:NewName.dll

Full paths are required for both DLLs. The new DLL needs to be put in the website's BIN directory. The script that calls the component must import the Interop Assembly as a NameSpace. The component instance is created using the following VB.NET syntax:

ObjName is the name of the object instance and ClassName is the name of the class in the ASP component, which is Manage in csImageFile.

The script that uses the component must import the Interop Assembly as a Namespace. If the Interop Assembly is called "csimagefilenet.dll" the following line imports it:

In the previous example the only other change required is to replace the Server.CreateObject line with:

12. Utility Functions

There are a number of utility functions provided for convenience which are mostly related to file handling. Some of them are restricted to use in ASP. For a full range of file handling functions use the File System Object instead.

FileExists(FileName) - Boolean property, read only. Checks for the existence of the file defined by FileName. FileName is a string and must be a physical path.

CurrentDir - String property, read only. This can only be used in ASP scripts and it returns the physical path of the directory containing the script, complete with trailing backslash.

ParentDir(Directory) - String property, read only. This returns the physical path of the parent directory to Directory. Directory is a string.

Example:

This would display the directory immediately above the directory containing the script.

DirName - String property. This is the directory that will be listed in the FileList collection. It is a physical path and can include a single filter in the name.

Example 1:

This will assign all the files in the "images" directory to the FileList collection.

This will assign all the files in the "images" directory with a .jpg extension to the FileList collection.

FileList - Collection of strings. When a directory is assigned to the DirName property this collection will be populated by a list of the files in that directory. As a Collection it can be accessed by index using the Item property, or in a For..Each loop, and it has a Count property.

Example:

This would display all the .jpg files in the specified directory.

DirSortType - Integer enumeration. This determines the order of the files in the FileList collection. It must be set before the DirName property. Available values are 0 - alphabetical ascending, 1 - alphabetical descending, 2 - date order ascending, 3 - date order descending. The default is 0. For date sorting it is the last modified date that is used.

Delete FileName - This deletes the file specified by the physical path FileName. Note that it is permanently deleted NOT placed in the Recycle Bin. FileName is a string.

Copy OldName, NewName - This copies the file OldName to the location and name given by NewName. Full paths are required. OldName and NewName are strings.

Rename OldName, NewName - This renames the file OldName to NewName. Physical paths are required. Renaming to a different directory is the equivalent of moving the file. OldName and NewName are strings.

GetFileName(Path) - This function returns the file name, complete with extension but without the directory structure, where Path is a physical path and file name. Path is a string.

GetExtension(Path) - This function returns the extension, complete with the period character, where Path is a physical path and file name. Path is a string.

AppendToFile FileName, NewLine - This function appends the string NewLine to the text file FileName. If the text file does not exist it will be created if possible. The physical path is required. FileName and NewLine are strings.

Example:

This will append the line "Testing" at the end of a text file called "test.txt" which is in the same directory as the script. If the file does not exist it will create it.

AppendToFile is the only command in this component for manipulating text files. It is useful for maintaining a simple log or to assist in debugging. For a complete set of commands for working with text files, use the File System Object.

All the file handling routines require that the Internet Guest User account has the appropriate permissions. If files are to be accessed across a network, Component Services will need to be configured as described in Section 1.4.

GetTickCount - Integer property, read only. This returns the number of milliseconds that have elapsed since the computer was switched on. It can be used for timing sections of code.

Example:

This will display the number of milliseconds taken for the code to run. If it is less than 0.5 milliseconds it will return zero.

12.1. Finding Image Dimensions

The following methods and properties allow the dimensions of an image to be found without loading it into the component memory. This avoids the need to decode a compressed image and so image dimensions can be found quickly if that is all that is required. This functionality will continue to work in the trial version even after the expiry date.

GetDimensions FileName - FileName is a string and is the physical path to the file. This populates the four read only properties described below. It will raise an exception if the file cannot be found or opened but will simply set the properties to zero if the file is in an invalid format.

GetDimensionsBin FileStream - FileStream is a variant array containing an image. This populates the four read only properties described below. It does not raise an exception on failure.

If the file is a multipage TIFF the page read is determined by the ReadImageNumber property.

ReadWidth - Integer, read only. The width of an image in pixels tested by GetDimensions or GetDimensionsBin.

ReadHeight - Integer, read only. The height of an image in pixels tested by GetDimensions or GetDimensionsBin.

ReadXDPI - Integer, read only. The horizontal pixel density of an image tested by GetDimensions or GetDimensionsBin, measured in dots per inch.

ReadYDPI - Integer, read only. The vertical pixel density of an image tested by GetDimensions or GetDimensionsBin, measured in dots per inch.

13. Web Examples

There are a number of web pages on the Chestysoft web site that provide further reference. These include some tips on getting started and troubleshooting, code examples that can be downloaded, and working examples on our demonstration site.

ASP Examples: www.chestysoft.com/imagefile/examplesasp.asp

Cold Fusion Examples: www.chestysoft.com/imagefile/examplescf.htm

Both of these pages contain links to all the available examples and tutorials.

14. Supported Image Formats

csImageFile supports the reading and writing of files in most popular formats commonly found on the web. These formats are briefly summarised here.

14.1. BMP (Bitmap)

BMP is the standard graphics format for Windows systems. The image is stored uncompressed and can be in either 24 bit or a paletted format. The palette can be either 256 colour (8 bit), 16 colour (4 bit) or monochrome (1 bit).

Bitmaps are usually larger file sizes than other images because they are uncompressed but they are often faster to import and export because there is no compression to calculate.

14.2. JPG / JPEG / JPE (Joint Photographic Experts Group)

The JPEG file format is probably the most common method of saving full colour images, typically photographs, when a high level of compression is required. It uses a "lossy" compression method, which means that the image read from a saved file will not be identical to the original image before it was saved.

Repeated loading and saving of a JPEG file will result in deterioration of the quality, and should be avoided, but at the levels of compression typically used for saving photographs, the loss of quality is hardly noticeable when the file is saved once from its original. The type of compression used by JPEGs does not produce good quality images that contain sharp edges and text as these edges often become blurred on saving, even using a low compression level. The JpegQuality property controls the amount of compression used when a JPEG is saved.

JPEG compression / quality is not a universal value and different software packages use different scales. It cannot be read directly from an image, although csImageFile has a read only property, JpegApproxQuality, that gives an approximate value. This could be useful when reading images that have already been compressed in order to save them again with a similar level of compression. If JpegQuality is set to a higher value than that originally used to save the image, the new image will have a larger file size without gaining any quality, and it is better to avoid this if possible.

JpegApproxQuality - Integer in the range 0 to 100, read only. When a JPG is loaded, this property contains an approximate value for the compression (quality) used when the image was saved. It corresponds to the same range of values as JpegQuality except 0 indicates the value is undefined.

JpegApproxQualityError - Double, read only. When a JPG is loaded, this property contains an indication of the accuracy of the JpegApproxQuality property. A lower value indicates a higher level of accuracy. A value of less than 1 indicates that JpegApproxQuality is a reliable measure of the quality while a value of tens or hundreds indicates that JpegApproxQuality is merely an approximate estimate.

JPEG files stored in CMYK colour space can be read by csImageFile and are automatically converted to RGB. The WasCMYK property is set to true to indicate a conversion has taken place. Saving to CMYK is not supported.

IPTC text (File Info) and Exif data can be stored in JPEG files and this data can be read and edited with csImageFile. This meta data can be removed by calling the ClearMetaData method, and this can reduce the file size.

JPEG images are usually stored as 24 bit RGB images but they can also be stored as 8 bit greyscale. See the JpegGrayScale property for details.

csImageFile provides an option for opening JPEG files at a higher speed while reducing image quality. This can be useful if speed is important, for example when creating thumbnails dynamically. Set the JpegHigherSpeed property to true before loading the image for this to take effect.

14.3. GIF (Graphics Interchange Format)

GIF format saves files using 256 colours or less. It can compress images with large areas of a single colour very efficiently and is commonly used in web pages for backgrounds, logos, etc. The compression is "lossless". GIFs use the LZW compression method.

GIF images support the use of a transparent colour. See the Transparent and TransparentColor properties for details.

GIF files can contain multiple images (or frames) and these are usually used to create animations for use in web pages. Prior to version 8.2, csImageFile did not support multi frame GIFs and only read the first frame. From version 8.2 some multi frame support has been added and individual frames can be extracted and images can be assembled into a multi frame GIF. See Section 2.5 for details of properties and methods related to multi frame GIFs. For more comprehensive multiframe support, we have a component called csASPGif - www.chestysoft.com/aspgif/default.asp.

14.4. PNG (Portable Network Graphics)

The PNG format provides an efficient lossless compression of image data and it uses the same compression method as zip files. It provides a wide range of colour depths, but these are not all supported for writing by csImageFile, although they can be read. Supported colour depths are 24 bit, 8 bit, 4 bit and 1 bit. Paletted images support single colour transparency in the same way as GIF files or they can specify a variable amount of transparency for each palette entry.

The PNG format also allows for an alpha channel where a transparency amount is specified for each pixel. csImageFile supports this from version 6.4, and the alpha channel can be used when images are merged. An image with an alpha channel can be resized, rotated, cropped or flipped while preserving the transparency. Any other editing will clear the alpha channel unless instructed otherwise by setting the KeepAlpha property. If the image is exported to another format, the pixels are merged with the background colour of the PNG image and the alpha channel is lost.

Version 8.5 of csImageFile introduces support for some PNG meta data. This includes the textual information that is defined in the PNG specification, and consists of some named properties. It also includes Exif, which is defined in an extension to PNG, and the XMP properties, described in Sections 6.2 and 6.3.

14.5. TIF / TIFF (Tagged Image File Format)

The TIF file format allows images to be stored in many different ways. The baseline TIF specification is fully supported by csImageFile and this allows for images to be stored as 24 bit RGB, paletted (8 bit or 4 bit), greyscale or black and white. The image can be uncompressed or stored using the Packbits compression method which is a lossless run-length compression.

In addition to the baseline specification, some extensions to the TIF format are supported as described below.

Images stored using the CCITT Group 3 or Group 4 fax compression schemes can be read. Files can be written using Group 4 compression. These compression schemes apply to black and white images only and are very efficient.

Files stored in CMYK colour space can be read and are automatically converted to RGB. The WasCMYK property is set to true to indicate a conversion has taken place. Saving to CMYK is not supported.

Files stored using LZW compression can be read, but this compression method is not available for writing.

TIF files can contain multiple pages and support for this is described in Section 2.4.

IPTC text (File Info) and Exif data can be stored in TIF files. csImageFile supports IPTC as described in Section 6. Exif is not currently supported.

There are further extensions to the TIF format that are not supported by csImageFile including JPEG compression, YcbCr and LAB.

14.6. PSD (Photoshop Format)

This is the standard format used by Adobe Photoshop to save images. A PSD file can contain multiple layers of an image, as well as the composite image created by combining the layers together. As csImageFile only holds a single image, it simply reads the composite image and ignores the layers. A PSD file saved by csImageFile will only have a composite image and no layers.

Files stored in CMYK colour space can be read and are automatically converted to RGB. The WasCMYK property is set to true to indicate a conversion has taken place. Saving to CMYK is not supported.

Reading and writing IPTC text (File Info) in PSD files is supported.

14.7. PCX Format (ZSoft Paintbrush Format)

PCX is an old format for saving images of all colour depths. It uses a simple run length encoding compression system which is lossless but not very efficient. It is not commonly used today.

14.8. WBMP / WBM (Wireless Bitmap)

The WBMP format is used by WAP devices. It only supports black and white images.

14.9. PDF (Portable Document Format)

csImageFile can save images to PDF files. The images are always saved one per page, with the page size set equal to the image size.

Images are exported to PDF by using the WriteFile method with ".pdf" used as the file extension, or by using the PDFData property.

Multiple images can be saved to a PDF file by building the PDF pages in memory with the AddToPDF method.

The following properties allow the property tags of PDF files to be set before they are saved. They are all strings and their use is self-explanatory. All are empty strings by default.

PDFTitle - String.

PDFSubject - String.

PDFAuthor - String.

PDFKeywords - String.

For more advanced PDF creation functions we recommend using the PDFBuilderASP component from Ciansoft.

PDF (Portable Document Format) is copyright of Adobe Systems Incorporated.

15. Revision History

The current version of csImageFile is 8.5

The main changes since version 4.0 are described below.

New in version 4.0

Support for PSD and TIF files added.
Support for compressed GIF files added.
File Info properties now include support for .XMP file format.
EXIF attributes can now be read from JPG files.
FileList collection added.
ReadURL can now identify files from the MIME type.
Basic Authentication password and username added to ReadURL method.
ConvertToBW method added.

New in version 4.1

TIF support extended to include LZW and Group 4 compression.
JPG and TIF images using CMYK colour space can be read.
OLE_COLOR conversion functions added.
Polygon method added.
SharpenBy and BlurBy methods added.
ProgressiveJpeg property added.
Use of a bitmap as the fill pattern included.
Unicode support added to Text method.

New in version 4.2

Antialias property for text and drawing functions.
TextJustify property.
Carriage returns can be used with the Text method.
OverwriteChr property.
WasCMYK property.
TIF support extended to include Group 3 compression.

New in version 4.3

OverwriteMetaData method added.
Additional IPTC fields supported.
PSD images using CMYK colour space can be read.
MergeFrontHDC and MergeBackHDC methods added.
Modifications to ReadURL allowing SSL connections and Integrated Windows Authentication.

New in version 4.4

Changes to the way antialiased text is drawn. This is not fully compatible with previous component versions although the overall results are improved. Now the ColorDepth property must be set to 24 before drawing the text, and small font sizes will not be antialiased.
IPTC support added for TIF images.

New in version 5.0

Images can now be read when they have the wrong extension, or in the case of binary imports, when the format is not known. ReadVariant, OriginalImageType, IgnoreInputFileType added.
Arc3XY, Circle3XY, CircleCR and PolyBezier methods added.
BlurText property added to allow text to be antialiased as versions 4.2 and 4.3.
ResizeFit added to resize to a specified maximum width and height.
Support for 8 bit greyscale JPEGS, JpegGrayScale property added.
Multi-page TIF support.
Exif support upgraded to Exif version 2.2 with ability to write attributes.

New in Version 6.0

Support for ICC colour profiles.
Palette method and properties added.
Text drawn with TextWrap can now be justified.
ArcText method added.
PixelArray property added.

New in Version 6.1

Images can be exported to PDF.
ReadMetaData method added.
ExifUserComment property added.
HTTPUserComment property added.
Colours are now added to a palette when they are used.

New in Version 6.2

Alpha transparency preserved from PNG images and used in merge functions.
MergeBin and MergeBackBin automatically use transparency details from foreground image.
BGColor property renamed to TransparentColor (BGColor can still be used).
ICC colour profile support extended to TIF images.
OverwriteMetaDataBin method added.
DirSortType property added.
HTTPTimeout property added.

New in Version 6.3

IPTC support extended to include the XMP based IPTC Core Schema.

New in Version 6.4

IPTC support for TIFFs extended to include the XMP based IPTC Core Schema.
XMPPriority property added.
TextTranspercent added.
Hue, Lightness and Saturation conversion methods added.
PDFTitle, PDFSubject, PDFAuthor and PDFKeywords properties added.

New in Version 7.0

Functionality to import, export and edit alpha channels.
Meta data support for people tagging.
XP Summary data properties.
Invert method.
GetDimensions and GetDimensionsBin for finding image sizes without fully loading an image.
DeleteTrailingData method for improved meta data compatibility.
FFO_Rating anf FFO_RatingPercent properties.

New in Version 8.0

64 bit version available.
StreamToBrowser method added.
KeepExifThumbnail added.
ColorReplace method added.
XMP support extended to PSD.
Ability to merge two images with alpha channels added.

New in Version 8.1

Additional support for partially transparent palette in PNG images.
Fix to intermittent bug in handling GIF images.

New in Version 8.2

Limited support for animated GIF images.

New in Version 8.3

Base64 input and output.
Limited support to read embedded images from PDFs.

New in Version 8.4

Support for some IPTC Extended Properties.

New in Version 8.5

Support added to PNGs for EXIF, XMP and Textual Information.

16. Other Products From Chestysoft

ActiveX Controls

csXImage - An ActiveX control to display, edit and scan images.

csXGraph - An ActiveX control to draw pie charts, bar charts and line graphs.

ASP Components

csImageLite - A cut-down version of csImageFile for resizing and merging images.

csDrawGraph - Draw pie charts, bar charts and line graphs in ASP.

csASPGif - Create and edit animated GIFs.

csASPUpload - Process file uploads through a browser.

csASPZipFile - Create zip files and control binary file downloads.

csFileDownload - Control file downloads with an ASP script.

csFTPQuick - ASP component to transfer files using FTP.

17. Alphabetical List of Commands

Click on one of the links below to go directly to information about that command: