Compatibility

Licenses

HALCON 18.05 Progress requires a valid HALCON Progress license and does not run with licenses of HALCON 13 and earlier versions.

HDevelop

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.

HALCON Library

Compared to HALCON 17.12, many extensions have been introduced. Thus, the HALCON 18.05 Progress libraries are not binary compatible with HALCON 17.12 Progress or earlier versions.

However, HALCON 18.05 Progress is mostly source-code compatible to HALCON 17.12 Progress except for the changes listed below:

  • 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.
  • In some cases, find_surface_model_image crashed when using a model that was written with write_surface_model and read with read_surface_model. Since the data corruption already occurred during write_surface_model, all models created and written with prior versions of HALCON (including HALCON 13.0.1 and HALCON 17.12 Progress) must be re-created. To facilitate finding such incorrectly written models, the internal version number of surface models that were created with ‘train_3d_edges’ enabled has been increased. HALCON will now raise an error when attempting to read a corrupted surface model that was written with a previous version of HALCON.
  • 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.
  • set_data_code_2d_param now throws an exception if the min/max values for the following parameters are inconsistent: ‘symbol_rows_min/max’, ‘symbol_cols_min/max’, ‘symbol_size_min/max’, ‘module_size_min/max’, ‘module_width_min/max’, ‘module_aspect_min/max’, ‘module_gap_min/max’, and ‘version_min/max’.
  • When on an Asian system a pretrained OCR classifier from HALCON 17.12 or earlier 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’.

HALCON Applications

Please re-compile all C, C++, or .NET programs developed with HALCON 17.12 Progress.

The incompatibility with HALCON 17.12 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.05 Progress, HALCON 17.12 Progress and HALCON 13.0.x image acquisition interfaces are library compatible.
HALCON 18.05 Progress includes only standard image acquisition interfaces.

Digital I/O Interfaces

In general, HALCON 18.05 Progress, HALCON 17.12 Progress and HALCON 13.0.x image acquisition interfaces are library compatible.
HALCON 18.05 Progress includes only standard image acquisition interfaces. You can download additional interfaces from our webserver.

Extension Packages

Please re-generate your own extension packages developed with HALCON 17.12 Progress.

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.
  • 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’.
  • 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.