ReadImage

The ReadImage function reads an image file in GIF, JPEG, BMP, WMF, PNG, TIFF format, or from Picture object.

ReadImage sFilename[,aPalette][,startX][,startY][,bUseTransparency][,iFramesCount]

Parameters

sFilename
Specifies the name of the file to read.
You can specify the binary safearray instead of file name string. In this case the necessary day will be get from that array. Using FileStart and FileSize properties, you can set where the image data are located in the array.
It can be also other ShotGraph object.

aPalette
Optional, output. If the function has been finished successul, contains the two dimensional array with image palette. The first index of array is the color number. The second index of array (0..2) is accordingly red, green, and blue color component. The lower bound of array is always zero.
If being read file does not contain any palette information, the value remains uninitialized. To check that you can use the IsArray function of VBScript.
In VBScript, use UBound function to know the image palette size:
UBound(aPalette)+1

startX
Optional. Specifies the x-coordinate where do draw the image. Can be negative.

startY
Optional. Specifies the y-coordinate where do draw the image. Can be negative.

bUseTransparency
Optional. Specifies whether the image transparency information will be used to draw image. GIF and PNG images may contain transparent areas. If the image does not contain transparency information, this parameter is ignored. The default value is True (the image transparency is used).
iFramesCount
Optional. If specified, this output parameter returns amount of frames in the GIF image (or amount of pages in TIFF image). Using this parameter, you have an opportunity to tell the animated GIF images from static one. The frames count is more than one for animated images.

Return value

This function returns the same value as GetFileDimensions if successful, overwise zero.

Remarks

The function can read image files in GIF, JPEG, BMP, WMF, PNG, TIFF format. The top left corner of the image rectangle is defined by startX,startY point on the coordinate space. The function supports transparency information in GIF and PNG images. So if the file contains information about transparency then being read image will have overlaped the underlying picture properly.

The image palette, returned by function, can be not matched to real image colors. This depends on the file structure and subformats. Moreover, the palette information can be absent in the image file. To get the proper resulting output image in the end of the script job you should either save the image into true color format (JPEG or true color PNG) or use WebPalette, BuildPalette or ApplyPalette just before creating GIF image or paletted PNG.

Vector (WMF) images
The function can read WMF files only if the AdvancedCheck property is set to True. The VectorSizeX and VectorSizeY properties also affect the vector image drawing.

Multipaged TIFF images
By default, the ReadImage reads the first page of TIFF image. In case if TIFF image contains two or more pages then you can instruct the method to read specified page. Call the SetInstantParameter method passing two parameters: the "TiffFrameNumber" string and zero-based frame number. The value will be set before the ReadImage call, after that it will be reset to zero again. Therefore, if you want to call the ReadImage with different frame numbers several times one after another then you should call the SetInstantParameter before every ReadImage call:
g.SetInstantParameter "TiffFrameNumber",4
g.ReadImage tiff_file,palette,0,0

Possible data types for 'sFileName' parameter
Data typeMeans
StringPath to file. The image will be read from that file.
SafearrayImage into safearray. The image will be read from safearray.
ShotGraph objectThe image will be read from active imagespace of other ShotGraph object.

Example
This example demonstrates the differernt ways of mixing the dragon image file, dragon.gif, with ShotGraph image picture.

filename="d:\dragon.gif"
set obj=CreateObject("shotgraph.image")
obj.GetFileDimensions filename,xsize,ysize
obj.CreateImage xsize,ysize,256
obj.SetColor 0,255,255,204
obj.SetColor 1,255,51,51
obj.SetBgColor 0
obj.FillRect 0,0,xsize,ysize
obj.CreatePen "PS_SOLID",2,1
obj.SetTextColor 1
obj.SetBkMode "TRANSPARENT"
obj.CreateFont "Arial",204,56,0,True,False,False,False
obj.SetTextAlign "TA_LEFT","TA_TOP"
obj.TextOut 20,10,"String 1"
obj.SetTextAlign "TA_RIGHT","TA_BOTTOM"
obj.TextOut xsize-20,ysize-10,"String 2"
obj.Line 0,ysize-1,xsize-1,0
obj.ReadImage filename,pal,0,0
obj.BuildPalette 2
obj.GifImage -1,0,"d:\test.gif"
Result:

The second script is similar the previous one except the dragon GIF image is read before drawing text strings and line


filename="d:\dragon.gif"
set obj=CreateObject("shotgraph.image")
obj.GetFileDimensions filename,xsize,ysize
obj.CreateImage xsize,ysize,256
obj.SetColor 0,255,255,204
obj.SetColor 1,255,51,51
obj.SetBgColor 0
obj.FillRect 0,0,xsize,ysize
obj.CreatePen "PS_SOLID",2,1
obj.SetTextColor 1
obj.ReadImage filename,pal,0,0
obj.SetBkMode "TRANSPARENT"
obj.CreateFont "Arial",204,56,0,True,False,False,False
obj.SetTextAlign "TA_LEFT","TA_TOP"
obj.TextOut 20,10,"String 1"
obj.SetTextAlign "TA_RIGHT","TA_BOTTOM"
obj.TextOut xsize-20,ysize-10,"String 2"
obj.Line 0,ysize-1,xsize-1,0
obj.BuildPalette 2
obj.GifImage -1,0,"d:\test.gif"
Result: