SK91USB3-WIN  5.5.0
Functions
Grabbing

Explanations and examples for grabbing of lines or images. More...

Functions

int SK_GRAB (int CamID, unsigned char *pData, size_t lines, size_t iTimeOutMs, BOOL NoWait, int FrameSync, int LineSyncMode)
 Grabbing a desired number of lines. More...
 
int SK_GRAB_BUFFER (int CamID, int bufferID, size_t iTimeOutMs, BOOL NoWait, int FrameSync, int LineSyncMode)
 Grabs into given internal buffer. More...
 
int SK_WAITFORSCAN (int CamID, unsigned int iTimeOutMs)
 Waits until grab is finished. More...
 
int SK_GRABCONTINUOUS (int CamID, int lines, size_t timeoutMS, bool grabInUserBufferQueue, int NumberOfBuffers, bool FrameSync, int LineSyncMode)
 Grabs continuously images into a ring buffer. More...
 
int SK_GETIMAGE (int CamID, unsigned char **pImage, size_t timeoutMS)
 Returns the pointer to currently filled buffer. More...
 
int SK_STOPGRABBING (int CamID)
 Stops image grabbing. More...
 
int SK_GETIMAGEID (int CamID)
 Returns an consecutively image ID number. More...
 
int SK_GETRESULT (int CamID)
 Returns the current result status. More...
 
int SK_SETBITDEPTH (int CamID, int bitDepth)
 Setting the output data format. More...
 
int SK_GETBITDEPTH (int CamID)
 Returns the bit depth of output data format. More...
 
size_t SK_GETLINES (int CamID)
 Returns the current number of lines for grabbing. More...
 
int SK_DATATRANSFERDIAGNOSIS (int CamID, int enable, LPCTSTR logFilename)
 The enabled diagnosis allows the checking of data streaming for lost lines or lost frames. More...
 
size_t SK_GETLOSTFRAMES (int CamID)
 Returns the number of lost frames, if SK_DATATRANSFERDIAGNOSIS is enabled. More...
 

Detailed Description

Explanations and examples for grabbing of lines or images.

Examples for grabbing

Grab an image into user managed buffer

// Init internal data structures and search for USB devices
return false;
// The number of connected cameras, their serial number, and their name are available now
m_CameraName = SK_GETCAMTYPE(CamID); // query camera name
m_SN = SK_GETSN(CamID); // query serial number
// Init USB Camera with CamID = 0
return false;
// set output data format to 8 bit grayscale or 3x8 bit color images
SK_SETBITDEPTH(CamID, 8);
// Allocate data memory size for m_iLines
// m_iLines = 1 single line scan, else area scan
m_imagesize = SK_GETBYTESPERLINE(CamID) * m_iLines;
// init image buffer
if (m_pData) delete m_pData;
m_pData = new unsigned char[m_imagesize];
memset(m_pData, 0, m_imagesize);
// Grab an image with 2s timeout, wait until image is ready, no frame sync
int result = SK_GRAB(CamID, m_pData, m_iLines, 2000, false, 0, SK_FREERUN);
if (result != SK_RESULT_OK)
{
// error
}
// image processing ...
// Close the camera
if (m_pData)
{
delete [] m_pData;
m_pData = NULL;
}
// Release internal data structures

Grab an image using internal buffer

// Init internal data structures and search for USB devices
return false;
// The number of connected cameras, their serial number, and their name are available now
// e.g.
CString m_CameraName = SK_GETCAMTYPE(CamID); // query camera name
int m_SN = SK_GETSN(CamID); // query serial number
// Init USB Camera with CamID = 0
if (SK_INITCAMERA(m_CamID) != SK_RESULT_OK)
return false;
// optional:
// using 8 bit grayscale or 3x8 bit color images
SK_SETBITDEPTH(m_CamID, 8);
// Set integration time if necessary, e.g. 0.2 ms
SK_SETINTEGRATIONTIME(m_CamID, (float)0.20);
// Allocate data memory for m_iLines
// m_iLines = 1 single line scan
// = 10000, a 2 dimensional image with 10000 lines
// m_bufferID= 0, buffer 0 is used
SK_ALLOC_LINES(m_CamID, m_iLines, m_bufferID);
// Grab an image with 2s timeout, wait until image is ready, no frame sync
int result = SK_GRAB(m_CamID, 0, 2000, false, 0, SK_FREERUN);
if (result != SK_RESULT_OK)
{
// error
}
// Get the image data
unsigned char * imageData = SK_GETBUFFER(m_CamID, m_bufferID, NULL);
// image processing ...
// Close the camera
SK_CLOSECAMERA(m_CamID);
// Release internal data structures

Asynchronous grabbing with user managed buffer

// Init internal data structures and search for USB devices
return false;
// Init USB Camera with CamID = 0
if (SK_INITCAMERA(m_CamID) != SK_RESULT_OK)
return false;
if (SK_GETBITDEPTH(m_CamID) == 12)
// here: using 8 bit grayscale or 3x8 bit color images
SK_SETBITDEPTH(m_CamID, 8);
// Allocate data memory for m_iLines
m_imagesize = SK_GETBYTESPERLINE(m_CamID) * m_iLines;
// init image buffer
if (m_pData) delete m_pData;
m_pData = new unsigned char[m_imagesize];
memset(m_pData, 0, m_imagesize);
// optional:
// Set integration time if necessary, e.g. 0.2 ms
SK_SETINTEGRATIONTIME(m_CamID, (float)0.20);
// Grab an image with 2s timeout, return immediately by noWait = true, frameSync is active
int result = SK_GRAB(m_CamID, m_pData, m_iLines, 2000, true, 1, SK_FREERUN);
if (result != SK_RESULT_OK)
{
// error
}
// do something, e.g. start scanner motor
// the camera waits for FRAME trigger to start
// Wait until scan has finished
while (result == SK_RESULT_OPERATION_PENDING)
{
result = SK_WAITFORSCAN(m_CamID, 1); // poll for image completed
// test for stop grabbing
if (WaitForSingleObject(m_eStopEvent, 0) == WAIT_OBJECT_0)
{
break;
}
}
{
// image processing
}
// Close the camera
if (m_pData)
{
delete [] m_pData;
m_pData = NULL;
}
// Close the camera
SK_CLOSECAMERA(m_CamID);
// Release internal data structures

Continuous grabbing of frames in a user managed buffer queue

// Init internal data structures and search for USB devices
return false;
// Init USB Camera with CamID = 0
if (SK_INITCAMERA(m_CamID) != SK_RESULT_OK)
return false;
if (SK_GETBITDEPTH(m_CamID) == 12)
// here: using 8 bit grayscale or 3x8 bit color images
SK_SETBITDEPTH(m_CamID, 8);
// Allocate data memory for m_iLines
m_imagesize = SK_GETBYTESPERLINE(m_CamID) * m_iLines;
// e.g., the queue contains 8 buffers
m_nrOfBuffer= 8;
if (m_pData) delete m_pData;
m_pData = new unsigned char[m_nrOfBuffer * m_imagesize];
memset(m_pData, 0, m_nrOfBuffer * m_imagesize);
// create buffer list, type of m_bufferList: std::vector<unsigned char *>
for(int i = 0; i < m_nrOfBuffer; i++)
m_bufferList.push_back(static_cast<unsigned char *>(m_pData + i * m_imageSize));
// create user managed buffer queue
SK_SETUSERBUFFERQUEUE(m_CamID, static_cast<void *>(&m_bufferList[0]), m_imageSize, m_nrOfBuffer);
// Set integration time if necessary, e.g. 0.2 ms
SK_SETINTEGRATIONTIME(m_CamID, (float)0.20);
// Continuous grab images with 5s timeout in user buffer queue
int result = return SK_GRABCONTINUOUS(m_CamID, m_iLines, 5000, true, 0, 0, SK_FREERUN);
if (result != SK_RESULT_OK)
{
// error
}
// get images until the m_eStopEvent is set
while (WaitForSingleObject(m_eStopEvent, 0) != WAIT_OBJECT_0)
{
unsigned char * imageData = NULL;
// wait 10ms for the next grabbed image in the buffer
result = SK_GETIMAGE(m_CamID, &imageData, 10);
// if imageData is not NULL and the result is IMAGE_COMPLETED, do some stuff
if (imageData != NULL && result == SK_RESULT_IMAGE_COMPLETED)
{
// do some image processing ...
}
}
// Stop the continuous grab
SK_STOPGRABBING(m_CamID);
// Close the camera
if (m_pData)
{
delete [] m_pData;
m_pData = NULL;
}
SK_CLOSECAMERA(m_CamID);
// Release internal data structures

Continuous grabbing of images with internal buffers

// Init internal data structures and search for USB devices
return false;
// Init USB Camera with CamID = 0
if (SK_INITCAMERA(m_CamID) != SK_RESULT_OK)
return false;
if (SK_GETBITDEPTH(m_CamID) == 12)
// here: using 8 bit grayscale or 3x8 bit color images
SK_SETBITDEPTH(m_CamID, 8);
// Allocate data memory for m_iLines
m_imagesize = SK_GETBYTESPERLINE(m_CamID) * m_iLines;
// init image buffer
if (m_pData) delete m_pData;
m_pData = new unsigned char[m_imagesize];
memset(m_pData, 0, m_imagesize);
// Set integration time if necessary, e.g. 0.2 ms
SK_SETINTEGRATIONTIME(m_CamID, (float)0.20);
// Continuous grab images with 5s timeout and 10 internal buffers
int result = SK_GRABCONTINUOUS(m_CamID, m_iLines, 5000, false, 10, 0, SK_FREERUN);
if (result != SK_RESULT_OK)
{
// error
}
// get images until the m_eStopEvent is set
while (WaitForSingleObject(m_eStopEvent, 0) != WAIT_OBJECT_0)
{
unsigned char * imageData = NULL;
// wait 10ms for the next grabbed image in the buffer
result = SK_GETIMAGE(m_CamID, &imageData, 10);
// if imageData is not NULL and the result is IMAGE_COMPLETED, do some stuff
if (imageData != NULL && result == SK_RESULT_IMAGE_COMPLETED)
{
// copy the image data into a local memory
memcpy_s(m_pData, m_imagesize, imageData, m_imagesize);
// do some image processing ...
}
}
// Stop the continuous grab
SK_STOPGRABBING(m_CamID);
// Close the camera
if (m_pData)
{
delete [] m_pData;
m_pData = NULL;
}
SK_CLOSECAMERA(m_CamID);
// Release internal data structures

Function Documentation

◆ SK_DATATRANSFERDIAGNOSIS()

int SK_DATATRANSFERDIAGNOSIS ( int  CamID,
int  enable,
LPCTSTR  logFilename 
)

The enabled diagnosis allows the checking of data streaming for lost lines or lost frames.

Note
In the camera output signal the first pixel of each line is replaced by a line counter. Depending on the programmed bit depth, the counter range is 0...255 at 8 bit, or 0...4095 at 12 bit. Within a frame a counter difference greater 1 signals a lost line. Between two consecutive frames, the counter in pixel 1 of the current frame must be the content of pixel 1 + linesPerFrame of the previous frame.
See also
SK_GETLOSTFRAMES
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
enable1 = enable, 0 = disable
logFilenamefile name for saving diagnosis report, NULL= no saving
Returns
status code

◆ SK_GETBITDEPTH()

int SK_GETBITDEPTH ( int  CamID)

Returns the bit depth of output data format.

Valid values are:

bit depth output format
1 thresholding mode, 2 byte per transition
2 thresholding mode with subpixel, 2 byte per transition, sensor > 8k: 4 byte per pixel
8 8 bit resolution, 1 byte per pixel
12

12 bit resolution, 2 bytes per pixel

Note
This function returns the resolution of Analog Digital Converter(s). At color line scan cameras the returned value must be multiplied with 3 to get the number of bits per color pixel.
See also
Thresholding
SK_SETBITDEPTH
SK_GETBITSPERPIXEL
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
bit depth, else see Error Code Table

◆ SK_GETIMAGE()

int SK_GETIMAGE ( int  CamID,
unsigned char **  pImage,
size_t  timeoutMS 
)

Returns the pointer to currently filled buffer.

This function gives access to actual frame from continuous image acquisition.

Remarks
After result SK_RESULT_IMAGE_COMPLETED the pointer to the last grabbed image is stored in pImage.
See also
SK_GRABCONTINUOUS
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
pImagepointer to pointer of the buffer with last grabbed image
timeoutMStimeout in milliseconds
Returns
SK_RESULT_OPERATION_PENDING means camera is busy
SK_RESULT_IMAGE_COMPLETED means image is ready
else see Error Code Table

◆ SK_GETIMAGEID()

int SK_GETIMAGEID ( int  CamID)

Returns an consecutively image ID number.

Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
incremental ID number of grabbed images, else see Error Code Table

◆ SK_GETLINES()

size_t SK_GETLINES ( int  CamID)

Returns the current number of lines for grabbing.

Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
number of lines, else see Error Code Table

◆ SK_GETLOSTFRAMES()

size_t SK_GETLOSTFRAMES ( int  CamID)

Returns the number of lost frames, if SK_DATATRANSFERDIAGNOSIS is enabled.

Note
The camera must grab frames continuously in a buffer queue.
Parameters
CamIDid of camera
Returns
number of lost frames

◆ SK_GETRESULT()

int SK_GETRESULT ( int  CamID)

Returns the current result status.

Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
status code, see Error Code Table

◆ SK_GRAB()

int SK_GRAB ( int  CamID,
unsigned char *  pData,
size_t  lines,
size_t  iTimeOutMs,
BOOL  NoWait,
int  FrameSync,
int  LineSyncMode 
)

Grabbing a desired number of lines.

This function starts grabbing images with the defined number of lines lines.
If the parameter noWait is TRUE, the function will be come back immediately. Use the function SK_WAITFORSCAN to check the completed image acquisition.

For an example how to grab images, see Grab an image into user managed buffer .

See also
SK_SETFRAMESYNC for explanation of the FrameSync trigger
SK_SETSYNCMODE for explanation of the line synchronization
SK_WAITFORSCAN
SK_STOPGRABBING
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
pDataDestination buffer to write grabbed image into
linesnumber of lines to grab, minimum = 1, maximum = 65500
iTimeOutMstime in milliseconds (ms) to wait before timeout error occurs
NoWaittrue = function returns immediately, useful for image acquistion
false = function blocks until image is ready
FrameSync-1 = no change,
1 = wait for FrameSync trigger,
0 = FrameSync trigger off
LineSyncMode-1 = no change,
0 = Free Run,
1 = Line Start,
4 = Exporsure Start,
5 = Exposure Control
Returns
SK_RESULT_OK on success, else see Error Code Table

◆ SK_GRAB_BUFFER()

int SK_GRAB_BUFFER ( int  CamID,
int  bufferID,
size_t  iTimeOutMs,
BOOL  NoWait,
int  FrameSync,
int  LineSyncMode 
)

Grabs into given internal buffer.

This function starts grabbing into the internal buffer with the ID bufferID. The size and number of lines is defined by the internal buffer.
If the parameter noWait is activated, the function SK_WAITFORSCAN must be called to get the lines / image or rather to wait for image completion.

For an example how to grab images with internal buffer, see Grab an image using internal buffer .

Note
The function SK_ALLOC_BUFFER or SK_ALLOC_LINES must be called before using this function. Otherwise there is no memory allocated.
See also
SK_SETFRAMESYNC for explanation of the FrameSync trigger
SK_SETSYNCMODE for explanation of the line synchronization
SK_WAITFORSCAN
SK_STOPGRABBING
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
bufferIDdestination buffer ID
iTimeOutMstime in milliseconds (ms) to wait before timeout error occurs
NoWaittrue = function returns immediately, useful for image acquistion
false = function blocks until image is ready
FrameSync-1 = no change,
1 = wait for FrameSync trigger,
0 = FrameSync trigger off
LineSyncMode-1 = no change,
0 = Free Run,
1 = Line Start,
4 = Exporsure Start,
5 = Exposure Control
Returns
SK_RESULT_OK on success, else see Error Code Table

◆ SK_GRABCONTINUOUS()

int SK_GRABCONTINUOUS ( int  CamID,
int  lines,
size_t  timeoutMS,
bool  grabInUserBufferQueue,
int  NumberOfBuffers,
bool  FrameSync,
int  LineSyncMode 
)

Grabs continuously images into a ring buffer.

This function starts continuous image grabbing of images with height of lines. A ring buffer with a size of numberOfBuffers will be written cyclical. The ring buffer can be managed internal or by the user. Acquired images can be accessed by SK_GETIMAGE.

For an example how to grab images with user ring buffer, see Continuous grabbing of frames in a user managed buffer queue .
For an example how to grab images with internal ring buffer, see Continuous grabbing of images with internal buffers .

Note
If grabInUserBufferQueue is true, the ring buffer must be previously generated by SK_SETUSERBUFFERQUEUE.
See also
SK_SETFRAMESYNC for explanation of the FrameSync trigger
SK_SETSYNCMODE for explanation of the line synchronization
SK_GETIMAGE
SK_STOPGRABBING
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
linesnumber of scan lines
timeoutMStimeout in milliseconds before timeout error occurs,
e.g. 24 h = 86400000
grabInUserBufferQueuetrue = user controlled buffer,
false = internal memory management
NumberOfBuffers0 = grabInUserBufferQueue == true,
otherwise number of buffers to create
FrameSync-1 = no change,
1 = wait for FrameSync trigger,
0 = FrameSync trigger off
LineSyncMode-1 = no change,
0 = Free Run,
1 = Line Start,
4 = Exporsure Start,
5 = Exposure Control
Returns
SK_RESULT_OK on success, else see Error Code Table

◆ SK_SETBITDEPTH()

int SK_SETBITDEPTH ( int  CamID,
int  bitDepth 
)

Setting the output data format.

This function sets the resolution of Analog Digital Converter and determines the output data format.

Valid values for bitDepth are:

bit depth output format
1 thresholding mode, 2 byte per transition
2 thresholding mode with subpixel, 2 byte per transition, sensor > 8k: 4 byte per pixel
8 8 bit resolution, 1 byte per pixel
12 12 bit resolution, 2 bytes per pixel
Note
The value range of the digitized signal is dependent of ADC resolution:
8 bit: 0 ... 255, occupies 1 byte per pixel
12 bit 0 ... 4095, occupies 2 bytes per pixel in the memory
The programmed bit depth is valid for all ADCs inside the camera. Color line scan cameras have one or two ADCs for each color (rgb).
See also
Thresholding
SK_GETBITDEPTH
SK_GETNROFCHANNELS
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
bitDepthbit depth
Returns
SK_RESULT_OK on success, else see Error Code Table

◆ SK_STOPGRABBING()

int SK_STOPGRABBING ( int  CamID)

Stops image grabbing.

See also
SK_GRAB
SK_GRABCONTINUOUS
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
SK_RESULT_OK on success, else see Error Code Table

◆ SK_WAITFORSCAN()

int SK_WAITFORSCAN ( int  CamID,
unsigned int  iTimeOutMs 
)

Waits until grab is finished.

If the parameter noWait of the function SK_GRAB is true, this function waits until a grab is finished or timeout error occurs. This is suitable for asynchronous grabbing, e.g. after starting a grab with immediately return from SK_GRAB, a scanner translation unit should be started. This function waits until the grab is ready.

See also
SK_GRAB
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
iTimeOutMstimeout in milliseconds
Returns
SK_RESULT_OPERATION_PENDING means camera is busy
SK_RESULT_IMAGE_COMPLETED means image is ready
else see Error Code Table