Firstly, start the MSVC DevStudio
IDE. Then, select New from the File menu.1. MicrosoftÒ Visual C++Ô Recipe
Creating the project
Adding the Code
How the Code Works
Pervasive Multithreading
Build Settings
Setting-up the Runtime Environment
Initialization Call-backs
Supplying a call-back function pointer
Synchronous Initialization
Asynchronous Initialization
Setting Parameters
Reading back the results
Signal State vs. Speed & Sensitivity
Exposure Time
Start Acquisition/Stop Acquisition
Grab n Frames
Synchronous Take
You Supply the Memory
Asynchronous Take
Frame Call-backs
You Supply the Memory
SDK Supplies the Memory
The EG&G Life Sciences Camera SDK provides a development environment for controlling a wide range of cameras through a simple set of APIs.
It offers both flexibility and performance under a variety of operating environments and hardware set-ups.
Anyone with ‘beginner level’ ability in one of the supported programming languages should be able to work with the SDK within an hour or two of reading this manual, working through the examples and reviewing the sample applications.
At present, the SDK is only available on Win32 platforms. Specifically, there is support for the following environments:
Microsoftâ Windows 95ä
Microsoftâ Windows 98ä
Microsoftâ Windows NT4.0ä
It is also expected that Microsoftâ Windows 2000ä Professional (formerly Microsoftâ Windows NT5.0ä Workstation) will be supported when it becomes available.
An application written using the SDK will run unchanged on any of the other platforms, provided no platform-specific code has been included in your own code. A suitable tool such as Rational Software Corp.’s PurifyÔ tool, or NuMega’s BoundsCheckerÔ can be used to verify compliance, if no other testing facilities are available.
The minimum hardware requirements are those specified by your OS/Development environment (e.g. minimum 16Mb RAM, i486 equivalent processor, IBM Compatible PC for Windows NT4.0ä ). In addition to this, you will require additional RAM, which can be calculated as follows:
For example, if you wanted to be able to capture a sequence of 10 images with a KAF0400 camera (820´ 576 pixels), on a Windows NT4.0 system, you would need at least 16Mb for the base operating system, plus the extra outlined above, which comes to:
On top of this, you would require any memory needed for your development environment (usually ~32Mb minimum). In all this comes to a minimum requirement of ~64Mb.
A recommended minimum development system would be an Intelâ Pentium IIä 300MHz equivalent processor with 96Mb RAM. When dealing with large amounts of image data, it is recommended that you also start with at least 1Gb of free hard disk space. You can use the formula above to calculate how much HD space will be required to store the number of images you expect to collect with your application.
You will also require free AT/PCI slots and system resources, as detailed in your camera’s hardware set-up manual.
By implementing a C-callable DLL interface on the Win32 platform, we have made it possible to use the SDK with a wide variety of development environments, including products from the following manufacturers:
MicrosoftÒ
Visual C++Ô
Visual BasicÔ
InpriseÒ
Borland C++ BuilderÔ
Borland DelphiÔ
IBMÒ
VisualAgeÔ C++
VisualAgeÔ Basic
However, only the MicrosoftÒ products listed above are directly supported by EG&G Life Sciences. Please refer to your development environment’s documentation for details on how to call into a C-language DLL, supply function callbacks etc.
The EG&G Life Sciences SDK currently supports the complete Camera range. Through a system of initialization files and custom camera support DLLs, shipped with new cameras, as they become available, existing software written using the SDK will automatically support these new systems, without changes to the code.
In addition, there is a Dummy camera, which can be used to test the software in the absence of camera hardware, or to ship with a demonstration version of your application.
All cameras are supported on the Microsoftâ Windows 95ä , and Microsoftâ Windows 98ä platforms.
At present, there is no suitable driver for the frame grabber card used with our FastScan cameras under Microsoftâ Windows NT4.0ä . Until a driver becomes available, you will be unable to use the FastScan cameras on this platform.
Microsoftâ Windows 95ä is recommended for FastScan cameras, as performance is higher than with Microsoftâ Windows 98ä .
1. MicrosoftÒ Visual C++Ô Recipe
This example uses MSVC5.0, although MSVC6.0 etc. should work in much the same way.
Firstly, start the MSVC DevStudio
IDE. Then, select New from the File menu.
This will bring up the New
dialog.
From this dialog, you should select the Win32Application option; type a suitable path for the project files in the location box (e.g. D:\Projects) and type FirstApp into the Project name edit field. (It will automatically be appended to the path in the Location box for you).
Next, you need to create a new source file. To do this, select New from the File menu, again. This brings back the New dialog, but this time it shows the Files tab.
Select the C++ Source File option, and type FirstApp into the File name field.
This will create you a new,
empty source file called FirstApp.cpp and add it to the project.
Next, you need to add the following code to the file:
/*-----------------------------------------------------------------------------
File Name : FirstApp.cpp
Description : Simple demonstration app for the camera SDK
See the SDK User Guide for details.
-------------------------------------------------------------------------------
(c) Copyright 1998 Life Science Resources Ltd, All Rights Reserved.
Licensed Materials, Program Property of
-----------------------------------------------------------------------------*/
#include <windows.h>
#include "CamAPI.h"
const int total = 50; // Total number of frames to capture
const char* eventName = "FrameEvent";
int count = 0;
void FrameCallback( CAMFrame* frame, void* /*param*/ )
// Called by the SDK for every frame
{
// Release the frame data - we don't want it any more
if( frame )
{
CAMFreeFrame( frame );
}
if( ++count >= total || frame == 0 )
{
// Signal our main thread that we are done
HANDLE myEvent = OpenEvent( EVENT_ALL_ACCESS, FALSE, eventName );
SetEvent( myEvent );
CloseHandle( myEvent );
}
}
int WINAPI WinMain( HINSTANCE hInstance, // handle to current instance
HINSTANCE hPrevInstance, // handle to previous instance
LPSTR lpCmdLine, // pointer to command line
int nCmdShow // show state of window
)
{
// *** PHASE ONE - INITIALIZATION
CAMInitDriver( hInstance ); // Initialise the environment
// Boot the camera, using the file ‘test.ini’ found in the current
// directory
CAMInitialise( "test.ini" );
// Create our event
HANDLE frameEvent = CreateEvent( NULL, TRUE, FALSE, eventName );
// *** PHASE TWO - ACQUISITION
// Get ready to grab
CAMRegFrameCallback( FrameCallback, 0 );
// Start the camera
CAMStartGrabbing();
// Wait until we're signalled by our callback that we're done
WaitForSingleObject( frameEvent, INFINITE );
// Stop the camera
CAMStopGrabbing();
// *** PHASE THREE - TERMINATION
CloseHandle( frameEvent ); // Clean up the handle
// Shut down this instance of the driver
CAMTerminateDriver();
return 0;
}
Note that this code can also be found on the disk supplied with the SDK as \FirstApp\FirstApp.cpp.
If we look at WinMain(), we see that there are 3 phases to the application:
Initialize the SDK
Initialize the Camera
Select Acquisition Mode
Grab Images
Free resources
Terminate the SDK
Any application built using the SDK will follow this broad structure, although the phases may well be more complex in a larger application. You might wish to set up the configurable parameters in the camera, or interleave parameter changing and image acquisition, for example.
Select Acquisition Mode and Grab Images have been highlighted in the above list, as they are at the heart of the application. The call to CAMRegFrameCallback tells the SDK to call our function FrameCallback, each and every time it successfully grabs a frame. We then get the camera going, and wait around until someone signals the event we created earlier on.
If you look at the code in FrameCallback, what we do is to keep a count of the number of frames we have seen, and release the memory for the CAMFrame we have just been given (we could equally well store it away somewhere for later viewing, printing etc.). Then, if we exceed the required frame count (total), we open a handle on the event we created back in WinMain, and signal it that we’re done.
This causes our WinMain function to wake up again, and carry on into the termination phase.
This illustrates quite nicely the way that the SDK can operate asynchronously for maximum performance, without bothering the application programmer with the intimate details of how this is achieved.
For those who are happy with multithreaded programming, I will explain how this works. If you are not experienced with multiple threads, don’t worry. We will look at examples that show how to use simple synchronization objects (like the event in the example above) to make use of the asynchronous acquisition modes, with very little multithreading experience. We will also see how to use entirely synchronous (‘traditional’) code with the SDK. Because the SDK is pervasively multi-threaded internally, you gain many of the benefits of a multi-threaded approach, even if you use synchronous acquisition! For now, though, you can skip on to Build Settings.
For those of you still reading, the FrameCallback function was called on
a separate, SDK-created thread. Instead of simply waiting for
an event, and wasting time without wasting processor cycles, the
main application thread could have drawn the captured frames,
processed user input, or anything else it might have needed to
do. The only consideration a programmer needs to have for this
multi-threaded environment is to protect anything accessed from
both the main routine and the call-back routine with a suitable
synchronization object (e.g. a mutex), as usual.
Before we can build this project,
we must tell the system how to find the SDK library itself. We
do this by using the Settings option from the Project
menu.
Then, select the C/C++ tab, and drop down
the combo-box, to select the Preprocessor option.
This will enable you to set the path to the SDK include file, CAMAPI.H.
To do this, type the path to the SDK header files
into the Additional Include Directories field. For a standard
installation, this will be ..\..\Include
Next, you need to set the up the path to the SDK library file, which contains the information about which functions the SDK DLL exports. This is done from the Link setting page, accessed by clicking on the Link tab.
On the general page, type the path to the SDK lib
file into the Object/Library Modules field. For a standard
installation, this will be ..\..\Lib\lsrcam.lib.
Then, drop down the list box on the left, and repeat
the procedure above for the Release build. Alternatively,
you could have selected All Configurations from this box,
and performed both operations at once. Then click OK.
Setting-up the Runtime Environment
You must ensure that you have copied the OS specific DLLs from the c:\sdk\distrib directory, to the working directory for the application (in this case, firstapp\release, or firstapp\debug).
If you are using a FastScan camera (and therefore Windows 95/98), you will also need to follow the special instructions in the Win9x directory (readme.txt).
If you are using a SlowScan camera, under Windows NT, you will also need to follow the special instructions in the WinNT directory (readme.txt).
For this first application, you also need to insure that your camera’s INI file is located in the working directory for the application. Copy the INI file supplied to the application’s working directory (in this case, firstapp\release, or firstapp\debug). You will also need to rename it from slowscan.ini or fastscan.ini to test.ini. Note for fast-scan systems the LINK_SPEED setting in the [LINK_CONTROL] section must be set to 10 to match the camera hardware.
The INI file is used to set the default parameters for the camera. See your camera manual for more information on the INI file. Additionally, 2 extra lines must be present in the INI file for the SDK to work correctly.
[SDK_SETTINGS]
CAMERA_NAME=<CAMERANAME>
<CAMERANAME> should be replaced by one of Slowscan, Fastscan, or Dummy, depending on the camera type you wish to use. Dummy represents a demonstration mode, which will generate images even without camera hardware present.
Initialization can take place either synchronously, or asynchronously. To support asynchronous initialization, a call-back is used, to provide information on the progress of the operation to the client.
The programmer supplies a pointer to a function, which is called periodically on the initialization thread (rather than the client thread). A parameter is passed to the function which indicates the progress of the operation (0-100%, completed or aborted). The programmer can, for example, post a message back to the main application to update some user interface, or similar (see the initialization example in the SDKDemo application’s CSDKDemoApp class).
Supplying a call-back function pointer
You need to declare a c-callable function in your application, which complies with the following specification:
Example in C++
void InitCallback( int percentComplete, void* /*params*/ )
{
if( percentComplete <= 100 )
{
CSplashWnd::UpdateInitializationProgress( percentComplete );
}
else if( percentComplete > 100 )
{
if( percentComplete == 102 )
{
CSDKDemoApp::fInitError = true;
}
HANDLE evt;
evt = OpenEvent( EVENT_ALL_ACCESS, FALSE, "InitCompletion" );
SetEvent( evt );
CloseHandle( evt );
}
}
You can initialize the camera synchronously (i.e. your calling thread is suspended until the operation is completed). This may be useful for embedded applications where there is no user interface to update.
Example in C++
CAMInitialise( "c:\\test.ini" )
Normally, however, you will initialize the camera asynchronously. This enables you to update your user interface as the operation progresses. The example below is using the InitCallback function illustrated above.
Example in C++
InsideIntializationCodeForApp()
{
// ...
// Initialize camera
CAMRegInitCallback( InitCallback, (void*)0 );
CAMInitialise( iniFile );
while( WaitForSingleObject( initEvent, 0 ) != WAIT_OBJECT_0 )
{
MSG msg;
if( ::PeekMessage( &msg, NULL, 0, 0, PM_NOREMOVE ) )
{
PumpMessage();
}
}
// ...
}
For those people who have experience of the original SDK/Control software supplied with our cameras, you will have noticed that different hardware behaves very differently in terms of the parameters it supports. For this release, we have abstracted away from the hardware, and provided a more general set of parameters that can control any camera equally well. There are some examples of this in the sections below.
Any given parameter may be read only, write only or read-write. If you look at the reference documentation, you will see that all the Read and Write functions follow the same naming convention:
Example in C++
Attribute Name: XBinning
Read Function: CamGetXBinning()
Write Function: CamSetXBinning()
Because we are working in a generic (i.e. non-camera specific environment), when you try to set a parameter, you are really only providing a hint to the system as to what you would like to do. It then takes this hint, and translates it into the real-life camera settings needed to best comply with your request. Anybody who has programmed for the X-Windows™ system will be familiar with this approach.
This makes it even more important than usual to test your result codes, and to read back the actual settings to ensure that you always know exactly what state the system is in.
Signal State vs. Speed & Sensitivity
A good example of this is to look at the Speed and Sensitivity settings of the cameras. These are both set in terms of a percentage of the maximum speed, or maximum sensitivity. So, instead of saying ‘I want the camera to go at speed setting 3’ (which is the native way of talking to the camera hardware you may be familiar with from previous SDKs), you say ‘I want the camera to run at 75% of its maximum speed’. You set the sensitivity up in exactly the same way.
Now, the camera may not support a speed exactly 75% of its maximum readout rate, or exactly 30% of its maximum sensitivity. To get round this, it sets the camera into the nearest possible mode to support your request.
To find out exactly what rate and sensitivity (and therefore what peak signal strength) the camera is using, you can then call back on the SignalState attribute, which gives you accurate readings for these values, in kilo-pixels per second, electrons per level (and electrons) respectively.
Another common parameter you will need to set is the exposure time. This is set in microseconds using 2 parameters. You multiply the 2 values together to retrieve the actual exposure time. This allows very long exposure times, but also very high precision.
Taking a picture can be done in a variety of ways, to suit your particular application.
Start Acquisition/Stop Acquisition
This sets the camera into its most efficient multi-frame grab mode. When StartAcquisition is called, the camera will keep pouring out frames as fast as possible, until a call to StopAcquisition terminates the operation. Whilst this is very fast indeed, it limits the ability of the program to change the camera parameters on-the-fly.
Whilst the camera will not necessarily grab at its most efficient, sequenced use of Grab(1) may enable the program to change camera parameters on the fly. For example, you could Grab(1), MoveAFilter(), Grab(1) etc. [NB: MoveAFilter() is an example application function, and not a part of this SDK].
Synchronous take blocks the calling thread until the frame(s) has arrived. Operations are synchronous if you do not supply a frame callback. You must, however, supply memory to the application.
This enables the application to control the memory allocation, perhaps pre-allocating enough memory for all the frames that need grabbing up front, maximizing efficiency. You may use either start/stop acquisition or Grab n Frames in this mode.
Asynchronous take returns immediately after the camera has been set up and acquisition has begun.
Frame call-backs allow the application programmer to have a piece of code called every time a frame arrives. Note that the call-back does not occur on any of your own threads, but on some other, implementation defined thread. If you wish to communicate with your own threads, you must use appropriate synchronization/messaging calls.
This enables the application to control the memory allocation, perhaps pre-allocating enough memory for all the frames that need grabbing up front, maximizing efficiency. You may use either start/stop acquisition or Grab n Frames in this mode.
This frees the application from the worry of pre-allocating memory, but still requires that you ‘free’ the memory allocated when you are done. You should do this with the supplied SDK function CamFreeFrame(). For the technically interested, this is to ensure that memory allocated is freed within the module that allocated it (i.e. within the SDK dll).