CatchBEST Camera API Programming Introduction

CatchBEST Vision Technologies (Beijing) Co., Ltd.
CatchBEST Industrial Cameras
API programming introduction

V1.0
CatchBEST Vision Technologies (Beijing) Co., Ltd. 1

Tel：86(010)51709170 Fax：86(010)51709171 Email: usb2cam@hotmail.com Http://en.catchbest.com
Address：Room C802,Building C, Jiahaoguoji Centre，116#,Zizhuyuan Road,Haidian District,Beijing ,China
Operation for black&white(mono)

camera
The most simple capture operations
1． First initialize the dynamic library, call “KSJ_Init” function.
2． Get the devices number of connected to the PC:
int nDeviceNum = KSJ_DeviceGetCount();
3． Set the capture field of view (if the user does not set, the default is the large format field of view, no
skip mode), the following setting is the 0th capture device field of view 0,0,1280,1024, no skip mode:
KSJ_CaptureSetFieldOfView(0,0,0,1280,1024, KSJ_SKIPNONE, KSJ_SKIPNONE);
4． “KSJ_CaptureGetSize” function can get image’s width and height (unit: pixel):
Int nWidth, nHeight;

KSJ_CaptureGetSize( 0, &nWidth, &nHeight );
5． Call “KSJ_SetParam (KSJ_RED, nRedValue);” to set the gain, for the black&white camera, you can
casually select “KSJ_RED” or “KSJ_GREEN”, or “KSJ_BLUE”, only call one of the three, the others will
follow the changes to the same value. You can set the exposure value by calling “KSJ_SetParam
(KSJ_EXPOSURE, nEValue);”.
6． Allocate memory by “Nwidth”, “nHeight”
Unsigned char *pData = (unsigned char*)malloc( nWidth * nHeight );
7． Call the capture function to capture “KSJ_CaptureRawData (0, pData);” , for black&white camera do
not call this function.

KSJ_CaptureRgbData.
8． If you want to save the data as bmp, jpg, please call “KSJ_HelperSaveToBmp”, or
“KSJ_HelperSaveToJpg”. Note: “nBitCount” value is 8.
9． Last call “KSJ_UnInit” function for un-initialization the dynamic library.
The most simple preview operation
First, initialize dynamic library, call “KSJ_Init” function
1． Get the device number which are connected to PC:
int nDeviceNum = KSJ_DeviceGetCount();
2． Set the preview field of view (if the user does not set, the default is the large format field of view, no
KSJ_PreviewSetFieldOfView(0,0,0,1280,1024, KSJ_SKIPNONE, KSJ_SKIPNONE);
3． Call “KSJ_PreviewGetSize” function to get the width and height of preview image (unit:pixel):

KSJ_PreviewGetSize( 0, &nWidth, &nHeight );
4． Call “KSJ_PreviewSetPos” to set which window the preview image will be displayed in and the
position of this window
5． Call “KSJ_PreviewStart (0, true);” to open the video stream
6． Call “KSJ_SetParam (KSJ_RED, nRedValue);” to set the gain, for the black&white camera, you can
casually select “KSJ_RED” or “KSJ_GREEN”, or “KSJ_BLUE”, only call one of the three, the others will
follow the changes to the same value. You can set the exposure value by calling “KSJ_SetParam
(KSJ_EXPOSURE, nEValue);”.

7． Call “KSJ_PreviewPause(0,true);” to pause the preview. After the successful pause, call
“KSJ_PreviewGetPausedData(0, pData);” function to get that frame image, you need allocated
memory before calling this function, and get the required memory size by calling
“KSJ_PreviewGetSize”, the data can be saved as BMP or JPG file by calling “KSJ_HelperSaveToBmp” or
“KSJ_HelperSaveToJpg” function. Then call “KSJ_PreviewPause(0, false);” to continue the video
stream, finally call “KSJ_PreviewStart (0, false);” to turn off the video stream.
8． Finally call “KSJ_UnInit” function to un-initialize the dynamic library.
Note: The development package completely separated video preview and capture, these two parts
can be run separately, and also can be run at the same time time,, so the skip mode can be different at
view,, It is more in line with the requirements of the application.
preview and capture of field of view

Program operation of colour camera
The most simple capture operation

capture
1． First initialize the dynamic library, call “KSJ_Init” function
2． Get the device number of contacted the PC: int nDeviceNum = KSJ_DeviceGetCount();
3． Set the capture field of view (if the user does not set, the default is the large format field of view, no
KSJ_CaptureSetFieldOfView(0,0,0,1280,1024, KSJ_SKIPNONE, KSJ_SKIPNONE);
4． Int nWidth, nHeight;

Call “KSJ_CaptureGetSize” function to get the image’s width and height (unit: pixel):

KSJ_CaptureGetSize( 0, &nWidth, &nHeight );
5． Call “KSJ_SetParam” function to set “KSJ_RED”, “KSJ_GREEN”, “KSJ_BLUE” colour’s gain. Call
“KSJ_SetParam(KSJ_EXPOSURE,nEValue);” function to set the exposure value.
6． Allocate the memory according to nWidth,nHeight
Unsigned char *pData = (unsigned char*)malloc( nWidth * nHeight * 3 );
7． Capture 24 bit colour image by calling function “KSJ_CaptureRgbData (0,pData );”
8． If you want to save the data as format of bmp, jpg, please call function “KSJ_HelperSaveToBmp” or
“KSJ_HelperSaveToJpg”, note: the value of nBitCount is 24.
9． Finally, call “KSJ_UnInit” function to un-initilized dynamic library
The most simple preview operation
First, initialize the dynamic library by calling function “KSJ_Init”.

1． Get the device number of contacted host by calling function “int nDeviceNum
=KSJ_DeviceGetCount();”
2． Set the preview field of view (if the user does not set, the default is the large format field of view, no
KSJ_PreviewSetFieldOfView(0,0,0,1280,1024, KSJ_SKIPNONE, KSJ_SKIPNONE);
3． Calling function “KSJ_PreviewGetSize” to get the preview image’s width and height (unit: pixel): Int
nWidth, nHeight;
KSJ_PreviewGetSize( 0, &nWidth, &nHeight );
4． Call function “KSJ_PreviewSetPos” to set which window the preview image will be displayed in and
the position of window.
5． Call function “KSJ_PreviewStart ( 0,true );” to start the video stream.
6． Call function “KSJ_SetParam” to set “KSJ_RED”, “KSJ_GREEN”, “KSJ_BLUE” colour ‘s gain. Call function
“KSJ_SetParam(KSJ_EXPOSURE,nEValue);” to set the exposure value.
7． Call “KSJ_PreviewPause(0,true);” to pause the preview. After the successful pause, call function
“KSJ_PreviewGetPausedData(0, pData)” to get that frame image, you need allocated memory before
calling this function, and get the required memory size by calling “KSJ_PreviewGetSize”, the data can
be saved as BMP or JPG file by calling “KSJ_HelperSaveToBmp” or “KSJ_HelperSaveToJpg” function.
After that call “KSJ_PreviewPause(0, false);” function to continue the video stream, finally call
“KSJ_PreviewStart(0, false);” to turn off the video stream.
8． Finally call “KSJ_UnInit” function to un-initialize the dynamic library.

Note: The development package completely separated video preview and capture, these two parts
can be run separately, and also can be run at the same time time,, so the skip mode can be different at
preview and capture of field of view
view,, It is more in line with the requirements of the application.

External trigger capture programming

The external trigger button’s connection circuit is as below: (It’s made by user)
SW1
SNAP
GND
In the camera, SNAP connection is connected to the pull-up resistor, so the normal is high-voltage (3.3V),
when the SW1 button is pressed, SNAP connection is low-voltage.
We can the call function “KSJ_API int __ stdcall KSJ_SnapButtonStatus ( int nChannel,
KSJ_SNAPBUTTONSTATUS * pSnapButtonStatus);” to get SNAP connection status to determine the status
of the SW1 button. Through this status, we can program to do low-voltage trigger for capture or fall time
of pulse trigger for capture control.
The capture operation of the external control trigger has two simple programmings:
1. Operation in the preview callback function
1.1 Set the preview callback function, please refer to the explaination of “KSJ_PreviewSetCallback” in the
“CatchBEST Camera API Function Instruction Manual” and see the call example.
1.2 Read the button’s status by calling the callback function “KSJ_SnapButtonStatus”, when the conditions
are met, this frame image will be captured by the external trigger. The following example means that
when you pressed one button you can make a capture:
static KSJ_SNAPBUTTONSTATUS PrvSnapButtonStatus = KSJ_UP;

static KSJ_SNAPBUTTONSTATUS CurSnapButtonStatus = KSJ_UP;
int CMyWnd::PreviewCallback(unsigned char *pImageData, int nWidth, int nHeight, int nBitCount)
{
// Read the status of the button
KSJ_SnapButtonStatus( m_nDeviceIndex, &CurSnapButtonStatus );
TCHAR Buf[256] = {‘\0’};
_stprintf( Buf, _T("Snap Button: %s\n"), CurSnapButtonStatus == KSJ_UP ? _T("UP") : _T("DOWN") );
OutputDebugString( Buf );
// Press the button, save this frame image
if( CurSnapButtonStatus == KSJ_DOWN && PrvSnapButtonStatus == KSJ_UP )
KSJ_HelperSaveToBmp( pImageData, nWidth, nHeight, nBitCount, "c:\\snap.bmp" );
PrvSnapButtonStatus = CurSnapButtonStatus;
}

2．P
Polling in the thread test
2.1 Open one thread or timer
2.2 Check the external button status in the threads or timer condition reached, and when conditions
fullfilled, call the related capture function to get the image.
Note: this external trigger capture mode can completely separate the preview and external trigger
capture, that is, you can check the external button status while you open the preview video stream, when
the conditions fullfilled, You can call the capture function to capture and preview different field of view.
For details, please refer to the related function explain of capture and preview in the “CatchBEST Camera
API Function Instruction Manual”. The following code means read the external trigger buton status in the
timer of 1000ms, when the button press is detected, capture an image according to the setted capture
field of view:
// First, set one timer of 1000 ms
SetTimer( 1, 1000, NULL );
// Read the information of the external trigger key within timer, capture a image when the external
button is pressed.
void CVideoChildFrame::OnTimer(UINT nIDEvent)

{
If( nIDEvent != 1 ) return;
// Read the status of external button

KSJ_SnapButtonStatus( m_nDeviceIndex, &CurSnapButtonStatus );
CHAR Buf[256];
_stprintf( Buf, _T("Snap Button: %s"), CurSnapButtonStatus == KSJ_UP ? _T("UP") : _T("DOWN") );
OutputDebugString( Buf );
// Press the button

if( CurSnapButtonStatus == KSJ_DOWN && PrvSnapButtonStatus == KSJ_UP )
{
int nWidth, nHeight;
// Read the capture image size in the current field of view setting.
KSJ_CaptureGetSize( m_nDeviceIndex, &nWidth, &nHeight );
// Allocate the capture memory space

BYTE *pImageData = new BYTE [nWidth * nHeight * 3];
// Captue the image

KSJ_CaptureRgbData( m_nDeviceIndex, pImageData );

// Save the image
KSJ_HelperSaveToBmp( pImageData, nWidth, nHeight, 24, "c:\\snap.bmp" );
// Release the memory
delete [] pImageData;
}
PrvSnapButtonStatus = CurSnapButtonStatus;
CMDIChildWnd::OnTimer(nIDEvent);
}
Explain: there’s only inquery mode, and no intermit mode in reading the external trigger.

Programming of multiple cameras at

same time
BestScope CatchBEST USB2.0 industry camera’s driver and SDK support multiple of the different type
cameras and same type cameras to make capture and preview at the same time. Same time in here is not
true the same time, but the fact is time-sharing. USB 2.0 can transmit 480Mbps in theory, but it can
transmit about 400 Mbps in fact, at same time need to value your USB2.0 master chip’s performance in
the PC. According to our experience, Intel 845 chip or the aboves can support USB 2.0 better, when you
connect multiple cameras to the PC, the bandwidth will be sharing, USB 2.0 master chip will read the data
by polling of time slice, so the frame rate will be decreased accordingly.
Programming for multiple cameras is relatively simple, brief steps are as follows:
1． Initialize the dynamic library, call function “KSJ_Init”.
2． Get the device number of connected to the host: int nDeviceNum = KSJ_DeviceGetCount();
3． According to the devices number, in turn call “KSJ_API int __ stdcall, KSJ_DeviceGetInformation (IN
int nChannel, the OUT KSJ_DEVICETYPE * pDeviceType, OUT int * pnIndex, the OUT WORD *
pwFirmwareVersion); ” to get the model of each camera, the same type of equipment distinguish by
serial number. We also can provide the corresponding program to rewrite the internal serial number
of each camera. The detail operations please see “BestScope firmware upgrade guide and rewrite the
serial number”.
4． After that use “nChannel=0,1,...(nDeviceNum-1)” to call “KSJApi” function to operate each camera
separately. For the detail operation, please refer to the above described “black and white camera
operation” and “color camera operation”.

Camera recovery for the abnormal

For the stability of equipment operation, we have added the recovery function in the firmware, drivers
and SDK to ensure recovery to the previous status while the abnormal operations, eliminated instabilizing
factors in preview and capture process.
Abnormal recovery main includes preview recovery and the capture recovery:
1. Preview recovery
When the user calls function “KSJ_PreviewStart (nChannel, TRUE);”, API development package will display
the video stream on the user specified window, unplug the camera's USB cable, the API will continuously
detect user’s re-insert the camera operation, if Yes, API will call the user’s previous field of view setting to
camera, and automatically restore the video stream, so the abnormal recovery of the camera are
auto-completed in development package, the user don’t need special operation in the programming.
2. Capture recovery
When the user called function “KSJ_CaptureRawData”, or “KSJ_CaptureRgbData”, if the camera's USB
cable has been pulled out, the above function will return to the “RET_RECOVERY_FAIL” , when the camera
is connected again, call “KSJ_CaptureRawData” or “KSJ_CaptureRgbData” function will automatically
recover the camera, and reset settings in accordance with previous user’s field of view setting, so users
do not need special operate for the capture automatically recovery, but must judge whether or not
“KSJ_CaptureRawData”, or “KSJ_CaptureRgbData” return value is “RET_SUCCESS”.
Note: When between the camera pulled out to re-connect, if the user does not call
“KSJ_CaptureRawData “ or “KSJ_CaptureRgbData”, then once the camera is connected, the first time call
“KSJ_CaptureRawData “ or “KSJ_CaptureRgbDat”, it will return to “RET_RECOVERY_SUCCESS”, this does
not mean “KSJ_CaptureRawData”, or “KSJ_CaptureRgbData” are successfully called, but means the
capture failed, the recovery is successful. Call “KSJ_CaptureRawData” or “KSJ_CaptureRgbData” function
again, then it will return to “RET_SUCCESS”.
Note: after the camera is disconnected, it’s will return to “RET_FAIL” when call some functions which are
communicating with the hardware. For example, the “KSJ_DeviceGetInformation” and “KSJ_SetParam”
functions only can be called after confirm that the camera has recovered to nomal status.
“KSJ_DeviceGetInformation”, and “KSJ_SetParam” functions do not have internal recovery mechanism.
For capture recovery, the recovery mechanism only exists in the two functions of “KSJ_CaptureRawData”,
and “KSJ_CaptureRgbData” function.

Explanation on the Bayer mode

Note: the Bayer mode only effective for the color cameras, black&white camera does not need to do
Bayer conversion.
BestScope CatchBESTA/B/C-130C cameras’ the photosensitive array of image sensors is as following:
Figure 1. RGGB array
Each square represents a pixel, each pixel only receives R, G, B, one of them. After Bayer conversion, each
pixel will be reconstruct of a 24 or 32-bit RGB of color pixels, all pixels will be reconstructed to create a
color image by Bayer mode. The user can set Bayer mode by calling “KSJ_BayerSetMode”. Currently
supported Bayer mode including:
KSJ_BGGR_BGR24
Pixels arrangement is:
B G B G…
G R G R…
B G B G…
…
After conversion it is a 24-bit bitmap format. In order to keep the display image not flip vertically, we will
transform the first pixel line to the last line of the RGB bitmap memory (this is because “Windows GDI”
function displays the first line in the image is actually the last line of the image in memory), so when you
set “KSJ_BGGR_BGR24”, “KSJ_GRBG_BGR24”, “KSJ_RGGB_BGR24”, “KSJ_GBRG_BGR24”,
“KSJ_BGGR_BGR32”, “KSJ_GRBG_BGR32”, “KSJ_RGGB_BGR32”, “KSJ_GBRG_BGR32” functions. You can
get the RGB bitmap data after calling of the “KSJ_CaptureRgbData” or “KSJ_CaptureRgbDataEx”. The pixel
conversion results under the photosensitive array picture are stored in the starting address.

If you want to save pixel converted values of the photosensitive array into the RGB bitmap data
starting address in memory, you can call “KSJ_BGGR_BGR24_FLIP”, “KSJ_GRBG_BGR24_FLIP”,
“KSJ_RGGB_BGR24_FLIP”, “KSJ_GBRG_BGR24_FLIP”, “KSJ_BGGR_BGR32_FLIP”, “KSJ_GRBG_BGR32_FLIP”,
“KSJ_RGGB_BGR32_FLIP”, “KSJ_GBRG_BGR32_FLIP” functions according to the pixel arrangement.
For CatchBESTA/B/C-130C cameras, the arrangement is “RGGB” format. For CatchBESTA/B/C-320C

cameras, the arrangement is “GRBG” format. When you set the Bayer mode, be sure to correspond to the
format of the photosensitive array, otherwise the color and white balance algorithm will be incorrect. For
24 bit color bitmap, each pixel is consisted of B, G, R format, each pixel is 8bit. For 32 bit color bitmap,
each pixel is consisted of B, G, R, 0 format, each pixel is 8bit.
KSJ_GRBG_BGR24
KSJ_GRBG_BGR32
KSJ_GRBG_BGR24_FLIP
KSJ_GRBG_BGR32_FLIP
G R G R…
B G B G…
G R G R…
…
After conversion it is a 24-bit or 32-bit bitmap format(it is decided by “BGR24” or “BGR32”).
The 1st row of pixel arrangement is converted to the last row or the first row of RGB bitmap memory
address(it is decided by the “FLIP”).
KSJ_RGGB_BGR24
KSJ_RGGB_BGR32
KSJ_RGGB_BGR24_FLIP
KSJ_RGGB_BGR32_FLIP
R G R…
G B G…
R G R…
…
KSJ_GBRG_BGR24
KSJ_GBRG_BGR32
KSJ_GBRG_BGR24_FLIP

KSJ_GBRG_BGR32_FLIP
G B G B…
R G R G…
G B G B…
…
Note: The white balance area location will also be adjusted, the adjusted result makes the upper left
conrner of the display images as the origin, the user setted white balance area unchanged relative to the
upper left corner of the image.
The auto exposure area is the same as above.
Note: When a user call “KSJ_SetParam” function and set “KSJ_FLIP” as 1, it means that control the front
array to output from the last row, that is, the raw data which we read will vertically flip. So that the
“Bayer” mode also need to be setted based on the actual situation. For example, the original is “RGGB”,
after flip, it is “GBRG” mode.
Explanation: The above settings on the modes, regardless of the flip or not flip, it will not affect the
performance of capture. So users please do not write your own flip algorithm, you should use “KSJ_FLIP”
and “KSJ_BayerSetMode” of “KSJ_SetParam” to find a proper combination to flip.

Instruction on “GPIO
GPIO”” operation
CatchBESTA/B/C-130C, CatchBESTA/B/C-130M and CatchBESTA/B/C-320C have 4 “IO” can be provided for
customers to operate. Users can call “KSJ_GpioSetDirection”, “KSJ_GpioGetDirection”,
“KSJ_GpioSetStatus”, and “KSJ_GpioGetStatus” functions to set and read input/output status, electrical
level status of “IO” pins. The 4 “IO” are connected to a pull-up resistor inside the camera. For detail
introduction of the 4 functions, please refer to “CatchBEST Camera API Function Instruction Manual”.
Call example (Set “GPIO0-GPIO” as output, “GPIO0” output 1, “GPIO1” output 0, “GPIO2” output 1;
Set “GPIO3” as input, and read the input status of “GPIO3” pin)
// Set input/output status of pin, “GPIO3:GPIO” correspond to “BIT3:BIT0”, the corresponding 1 means
output, 0 means input.
KSJ_GpioSetDirection( nDeviceIndex, 0x07);
// Set output electrical level of the output pin, will not effect input pin
KSJ_GpioSetStatus( nDeviceIndex, 0x05);
// Read electrical level status of the pin

BYTE btStatus;
KSJ_GpioGetStatus( nDeviceIndex, &btStatus );
If btStatus & 0x08 != 0x00, then means “GPIO3” input is 1, otherwise means input is 0.
Note: For UC500C_MRYN,UC500M_MRYN,UC36M_MGYN,UC36C_MGYN cameras, there are 6 “IO” can

be provided for users to operate.

External extension interface

introduction 1
This interface introduction is applied to the modules of UC130C_MRYN, UC130M_MRYN, UC200C_MRYN,
UC320C_MRYN industry camera which are supplied to the users.
The position is as below:
The definitions of pins are as below:
PIN 1 2 3 4 5 6 7 8 9 10
Name LED+ USB_5V USB_GND SNAP IO1 IO0 IO3 IO2 TXD RXD
The introductions of pins are as following:
Pin1 (LED +): Anode drive LED, LED light when the PC capture images. LED + internal series connect 330Ω
resistor and connected to +3.3 V, the circuit connection is as follows:
LED+
LED
GND

Pin2 (USB_5V): Take +5 V voltage from the PC's USB interface for external supply, the current should be
less than 200mA.
Pin3 (USB_GND): USB interface of PC and camera to the ground.
Pin4 (SNAP): Connected to external capture button, press button to capture a single image. About
“External capture trigger” please refer to the related “the external trigger capture Programming " part in
this article. The connection circuit is as follows:
SW1
SNAP
GND
Pin5 (GPIO1), Pin6 (GPIO0), Pin7 (GPIO3), Pin8 (GPIO2): 4-bit GPIO port can be set by software for input
or output, and flexible to control. All of the “IO” ports in the camera are connected to +3.3 V via the
pull-up resistor. Regarding the related operation of “GPIO”, please refer to “Instructions on the GPIO”
section of this article.
Pin9 (TXD), Pin10 (RXD): extension of the asynchronous serial port. Not supported at present.

External extension interface

introduction 2
This interface introduction is applied to the modules of UC500C_MRYN, UC500M_MRYN, UC36C_MGYN,
and UC36M_MGYN industry cameras which are supplied to the users.
The position is as below:
The definitions of pins are as below:
PIN 1 2 3 4 5 6 7 8 9 10
Name FLASH USB_5V USB_GND SNAP IO1 IO0 IO3 IO2 IO4 IO5
The introductions of pins are as following:
Pin1 (LED+): the flash trigger signal, the user can set the flash trigger signal by “KSJ_FlashControl”,
including enable or not, the effective level is overturned or not, the effective width etc. Details please
refer to the introductions on flash trigger signal in this article and “CatchBEST Camera API Function
Instruction Manual".
Please note that the signal directly comes from the camera sensor, it is only used as the trigger signal,
users need to consider of using switch triode circuit or Optical coupling isolation circuit. Large current or

high voltage may damage the camera.
pin2 (USB_5V): Take +5 V voltage from the PC's USB interface for external supply, the current should be
less than 200mA.
Pin3 and (USB_GND): USB interface of PC and camera to the ground.
Pin4 (SNAP): Connected to external capture button, press button to capture a single image. About
“External capture trigger” please refer to the related “the external trigger capture Programming" part in
this article. The connection circuit is as follows:
SW1
SNAP
GND
Pin5 (GPIO1), Pin6 (GPIO0), Pin7 (GPIO3), Pin8 (GPIO2), Pin9(GPIO4), Pin10(GPIO5): 6-bit GPIO port can
be set by software for input or output, and flexible to control. All of the “IO” ports in the camera are
connected to +3.3 V via the pull-up resistor. Regarding the related operation of “GPIO”, please refer to
“Instructions on the GPIO” section of this article.
Flash signal trigger instructions

UC500C_MRYN, UC500M_MRYN series cameras support trigger by the flash trigger signal. Please refer to
the "external expansion interface instruction 2” part.
In order to support the exposure and external flash synchronization, the effective moment of the Flash
signal is right exposure time of all the rows. For the image sensor of electronic rolling shutter, only this
time is the global exposure, so suitable for use at night to add the flash to capture fast moving objects.
After Flash signal works (by calling KSJ_FlashControl), when capture image each time, output flash
signals.
In order to take normal images with flash, you must follow the below exposure settings:
The number of exposure rows must be greater than (effective line number of capture field of view +256)
the required time. The number 256 is the camera's default setted number of rows vertical blank. The
time required of each line is (capture field of view’s number of columns +1280) * (1/48000000).
1/48000000 is the point frequency, means the camera output 48000000 points per second, then the time
each point takes is 1/48000000 second. So (the number of columns of capture field of view +1280) *
(1/48000000) is the time of one line, the 1280 is the camera default settings for the line blanking time.
The exposure time unit which we provide for API function is “ms”, so you need to conversion.
For example, you set the column numbers of capture field of view, columns: X=4096, rows: Y = 2048, then
with the following formula, you can calculate the minimum exposure time:
（Y+256）*（X+1280）/48000000 = (2048+256)*（4096+1280）/48000000 = 0.258048(S) = 258.048(ms)
The setting time is at least 259ms.
Appendix: Technical Information (internal trigger timing)
After user call the capture function, when the camera receive capture instructions of “TRIGGER” singal,
the camera will send the trigger signal to the image sensor, user don’t need concern it.
STROBE signal is what we said FLASH signal, when the image sensor receives the Trigger signal, in the (H +
VB) * tRow time, “H” means the number of rows in the setted field of view, “VB” is the vertical blanking

interval of the row numbers. The FLASH signal is effective, the high electical level is also effective. If it is
risetime or falltime to trigger the flash, here is the risetime trigger. The default effective width time of the
FLASH is tRow, that is the time of a row of data.
We default the time from TSE to TSW is a tRow time, this is the camera default setting timing, it is also
the timing of normal to use the flash. In fact, we can set “TSE” appear moment after “8* tRow” moment,
which after TRIGGER, extend the high levle of “FLASH (STROBE)”. We can customerize this program if
customers need.

External trigger interface customization

camerass with shell
of camera
All external trigger pins can be output by customorized air plugs, currently support four ports output.
For UC500C_MRYN, UC500M_MRYN, UC36C_MGYN and UC36M_MGYN, the standardized output way
are as follows:
Pin1：FLASH
Pin2：USB_5V
Pin3：USB_GND
Pin4：SNAP
Users can find the pin’s serial number next to the lead pin of plug. And offer socket as an accessory.

Instructions for us ing the color camera as

using
the black&white camera
black&
We added eight Bayer modes to convert the color camera “Raw” data to grayscale data, this 8 modes are
KSJ_BGGR_GRAY8, KSJ_GRBG_GRAY8, KSJ_RGGB_GRAY8, KSJ_GBRG_GRAY8, KSJ_BGGR_GRAY8_FLIP,
KSJ_GRBG_GRAY8_FLIP, KSJ_RGGB_GRAY8_FLIP, KSJ_GBRG_GRAY8_FLIP. Users choose the Bayer mode
according to the format of raw data. Users only need to call “KSJ_BayerSetMode” to set the black&white
mode, the bit depth when capture images will be directly affected, means that the captured bitmap will
be 8-bit grayscale bitmap. Please pay attention to this.


CatchBEST Camera API Programming Introduction

Caricato da

Informazioni sul documento

Copyright

Formati disponibili

Condividi questo documento

Condividi o incorpora il documento

Opzioni di condivisione

Hai trovato utile questo documento?

Questo contenuto è inappropriato?

Copyright:

Formati disponibili

CatchBEST Camera API Programming Introduction

Caricato da

Copyright:

Formati disponibili

CatchBEST Vision Technologies (Beijing) Co., Ltd.

CatchBEST Industrial Cameras

API programming introduction

CatchBEST Vision Technologies (Beijing) Co., Ltd. 1

Operation for black&white(mono)

The most simple capture operations

1． First initialize the dynamic library, call “KSJ_Init” function.

2． Get the devices number of connected to the PC:

int nDeviceNum = KSJ_DeviceGetCount();

KSJ_CaptureSetFieldOfView(0,0,0,1280,1024, KSJ_SKIPNONE, KSJ_SKIPNONE);

Int nWidth, nHeight;

6． Allocate memory by “Nwidth”, “nHeight”

Unsigned char *pData = (unsigned char*)malloc( nWidth * nHeight );

CatchBEST Vision Technologies (Beijing) Co., Ltd. 2

9． Last call “KSJ_UnInit” function for un-initialization the dynamic library.

The most simple preview operation

First, initialize dynamic library, call “KSJ_Init” function

1． Get the device number which are connected to PC:

int nDeviceNum = KSJ_DeviceGetCount();

KSJ_PreviewSetFieldOfView(0,0,0,1280,1024, KSJ_SKIPNONE, KSJ_SKIPNONE);

Int nWidth, nHeight;

5． Call “KSJ_PreviewStart (0, true);” to open the video stream

CatchBEST Vision Technologies (Beijing) Co., Ltd. 3

8． Finally call “KSJ_UnInit” function to un-initialize the dynamic library.

CatchBEST Vision Technologies (Beijing) Co., Ltd. 4

Program operation of colour camera

The most simple capture operation

1． First initialize the dynamic library, call “KSJ_Init” function

KSJ_CaptureSetFieldOfView(0,0,0,1280,1024, KSJ_SKIPNONE, KSJ_SKIPNONE);

4． Int nWidth, nHeight;

Int nWidth, nHeight;

6． Allocate the memory according to nWidth,nHeight

Unsigned char *pData = (unsigned char*)malloc( nWidth * nHeight * 3 );

7． Capture 24 bit colour image by calling function “KSJ_CaptureRgbData (0,pData );”

9． Finally, call “KSJ_UnInit” function to un-initilized dynamic library

The most simple preview operation

First, initialize the dynamic library by calling function “KSJ_Init”.

CatchBEST Vision Technologies (Beijing) Co., Ltd. 5

KSJ_PreviewSetFieldOfView(0,0,0,1280,1024, KSJ_SKIPNONE, KSJ_SKIPNONE);

KSJ_PreviewGetSize( 0, &nWidth, &nHeight );

5． Call function “KSJ_PreviewStart ( 0,true );” to start the video stream.

8． Finally call “KSJ_UnInit” function to un-initialize the dynamic library.

CatchBEST Vision Technologies (Beijing) Co., Ltd. 6

External trigger capture programming

1. Operation in the preview callback function

static KSJ_SNAPBUTTONSTATUS PrvSnapButtonStatus = KSJ_UP;

CatchBEST Vision Technologies (Beijing) Co., Ltd. 7

2.1 Open one thread or timer

void CVideoChildFrame::OnTimer(UINT nIDEvent)

// Read the status of external button

// Press the button

// Allocate the capture memory space

// Captue the image

CatchBEST Vision Technologies (Beijing) Co., Ltd. 8

CatchBEST Vision Technologies (Beijing) Co., Ltd. 9

Programming of multiple cameras at

CatchBEST Vision Technologies (Beijing) Co., Ltd. 10

Camera recovery for the abnormal

CatchBEST Vision Technologies (Beijing) Co., Ltd. 11

Explanation on the Bayer mode

BestScope CatchBESTA/B/C-130C cameras’ the photosensitive array of image sensors is as following:

Figure 1. RGGB array

CatchBEST Vision Technologies (Beijing) Co., Ltd. 12

For CatchBESTA/B/C-130C cameras, the arrangement is “RGGB” format. For CatchBESTA/B/C-320C

Unsigned char pData = (unsigned char)malloc( nWidth * nHeight );

Unsigned char pData = (unsigned char)malloc( nWidth * nHeight * 3 );