SK91USB3-LX  1.2.0
Functions
Exposure Control

Describes the way to control the camera exposure. More...

Functions

int SK_SETINTEGRATIONTIME (int CamID, double integrationTimeMs)
 Integration time control. More...
 
int SK_SETEXPOSURETIME (int CamID, double exposureTimeMs)
 Exposure time control. More...
 
int SK_SETINTEGRATIONTIME_GREEN (int CamID, double integrationTimeMs)
 Integration time control for green channel. More...
 
int SK_SETEXPOSURETIME_GREEN (int CamID, double exposureTimeMs)
 Exposure time control for green channel. More...
 
int SK_SETINTEGRATIONTIME_BLUE (int CamID, double integrationTimeMs)
 Integration time control for blue channel. More...
 
int SK_SETEXPOSURETIME_BLUE (int CamID, double exposureTimeMs)
 Exposure time control for blue channel. More...
 
int SK_SETLINEFREQUENCY (int CamID, float kHz)
 Line frequency control. More...
 
int SK_SETPIXELFREQUENCY (int CamID, int clockDivider)
 Pixel frequency setting. More...
 
int SK_DECOUPLINGLF (int CamID, bool enable)
 Decoupling of line frequency. More...
 
double SK_GETMINPIXELFREQUENCY (int CamID)
 Returns the camera specific lower pixel frequency. More...
 
double SK_GETMAXPIXELFREQUENCY (int CamID)
 Returns the camera specific highest pixel frequency. More...
 
double SK_GETPIXELFREQUENCY (int CamID)
 Query the current pixel frequency. More...
 
double SK_GETLINEFREQUENCY (int CamID)
 Query the current line frequency in kHz. More...
 
double SK_GETMINLINEFREQUENCY (int CamID)
 Returns the slowest line rate in kHz. More...
 
double SK_GETMAXLINEFREQUENCY (int CamID)
 Returns the maximum line rate in kHz. More...
 
double SK_GETINTEGRATIONTIME (int CamID)
 Query the current integration time in milliseconds. More...
 
double SK_GETEXPOSURETIME (int CamID)
 Query the current expsoure time in milliseconds. More...
 
double SK_GETINTEGRATIONTIME_GREEN (int CamID)
 Get the current integration time for green channel in milliseconds. More...
 
double SK_GETEXPOSURETIME_GREEN (int CamID)
 Get the current exposure time for green channel in milliseconds. More...
 
double SK_GETINTEGRATIONTIME_BLUE (int CamID)
 Get the current integration time for blue channel in milliseconds. More...
 
double SK_GETEXPOSURETIME_BLUE (int CamID)
 Get the current exposure time for blue channel in milliseconds. More...
 
double SK_GETMINEXPOSURETIME (int CamID)
 Returns the camera specific minmum of exposure time in milliseconds. More...
 
double SK_GETMAXEXPOSURETIME (int CamID)
 Returns the camera specific maximum of exposure time in milliseconds. More...
 
double SK_GETEXPOSURETIMEFROMCAMERA (int CamID)
 Returns the current exposure time in milliseconds by reading the result of serial command "I24". More...
 
double SK_GETMAXLINEFREQUENCYFROMCAMERA (int CamID)
 Returns the maximum line frequency in kHz by reading the result of serial command "I27". More...
 
int SK_GETDECOUPLINGLF (int CamID)
 Returns the status of line frequency decoupling. More...
 

Detailed Description

Describes the way to control the camera exposure.

Exposure Time And Integration Control

Exposure Time
The light sensitive elements of the photoelectric sensor accumulate the charge that is generated by the incident light. The duration of this The duration of this process is called exposure time. Because of accumulation of the charges it is called also integration time. This both terms refer to the same process, the API functions SK_SETEXPOSURETIME and SK_SETINTEGRATIONTIME are identical. The longer exposure time the higher the intensity of the line scan signal, assuming constant illumination conditions.

Every line scan camera has a specific minimum exposure period, which is a function of sensor length and pixel clock frequency. Thus, the minimum exposure period determines the maximum line frequency of that camera and this is declared in the data sheet of the particular camera type.

Integration Control
Integration Control is a specific feature of the most sensors. It works like a shutter by stopping pixel charge accumulation within an exposure period, thereby restricting the integration of the signal. The Integration Control function is useful at very strong light, such as laser light, direct sunlight, or flash, to avoid over exposure of the sensor.

Example:
Adjustment of exposure time with varying effects on line frequency Camera: SK2048U3PD, 60 MHz pixel clock frequency

  1. 0.036 [ms] → SK_SETEXPOSURETIME(CamID, 0.036): exposure time = 0.036 ms –> line frequency = 27.777 kHz (= maximum)
  2. 0.106 [ms] → SK_SETEXPOSURETIME(CamID, 0.106): exposure time = 0.106 ms –> line frequency = 9.433 kHz
  3. 0.021 [ms] → SK_SETEXPOSURETIME(CamID, 0.021): exposure time = 0.021 ms –> line frequency = 27.777 kHz

In example 3, the integration time is shorter than the minimum exposure period, and the camera performs in Integration Control mode automatically. The shorter integration time means that the signal intensity is reduced, but the line frequency remains at the maximum of 27.777 kHz.

Line Frequency
To acquire an image in correct aspect ratio, the scanning speed and the image acquisition process must be synchronized. This is most easily achieved by adjusting the transport speed to the line frequency of the camera. However, in practice, it is usually the transport speed and the image resolution that are constraining and these predefine the line frequency.

At constant transport speeds, such as when examining objects on a conveyer belt, a line scan camera can be allowed to operate in a free-running mode. Conversely, any velocity fluctuations or discordant movements require the coordinated triggering of the line camera over equally spaced increments. The most convenient solution is for the software control unit of the transport motor to be made responsible for coordinating the individual line scans also. This precise synchronization guarantees images with a reproducible resolution and correct aspect ratio (see the figure below). The line frequency $f_L$ can be calculated for a given object speed $v_0$ and field width $FOV$, sensor length $S$ and pixel width $w$ from

\[f_L = \frac{v_0 \cdot S}{w \cdot FOV}\]

USB_3_0_Kamera.png

Decoupling Line Frequency
This feature allows the decoupling of line frequency and exposure time. In normally the changing of exposure time causes a changing of line frequency. If the feature is activated, the camera holds the current line frequency constant. The expsoure time can be controlled in the range from the reciprocal value of the fixed line frequency down to the shortest possible exposure time.

This function is useful e.g. in untriggered image acquisition in Free Run mode, if the line frequency is synchronized with the scan velocity and must be constant, but the integration time has to be reduced because of too much light.

Example for the SK2048U3PD:

// Set line frequency fixed to 10 kHz (correspond to 100ms exposure time)
//Enable the decoupling of line frequency and exposure time
SK_DECOUPLINGLF(0, true);
// Set exposure time to 50 milliseconds, line frequency stays at 10 kHz, everything is ok
// Set exposure time to 110 milliseconds, will not be accepted by the camera
// Disable coupling of line frequency and exposure time
SK_DECOUPLINGLF(0, false);

Pixel Frequency

The pixel frequency is the clock rate at which the freed charges are read out of the sensor. The maximum pixel frequency is a individual characteristic of each sensor. Cameras from Schaefter+Kirchhoff are able to work with maximum or the half of maximum pixel frequency.
Together with the sensor length, the pixel clock determines the exposure period and the maximum line frequency. The higher the pixel frequency, the higher the camera speed. But, also the power consumption of the camera is higher. If a camera should be connected at a USB 2.0 port, it can be needed to select a lower pixel frequency.

Function Documentation

int SK_DECOUPLINGLF ( int  CamID,
bool  enable 
)

Decoupling of line frequency.

If the line frequency is decoupled, it is possible to adjust the integration time in a range of reciprocal of this line frequency to SK_GETMINEXPOSURETIME, wherein the line frequency is unchanged.

Remarks
This function is useful e.g. in untriggered acquisition (Free Run), if the line frequency is synchronized with the scan velocity and the integration time must be reduced.
See also
SK_GETDECOUPLINGLF
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
enabletrue = enable line frequency decoupling,
false = disable line frequency decoupling
Returns
SK_RESULT_OK on success, else see Error Code Table
int SK_GETDECOUPLINGLF ( int  CamID)

Returns the status of line frequency decoupling.

See also
SK_DECOUPLINGLF
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
0 = line frequency decoupling not active
1 = line frequency decoupling active
else see Error Code Table
double SK_GETEXPOSURETIME ( int  CamID)

Query the current expsoure time in milliseconds.

Note
In normally the exposure time is the reciprocal of line frequency. Cameras with Integration Control feature can work with shorter exposure time than the reciprocal of SK_GETMAXLINEFREQUENCY. The Integration Control feature can be helpful at extensive light to avoid over exposure of the sensor.
See also
SK_GETEXPOSURETIME_GREEN
SK_GETEXPOSURETIME_BLUE
SK_SETEXPOSURETIME
SK_SETEXPOSURETIME_GREEN
SK_SETEXPOSURETIME_BLUE
SK_GETEXPOSURETIMEFROMCAMERA
SK_GETMAXEXPOSURETIME
SK_GETMINEXPOSURETIME
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
expsoure time in milliseconds, else see Error Code Table
double SK_GETEXPOSURETIME_BLUE ( int  CamID)

Get the current exposure time for blue channel in milliseconds.

Note
In normally the exposure time is the reciprocal of line frequency. Cameras with Integration Control feature can work with shorter exposure time than the reciprocal of SK_GETMAXLINEFREQUENCY. The Integration Control feature can be helpful at extensive light to avoid over exposure of the sensor.
This function is available only for color line scan cameras. If decoupling of line frequency is enabled, the query returns the current exposure time of blue channel.
Since
version 1.1.0 and camera revision 1.22 / 2.22
See also
SK_GETEXPOSURETIME
SK_GETEXPOSURETIME_GREEN
SK_SETEXPOSURETIME
SK_SETEXPOSURETIME_GREEN
SK_SETEXPOSURETIME_BLUE
SK_GETEXPOSURETIMEFROMCAMERA
SK_GETMAXEXPOSURETIME
SK_GETMINEXPOSURETIME
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
exposure time for blue channel in milliseconds, else see Error Code Table
double SK_GETEXPOSURETIME_GREEN ( int  CamID)

Get the current exposure time for green channel in milliseconds.

Note
In normally the exposure time is the reciprocal of line frequency. Cameras with Integration Control feature can work with shorter exposure time than the reciprocal of SK_GETMAXLINEFREQUENCY. The Integration Control feature can be helpful at extensive light to avoid over exposure of the sensor.
This function is available only for color line scan cameras. If decoupling of line frequency is enabled, the query returns the current exposure time of green channel.
Since
version 1.1.0 and camera revision 1.22 / 2.22
See also
SK_GETEXPOSURETIME
SK_GETEXPOSURETIME_BLUE
SK_SETEXPOSURETIME
SK_SETEXPOSURETIME_GREEN
SK_SETEXPOSURETIME_BLUE
SK_GETEXPOSURETIMEFROMCAMERA
SK_GETMAXEXPOSURETIME
SK_GETMINEXPOSURETIME
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
exposure time for green channel in milliseconds, else see Error Code Table
double SK_GETEXPOSURETIMEFROMCAMERA ( int  CamID)

Returns the current exposure time in milliseconds by reading the result of serial command "I24".

See also
SK_GETEXPOSURETIME
SK_GETEXPOSURETIME_GREEN
SK_GETEXPOSURETIME_BLUE
SK_SETEXPOSURETIME
SK_SETEXPOSURETIME_GREEN
SK_SETEXPOSURETIME_BLUE
SK_GETMAXEXPOSURETIME
SK_GETMINEXPOSURETIME
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
current exposure time in milliseconds, else see Error Code Table
double SK_GETINTEGRATIONTIME ( int  CamID)

Query the current integration time in milliseconds.

Deprecated:
see SK_GETEXPOSURETIME
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
integration time in milliseconds, else see Error Code Table
double SK_GETINTEGRATIONTIME_BLUE ( int  CamID)

Get the current integration time for blue channel in milliseconds.

Deprecated:
see SK_GETEXPOSURETIME_BLUE
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
integration time in milliseconds for blue channel, else see Error Code Table
double SK_GETINTEGRATIONTIME_GREEN ( int  CamID)

Get the current integration time for green channel in milliseconds.

Deprecated:
see SK_GETEXPOSURETIME_GREEN
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
integration time in milliseconds for green channel, else see Error Code Table
double SK_GETLINEFREQUENCY ( int  CamID)

Query the current line frequency in kHz.

Remarks
Range of line frequency is defined by SK_GETMAXLINEFREQUENCY and SK_GETMINLINEFREQUENCY
See also
SK_SETLINEFREQUENCY
SK_GETMINLINEFREQUENCY
SK_GETMAXLINEFREQUENCY
SK_GETMAXLINEFREQUENCYFROMCAMERA
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
current line frequency in kHz, else see Error Code Table
double SK_GETMAXEXPOSURETIME ( int  CamID)

Returns the camera specific maximum of exposure time in milliseconds.

See also
SK_GETEXPOSURETIME
SK_GETEXPOSURETIME_GREEN
SK_GETEXPOSURETIME_BLUE
SK_SETEXPOSURETIME
SK_SETEXPOSURETIME_GREEN
SK_SETEXPOSURETIME_BLUE
SK_GETEXPOSURETIMEFROMCAMERA
SK_GETMINEXPOSURETIME
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
longest exposure time in milliseconds, else see Error Code Table
double SK_GETMAXLINEFREQUENCY ( int  CamID)

Returns the maximum line rate in kHz.

See also
SK_SETLINEFREQUENCY
SK_GETLINEFREQUENCY
SK_GETMINLINEFREQUENCY
SK_GETMAXLINEFREQUENCYFROMCAMERA
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
highest line frequency in kHz, else see Error Code Table
double SK_GETMAXLINEFREQUENCYFROMCAMERA ( int  CamID)

Returns the maximum line frequency in kHz by reading the result of serial command "I27".

See also
SK_SETLINEFREQUENCY
SK_GETLINEFREQUENCY
SK_GETMINLINEFREQUENCY
SK_GETMAXLINEFREQUENCY
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
maximum line frequency in kHz, else see Error Code Table
double SK_GETMAXPIXELFREQUENCY ( int  CamID)

Returns the camera specific highest pixel frequency.

See also
SK_GETMINPIXELFREQUENCY
SK_SETPIXELFREQUENCY
SK_GETPIXELFREQUENCY
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
highest pixel frequency in MHz, else see Error Code Table
double SK_GETMINEXPOSURETIME ( int  CamID)

Returns the camera specific minmum of exposure time in milliseconds.

Note
The query returns the absolute shortest exposure time. It can be only few micro seconds, if the camera has the Integration Control feature. If not, the return is the reciprocal of maximum line frequency.
See also
SK_GETEXPOSURETIME
SK_GETEXPOSURETIME_GREEN
SK_GETEXPOSURETIME_BLUE
SK_SETEXPOSURETIME
SK_SETEXPOSURETIME_GREEN
SK_SETEXPOSURETIME_BLUE
SK_GETEXPOSURETIMEFROMCAMERA
SK_GETMAXEXPOSURETIME
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
shortest exposure time in milliseconds, else see Error Code Table
double SK_GETMINLINEFREQUENCY ( int  CamID)

Returns the slowest line rate in kHz.

See also
SK_SETLINEFREQUENCY
SK_GETLINEFREQUENCY
SK_GETMAXLINEFREQUENCY
SK_GETMAXLINEFREQUENCYFROMCAMERA
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
slowest line frequency in kHz, else see Error Code Table
double SK_GETMINPIXELFREQUENCY ( int  CamID)

Returns the camera specific lower pixel frequency.

See also
SK_GETMAXPIXELFREQUENCY
SK_SETPIXELFREQUENCY
SK_GETPIXELFREQUENCY
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
low pixel frequency in MHz, else see Error Code Table
double SK_GETPIXELFREQUENCY ( int  CamID)

Query the current pixel frequency.

See also
SK_GETMAXPIXELFREQUENCY
SK_GETMINPIXELFREQUENCY
SK_SETPIXELFREQUENCY
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
Returns
current pixel frequency in MHz, else see Error Code Table
int SK_SETEXPOSURETIME ( int  CamID,
double  exposureTimeMs 
)

Exposure time control.

This function sets the expsosure time in milliseconds (ms).

In normally the integration time is the reciprocal of line frequency. Cameras with Integration Control feature can work with shorter integration time than the reciprocal of maximum line frequency. The Integration Control feature can be helpful at extensive light to avoid over exposure of the sensor.

See also
SK_GETEXPOSURETIME
SK_GETEXPOSURETIME_GREEN
SK_GETEXPOSURETIME_BLUE
SK_SETEXPOSURETIME_GREEN
SK_SETEXPOSURETIME_BLUE
SK_GETEXPOSURETIMEFROMCAMERA
SK_GETMAXEXPOSURETIME
SK_GETMINEXPOSURETIME
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
exposureTimeMsexposure time in milliseconds [ms]
Returns
SK_RESULT_OK on success, else see Error Code Table
int SK_SETEXPOSURETIME_BLUE ( int  CamID,
double  exposureTimeMs 
)

Exposure time control for blue channel.

Sets the exposure time for blue channel in milliseconds

Note
In normally the exposure time is the reciprocal of line frequency. Cameras with Integration Control feature can work with shorter exposure time than the reciprocal of SK_GETMAXLINEFREQUENCY. The Integration Control feature can be helpful at extensive light to avoid over exposure of the sensor.
This function is available only for color line scan cameras and if decoupling of line frequency is enabled.
Since
version 1.1.0 and camera revision 1.22 / 2.22
See also
SK_GETEXPOSURETIME
SK_GETEXPOSURETIME_GREEN
SK_GETEXPOSURETIME_BLUE
SK_SETEXPOSURETIME
SK_SETEXPOSURETIME_GREEN
SK_GETEXPOSURETIMEFROMCAMERA
SK_GETMAXEXPOSURETIME
SK_GETMINEXPOSURETIME
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
exposureTimeMsexposure time for blue channel in milliseconds [ms]
Returns
SK_RESULT_OK on success, else see Error Code Table
int SK_SETEXPOSURETIME_GREEN ( int  CamID,
double  exposureTimeMs 
)

Exposure time control for green channel.

Note
In normally the exposure time is the reciprocal of line frequency. Cameras with Integration Control feature can work with shorter exposure time than the reciprocal of SK_GETMAXLINEFREQUENCY. The Integration Control feature can be helpful at extensive light to avoid over exposure of the sensor.
This function is available only for color line scan cameras and if decoupling of line frequency is enabled.
Since
version 1.1.0 and camera revision 1.22 / 2.22
See also
SK_GETEXPOSURETIME
SK_GETEXPOSURETIME_GREEN
SK_GETEXPOSURETIME_BLUE
SK_SETEXPOSURETIME
SK_SETEXPOSURETIME_BLUE
SK_GETEXPOSURETIMEFROMCAMERA
SK_GETMAXEXPOSURETIME
SK_GETMINEXPOSURETIME
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
exposureTimeMsexposure time for green channel in milliseconds [ms]
Returns
SK_RESULT_OK on success, else see Error Code Table
int SK_SETINTEGRATIONTIME ( int  CamID,
double  integrationTimeMs 
)

Integration time control.

Deprecated:
See SK_SETEXPOSURETIME
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
integrationTimeMsintegration time in milliseconds [ms]
Returns
SK_RESULT_OK on success, else see Error Code Table
int SK_SETINTEGRATIONTIME_BLUE ( int  CamID,
double  integrationTimeMs 
)

Integration time control for blue channel.

Deprecated:
See SK_SETEXPOSURETIME_BLUE
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
integrationTimeMsintegration time for blue channel in milliseconds [ms]
Returns
SK_RESULT_OK on success, else see Error Code Table
int SK_SETINTEGRATIONTIME_GREEN ( int  CamID,
double  integrationTimeMs 
)

Integration time control for green channel.

Sets the integration time for green channel in milliseconds

Note
This function is available only for color line scan cameras and if decoupling of line frequency is enabled.
Since
camera revision 1.22 / 2.22
Deprecated:
See SK_SETEXPOSURETIME_GREEN
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
integrationTimeMsintegration time for green channel in milliseconds [ms]
Returns
SK_RESULT_OK on success, else see Error Code Table
int SK_SETLINEFREQUENCY ( int  CamID,
float  kHz 
)

Line frequency control.

This function sets desired line frequency (in [kHz]).

The range of programable line frequency is defined by SK_GETMAXLINEFREQUENCY and SK_GETMINLINEFREQUENCY.

See also
SK_GETLINEFREQUENCY
SK_GETMINLINEFREQUENCY
SK_GETMAXLINEFREQUENCY
SK_GETMAXLINEFREQUENCYFROMCAMERA
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
kHzline frequency in kHz, limit is specified by the camera type
Returns
SK_RESULT_OK on success, else see Error Code Table
int SK_SETPIXELFREQUENCY ( int  CamID,
int  clockDivider 
)

Pixel frequency setting.

This function sets the pixel frequency of the camera via a clock divider.

See also
SK_GETMAXPIXELFREQUENCY
SK_GETMINPIXELFREQUENCY
SK_GETPIXELFREQUENCY
Parameters
CamIDid of camera from 0 ... n - 1, 0 = 1st camera
clockDivider0 = maximum pixel clock rate (return of serial command 'I5'),
1 = lower pixel frequency (return of serial command 'I4')
Returns
SK_RESULT_OK on success, else see Error Code Table