Image Acquisition in Director

Developing applications with Macromedia Director you may face the necessity of image input from devices like scanners or digital cameras. There are a lot of reasons for this. You may need to allow user's image input so your customers are able to acquire images, modify them right in your application, print them and save the result. Practically all virtual make over CD titles require image acquisition functionality and there's an infinite number of subjects to change - from architectural objects to hair styles. This way users can create digital photo archives, share their creations with friends by email or uploading to a web site, etc. Placing custom images to Director's digital world allows your applications a new level of interactivity and functionality. In this article we will examine for possible solutions and try to find the answer on "How to?" question.

TWAIN is an Application Programming Interface (API) that standardizes communication between applications and image acquisition devices such as scanners or digital cameras. It allows to make standard calls to any image acquisition device that supports TWAIN interface so the application would not have to be rewritten to support every single device. You can find more information about TWAIN at http://www.twain.org. TWAIN exists since 1992 and most of modern scanners and digital cameras support it. Epson PhotoPC 800 and Canon PowerShot S60 cameras are to name a few.
Director doesn't support TWAIN interface by itself, and image acquisition functionality is possible with third party extensions only. Macromedia Director works with two types of third party extensions: Xtras and ActiveX controls (for Windows only). So, lets get our review started.

You can find a few Twain ActiveX Controls available on the market. In this article we will not examine how to handle them in Director since there's a common approach for using AciveX controls. We believe you know how to install and use ActiveX Controls on Windows. Here is a brief description just to give you an idea:
1. Copy the .ocx file to the Windows System folder.
2. Run the following command:
REGSVR32.EXE /s YOURCONTROL.OCX
REGSVR32.EXE also should be in the Windows System folder, check if it's there before running it.
To insert ActiveX Control in Director select Insert > Controls > ActiveX menu and then just drag the appropriate cast member to the stage. Feel free to resize the sprite on the stage as you need.
Each ActiveX control has its own methods, properties and events, refer to the documentation supplied with the control to learn more on the stuff provided by the control. You can also find the comprehensive help on using ActiveX controls in Director's manual.

ActiveX approach to image acquisition in Director has some limitations, it allows to get the acquired image inside an ActiveX object which is not a Director bitmap cast member. You can display the acquired image on stage but no more than this. Twain Xtra is a more flexible solution because you get a full-featured bitmap cast member to:

• modify with imagine lingo;
• crop, rotate, resize and scale;
• apply a mask;
• set the ink of sprite property for a bitmap sprite;
• use as a texture for a 3D object;
• save to image file on user's HDD;
• upload to server and much more...

The Demo version of Twain Xtra is fully functional in Director authoring mode so you may use it for direct image acquisition to Director saving a few steps. The demo version is supplied with a comprehensive documentation and the demo movie. Here we will give you some basic ideas but that's not a replacement for the documentation and the demo movie so you're strongly recommended to read the documentation and try the demo movie before using the Xtra.
Before working with TWAIN interface the Xtra must be initialized. The "on startMovie" handler is a good place for things like that:

on startMovie
   Result = TwainInit()
end

Initialization allocates some memory for TWAIN engine, so, when user quits the application it should be set free. To do so we need to uninitialize TWAIN and the "on stopMovie" handler is exactly what we need:

on stopMovie
   Result = TwainUninit()
end

You can initialize and uninitialize the Xtra anywhere in your movie, there are no any restrictions or limitations. Of course, it's not a good idea to call those functions in a frame script's handler like "on exitFrame" that's being called a few times a second. Initialize the Xtra only once before image acquisition session started and uninitialize after it's been completed. After the Xtra has been initialized image acquisition can be performed. It's possible to connect one or more TWAIN compliant devices to a computer, they could be a scanner plus a digital camera. TWAIN needs user input to define which device is selected for image acquisition and the "Select Twain Source" dialog was designed specifically for that purpose.
With the TwainShowSelectDlg() function you can display the dialog to get user's input. Place this code to the "on mouseDown" event for the "Select Twain Source" button:

global TwainSource
set Result = TwainShowSelectDlg()
if count(Result) = 3 then
   set TwainSource = getAt(Result,3)
else
   set TwainSource = ""
end if

The TwainShowSelectDlg() function displays the standard device Select Twain Source dialog. This dialog comprises a list of available devices with two buttons: Select and Cancel. The function returns a list, the third element of the list is a string which is the name of the selected Twain Source, we put it to the global variable TwainSource. TwainSource is not the exact device name, usually it's just a contracted name or some combination of the name and abbreviation. It may be something like "FV950_32 v 1.24" where FV950 is the model name. If user selected some device from the list and clicked on the "Select" button then the TwainSource variable would be equal to the selected device name, if user clicked on the "Cancel" button then the TwainSource variable would be an empty string.
After the source has been selected user can start scanning. That's what we put to the "on mouseDown" handler for the "Scan Button":

if TwainSource <> "" then
   set ShowUI = true
   set NumberOfImages = 1
   set CastMember = member 11
   set CallbackHandler = "finishScan"
   set Result = TwainAcquireImage(TwainSource, ShowUI, NumberOfImages, CastMember, CallbackHandler)
end if

TwainAcquireImage() function has five parameters:

• TwainSource - a string with a name of the TWAIN source. This variable was set when user clicked on the "Select Twain Source" button.
• ShowUI - boolean to indicate if device specific user interface should be visible or not. Every device has its own acquisition dialog that allows to adjust some settings like brightness, contrast, RGB settings, cropping etc. Note, not all devices allow to adjust this setting, it completely depends on specific device driver.
• NumberOfImages - number of images to capture during the current acquisition session. Most digital cameras allow to acquire more than one image per session. You can set this parameter to -1 to acquire as many images as the source can provide.
• CastMember - reference to a bitmap or an empty cast member where the first acquired image will be allocated.
• CallbackHandler - the name of the callback handler. Callback handler is a movie script handler that will be invoked when acquisition is finished.
  

Callback Handler should look like this:

on finishScan nImage
   -- scanning process has been finished
   -- do something here
end

nImage is the number of images that were actually acquired. User may select 20 images for acquisition but if the camera had just 15 ones, only 15 cast members would be filled with images. So, it's just to inform on how many cast members were filled/created. Please, avoid calling any Twain Xtra functions in the callback handler. As you may have noticed, it's pretty easy to implement seamless image acquisition to your Director application - all you need is just to handle a few functions. For reference:

- TwainInit(), TwainUninit() - initailization and deinitailization of Twain Xtra (starting and stopping TWAIN engine);

- TwainShowSelectDlg() - allows user to select twain source;

- TwainAcquireImage(TwainSource, ShowUI, NumberOfImages, CastMember, CallbackHandler) - acquire image to cast member(s).

That's it, good luck!

On March 1, 2004 we released Twain Xtra version 2.0.
That was a major update since version 1.1 released in March, 2002. Twain scanning engine was completely redesigned to make the Xtra compatible with a wider range of TWAIN compliant devices. Besides, we released a completely new product - Twain Xtra 2.0 Professional Edition that brought the power of TWAIN 1.9 specification capabilities to Director.