SK91USB3-LX  1.2.0
Functions
Grabbing images

This pages details you how to grab lines or images. More...

Functions

int SK_GRAB (int CamID, unsigned char *pData, size_t lines, size_t timeout, bool noWait, int frameSync, int lineSyncMode)
 Grabbing a desired number of lines. More...
 
int SK_GRAB (int CamID, int bufferID, size_t timeout, bool noWait, int frameSync, int lineSyncMode)
 Grabs into given internal buffer. More...
 
int SK_WAITFORSCAN (int CamID, size_t timeout)
 Waits until grab is finished. More...
 
int SK_GRABCONTINUOUS (int CamID, size_t lines, size_t timeout, bool grabInUserBufferQueue, int numberOfBuffers, int frameSync, int lineSyncMode)
 Grabs continuously images into a ring buffer. More...
 
int SK_GETIMAGE (int CamID, unsigned char **pImage, size_t timeout)
 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...
 

Detailed Description

This pages details you how to grab lines or images.

Examples for grabbing

Grab an image with user 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
if (SK_INITCAMERA(m_CamID) != SK_RESULT_OK)
return false;
// set output data format to 8 bit grayscale or 3x8 bit color images
SK_SETBITDEPTH(CamID, 8);
// Allocate data memory for m_iLines
// m_iLines = 1 single line scan, else area scan
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);
// Grab an image with 2s timeout, wait until image is ready, no frame sync
int result = SK_GRAB(m_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 = nullptr;
}
SK_CLOSECAMERA(m_CamID);
// Release internal data structures

Grab an image with 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
m_CameraName = SK_GETCAMTYPE(CamID); // query camera name
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, else area scan
SK_ALLOC_LINES(m_CamID, m_iLines, 0);
// 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, 0, nullptr);
// 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);
// 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;
}
}
if (result == SK_RESULT_OK || result == SK_RESULT_IMAGE_COMPLETED)
{
// image processing
}
// Close the camera
if (m_pData)
{
delete [] m_pData;
m_pData = nullptr;
}
// 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;
// init image buffer for m_nrOfBuffer buffers
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 = nullptr;
// 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 != nullptr && 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 = nullptr;
}
SK_CLOSECAMERA(m_CamID);
// Release internal data structures

Continuous grabbing of frames 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 = nullptr;
// 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 != nullptr && 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 = nullptr;
}
SK_CLOSECAMERA(m_CamID);
// Release internal data structures

Function Documentation

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
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
bit depth, else see Error Code Table
int SK_GETIMAGE ( int  CamID,
unsigned char **  pImage,
size_t  timeout 
)

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
timeouttimeout in milliseconds
Returns
SK_RESULT_OPERATION_PENDING means camera is busy
SK_RESULT_IMAGE_COMPLETED means image is ready
else see Error Code Table
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
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
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
int SK_GRAB ( int  CamID,
unsigned char *  pData,
size_t  lines,
size_t  timeout,
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 activated, 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 with user 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
timeouttime 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
int SK_GRAB ( int  CamID,
int  bufferID,
size_t  timeout,
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 with 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
timeouttime 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
int SK_GRABCONTINUOUS ( int  CamID,
size_t  lines,
size_t  timeout,
bool  grabInUserBufferQueue,
int  numberOfBuffers,
int  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 frames 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
timeouttimeout 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
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
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
int SK_WAITFORSCAN ( int  CamID,
size_t  timeout 
)

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
timeouttimeout in milliseconds
Returns
SK_RESULT_OPERATION_PENDING means camera is busy
SK_RESULT_IMAGE_COMPLETED means image is ready
else see Error Code Table