SK91GigE-WIN  5.5.2
Functions
Grabbing

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

Functions

size_t SK_CALCNUMOFLINES (int CamID, size_t lines)
 Calculates the number of valid lines to avoid loss of lines when grabbing large images. The result of this function should be used as parameter 'lines' in the function SK_GRAB. More...
 
int SK_GRAB (int CamID, unsigned char *pData, size_t lines, size_t timeout, int 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, size_t timeout)
 Waits until grab is finished. More...
 
int SK_GRABCONTINUOUS (int CamID, size_t lines, size_t timeout, int 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 timeout, int grabInUserBufferQueue)
 Returns the pointer to currently filled buffer. More...
 
int SK_STOPGRABBING (int CamID)
 Stops image grabbing. More...
 
int SK_BREAKGRABBING (int CamID, unsigned char **pImageStart, unsigned char **pImageEnd, size_t *lines)
 Breaks image grabbing and returns the number of grabbed lines and pointer for the memory. More...
 
size_t 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...
 

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 devices
return false;
// Initialize the GigE Interface
// 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 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 devices
return false;
// Initialize the GigE Interface
// 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 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 devices
return false;
// Initialize the GigE Interface
// Init 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 devices
return false;
// Initialize the GigE Interface
// Init 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 devices
return false;
// Initialize the GigE Interface
// Init 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_BREAKGRABBING()

int SK_BREAKGRABBING ( int  CamID,
unsigned char **  pImageStart,
unsigned char **  pImageEnd,
size_t *  lines 
)

Breaks image grabbing and returns the number of grabbed lines and pointer for the memory.

See also
SK_GRAB
SK_GRABCONTINUOUS
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
pImageStartpointer to pointer of the buffer with last grabbed image (start address)
pImageEndpointer to pointer of the buffer with last grabbed image (end address)
linespointer to size_t for the number of grabbed lines
Returns
SK_RESULT_OK on success, else see Error Code Table

◆ SK_CALCNUMOFLINES()

size_t SK_CALCNUMOFLINES ( int  CamID,
size_t  lines 
)

Calculates the number of valid lines to avoid loss of lines when grabbing large images. The result of this function should be used as parameter 'lines' in the function SK_GRAB.

Calculation is based on following restrictions:

  1. max. 16.383 lines per internal buffer
  2. Frame size:
    1. 32 bit systems: max. 32 MB per internal buffer
    2. 64 bit systems: max. 80 MB per internal buffer
  3. lines per frame have to be a multiple of 8

If the image size is greater than one of the limits, the image will be splitted into multiple frames. The number and size of the frames are dynamically calculated in this function. Starting from the entire image size, the function increases the number of frame buffers until both (number of lines, number of bytes per frame) are within the limits. In addition, the number of lines per frame must be divisible by 8 and is rounded down to the nearest whole number.

Example:

Line scan camera SK8160GKO-LB 8160 pixel per line
image height 10000 lines
image size 77.82 MB (81600000 Bytes)

for 32 bit systems to big, split is necessary

internal number of frame buffers 4
lines per frame 2500
check for multiple of 8 2500 / 8 = 312.5 -> 312 * 8 = 2496 lines per frame
entire image 2496 lines * 4 buffers = 9984 lines
See also
SK_GRAB
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
linesnumber of lines to grab, minimum = 1, maximum = 65500
Returns
number of lines on success, else see Error Code Table

◆ 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  timeout,
int  grabInUserBufferQueue 
)

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
grabInUserBufferQueue1 = SK_SETUSERBUFFERQUEUE was called before
0 = internal memory management is used
Returns
SK_RESULT_OPERATION_PENDING means camera is busy
SK_RESULT_IMAGE_COMPLETED means image is ready
else see Error Code Table

◆ SK_GETIMAGEID()

size_t 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_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  timeout,
int  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
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

◆ 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,
size_t  lines,
size_t  timeout,
int  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.
lines have to be a multiple of 8, e.g. 256, 512, ...
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

◆ 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
16 2 x 8 bit, 1 byte per pixel, high speed transfer
24 3 x 8 bit, 3 bytes per pixel (RGB)
25 2 x 12 bit, 2 bytes per pixel, high speed transfer
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,
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