A few tips, tricks and gotchas when it comes to using the Pixelink API.
Query A Feature's Capabilities and Limits
Before using a feature, query the camera to see if it supports the feature. This can be done by calling PxLGetCameraFeatures for the feature in question, and then examining the FEATURE_FLAG_PRESENCE bit. If this is set, the feature is supported.
Using PxLGetCameraFeatures, it is also possible to read the current valid range (limits) for the feature. Beware that some features have dynamic limits.
Be Mindful of Inter-dependent Features
Some features can be queried and set and will remain constant regardless of what happens with other features. For example, a camera's gain (FEATURE_GAIN) will not change unless you change it by calling PxLSetFeature or PxLLoadSettings, or reboot the camera. The camera's gain limits are fixed: the minimum gain will always be the same for your camera, as will the maximum.
However, some features are interdependent, meaning a change to one feature may affect one or more of the other features' values, limits, or flags (e.g. FEATURE_FLAG_OFF). For example, gamma and lookup table are interdependent (See the C/C++ sample app 'gamma'). Exposure, frame rate, ROI, pixel addressing, and triggering are interdependent. For example:
Changing the exposure may change the current frame rate.
Enabling fixed frame rate mode (for cameras that support this feature) may change the exposure limits, and/or exposure value.
When fixed frame rate mode is enabled (for cameras that support this feature), changing the ROI may change the exposure limits, and/or exposure value.
Changing the ROI may change the frame rate, as well as the frame rate limits.
So, when changing camera features, be aware that in some cases you have to order the way you set the features, and you may want to double-check at the end that things are the way you expect them to be.
As of Release 7.22 and later, you can query a feature using PxLGetCameraFeatures and examine the feature's FEATURE_FLAG_VOLATILE flag to see if the feature can be affected by changes to other features.
Summary
Changing One of these Features | May Cause a change to One or more of these Features |
FEATURE_EXPOSURE (aka FEATURE_SHUTTER) FEATURE_EXTENDED_SHUTTER FEATURE_FRAME_RATE | |
FEATURE_FRAME_RATE | |
FEATURE_EXPOSURE (aka FEATURE_SHUTTER) FEATURE_EXTENDED_SHUTTER |
Feature Limits
Part 1 - Integral Features
Although PxLSetFeature and PxLGetFeature use floats for their parameters, some feature parameters are actually integral. Furthermore, for some integral feature parameters, not all values between minimum and maximum are supported. For example, querying the min and max for feature FEATURE_PIXEL_ADDRESSING shows that the value parameter has limits of [1, 6], but that does not mean that the camera supports pixel addressing values 1, 2, 3, 4, 5, and 6. The only way to determine which values are actually supported is to test the value by setting it with PxLSetFeature and then examining the return code for success (using the API_SUCCESS macro). Don't forget that some features can only be changed when streaming is stopped. Beware of snappy features.
Part 2 - Snappy Features
Some features only support a set of values. Rather than report an error if the feature is set to an unsupported value, the camera will adjust ('snap') the value to a supported value. For example, gain is a 'snappy' feature. On a PL-B778, the gain will report limits of [0.00, 24.08]. If you set the gain to 1.0, PxLSetFeature will return a return code indicating success, but if you use PxLGetFeature to read the current gain, you'll see that it has been 'snapped' to 0.76, the nearest lower supported gain.
Snappy Features
FEATURE_COLOR_TEMP (aka FEATURE_WHITE_BAL)
Note: FEATURE_COLOR_TEMP is snappy only on some cameras.
Same, but Different
Feature support may not be exactly the same between PL-A and PL-B. For example, PL-B741 cameras support auto-exposure, but PL-A741 cameras do not.
Possible Name Confusion
Some features were named based on DCAM terminology, but those names don't match nicely with the names used in Capture OEM.
FEATURE_WHITE_BAL vs. FEATURE_WHITE_SHADING
DCAM FEATURE_WHITE_BAL is used to indicate the temperature of the light source, in degrees Kelvin, and appears in Capture OEM as "Color Temperature". To better reflect what is seen in Capture OEM, we have added a #define for FEATURE_WHITE_BAL called FEATURE_COLOR_TEMP.
DCAM FEATURE_WHITE_SHADING is used to control individual RGB colour gains. It appears in Capture OEM as "White Balance", and is used to perform an auto white balance. We have NOT created a #define called FEATURE_WHITE_BALANCE so that people will not confuse it with FEATURE_WHITE_BAL.
FEATURE_EXPOSURE vs FEATURE_SHUTTER
FEATURE_EXPOSURE is a DCAM feature meant to allow the user to enable some kind of mechanical auto-exposure. People using our API were confusing it with the exposure time. Capture OEM has Exposure on the basic tab, however, that exposure is actually controlling FEATURE_SHUTTER. To simplify things, we have changed FEATURE_EXPOSURE to have the same value as FEATURE_SHUTTER (and reserved the old FEATURE_EXPOSURE value).
Summary
As Seen in Capture OEM | FEATURE_to USE |
Exposure | FEATURE_EXPOSURE (or FEATURE_SHUTTER) |
White Balance | FEATURE_WHITE_SHADING |
Color Temperature (K) | FEATURE_COLOR_TEMP (or FEATURE_WHITE_BAL). |
API_SUCCESS
Test for success or failure by using the API_SUCCESS macro. In general, do not test against specific error codes. However...
PxLGetNextFrame Timeouts
It can be possible, under heavy traffic or CPU loads, when streaming images (non-triggered) for PxLGetNextFrame to return the error ApiCameraTimeoutError, in which case PxLGetNextFrame should be called again. The C/C++ demo app 'getnextframe' shows a recommended strategy.
Pixel Format and Bayer Pattern
For color cameras, the pixel format may also indicate the type of Bayer pattern used by the sensor. (This is not true for PIXEL_FORMAT_YUV422) For example, a PL-B952 will return a pixel format value of 7, i.e. PIXEL_FORMAT_BAYER8_RGGB, or PIXEL_FORMAT_BAYER16_RGGB.
However, when setting the pixel format you don't have to know the Bayer pattern, just use PIXEL_FORMAT_BAYER8 or PIXEL_FORMAT_BAYER16.
Free-Running Triggering
Free-Running Triggering is to be used to test triggering. If you need the camera to provide a continuous stream of images, disable triggering and just start the stream with PxLSetStreamState.
Thread Safety
If you keep in mind the following guidelines, the Pixelink API is suitable for use in a multithreaded, multicore environment.
Guideline 1) The thread that calls PxLInitialize must call PxLUninitialize.
Guideline 2) Multiple threads may call PxLGetNextFrame, but it is recommended that you use only one thread to call PxLGetNextFrame to simplify ordering. For example, if Thread A calls and blocks on PxLGetNextFrame, and then Thread B calls and blocks on PxLGetNextFrame, when a frame arrives, there is no guarantee that Thread A will be notified and return from PxLGetNextFrame rather than Thread B. i.e. there's no guarantee that threads blocked in PxLGetNextFrame will return from PxLGetNextFrame in the same order in which they called PxLGetNextFrame.
Reminder: You can unblock a thread blocked in PxLGetNextFrame by stopping streaming with PxLSetStreamState. See the sample application 'aborttrigger' for a demonstration.
Guideline 3) Be mindful of the thread calling a callback. See PxLSetCallback for more details.
Always, Always, Always Set the FRAME_DESC uSize
Before each and every time you call PxLGetNextFrame, you must set the uSize field of the FRAME_DESC to the size of the FRAME_DESC. The uSize field tells the API the version of the FRAME_DESC you are using. In some versions of the API, the uSize is overwritten to tell you the size of the FRAME_DESC it supports, hence the need to re-set the uSize before each and every call.