Omegonprocam API Manual


1. Version & Platform



2. Introduction


Omegonprocam cameras support various kinds of APIs (Application Program Interface), namely Native C/C++, .NET (C# & VB.NET), Python, Java, DirectShow, Twain, LabView, MabLab 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:

omegonprocam.h, C/C++ head file


3. Concepts & Terminology


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

Omegonprocam 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 Omegonprocam_StartPullModeWithWndMsg. When event occurs, omegonprocam will post message (PostMessage) to the specified window. Parameter WPARAM is the event type, refer to the definition of OMEGONPROCAM_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 macOS.)

b) Use Callback function: Start pull mode by using the function Omegonprocam_StartPullModeWithCallback. When event occurs, omegonprocam will callback the function POMEGONPROCAM_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:

Event Source Description
OMEGONPROCAM_EVENT_EXPOSURE Software exposure time changed
OMEGONPROCAM_EVENT_TEMPTINT white balance changed. Temp/Tint Mode, please see here.
OMEGONPROCAM_EVENT_WBGAIN white balance changed. RGB Gain Mode, please see here.
OMEGONPROCAM_EVENT_IMAGE Video image data arrives. Use Omegonprocam_PullImageXXXX to 'pull' the image data
OMEGONPROCAM_EVENT_STILLIMAGE Still image which is triggered by function Omegonprocam_Snap or Omegonprocam_SnapN or Omegonprocam_SnapR arrives. Use Omegonprocam_PullImageXXXX to 'pull' the image data
OMEGONPROCAM_EVENT_ERROR Generic error, data acquisition cannot continue
OMEGONPROCAM_EVENT_DISCONNECTED Camera disconnected, maybe has been pulled out
OMEGONPROCAM_EVENT_NOFRAMETIMEOUT No frame was not captured within the specified time. see OMEGONPROCAM_OPTION_NOFRAME_TIMEOUT
OMEGONPROCAM_EVENT_NOPACKETIMEOUT No packet was not captured within the specified time. see OMEGONPROCAM_OPTION_NOPACKET_TIMEOUT
OMEGONPROCAM_EVENT_TRIGGERFAIL trigger failed (for example, bad frame data or timeout)
OMEGONPROCAM_EVENT_BLACK black balance changed
OMEGONPROCAM_EVENT_FFC flat field correction status changed
OMEGONPROCAM_EVENT_DFC dark field correction status changed
OMEGONPROCAM_EVENT_FPNC fixed pattern noise correction status changed
OMEGONPROCAM_EVENT_ROI roi changed
OMEGONPROCAM_EVENT_LEVELRANGE level range changed
OMEGONPROCAM_EVENT_AUTOEXPO_CONV auto exposure convergence
OMEGONPROCAM_EVENT_AUTOEXPO_CONVFAIL auto exposure once mode convergence failed
OMEGONPROCAM_EVENT_FACTORY restore factory settings. Please note that restoring factory settings may cause resolution changes.
OMEGONPROCAM_EVENT_EXPO_START Hardware exposure start
OMEGONPROCAM_EVENT_EXPO_STOP exposure stop
OMEGONPROCAM_EVENT_TRIGGER_ALLOW next trigger allow
OMEGONPROCAM_EVENT_TRIGGER_IN trigger in
OMEGONPROCAM_EVENT_HEARTBEAT heartbeat, can be used to monitor whether the camera is alive. see OMEGONPROCAM_OPTION_HEARTBEAT

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 Omegonprocam_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, OMEGONPROCAM_EVENT_STILLIMAGE will be sent out for external acknowledgement. The external application should call Omegonprocam_PullImageV3 or Omegonprocam_PullStillImage(V2) to get the still captured image.
b) In push mode operation, after the still capture, the callback function POMEGONPROCAM_DATA_CALLBACK_V4/V3 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 Omegonprocam_get_StillResolutionNumber function or check the still field of the struct OmegonprocamModelV2.

c. Data format: RGB vs RAW

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

Users could switch these two format by calling Omegonprocam_put_Option function with different value setting to OMEGONPROCAM_OPTION_RAW. You change this option only when camera is NOT running.

Users could change RGB bits by calling Omegonprocam_put_Option with different value setting to OMEGONPROCAM_OPTION_RGB. You change this option only when camera is NOT running.

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

1. Omegonprocam 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. Omegonprocam_get_TempTint function is used to acquire the temp and tint values and Omegonprocam_put_TempTint is used to set the temp and tint values. Function Omegonprocam_AwbOnce is used to execute the auto white balance. When the white balance parameters change, OMEGONPROCAM_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. Omegonprocam_get_WhiteBalanceGain is used to acquire the parameters and Omegonprocam_put_WhiteBalanceGain is used to set the white balance parameters. Omegonprocam_AwbInit is used to execute the execute the auto white balance. When the white balance parameters change, OMEGONPROCAM_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 Omegonprocam_get_TempTint and Omegonprocam_put_TempTint and Omegonprocam_AwbOnce. Omegonprocam_get_WhiteBalanceGain and Omegonprocam_put_WhiteBalanceGain and Omegonprocam_AwbInit cannot be used, they always return E_NOTIMPL.
b) In RGB Gain mode, please use Omegonprocam_get_WhiteBalanceGain and Omegonprocam_put_WhiteBalanceGain and Omegonprocam_AwbInit. Omegonprocam_get_TempTint and Omegonprocam_put_TempTint and Omegonprocam_AwbOnce cannot be used, they always return E_NOTIMPL

This mode is specified when the camera is opened and cannot be changed unless the camera is closed and opened again. Please see here.

2. There are two auto white balance mechanisms available in this field: one is continuous auto white balance and the other is a "once" auto white balance. The white balance parameters will be always calculated and updated for the continuous auto white balance mechanism. For "once" auto white balance mechanism, the white balance parameters will be calculated and updated only when triggered. Omegonprocam cameras support "once" 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.

e. Trigger Mode

1. What is Trigger Mode

Omegonprocam camera has two working modes: video mode and trigger mode. When in trigger mode, no images will be available until the trigger conditions are met. Cameras have 2 types for triggering according to the types of trigger source, including software trigger mode, external trigger mode and simulated trigger mode.

2. The Difference between Trigger and Snap

Trigger mode is designed for accurate control of the camera and images would be acquired only when the conditions are met. Users could get the images by controlling the trigger conditions. Trigger mode must be pre-specified. Once the trigger mode is entered, no images will come out from the camera until the trigger conditions are met. The triggered images will stay the same property as the pre-specified resolution. Snap is designed to acquire the images from the camera in video mode. The resolution of the snapped image could be the same resolution as the video or could be different.

3. Software Trigger Mode

Camera could be triggered by software. In software trigger mode, images burst out only when users trigger the camera from the software. Numbers of the images of the triggering could also be controlled by software.

4. External Trigger Mode

Camera could be triggered by external trigger signal. By now Omegonprocam camera only supports positive-edge trigger mode.

5. Mix Trigger Mode

Both external and software trigger are enabled.

6. Simulated Trigger Mode

For cameras that do not support software trigger and external trigger, simulated trigger mode could be available. When in simulated trigger mode, the camera hardware actually works in the same mode as the video mode. But the up-level software will not obtain any images from the camera. The software buffer will stay empty until the user set the trigger conditions by software.

7. How to Enter the Trigger Mode

After the numeration of the connected camera, you can check the flag and find out what trigger mode does the camera support according to the following definition.
#define OMEGONPROCAM_FLAG_TRIGGER_SOFTWARE   0x00080000  /* support software trigger */
#define OMEGONPROCAM_FLAG_TRIGGER_EXTERNAL   0x00100000  /* support external trigger */
#define OMEGONPROCAM_FLAG_TRIGGER_SINGLE     0x00200000  /* only support trigger single: one trigger, one image */
Function Omegonprocam_put_Option(HOmegonprocam h, unsigned iOption, int iValue) could be used to set the camera to trigger mode when assign OMEGONPROCAM_OPTION_TRIGGER to the iOption parameter. iValue is used to specify the types of the trigger modes. Please see the following for reference.
#define OMEGONPROCAM_OPTION_TRIGGER   0x0b    /* 0 = video mode, 1 = software or simulated trigger mode, 2 = external trigger mode, 3 = external + software trigger, default value = 0 */
Function Omegonprocam_get_Option(HOmegonprocam h, unsigned iOption, int* piValue) could be used to get what type of trigger mode the camera is in.

8. How to Trigger the camera

Function Omegonprocam_Trigger(HOmegonprocam h, unsigned short nNumber) could be used to trigger the camera. Assigning different value to nNumber means different:
nNumber = 0 means stop the trigger.
nNumber = 0xFFFF means trigger continuously, the same as video mode;
nNumber = other valid values means nNumber images will come out from the camera.
If the OMEGONPROCAM_FLAG_TRIGGER_SINGLE flag is checked, the nNumber parameter must be assigned to 1 and 1 image will come out from the camera when Omegonprocam_Trigger is called.
Enter the trigger mode first and then call Omegonprocam_Trigger function to trigger the camera.

9. Trigger timeout

The timeout is recommended for not less than (Exposure Time * 102% + 4 Seconds).

4. Functions



5. .NET (C# & VB.NET)


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

omegonprocam.cs use P/Invoke to call into omegonprocam.dll. Copy omegonprocam.cs to your C# project, please reference samples.

Please pay attation to that the object of the C# class Omegonprocam. Omegonprocam must be obtained by static mothod Open or OpenByIndex, it cannot be obtained by obj = new Omegonprocam (The constructor is private on purpose).

Most properties and methods of the Omegonprocam class P/Invoke into the corresponding Omegonprocam_xxxx functions of omegonprocam.dll/so. So, the descriptions of the Omegonprocam_xxxx function are also applicable for the corresponding C# properties or methods. For example, the C# Snap method call the function Omegonprocam_Snap, the descriptions of the Omegonprocam_Snap function is applicable for C# Snap method:

[DllImport("omegonprocam.dll", ExactSpelling = true, CallingConvention = CallingConvention.StdCall)]
private static extern int Omegonprocam_Snap(SafeHOmegonprocamHandle h, uint nResolutionIndex);

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

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


6. Python


Omegonprocam does support Python (version 3.0 or above), please import omegonprocam to use omegonprocam.py and reference the sample code simplest.py and qt.py.

Please pay attation to that the object of the python class omegonprocam.Omegonprocam must be obtained by classmethod Open or OpenByIndex, it cannot be obtained by obj = omegonprocam.Omegonprocam()

Most methods of the Omegonprocam class use ctypes to call into the corresponding Omegonprocam_xxxx functions of omegonprocam.dll/so/dylib. So, the descriptions of the Omegonprocam_xxxx function are also applicable for the corresponding python methods.

Please reference __errcheck in omegonprocam.py, the original HRESULT return code is mapped to HRESULTException exception (in win32 it's inherited from OSError).

Please make sure the omegonprocam dll/so/dylib library file is in the same directory with omegonprocam.py.


7. Java


Omegonprocam does support Java, omegonprocam.java use JNA to call into omegonprocam.dll/so/dylib. Copy omegonprocam.java to your java project, please reference the sample code simplest.java (Console), javafx.java, swing.java.

Please pay attation to that the object of the java class omegonprocam must be obtained by static method Open or OpenByIndex, it cannot be obtained by obj = new omegonprocam()(The constructor is private on purpose).

Most methods of the omegonprocam class use JNA to call into the corresponding Omegonprocam_xxxx functions of omegonprocam.dll/so/dylib. So, the descriptions of the Omegonprocam_xxxx function are also applicable for the corresponding java methods.

Please reference errcheck in omegonprocam.java, the original HRESULT return code is mapped to HRESULTException exception.

Remark: (1) Download jna-*.jar from github; (2) Make sure omegonprocam.dll/so/dylib is placed in the correct directory.


8. Samples


Name Platform Language Dependency UI Description
demosimplest Win32
Linux
macOS
Android
C++   console simplest sample, about 70 lines of code. snapshot.
demowait Instead of using the callback function, use the Omegonprocam_WaitImageV3 to get the image, about 60 lines of code
demomulti Open all the enumerated cameras (possibly multiple) and pull image, about 90 lines of code
demostill simplest sample to demo snap still image, about 120 lines of code
demosofttrigger simplest sample to demo soft trigger, about 80 lines of code
demotriggersync simplest sample to demo soft trigger synchronously (TriggerSync), about 80 lines of code
demoexternaltrigger simplest sample to demo external trigger, about 130 lines of code
demotriggerout simplest sample to demo output signal, about 150 lines of code
demoraw raw data, snap still image and save raw data to *.raw files, about 140 lines of code. snapshot.
demostillraw snap still raw image and save to *.raw files, about 140 lines of code
demoqt Win32
Linux
macOS
Qt GUI Qt sample, snapshot.
Enumerate device, open device, video preview, (still) image capture, preview resolution, image save to file, etc. This sample use Pull Mode, StartPullModeWithCallback.
demotwoqt Qt sample, snapshot.
Use two cameras simultaneously
democpp Win32 ATL/WTL snapshot. demonstrates to enumerate device (Respone to device plugin/unplug notifications), initialize support GigE, open device, video preview, image capture, preview resolution, trigger, image saving multi-format (.bmp, .jpg, .png, etc), wmv format video recording, trigger mode, IO control, read write EEPROM/FLASH, etc. This sample use Pull Mode. To keep the code clean, this sample uses the WTL library which can be downloaded from http://sourceforge.net/projects/wtl
democallback snapshot. use Pull Mode, StartPullModeWithCallback
demopush snapshot. use Push Mode, StartPushModeV4
demomono demonstrates to use mono camera with 8 or 16 bits
democns snapshot. Consistency test: The image is evenly divided into m*n zones, and each zone takes a small area in the center to calculate the average value, connect the average value into a line, and check the fluctuation range of the line up and down
triggertest snapshot. Soft trigger test, use a background thread to save the image file to disk (SSD is recommended, otherwise, when the disk speed is insufficient, the storage speed will not be able to keep up, more and more images will be stored in the deque, and the memory consumption will also increase).
demomfc MFC snapshot. use MFC as the GUI library. It demonstrates to open device, video preview, image capture, set the preview resolution, multi-format image saving (.bmp, .jpg, .png, etc). This sample use Pull Mode
autotest snapshot. auto test tool used to automatically test, such as open/close the camera, change the resolution, snap, ROI, bitdepth, etc
demowpf .NET C# WPF WPF sample, snapshot.
Enum camera, open camera, preview video, captuare (still) image, save image to file, auto exposure, white balance, calculate fps (frame per second), etc. This sample use Pull Mode, StartPullModeWithCallback
demowinformcs WinForm winform sample, snapshot.
Enum camera, open camera, preview video, captuare (still) image, save image to file, auto exposure, white balance, calculate fps (frame per second), etc. This sample use Pull Mode, StartPullModeWithCallback
demotwocs winform sample, snapshot.
Use two cameras simultaneously. This sample use Pull Mode, StartPullModeWithCallback
demowinformvb VB.NET winform sample, snapshot.
Enum camera, open camera, preview video, captuare (still) image, save image to file, auto exposure, white balance, calculate fps (frame per second), etc. This sample use Pull Mode, StartPullModeWithCallback
demouwp WinRT C#   UWP (Universal Windows Platform) simple demo, snapshot.
Before build and run this demo, please pay attention to the value of vid in file Package.appxmanifest
demoandroid Android Java
C++
Android sample
demojava simplest Win32
Linux
macOS
Java jna console simplest java sample. IntelliJ project
javafx GUI javafx sample. IntelliJ project
swing swing sample. IntelliJ project
demopython simplest Python console simplest python sample
qt PyQt GUI PyQt sample, snapshot.
demodshow DirectShow C++ MFC DirectShow sample
amcap Microsoft sample demonstrates various tasks related to video capture, see https://github.com/microsoft/Windows-classic-samples/tree/main/Samples/Win7Samples/multimedia/directshow/capture/amcap
LVDemo1 LabView     Labview program which works with one camera
LVDemo2 Labview program which opens two cameras and control them respectively
imagepro liveedf Win32 C++ Qt Qt sample, snapshot.
C# WinForm C# sample, snapshot.
livestack C++ Qt Qt sample, snapshot.
C# WinForm C# sample, snapshot.

9. Changelog


v55: Add Support to HDR Pixel Format

v54: Add support to GigE. Please see here

v53: Add OmegonprocamFrameInfoV3, Omegonprocam_PullImageV3, Omegonprocam_StartPushModeV4

v52: Android Java side transfer file descriptor to Omegonprocam_Open to open camera. Please see here

v51: Add support auto exposure "once" mode. Please see here

v50: SIMD optimize in Windows(x86/x64), Linux(x64) and Android(x64)
       frontend and backend deque length: OMEGONPROCAM_OPTION_FRONTEND_DEQUE_LENGTH, OMEGONPROCAM_OPTION_BACKEND_DEQUE_LENGTH

v49: Add support to save & load configuration. Please see here

v48: hardware event. Please see here, here and here

v47: hardware level range. Please see here and here

v46: Add support denose. Please see here

v45: Add sequencer trigger, UART, mix trigger (external and software trigger both are enabled)

v44: Extend the realtime mode, Please see here
       Add OMEGONPROCAM_OPTION_CALLBACK_THREAD and OMEGONPROCAM_OPTION_FRAME_DEQUE_LENGTH

v43: Reload the last frame in the trigger mode. Please see OMEGONPROCAM_OPTION_RELOAD

v42: Precise frame rate and bandwidth. Please see here and OMEGONPROCAM_FLAG_PRECISE_FRAMERATE

v41: no packet timeout. Please see here

v40: Auto test tool, see samples\autotest

v39: Update C#/VB.NET/Java/Python

v38: Add support to byte order, change BGR/RGB. Please see here

v37: Add Android support
       Add Omegonprocam_StartPushModeV3 (Omegonprocam_StartPushModeV2 and Omegonprocam_StartPushMode are obsoleted)

v36: Add Java support. Please see here

v35: Add Python support. Please see here

v34: Auto Focus and Focus Motor

v33: extend OMEGONPROCAM_OPTION_AGAIN to OMEGONPROCAM_OPTION_AUTOEXP_POLICY, support more options. Please see here

v32: Addd support to Windows 10 on ARM and ARM64, both desktop and WinRT

v31: Add Omegonprocam_deBayerV2, support RGB48 and RGB64

v30: Add OMEGONPROCAM_FLAG_CGHDR

v29: Add OmegonprocamFrameInfoV2, a group of functions (PullImageV2 and StartPushModeV2), some cameras support frame sequence number and timestamp. Please see here

v28: Add Omegonprocam_read_Pipe, Omegonprocam_write_Pipe, Omegonprocam_feed_Pipe

v27: Add Omegonprocam_SnapN, support to snap multiple images, please see here and democpp

v26: Add support to restore factory settings, OMEGONPROCAM_OPTION_FACTORY

v25: Add sharpening, OMEGONPROCAM_OPTION_SHARPENING

v24: Add support to Exposure time with the 50/60 HZ constraint

v23: Add support to Linux armhf, armel and arm64
       Add FFC and DFC, please see here and here

v22: Add OMEGONPROCAM_OPTION_DDR_DEPTH, please see here

v21: Add Omegonprocam_IoControl

v20: Add Omegonprocam_EnumV2, OmegonprocamModelV2, OmegonprocamDeviceV2; (Omegonprocam_Enum, OmegonprocamModel and OmegonprocamDevice are obsoleted)
       Add Pixel Format, see OMEGONPROCAM_OPTION_PIXEL_FORMAT; (OMEGONPROCAM_OPTION_PIXEL_FORMAT is the super set of OMEGONPROCAM_OPTION_BITDEPTH)
       Add Flat Field Correction

v19: Add Black Balance: please see here

v18: Add Omegonprocam_get_Revision

v17: Add OMEGONPROCAM_OPTION_ROTATE

v16: Add OMEGONPROCAM_FLAG_DDR, use very large capacity DDR (Double Data Rate SDRAM) for frame buffer

v15: Add OMEGONPROCAM_OPTION_BINNING

v14: Add support to WinRT / UWP (Universal Windows Platform) / Windows Store App

v13: support row pitch, please see Omegonprocam_PullImageWithRowPitch and Omegonprocam_PullStillImageWithRowPitch

v12: support RGB32, 8 bits Grey, 16 bits Grey, please see here

v11: black level: please see here

v10: demosaic method: please see here

v9: change the histogram data type from double to float

v8: support simulated trigger, please see here

v7: support RGB48 when bitdepth > 8, please see here

v6: support trigger mode, please see here

v5: White Balance: Temp/Tint Mode vs RGB Gain Mode, please see here

v4: ROI (Region Of Interest) supported: please see here

v3: more bitdepth supported: 10bits, 12bits, 14bits, 16bits

v2: support RAW format, please see here and here; support Linux and macOS

v1: initial release