Detailed Description of Changes in HALCON 18.11.1.0 Steady

The changes in HALCON 18.11.1.0 Steady are described with respect to HALCON 13.0.2.

HDevelop

New Functionality

Code Export
  • HDevelop provides a new library export that makes the use of HALCON procedures from C++ as easy and intuitive as calling any other C++ function. This is possible via a C++ wrapper that encapsulates the necessary HDevEngine API calls. With this new library export, CMake projects are generated. CMake projects can easily be used to generate project files for many popular IDEs, such as Visual Studio. The new functionality is accessible from the HDevelop GUI and via command line interface.
  • 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.
  • HDevelop now warns the user if code containing invalid lines is exported from the command line. Depending on the graphics capabilities of the used system, either a message box pops up or a message is written to stdout. If the option -no_msg_box is set, the message is only written to stdout and HDevelop returns -1. This is useful for a command line export via scripts, which can use the return value to catch an erroneous code export.
  • 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
  • The ‘Start Dialog’ and the dialog box ‘About’ now always show the full version number, even if the last parts of the version number only contain zeros.
  • The Variable Window in HDevelop now shows the semantic type of handles for tuples that contain only a single handle.
  • HDevelop now allows to inspect handles using a new Handle Inspection Window, which can be opened by double-clicking on a variable that contains a single handle, or using the context menu of the Variable Window. The Handle Inspection Window shows the properties of the handle that can also be obtained using the get-Operators for that handle type. Note that depending on the handle type, more or less information can be displayed. The content of the window is automatically updated when stepping through the program and changes are highlighted.
IDE
  • The HDevelop editor now highlights instances of the word under the cursor or instances of the selected text. The auto highlighting can be enabled and disabled in the preferences.
  • 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.
Procedures
  • The saving of procedures in procedure library files has been improved to facilitate the work with, e.g., version control systems. Now, procedures are always stored in lexicographical order (case insensitive).
  • Within the dialog box ‘Edit Procedure Interface’, now the scope of local procedures can be chosen in the same way as the scope of external procedures. The icons of private local procedures are marked in the same way as private external procedures.
    Note that in HDevelop private local procedures behave the same as public local procedures, but in HDevEngine applications no HDevProcedure objects can be created from private local procedures nor will their names get listed by HDevProgram::GetLocalProcedureNames. Additionally, private local procedures are not included in the exported header file of the new library export.
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).
  • The handling of paths with non-ASCII characters has been improved.
  • 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.
  • The out-dated functionality ‘Insert Program …’ has been removed from HDevelop. To transfer or reuse code use HDevelop’s copy/paste mechanism, or procedures and procedure libraries.

Bug Fixes

Assistants
  • The image acquisition assistant no longer generated a close_framegrabber call. However even with the new handle mechanism an explicit close is usually desired for external resources. Therefore the call has been added again.
  • In rare cases, the operator find_text and the OCR Assistant caused a low level error about still allocated temporary memory blocks. This problem has been fixed.
  • 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.
  • 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 versions earlier than HALCON 18.05 Progress). If all sample names are valid UTF-8 characters the file is assumed to be encoded in UTF-8, otherwise local-8-bit encoding is used.
  • Changing the case of the variable name (e.g. from ‘MyImportantVariable’ to ‘myimportantvariable’) in the dialog box ‘Read Image’ did not work. This problem has been fixed.
Code Export
  • Exporting an external procedure via command line with the options -convert -no_export_of_referred_procs yielded different results than the export via the GUI with comparable settings. This problem has been fixed.
  • 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.
  • HDevelop’s library project export generated one superfluous and corruptive semicolon which prevented the exported code from compiling. Note that this problem has already been fixed in HALCON 18.05.0.1.
  • In HDevelop programs that were exported as C programs or procedures in native encoding, some strings with non-ASCII characters were not correctly encoded. This problem has been fixed.
  • Temporary vectors in expressions exported to C# or VB.NET were not disposed properly in some cases. This problem has been fixed.
GUI
  • HDevelop’s Function Inspect Window sometimes displayed erroneous labels on its x-axis. This problem has been fixed.
  • The tab order in the dialog box ‘Bounds’ of the Function Inspect Window was unintuitive. 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.
  • HDevelop crashed if an 3D object model has been inspected while the model changed via program execution. This problem has been fixed.
  • HDevelop’s ‘Visualize Object Model 3D’ widget might have crashed HDevelop if more than one model was displayed together with its model ID. This problem has been fixed.
  • Interaction with the Graphics Window after changing the display font could also change the font for existing text overlays created using the disp_text operator. This problem has been fixed.
  • Interaction with the Graphics Window after changing the set_system parameter ‘filename_encoding’ could corrupt existing non-ASCII text overlays created using the disp_text operator. This problem has 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.
  • HDevelop’s Help Window displayed HDevelop operators with parentheses, while regular HALCON operators were displayed without parentheses. 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.
  • The dialog box ‘Export Library Project’ was linked to a wrong help page. 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.
  • 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.
  • The dialog box for selecting iconic arrays and vectors (accessible from the context menu ‘Display Content’ > ‘Select ….’) did not update its content if the variables have been changed after opening the dialog. This problem has been fixed.
  • 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.
  • HDevelop’s auto completion suggested incorrect parameters after the code has been executed. Note that this problem has already been fixed in HALCON 18.05.0.1.
  • Interlacing two block statements in HDevelop (like for, while, endfor, endwhile) usually causes a syntax error. If one of the two blocks is actually deactivated (like * for, while, * endfor, endwhile) it must not affect the second one, and, therefore, no syntax error must occur. This, however, happened. This problem has been fixed.
  • HDevelop opened new inspection widgets for variables with sem_type ‘framegrabber’ instead of using an already opened inspection widget. This problem has been fixed.
  • The auto completion for dev_inspect_ctrl suggested too less variables. This problem has been fixed.
  • HDevelop could have crashed in rare cases when inserting very long program code lines. This problem has been fixed.
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
  • In rare cases calls to imported procedures appeared as valid code lines although they had too many parameters. This problem has been fixed.
  • 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.
  • The copy-and-paste of local procedures between different HDevelop instances did not work if there was an existing local procedure at the destination with matching signature and name. 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.
  • When duplicating procedures using library procedures it sometimes happened that a referenced library procedure turned into an unresolved procedure in some places whereas in some other places the library procedure was still referenced correctly. This problem has been fixed. Now, the library procedure stays resolved correctly in all places.
  • 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.
  • Procedures with calls to non-JIT-compiled procedures could not be executed JIT-compiled, even if the calls to such procedures have been deactivated. This problem has been fixed.
  • In rare cases HDevelop corrupted code lines when pasting the bodies of copied procedures. This problem has been fixed.
  • Invalid code lines were not displayed with their actual text in the tab cards ‘Invalid Lines’, ‘Find Results’, ‘Breakpoints’ and ‘Bookmarks’ of the Quick Navigation Window. This problem has been fixed.
  • Library procedures that were both explicitly opened and available via a procedure path disappeared completely when the procedure path was removed (though they should have stayed available for editing). This problem has been fixed.
  • HDevelop sometimes didn’t resolve library procedures when loading. This problem has been fixed.
Miscellaneous
  • Enabling low level errors could have caused HDevelop to hang. This problem has been fixed.
  • In HDevelop, it could have happened that string constants with characters that are not supported by the current code page, like umlauts on a Japanese system, were converted to similar ANSI characters so that they could not be used as intended, even if the HLib encoding was set to UTF-8 afterwards. 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.
  • The operator dev_set_part did not work consistently to set_part for special cases. This problem has been fixed. The remaining differences are documented.
  • 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 could have crashed when dev_get_system threw an error in a JIT-compiled procedure after setting ~give_error. This problem has been fixed.
  • The operator dev_set_window_extents resized the Graphic Window more than once. This problem has been fixed.
  • Drawing a region of interest while running an HDevelop script, e.g., within a while loop, led to problems. This problem has been fixed. Now, the execution of the script stops when activating the ROI tool.
  • open_socket_accept and open_socket_connect may have caused memory corruption due to an improper error handling. 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.
  • The HDevelop example program hdevelop/explore_halcon.hdev has been improved by providing the program runtime for each example application.
Bug Fixes
  • The HDevelop example browser listed too many examples in the category ‘Method’ > ‘I/O’. This problem has been fixed. Now, only IO interface examples are listed.
  • The HDevelop example programs and folders regarding hand-eye calibration were named inconsistently, making it difficult to find them collectively in the HDevelop example browser. This problem has been fixed. Now, filtering either for “hand-eye” or “hand_eye” lists all relevant examples.
  • 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.
  • The HDevelop example program hdevelop/System/Parameters/query_system_parameters.hdev did not work correctly on machines without OpenGL installed. This problem has been fixed.
  • Some HDevelop examples used the operator tuple_environment when it was possible to query the same information using get_system, like for example the HALCON example directory. This can be a problem when using macOS since it is not possible to set environment variables for applications started from the GUI. This problem has been fixed.
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/3D-Object-Model/Segmentation/measure_plant.hdev
  • hdevelop/3D-Object-Model/Transformations/fuse_object_model_3d_workflow.hdev
  • hdevelop/Applications/General/paddle_game.hdev
  • hdevelop/Applications/Surface-Inspection/inspect_flooring_uncalib_photometric_stereo.hdev
  • hdevelop/Calibration/Multi-View/calibrate_cameras_hypercentric.hdev
  • hdevelop/Calibration/Multi-View/check_calib_image_quality.hdev
  • hdevelop/Deep-Learning/Classification/classify_fruit_deep_learning.hdev
  • hdevelop/Deep-Learning/Classification/classify_pill_defects_deep_learning.hdev
  • hdevelop/Deep-Learning/Detection/detect_pills_deep_learning_1_prepare.hdev
  • hdevelop/Deep-Learning/Detection/detect_pills_deep_learning_2_train.hdev
  • hdevelop/Deep-Learning/Detection/detect_pills_deep_learning_3_evaluate.hdev
  • hdevelop/Deep-Learning/Detection/detect_pills_deep_learning_4_infer.hdev
  • hdevelop/Deep-Learning/Segmentation/segment_pill_defects_deep_learning_1_preprocess.hdev
  • hdevelop/Deep-Learning/Segmentation/segment_pill_defects_deep_learning_2_train.hdev
  • hdevelop/Deep-Learning/Segmentation/segment_pill_defects_deep_learning_3_evaluate.hdev
  • hdevelop/Deep-Learning/Segmentation/segment_pill_defects_deep_learning_4_infer.hdev
  • hdevelop/File/Tuple/serialize_handle.hdev
  • hdevelop/Image/Acquisition/genicamtl_acquisition_events.hdev
  • hdevelop/Image/Acquisition/genicamtl_devicelost_event.hdev
  • hdevelop/Image/Acquisition/genicamtl_fileaccess.hdev
  • hdevelop/Image/Acquisition/genicamtl_fwupdate.hdev
  • hdevelop/Image/Acquisition/gigevision2_acquisition_events.hdev
  • hdevelop/Image/Acquisition/gigevision2_action_control.hdev
  • hdevelop/Image/Acquisition/gigevision2_chunkdata.hdev
  • hdevelop/Image/Acquisition/gigevision2_devicelost_event.hdev
  • hdevelop/Image/Acquisition/gigevision2_fileaccess.hdev
  • hdevelop/Image/Acquisition/gigevision2_fwupdate.hdev
  • hdevelop/Image/Acquisition/usb3vision_acquisition_events.hdev
  • hdevelop/Image/Acquisition/usb3vision_fileaccess.hdev
  • hdevelop/Image/Acquisition/usb3vision_fwupdate.hdev
  • hdevelop/Inspection/Structured-Light/structured_light_partially_specular.hdev
  • hdevelop/Inspection/Structured-Light/structured_light_tap_collar.hdev
  • hdevelop/Object/Manipulation/insert_obj.hdev
  • hdevelop/Object/Manipulation/remove_obj.hdev
  • hdevelop/Object/Manipulation/replace_obj.hdev
  • hdevelop/OCR/Segmentation/find_text_separate_touching_chars.hdev
  • hdevelop/System/IO-Devices/hilscher-cifx_data_conversion.hdev
  • hdevelop/System/IO-Devices/hilscher-cifx_read.hdev
  • hdevelop/System/IO-Devices/hilscher-cifx_simple_diagnostic.hdev
  • hdevelop/System/IO-Devices/hilscher-cifx_write.hdev
  • hdevelop/System/IO-Devices/opc_ua_monitor_subscription.hdev
  • hdevelop/System/Multithreading/get_current_hthread_id.hdev
  • hdevelop/System/Multithreading/interrupt_operator.hdev
  • hdevelop/Tools/Geometry/distance_cc_min_points.hdev
  • hdevelop/Tuple/Data-Containers/dictionary.hdev
  • hdevelop/Tuple/String-Operations/tuple_operators_using_unicode.hdev
  • hdevelop/Tuple/String-Operations/tuple_ord_chr.hdev

HDevEngine

Functionality

  • The just-in-time (JIT) compiler of the HDevEngine now produces faster code, especially when performing arithmetic on tuples that contain single numbers. The compiled code is now up to 8 times faster than code compiled with previous versions of HALCON, and up to 100 times faster than HDevelop code that is not JIT-compiled.

Bug Fixes

  • Due to a race condition when shutting down the HDevEngine, threads were sometimes not cleaned up correctly before exiting the application, which led to a warning message. This problem has been fixed.
  • 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.
  • On Linux and macOS, HDevEngine did not follow symbolic links when looking for procedure libraries. 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.
  • There was a (rather theoretical) possibility to crash an HDevEngine C++ application using the operator SetHDevOperatorImpl with mem_free_intern=’true’. This problem has been fixed. Now, SetHDevOperatorImpl no longer supports mem_set_intern, and, as a consequence, user defined HDevOperatorImpl objects have always to be deleted by the application. Note that this change affects the compatibility.
  • Loading two or more programs into the same instance of HDevEngine sometimes led to unresolved procedure calls. This problem has been fixed.
  • During the initialization of HDevEngine, it might have happened that a small memory leak occured (about 120kB). This problem has been fixed.
  • Using Reset() with an HDevProgramCall executed in a thread led to a deadlock. 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.
  • In rare circumstances, it was possible for HDevEngine threads to run without proper error handling so that an error encountered during script execution could have led to an application crash instead of raising an HDevException. 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.
  • 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.

HALCON Library

Speedup

  • binocular_disparity_ms and binocular_distance_ms are now faster due to a further parallelization on internal data level. The achieved speedup is highly dependent on the available number of threads and data and fluctuates between 15% and 200%.
  • binomial_filter is now faster on systems that support AVX2. In particular, the following speedups compared to previously available SSE implementations can be expected:
Image TypeImage SizeFilter SizeAvailable Instruction SetSpeedup
byte1600×12003×3AVX2up to 35%
byte1600×1200 5×5AVX2up to 35%
byte1600×12007×7AVX2up to 25%
byte1600×120011×11AVX2up to 30%
byte1600×120021×21AVX2up to 35%
byte1600×12003×1/1×3AVX2up to 55%
byte1600×12005×1/1×5AVX2up to 40%
byte1600×12007×1/1×7AVX2up to 25%
byte1600×120011×1/1×11AVX2up to 40%
byte1600×120021×1/1×21AVX2up to 50%
Image TypeImage SizeFilter SizeAvailable Instruction SetSpeedup
uint2800×6003×3AVX2up to 30%
uint2800×6005×5AVX2up to 30%
uint2800×6007×7AVX2up to 40%
uint2800×60011×11AVX2up to 40%
uint2800×60021×21AVX2up to 45%
uint2800×6003×1/1×3AVX2up to 80%
uint2800×6005×1/1×5AVX2up to 90%
uint2800×6007×1/1×7AVX2up to 105%
uint2800×60011×1/1×11AVX2up to 115%
uint2800×60021×1/1×21AVX2up to 120%
  • derivate_gauss is now slightly faster on Intel compatible processors that support AVX. In particular, the following speedups can be expected:
Image SizeSigmaSpeedup without ParallelizationSpeedup with 8-Thread Parallelization
512×512115%10%
321%10%
512%9%
79%10%
98%7%
800×600 111%0%
322%12%
516%13%
713%15%
916%5%
1024×76818%-5%
318%11%
522%9%
717%14%
918%8%
1600×120018%0%
323%14%
518%13%
712%9%
916%11%
  • Please note that the achieved speedups are slightly dependent on the chosen derivative or feature to be calculated. As a result of the speed-up, the following operators also become slightly faster:
  • The operator deviation_image is now faster for image types uint2 and real. In particular, the following speedups can be excepted:
Image SizeImage typeMask SizeSpeedup without ParallelizationSpeedup with 8-Thread Parallelization
512×512uint23×3160%180%
9×9540%450%
99×997000%4250%
1600×12003×3170%65%
 9×9 525%265%
 99×99 7250%3330%
512×512real3×3105%40%
9×9 365% 210%
99×99 6050% 2500%
1600×12003×3100%10%
9×9340%125%
99×994800%2150%
OperatorImage SizeAvailable Instruction SetSpeedup
zoom_image_size
zoom_image_factor		700×500SSSE3up to 65%
AVX2up to 140%
1180×1000SSSE3up to 75%
AVX2up to 170%
1400×1050SSSE3up to 75%
AVX2up to 150%
gen_gauss_pyramid700×500SSSE3up to 45%
AVX2up to 105%
1180×1000SSSE3up to 70%
AVX2up to 155%
1400×1050SSSE3up to 70%
AVX2up to 155%

Furthermore, there was a restriction that AVX2 code was only executed when the input images were 32 byte aligned, even if the image size was divisible by 32 without remainder. This restriction has been removed. The following speedups can be expected for byte images:

OperatorImage SizeSpeedup
zoom_image_size
zoom_image_factor		800×600up to 45%
1024×768up to 45%
1280×960up to 35%
1600×1200up to 35%
gen_gauss_pyramid800×600up to 35%
1024×768up to 30%
1280×960up to 30%
1600×1200up to 40%
  • 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.
  • mean_image using a 3×3 filter mask is now faster for uint2 images. In particular, the following speedups can be expected:
Image TypeImage SizeAvailable Instruction SetSpeedup
uint2800×600AVX2up to 280%
uint21024×768AVX2up to 315%
uint21200×960AVX2up to 345%
uint21600×1200AVX2up to 170%
  • median_image is now faster for byte and uint2 images, filters of size 3×3 and 5×5 (mask type ‘square’, mask radius 1 and 2) and border handling ‘mirrored’.
    median_rect is now faster for byte and uint2 images and filters of size 3×3 and 5×5.
    rank_rect is now faster for byte and uint2 images and filters of size 3×3 (rank 5) and 5×5 (rank 13).
    In particular the following speedups can be expected for median_image for a 1600×1200 image. Similar values can also be expected for median_rect and rank_rect. Values in parenthesis apply to a 512×512 image:
Image TypeFilter SizeInstruction SetImplementation ChangeSpeedup without ParallelizationSpeedup with 8-Thread Parallelizationvs. HALCON 13
byte3×3SSE2Improved19%60%SSE2
AVX2New72%100%SSE2
Non-SIMDImproved1030%770%Non-SIMD
MMXRemovedn/an/an/a
5×5SSE2Improved22%60%SSE2
AVX2New83%150%SSE2
Non-SIMDImproved380%310%Non-SIMD
MMXRemovedn/an/an/a
uint23×3SSE2Improved-7.5% (12.5%)15%SSE2
SSE41New55%35%SSE2
AVX2New115%40%SSE2
Non-SIMDImproved7770%6850%Non-SIMD
MMXRemovedn/an/an/a
5×5SSE2Improved-10.1% (1.3%)-3.7% (30%)SSE2
SSE41New54%65%SSE2
AVX2New149%165%SSE2
Non-SIMDImproved3040%2710%Non-SIMD
MMXRemovedn/an/an/a
  • 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:
Image TypeImage sizeOSSpeedup without ParallelizationSpeedup with ParallelizationAvailable Instruction Set
byte512×512Windows45%45%AVX2
800×60045%40%AVX2
1024×76845%45%AVX2
1600×120045%50%AVX2
2048×204840%45%AVX2
512×512Linux35%40%AVX2
800×60035%35%AVX2
1024×76840%45%AVX2
1600×120055%60%AVX2
2048×204850%55%AVX2

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 SizePlatformSpeedup
uint22048×1600Windowsup to 55%
uint21600×1200Windowsup to 55%
uint21024×768Windowsup to 25%
uint2800×600Windowsup to 18%
uint22048×1600Windowsup to 60%
uint21600×1200Linuxup to 60%
uint21024×768Linuxup to 25%
uint2800×600Linuxup to 20%
uint22048×1600MacOsXup to 25%
uint21600×1200MacOsXup to 25%
uint21024×768MacOsXup to 33%
uint2800×600MacOsXup to 15%

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.
  • HALCON has been extended with an operator fuse_object_model_3d that fuses 3D object models into one watertight surface. This new method is able to combine data from various 3D sensors, even from different types like a stereo camera, a time-of-flight camera, and fringe projection. This technology is especially useful for reverse engineering. The new HDevelop example program hdevelop/3D-Object-Model/Transformations/fuse_object_model_3d_workflow.hdev shows how to use the new operator and its various parameters. It uses the new 3D object models universal_joint_part_registered_[00-14].om3 from the subdirectory 3d_models/universal_joint_part.
  • 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’.
  • surface_normals_object_model_3d has been extended by two methods which calculate point normals from triangles or an xyz_mapping, respectively.
  • triangulate_object_model_3d has been extended by a method which derives a mesh from a xyz_mapping.
  • HALCON has been extended with an operator uncalibrated_photometric_stereo that is able to detect high-frequency details such as surface scratches without any calibration process. The new HDevelop example program hdevelop/Applications/Surface-Inspection/inspect_flooring_uncalib_photometric_stereo.hdev shows the new functionality.
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.
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/.
Classification
Compute Device
  • On Arm-based platforms, available compute devices may use OpenCL now.
Data Code
  • The ECC 200 reader has been improved. In particular, it is now more robust against disturbed quiet zones. The new data code model parameter ‘candidate_selection’ can be used to determine the selection of candidate regions that are used for symbol detection. Further, the parameter ‘contrast_min’ has been removed for ECC 200 codes. The following HDevelop example programs have been adapted accordingly:
    • hdevelop/Applications/Data-Codes/ecc200_optimized_settings.hdev,
    • hdevelop/Identification/Data-Code/2d_data_codes_data_access.hdev,
    • hdevelop/Identification/Data-Code/ecc200_contrast_tolerance.hdev,
    • hdevelop/Identification/Data-Code/ecc200_print_quality_intermediate_results.hdev, and
    • hdevelop/explore_halcon.hdev.The HDevelop example program hdevelop/Identification/Data-Code/2d_data_codes_default_settings.hdev has been extended with the new images images/datacode/ecc200/ecc200_quiet_zone_disturbed_[01-03].png. For very simple images find_data_code_2d now has the option to use a less complex symbol search method with the new parameter ‘symbol_search’.
  • get_data_code_2d_param has been extended by the parameter ‘symbol_type’. It retrieves the data code type from the data code handle.
  • The operator set_data_code_2d_param has been extended by the parameter ‘string_encoding’. It specifies the expected encoding of the string which is encoded in the symbol. The string will be transcoded if necessary. Note that this change affects the compatibility.
  • 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.
  • HALCON has been extended with a set of operators that can be used to read and train a deep neural network, and to apply it on images for classification tasks. Since the CNN (Convolutional Neural Network) extracts features automatically during training, using these operators avoids the need to manually extract features – a big advantage compared to all previous classification methods. The operators for deep-learning-based classification are
    • apply_dl_classifier_batchwise,
    • evaluate_dl_classifier,
    • gen_dl_classifier_heatmap,
    • get_dl_classifier_image_results,
    • plot_dl_classifier_training_progress,
    • preprocess_dl_classifier_images,
    • read_dl_classifier_data_set,
    • select_percentage_dl_classifier_data, and
    • split_dl_classifier_data_set.The following additional general purpose procedures have been added to support deep-learning-based classification applications:
    • augment_images and apply_brightness_variation_spot in the procedure library augment_images.hdpl and
    • procedures/general/gen_confusion_matrix.hdvp.The new HDevelop example programs classify_pill_defects_deep_learning.hdev and classify_fruit_deep_learning.hdev in the subdirectory hdevelop/Deep-Learning/Classification have been added to show the deep-learning-based classification. The examples use the new images in the subdirectories
    • food/apple_braeburn,
    • food/apple_golden_delicious,
    • food/apple_topaz,
    • food/peach,
    • food/pear,
    • pill/ginseng,
    • pill/magnesium, and
    • pill/mint.The images for these examples are available as download in a separate installer. Please, refer to the Installation Guide for more information.
      HALCON has been extended with two pretrained deep-learning-based classifiers, which can be found in the directory %HALCONROOT%/dl:
    • pretrained_dl_classifier_compact.hdl and
    • pretrained_dl_classifier_enhanced.hdl.The Solution Guide on Classification has been extended to describe how to use the new deep learning functionality.
      Please note that this functionality has special system requirements. Amongst others, third party libraries have to be installed manually. Please refer to the Installation Guide for more information.
  • The classifier pretrained_dl_classifier_compact.hdl has been adapted such that the network can be used as backbone for the new operator create_dl_model_detection. Moreover, the minimal image width and height of the network have been changed from 17 pixel to 15 pixel.
  • HALCON has been extended with deep learning based object detection to locate object instances in an image. The location of an instance within the image is given by a rectangular, axis parallel bounding box.
    The new operator create_dl_model_detection has been added to create a deep learning model for object detection. For all other purposes besides creation, the general purpose dl_model operator set is used.
    The object detection model uses a pretrained deep learning classifier as backbone network. All pretrained classifiers shipping with HALCON can be used for this purpose to fit detection tasks of different difficulty.
    The HDevelop example series
    • examples/hdevelop/Deep-Learning/Detection/detect_pills_deep_learning_1_prepare.hdev
    • examples/hdevelop/Deep-Learning/Detection/detect_pills_deep_learning_2_train.hdev
    • examples/hdevelop/Deep-Learning/Detection/detect_pills_deep_learning_3_evaluate.hdev
    • examples/hdevelop/Deep-Learning/Detection/detect_pills_deep_learning_4_infer.hdevhas been added to show how to use deep learning based object detection in HALCON. These examples use the new images in examples/images/pill_bag and the annotations in examples/hdevelop/Deep-Learning/Detection/pill_bag.json.
      To enable usage of part 3 and 4 of this series without executing the time consuming training part, the pretrained object detection model examples/hdevelop/Deep-Learning/Detection/detect_pills.hdl, the preprocessing parameters examples/hdevelop/Deep-Learning/Detection/detect_pills_preprocess_param.hdict, and the evaluation results examples/hdevelop/Deep-Learning/Detection/detect_pills_deep_learning_3_evaluate_result.hdict are used.
      The HALCON Operator Reference Manual has been extended with a chapter on object detection to describe how to use the new deep learning functionality (“Deep Learning -> Object Detection”).
      The new procedure read_dl_dataset_from_coco can be used to read a set of annotations for object detection in the COCO format.
      Please note that this functionality has special system requirements. Amongst others, third party libraries have to be installed with a separate installer. This installer also contains the images and pretrained model for the examples. Please refer to the Installation Guide for more information.
  • HALCON now includes a pretrained deep learning classifier based on the popular ResNet-50 architecture: dl/pretrained_dl_classifier_resnet50.hdl.
    This classifier can be used for very complex classification tasks or as backend for very complex object detection problems.
  • 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.
  • HALCON has been extended with functionality to train deep learning based semantic segmentation models. These new segmentation models are a big advantage compared to previous segmentation methods. They learn automatically to segment defects or objects based on training data. These models are able to solve both very complex and easy segmentation tasks.
    HALCON has been extended with two pretrained semantic segmentation models, which can be found in the directory dl:
    • pretrained_dl_segmentation_compact.hdl and
    • pretrained_dl_segmentation_enhanced.hdl.These models can be used as a good starting point to solve advanced segmentation tasks. The general purpose dl_model operator set can be used to train, adjust, and apply these models to custom segmentation tasks. The input image dimension of this feature is flexible in width, height, and depth. The maximum image dimension is limited by the capacity of the available GPU memory used to train the model. Inference of these models is highly optimized for CPU and GPU. Training is implemented for GPUs only.
      The HDevelop example series
    • examples/hdevelop/Deep-Learning/Segmentation/segment_pill_defects_deep_learning_1_preprocess.hdev
    • examples/hdevelop/Deep-Learning/Segmentation/segment_pill_defects_deep_learning_2_train.hdev
    • examples/hdevelop/Deep-Learning/Segmentation/segment_pill_defects_deep_learning_3_evaluate.hdev
    • examples/hdevelop/Deep-Learning/Segmentation/segment_pill_defects_deep_learning_4_infer.hdevhas been added to show how to use deep learning based semantic segmentation in HALCON. These examples use ground truth annotations located in the folder examples/images/labels/pill.  To enable usage of part 3 and 4 of this series without executing the time consuming training part, the pretrained segmentation model examples/hdevelop/Deep-Learning/Segmentation/segment_pill_defects.hdl and the corresponding preprocessing parameters examples/hdevelop/Deep-Learning/Segmentation/segment_pill_defects_preprocess_param.hdict are used.
      The HALCON Operator Reference Manual has been extended with a chapter on semantic segmentation to describe how to use the new deep learning functionality (“Deep Learning -> Semantic Segmentation”).
      The new procedure read_dl_dataset_segmentation can be used to read annotation data used commonly in semantic segmentation tasks.
      Please note that this functionality has special system requirements. Amongst others, third party libraries have to be installed with a separate installer. This installer also contains the images and pretrained model for the examples. Please refer to the Installation Guide for more information.
  • get_dl_classifier_train_result has been extended to individually query the ‘mll_loss’ and ‘regularization_loss’ terms of the loss function.
  • The operator train_dl_classifier_batch now supports arbitrary batch sizes independent of the available GPU device memory. This is realized by subdividing the batch into smaller subbatches from which the update is iteratively calculated. The size of the subbatches can be set with ‘batch_size_device’ using set_dl_classifier_param.
  • HALCON has been extended with a general purpose operator set for deep learning, which is shared by the new deep learning based functionalities Object Detection and Semantic Segmentation. The following operators have been added:
    • find_dl_samples
    • gen_dl_samples
    • gen_dl_samples_from_images
    • read_dl_dataset_from_coco
    • read_dl_dataset_segmentation
    • read_dl_samples
    • split_dl_dataset
    • write_dl_samplesThe new procedure library dl_visualization contains procedures to visualize DLSamples and evaluation results
    • dev_display_dl_data
    • dev_display_dl_data_close_windows
    • dev_display_dl_data_tiled
    • dev_display_detection_detailed_evaluation
    • dev_display_segmentation_evaluationThe new procedure library dl_preprocess contains procedures to preprocess a DLDataset for training of individual DLSamples for inference:
    • calculate_dl_segmentation_class_weights
    • create_dl_preprocess_param
    • create_dl_preprocess_param_from_model
    • gen_dl_segmentation_weight_images
    • preprocess_dl_dataset
    • preprocess_dl_model_images
    • preprocess_dl_model_segmentations
    • preprocess_dl_samplesThe new procedure library dl_evaluation contains procedures to evaluate a trained model:
    • calculate_evaluation_measures
    • create_evaluation_default_param
    • evaluate_dl_model
    • init_running_evaluation_measures
    • update_running_evaluation_measuresThe new procedure library train_dl_model contains procedures to train a dl_model:
    • create_dl_train_param
    • set_dl_model_param_based_on_preprocessing
    • train_dl_modelThe new procedure augment_dl_samples can be used to augment DLSamples for training.
      The new procedure set_dl_model_param_max_gpu_batch_size can be used to determine the maximum available batch size for a DLModel with respect to the available GPU memory.
      Please note that this functionality has special system requirements. Among others, third party libraries have to be installed with a separate installer. Please refer to the Installation Guide for more information.
  • The procedure gen_interactive_confusion_matrix has been added. It visualizes a confusion matrix whose entries can be clicked, displaying the respective images.
  • 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.
  • 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.
  • HALCON now ships with version 7.3.1 of the cuDNN library.
  • To use HALCON’s deep learning functionality with NVIDIA GPUs it is now required that the graphics driver supports at least CUDA 10.0. The cuDNN and cuBLAS libraries shipping with HALCON now target CUDA 10.0.
    This does not affect the aarch64 platform, which only requires a CUDA 9.0 compatible driver.
Feature
  • HALCON has been extended with the operators height_width_ratio and height_width_ratio_xld, which compute the height, width, and aspect ratio of the enclosing axis-aligned rectangle of regions as well as XLD contours and polygons. Furthermore, region_features, select_shape, andselect_shape_xld have been extended by the feature ‘ratio’. The feature ‘ratio’ is now also available in HDevelop’s ‘Feature Inspection’ and ‘Feature Histogram’ dialogs.
File
Filter
  • The operator deviation_image is now faster by up to 40% for byte images. Note that this change affects the compatibility.
Graphics
Inspection
Matching
  • The usability of the shape-based matching operators (find_shape_model, find_shape_models, find_scaled_shape_model, find_scaled_shape_models, find_aniso_shape_model, find_aniso_shape_models) has been improved. Now, the operators are robustly interruptible, i.e., they can be cancelled in HDevelop, a timeout can be set for them, and they can be interrupted from other threads using the new operator interrupt_operator.
  • 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”)
  • The new operators get_handle_param, get_handle_tuple, and get_handle_object have been added. They can be used to inspect handles of most types, which can help during development and debugging of applications.
  • HALCON has been extended with an operator insert_obj, which inserts iconic objects into an iconic object tuple. The new HDevelop example program hdevelop/Object/Manipulation/insert_obj.hdev shows the new functionality.
  • HALCON has been extended with an operator remove_obj that removes single iconic object elements from an iconic object tuple. The new HDevelop example program hdevelop/Object/Manipulation/remove_obj.hdev shows how to use it.
  • HALCON has been extended with an operator replace_obj that replaces single iconic object elements of an object array. The new HDevelop example program hdevelop/Object/Manipulation/replace_obj.hdev shows how to use it.
  • When HALCON was installed into a folder with non-ASCII characters or if global HALCON folders like the image or 3d model directory were set with the set_system operator to a path with non-ASCII characters, and if afterwards the filename encoding was changed, the folder names became corrupted and could not be used correctly, e.g., when opening an image with theread_image operator passing only the file name without full path. This problem has been fixed.
  • HALCON has been extended with the new set_system parameter ‘disabled_operators’ that disables the specified HALCON operators. Those operators will return H_ERR_OP_DISABLED if used. The intended use case is to allow developers of freely programmable devices (usually with HDevengine) to explicitly deactivate certain HALCON operators which could affect the security of the device.
  • 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.
  • Several operators now signal their progress to the application using a common interface. For this, set_system was extended by the arguments ‘add_progress_callback’ and ‘remove_progress_callback’, which applications can use to register themselves to obtain such callbacks. Currently, the following operators support such callbacks:
  • The range of operators that work with UTF-8 encoding has been extended to the operators system_call, read_char, and read_string.
    After setting the filename encoding to ‘utf8’ these operators accept UTF-8 strings with arbitrary characters.
OCR
  • The Automatic Text Reader has been extended to detect and separate pairs or small groups of horizontally touching characters more reliably. The new text model parameter ‘separate_touching_chars’ can be used to control the separation of touching characters. If this parameter is set to ‘enhanced’, find_text detects touching regions with a new comprehensive method that uses the new helper file %HALCONROOT%/ocr/find_text_support.hotc. The new HDevelop example program hdevelop/OCR/Segmentation/find_text_separate_touching_chars.hdev demonstrates the usage of the new text model parameter. It uses the new images article_label_01, article_label_02, and article_label_03 from the subdirectory images/ocr/.
Segmentation
  • segment_image_mser has been improved such that it is now possible to set the minimal and maximal gray values that are considered in the segmentation process, which might reduce the runtime considerably. The HDevelop example program
    • hdevelop/Segmentation/MSER/segment_image_mser.hdev
    has been adapted to display how the minimal and maximal gray values can be set.
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.
  • get_system has been extended by the parameter ‘edition’ that returns the HALCON Edition of the running HALCON library.
  • get_system has been extended with the parameters ‘cuda_loaded’, ‘cuda_version’, ‘cuda_devices’, ‘cudnn_loaded’, ‘cudnn_version’, ‘cublas_loaded’, and ‘cublas_version’ to query the versions of CUDA, cuDNN, and cuBLAS, which have to be installed when using the new deep learning functionalities. The HDevelop example program hdevelop/System/Parameters/query_system_parameter.hdev has been extended to include the queries of the versions of CUDA, cuDNN, and cuBLAS.
  • 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.
Timeout
Tuple
  • HALCON has been extended with a new container data type called ‘dictionary’. It allows to store arbitrary key-value pairs, which can be retrieved in constant time. This can help to structure programs when, e.g., passing many parameters to a procedure. For this, the following new operators were introduced:
    • create_dict
    • write_dict
    • read_dict
    • remove_dict_key
    • get_dict_param
    • set_dict_tuple
    • get_dict_tuple
    • set_dict_object
    • get_dict_object
    • copy_dictserialize_handle and deserialize_handle have been adapted so that they can (de)serialize dictionaries. Besides a HALCON-specific format, read_dict can also read files in the JSON format.
      The HDevelop example program examples/hdevelop/Tuple/Data-Containers/dictionary.hdev has been added, which replaces the HDevelop example examples/hdevelop/System/Multithreading/messages_as_dictionary.hdev.
      The HDevelop example programs examples/hdevelop/Applications/Robot_Vision/pick_and_place_with_2d_matching_moving_cam.hdev, examples/hdevelop/Applications/Robot_Vision/pick_and_place_with_2d_matching_stationary_cam.hdev, and examples/hdevelop/Calibration/Hand-Eye/calibrate_hand_eye_stationary_cam_approx.hdev have been adapted to use dictionaries instead of messages. Note that this change affects the compatibility.
  • When an empty tuple was used in tuple_concat, a mixed tuple was returned. Now the returned tuple has the type of the non empty tuple.
XLD
  • HALCON has been extended with a new operator distance_cc_min_points, which is an improved version of distance_cc_min. In particular, the new operator does the same calculations as the older one, but additionally provides the points in the two contours used for the calculation. The new HDevelop example program hdevelop/Tools/Geometry/distance_cc_min_points.hdev demonstrates the new functionality.

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.  Note that this change affects the compatibility.
  • When calling create_surface_model in parallel from several threads with the ‘train_3d_edges’ parameter set to ‘true’, the created models were incorrect and could contain invalid 2D and 3D edges. This problem has been fixed. create_surface_model is now safe to use from multiple threads.
  • The operators disp_object_model_3d, render_object_model_3d, display_scene_3d, and render_scene_3d could crash when displaying infinite primitive shapes (cylinders or planes without boundary). This problem has been fixed.
  • The operator distance_object_model_3d, when applied with the ‘voxel’ method, sometimes returned incorrect distances. This problem has been fixed. Note that 3D object models for which the ‘voxel’ index was previously created with the operator prepare_object_model_3d and that were written as OM3 file need to be re-prepared to apply this fix.
  • distance_object_model_3d was not using the information prepared in prepare_object_model_3d by default. This problem has been fixed.
  • The parameter ‘max_gap’ was missing in the parameter list of find_surface_model and find_surface_model_image. This problem has been fixed.
  • The operator fit_primitives_object_model_3d can fit cylinders into point clouds. Sometimes, small changes of the input point cloud switched the orientation of the fitted cylinder, i.e., its pose and axis. This problem has been fixed. Now, the axis points towards the half space in which the origin is located.
  • 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_binocular_rectification_map and set_stereo_model_image_pairs in rare cases raised an error because the generated maps got too large. This problem has been fixed. Now, the parameter ‘Method’ of gen_binocular_rectification_map has the new default value ‘viewing_direction’. set_stereo_model_image_pairs also uses this method per default. set_stereo_model_param, get_stereo_model_param, and create_stereo_model have been extended with the generic parameter (GenParamName) ‘rectif_method’ and the according parameter values (GenParamValue) ‘viewing_direction’ or ‘geometric’. Note that this change affects the compatibility.
  • 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 debug procedure procedures/general/debug_find_surface_model.hdpl displayed incorrect edges if the center of the surface model was not the origin. Additionally, the initial visualization pose was such that the model was not visible. These problems have been fixed. debug_find_surface_model.dhpl now shows the correct edges and uses the correct initial pose.
  • 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.
  • The operator segment_object_model_3d crashed in rare cases. This problem has been fixed.
  • For the file format ‘om3’, the operators set_object_model_3d_attrib, set_object_model_3d_attrib_mod and read_object_model_3d did not raise errors for inconsistent ‘xyz_mappings’, e.g., for mappings of height zero, or pixel values outside the given image dimensions. Many operators processing object_model_3d with mappings might have crashed due to the inconsistently generated models. This problem has been fixed. Now, set_object_model_3d_attrib and set_object_model_3d_attrib_mod return the following errors:
    • 3524 (“Image width <= 0”),
    • 3521 (“Image width > MAX_FORMAT”),
    • 3525 (“Image height <= 0”),
    • 3523 (“Image height > MAX_FORMAT”),
    • 1304 (“Wrong value of control parameter 4”).The operator read_object_model_3d now returns the error 9511 (“Invalid 3D object model”).
  • 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.
  • triangulate_object_model_3d with Method set to ‘implicit’ returned different results for empty GenParamName and GenParamValue on the one hand, and GenParamName set to ‘implicit_octree_depth’, GenParamValue set to 6 on the other hand, although 6 is the default value of ‘implicit_octree_depth’. This problem has been fixed. Now, triangulate_object_model_3d in both cases returns the results which previously were returned for empty parameters.
  • 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.
  • 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.
  • The procedure debug_find_surface_model sometimes threw internal exceptions when some 3D object models, such as edges, were empty. This problem has been fixed. Now, exceptions in sub-tools are caught and properly reported.
Bar Code
  • find_bar_code, decode_bar_code_rectangle2, and find_data_code_2d in some cases returned incorrect results if the internal image width and height of the system were smaller than the actual size of the input image. This could have happened in cases where the operators were called in a different thread than the one in which the corresponding image has been read or created or if the system image width and height has been changed with set_system. This problem has been fixed.
  • The operator find_bar_code crashed in rare cases when the ‘quiet_zone’ of set_bar_code_param was set to a high value. This problem has been fixed.
  • In some cases, find_bar_code was significantly slower on machines with many cores. This problem has been fixed.
  • The operator find_bar_code did not check the quiet zone correctly when the quiet zone check was enabled. This problem has been fixed.
  • 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.
  • In rare cases of print growth or overexposure, find_bar_code did not apply the “merged_scanlines” feature correctly. This problem has been fixed.
  • get_bar_code_result could have returned wrong values for the ISO/IEC 15416 decodability in case of EAN-8 symbols. This problem has been fixed.
  • get_bar_code_result with quality_isoiec15416 in rare cases returned an incorrect modulation grade when an edge was lying directly at the end of the quiet zone. This problem has been fixed.
  • The operator set_bar_code_param adapted the value of ‘min_identical_scanlines’ when ‘num_scanlines’ was set to 0. This problem has been fixed. Now, ‘min_identical_scanlines’ is adapted only when ‘num_scanlines’ is greater than 0.
  • 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.
  • In very rare cases, horizontally oriented barcodes could not be decoded. This problem has been fixed. Note that this change affects the compatibility.
  • HALCON now supports all GS1 application identifiers specified in the latest version of the “GS1 General Specifications” (January 2018).
Calibration
  • The operators calibrate_cameras, binocular_calibration, and the camera calibration in calibrate_hand_eye in rare cases did not perform as well as expected, i. e., they have returned with an unnecessarily high reprojection error. This problem has been fixed. Note that this change affects the compatibility.
  • The comments of the calibration description files generated by create_caltab contained misleading values for ‘width’ and ‘height’. Furthermore, the formulas for ‘width’ and ‘height’ in the reference manual entry of create_caltab were incorrect. These problems have been fixed.
  • gen_binocular_rectification_map and set_stereo_model_image_pairs in rare cases raised an error because the generated maps got too large. This problem has been fixed. Now, the parameter ‘Method’ of gen_binocular_rectification_map has the new default value ‘viewing_direction’. set_stereo_model_image_pairs also uses this method per default. set_stereo_model_param, get_stereo_model_param, and create_stereo_model have been extended with the generic parameter (GenParamName) ‘rectif_method’ and the according parameter values (GenParamValue) ‘viewing_direction’ or ‘geometric’. Note that this change affects the compatibility.
  • get_calib_data for ItemType set to ‘camera’ and DataName set to ‘params_deviations’ or ‘params_covariances’ returned unintuitive values more often than necessary, in particular when the covariance matrix was nearly singular. This problem has been fixed. Note that this change affects the compatibility.
  • 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.
  • The operators classify_class_gmm and evaluate_class_gmm returned incorrect values for the k-sigma probability ‘KSigmaProb’ for Gaussian Mixture Models with covariance type ‘spherical’ or ‘diag’. This problem has been fixed. Note that this change affects the compatibility.
  • When removing sample identifier training data out of a set of multiple samples, internal data structures may have been corrupted. This problem has been fixed.
  • In very rare cases a support vector machine (SVM) issued an error that it is not trained yet, despite being trained. This problem has been fixed.
Data Code
  • find_bar_code, decode_bar_code_rectangle2, and find_data_code_2d in some cases returned incorrect results if the internal image width and height of the system were smaller than the actual size of the input image. This could have happened in cases where the operators were called in a different thread than the one in which the corresponding image has been read or created or if the system image width and height has been changed with set_system. This problem has been fixed.
  • In very rare cases find_data_code_2d crashed for ECC 200 symbols if a candidate was found close to the image border. This problem has been fixed.
  • In very rare cases, find_data_code_2d crashed with signal 11 failure for Aztec codes. This problem has been fixed.
  • The operators find_data_code_2d and find_bar_code were not able to decode in case of an GS1 Code containing the application identifier 714. This problem has been fixed.
  • The operators find_data_code_2d and set_distance_transform_xld_param did not set the ‘modified’ flag for their handle parameter, which can get queried with get_param_info. This problem has been fixed.
  • For invalid values of the data code model parameter ‘module_gap’ find_data_code_2d crashed in rare cases. This problem has been fixed.
  • For Micro QR and Aztec codes find_data_code_2d in some cases was significantly slower on machines with many cores. This problem has been fixed.
  • In very rare cases the print quality inspection for ECC 200 codes crashed for symbols that lay close to the image border. This problem has been fixed.
  • In some cases the variable module grid used for print quality inspection of the ECC 200 reader was inaccurate in case of distorted clock patterns. This could have led to bad quality grades. This problem has been fixed.
  • In rare cases, the image pixel data for ECC 200 data codes was taken from uninitialized memory. 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.
  • get_data_code_2d_results returned wrong values for ‘symbol_identifier’ of Aztec codes when the data string contained a FNC1 character. This problem has been fixed.
  • In some cases get_data_code_2d_results returned wrong  ISOIEC 15415 and AIMDPM-2006-1 quality values for ‘print growth’ and ‘contrast uniformity’. This problem has been fixed.
  • The operator get_data_code_2d_results returned invalid values for the candidate groups ‘symbology_ident’ and ‘structured_append’ in case of Micro QR Codes. This problem has been fixed.  Note that this change affects the compatibility.
  • In rare cases, get_data_code_2d_results crashed during print quality inspection. This problem has been fixed.
  • HALCON now supports all GS1 application identifiers specified in the latest version of the “GS1 General Specifications” (January 2018).
Deep Learning
  • Handles of the deep-learning-based classifier (dl_classifier) could not be deserialized with deserialize_handle. This problem has been fixed.
  • The deep-learning-enhanced classifier did not perform well when resized. This problem has been fixed. As a consequence the minimal image width and height for the enhanced classifier is now 47.
  • The procedure dev_display_dl_classifier_heatmap did not work for single-channel input images. This problem has been fixed. Now, the procedure works for images with either one or three channels.
  • 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.
  • In some cases, train_dl_classifier_batch reported a cuDNN error in out of memory constellations. This problem has been fixed. Now, an error indicating that no memory is available on the GPU is returned instead.
  • 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 occured when multiple dl_classifier handles were cleared. This problem has been fixed.
  • The serialization of larger models was significantly slower than writing them to disc. This behavior has been improved. As a consequence, the memory consumption of serialized models increased up to 25%.
Feature
File
  • Calling copy_file with long path names on Windows could lead to an error in temporary memory management. This problem has been fixed.
  • Using very long path names for the copy_file operator could crash HALCON. This problem has been fixed.
  • If copy_file was called with the same name for the source as well as the destination file, the source file was destroyed. This problem has been fixed. Now, the source file is not changed in this case.
  • The operators read_image and read_region leaked memory when for concatenated objects the error 5279 (“Unexpected object detected”) was returned for the second or any subsequent indices of the object array. This problem has been fixed.
  • Using very long filenames with write_image in ‘tiff’ format or write_ocv may have caused buffer overruns and crashes. This problem has been fixed.
  • When writing files to disk, out-of-disk-space errors may not have been detected. This problem has been fixed.
  • A check preventing serialized data to be written to files not opened in binary mode was missing, resulting in possible data corruption. This problem has been fixed. Now, the error 5281 (“File has not been opened in binary file format”) is returned in attempts to read or write serialized data to/from files not opened in binary mode.
Filter
  • derivate_gauss crashed for very large images (width * height > 500 million pixels). This problem has been fixed.
  • The operator deviation_image did not return results as accurate as possible for images of type ‘real’. This problem has been fixed.
  • The operator deviation_image did not raise an error when the filter size exceeded the image size for images whose type is not ‘byte’. This problem has been fixed. Now, deviation_image returns the error 3033 (“Filter size exceeds image size”).
  • The operator exhaustive_match_mg crashed for some invalid values of the parameter ‘Level’. This problem has been fixed. Now, an error is returned if ‘Level’ does not fit the image or template size.
  • Due to a incorrect rounding factor, the C implementation used for the creation of the Gauss pyramid for uint2 images returned slightly incorrect results. This problem has been fixed. The problem can only occur if the image is internally cropped, i.e., for the following operators: find_local_deformable_model, find_planar_calib_deformable_model, find_planar_uncalib_deformable_model, find_ncc_model, find_ncc_models, find_aniso_shape_model, find_aniso_shape_models, find_scaled_shape_model, find_scaled_shape_models, find_shape_model, and find_shape_models. Note that the corresponding SSE41 implementation is not affected by this bug. Note that this change affects the compatibility.
  • The operator gen_spherical_mosaic sometimes crashed, returned invalid results, or raised the error 3513 (“Internal error: number of chords too big for num_max”) if ‘StackingOrder’ was set to ‘blend’. These problems have been fixed.
  • The operator illuminate crashed with a mask size of 1×1. This problem has been fixed.
  • mean_image crashed in rare cases if a compute device was activated and the mask size was 3×3. 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.
  • The operators disp_rectangle1 and disp_rectangle2 could show unwanted display artifacts when anti-aliasing was enabled. This problem has been fixed.
  • dump_window_image now supports setting the internal image width and height of the system. The internal width and height of the system are the maximum width and height of all HALCON image objects. It will be increased if images of greater width or height are instantiated subsequently.
  • On Linux, get_window_extents could have crashed, when run in parallel to other graphics operators. 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.
  • The operator read_string allows to limit the size of the string that can be entered into a HALCON window. After switching the encoding of the HALCON library to UTF-8 withset_system (‘filename_encoding’, ‘utf8’) the passed length could not entirely be used when non-ASCII characters had been entered. This problem has been fixed. In UTF-8 mode the Length parameter now determines the number of characters instead of the number of bytes. This is not true in the legacy ‘locale’ encoding mode and for legacy HALCON windows.
  • set_drawing_object_params in rare cases might have caused HDevelop to freeze. For drawing objects of type rectangle1, set_drawing_object_params in rare cases might have crashed or raised a memory error. This problem has been fixed.
  • The operators set_window_extents and dev_set_window_extents crashed if ‘flush’ was set to ‘false’. This problem has been fixed.
  • 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.
  • If HIOCancelDraw was called before calling a drawing operator, the drawing operator aborted immediately. This problem has been fixed.
Inspection
  • 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.
Images
  • 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.
  • The operator channels_to_image threw the HALCON error 3513 (“Internal error: number of chords too big for num_max”) for images with ‘Width’ equal to 1. This problem has been fixed.
  • The operators crop_rectangle1 and crop_part raised an error in cases where more than one input image and more than one set of region parameters was specified and the numbers were not equal. Furthermore, they might have raised errors when used in parallel in cases where more input images than available threads and more than one set of region parameters was specified. This problem has been fixed.
  • The HALCON/CPP interface crashed when calling operators with output control parameters if an iconic input object parameter was not set (i.e., the input was a NULL-object). This problem has been fixed.
  • write_image leaked memory when writing the ‘jpegxr’ format. This problem has been fixed.
Matching
Measure
Memory
  • The temporary memory used by the last operator returned by get_system(‘temp_mem’) was inaccurate. This problem has been fixed.
Miscellaneous
  • The operators disp_text and dev_disp_text crashed if a handle was passed for the parameters ‘String’, ‘Row’, or ‘Column’. This problem has been fixed.
  • Setting the parameters ‘width’ or ‘height’ for region clipping purpose in a multi threaded environment might have led to an unpredictable automatic update behavior of these parameter values by image generating operators. This problem has been fixed.
  • The operator get_operator_info could leak memory when attempting to retrieve a slot that is empty for an operator. This problem has been fixed.
  • The operator line_position converted its inputs to integer values prior to calculating its outputs. This problem has been fixed. The operator will now work correctly on floating point input values.
  • 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.
  • The operator optimize_aop crashed if the help files could not be found. This problem has been fixed. Now, optimize_aop will report an error instead.
  • In contrast to the documentation, the operator set_sheet_of_light_param did not accept ‘um’ as alternative to ‘microns’ for the different generic scale and offset parameters. This problem has been fixed. In addition, the operator read_object_model_3d also accepts ‘um’ for the parameter ‘Scale’ now.
  • Using excessively long arguments for set_system or HAccessGlVar may have resulted in buffer overruns. This problem has been fixed. Now, the HALCON error 5141 (“String too long or too high”) will be raised.
  • 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.
  • The undocumented macro TestRegIma() has been removed from the header file HMacro.h.
  • For some error codes no error messages were returned. This problem has been fixed.
  • In rare cases HALCON could deadlock when running out of memory. This problem has been fixed.
Morphology
OCR
  • In rare cases find_text led to a stack overflow for highly textured images. The problem occured for text models of mode ‘manual’ and for parameter settings that created a very large number of candidate regions. This problem has been fixed.
  • In rare cases, the operator find_text and the OCR Assistant caused a low level error about still allocated temporary memory blocks. This problem has been fixed.
  • In manual mode find_text sometimes failed to segment characters in binary images. This problem has been fixed.
  • The operator get_text_object crashed when no value or only an integer or float value was passed to the parameter ‘ResultName’. This problem has been fixed. Note that this change affects the compatibility.
  • When a lexicon file was created in UTF-8 encoding and the file starts with a Unicode marker (some editors like Windows Notepad add it automatically), the first entry of the lexicon file could not be read correctly by the appropriate HALCON operators import_lexicon and do_ocr_word_*. This problem has been fixed.
  • 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
Region
Segmentation
  • auto_threshold crashed for images of type ‘real’ with a constant gray value. 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.
  • Calling get_system for the parameter ‘opengl_info’ returned an error if the DISPLAY environment variable was not set on Linux systems, or when not running in a graphical session on macOS systems. This problem has been fixed. Now, get_system will return ‘No OpenGL support included’ in both cases.
  • In error cases, the operator read_ocr_trainf changed the global variable ‘init_new_image’ to ‘false’. This problem has been fixed.
Tuple
  • tuple_regexp_match, tuple_regexp_replace, tuple_regexp_select, and tuple_regexp_test did not support empty matches. This problem has been fixed. Now, tuple_regex_test(”, ‘^$’, NumMatches) will be a match. Note that this change affects the compatibility.
  • The semantic type of some handles as reported by tuple_sem_type and tuple_sem_type_elem were inconsistent with the semantic type defined in the operator arguments that use those handles. This problem has been fixed. In particular, now the following semantic types are used consistently:
    • ‘surface_matching_result’ (previously also ‘surface_result’)
    • ‘deformable_surface_matching_result’ (previously also ‘surface_result_deformable’)
    • ‘sheet_of_light_model’ (previously also ‘sheet_of_light’)
    • ‘dl_classifier_train_result’ (previously also ‘dl_classifier_training_result’)  Note that this change affects the compatibility.
  • The error codes of the operators tuple_str_first_n and tuple_str_last_n were wrong. When the Position parameter was lower than 0 or greater than the string length, these operators returned the error 1301 (“Wrong value of control parameter 1”). This problem has been fixed. Now, in case of an invalid Position parameter these operators return the error 1302 (“Wrong value of control parameter 2”).
XLD

String Encoding

HALCON’s string encoding is now based on UTF-8. The following adaptions have been made:

  • The HALCON operators that handle regular expressions, namely tuple_regexp_match, tuple_regexp_replace, tuple_regexp_select, and tuple_regexp_test as well as the OCR operators do_ocr_word_cnn, do_ocr_word_knn, do_ocr_word_mlp, and do_ocr_word_svm are now able to match arbitrary Unicode characters like German Umlauts and Japanese characters. This includes the correct counting of characters as well as the correct interpretation of character classes like spaces (\s), letters or digits (\w), lower and upper case letters ([:lower:], [:upper:], option ‘ignore_case’), and word boundaries. In addition, in tuple_regexp_replace a problem with regular expressions with ‘^’ (start of string) and the ‘replace_all’ option has been fixed.
  • The HALCON/C interface has been improved to support the handling of strings with a defined encoding in C applications that use HALCON. The default encoding that is used by the HALCON/C interface is UTF-8 now. For applications using strings with the locale encoding, the interface can be changed by calling the function SetHcInterfaceStringEncodingIsUtf8(false) at the beginning of the program. In addition, the HALCON/C interface now provides functions for passing and receiving strings with a defined encoding when working with Htuple, independently on the global interface encoding. Under Windows this includes also functions for passing and receiving wide character strings (wchar_t*). Note that this change affects the compatibility.
  • The HALCON/C++ interface has been improved to ease the integration of HALCON into Unicode aware C++ applications. Character pointers in HTuple and HString as well as strings returned by HALCON operators are encoded in UTF-8 and will be transcoded to the internal string encoding of the HALCON library when necessary. Furthermore, under Windows support for wide characters has been added. It is now possible to initialize an HTuple, HTupleElement and HString with wchar_t*-string. Operators except wide character strings as input. HString has been extended by HString::TextW() and HString::LengthW(), providing access to a wide character representation of the string and its length. When UNICODE is defined, HString::Text() and HString::Length() will refer to these wide character variants, otherwise to HString::TextA() and HString::LengthA(), the character variants in interface encoding. Wide character strings internally are transcoded to the interface encoding. For applications using strings with locale encoding, it is possible to switch the HALCON/C++ interface encoding to the locale string encoding by calling HalconCpp::SetHcppInterfaceStringEncodingIsUtf8(false) at the beginning of the program. For each HALCON operator call, the HALCON/C++ interface will transcode all strings to the HALCON internal encoding (default UTF-8). To ease the compatibility with other C++ code, the HString class has been extended by the methods HString::FromUtf8, HString::ToUtf8, HString::FromLocal8Bit and HString::ToLocal8Bit to convert strings independently of the HALCON/C++ interface encoding. Note that this change affects the compatibility.
  • The operators tuple_split, tuple_str_bit_select, tuple_str_first_n, tuple_str_last_n, tuple_strchr, tuple_strlen, tuple_strrchr, tuple_strrstr, tuple_strstr and tuple_substr now support Unicode code points. All positions reference Unicode code points. Unicode code points may consist of more than one byte in the UTF-8 string. If positions should reference raw bytes, these operators may be switched to a byte mode with the thread specific setting set_system(‘tsp_tuple_string_operator_mode’, ‘byte’). Note that this change affects the compatibility.
  • HDevelop has been adapted to support the new UTF-8 handling in HALCON. Some changed behavior is implicit due to the changed behavior of the HALCON library. In particular the default setting for ‘filename_encoding’ is now ‘utf8’, and string operations in the HDevelop language inherit UTF-8 aware behavior from the improved HALCON operators. For example the expression s{i} will now correctly return the character at position i as documented instead of byte i of the encoded representation as previously. Similarly, ord and chr functions will convert between string representations and Unicode code points. For pure ASCII strings the behavior is backward compatible. Also for legacy purposes it is still possible to revert to the ‘locale’ setting.
    In addition, the word processing functionality in the OCR assistant has been fixed to properly handle corrections for non-ASCII text.
  • The operators tuple_ord, tuple_ords, tuple_chr, and tuple_chrt have been improved. In older HALCON versions these operators were based on the byte representation of characters and strings. That was accompanied by the following disadvantage: first, the result of the operations depended on the current encoding (‘locale’ vs. ‘utf8’) and the system (Windows, Linux, macOS X), and second, the operators tuple_ord and tuple_chr could not be called with multi byte characters. These restrictions have been resolved: When the encoding used by the HALCON library is UTF-8 (which is the default now) these operators are based on Unicode characters and return or accept Unicode code points. This allows to call tuple_ord also on Asian letters or German Umlauts and to get the same result on all systems. If the actual byte representation of a UTF-8-string is needed, the behavior can be changed with the new set_system option ‘tuple_string_operator_mode’ which can be set to ‘byte’. When the HALCON library encoding was set to the legacy mode ‘locale’ the operators behave as in older HALCON versions. There is a new example program hdevelop/Tuple/String-Operations/tuple_ord_chr.hdev. It demonstrates the usage of these operators with arbitrary Unicode code points. Note that this change affects the compatibility.
  • HDevEngine has been adapted to the improved handling of string encoding in HALCON. For HDevEngine/C++ the expected encoding for const char* parameters is now the explicitely specified HALCON/C++ interface encoding (default is UTF-8). This also holds when creating or accessing HTuple instances, e.g., for passing parameters to procedures. In addition, members with const char* parameters that represent path or file names have been extended with a const wchar_t* signature variant under Windows. Those always accept the standard UTF-16 encoding for UNICODE applications. For HDevEngine/.NET this change is transparent to the user and everything will work as before. A problem in HDevProcedure.ShortDescription was fixed and this property will now also correctly represent non-ASCII characters in the short description. Note that this change affects the compatibility.
  • The operator open_file now supports setting the string encoding. Three modes are supported: ‘utf8_encoding’, ‘locale_encoding’ and ‘ignore_encoding’. If the encoding is not explicitly set to be ignored, the string encoding is used by all operators that read or write text files (fread_char, fread_line, fread_string and fwrite_string). These operators are now able to handle multi-byte characters as well as special encoding-dependent characters like Unicode white spaces and line breaks. Furthermore, the strings are now correctly transcoded between the internal encoding of the HALCON library and the file encoding if the encodings differ. Note that this change affects the compatibility.
  • The operators send_tuple, receive_tuple, send_data, and receive_data now use UTF-8 by default to encode strings. Note that this change affects the compatibility.
  • Lexicon files can be used to provide a predefined set of words, e.g., for looking them up in conjunction with OCR operators. From now on, these lexicon files have to be encoded in UTF-8 if they contain non-ASCII characters. Old lexicon files with non-ASCII characters that were encoded with the local-8-bit encoding are still supported and will automatically be detected and converted to UTF-8, as long as they do not contain only strings that accidentally are all also valid UTF-8.
    The operator suggest_lexicon can be used to suggest for an arbitrary word that entry of the lexicon that can be obtained with the minimum number of edit operations applied on the input word. Until now, this operation depended on the encoding because it counted the number of bytes to change. From now on it is based on the actual characters so the results will meet one’s expectations better.
    Note that this change affects the compatibility.
  • Sequence files used by the HALCON virtual image acquisition (i.e., file) interface have to be encoded in UTF-8 from now on. Old sequence files, which use the local-8-bit encoding and do not accidentally yield a valid UTF-8 string, are still supported and will automatically be detected.
  • The operators serialize_tuple and deserialize_tuple now use UTF-8 by default to encode strings. Note that this change affects the compatibility.
  • The default encoding which is used for representing strings with non-ASCII characters within the HALCON library was changed to UTF-8. This allows to represent arbitrary characters in a unique way on all systems independent of the system and the current locale. The locale encoding is still supported as legacy mode for running old programs. This mode can be achieved viaset_system(‘filename_encoding’, ‘locale’) or by setting the environment variable HALCON_ENCODING to LOCALE. Applications that use the HALCON/C or HALCON/C++ interface for calling HALCON operators can also set the encoding of the interface independently of the HALCON encoding. Note that this change affects the compatibility.
  • Programmers who want to extend HALCON by their own operator set via the ‘HALCON Extension Package Interface’ have to respect that the def-files which are used to define the operators and to describe their functionality are expected to be UTF-8 encoded from now on for all supported languages, not only for Japanese as before. Note that this change affects the compatibility.
  • For HDevelop programs that are exported to one of the programming languages C, C++, C#, or VisualBasic .NET via the HDevelop command line option -convert, the default encoding of string constants in the output source files was changed to UTF-8. This can be set back to locale encoding by the new command line option -encoding native, which can only be used in conjunction with the -convert option. In order to avoid problems with some C and C++ compilers, in the exported C and C++ files the non-ASCII characters in string constants are represented by octal code sequences. Furthermore, when an HDevelop program is exported in native (locale) encoding to a C or C++ program, the HALCON/C or C++ interface encoding is set accordingly at the begin of the generated program. Note that this change affects the compatibility.

Procedures

Functionality

  • To calculate the dimensions of a calibration object for a sheet-of-light-calibration, the new procedure get_sheet_of_light_calib_object_dimensions has been added.  A technical drawing within the reference manual entry of create_sheet_of_light_calib_object shows the dimensions of the calibration object.
  • The usability of the procedure list_image_files has been improved. Now, it is possible to use a tuple of multiple image directories as input.
  • The usability of the procedures plot_tuple and plot_funct_1d has been improved. It is now possible to visualize plots using the ‘step’-style. Additionally, the format of the values displayed next to the axis can be adapted, using the new parameters ‘format_x’ and ‘format_y’.
    The parameters ‘origin_x’ and ‘origin_y’ have been renamed to ‘axis_location_y’ and ‘axis_location_x’, respectively. Additionally, it is now possible to pass convenience strings for ‘axis_location_y’ and ‘axis_location_x’: ‘left’, ‘right’, ‘origin’, ‘bottom’, ‘top’, and ‘origin’.
  • HALCON has been extended with the procedure remove_dir_recursively to remove a directory recursively.
  • The usability of the procedure inspect_object_model_3d and the operator create_shape_model_3d has been improved. Now, it is mentioned that the coordinate system of the model may differ from the CAD origin.
  • The procedure visualize_object_model_3d no longer throws an exception when passing an empty 3D object model for visualization.
  • The standard procedures in HALCON contained the procedure determine_optimum_pose_distance twice, in different libraries. This problem has been fixed. The duplicate was removed and the procedure now exists only in the library visualize_object_model_3d.hdpl.

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.
  • The procedure reference entry of list_image_files mentioned a wrong path to an environment variable. This problem has been fixed.
  • The procedures disp_object_model_no_opengl, color_string_to_rgb, disp_object_model_3d_safe, disp_text_button, gen_arrow_object_model_3d, get_object_models_center, and tuple_vector_cross_product were delivered as public and as private procedures. This problem has been fixed. Now, they are only delivered as public procedures.

HALCON/C

Bug Fixes

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.

Bug Fixes

  • In HALCON/CPP and HALCON/.NET, the member function GetGrayval of the HImage class returned only the gray value of the first image channel when using the signature variant with native input types for the coordinates. This problem has been fixed. To solve the problem, the type of the return value for this member function has been changed to HTuple. For HALCON/C, the operator variant with the tuple signature is the only available anymore. Note that this change affects the compatibility.
  • The behavior for vector remove function has been changed in the language interfaces C# and C++. Deleting with an index greater than the tuple size caused an error. This problem has been fixed.

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.
  • The HSmartWindowControlWPF has been extended to fully support Data Binding. To achieve this, additional properties have been added to the HSmartWindowControl to set the drawing options. In addition, HIconicDispayObjectWPF and HMessageDisplayObjectWPF objects can be added as items to the HSmartWindowControlWPF. These new objects also support Data Binding.
  • The performance of tuple_concat when using the HALCON/.NET language interface has been improved in some common cases.

Bug Fixes

  • In HALCON/CPP and HALCON/.NET, the member function GetGrayval of the HImage class returned only the gray value of the first image channel when using the signature variant with native input types for the coordinates. This problem has been fixed. To solve the problem, the type of the return value for this member function has been changed to HTuple. For HALCON/C, the operator variant with the tuple signature is the only available anymore. Note that this change affects the compatibility.
  • There were several problems with HSmartWindowControlWPF and/or HWindowControlWPF:
    • The returned value of HalconDotNet.HMouseEventArgsWPF.Button in HMouseMove event in HSmartWindowControlWPF and HWindowControlWPF was always Left. This problem has been fixed. Now, the pressed button is returned. Notice that in case of multiple buttons pressed, only one value can be returned. If no button is pressed, null is returned.
    • The returned value of HalconDotNet.HMouseEventArgsWPF.Delta in HMouseWheel event in HSmartWindowControlWPF was always 0.
    • In HWindowControlWPF, the Middle, XButton1 and XButton2 buttons change state was not detected in HMouseUp and HMouseDown.These problems have been fixed. Additionally, the summary information of the mouse events in HSmartWindowControlWPF, HSmartWindowControl, HWindowControlWPF and HWindowControl has been improved.
      Note that this change affects the compatibility.
  • 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.
  • Tuples of a single type were sometimes converted into mixed tuples leading to unexpected results from the tuple_is_string and tuple_is_int operators. This problem has been fixed.
  • The behavior for vector remove function has been changed in the language interfaces C# and C++. Deleting with an index greater than the tuple size caused an error. This problem has been fixed.
  • If HIOCancelDraw was called before calling a drawing operator, the drawing operator aborted immediately. This problem has been fixed.
  • The HSmartWindowControl was overwriting the property HImagePart when the internal HALCON window was created. This problem has been fixed.

Language Interface Example Programs

Functionality

  • The exported armv7a C and C++ examples have been updated.

Bug Fixes

  • The operatorswere erroneously added as static class member function in the C++ and C# language interfaces. 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.
  • In the header file HDevEngineCpp.h for using the HDevEngine two comments were marked with TODO. This problem has been fixed.
  • The C# DrawingObjectsWPF example did not work correctly when using handles. This problem has been fixed.
  • The operator set_drawing_object_params only accepted integer values for the generic parameter ‘line_width’. This problem has been fixed. Now, also floating point numbers are accepted. In this case the number is rounded to the nearest integer.

HALCON Variable Inspect

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.

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.
  • Reading the memory in HALCON Vaiable Inspect Visual Studio extension failed in some cases. This problem has been fixed.
  • 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

  • Messages previously allowed only certain strings as keys. This restriction has been lifted. Messages now allow integers and arbitrary strings as keys.

Image Acquisition Interfaces

The latest information about new interface revisions and newly supported image acquisition devices can be found on MVTec’s web server. Please refer to the release notes within the documentation of the individual image acquisition interfaces for information about improvements, bugfixes, or whether a new revision of the corresponding device driver is required.

New Image Acquisition Interfaces

  • The USB3Vision image acquisition interface is now also available for Arm-based platforms.

Miscellaneous

  • The handling of events in the GenICamTL, GigEVision2 and USB3Vision interfaces has been extended. It is now possible to register a message queue for GenICam events like DeviceLost. Furthermore, subscriptions to nodes with the OPC_UA interface now support registering a message queue that receives notifications when the node value changes.
  • HALCON has been extended by the new error code H_ERR_COMPONENT_NOT_INSTALLED, which is returned by the operators open_framegrabber, info_framegrabber, open_io_device, and query_io_interface if an image acquisition or digital I/O interface can not be loaded because it was not installed. Note that this change affects the compatibility.
  • GenApi has been updated to version 3.1.0, which is required by the GenICamTL, GigEVision2, and USB3Vision image acquisition interfaces.
  • Opening and closing multiple framegrabbers using the same image acquisition interface could lead to crashes. This problem has been fixed.
  • The operator open_framegrabber crashed with strings longer than 1024 characters as input control data. This problem has been fixed. Now, an error is returned.
  • When a sequence file, which collects images for the HALCON Virtual File interface, was created in UTF-8 encoding and the file starts with a Unicode marker (some editors like Windows Notepad add it automatically), the first entry of the sequence file could not be read correctly by the operator grab_image. This problem has been fixed.
  • In the template to create an image acquisition interface (%HALCONEXAMPLES%\ia_integration), the value of ‘HGInitNewImage’ was modified via ‘HWriteSysComInfo’ before calling ‘HNewImage’. In case of failure, its value was not always properly restored. This problem has been fixed. Moreover, the third argument of ‘HReadSysComInfo’ was of type *HINT instead of the expected type *HBOOL. This could lead to potential access to uninitialized memory. This problem has been fixed.

Image Acquisition Example Programs

  • The following HDevelop example programs used old handle names, display settings, or acquisition interfaces:
    • hdevelop/Identification/Data-Code/calibration_aimdpm_1_2006.hdev,
    • hdevelop/Identification/Data-Code/print_quality_aimdpm_1_2006.hdev,
    • hdevelop/Matching/Component-Based/cbm_param_visual.hdev, and
    • hdevelop/Matching/Component-Based/cbm_sbm.hdev.
    This problem has been fixed.
  • The following image acquisition example programs have been renamed so that the name is consistent with other examples:
    • genicamtl_gocator_objectmodel3d.hdev -> genicamtl_lmi_gocator_objectmodel3d.hdev
    • genicamtl_areascan3d_objectmodel3d.hdev -> genicamtl_vrmagic_areascan3d_objectmodel3d.hdev
    • gigevision2_atc4_objectmodel3d.hdev -> gigevision2_automation_technology_c4_objectmodel3d.hdev

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. Please refer to the release notes within the documentation of the individual digital I/O interfaces for information about improvements, bugfixes, or whether a new revision of the corresponding device driver is required.

New Digital I/O Interfaces

  • The OPC_UA interface is now also available for the Arm-based platforms armv7a and aarch64.
  • HALCON now provides the new Hilscher-cifX interface which in combination with hardware using Hilscher communication chips supports communication with PLCs. In particular, you can now communicate with a PLC directly from HALCON via real-time ethernet and fieldbus protocols when using this new interface.

Miscellaneous

  • The handling of events in the GenICamTL, GigEVision2 and USB3Vision interfaces has been extended. It is now possible to register a message queue for GenICam events like DeviceLost. Furthermore, subscriptions to nodes with the OPC_UA interface now support registering a message queue that receives notifications when the node value changes.
  • HALCON has been extended by the new error code H_ERR_COMPONENT_NOT_INSTALLED, which is returned by the operators open_framegrabber, info_framegrabber, open_io_device, and query_io_interface if an image acquisition or digital I/O interface can not be loaded because it was not installed. Note that this change affects the compatibility.
  • HALCON did not unload an I/O interface after the last device using it is closed. This problem has been fixed.
  • The operator get_io_channel_param always returned an empty tuple for the parameter GenParamValue for any digital I/O interface. Note that this problem has already been fixed in HALCON 18.05.0.1.
  • Opening an I/O device leaked a small amount of memory. This problem has been fixed.
  • The OPC_Classic interface is no longer part of the standard HALCON installation. However, it is still available for download.

HALCON for Embedded Vision

Functionality

  • HALCON is now also available for 64-bit Arm-based platforms.  I.e., the Linux installer, which can be downloaded as usual from the MVTec website, has been extended by the option to additionally install the components necessary for 64-bit Arm-based platforms. These components include:
    • HALCON libraries including HDevEngine,
    • two example programs for C++ and HDevEngine,
    • image acquisition interfaces (Video4Linux2, File, GenICamTL, GigEVision, USB3Vision),
    • the I/O interface OPC_UA, and
    • a tar-file for the installation of the runtime files on a 64-bit Arm-based platform.
    Additionally, hbench has been extended by a new reference CPU, which is an Arm Cortex-A57.
  • On Arm-based platforms, available compute devices may use OpenCL now.

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 usability of the document third_party_copyrights.html has been improved. Now, for every third party library, the components of HALCON that use it are mentioned.
  • All HALCON PDF manuals have been adapted to uniformly match the paper format DIN A4.
  • 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

  • The Extension Package Programmer’s Manual now includes instructions on how to use the HANDLE_PAR data type in tuples.
  • 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.
  • In the Programmers Guide, chapter 5.2.5 ‘The Tuple Mode’, in the 2nd code block, ‘ToString()’ was missing. This problem has been fixed.
  • The Programmer’s Guide did not clearly mention the procedure call clean up in case of an exception. This problem has been fixed.

Reference Manual

  • The reference manual entry of binary_threshold falsely listed ‘real’ as possible value for the image type of the input image. This problem has been fixed.
  • The reference manual entry of calibrate_cameras now documents the default units of camera parameters.
  • The reference manual entry of create_planar_uncalib_deformable_model_xld incorrectly described that the parameters ScaleCMin and ScaleRMin are not used by the operator. This problem has been fixed.
  • 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.
  • For create_surface_model and find_surface_model, the reference manual did not mention that the normal vectors need to point inwards when ‘train_3d_edges’ is enabled. This problem has been fixed.
  • The reference manual entries of do_ocr_word_cnn, do_ocr_word_knn, do_ocr_word_mlp and do_ocr_word_svm have been extended. They now describe how the score parameter is calculated.
  • The operators draw_nurbs, draw_nurbs_mod, draw_nurbs_interp, draw_nurbs_interp_mod, drag_region1, drag_region2, and drag_region3 do not work in HDevelop graphics windows. The corresponding warning messages in the operator reference have been updated accordingly.
  • 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 generic parameters ‘pose_ref_dist_threshold_edges_rel’, ‘pose_ref_dist_threshold_edges_abs’, ‘pose_ref_scoring_dist_edges_rel’, and ‘pose_ref_scoring_dist_edges_abs’ of the operators find_surface_model and find_surface_model_image were not documented. This problem has been fixed. Note that the parameters are also supported, even if not documented, by previous versions of HALCON that support edge-supported surface-based matching.
  • Within the chapter Calibration / Calibration Object of the reference manual, the list of suggested calibration plates for the parameter ‘CalPlateDescr’ was outdated. This problem has been fixed.
  • In the reference manual, it was not documented that the parameter ‘MinContrast’ influences the automatic contrast estimation of the parameter ‘Contrast’ when creating a model for shape-based, component-based, or deformable matching. This problem has been fixed.
  • The legacy status for the Wiener filter has been removed from the Reference Manual.
  • The description of the camera poses has been improved. Now, for the pose parameters of frequently used operators the direction of the transformation is mentioned.
  • The reference manual entries of gen_image1, gen_image1_extern, gen_image1_rect, gen_image3, gen_image3_extern, and gen_image_interleaved now include a warning, stating that a crash may occur for invalid pointer values.
  • The reference manual entry of get_bar_code_result did not mention the quality grade ‘-1’. Furthermore, the reference manual entry of get_bar_code_object contained a misleading statement. These problems have been fixed.
  • The documentation of the parameter ‘quality_isoiec15416_values’ (get_bar_code_result) stated ‘N/A’ as value for ‘Overall Quality’, ‘Overall Quality Linear’ and ‘Overall Quality Composite’, although floating grades are returned. This problem has beed fixed.
  • The reference manual entries of get_contour_attrib_xld and get_contour_global_attrib_xld have been improved to better describe the set of possible contour parameters.
  • The operator reference of get_data_code_2d_results was inconsistent for the parameters ‘mirrored’ and ‘structured_append’. This problem has been fixed.
  • The documentation of the operator get_object_model_3d_params has been improved. Now, the option ‘extended_attribute_types’ for extended parameters is documented.
  • 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 entry of get_support_vector_class_svm contained misleading phrases concerning the parameter ‘IndexSupportVectors’. This problem has been fixed.
  • The reference manual entry of get_support_vector_class_svm falsely stated that an array was allowed as input for the parameter ‘IndexSupportVector’. This problem has been fixed.
  • 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.
  • For the operator open_socket_accept the GenericParameter option ‘reuseaddr’ was not documented. This problem has been fixed.
  • The reference manual entry of send_data mentioned zeros instead of NULL-Bytes. This problem has been fixed.
  • The documentation of the operator set_bar_code_param was formulated over-simplified which led to a wrong description for the result value concerning the removal of the check character. This problem has been fixed.
  • The example snippet within the reference manual entry of set_fuzzy_measure transformed a function and then used the original function instead of the transformed one. 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.
  • 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 vector_to_pose has been improved. In particular, it has been extended with references to the publications the implementations of the methods are based on.
  • Within the reference manual, the introduction of the chapter Filters / Smoothing has been extended with information regarding the differences between the different smoothing filter operations.
  • Within the reference manual, the introduction of the chapter 3D Reconstruction / Multi-View Stereo has been extended with general information related to the workflow when reconstructing 3D surfaces and points.
  • Within the reference manual, the introduction of the chapter Region / Morphology has been extended with more detailed descriptions regarding region morphology operations.
  • The introduction of the chapter Transformations/2D Transformations has been extended with information regarding the different 2D coordinate systems used in HALCON.
  • The introduction of the chapter Camera Calibration / Multi-View has been extended with more detailed descriptions regarding the calibration process of different camera setups.
  • For several operators, the semantic type definitions have been specified more precisely.
  • The reference manual had several operators where the warning or attention block was missing. This problem has been fixed.

Release Documents

  • In the documentation, the ‘Third-party Copyrights’ now contain information about the version of the used third-party libraries.

Solution Guides

  • The Solution Guide on Image Acquisition still listed the OpenNI interface as supported interface although the support ended with HALCON 13.0. This problem has been fixed.
  • In the Solution Guide on 3D Vision the equation for the polynomial model of tilt lenses was erroneous. This problem has been fixed.

User Guides

  • 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.
  • Some example paths within the user manuals referred to %HALCONROOT% instead of %HALCONEXAMPLES%. This problem has been fixed.
  • Within the PDF version of the HDevelop User’s Guide a link to the Programmer’s Guide did not work. This problem has been fixed.
  • The HDevelop User’s Guide falsely stated that within the Help Window PDFs could be opened in an external viewer using the Return key. This problem has been fixed.
  • Table 8.6 in the HDevelop User’s Guide was numerated erroneous in the pdf-file. This problem has been fixed.

Installation

  • On Linux systems, the HALCON shared libraries now encode the HALCON version number in the shared libraries’ SONAME.
  • The usability of the HALCON Windows installer has been improved. Now, the examples are always installed to the user documents folder path.
  • The images used by the HDevelop example programs for deep learning require a lot of memory space. Therefore, they are provided in a separate installer that can be downloaded from the MVTec HALCON download area.
  • The usability of starting HDevelop for different HALCON versions and platform versions has been improved for Windows. In previous HALCON versions, the environment variable %HALCONROOT% and/or %HALCONARCH% had to be adapted accordingly. Now, the Windows batch files
    • start_hdevelop_x64.bat
    • start_hdevelopxl_x64.bat
    • start_hdevelop_x86sse2.bat
    • start_hdevelopxl_x86sse2.batare installed to the HALCON root directory. A double-click on one of these batch files starts the respective HDevelop (platform) version. Furthermore, HDevelop program files can be dragged on the batch files to open them with the respective HDevelop (platform) version.
  • Several proprietary image acquisition and digital I/O interfaces are no longer part of the standard HALCON installation. These interfaces can be obtained online on the MVTec image acquisition interfaces page. The reference manual has been adapted accordingly and the Solution Guides have been revised so that code examples no longer use any proprietary image acquisition or digital I/O interfaces.
  • 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.
  • The deep learning classifiers have been moved from the main installer to the separate installer (Windows) / tarball (Linux) for deep learning. See the Installation Guide for more details.
  • Under Linux it is no longer necessary to manually install the cuBLAS and the cuDNN libraries. These are included in the Linux tarball for deep learning.
  • The link to the HALCON Uninstaller has been removed from the Windows Start Menu.

Licensing

  • The new license modules “Deep Learning Training” and “Deep Learning Inference” have been introduced for licensing the training and inference operators of the deep learning functionality.
  • The Installation Guide has been extended by an explanation to check for a genuine halcon.dll. If you encounter an unexpected behavior of HALCON, please make sure to use a genuine halcon.dll.
  • 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.
  • On macOS systems without any HID devices attached, HALCON would crash during initialization.This problem has been fixed.
  • HALCON has been extended with an operator get_system_info that can be used to query a subset of the parameters supported by get_system without requiring a valid HALCON license. Note that this change affects the compatibility.

Miscellaneous

  • The semantic type of a background estimator as returned by tuple_sem_type has been changed from ‘bg_esti’ to ‘bg_estimation’.
  • The HDevelop example hdevelop/3D-Object-Model/Segmentation/measure_plant.hdev has been added. With this example we demonstrate how you can segment and measure different parts of a plant.
  • 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.