Licenses
HALCON 18.11.0.0 Progress requires a valid HALCON Progress license and does not run with licenses of HALCON 13 and earlier versions.
Furthermore, please note the following compatibility issues related to licenses:
- The operators get_error_text and get_extended_error_info no longer require a valid HALCON license.
HALCON Library
Compared to HALCON 18.05 Progress, many extensions have been introduced. Thus, the HALCON 18.11.0.0 Progress libraries are not binary compatible with HALCON 18.05 Progress or earlier versions. However, HALCON 18.11.0.0 Progess is mostly source-code compatible to HALCON 18.05 Progress except for the changes listed below:
- The operators calibrate_cameras, binocular_calibration, and the camera calibration in calibrate_hand_eye in rare cases might return slightly different optimized parameters and reprojection error.
- The operator classify_class_gmm returns different values fo the k-sigma probability ‘KSigmaProb’ for Gaussian Mixture Models with covariance type ‘spherical’ or ‘diag’. Since classify_image_class_gmm uses the k-sigma probability to reject pixels, the class regions returned by classify_image_class_gmm now might differ from those of previous HALCON versions.
- The operators create_scaled_shape_model, create_aniso_shape_model, determine_shape_model_params, create_planar_uncalib_deformable_model, create_planar_calib_deformable_model, create_local_deformable_model, and determine_deformable_model_params for ‘NumLevels’=’auto’ in rare cases might return a different number of pyramid levels when ‘ScaleMin’, ‘ScaleRMin’, or ‘ScaleCMin’ are set to a value < 0.7. In extremely rare cases, create_shape_model_3d might create a slightly different model.
- The speedup of deviation_image might lead to results that differ by a gray value of 1 from the results in previous HALCON versions.
- The results and the score of find_planar_calib_deformable_model, find_planar_uncalib_deformable_model, and find_local_deformable_model can vary slightly from previous results and scores.
- The results and the score of find_planar_calib_deformable_model and find_planar_uncalib_deformable_model with the metric ‘ignore_part_polarity’ can vary slightly from previous results and scores.
- The results and the score of find_planar_calib_deformable_model, find_planar_uncalib_deformable_model and find_local_deformable_model can vary slightly from previous results and scores. This does not only affect the SIMD implementations but also the C version.
- gen_circle_sector, gen_ellipse_sector, create_drawing_object_circle_sector, and create_drawing_object_ellipse_sector might return slightly different results.
- get_calib_data for ItemType set to ‘camera’ and DataName set to ‘params_deviations’ or ‘params_covariances’ sometimes returns different results.
- The operator get_data_code_2d_results now returns error 8831 (“Unknown parameter name”) if the candidate groups ‘symbology_ident’ and ‘structured_append’ are chosen for Micro QR Codes.
- The HALCON language interfaces do not support a signature with an integer variation for the parameter ‘Instance’ in the operators get_metrology_object_result and get_metrology_object_result_contour anymore. Instead, the signatures with HTuple or string variations of the parameter can be used.
- When using a text model of type ‘manual’, get_text_object erroneously returned the error 1301 (“Wrong value of control parameter 1”), when passing an unsupported string for the parameter ‘ResultName’. Now, the error 1302 (“Wrong value of control parameter 2”) is returned. The operator get_text_object also returned no error for text models of type ‘manual’, when multiple values for parameter ‘ResultName’ have been passed. Instead, only the first parameter value has been processed. Now, the error 1202 (“Wrong type of control parameter 2”) is returned.
- set_stereo_model_image_pairs and reconstruct_surface_stereo might return slightly different results, in rare cases also significantly different results. In order to obtain the old behavior, before calling set_stereo_model_image_pairs, please call set_stereo_model_param (StereoModelID, ‘rectif_method’, ‘geometric’).
- The following operators may produce different results for uint2 images when the SSE41 optimization is switched off by using set_system (‘sse41_enable’,’false’): find_local_deformable_model, find_planar_calib_deformable_model, find_planar_uncalib_deformable_model, find_ncc_model, find_ncc_models, find_aniso_shape_model, find_aniso_shape_models, find_scaled_shape_model, find_scaled_shape_models, find_shape_model, and find_shape_models.
- Programs that relied on the exact output of tuple_sem_type or tuple_sem_type_elem need to be adjusted for specific semantic types, as they have been renamed to be consistent with the semantic types used by other operators. In particular,
- ‘surface_result’ is now ‘surface_matching_result’,
- ‘surface_result_deformable’ is now ‘deformable_surface_matching_result’,
- ‘sheet_of_light’ is now ‘sheet_of_light_model’, and
- ‘dl_classifier_training_result’ is now ‘dl_classifier_train_result’.
- The barcode reader could result in different decoding results compared to prior HALCON versions.
- The procedures in the procedure library procedures/general/hand_eye.hdpl have been adapted to use the new container data type ‘dictionary’ instead of messages.
- The feature cache macros of the internal region structure where removed from the HMacro.h header file because user code should not access the feature cache directly.
HALCON Applications
Please re-compile all C, C++, or .NET programs developed with HALCON 18.05 Progress. The incompatibility with HALCON 18.05 Progress or earlier versions mainly concerns the binaries, with only few changes in the language interfaces. If you encounter problems during recompiling your programs, please check the detailed description of changes below.
Image Acquisition Interfaces
In general, HALCON 18.11.0.0 Progress, HALCON 18.05 Progress and HALCON 13.0.x image acquisition interfaces are library compatible.
HALCON 18.11.0.0 Progress includes only a subset of available image acquisition interfaces. Image acquisition interfaces that are included are: BitFlow, DirectFile, DirectShow, Ensenso-NxLib, File, GenICamTL, GigEVision2, LinX, MILLite, MultiCam, O3D3xx, pylon, SaperaLT, SICK-3DCamera, SiliconSoftware, uEye, USB3Vision, and Video4Linux2.
Digital I/O Interfaces
In general, HALCON 18.11.0.0 Progress, HALCON 18.05 Progress and HALCON 13.0.x digital I/O interfaces are library compatible.
HALCON 18.11.0.0 Progress includes only a subset of available digital I/O interfaces. Digital I/O interfaces that are included are: OPC_UA, and Hilscher-cifX.
Extension Packages
Please re-generate your own extension packages developed with HALCON 18.05 Progress.
Note also the following compatibility issues:
- German and English def-files, which are used to describe the behavior of user defined operators provided via a HALCON extension package, must be UTF-8 encoded from now on.
Further Compatibility Information
- To avoid potential problems with memory management, the HDevEngine/C++ operator SetHDevOperatorImpl no longer supports the automatic deletion of passed HDevOperatorImpl objects, and, as a consequence, no longer supports the parameter mem_set_intern. Instead, the application always has to free HDevOperatorImpl objects. HDevEngine/C++ applications, which use SetHDevOperatorImpl, must be adapted accordingly.
String Encoding
HALCON’s string encoding is now based on UTF-8. This may cause the following incompabilities:
- The HALCON/C interface assumes strings to be encoded in UTF-8. This must be taken into account when C applications pass strings with non-ASCII characters to HALCON via the HALCON/C interface. With SetHcInterfaceStringEncodingIsUtf8(false) at the beginning of the application, the HALCON/C interface can be switched to use the string encoding of the current locale.
- The HALCON/C++ interface assumes strings to be encoded in UTF-8. This must be taken into account when C++ applications pass strings with non-ASCII characters to HALCON via the HALCON/C++ interface. With HalconCpp::SetHcppInterfaceStringEncodingIsUtf8(false) at the beginning of the application, the HALCON/C++ interface can be switched to use the string encoding of the current locale.
- The operators tuple_split, tuple_str_bit_select, tuple_str_first_n, tuple_str_last_n, tuple_strchr, tuple_strlen, tuple_strrchr, tuple_strrstr, tuple_strstr and tuple_substr now operate on Unicode code points. If indices should reference raw bytes, use set_system(‘tsp_tuple_string_operator_mode’, ‘byte’) to switch these operators to byte mode.
- The behavior of the operators tuple_ord, tuple_ords, tuple_chr, and tuple_chrt has changed so that they may return different results compared to older HALCON versions:
- True latin-1 characters (ISO88591) work as before because the Unicode codes of these characters are the same as their latin-1-ANSI codes.
- Latin-1 extensions like Windows code page 1252 or latin-9 (ISO885915) contain characters with ANSI-codes which differ from their Unicode counterparts, e.g., the EURO sign (€) has different codes in Windows code page 1252, latin-9, and Unicode.
- Multi byte characters like Asian letters or any special character in UTF-8 couldn’t be processed with tuple_ord and tuple_chr until now. As a workaround it was possible to call tuple_ords and tuple_chrt for creating such a character from a number sequence or converting it into one (according to the current encoding). Such workarounds are no longer needed, but also no longer possible (with the default settings). Programs which used these operators with special characters which are not true latin-1 are very likely to need some modifications with the advantage that the new code is interchangeable between different locales and platforms.
- The data code readers assume the string encoding of the strings encoded in the symbol to be UTF-8 by default. If the string is encoded in the string encoding of the current locale, use set_data_code_2d_param(DataCode2DHandle, ‘string_encoding’, ‘locale’).
- HDevEngine/C++ assumes strings to be encoded in UTF-8. Non-ASCII strings in the local system encoding are no longer handled correctly since they are interpreted as UTF-8 by default. This can be changed by setting HalconCpp::SetHcppInterfaceStringEncodingIsUtf8(false).
- Applications that read text files with non-ASCII characters may need to be adapted if these files have not been encoded in UTF-8. Text files should therefore be provided in UTF-8 in the future. In addition, applications which use fread_char for reading files byte-wise and rely on the fact that this operator returns exactly one byte, must be adapted. Furthermore, the operator fread_line now returns on all systems, i.e., also on Linux and macOS X, the line ending ‘\n’ when the file was written under Windows with the line break sequence ‘\r\n’ (carriage return + line feed).
- When communicating via send_tuple, receive_tuple, send_data, and receive_data, non-ASCII characters might not be transfered correctly anymore. If the strings of the connection partner are encoded in the encoding of the current locale, the parameter ‘string_encoding’ of open_socket_accept and open_socket_connect should be set to ‘locale’.
- In the very unlikely case that an old lexicon file contains non-ASCII entries in the local-8-bit encoding that all could be misinterpreted as valid UTF-8 words, the lexicon would not represent the expected words. The favored way to solve the problem would be to transcode the lexicon file into UTF-8. If this is not possible because the file must be used by an old HALCON version as a workaround one could enter one entry in the native encoding that cannot be misinterpreted as UTF-8.
- When communicating via serialize_tuple or deserialize_tuple using a previous HALCON version, non-ASCII characters might not be transferred correctly anymore. In that case, you can set the parameter ‘write_halcon_files_encoding’ or ‘read_halcon_files_encoding’ of set_system to ‘locale’ to force HALCON to write or read its files with the current locale system encoding instead of UTF-8.
- Old programs that rely on the locale string encoding may need to be modified for returning the same results on HALCON 18.11.
- If the HDevelop command line option -convert was used to export HDevelop programs to C or C++ programs, until now string constants were encoded with the local-8-bit encoding. Now, the default to encode these strings is UTF-8. By the new option -encoding native this can be changed back to the old behavior.
Legacy or No Longer Supported Functionality
The following functionality may be discontinued in a future major release:
- Switching the string encoding of the HALCON library to the local-8-bit encoding of the current locale via set_system(‘filename_encoding’, ‘locale’) is declared to be legacy now.
See the reference manual entries of legacy operators for details on how to replace them.
Planned Discontinuation of the x86-win32 platform version for Windows
MVTec plans to discontinue the x86-win32 platform version for Windows. This might likely to be happening in the course of 2020. We recommend to start switching your applications to the x64-win64 platform version for Windows.