1.0.2774.20140217
ToupCam cameras (model series: UCMOS, U3CMOS, UHCCD, EXCCD, SCCCD) support various kinds of APIs (Application Program Interface), namely Native C/C++, .Net/C#, DirectShow, Twain, LabView and so on. Compared with other APIs, Native C/C++ API, a low level one, characterized by the employment of Native C/C++ only without any other run-time libraries. Besides, this interface is simple, flexible and easy to integrate into the customized applications. The SDK zip file contains all of the necessary resources and information:
toupcam.h, C/C++ head file
toupcam.cs, for .Net/C#. The toupcam.cs use P/Invoke to call toupcam.dll. Please copy toupcam.cs to your .Net/C# project to use it.
toupcam.lib, lib file for x86.
toupcam.dll, dll file for x86.
toupcamdemocpp.exe, x86 C++ demo exe file.
toupcam.lib, lib file for x64.
toupcam.dll, dll file for x64.
toupcamdemocpp.exe, x64 C++ demo exe file.
x86 folder contains the kernel mode drivers for x86, including toupcam.cat, toupcam.inf and toupcam.sys.
x64 folder contains the kennel mode driver for x64, including toupcam.cat, toupcam.inf and toupcam.sys.
directshow directory contains the directshow SDK and demo.
twain directory contains the twain SDK and demo.
labview directory contains the labview SDK and demo.
User manuals in English and Chinese.
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.
Two ways are listed below to notify applications for reference:
In Pull Mode, the SDK could not only notify the application that the image data or still image are available for access, but also inform you of the other events, such as:
TOUPCAM_EVENT_EXPOSURE | exposure time changes |
TOUPCAM_EVENT_TEMPTINT | white balance parameters changes |
TOUPCAM_EVENT_IMAGE | Video image data arrives. Use Toupcam_PullImage to obtain data |
TOUPCAM_EVENT_STILLIMAGE | Still image arrives by function Toupcam_Snap. Use Toupcam_PullStillImage to obtain data |
TOUPCAM_EVENT_ERROR | Error occurs, data acquisition cannot continue |
Return Value: non-negative integer, enumerated camera number
Parameters: ToupcamInst buffer
Remarks: call this function to enumerate ToupCam cameras that are currently connected to computer and when it is returned, ToupcamInst buffer contains the information of each camera instance enumerated.If we don't care about that multiple cameras connect to the computer simultaneously, it's optional to call this function to enumerate the camera instances.
The code snippet shows as below:
ToupcamInst arr[TOUPCAM_MAX];
unsigned cnt = Toupcam_Enum(arr);
for (unsigned i = 0; i < cnt; ++i)
......
typedef struct{
#ifdef _WIN32
const wchar_t* name; /* model name */
#else
const char* name;
#endif
unsigned flag; /* TOUPCAM_FLAG_xxx */
unsigned maxspeed; /* number of speed level, Toupcam_get_MaxSpeed, the speed range = [0, max], closed interval */
unsigned preview; /* number of preview resolution, Toupcam_get_ResolutionNumber */
unsigned still; /* number of still resolution, Toupcam_get_StillResolutionNumber */
ToupcamResolution res[TOUPCAM_MAX];
}ToupcamModel;
Return Value: HToupCam handle. Return NULL when fails (Such as the device has been pulled out).
Parameters: ToupCam camera instance, enumerated by Toupcam_Enum. If id is NULL, Toupcam_Open will open the first camera which connects to the computer. So, if we don't care about that multiple cameras connect to the computer simultaneously, Toupcam_Enum is optional, we can simply use NULL as the parameter.
Remarks: open the camera instance.
Return Value: void
Parameters: HToupCam handle
Remarks: close the camera instance. After it is closed, never use the HToupCam handle any more. Do not call Toupcam_Close in the PTOUPCAM_DATA_CALLBACK callback function, otherwise, deadlock occurs.
Return Value: HRESULT type means "success/ failure"
Parameters:
Return Value: HRESULT type means "success/ failure"
Parameters:
Remarks: when pImageData is NULL, while pnWidth and pnHeight are not NULL, you can peek width and height info of images.
Return Value: HRESULT type means "success / failure"
Parameters:
typedef void (*PTOUPCAM_DATA_CALLBACK)(const void* pData, const BITMAPINFOHEADER* pHeader, BOOL bSnap, void* pCallbackCtx);
when calls back, if Parameter pData == NULL, then internal error occurs (eg: the camera pulled out suddenly).
For parameter BOOL bSnap, TRUE means still image snap by Toupcam_Snap function, FALSE means ordinary previewed pictures/ videos.
Attention: this callback function is called back from the internal thread in toupcam.dll, so great attention should be paid to multithread matter. Do not call Toupcam_Stop and Toupcam_Close in this callback function, otherwise, deadlock occurs.
Remarks: start camera instance.
Return Value: HRESULT type means success/failure
Parameters: HToupCam handle
Remarks: stop the camera instance. Do not call Toupcam_Stop in the PTOUPCAM_DATA_CALLBACK callback function, otherwise, deadlock occurs.After stopped, it can be restart again. For example, switching the video resolution:
Return Value: HRESULT type means success/failure
Parameters: HToupCam handle
Remarks: pause/continue camera instance.
Return Value: HRESULT type means success/failure
Parameters:
Remarks: snap image. When snap successfully, the image will be returned by callback function PTOUPCAM_DATA_CALLBACK. Here, BOOL bSnap is TRUE.
Most cameras can snap still image with different resolutions under continuous preview. For example, UCMOS03100KPA's previewed resolution is 1024*768, if we call Toupcam_Snap(h, 0), we get so called "still image" with 2048*1536 resolution.
Some cameras hasn't this ability, so nResolutionIndex must be equal the preview resolution which is set by Toupcam_put_Size, or Toupcam_put_eSize.
Whether it supports "still snap" or not, see "still" domain in ToupcamModel.
Return Value: HRESULT type means success/failure
Parameters:
Remarks: set/get current resolution
Set resolution before running ToupCam_Startxxxx
There are two ways to set current resolution: one is by resolution index, the other by width/height. Both ways are equivalent. For example, UCMOS03100KPA supports the following three kinds of resolution:
Index 0: 2048, 1536
Index 1: 1024, 768
Index 2: 680, 510
So Toupcam_put_Size(h, 1024, 768) is as effective as Toupcam_put_eSize(h, 1)
Return Value: HRESULT type means success/failure
Parameters:
Remarks: Toupcam_get_ResolutionNumber means the number of resolution supported. Take UCMOS03100KPA as an example, if we call the function Toupcam_get_ResolutionNumber and get "3", which means it can support three kinds of resolution. Toupcam_get_Resolution obtains the width/height of each kind of resolution.
These parameters have also been contained in ToupcamModel.
Return Value: HRESULT type means success/failure
Parameters:
TOUPCAM_PROCESSMODE_FULL: full mode with better image quality but more CPU usage
TOUPCAM_PROCESSMODE_FAST: fast mode with poorer image quality but less CPU usag
Remarks: choose FULL mode or FAST mode correspondingly. The default value is FULL.
Return Value: HRESULT type means success/failure
Parameters:
Remarks: If you set RealTime mode as TRUE, then you get shorter frame delay but lower frame rate which damages fluency. The default value is FALSE.
Return Value: HRESULT type means success/failure
Parameters:
Remarks: auto-exposure, auto-exposure target
Return Value: HRESULT type means success/failure
Parameters:
Remarks: exposure time related.
Return Value: HRESULT type means success/failure
Parameters:
Remarks: analog gain related.
Return Value: HRESULT type means success/failure
Parameters: HToupCam h: camera instance handle
Remarks: set or obtain hue, saturation, brightness, contrast and gamma.
Return Value: HRESULT type means success/failure
Parameters:
Remarks: color or gray mode
Return Value: HRESULT type means success/failure
Parameters: HToupCam h: camera instance handle
Remarks: vertical/horizontal flip.
Return Value: HRESULT type means success/failure
Parameters:
Remarks: the minimum frame rate level is "0", the maximum one can be achieved through Function "Toupcam_get_MaxSpeed" which equals to maxspeed in ToupcamModel.
Remind: CCD cameras cannot change frame rate setting real-timely, that's to say you can't change the frame rate setting any more after calling the function Toupcam_Startxxxx. Therefore, the frame rate for CCD cameras should be set after function Toupcam_Open but before function Toupcam_Startxxxx.
Return Value: HRESULT type means success/failure
Parameters:
Remarks: set the light source power frequency
Return Value: HRESULT type means success/failure
Parameters:
Remarks: set Bin mode or Skip mode. Cameras with higher resolution can support two sampling modes, one is Bin mode (Neighborhood averaging), the other is Skip (sampling extraction). In comparison, the former is with better image effect but decreasing frame rate while the latter is just the reverse.
Return Value: HRESULT type means success/failure
Parameters:
Remarks: set/obtain the color temperature and Tint parameters of white balance.
Toupcam_TempTint2RGB(...) and Toupcam_RGB2TempTint(...) can be used to convert RGB Gain from / to Temp / Tint.
Return Value: HRESULT type means success/failure
Parameters:
Remarks: For AWB function, basically there are two methods available in the field. One is continuous AWB mode and the other is one push AWB mode. Continuous AWB mode will do the AWB function all the time and one push AWB mode will do the AWB function once triggered. And toupcam cameras use one push AWB mode because this mode is preferred for microscope industry and more accurate. Continuous AWB mode will introduce some errors in some conditions. Call this function to perform one "auto white balance". When the "auto white balance" completes, TOUPCAM_EVENT_TEMPTINT event notify the application (In Pull Mode) and callback happens. In pull mode, this callback is useless, set it to NULL.
Return Value: HRESULT type means success/failure
Parameters: HToupCam h: camera instance handle
Remarks: set/obtain the ROI of automatic white balance and auto-exposure.
Return Value: HRESULT type means success/failure
Parameters: HToupCam h: camera instance handle
Remarks: gray camera or not, find the flag in ToupCamModel: TOUPCAM_FLAG_MONO
Return Value: HRESULT type means success/failure
Parameters:
Remarks: Toupcam_get_StillResolutionNumber means the number of supported still resolution. Take UCMOS03100KPA as an example, if we call the function Toupcam_get_StillResolutionNumber and get "3", which means it can support three kinds of resolution. If it doesn't support "still snap", then we get "0". Toupcam_get_Resolution obtains the width/height of each kind of resolution.
Return Value: HRESULT type means success/failure
Parameters:
Remarks: each camera has a unique serial number with 31 letters, eg,"TP110826145730ABCD1234FEDC56787"
Return Value: HRESULT type means success/failure
Parameters:
Remarks: Once we set non-NULL callback function, then callback happens whenever the exposure time changes.
Return Value: HRESULT type means success/failure
Parameters:
Remarks: once we set non-NULL callback function, then callback happens whenever the color/gray switches, eg, call Toupcam_put_Chrome
Return Value: HRESULT type means success/failure
Parameters: HToupCam h: camera instance handle
Remarks: auto Level Range.
Return Value: HRESULT type means success/failure
Parameters:
Remarks: level range related.
Return Value: HRESULT type means success/failure
Parameters:
Remarks: obtain histogram data.
Toupcam support.Net and C# development environment.
toupcam.cs in the 'inc' directory use P/Invoke call into toupcam.dll. Copy toupcam.cs to your .Net / C# project, please reference toupcamdemowinform in the samples directory.
The c# class ToupTek.ToupCam is a thin wrapper class to the native 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); } |
Ranges and default value of some parameters
Parameters | Range | Default value |
AutoExpoTarget | 10~230 | 120 |
Temp | 2000~15000 | 6503 |
Tint | 200~2500 | 1000 |
LevelRange | 0~255 | Low = 0, High = 255 |
Contrast | -100~100 | 0 |
Hue | -180~180 | 0 |
Saturation | 0~255 | 128 |
Brightness | -64~64 | 0 |
Gamma | 20~180 | 100 |
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