Release Notes for HALCON 18.05 Progress
This document provides the release notes for MVTec HALCON 18.05 Progress, as released in May 2018.
Addendum to the Release Notes of HALCON 18.05.0.1 Progress
The released version of HALCON 18.05.0.1 Progress had a few issues. Therefore, the version HALCON 18.05.0.1 Progress was substituted by an updated version HALCON 18.05.0.2 Progress.
To find out which version is currently installed, please open the dialog "Help->About" in HDevelop. The fixed version of the HALCON library is indicated by: "HALCON version: 18.05.0.2 (11.07.2018)". The file version of the HALCON library can also be checked with the following operator call: get_system('file_version',FileVersion), or, under Windows, by inspecting the file properties of the files halcon.dll and halconxl.dll.
In particular, the following problems have been fixed:
- Creating an HDevProcedure instance from a local procedure in an HDevProgram did not work when that local procedure referenced other local procedures. This problem has been fixed.
- The OCR Training File Browser displayed sample names with non-ASCII characters incorrectly. This problem has been fixed. In addition, the encoding of the sample names is automatically detected (for training files that have been written with HALCON earlier than 18.05). If all sample names are valid UTF-8 characters the file is assumed to be encoded in UTF-8, otherwise local-8-bit encodig is used.
- The results of the OCR Assistant could appear corrupted in the Graphics Window. In addition, when setting the system parameter 'filename_encoding' to 'utf8', character names were not displayed correctly in the OCR Assistant. These problems have been fixed.
- Opening an I/O device leaked a small amount of memory. This problem has been fixed.
- HALCON did not unload an I/O interface after the last device using it is closed. This problem has been fixed.
- Opening and closing multiple framegrabbers using the same image acquisition interface could lead to crashes. This problem has been fixed.
Addendum to the Release Notes of HALCON 18.05 Progress
The originally released version of HALCON 18.05 Progress had a few issues:
- get_io_channel_param always returned an empty tuple for the parameter GenParamValue for any digital I/O interface.
- HDevelop's library project export generated one superfluous and corruptive semicolon which prevented the exported code from compiling.
- HDevelop's auto completion did not work as expected, i.e., the auto completion withheld some parameters or suggested incorrect parameters.
Therefore, the original version HALCON 18.05 Progress was substituted by an updated version HALCON 18.05.0.1 Progress.
To find out which version is currently installed, please open the dialog "Help->About" in HDevelop. The fixed version of the HALCON library is indicated by: "HALCON version: 18.05.0.1 (08.06.2018)". The file version of the HALCON library can also be checked with the following operator call: get_system('file_version',FileVersion), or, under Windows, by inspecting the file properties of the files halcon.dll and halconxl.dll.
Contents
- Major New Features of HALCON 18.05 Progress
- Compatibility
- Supported Operating Systems
- Detailed Description of Changes in HALCON 18.05 Progress
- Release Notes of Previous HALCON Versions
Major New Features of HALCON 18.05 Progress
CPU Inference for Deep Learning
With HALCON 18.05, you are able to perform the deep learning inference, i.e., applying your trained Convolutional Neural Network (CNN) to new data, on a CPU.This CPU inference has been highly optimized for Intel® compatible x86 processors. As a result, a standard Intel CPU can reach inference execution times comparable to a mid-range graphics processor (GPU).
Removing the need for a dedicated GPU greatly increases the operational flexibility. E.g., industrial PCs that are usually not designed for housing large and powerful GPUs can now easily be used for deep-learning-powered classification.
Variable Input Image Size for Deep Learning Classifier
You can now adjust the input image size of your deep learning classifier. This can help to improve classification results by preserving relatively small relevant information, e.g., a very small defect in a large image. If smaller images are sufficient for the given purpose, reducing the input image size can speed up the classification.Enhanced Deflectometry
The deflectometry functionality introduced in HALCON 17.12 now includes a new pattern type that improves the precision and robustness of error detection especially on partially specular surfaces like varnished metal sheets.Improved Bar Code Reader
HALCON 18.05 features optimized edge detection, which improves the ability to reliably read bar codes with very small line widths as well as strongly blurred codes. Moreover, the quality of the bar codes is also verified in accordance with the most recent version of the ISO/IEC 15416 standard.HDevEngine Improvements
The HDevelop library export feature has been expanded: Developers can now access HDevelop procedures not just in C++, but also in .NET via an exported wrapper – as easily and intuitively as a native function. This significantly facilitates the development process.Automatic Handle Clearing
HALCON 18.05 makes it much more comfortable to work with handles by clearing these automatically once they are no longer required. This significantly reduces the risk of creating memory leaks because you no longer have to manually release unused memory. This way, writing “safe code” is now much simpler.3D Improvements
HALCON 18.05 offers optimized functions for surface-based 3D matching: These can be used to determine the position of objects in 3D space more reliably, making development of 3D applications easier. In addition, HALCON now also includes a new helper procedure that allows developers to quickly inspect and debug parameters and results of a surface-based matching application.Support for Hypercentric Lenses
A new camera model within HALCON now allows the corrections of distortions in images that were recorded with hypercentric (also known as pericentric) camera lenses. These lenses can depict several sides of an object simultaneously, thus enabling a convergent view of the test object. With this technology, users only need a single camera system for inspection and identification tasks, e.g., the inspection of cylindrical objects.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
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. More information.
- 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. More information.
- 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. More information.
- set_bar_code_param now throws an exception, if 'element_size_min' and 'element_size_max' are inconsistent. More information.
- 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. More information.
- 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'. More information.
- 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 '¥' . More information.
- 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'. More information.
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. You can download additional interfaces from our webserver.
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. More information.
- 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). More information.
- 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. More information.
- 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'. More information.
- 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. More information.
Supported Operating Systems
Windows
HALCON 18.05 Progress has been compiled for the following Windows platform versions:
- x86sse2-win32 platform version for Windows 7/8/8.1/10 or Windows Server 2008 R2/2012/2012 R2/2016 on Intel Pentium 4 or AMD Athlon 64 or higher with SSE2
- x64-win64 platform version for Windows 7/8/8.1/10 or Windows Server 2008 R2/2012/2012 R2/2016 x64 Edition on Intel 64 or AMD 64 processors
The setup process checks whether it is running on a 32- or 64-bit system and provides a suitable list of platform versions that can be installed. During the installation, the environment variable HALCONARCH is set to x86sse2-win32 or x64-win64 to indicate the installed platform version. Please note that if you want to switch to another platform version, you must first install it. Then, you must adapt the environment variable HALCONARCH (see the Installation Guide for more information).
Linux
HALCON 18.05 Progress has been compiled for the following Linux platform versions:
- x64 platform version for Linux x86_64, GLIBC_2.17, GLIBCXX_3.4.15, on Intel 64 or AMD 64 processors
- armv7a platform version for Linux armv7a, Kernel with hidraw support, hard-float ABI, GLIBC_2.17, GLIBCXX_3.4.4 on Armv7-A processors with NEON support
Please refer to the Installation Guide for detailed system requirements corresponding to the different Application Binary Interfaces.
macOS
HALCON 18.05 Progress has been compiled for macOS in the following platform version:
- x64 platform version for macOS 10.12/10.13 on Intel 64.
Detailed Description of Changes in HALCON 18.05 Progress
The changes in HALCON 18.05 Progress are described with respect to HALCON 17.12 Progress. The detailed description of changes in previous HALCON versions can be found in the release notes of the previous HALCON versions.General
- HALCON control tuples support a new data type for handles that provides a reference counting system similar to iconic objects. This allows HALCON to keep the ownership of handles and to support an automatic destructor mechanism, i.e., handles will be cleared automatically when destroying the last reference on it. This means that, like iconic objects, the explicit call of a clear operator for handle types, like object_model_3d or framegrabber, is not needed for handles anymore, but can still be used for early freeing of resources. The operators tuple_is_handle, tuple_is_handle_elem, clear_handle, tuple_is_valid_handle, serialize_handle, deserialize_handle, tuple_sem_type, tuple_sem_type_elem, tuple_is_serializable, tuple_is_serializable_elem, handle_to_integer, and integer_to_handle have been added to deal with the new tuple data type and take advantage of it. The use of these operators is shown in the new example programs hdevelop/File/Tuple/serialize_handle.hdev and hdevelop/Tuple/Type/tuple_type.hdev. The HALCON language interfaces for C, C++, and .NET have been revised accordingly. Code adaptions of existing code for the new data type will usually not be necessary. Please refer also to the compatibility note and the Programmer's Guide for further details. HDevEngine has been revised accordingly. For the most part this is transparent to application code and passing tuples that contain handles as input or output parameters works as expected. HDevelop is able to track semantic types for handle variables, even after assignments and in passed procedure parameters. The keywords HNULL and H_TYPE_HANDLE have been added to the HDevelop TRIAS language to address an empty handle and the handle type. The example programs have been revised to use the new handle type. Note that this change affects the compatibility. Read more.
HDevelop
New Functionality
Code Export
- The HDevelop library export that was introduced with HALCON 17.12 Progress is now also available for .NET. It makes the use of HALCON procedures from .NET as easy and intuitive as calling any other .NET function. This is possible via a .NET wrapper that encapsulates the necessary HDevEngine API calls. With the .NET library export, CMake projects are generated. CMake projects can easily be used to generate project files for popular IDEs, such as Visual Studio. The new functionality is accessible from the HDevelop GUI and via command line interface using the new option '-language cs'. Note that this change affects the compatibility. Read more.
- The export of programs and procedures has been improved to facilitate the work with, e.g., version control systems. Now, the exported external procedures are always written in lexicographical order (case insensitive) to the output files.
GUI
- HDevelop's suggestion list used the HOME or the END key to jump to the beginning or the end of the suggestion list. This has been changed in order to use the HOME or the END key to jump to the beginning or end of the program line.
IDE
- The HDevelop auto highlighting feature has been extended. Now, matching brackets, quotes and control structure blocks are also highlighted. The auto highlighting can be enabled and disabled in the preferences.
- In the Program Window, syntax errors and undefined variables were underlined with a dotted line that was easily overlooked by users. Now, these errors are highlighted with a wavy underline.
Miscellaneous
- The new HALCON functions tuple_is_handle, tuple_is_handle_elem, and tuple_is_valid_handle have also been made available as HDevelop/HDevEngine inline functions (refer to the HDevelop User's Guide, chapter 8.5.6).
- Clearing the path of a user defined directory (HDevelop's procedure settings) replaced it with the current working directory. Now, the path entry is removed when an empty string is entered.
- Error message dialogs within try/catch blocks are now suppressed by default (Preferences > General Options > Experienced User > Suppress error message dialogs in try/catch blocks). Example programs and procedures that had explicitly set this option have been adapted. Furthermore, the error message has been restated for clarity.
Bug Fixes
Assistants
- Attempts to connect to an already connected DirectShow image source from the Image Acquisition Assistant caused HDevelop to freeze. This problem has been fixed.
- Code generated by the OCR assistant for training an MLP classifier could have used a different number of hidden components as training parameter than when training the classifier within the OCR assistant itself. This problem has been fixed.
- The OCR Trainingfile Browser allowed to enter empty symbol names. Therefore, these symbols could not be deleted from the tree. This problem has been fixed. Empty symbol names are not supported anymore.
Code Export
- HDevelop's C code export sometimes terminated prematurely. This might have happened when a HALCON operator or procedure call was exported that used a global variable as an output control parameter. This problem has been fixed.
- HDevelop's .NET code export erroneously generated a line that called .Dispose on the getter function of the global variable if a value was assigned to a global variable. This problem has been fixed.
GUI
- Selecting regions by clicking on them in the Graphics Window did not work reliably for coordinates larger than 511. This problem has been fixed.
- HDevelop crashed when a matrix variable was cleared while it was being edited in the Variable Inspect Dialog. This problem has been fixed.
- In HDevelop, low-level error messages with non-ASCII characters that were displayed in the Output Console Window or the HALCON Low Level Error Message Box could have been displayed corrupted. This problem has been fixed.
- In large programs, sometimes typed characters were only displayed after some delay in HDevelop's Program Window. This problem has been fixed.
- HDevelop's auto completion did not suggest any entries for 'vector' in the global variable declaration. This problem has been fixed.
- HDevelop could have crashed during execution of an HDevelop program, when switching between the “All” tab and the “Global” tab of the Variable Window. Sometimes the Variable Window did not display all variables when switching from the “Auto” tab to the “All” tab. These problems have been fixed.
Help
- When using the navigation buttons ('back', 'forward') in the HDevelop help, the highlighting of the search result in the browser window got lost. This problem has been fixed.
- The HDevelop help didn't resolve quoted strings (using " quotation marks) correctly leading to missing highlighting of search terms in the browser window. This problem has been fixed.
IDE
- In HDevelop, string expressions with characters which cannot be represented by the current locale were sometimes corrupted. This problem has been fixed. Now, the encoding of strings is always consistent with the encoding used by the HALCON library which can be set via set_system ('filename_encoding', ...). Assigning such strings to variables or passing them to functions or HALCON operators, the characters that cannot be represented are now replaced by a placeholder (e.g., '?') or by similar character(s), whereas the replacement may depend on the operating system and the current locale.
Furthermore, when setting a variable break point on a variable to which a string with non-ASCII characters was assigned, the message in the Output Console was broken. This problem has been fixed.
Note that this change affects the compatibility. Read more. - HDevelop’s auto completion and inspection did not work correctly. The sem_type of a variable was always set to ‘any’ if a vector or tuple element has been assigned. Therefore the variable could not be used as parameter for operators expecting a specific sem_type. Furthermore, the variable could not be inspected as supposed. This problem has been fixed.
HDevelop Language
- HDevelop's vector method .remove raised an exception when the passed index value was negative (and thus, out of range), but didn't so when the passed index value was positive and out of range. This problem has been fixed. Now, no exception is raised in both cases.
- HDevelop raised a signal 11 while uninitialized vector objects have been accessed. This problem has been fixed.
Procedures
- The protection format for HDevelop files has been changed to improve security. Files containing procedures protected with the old format can still be opened, edited, and executed, but will be stored in the new format. Note that this change affects the compatibility. Read more.
- When executing a JIT-compiled procedure that contained a for-loop with an invalid start value, i.e. not of length 1 or not numeric, an exception with an incorrect error message was thrown. This problem has been fixed. Now, an exception with code H_ERR_WIPN1 or H_ERR_WIPT1 is thrown, which corresponds to the error code for non-JIT-compiled execution.
- When within a JIT-compiled procedure a user defined HDevelop exception was thrown and the user data contained a string with non-ASCII characters, the string was not correctly encoded when the exception was caught by the calling procedure. This could also have happened with Japanese system error messages that were extracted within an HDevelop script from an exception. These problems have been fixed.
- HDevelop did not recognize and resolve procedures from procedure libraries that were opened for editing first, and added afterwards via external procedure library path. This problem has been fixed.
- Encrypting large HDevelop program files took a lot of time during which the user interface was not responsive. This problem has been fixed.
- There were several problems with JIT-compiled procedures which called other procedures: After removing the path to the called procedure, HDevelop could have crashed. In addition, procedure calls within a JIT-compiled procedure were not properly resolved to other procedures after adding a new procedure path. These problems have been fixed.
Miscellaneous
- Enabling low level errors could have caused HDevelop to hang. This problem has been fixed.
- Using get_framegrabber_param and set_framegrabber_param via Operator Window could lead to invalid suggestions in rare cases. This problem has been fixed.
- HDevelop could have crashed when trying to execute procedures JIT-compiled that contained HDevelop's old error handling mechanism, i.e. handling HALCON operator errors via dev_set_check('~give_error'). This problem has been fixed.
- HDevelop crashed when an import statement was deactivated while the corresponding imported procedure was executed JIT-compiled. This problem has been fixed. Now the program execution is aborted and the deactivation of the line is postponed until the execution has stopped. For the related limitations of activating/deactivating program lines during program execution, please consult the HDevelop User's Guide.
- HDevelop crashed while dev_open_window has been called and run into an out of memory error. This problem has been fixed.
- HDevelop sometimes crashed when running JIT-compiled. This happened when the return value of an operator or procedure was stored directly into a vector element, but the operator or function actually returned nothing. This problem has been fixed.
HDevelop Example Programs
New Functionality
- The HDevelop example hdevelop/Applications/General/paddle_game.hdev has been added. With this example, it is possible to play the paddle game with one or two players, using live images and augmented reality.
- The HDevelop example hdevelop/Calibration/Multi-View/check_calib_image_quality.hdev has been added. This example program includes different procedures that can be used to evaluate the quality of calibration images, similar to the Calibration Assistant included in HDevelop.
- The usability of the examples hdevelop/Deep-Learning/Classification/classify_fruit_deep_learning.hdev and hdevelop/Deep-Learning/Classification/classify_pill_defects_deep_learning.hdev has been improved. Now, the examples warn the user right at the beginning of the examples if no suitable hardware is found or if the necessary libraries are not found.
Bug Fixes
- The example program hdevelop/Applications/Surface-Inspection/check_for_holes_sheet_of_light.hdev used camera parameters that did not correspond to a real sheet-of-light setup. This problem has been fixed.
- In the HDevelop examples hdevelop/Deep-Learning/Classification/classify_fruit_deep_learning.hdev and hdevelop/Deep-Learning/Classification/classify_pill_defects_deep_learning.hdev, the adaptation algorithm of the learning rate did not update the learning rate completely regularly according to the specified parameters. This problem has been fixed.
- In the example hdevelop/Deep-Learning/Classification/classify_fruit_deep_learning.hdev, the procedure get_error_for_confusion_matrix was named incorrectly. This problem has been fixed. Now, it is called get_predicted_classes.
New HDevelop Example Programs
- hdevelop/3D-Matching/Surface-Based/debug_find_surface_model.hdev
- hdevelop/3D-Matching/Surface-Based/find_surface_model_restrict_rotation_range.hdev
- hdevelop/3D-Matching/Surface-Based/find_symmetric_3d_objects.hdev
- hdevelop/Applications/General/paddle_game.hdev
- hdevelop/Calibration/Multi-View/calibrate_cameras_hypercentric.hdev
- hdevelop/Calibration/Multi-View/check_calib_image_quality.hdev
- hdevelop/File/Tuple/serialize_handle.hdev
- hdevelop/Image/Acquisition/gigevision2_chunkdata.hdev
- hdevelop/Inspection/Structured-Light/structured_light_partially_specular.hdev
- images/bottle_label/eye_drops_vial_hypercentric.png
- images/calib/calib_hypercentric_[01-25].png
- images/calib/check_calib_image_quality/check_calib_image_quality_[01-08].png
- images/structured_light/varnished_metal_sheet/varnished_metal_sheet_[01-36].png
- images/structured_light/varnished_metal_sheet/varnished_metal_sheet_single_stripe_[01-58].png
- 3d_models/car_rim.om3
Removed HDevelop Example Programs
- hdevelop/Identification/Bar-Code/barcode_param_meas_param_estimation.hdev
- images/barcode/ean13/ean13_meas_param_estimation_[01-10].png
HDevEngine
Bug Fixes
- In HDevEngine/.NET the passing of procedure paths with non-ASCII characters to HDevEngine via HDevEngine::SetProcedurePath and HDevEngine::AddProcedurePath was broken. This problem has been fixed. Now, it is possible to pass procedures paths with arbitrary special characters to the HDevEngine instance.
- When executing a JIT-compiled procedure that contained a for-loop with an invalid start value, i.e. not of length 1 or not numeric, an exception with an incorrect error message was thrown. This problem has been fixed. Now, an exception with code H_ERR_WIPN1 or H_ERR_WIPT1 is thrown, which corresponds to the error code for non-JIT-compiled execution.
- On Linux and macOS, HDevEngine did not follow symbolic links when looking for procedure libraries. This problem has been fixed.
- HDevelop's vector method .remove raised an exception when executed JIT-compiled with an index value beyond the vectors end, but didn't so when executed non-JIT-compiled. This problem has been fixed. Now, no exception is raised in both cases.
- HDevelop could have crashed when trying to execute procedures JIT-compiled that contained HDevelop's old error handling mechanism, i.e. handling HALCON operator errors via dev_set_check('~give_error'). This problem has been fixed.
- Loading two or more programs into the same instance of HDevEngine sometimes led to unresolved procedure calls. This problem has been fixed.
- Using Reset() with an HDevProgramCall executed in a thread led to a deadlock. This problem has been fixed.
- Loading and destroying instances of HDevProcedure and HDevProcedureCall was relatively slow. This problem has been fixed.
- HDevelop sometimes crashed when running JIT-compiled. This happened when the return value of an operator or procedure was stored directly into a vector element, but the operator or function actually returned nothing. This problem has been fixed.
- Not assigned entries of iconic vectors contained uninitialized iconic objects, instead of empty iconic objects. This problem has been fixed.
- HDevEngine/.NET was missing the HDevProcedureCall.Reset method. This problem has been fixed.
HALCON Library
Speedup
- find_shape_model, find_shape_models, find_scaled_shape_model, find_scaled_shape_models, find_aniso_shape_model and find_aniso_shape_models are now faster on machines with many cores (estimated more than 8 cores), especially for matching models with larger rotation ranges and/or scale ranges.
find_local_deformable_model, find_planar_uncalib_deformable_model and find_planar_calib_deformable_model are now faster on machines with more than one core. - HALCON now supports AVX512. get_system and set_system have been extended by parameters to verify if the processor supports this instruction set and to disable it ('avx512f_enable', 'avx512dq_enable', 'avx512bw_enable', 'avx512er_enable', 'avx512cd_enable'). There exist implementations using AVX512 for shape based matching and area_center_xld, however due to restrictions of current hardware, there are speedups only in specific cases.
- lines_gauss and lines_facet are now faster by up to 10% on Intel processors that support AVX2.
- min_max_gray with parameter 'Percent' set to 0 is now faster. In particular, the following speedups can be expected on machines with x86 or x64 processors that support the required version of the AVX instruction set:scale_image_max also benefits from this speedup by about 10% (Windows) and 6% (Linux). The operators gray_features and select_gray for features 'min' and 'max' also benefit from this speedup in the same manner as min_max_gray.
Image
TypeImage size OS Speedup
without
ParallelizationSpeedup
with
ParallelizationAvailable
Instruction
Setbyte 512x512 Windows 45% 45% AVX2 800x600 45% 40% AVX2 1024x768 45% 45% AVX2 1600x1200 45% 50% AVX2 2048x2048 40% 45% AVX2 512x512 Linux 35% 40% AVX2 800x600 35% 35% AVX2 1024x768 40% 45% AVX2 1600x1200 55% 60% AVX2 2048x2048 50% 55% AVX2
New Functionality
3D
- The usability of the sheet-of-light model has been improved. Now, for sheet-of-light models calibrated with calibrate_sheet_of_light, it is possible to obtain values for the calibrated camera parameters, camera pose, lightplane pose, and movement pose using get_sheet_of_light_param. Note that HALCON does not use the error 3789 ("Not available with 3D calibration object based calibration") anymore.
- The usability of the sheet-of-light model has been improved. HALCON has been extended with the procedure gen_sheet_of_light_object_model_3d, which, for sheet-of-light models with 'calibration' set to 'xyz', makes it possible to visualize camera, light plane and movement of the sheet-of-light model.
The HDevelop example programs hdevelop/3D-Reconstruction/Sheet-Of-Light/calibrate_sheet_of_light_3d_calib_object.hdev and hdevelop/Applications/Measuring-3D/calibrate_sheet_of_light_calplate.hdev use the procedure to visualize the results of calibration. - The new procedure debug_surface_based_matching has been added, which allows debugging the parameters for surface-based matching. The procedure is included in the new library procedures/general/debug_find_surface_model.hdpl. The new example hdevelop/3D-Matching/Surface-Based/debug_find_surface_model.hdev has been added to show the new procedure.
- The usability of set_profile_sheet_of_light and apply_sheet_of_light_calibration has been improved. Now, they raise the error 3790 ("The gray values of the disparity image, which specify rows in the camera image, do not fit the height of the camera") for models with 'calibration' set to 'xyz' or 'xz'.
- The usability of smooth_object_model_3d and surface_normals_object_model_3d has been improved. Now, the default value of the generic parameter 'mls_force_inwards' is 'true'.
Bar Code
- The bar code reader now calculates the quality grades of bar codes according to the latest ISO/IEC 15416 standard (second edition). Consequently, 'quality_isoiec15416_float_grades' of get_bar_code_result returns the print quality with one decimal place. This change of ISO/IEC 15416 also influences the print quality grading of PDF417 codes. Thus, 'quality_isoiec15415_float_grades' of get_data_code_2d_result returns the print quality for PDF417 with one decimal place.
- The bar code reader has been improved in terms of blur and low resolution. Now, bars and spaces previously missing due to low resolution and blur are detected more robustly with default settings. This improvement applies to all bar code types. Furthermore, the parameter 'meas_param_estimation' of set_bar_code_param and get_bar_code_param has been removed. Now, the default behavior covers all use cases of this parameter. Note that this change affects the compatibility. Read more.
Calibration
- HALCON has been extended by two new camera models for hypercentric lenses: 'area_scan_hypercentric_division' and 'area_scan_hypercentric_polynomial'. The HDevelop Calibration Assistant has been extended accordingly. The new HDevelop example program hdevelop/Calibration/Multi-View/calibrate_cameras_hypercentric.hdev shows how to calibrate a hypercentric lens and how images of cameras with hypercentric lenses can be prepared for inspection tasks. It uses the new images calib_hypercentric_01-25.png from the subdirectory images/calib/ and the new image eye_drops_vial_hypercentric.png from the subdirectory images/bottle_label/.
Data Code
- get_data_code_2d_param has been extended by the parameter 'symbol_type'. It retrieves the data code type from the data code handle.
- set_data_code_2d_param is now able to set the training state of parameters. This allows to extend the parameter values during a subsequent training, instead of resetting them. Furthermore, query_data_code_2d_params can be used to query all trained parameters.
Deep Learning
- The inference of deep learning classifiers with apply_dl_classifier can now be done without GPU on Intel compatible x86 processors. To support this, HALCON ships with the additional library hcpudnn.dll/libhcpudnn.so. The example hdevelop/Deep-Learning/Classification/classify_fruit_deep_learning.hdev has been extended to show how to use this mode.
Please consider that the CPU inference uses OpenMP for parallelization, which may conflict with existing OpenMP runtimes in your application. Refer to the Programmer's Guide on how to resolve these conflicts. The libraries hcpudnn.dll and libiomp5md.dll (Linux: libhcpudnn.so and thirdparty/libiomp5.so; macOS: the respecitve files are included in the HALCON(xl).framework) must be redistributed with applications that make use of the CPU based inference. - The labels in the plot created by the procedure plot_dl_classifier_training_progress have been improved. Previously, the last training error and validation error were displayed. Now, the best validation error and the associated training error are displayed. This better reflects the behavior of the provided example programs, where the best classifier is used for subsequent classification.
- The minimum requirements for Deep Learning on NVIDIA GPUs have been changed. Now, an NVIDIA driver supporting CUDA 9.1 including the cuBLAS library, as well as the library cuDNN 7.1 is required. Under Windows it is no longer necessary to manually install the cuBLAS and the cuDNN libraries. These are included in the Windows Installer for Deep Learning and installed automatically.
- To support Deep Learning on Intel CPUs, HALCON now includes two additional libraries: hcpudnn.dll (libhcpudnn.so on Linux, libhcpudnn.dylib on macOS) and libiomp5md.dll (libiomp5.so on Linux, libiomp5.dylib on macOS). These libraries must be shipped with all applications that use Deep Learning on Intel CPUs.
- The procedure plot_dl_classifier_training_progress has been improved. Instead of iterations, the plot now uses epochs to visualize the training progress. The HDevelop example programs hdevelop/Deep-Learning/Classification/classify_pill_defects_deep_learning.hdev and hdevelop/Deep-Learning/Classification/classify_fruit_deep_learning.hdev have been adapted accordingly. Note that this change affects the compatibility. Read more.
- set_dl_classifier has been extended with a new functionality to set the input image width, height, and number of channels. Each value can be set individually using 'image_width', 'image_height', and 'image_num_channels'. Alternatively one can set the values using a tuple with 'image_dimensions'. get_dl_classifier has been extended to query the new parameters.
Graphics
- The following operators now work with buffer windows:
draw_circle, draw_region, draw_polygon, draw_point, draw_point_mod, draw_line, draw_line_mod, draw_circle, draw_circle_mod, draw_ellipse, draw_ellipse_mod, draw_rectangle1, draw_rectangle1_mod, draw_rectangle2, draw_rectangle2_mod, draw_xld, draw_xld_mod, get_mbutton, get_mbutton_sub_pix, get_mposition, and get_mposition_sub_pix.
To use the draw_* operators without causing a deadlock, the application has to provide the mouse state (by using the operators send_mouse_double_click_event, send_mouse_down_event, send_mouse_drag_event and send_mouse_up_event) as well as the state of the modifier keys (also by using send_mouse_drag_event), whereas the draw operators themselves must be run in another thread. While using the draw operator, the image section must not be changed.
Inspection
- The operator set_structured_light_model_param now supports a new 'pattern_type' called 'single_stripe' which can be configured using the new parameter 'single_stripe_width'. The new pattern type can be used to improve defect detection on partially specular surfaces. To support the new 'pattern_type' the following operators have been modified: gen_structured_light_pattern, get_structured_light_object, get_structured_light_model_param, decode_structured_light_pattern, read_structured_light_model, write_structured_light_model, serialize_structured_light_model, and deserialize_structured_light_model.
The chapter Inspection/Structured Light of the Reference Manual describes the use of the new functionality. The deflectometry chapter of the Solution Guide Basics has been extended accordingly.
The new HDevelop example program hdevelop/Inspection/Structured-Light/structured_light_partially_specular.hdev shows how to determine if the inspected surface is partially specular and how to use the new functionality. It also compares the improved results to those of the default 'pattern_type'.
The new HDevelop procedure procedures/general/structured_light_inspect_segmentation.hdvp helps the user to visually inspect the Gray code of a structured light model.
Matching
- The operator set_surface_model_param can now be used to set symmetry information of the 3D model and to restrict the range of rotations that are searched by find_surface_model. For this, set_surface_model_param has been extended with the parameters 'symmetry_axis_direction', 'symmetry_axis_origin', 'symmetry_poses', 'pose_restriction_reference_pose', 'pose_restriction_max_angle_diff', 'pose_restriction_allowed_axis_direction', 'pose_restriction_allowed_axis_origin', and 'pose_restriction_filter_final_poses_only'. The new example programs hdevelop/3D-Matching/Surface-Based/find_symmetric_3d_objects.hdev and hdevelop/3D-Matching/Surface-Based/find_surface_model_restrict_rotation_range.hdev have been added to show the new behavior.
Miscellaneous
- The following unused error codes have been removed:
- H_ERR_WLST (7100, "Wrong list structure using input objects")
- H_ERR_WIOP (7101, "Wrong input object parameter (not bound)")
- H_ERR_WICP (7102, "Wrong input control par. (not bound)")
- H_ERR_WOOP (7103, "Wrong output object par. (already bound)")
- H_ERR_WOCP (7104, "Wrong output control par.(already bound)")
- H_ERR_WNOIP (7300, "Wrong number of input parameter")
- H_ERR_CPPWOM (7430, "CPP-interface internal error: Wrong object mode")
- H_ERR_CPPWNOR (7431, "Wrong number of regions (> 1) for type HRegion")
- H_ERR_CPPWNOI (7432, "Wrong number of images (> 1) for type HImage")
- H_ERR_TNOVAL (7433, "Tupel with undefined values")
- H_ERR_RPCS (7500, "No contact to RPC server")
- H_ERR_RPC (7501, "Error in remote procedure call")
- H_ERR_SWI_NOLIST (7600, "Parameter value is neither a list nor a atom")
- All proprietary HALCON files, i.e. files whose format is controlled by HALCON, will encode strings from now on in UTF-8 in order to allow exchanging these files between different countries, locales, and operating systems. This affects mainly HALCON tuples as well as OCR and OCV classifiers, training data, and sample identification models, which all contain user defined class or character names. This is also true when the data is serialized. Note, that the encoding affects only strings that contain special characters, i.e., characters that are not plain ASCII. For backwards compatibility, the operator set_system offers two new options. They can be used to control the encoding when old and new HALCON versions have to be used in parallel. The option 'write_halcon_files_encoding' allows to write HALCON files in the old locale encoding, so that they can be read by old HALCON applications, which cannot be adapted to UTF-8 mode. When an old proprietary HALCON file, which was created by a former HALCON version, is opened, the encoding of that file is assumed to be the locale system encoding. If that is not true because such a file was created in UTF-8 mode, the new set_system option 'read_halcon_files_encoding_fallback' can be used to read it correctly. The pretrained OCR classifiers that are delivered with HALCON and from which some contain the special characters '€', '£', or '¥' are also affected. After setting HALCON into UTF-8 mode via set_system ('filename_encoding', 'utf8') these classifiers can be used directly also on systems with a locale that doesn't support the special characters. Note that this change affects the compatibility. Read more.
System
- The operator get_system has been extended by two parameters for requesting information about the locale of the system. get_system ('locale_codeset', ...) returns the current code set or code page in a normalized form. get_system ('locale_raw', ...) returns the locale information that is used for string encoding issues as it is returned by the C function setlocale with the category LC_CTYPE. Detailed information can be found in the Reference Manual.
- Opening of image acquisition and I/O interfaces on Linux has been improved. Previously, interfaces had to be located in the dynamic linker's search path ($LD_LIBRARY_PATH). Now, HALCON will look in the directory the HALCON shared object (libhalcon.so) is located in even if that directory is not part of the dynamic linker's search path.
Bug Fixes
3D
- On termination, HALCON may have returned the error 1301 ("Wrong value of control parameter 1") if stereo models in persistent mode had not been cleared using clear_stereo_model. This problem has been fixed.
- Some operators claimed that a 3D object model was invalid, even though it was not. This problem has been fixed. The corresponding operators are convex_hull_object_model_3d, max_diameter_object_model_3d, smallest_sphere_object_model_3d, smallest_bounding_box_object_model_3d, and select_object_model_3d for some parameters.
- copy_object_model_3d did not copy extended attributes when they were specified explicitly with '&'. Furthermore, copy_object_model_3d did not exclude extended attributes from copying by using the prefix '~&'. In both cases, the error 1302 ("Wrong value of control parameter 2") was thrown. This problem has been fixed.
- The operator create_shape_model_3d leaks small amounts of memory when not using the OpenGL based model generation. This problem has been fixed.
- create_sheet_of_light_model, set_sheet_of_light_param and get_sheet_of_light_param did not raise an error for some inconsistent parameters. This problem has been fixed.
- create_sheet_of_light_model, set_sheet_of_light_param and get_sheet_of_light_param now return the error 3790 ("Parameter does not match the set 'calibration'") in the following cases:
- 'GenParamName' set to 'scale' when the set 'calibration' in SheetOfLightModelID is 'none'
- 'GenParamName' set to 'offset_x', 'offset_y', 'offset_z', 'scale_x', 'scale_y', or 'scale_z' when the set 'calibration' in SheetOfLightModelID is not 'offset_scale'
- set_sheet_of_light_param and get_sheet_of_light_param now return the same error in the following cases:
- 'GenParamName' set to 'camera_pose' or 'lightplane_pose' when the set 'calibration' in SheetOfLightModelID is 'none' or 'offset_scale'
- 'GenParamName' set to 'camera_parameter' when the set 'calibration' in SheetOfLightModelID is 'offset_scale'
- 'GenParamName' set to 'movement_pose' when the set 'calibration' in SheetOfLightModelID is not 'xyz'
- get_sheet_of_light_param now returns the error 3764 ("Wrong parameter name") if 'GenParamName' is set to an invalid value.
- create_sheet_of_light_model and set_sheet_of_light_param now return the error 1303 ("Wrong value of control parameter 3") if 'GenParamName' is set to 'min_gray' and 'GenParamValue' is set to a negative value.
- get_sheet_of_light_param might have returned wrong values if 'GenParamName' was set to 'offset_x', 'offset_y', 'scale_x', 'scale_y', or 'scale_z'. This problem has been fixed.
- create_sheet_of_light_model, set_sheet_of_light_param and get_sheet_of_light_param now return the error 3790 ("Parameter does not match the set 'calibration'") in the following cases:
- The parameter 'max_gap' was missing in the parameter list of find_surface_model and find_surface_model_image. This problem has been fixed.
- 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. This problem has been fixed. Note that this change affects the compatibility. Read more.
- The HALCON library did not export the symbols for the functions dealing with 3D object models. This only affects the linking of image acquisition interfaces and extension packages handling 3D object models and the use of HALCON 13 image acquisition interfaces that support 3D object models. Note that this problem has already been fixed in HALCON 17.12.0.1.
- gen_cylinder_object_model_3d did not verify if MinExtent < MaxExtent. This problem has been fixed. Now, gen_cylinder_object_model_3d returns the error 1304 ("Wrong value of control parameter 4") in case the condition is not met.
- get_object_model_3d_params in rare cases returned implausible results when 'GenParamName' was set to 'num_neighbors_fast X' and the distance 'X' was very small in relation to the size of the input point cloud. This problem has been fixed.
- get_object_model_3d_params returned wrong results when 'GenParamName' was set to 'bounding_box1', 'diameter_axis_aligned_bounding_box' or 'diameter' for primitives of type cylinder whose pose was not the identity. This problem has been fixed.
- The operator get_surface_matching_result returned the incorrect error 1303 ("Wrong value of control parameter 3") when passing 'sampled_3d_edges' after matching with a model that was not created for edge-supported surface-based matching. This problem has been fixed. The operator now returns the correct error 1302 ("Wrong value of control parameter 2").
- measure_profile_sheet_of_light crashed in rare cases after a sheet of light model was read. This problem has been fixed.
- reconstruct_surface_stereo crashed in rare cases after set_stereo_model_image_pairs was successfully called at least one time and returned with an error (in most cases error 6001 ("Not enough memory available")) just before calling reconstruct_surface_stereo. This problem has been fixed.
- set_object_model_3d_attrib_mod may have corrupted the 3D object model if it was used to change existing attributes. This caused deadlocks or crashes in subsequent operations on this 3d object model. This problem has been fixed.
- set_stereo_model_image_pairs generated images whose image size is greater than MAX_FORMAT. This problem has been fixed. Now, an error occurs when the image size is too big.
- In some cases, the operator union_object_model_3d created a 3D object model with an invalid mapping width or height if the first input object model did not have any mapping. Such invalid mapping sizes might have led to crashes in other operators that use the resulting 3D object model. This problem has been fixed.
- union_object_model_3d did not raise an error if the passed parameter 'Method' was incorrect. This problem has been fixed. union_object_model_3d now returns the errors 1202 ("Wrong type of control parameter 2"), 1302 ("Wrong value of control parameter 2") and 1402 ("Wrong number of values of control parameter 2").
- HALCON could have crashed or hang when rendering a 3D scene in one thread while modifying one of the contained 3D object models in another thread. This problem has been fixed.
Bar Code
- find_bar_code in rare cases returned an incorrect symbol region for composite barcodes. This could have effected the results for 'quality_isoiec15416' of all barcode types. This problem has been fixed.
- find_bar_code returned an incorrect trained orientation for slanted bar codes. This problem has been fixed.
- find_bar_code did not check the whole 'quiet_zone' if the scanline was too short. This problem has been fixed.
- In some cases, find_bar_code could have leaked memory, when 'stop_after_result' and 'timeout' was set. This problem has been fixed.
- get_bar_code_result with 'quality_isoiec15416' used in very rare cases uninitialized image values to evaluate the quiet zone. This problem has been fixed.
- set_bar_code_param silently ignored 'element_size_min' and 'element_size_max' when their combination was inconsistent. This problem has been fixed. Now, an error is thrown if the values are inconsistent. Furthermore, when setting both values with one call, the order does not matter anymore. Note that this change affects the compatibility. Read more.
Calibration
- The operator cam_mat_to_cam_par computed a wrong value for the Sx camera parameter, if the first and second diagonal entries of the camera matrix were not equal, i.e., for cameras with differing Sx and Sy values. Furthermore, the operators match_essential_matrix_ransac and vector_to_essential_matrix computed slightly wrong results in this case. This problem has been fixed.
- When removing a calibration observation using remove_calib_data_observ for a certain pair of camera and calibration object pose indices and adding a new observation for the same indices, the order of observation indices broke. This problem has been fixed.
- In rare cases, vector_to_pose returned a wrong pose if the method 'analytic' was used. This problem has been fixed.
Classification
- In some cases, class_ndim_norm did not support more than 255 clusters. This problem has been fixed.
Data Code
- find_data_code_2d could have crashed while reading Data Matrix ECC 200 codes if a small candidate was found at the border of the image. This problem has been fixed.
- In rare cases, find_data_code_2d for QR codes might have returned the error 3513 ("Internal error: number of chords too big for num_max"). This problem has been fixed.
- In rare cases, the QR code reader caused a low level error about still allocated temporary memory blocks. This problem has been fixed.
- get_data_code_2d_objects could have returned wrong XLDs, when querying the XLD of undecoded candidates with 'candidate_xld'. This happened due to uninitialized memory. This problem has been fixed.
- get_data_code_2d_objects could crash when querying the 'process_image', if 'small_module_robustness' was enabled. This problem has been fixed.
- In rare cases, get_data_code_2d_results crashed during print quality inspection. This problem has been fixed.
- set_data_code_2d_param did not always check the consistency of min/max values for the following parameters: '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', 'version_min/max'. This problem has been fixed. Now, an error is thrown, if the values are inconsistent. Note that this change affects the compatibility. Read more.
- The parameter 'contrast_min' of set_data_code_2d_param did not accept values greater than 100 for the Aztec code reader. To be consistent with the other code readers, this restriction has been removed.
Deep Learning
- Setting the learning rate or the momentum with set_dl_classifier_param had no effect after the first call to train_dl_classifier_batch. This problem has been fixed.
- train_dl_classifier_batch sometimes returned an invalid value for the loss (NaN or -NaN) if unsuitable hyperparameters were used. This problem has been fixed. Now, the HALCON error 7720 ("Training step failed. This might be caused by unsuitable hyperparameters.") is returned if a training step returns invalid values.
- HALCON's deep-learning-based classification could not be used with the CUDA Toolkit Version 9.1 or higher. Note that this problem has already been fixed in HALCON 17.12.0.1. Note further that we cannot guarantee that future CUDA versions can be used together with HALCON.
- A CUDA error occurred when multiple dl_classifier handles were cleared. This problem has been fixed.
File
- When writing files to disk, out-of-disk-space errors may not have been detected. This problem has been fixed.
Filter
- convol_image returned incorrect results with byte images and separable filter masks that have more than 8 columns and 'mirrored' border treatment. This problem has been fixed.
- derivate_gauss crashed for very large images (width * height > 500 million pixels). This problem has been fixed.
- The operator illuminate crashed with a mask size of 1x1. This problem has been fixed.
Graphics
- clear_scene_3d may have crashed if a previous call to display_scene_3d returned with an error. This problem has been fixed.
- When using create_drawing_object_xld and attach_drawing_object_to_window together in a zoomed graphics window, it was sometimes not possible to select a contour point of the drawing object or to merge two contiguous points. This problem has been fixed.
- If a HALCON window was placed inside another HALCON window on Linux systems, the application that created the windows, for example HDevelop, could have hang on exit if the child window was not closed before the parent window. This problem has been fixed.
- On Linux, get_window_extents could have crashed, when run in parallel to other graphics operators. This problem has been fixed.
- HALCON crashed on macOS if a 'cocoa' window was opened and used after a 'pixmap' window has been created. This problem has been fixed.
- open_window on Linux systems with a tiling window manager (e.g. matchbox) could not display an image. This problem has been fixed. If the window manager chooses to display the HALCON window with other size as specified by the HALCON window, HALCON will only render the part specified by open_window or set_window_extents.
- open_window did not return consistent error codes in case of an invalid width or height. This problem has been fixed. Now, limitations for width and height of a window are documented in the Reference Manual. In case of an invalid width the error code 1303 ("Wrong value of control parameter 3") is returned. In case of an invalid height the error code 1304 ("Wrong value of control parameter 4") is returned.
- read_char returned random characters when its execution was aborted in HDevelop by stopping the program. This problem has been fixed. Now, read_char returns an empty string.
- Drawing objects were not shown after changing window dimensions with set_window_extents if 'flush' was set to 'false'. This problem has been fixed.
- HALCON could have crashed if set_window_extents aborted with the error code 6001 ("Not enough memory available") and the window was used, e.g., with dump_window_image. This problem has been fixed.
Inspection
- add_texture_inspection_model_image and apply_texture_inspection_model returned the misleading HALCON error 3370 ("The number of image channels and the number of dimensions of the look-up table do not match") when passing over a multichannel image. This problem has been fixed. Now, the HALCON error 3359 ("Wrong number of image channels") is returned.
- apply_texture_inspection_model crashed if the patch size was larger than the image on at least one pyramid level. This problem has been fixed.
- deserialize_texture_inspection_model returned the error 3803 ("Invalid file format for a texture inspection model") if models other than a texture inspection model were serialized before the serialization of the texture inspection model. In case that more than one texture inspection model was serialized, deserialize_texture_inspection_model only deserialized the texture inspection model that was serialized first. This problem has been fixed.
- If the parameter 'novelty_threshold' was changed using set_texture_inspection_model_param after a texture inspection model has been trained, the model could not be serialized anymore. This problem has been fixed.
- If the levels of a trained texture inspection model were changed, e.g., by setting the parameter 'num_levels' from [2,3,4] before the training to 'auto' after the training, write_texture_inspection_model crashed after writing the model a second time, i.e., calling write_texture_inspection_model, read_texture_inspection_model and calling write_texture_inspection_model again. The crash only occurred if some levels were omitted, e.g., by setting 'num_levels' from [2,3,4] to [2,4] or by adding additional levels, e.g., by setting 'num_levels' from [2,3,4] to [1,2,3,4]. Furthermore, set_texture_inspection_model_param crashed after new, untrained levels were added to a deserialized texture inspection model by, e.g., setting 'num_levels' from [2,3,4] to [1,2,3,4]. These problems have been fixed.
- In contradiction to write_texture_inspection_model, serialize_texture_inspection_model was not able to serialize an untrained or only partially trained (e.g., by training not all pyramid levels) texture inspection model. This problem has been fixed. Note that this change affects the compatibility. Read more.
Image
- add_channels did not use the correct intersection of the image domain and the input regions when the image domain was rectangular and not in the top left corner. This problem has been fixed.
- append_channel did not report an error when attempting to append beyond the limit of 65535 channels to an image. This problem has been fixed.
Matching
- The operators, create_planar_calib_deformable_model_xld, create_planar_uncalib_deformable_model_xld, and create_local_deformable_model_xld returned a low level error in rare cases. This problem has been fixed.
- find_ncc_model and find_ncc_models used much more memory than necessary when called parallelized, which led to the HALCON error 6001 ("Not enough memory available") in rare cases. This problem has been fixed.
- find_shape_model, find_shape_models, find_scaled_shape_model, find_scaled_shape_models, find_aniso_shape_model, and find_aniso_shape_models did not find a correct match in rare cases, although the model has been created for and searched in a full circle. This problem has been fixed.
- On Windows 32 bit systems, find_shape_model, find_shape_models, find_scaled_shape_model, find_scaled_shape_models, find_aniso_shape_model and find_aniso_shape_model crashed when a big memory block was requested. This problem has been fixed. Now, an error is returned.
- In rare cases, get_deformable_model_params returned an unexpected error message for 'cam_param' and 'cam_param_rect' values. This problem has been fixed.
Measure
- The default_type for the get_metrology_object_num_instances parameter 'NumInstances' is 'real', which was not listed in the corresponding type_list. This problem has been fixed, i.e., 'real' has been added to the type_list of the parameter.
Miscellaneous
- Operators like mult_image, which can be parallelized on channels, dumped low-level error messages or could even have crashed, when these operators were called with input images with a different number of channels. This problem has been fixed.
- Under rare race conditions, errors were not detected while loading OpenCL source files or model files of 2D data codes. This problem has been fixed.
OCR
- In manual mode find_text sometimes failed to segment characters in binary images. This problem has been fixed.
- find_text crashed in rare cases with text models of mode 'manual'. This problem has been fixed.
- get_text_result returned error messages that were not helpful if the result name is not available for the selected mode. This problem has been fixed. Now, the HALCON error 8338 ("The result is not available for the selected text segmentation method") is returned.
- The default extension of write_ocr_class_knn has been '.okc' while the parameter 'FileName' was declared as '.onc.' in the Reference Manual. This problem has been fixed. Now, write_ocr_class_knn appends the extension '.onc' by default if no extension is set explicitly. To support k-NN OCR classifiers generated with '.okc', read_ocr_class_knn now can read '.onc', '.okc' and '.fnt' files without setting the extension.
Parallelization
- The operators for
- shape-based matching (find_shape_model, find_shape_models, find_scaled_shape_model, find_scaled_shape_models, find_aniso_shape_model, find_aniso_shape_models),
- shape-based 3D matching (find_shape_model_3d),
- deformable matching (find_local_deformable_model, find_planar_uncalib_deformable_model, find_planar_calib_deformable_model)
- NCC-based matching (find_ncc_model, find_ncc_models), and
- map_image.
Region
- The region borders of regiongrowing_mean were sometimes one pixel too large. This problem has been fixed.
System
- Parallel opening and closing of windows might have caused a deadlock in rare cases. This problem has been fixed.
- In error cases, the operator read_ocr_trainf changed the global variable 'init_new_image' to 'false'. This problem has been fixed.
XLD
- In rare cases, intersection_contours_xld returned intersections where the contour contained duplicate points. This problem has been fixed.
Procedures
Bug Fixes
- The procedure plot_tuple sometimes displayed unappealing axis labels if 'start_x' or 'start_y' have been set explicitly. This problem has been fixed.
- Changing the step width within the procedure gen_dl_classifier_heatmap could have led to inappropriate binning regions. This problem has been fixed.
- The procedure gen_dl_classifier_heatmap sometimes displayed unreasonable regions. This problem has been fixed. In addition, the procedure now also provides more intuitive information to better understand classification results. As the procedure only displays the heatmap, it has been renamed to dev_display_dl_classifier_heatmap.
- Certain procedures used case-sensitive variables, causing problems for Visual Basic code export. This problem has been fixed. Now, the procedures use case-insensitive variables.
- The result 'PyramidDistanceFromFront' of the procedure get_sheet_of_light_calib_object_dimensions was calculated incorrectly. This problem has been fixed.
New Procedures
- procedures/general/debug_find_surface_model.hdpl
- procedures/general/structured_light_inspect_segmentation.hdvp
HALCON/C++
Functionality
- The HALCON/C++ interface has been extended to support HALCON's new handle data type. The new type HHandle has been added. HTuple elements representing handles should be accessed as HHandle (*.H) instead of Hlong (*.L). HHandle is also the base class for object-oriented tool classes that wrap a handle such as HShapeModel, HMatrix, etc. All copies of a handle whether in HTuple or tool class share a common reference counter, so destroying, e.g., a HShapeModel instance no longer destroys the actual shape model if it is still referenced by a HTuple instance. Note that this change affects the compatibility. Read more.
HALCON/.NET
Functionality
- The HALCON/.NET interface has been extended to support HALCON's new handle data type. The new type HHandle has been added. HTuple elements representing handles should be accessed as HHandle (*.H) instead of Hlong (*.L). HHandle is also the base class for object-oriented tool classes that wrap a handle such as HShapeModel, HMatrix, etc. All copies of a handle whether in HTuple or tool class share a common reference counter so disposing e.g. a HShapeModel instance no longer destroys the actual shape model if it is still referenced by a HTuple instance. HTuple is now a disposable class as well to allow deterministic release of handle references stored within an instance. Note that this change affects the compatibility. Read more.
Bug Fixes
- The Serialize() member functions in the .NET interfaces crashed in rare cases. This problem has been fixed.
- Serializing or deserializing HALCON/.NET objects raised use of unmanaged memory until the next garbage collection even when explicitly disposing all objects. This problem has been fixed.
- The .NET HWindow class erroneously provided public access to the internal OnContentUpdate() member function. This problem has been fixed. OnContentUpdate() is now internal to the .NET language interface.
- The HALCON window managed by HSmartWindowControl was not destroyed deterministically when closing the parent form (although it was garbage collected later). This problem has been fixed.
- If the property 'ZoomContent' has been set to 'off' inside the HSmartWindowControl, the event function did not return X and Y coordinates as argument. This problem has been fixed.
Language Interface Example Programs
Bug Fixes
- When the HALCON/C++ example cpp/qt/Matching/matching.cpp was built with Qt5, the encoding of the copyright string was wrong. This problem has been fixed.
- Closing the HALCON/C++ example application cpp/mfc/MatchingExtWin or the example application cpp/mfc/FGMultiThreading without stopping it first could have led to an unhandled exception. This problem has been fixed.
- On MacOS X 10.9 or higher compilation of the HDevengine example hdevengine/cpp/makedir failed since the compiler did not include /Library/Frameworks by default. This problem has been fixed.
HALCON Variable Inspect Extension for Visual Studio
Functionality
- After a clean has been done in the HALCON Variable Inspect extension for Visual Studio a double click on the selected variable was necessary to update it. Now this can be achieved by a single click on it.
- The HALCON Variable Inspect extension for Visual Studio has been improved. Former it allowed to inspect variables on the highest call stack level, now it supports the inspection of HALCON Variables on every call stack level. The call stack can be switched via the Visual Studio Call Stack Window.
Bug Fixes
- The HALCON Variable Inspect extension for Visual Studio behaved unexpectedly when a non-inspected variable was selected in the "Locals" list or "Watch" list by double-clicking. Instead of retrieving the data of the currently selected variable, the data of the first selected variable was retrieved. This problem has been fixed. Now, the data of the currently selected variable is retrieved.
- The HALCON Variable Inspect extension for Visual Studio did not clean the data of watched variables after a stop or restart of the application. Thus, the old value could be visualized, although retrieving data was not successful. This problem has been fixed. Now, watched variables are cleared during stopping or restarting the application.
- The HALCON Variable Inspect extension for Visual Studio in rare cases displayed a ProcessMemory::Read reading data error. This problem has been fixed. Please note that there are still known compatibility issues when using the Variable Inspect Visual Studio Extension in combination with the JetBrains ReSharper plugin.
- Sometimes HALCON Variable Inspect extension for Visual Studio failed to read data for large objects and displayed an error message. This problem has been fixed. Moreover, the displayed error messages have been improved to be more precise.
Extension Packages
Bug Fixes
- HALCON did not unload extension package libraries if the extension packages could not be initialized properly. Besides, an error during the initialization of an extension package prevented other extension packages from being loaded. These problems have been fixed.
- Extension packages might have crashed when using the macro HGetElemS. This problem has been fixed.
Image Acquisition Interfaces
The latest information about new interface revisions and newly supported image acquisition devices can be found on MVTec's web server.
- The MVTec GigE Vision Streaming Filter version 2.1.8.1 that is part of the Windows version of the new revision 13.0.2 of the GigEVision2 interface now has a more robust and better configurable resending mechanism for the case of lost packets.
- The Windows version of the GigEVision2 interface revision 13.0.2 has been enhanced by a firewall traversal feature. If paired with a compatible camera the interface is now able to pass an active Windows Firewall.
Digital I/O Interfaces
The latest information about new interface revisions and newly supported digital I/O interfaces can be found on MVTec's web server.
- Attempting to open an I/O interface with an incompatible interface version returned a wrong error code. This problem has been fixed.
Documentation
Miscellaneous
- The documentation has been extended by a new technical note "Technical Updates". It contains information that describes technological changes in HALCON and how to adapt to them.
- The documentation of the operator fwrite_string mentioned a legacy restriction. This problem has been fixed.
- HDevEngine does not safely support subthreads (started with par_start) that continue to run after the main procedure call returns to application code. This limitation has been added to the documentation. A procedure that is intended as entry point for an engine application should join all of its started subthreads before returning.
Programmer's Manuals
- In section 20.1.1 of the Programmer's Guide, information about the parameters 'mem_free_intern', 'debug_password', and 'debug_wait_for_connection' for SetEngineAttribute has been added.
- In the HTML version of the Programmer's Guide (section 3.3), the name of the installation file for the Visual Studio extension (HALCON Variable Inspect) was missing. This problem has been fixed.
- The Programmer's Guide did not mention that halcon.lib has to be linked to be able to call FinalizeHALCONLibrary() (chapter 3.2). This problem has been fixed.
Reference Manual
- The reference manual entry of the operator add_channels has been rewritten.
- The reference manual entry of calibrate_cameras now documents the default units of camera parameters.
- create_shape_model_3d is smart enough to know that input values for 'LongitudeMin' and 'LongitudeMax' must be within a range of 360° (2pi). It changes input values accordingly while preserving the viewing angles. This issue has been documented within the reference manual entry.
- On some systems, there was an encoding problem in an image within the reference manual entry of create_sheet_of_light_calib_object. This problem has been fixed.
- In the reference manual entries of edges_image, edges_sub_pix, and edges_color, the comparison of different values of 'Alpha' does not show comparable filter widths, but filters with comparable properties. Additionally, the reference manual entry of info_edges did not explain the coefficients well enough for all possible filters. These problems have been fixed.
- The reference manual entries of find_aniso_shape_model, find_aniso_shape_models, find_scaled_shape_model, find_scaled_shape_models, find_shape_model, and find_shape_models have been extended. Now, they mention that angle and scale ranges are checked only at the highest pyramid level.
- The reference manual entry of find_data_code_2d has been improved. Now, the parameter 'module_shape' is explained more clearly, stating that only the parameters 'module_gap_min' and 'module_gap_max' are trained with this parameter.
- The reference manual entry of get_object_model_3d_params now also describes the return values for the parameter 'primitive_parameter_extension' for planes created with gen_plane_object_model_3d instead of fit_primitives_object_model_3d.
- The reference manual entry of get_object_model_3d_params now documents the parameter 'mapping_size', which returns the image size of the XYZ mapping of the 3D object model.
- The reference manual entries of median_image and median_separate did not mention that using NaNs ('not a number') as input leads to a crash, since checking for NaNs would lead to a significant performance decline. This problem has been fixed.
- In the reference manual entry of set_part, the explanation for the special setting set_part (WindowHandle, 0, 0, -2, -2) was missing. This problem has been fixed. Now, it is described that the size of the last displayed image is used to adapt the image part such that the image fits completely into the window, preserving the aspect ratio of the image.
- set_shape_model_metric ignores an origin that was set by set_shape_model_origin. This issue has been documented within the reference manual entry.
- The reference manual entry of set_surface_model_param now mentions that the camera parameters must be set before the camera pose.
- The introduction of the chapter Segmentation/Threshold has been extended with detailed descriptions regarding threshold segmentation.
- The operator tuple_ldexp uses an integer (rounded down) for the exponent, but the reference manual entry did not mention this possible rounding. This problem has been fixed.
- The reference manual entry of of tuple_split has been extended regarding subsequent separators and separators at the beginning and the end of the string.
- The introduction of the chapter Transformations/2D Transformations has been extended with information regarding the different 2D coordinate systems used in HALCON.
- The reference manual entries of operators that depend on libcanvas have been extended to explicitly state this requirement.
- The Japanese reference manual had several punctuation mark errors. This problem has been fixed.
- In the PDF version of the Japanese reference manual, a figure in the chapter 1D Measuring appeared clipped. This problem has been fixed.
User Guides
- The explanation of the procedure resolution within the HDevelop User's Guide was partly unclear. This problem has been fixed.
- The HDevelop User's Guide did not mention distinct behavior of HDevEngine concerning validity of Thread IDs. This problem has been fixed.
- In the HDevelop User's Guide, the directory name for emergency backups was outdated. This problem has been fixed.
- The HDevelop User's Guide contained outdated information related to the single underscore variable '_'. This problem has been fixed.
Installation
- On Linux systems, the HALCON shared libraries now encode the HALCON version number in the shared libraries' SONAME.
- Support to install the Armv7-a release on aarch64 machines has been added to the installer.
- The two support programs misc/reg_halconx.exe and misc/clean_reg_halconx.exe that were installed under Windows are no longer required. Therefore, they have been removed from the fileset.
- The minimum requirements for Deep Learning on NVIDIA GPUs have been changed. Now, an NVIDIA driver supporting CUDA 9.1 including the cuBLAS library, as well as the library cuDNN 7.1 is required. Under Windows it is no longer necessary to manually install the cuBLAS and the cuDNN libraries. These are included in the Windows Installer for Deep Learning and installed automatically.
- During installation on Linux systems, invalid environment variables HALCONIMAGES and HALCONEXAMPLES were set in .cshrc_halcon and .profile_halcon for installation types "Runtime" and "Compact". This problem has been fixed.
- In the installers for Linux, the file and directory access permissions were set somewhat inconsistent. This problem has been fixed.
Licensing
- The license file selection mechanism with the environment variable HALCON_LICENSE_FILE did not work with blanks in the path name. This problem has been fixed.
Release Notes of Previous HALCON Versions
Links to Major New Features of Previous HALCON Versions
The major new features of HALCON 18.05 Progress are described with respect to HALCON 17.12 Progress. Follow the links below to read about major new features of previous HALCON versions.
Links to Detailed Description of Changes in Previous HALCON Versions
The changes in HALCON 18.05 Progress are described with respect to HALCON 17.12 Progress. Follow the links below to read about changes in previous HALCON versions.