Licenses
HALCON 18.11.1.0 Steady licenses are not compatible with previous HALCON versions. Please contact your local distributor.
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 13.0.2, many extensions have been introduced. Thus, the HALCON 18.11.1.0 Steady libraries are not binary compatible with HALCON 13.0.2 or earlier versions. However, HALCON 18.11.1.0 Steady is mostly source-code compatible to HALCON 13.0.2 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.
- create_sheet_of_light_model, set_sheet_of_light_param, and get_sheet_of_light_param have been extended by checks which verify whether the wanted parameters match the set ‘calibration’ in SheetOfLightModelID. In case they now return the error 3790 (“Parameter does not match the set ‘calibration'”), please use set_sheet_of_light_param (SheetOfLightModelID, ‘calibration’, Calibration) to adapt the model accordingly.
- 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. More information.
- 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.
- For find_text, do_ocr_single_class_cnn, and do_ocr_multi_class_cnn the implementation of the CNN-based OCR classifier has been improved. This can lead to slightly different results in the achieved confidences.
- 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.
- serialize_texture_inspection_model threw the error 3801 (“Texture inspection model is not trained”) if an untrained or only partially trained texture inspection model was passed as input parameter. Now, serialize_texture_inspection_model can cope with untrained models and therefore no error is returned in these cases anymore.
- set_bar_code_param now throws an exception, if ‘element_size_min’ and ‘element_size_max’ are inconsistent.
- The parameter ‘meas_param_estimation’ of set_bar_code_param and get_bar_code_param has been removed. The default behavior has been improved to cover its use cases.
- The parameters
- ‘module_gap_col’,
- ‘module_gap_col_min’,
- ‘module_gap_col_max’,
- ‘module_gap_row’,
- ‘module_gap_row_min’, and
- ‘module_gap_row_max’of set_data_code_2d_param and get_data_code_2d_param have been removed. Use ‘module_gap_min’ instead of ‘module_gap_col_min’. Furthermore, use ‘module_gap_row_min’ and ‘module_gap_max’ instead of ‘module_col_max’ and ‘module_row_max’.
- 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’).
- set_stereo_model_param returned the error 1303 (“Wrong value of control parameter 3”), if GenParamName was set to ‘surface_tolerance’ and GenParamValue exceeded the value of ‘min_thickness’ stored in StereoModelID. set_stereo_model_param now returns the error 9544 (“The minimum thickness is smaller than the surface tolerance”).
- 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.
- Note that the following undocumented but public functions for setting callbacks were removed. Applications must now use the new callback functionality within set_system instead.
- HSetCallbackOCRClassMLP
- HSetCallbackClassMLP
- HSetCallbackOCRClassSVM
- HSetCallbackClassSVM
- HSetCallbackClassGMM
- HSetCallbackTriang3D
- HSetCallbackFeatSel
- HSetCallbackDistXLD
- HSetCallbackTrainTexture
- HSetCallbackCalibSOL
- HSetCallbackMultiView
- tuple_regexp_match, tuple_regexp_replace, tuple_regexp_select, and tuple_regexp_test now support empty matches. Regular expressions such as ‘.*’ or ‘^$’ now match on an empty string. To avoid empty matches, the regular expression has to be adapted, e.g., by using ‘.+’ instead of ‘.*’.
- 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’.
- When on an Asian system a pretrained OCR classifier from a previous HALCON version is used and the HALCON encoding is set to UTF-8, the names of the special characters €, £, and ¥ are no longer mapped to the code page 1252 codes. In this scenario the new pretrained classifier should be used and the class names should be compared to the expected real character name ‘€’, ‘£’, or ‘¥’ .
- The procedure plot_dl_classifier_training_progress now uses epochs instead of iterations. Therefore, you have to pass the parameters ‘Epochs’ and ‘NumEpochs’ instead of ‘Iterations’ and ‘NumTotalIterations’.
- 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 13.0.2. The incompatibility with HALCON 13.0.2 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.1.0 Steady, HALCON 13.0.2 and HALCON 13.0.x image acquisition interfaces are library compatible.
Please note also the following compatibility issues related to image acquisition interfaces:
- The MVTec GigE Vision Streaming Filter version 2.1.8.0 that is part of the Windows version of the new GigEVision2 interface is only compatible with revision 13.0.3 and higher of the old GigEVision interface. If both, GigEVision2 and GigEVision, interfaces should be used on the same PC you need to make sure to update to this GigEVision revision to ensure compatibility.
- Image acquisition and digital I/O interfaces listed in the reference documentation of open_framegrabber and open_io_device will return the error code H_ERR_COMPONENT_NOT_INSTALLED instead of H_ERR_DLOPEN when loading of the interfaces fails.
HALCON 18.11.1.0 Steady includes only a subset of available image acquisition interfaces. The following interfaces are no longer included in the installation, but can still be downloaded from our web server and installed manually: ABS, Andor, DahengCAM, Ginga++, heliCamC3, LPS36, LuCam, MatrixVisionAcquire, Opteon, PixeLINK, Sentech, ShapeDrive, SICK-ScanningRuler, Slink, TWAIN, and VRmUsbCam.
Digital I/O Interfaces
In general, HALCON 18.11.1.0 Steady, HALCON 13.0.2 and HALCON 13.0.x digital I/O interfaces are library compatible.
HALCON 18.11.1.0 Steady includes only a subset of available digital I/O interfaces. The following interfaces are no longer included in the installation, but can still be downloaded from our web server and installed manually: ADLINK-DAQPilot, ADLINK-EOS, Advantech, Contec, Interface, NIDAQmx, and OPC_Classic.
Extension Packages
Please re-generate your own extension packages developed with HALCON 13.0.2.
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
- Applications that store handles as numeric values (Hlong) do not work reliably with the new handle mechanism since these “raw” references are not tracked by reference counting and the handle may get destroyed while still in use. Setting the system parameter ‘legacy_handle_mode’ to ‘true’ keeps all handles alive until destroyed explicitly and also allows to pass handles as numeric input values to HALCON operators as in previous HALCON versions. Furthermore, there are API extensions due to the new type and some old API members no longer serve any function with the new handle mechanism. This introduces potential source code incompatibilities which can be prevented by compiling with the preprocessor define HCPP_LEGACY_HANDLE_API. Finally, the new reference mechanism cannot unambiguously represent all legacy ownership states. This concerns scenarios where an application managed multiple instances of OOP classes referencing the same handle (via copying or rewrapping of the handle, typically involving explicit ‘Detach’ and/or ‘InvalidateHandle’). In such cases legacy code may need to be adapted to the new mechanism.
- Due to the introduction of the new HTuple element type HHandle some casts that were allowed previously may become ambiguous. In particular, converting a handle from procedural code to a tool class as in new HShapeModel(tuple) now requires to disambiguate the desired constructor with tuple.H (when using new handles) or tuple.IP (when using legacy mode).
- By converting strings consequently into the current locale the behavior of the program may slightly change and unexpected errors may occur, when characters are used in an HDevelop script that are not supported by the current locale. For instance, when using Japanese file names on a Western system with Latin-1 encoding, the file names were scrambled strings but valid Latin-1 byte sequences. Now the Japanese characters in the file names are replaced by ‘?’ which cannot be used within a path. In addition, different Japanese strings can be re-encoded to the same Latin-1 strings when different Japanese characters are all replaced by ‘?’, this may raise errors when these names are used as class names for a classifier.
- Due to a change of the type of the Grayval parameter of the operator get_grayval, the HALCON/C interface does not provide the native type signature variant of this operator anymore, but only the tuple variant. Due to this change, the types of the passed parameters have to be changed to type HTuple and the function call has to be changed to T_get_grayval, respectively.
- The previous parameter ‘cmake_cpp’ for the command line option ‘-export_type’ has been renamed to ‘cmake’. To specify the target language, now the additional option ‘-language’ is available which accepts the values ‘cpp’ and ‘cs’.
- HalconDotNet.HMouseEventArgsWPF.Button is now nullable type, that means it can take null as value.
- 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.
- The protection format for HDevelop files has been changed to improve security. Files with the new protection cannot be used with unpatched HALCON versions published before May 2018. If you need to open these files with older HALCON versions, please update these versions using the patches available for download from our webserver https://www.mvtec.com/download/halcon/.
- By introducing the new handle type, the ownership of the handle resources passes from the user to HALCON. This might lead in conventional programming languages like C, C++ classes, or .NET to undefined behavior and crashes when HALCON handles were not held in HALCON data structures like tuples or handle classes, as HALCON will free the handle resources automatically when the last HALCON structure holding a handle reference is destroyed. For these cases, HALCON offers a legacy mode to transfer the ownership of handles to the user code, i.e., handles have to be cleared explicitly again in this mode. Note that HDevelop does not support the legacy mode. The mode can be switched via the ‘legacy_handle_mode’ parameter of the operator set_system. But the more proper code adaption in case of this problem is to use HALCON data types instead, like HTuple or the specific semantic handle classes. This allows to keep the ownership on behalf of HALCON and to profit of the new HALCON handle resource guarding. The legacy operators clear_all_* that clear all created handles of a specific semantic type are no longer functional and will be removed in future HALCON versions. C++ classes of former HALCON versions used a local reference counting mechanism to support a shallow copy constructor. This behavior is not fully representable by the new handle mechanism, but generally, code that did not use ‘Detach’ or ‘InvalidateHandle’ is not concerned. HALCON/C operators with long type signatures for handles run in legacy mode only. For proper use of these operators, please use the tuple type signature instead. HALCON/COM (legacy) only runs in legacy handle mode. HDevEngine applications that provide custom implementations for dev_* operators must take care when storing window handles to keep their ownership separate from the caller: Handles must be stored and returned as independent copies of HTuple or HHandle instances, not as references to existing instances or as numeric values like Hlong or IntPtr. HDevEngine/.NET applications that use stock implementations HDevFixedWindowImplementation and HDevMultiWindowImplementation are not affected. The signature of the drawing object callback type changed to Herror (stdcall *)(Hphandle,Hphandle,char*). Following error codes are inoperable and have been removed: H_ERR_SOL_INVALID_HANDLE, H_ERR_WFID, H_ERR_WSID, H_ERR_FGWH, H_ERR_IOWH, H_ERR_BC_INVALID_HANDLE, H_ERR_BAR_UNKNOWN, H_ERR_WSKEY, H_ERR_WSKEYH_ERR_WSKEY, H_ERR_INVALID_TEXT_RESULT_ID, H_ERR_METROLOGY_MODEL_INVALID. Minor API differences may prevent source code from compiling out of the box in exceptional cases. Please refer to the Programmer’s Guide and the new technical note “Technical Updates” to resolve occurring problems.
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:
- The following operators became legacy:The operators dev_open_tool and dev_close_tool can be used instead.
- 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.
Discontinuation of the HALCON/COM Language Interface
The HALCON/COM interface, including the possibility to develop with Delphi, is no longer available.
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.