ToupCam API Manual

1. Version

1.6.5660.20150520

2. Introduction

ToupCam cameras (model series: UCMOS, WCMOS, LCMOS, U3CMOS, L3CMOS, E3CMOS, ICMOS, GCMOS, UHCCD, EXCCD, SCCCD) support various kinds of APIs (Application Program Interface), namely Native C/C++, .NET/C#/VB.NET, DirectShow, Twain, LabView and so on. Compared with other APIs, Native C/C++ API, as a low level API, don't depend any other runtime libraries. Besides, this interface is simple, flexible and easy to be integrated into the customized applications. The SDK zip file contains all of the necessary resources and information:

toupcam.h, C/C++ head file

3. Concepts and terminology

a. Modes for accessing image data: "Pull Mode" vs "Push Mode"

Toupcam offers two modes to obtain image data: Pull Mode and Push Mode. The former is recommended since it's simpler and the application seldom gets stuck in multithreading conditions, especially when using windows message to notify the events.

There are to ways to notify applications:

a) Use Windows message: Start pull mode by using the function Toupcam_StartPullModeWithWndMsg. When event occurs, toupcam will post message (PostMessage) to the specified window. Parameter WPARAM is the event type, refer to the definition of TOUPCAM_EVENT_xxxx. This model avoids the multithreading issues, so it's the most simple way. (Obviously, this is only supported in Windows systems, and not supported in Linux and MacOSX.)

b) Use Callback function: Start pull mode by using the function Toupcam_StartPullModeWithCallback. When event occurs, toupcam will callback the function PTOUPCAM_EVENT_CALLBACK.

In Pull Mode, the SDK could not only notify the application that the image data or still image are available for 'PULL', but also inform you of the other events, such as:

TOUPCAM_EVENT_EXPOSURE exposure time changes
TOUPCAM_EVENT_TEMPTINT white balance parameters changes. Temp/Tint Mode, please see here.
TOUPCAM_EVENT_TEMPTINT white balance parameters changes. RGB Gain Mode, please see here.
TOUPCAM_EVENT_IMAGE Video image data arrives. Use Toupcam_PullImage to 'pull' the image data
TOUPCAM_EVENT_STILLIMAGE Still image which is triggered by function Toupcam_Snap arrives. Use Toupcam_PullStillImage to 'pull' the image data
TOUPCAM_EVENT_ERROR Error occurs, data acquisition cannot continue
TOUPCAM_EVENT_DISCONNECTED Camera disconnected, maybe has been pulled out

b. Still Capture (Still Image)

Most cameras support the so-called still capture capability. This function switches the camera to another resolution temporarily when the camera is in preview mode, after a "still" image in the new resolution is captured and then switch back to the original resolution and resume preview mode.

For example, UCMOS05100KPA support 3 resolutions and the current one in preview mode is 1280 * 960. Call Toupcam_Snap(h, 0) to "still capture" an image in 2592 * 1944 resolution. To realize this function, the camera will temporarily switch to 2592 * 1944 firstly, get an image in 2592 * 1944 resolution and then switch back to 1280 * 960 and resume preview.

a) In pull mode operation, after the still capture, TOUPCAM_EVENT_STILLIMAGE will be sent out for external acknowledgement. The external application should call Toupcam_PullStillImage to get the still captured image.
b) In push mode operation, after the still capture, the callback function PTOUPCAM_DATA_CALLBACK will be called with bSnap parameter setting TRUE. The image information including the resolution information will be obtained via the parameter pHeader.

To check whether the camera have the still capture capability, call Toupcam_get_StillResolutionNumber function or check the still field of the struct ToupcamModel.

c. Data format: RGB vs RAW

Toupcam supports two data formats: RGB format (default) and RAW format. RAW format could be enabled by assigning TOUPCAM_OPTION_RAW parameter to 1 when calling Toupcam_put_Option function.

Users could switch these two format by calling Toupcam_put_Option function with different value setting to TOUPCAM_OPTION_RAW. You must call this function BEFORE the camera start function (Toupcam_StartPullModeWithWndMsg or Toupcam_StartPullModeWithCallback or Toupcam_StartPushMode).

d. White Balance and Auto White Balance: Temp/Tint mode vs RGB Gain mode

1. Toupcam sdk supports two independent modes for white balance: a) Temp/Tint Mode; b) RGB Gain Mode

a) Temp/Tint mode is the default white balance mode. In this mode, temp and tint are the parameters that could be used to control the white balance. Toupcam_get_TempTint function is used to acquire the temp and tint values and Toupcam_put_TempTint is used to set the temp and tint values. Function Toupcam_AwbOnePush is used to execute the auto white balance. When the white balance parameters change, TOUPCAM_EVENT_TEMPTINT event will be notified for external use.

b) In RGB Gain mode, the while balace is controled by the gain values of the R,G,B channels. Toupcam_get_WhiteBalanceGain is used to acquire the parameters and Toupcam_put_WhiteBalanceGain is used to set the white balance parameters. Toupcam_AwbInit is used to execute the execute the auto white balance. When the white balance parameters change, TOUPCAM_EVENT_WBGAIN event will be notified for external use.

The functions for these two modes cannot be misused:

a) In Temp/Tint mode, please use Toupcam_get_TempTint and Toupcam_put_TempTint and Toupcam_AwbOnePush. Toupcam_get_WhiteBalanceGain and Toupcam_put_WhiteBalanceGain and Toupcam_AwbInit cannot be used, they always return E_NOTIMPL.
b) In RGB Gain mode, please use Toupcam_get_WhiteBalanceGain and Toupcam_put_WhiteBalanceGain and Toupcam_AwbInit. Toupcam_get_TempTint and Toupcam_put_TempTint and Toupcam_AwbOnePush cannot be used, they always return E_NOTIMPL

When calling Toupcam_Open function, whether to add a '@' character at the beginning of the id parameter will determine the white balance mode. Add a '@' character at the beginning of the id parameter means the RGB gain mode. If you want to use the RGB Gain mode, for example, if the id parameter is "abcdef", please call the Toupcam_Open function with the id parameter "@abcdef".

2. There are two auto white balance mechanisms available in this field: one is continuous auto white balance and the other is a "one push" auto white balance. The white balance parameters will be always calculated and updated for the continuous auto white balance mechanism. For "one push" auto white balance mechanism, the white balance parameters will be calculated and updated only when triggered. Toupcam cameras support "one push" auto white balance mechanism since it is more accurate and propriate for the microscope application, especially when the background is in pure color. Continuous white balance mechanism will encounter some problem in some cases.

3. Monochromatic camera does not support white balance. The functions metioned above always return E_NOTIMPL.

4. Functions

5. .NET and C# and VB.NET

Toupcam does support .NET development environment (C# and VB.NET).

toupcam.cs in the 'inc' directory use P/Invoke call into toupcam.dll. Copy toupcam.cs to your C# project, please reference toupcamdemowinformcs1 and toupcamdemowinformcs2 in the samples directory.

The C# class ToupTek.ToupCam is a thin wrapper class of the native C/C++ API of toupcam.dll, it's properties and methods P/Invoke into the corresponding Toupcam_xxxx functions of toupcam.dll. So, the descriptions of the Toupcam_xxxx function are also applicable for the corresponding C# properties or methods. For example, the C# Snap method call the function Toupcam_Snap, the descriptions of the Toupcam_Snap function is applicable for C# Snap method:

[DllImport("toupcam.dll", ExactSpelling = true, CallingConvention = CallingConvention.StdCall)]
private static extern int Toupcam_Snap(SafeHToupCamHandle h, uint nResolutionIndex);

public bool Snap(uint nResolutionIndex)
{
    if (_handle == null || _handle.IsInvalid || _handle.IsClosed)
        return false;
    return (Toupcam_Snap(_handle, nResolutionIndex) >= 0);
}

VB.NET is similar with C#, not otherwise specified.

6. Others

Parameters Range Default value Get Set Auto
Auto Exposure Target 16~235 120 Toupcam_get_AutoExpoTarget Toupcam_put_AutoExpoTarget  
White Balance Temp/Tint Mode Color Temperature 2000~15000 6503 Toupcam_get_TempTint Toupcam_put_TempTint Toupcam_AwbOnePush
Tint 200~2500 1000
RGB Gain Mode Red Gain -128~128 0 Toupcam_get_WhiteBalanceGain Toupcam_put_WhiteBalanceGain Toupcam_AwbInit
Green Gain
Blue Gain
LevelRange 0~255 Low = 0
High = 255		 Toupcam_get_LevelRange Toupcam_put_LevelRange Toupcam_LevelRangeAuto
Contrast -100~100 0 Toupcam_get_Contrast Toupcam_put_Contrast  
Hue -180~180 0 Toupcam_get_Hue Toupcam_put_Hue  
Saturation 0~255 128 Toupcam_get_Saturation Toupcam_put_Saturation  
Brightness -64~64 0 Toupcam_get_Brightness Toupcam_put_Brightness  
Gamma 20~180 100 Toupcam_get_Gamma Toupcam_put_Gamma  

7. Changelog

v1.6: support RGB48 when bit depth > 8, please see here

v1.5: support trigger mode

v1.4: White Balance: Temp/Tint Mode vs RGB Gain Mode, please see here

v1.3: ROI (Region Of Interest) supported: please see here

v1.2: more bit depth supported: 10bits, 12bits, 14bits, 16bits

v1.1: support RAW format, please see here and here; support Linux and OSX

v1.0: initial release

8. Contact

If you have any problems in using this SDK, please use the following information to contact us.
www: www.touptek.com
email: support@touptek.com