Newsletters #6

Newsletter number 6 addresses another interesting topic: All 32 bit Microsoft Windows versions are shipped with Eastman Kodak's Imaging program. At a first glance this is an application useable to process graphics and scan images. On most computer systems this program isn't installed (because it is an optional Windows component, and most users prefer other applications). But Imaging is a little Gem: The Imaging program itself may be used as a COM server (similar to Internet Explorer or Microsoft Office applications). In addition, there are a few ActiveX controls supporting also the objects admin, edit, ocr, scan or thumb that allow scripters to manipulate graphic files. After installing Imaging, also the ActiveX controls are installed and registered on the target system.

These pearls are buried for years in the heap of files cluttered over my hard disk. It's like searching a needle in a hay stack - how hard might it bee to find this needle, if you have no idea that there is a needle? A short article in a German computer magazine and a view in the Windows SDK brought me to the right track. Although this article deals mainly with HTML files and doesn't provide too much detailled information about WSH scripting, it contained a few URLs to Eastman Kodaks web site (promising to lead to the programmers documentation). And on this site the "search for the needle" continues - they re-designed their site, so the links was no longer valid.

I spend one Saturday of investigation and experimenting how to use Imaging and its controls. With that know how and some samples it may be possible to create your own power script that uses Imaging as a helper to access graphics, print them, copy and paste to/from clipboard or to convert files. So let's talk about the details.

(c) Günter Born, http://www.borncity.de

Warning: The material submitted as a newsletter comes AS-IS without any warranty of any kind. In no event shall the author be liable for damages and losses of any kind. The material discussed herein is copyrighted by the author. You get a free right to use it. This newsletter may be distribute freely as long as: a) the zip-archive News6.zip remains intact and unmodified, b) a reference to the WSH Bazaar www.borncity.de is given and c) the newsletter is not shipped with other commercial material. If you like to ship the newsletter with CD-ROMs etc. please ask. Permission will be granted in normal cases, but I like to know where my material goes into.

Where do you get your help today?

Did I mentioned already that you got some pearls on your Windows hard disk? Well, its not only the Imaging program and its ActiveX controls itself. Also there is a complete programmers reference about these controls on your hard disk. I couldn't believe after I found that out today.

Well here is the story: After I noticed that Imaging is a scriptable component, I begun to investigate the ocx files in Object Browser. Unfortunately the programmers left no additional information about the methods and properties, so the Object Browser displays only the methods, their parameters and the properties supported by the objects. (BTW: I described the technique how an ActiveX controls designer may add short descriptions to a control in my WSH books and in the WSH Tutorial.) So I visited Eastman Kodak's web-site:
http://www.eastmansoftware.com/support_pro/Documentation/document_pro.htm
and downloaded their ActiveX Controls Reference, a help file describing the ActiveX controls programming interface for Imaging Pro. Unfortunately I wasn't as successful as I wished using the information provided in that help file. My hugest problem was: The help file was for Imaging Pro, so the help let me in in many places in doubt what exactly need to be used to call a method or access a property. And my experience was that not all methods was implemented in a way I wished. For instance, I found no property to read back the file type selected within a SaveAs dialog box. Also I missed the information about the objects a method or property belongs to. The samples shown in the help was written for Visual Basic (which isn't a principal problem for me), but there too much missing. Also the Windows SDK doesn't provide the necessary scripting samples demonstrating the details.

So I took the "stoney" way and went step-by-step to find out how to use Imaging within WSH scripts. At least I was successful, but here comes the joke: Because I could not find something about the Imaging COM server that provides the application object, I visited the Eastman Kodak website again. I could not found the requested info, but somewhere in a "dark" corner there was a FAQ file reporting me several interesting things. Here is a short excerpt what they tell us:

Where is the documentation for the Imaging ActiveX (OLE) controls?
The online Help file for the controls is in the Windows\Help folder. This file is named Imgocxd.hlp in Imaging Professional 2.0. Besides describing the syntax of the .OCXs, it contains code examples for Visual Basic and C++. (Previous versions of this Help file were named Wangocxd.hlp (Imaging Professional 1.1, Imaging for Windows 95, and Imaging for Windows NT)).
....
The baseline Imaging for Windows controls are also described on Microsoft's MSDN Library CD under Tools and Technologies, Third Party Contributors.
....
You can download an up-to-date version of the Imaging ActiveX Automation documentation from this site. A previous version is on Microsoft's MSDN Library CD under Tools and Technologies, Third PartyContributors.

Wow, have you ever searched your hard disk for a file like Imgocxd.hlp? I'm not! In my worsest dreams I don't spend any thought that such a thing might be on my hard disk (althought I recognized that Microsoft brought us a many interesting help files to our operating system folders). OK, to be precise: I found the help file on my Windows 98 machines (could not verify Windows 95 and Windows NT 4.0). In Windows 2000 the help file is no longer shipped, and the samples introduced below won't work on this platform (only the sample using Imaging as a server is platform independent). If you miss the help files, you may download them from the Eastman Kodak web-site. Their Image Pro help file contains also code samples that are not included in the help file I found in my German Windows 98 (but this help file is more accurate than the Image Pro 2.x help file).

Scripting with Eastman Kodak Imaging

OK, after obtaining the necessary help files, let's go into the details. Imaging itself may be used as a COM server for scripting. Although this component isn't documented at all in the ActiveX Controls Reference, I found ways to access this object. The COM server itself will be registered with the progID "Imaging.Application" after installing Imaging. The following statement creates a reference to the Imaging application object:

Set oApp = CreateObject ("Imaging.Application")

Afterward this object reference may be used to access the methods and properties of the Imaging program. The following code sequence use the object variable oApp to set several properties of the application object. The names are self explanatory. We hide or show the toolbars. The FitTo property defines how to fit an image into the display area (I have defined the necessary values as constants in the script's header).

' Set the toolbars and other properties
oApp.ImagingToolBarVisible=0    ' no Toolbar
oApp.ScanToolBarVisible=0       ' no Scan Toolbar
oApp.StatusBarVisible=1         ' Statusbar
oApp.ToolBarVisible=1           ' Toolbar
oApp.Edit = 1                   ' editable
oApp.FitTo BEST_FIT             ' Image fit

text = "Application: " & oApp.Name & vbCrLf & _
       "Path: " & oApp.Path & vbCrLf & _
       "Zoom: " & oApp.Zoom & vbCrLf

The last line reads some properties of this object. We may read the application name, the zoom factor or the program path. To use the image viewer, we need to create the related object. This may be done using the CreateImageViewer method. Then we may use the Open method to load an image file:

Set oImg = oApp.CreateImageViewerObject (1)
oImg.Open GetPath() & file      ' Load bmp image 

After obtaining an object reference to the viewer object, we can access the image properties and apply methods to this object. The following VBScript sample program creates a copy of the image viewer, shows the viewer and reads a bmp file. Then several dialog boxes are asking to rotate the image, to save the image in Tiff format and print the graphic. Further details about the related methods and the necessary constants may be obtained from the following listing.

'************************************************
' File:    ShowImaging.vbs (WSH sample in VBScript) 
' Author:  Günter Born
'
' Demonstrates how to use Eastman Kodak Imaging
' as a COM server show and convert an image.
'************************************************
Option Explicit

Const BEST_FIT = 0	' Fits image to window size
Const FIT_TO_WIDTH = 1	' Fits image to window width
Const FIT_TO_HEIGHT = 2	' Fits image to window height
Const INCH_TO_INCH = 3	' Maintains the relative size 

' Fileformats
Const wiFileTypeTIFF = 1 ' Tag Image File Format
Const wiFileTypeAWD = 2  ' At Work Document (MS Fax)
Const wiFileTypeBMP = 3  ' Microsoft Bitmap Format
Const wiFileTypePCX = 4  ' ZSoft PCX
Const wiFileTypeDCX = 5  ' modfied ZSoft PCX for Fax
Const wiFileTypeJPG = 6  ' JPEG
Const wiFileTypeXIF = 7  ' Xerox image documents
Const wiFileTypeGIF = 8  ' Graphic Interchange Format
Const wiFileTypeWIFF = 9 ' Wang Image File Format

Const title = "Born's Imaging Tester"

Const file = "Test.bmp"
Const file1 = "Test.tif"

' define object variable for reference to Internet Explorer
Dim oApp                ' Imaging Application object   
Dim oImg                ' image object

Dim ImgType 
Dim text, tmp

ImgType = Array ("unknown","Tiff", "Awd", "Bmp", _
                 "PCX", "DCX", "JPG", "XIF", _
                 "GIF", "WIFF")

' create object reference to Imaging Application object
Set oApp = CreateObject ("Imaging.Application")

' Set the toolbars and other properties
oApp.ImagingToolBarVisible=0    ' no Toolbar
oApp.ScanToolBarVisible=0       ' no Scan Toolbar
oApp.StatusBarVisible=1         ' Statusbar
oApp.ToolBarVisible=1           ' Toolbar
oApp.Edit = 1                   ' editable
oApp.FitTo BEST_FIT             ' Image fit

text = "Application: " & oApp.Name & vbCrLf & _
       "Path: " & oApp.Path & vbCrLf & _
       "Zoom: " & oApp.Zoom & vbCrLf '& _ 
'       "Scanner: " & oApp.ScannerIsAvailable & vbCrLf 

MsgBox text, vbInformation + vbSystemModal, Title

' Now create the viewer object
Set oImg = oApp.CreateImageViewerObject (1)
oImg.Open GetPath() & file      ' Load bmp image 

' retrieve Image properties
text = "File: " & GetPath & file & vbCrLf & _
       "Filetype: " & ImgType (oImg.FileType) & vbCrLf & _
       "Height: " & oApp.Height & vbCrLf & _
       "Save Image as TIFF?"

tmp = MsgBox (text, vbYesNo + vbSystemModal, Title)

If tmp = vbYes Then        ' save file as Tiff
 oImg.SaveAs GetPath() & file1, wiFileTypeTIFF 
 MsgBox "File " & GetPath() & file1 & " saved", _
         vbSystemModal, Title
End If

If MsgBox ("Rotate image?", vbYesNo + vbSystemModal, _
         Title) = vbYes Then     ' rotate image
  oImg.RotateAll
End If

If MsgBox ("Print image?", vbYesNo + vbSystemModal, _
         Title) = vbYes Then     ' rotate image
  oImg.Print
End If

WScript.Echo "Close Imaging and terminate"
oApp.Quit                     ' Close Imaging
WScript.Quit                  ' Close Script

' ### Helper ####
Function GetPath()
' Retrieve the script path
 DIM path
 path = WScript.ScriptFullName  ' Script name
 GetPath = Left(path, InstrRev(path, "\"))
End Function
' End 

The code may be used as a foundation for a "batch converter" reading a collection of input graphic files and convert them automatically to an output format. Using the FileSystemObject object allows you to access all files within a folder and read their names. I have tested this code in Windows 98 and in Windows 2000. The only disadvantage of this approach: I wasn't sussessful to access other objects, so it was not possible to do things like rotate one image within an image set or similar things. But this may be done with the ActiveX controls discussed below.

Scripting with Eastman Kodak Imaging ActiveX controls

Imaging installs also a few additional ocx files that allow you to administrate, edit, scan or handle images in different ways. Would it not be nice to use these controls from your WSH scripts to create your own image processing application? Unfortunately there is also the problem (similar to the Adobe Acrobat Reader control) that the objects provided by these ActiveX controls may not loaded directly from a script. The controls need a window to be shown, otherwise WSH reports a runtime error "Catastropic failure". I used the same approach with the Adobe Acrobat Reader control: I embeded them into a HTML page. And this page may be loaded into Internet Explorer unter a script's control. There are several controls that may be embedded into the HTML page.

The solution might provide a window that embeds the control. The Internet Explorer may be the right tool for that purpose. We can create a HTML document using Microsoft Frontpage and insert the ActiveX control Pdf.ocx into that page. You can use Microsoft FrontPage Express to insert the controls into a blank page, then you need to add the id attribute to any <object> tag (because this attribute defines the object name of a control). The code of this HTML page is shown below:

<html>
<head>
<meta http-equiv="Content-Type"
content="text/html; charset=iso-8859-1">
<meta name="GENERATOR" content="Microsoft FrontPage Express 2.0">
<title>Born's Imaging Viewer</title>
</head>

<body bgcolor="#FFFFFF">
<object id="admin"
 classid="clsid:009541A0-3B81-101C-92F3-040224009C02"
 width="1" height="1">
</object>

<object id="edit" 
 classid="clsid:6D940280-9F11-11CE-83FD-02608C3EC08A"
 width="100%" height="100%">
</object>

<object id="scan"
 classid="clsid:84926CA0-2941-101C-816F-0E6013114B7F" 
 width="1" height="1">
</object>
</body>
</html>>

I have embeded three objects within the HTML page and named them admin, edit and scan. These three objects provides methods to access Imaging, to edit and manipulate images and to access a scanner using the Twain interface.

Note: Loading this HTML page shows only a gray rectangle, because we haven't inserted an image. Also some of the controls are set to a size of 1x1 pixel, because they don't have visible elements (like the scan object). Unfortunately the HTML document file won't work in Windows 2000. Loading the file shows a page with the placeholder for missing controls.

A sample: Loading an image, and demonstrate how to manipulate, save and print it

In a simple VBScript program I like to demonstrate how to use the new technology to access image files. The following code listing shows the whole beef.

The script uses a simple procedure call to create an Internet Explorer instance and loads the predefined HTML file:

MakeHTMLPage "imaging.htm"

Then we can use the techniques already discussed in previous newsletters to access the objects within the document object. To create a reference to the admin object, we use the statement:

Set oAdmin = oIE.Document.All.admin

The name admin was defined via the id attribute value of the <object> tag in the HTML document. Then the script may prepare the control to open a file open dialog using the following statements:

oAdmin.Flags = CHECK_READONLY + SET_CURDIR + HELP_BUTTON
oAdmin.DialogTitle = "Born's Open dialog"
oAdmin.Filter = "All image files|*.tif;*.bmp|" & _
"TIFF files|*.tif|" & _
"BMP files|*.bmp|" & _
"All files|*.*|"
oAdmin.FilterIndex = 3 ' set bmp filter
oAdmin.InitDir = GetPath() ' set initial directory
oAdmin.CancelError = false ' Cancel causes no run-time error

oAdmin.ShowFileDialog open ' Show Open dialog

The ShowFleDialog method provided from admin may be called with the parameter 0 to invoke the Open dialog. The dialogs title may be set using the DialogTitle property. The Filter property defines the file extensions accessible trought the dialog. The initial folder may be set using the InitDir property. At this place I like to mention that the dialog box raises a run-time error, if the user clicks the Cancel button. The script can set the CancelError property to false to suppress this error. After closing the dialog box window, the selected file name may be obtained with the following statement:

filein = oAdmin.Image

To load and view an image, the script need a refence to the edit object (the 2nd control included in the HTML document).

Set oEdit = oIE.Document.All.edit ' get edit object
oEdit.Image = filein
oEdit.AutoRefresh = true
oEdit.Zoom = 100
oEdit.Display

The first line creates a reference to the object. Then the Image property is set to the graphic file's path and name. The Display method shows the graphic file within the control. The control's properties height and width are set to 100% to allow viewing the graphics.

Afterward the script may use other methods provided by the objects. So it is possible to rotate or flip the image using the edit control. Saving the image may be done also using the SaveAs method. To obtain the name of the output file, you can use also the ShowFileDialog method with the parameter 1. The problem I identified is: I couldn't find any property to return the file type the user selected within the Save As dialog box. Maybe it's my fould, at least I gave up (the FileType property returned a wrong result). I solved the problem with two functions: GetFileExt() and GetFileType(). GetFileExt() extract the file extension from the name returned from the dialog box. If no extension is given, the function sets the default value .tif. Then we may use GetFileType(), that function returns a file type code depending on the extension passed as a parameter. Further details may be obtained from the code listing above.

Sample 2: Scan as your scanner can

The HTML document shown above contains also the scan control. If the system is equipped with a scanner, Imaging installs a Twain interface. This interface may be accessed using the scan object. The following line may be used to create an object reference:

Set oScan = oIE.Document.All.scan

Then the script needs three statements to create a scan:

oScan.ScanTo 0 ' display scan
oScan.ShowScanPreferences
oScan.StartScan

The first line defines where the scan object shall "write" the scanned data. The value 0 displays the data in the edit control. There are other values allowing the object to send the data into a file on into a template. This is required before printing or copying to clipboard. Copying to the clipboard is a bit fussy. The ClipBoardCopy method provided by the edit object requires the coordinates of a rectangle of the image area. After a scan the method raises a run-time error reporting that the file isn't found. Therefore we need to save the scanned image to a temporary file before the method is accessed. Let's have a look at the following code snippet:

oEdit.Image = GetPath() + "Temp.bmp"
oEdit.SaveAs oEdit.Image
oEdit.AutoRefresh = true
oEdit.Display
tmpflag = true ' set flag

' copy whole image to clipboard
oEdit.ClipboardCopy 0, 0, oEdit.ImageWidth, oEdit.ImageHeight
If MsgBox ("Read Clipboard data?" _
, vbYesNo + vbSystemModal, Title) = vbYes Then
If oEdit.IsClipboardDataAvailable Then
oEdit.ClipBoardPaste
MsgBox "Image pasted", vbSystemModal, Title
End if

The first lines saves the graphic data into a temporary file. Then the clipboard methods ClipboardCopy and ClipboardPaste may be used. To find out whether data are available in the clipboard, the script may use the IsClipboardDataAvailable method of the edit object. Printing may be done using the PrintImage method of the edit object. I have discussed this feature above. Further details may be obtained from the following VBScript code listing.

The necessary constants used as parameters for methods are defined in the script header. More detailled information about the methods and properties may be found in the help files mentioned above. The scripts provided here shows the principles of using the Imaging controls. There are many other methods and properties not already introduced here. The script allows you to handle graphic files. And here is the ZIP archive with the sample files: News6.zip. Ok, that's all for this time. I continue to present new technologies for WSH scripters soon. Further samples and details may be found also in my WSH Bazaar. Have a look at the sample page and at the WSHExtend Programmers Reference.

Planned topics for newsletter #7 and future newsletters:

• For instance I have an ShellExtend.ocx control that allows deleting to Recycle bin, emptying the Tray or that enables a script to print any registered document file type....
• ....

If I have time, I will introduce ADO, ADSI and WMI stuff. Enyoy scripting, till the next newsletter arrives...

... and all registered users of my WSH Tutorial will receive the first update dealing about ADO, ADSI and WMI within the next days.

(c) G. Born, 01 - April 2000 - www.borncity.de