Upgrade Notes

This topic lists noteworthy changes that might in rare cases cause compile-time or run-time issues when upgrading EnsensoSDK or uEye driver versions in an existing application.

Note

Enabling or using new EnsensoSDK functions might in some cases cause incompatibilities in older functions and might require you to make small changes to your existing code as well.

See this page for a list of known issues in the current version of the SDK.

Upgrade of EnsensoSDK

To Version

≥ 3.3.x

  • This version ships with version 2.9 of the IDS GigE Vision firmware. Any GigE Vision devices should be updated as suggested by NxView.

  • Functions that require a separate license (e.g. PartFinder) now require the presence of NxLibCmBridge64.dll (Windows) or libNxLibCmBridge64.so (Linux), which gets loaded dynamically. The installers automatically install the library in the system’s library directory. You don’t have to do anything if you use NxLib from there.

  • Due to a large number of internal changes and improvements the PartFinder command will yield different results compared to earlier versions. It is recommended to verify parametrization and results again when using PartFinder.

≥ 3.2.x

  • This version adds support for EEPROM on IDS GigE Vision cameras instead of saving it to a local file (requires at least firmware 2.4). For backwards compatibility, the camera will still use the local file if it exists. Remove it manually to switch to the EEPROM on the device. Note that the SDK only ships the new firmware 2.8 for the GV-5040ACP-M, which is used in S-series cameras. For other camera model this version still ships an older firmware version due to known problems with the new firmware versions.

  • This versions adds the new EEPROM calibration format 11/12. This format is only required for S-series cameras, the calibration of any other stereo camera can always be downgraded and saved in the previous format.

  • The IgnoreEnsensoPatternEncoding parameter for CollectPattern was removed, because the resulting undecoded patterns were not usable for position estimation. CollectPattern in projector mode now always performs a basic decoding of Ensenso patterns.

  • The AbsoluteBlackLevelOffset node in the camera parameters was removed, because it was not used and its value was always zero.

≥ 3.1.x

  • Handling of multi-exposure images in the correlation matcher has been improved to increase data coverage for extreme lighting situations. This can change the matching result with these settings (SDK-2139) [062688].

  • NxLibItem::as<char const*>() could return a dangling pointer in previous versions of the NxLib. To make it slightly safer, it now returns a pointer to which the C-API string usage restrictions apply. The method will be removed in the next major version. If you use it, you should replace it with NxLibItem::asString() or NxLibItem::as<std::string>().

  • The bugfix SDK-2351 for RenderPointMap changed the shadowing behaviour of the projection. Please verify that your application is not affected when using this command.

≥ 3.0.x

  • The new PatchMatch stereo matching method as been adopted as default method and therefore the default values for the following parameters have been changed: FlexView, stereo matching Method, UniquenessRatio, TargetBrightness, ShadowingThreshold.

  • In order to benefit from the unlimited measurement range of PatchMatch the new flag FullWidth has been introduced which always enforces rectified images to have maximal width, regardless of the width of the stereo matching AOI.

  • The RenderPointMap parameters Near and Far did not work correctly in previous releases. If these are in use in your application please verify that they still produce the intended result with the repaired behaviour.

≥ 2.3.860

  • Changed tree structure

  • Changed default values of FlexView, stereo matching Method , UniquenessRatio for N35, X36 and XR36 camera models.

  • Changed default value of PixelClock for N20, N30, N35 models.

  • Changed default value of TargetBrightness .

  • Reduced single-flash time limit on X-series to 120ms for faster recovery of hardware limiting circuit

≥ 2.3.691

  • The NxLibCommand now creates a temporary execution slot on construction. Code that directly accesses nodes below the Execute node will no longer work. You can use the new slot member method of the NxLibCommand class to get a reference to a command’s execution slot.

  • The NxLib headers now require C++11 by default. See this topic for information on the compatibility mode.

≥ 2.3.600

  • Calibration format has been upgraded to 9/10 to support an additional rotation offset in recalibration (see this topic for more information). Modifying the calibration of a camera with this version or newer will render a camera unusable in earlier SDK versions. The device then needs to be recalibrated with an earlier SDK if necessary.

  • Upgrading may result in slight changes in the active calibration data, because the new eeprom format will cast the values into 32 bit floating point values, which results in lower precision. The internal stored calibration on the camera’s eeprom however will not change. It only changes when the active calibration is stored via the command StoreCalibration.

≥ 2.3.31

  • Delayed pattern point refinement was removed and replaced with a new method that works without a camera calibration. Therefore the interface of the Refinement parameter for CollectPattern was changed and the parameter value “Delayed” will no longer work.

≥ 2.3.30

  • By default, CollectPattern now uses full resolution images in order to be able to detect small patterns in high resolution images. This can degrade performance. The old behavior can be restored with the Downsample parameter.

≥ 2.2.147

  • NxView now shows update notifications. To get information on available versions, it makes an HTTP request to http://update.ensenso.com. This request contains the content of the Version node as JSON. For more details on the request and the data that is sent, you can inspect the source code of NxView that is delivered with the SDK.

≥ 2.2.135

This is an important firmware update for X series cameras.

  • This update introduces stricter flash time limits for X series projection modules which will prevent damage to the projection electronics in certain operation modes. This is an important update for the projector firmware. It can cause your application to run slower when using software triggered operation or cause frames without projection pattern when using hardware trigger when triggering faster than the reduced flash limit. Please review the reduced flash time limits under the X Series Illumination topic and contact the technical support if you are unsure if this affects your application.

≥ 2.2

≥ 2.1

  • Removed the dependency on the Wibu CodeMeter runtime for NxLib on Linux.

  • The structure of the Debug node was changed which might lead to runtime errors when accessing nodes only present in versions 2.0 and earlier.

  • The text format of the debug messages returned by nxLibGetDebugMessages changed.

  • The MeasurementVolume node has been split into MeasurementVolume and ScaledMeasurementVolume nodes, which leads to slightly narrower volume outputs in the existing MeasurementVolume node.

  • The Calibrate command was changed. The Cameras parameter is now required and used to specify the type of the calibration that is performed.

  • The optimization goal of CalibrateHandEye was changed from reprojection error to euclidean distances of the pattern pose estimates. Therefore the output node ReprojectionError has been renamed to Residual. This will usually yield lower euclidean errors than the previous version and result in an overall better calibration result.

  • The output format of camera distortion coefficients has been changed from an array to named parameters. Writing the old array parameter is still supported, but the output is generated in the new format which is incompatible with older NxLib versions when transferring calibration data e.g. in json files.

  • The structure of the NxLib setting files changed. In particular, NxView will lose any cached settings after upgrading. If you want to recover these settings, you can copy them from the cache directory in the installation directory of the SDK and apply them in NxView.

≥ 2.0

  • The structure of the camera Status node was changed.

  • The structure of the Sensor node was changed for N10 cameras. It now contains separate nodes for the left and right sensor.

  • The structure of the Output node was changed to allow more flexible configurations.

  • The EthernetConfiguration command now requires the Configuration parameter.

  • The StoreCalibration command now requires the specification of either the Link or the Calibration parameter.

  • The NxLibRemote TCP protocol changed. It is therefore not possible to connect a version 1.x NxLibRemote to a version 2.x NxLib or vice versa. This also means that a version 2.x NxTreeEdit cannot connect to older versions of the NxLib.

≥ 1.9.153

  • Wibu CodeMeter runtime is needed for loading the NxLib library; the EnsensoSDK installer will automatically install a minimal version of the CodeMeter runtime.

  • Refinement parameter needs to be specified when using CollectPattern to collect patterns for camera calibration.

  • Restructured pattern buffer API:

≥ 1.9.0

  • Support for Debian 6 (Squeeze) and older has been dropped.

  • Support for Windows XP has been dropped.

  • Pipelining of stereo geometry: Scaling, Binning and AOI parameters are internally stored on the Rectified and DisparityMap binary nodes. This guarantees that multi threaded processing and parameter modifications always deliver correct depth data. Changes to Scaling, Binning and AOI parameters will only take effect when the affected processing steps have been repeated.

≥ 1.3.167

  • A bug fix in the communication interface between NxLib and NxLibRemote required us to make an incompatible change in the TCP protocol. You thus cannot establish TCP connections between NxLib versions ≥1.3.167 and NxLibRemote versions ≤1.3.166.

≥ 1.3.146

  • When using the Recalibrate parameter of EstimatePatternPose the eeprom format of the calibration data will be upgraded. The respective camera will then not be compatible anymore with SDK versions prior to 1.3.146.

≥ 1.3.0

  • NxLibItem class operator[] now returns const objects with immutable path. This will avoid accidentally setting the path instead of the item value on temporary objects. Trying to set the path on temporaries will now generate compile-time errors. You will encounter compile-time errors where the assignment with operator= changed the path of the left hand side temporary object.

Upgrade of uEye Driver

To Version

≥ 4.80

  • uEye driver 4.80 contains improved blacklevel parametrization of the image sensors. The saved exposure and blacklevel values might therefore need to be updated.

≥ 4.72

  • uEye driver 4.72 fixes communication issues on internal camera buses. This reduces the number of reported image transfer failures. The release also fixes an issue causing error UEyeApiError -1 when opening the camera the first time on certain system configurations.

≥ 4.70

  • Due to a change in GPIO parametrization in uEye Driver 4.70 N10 cameras will not work with EnsensoSDK versions 1.3.167 and below when running uEye drivers 4.70 and newer. Please upgrade to EnsensoSDK version 1.3.170 or higher to run N10 cameras on uEye driver releases 4.70 or newer.

≥ 4.62

  • uEye driver 4.62 fixes a bug which could cause the sensor FPGA to enter a bad state making a camera reboot necessary.

≥ 4.61

  • uEye Driver 4.61 fixed an important issue with black level parametrization on the GigE camera image sensors. This yields huge improvements in image brightness at the same exposure times. You should therefore check and revise exposure times if you have been using fixed exposure settings in your application.

Update Checks

In order to provide upgrade information to users a simple and fully open source update checking mechanism is integrated in the GUI application NxView only. The source code of NxView is installed alongside the EnsensoSDK. Note that no other binary except for the NxView GUI will contact external servers. NxView sends the content of the Version node to the server at update.ensenso.com, and the server answers with a json struct of available updates. The update server can keep track of the version requests and IP addresses in order to keep simple anonymous statistics about the distribution of installed versions across the EnsensoSDK user base.

Note

Please be aware that the update communication, firmware and calibration downloading functions in NxView are implemented over unencrypted HTTP connections in order to simplify the library dependencies of NxView and allow for easier self-compilation of NxView.

Disabling Update Checks

If you do not want NxView to perform the update checks due to privacy concerns or to prevent upgrade information popups at your customer site you can disable updates either from the NxView GUI (Help->Check for Updates)) or by creating/modifying the NxView configuration file directly. The NxView configuration file is located at <Installation directory>/settings/NxView/settings.json and should provide the node /Update/Prohibited with value true, e..g. {“Update”:{“Prohibited”:true}}.

Note

Note that disabling the update notifications in NxView will prevent the popup of notifications only, where as the /Update/Prohibited setting in the NxView configuration file will prevent update checking itself.