Compatibility

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:

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:

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:
    1. True latin-1 characters (ISO88591) work as before because the Unicode codes of these characters are the same as their latin-1-ANSI codes.
    2. 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.
    3. 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:

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.