Release Notes for HALCON 17.12 Progress

• HALCON 17.12 Progress is a complete new HALCON Edition. Thus, HALCON Progress licenses are not compatible with HALCON 13 and previous HALCON versions. More information.

• For find_text, do_ocr_single_class_cnn, and do_ocr_multi_class_cnn the implementation of the CNN-based OCR classifier has been improved. This can lead to slightly different results in the achieved confidences. More information.
• The parameters
  • 'module_gap_col',
  • 'module_gap_col_min',
  • 'module_gap_col_max',
  • 'module_gap_row',
  • 'module_gap_row_min', and
  • 'module_gap_row_max'
  of set_data_code_2d_param and get_data_code_2d_param have been removed. Use 'module_gap_min' instead of 'module_gap_col_min'. Furthermore, use 'module_gap_row_min' and 'module_gap_max' instead of 'module_col_max' and 'module_row_max'.
• set_stereo_model_param returned the error 1303 ("Wrong value of control parameter 3"), if GenParamName was set to 'surface_tolerance' and GenParamValue exceeded the value of 'min_thickness' stored in StereoModelID. set_stereo_model_param now returns the error 9544 ("The minimum thickness is smaller than the surface tolerance").
• Note that the following undocumented but public functions for setting callbacks were removed. Applications must now use the new callback functionality within set_system instead.
  • HSetCallbackOCRClassMLP
  • HSetCallbackClassMLP
  • HSetCallbackOCRClassSVM
  • HSetCallbackClassSVM
  • HSetCallbackClassGMM
  • HSetCallbackTriang3D
  • HSetCallbackFeatSel
  • HSetCallbackDistXLD
  • HSetCallbackTrainTexture
  • HSetCallbackCalibSOL
  • HSetCallbackMultiView
  More information.
• tuple_regexp_match, tuple_regexp_replace, tuple_regexp_select, and tuple_regexp_test now support empty matches. Regular expressions such as '.*' or '^$' now match on an empty string. To avoid empty matches, the regular expression has to be adapted, e.g., by using '.+' instead of '.*'. More information.

• The MVTec GigE Vision Streaming Filter version 2.1.8.0 that is part of the Windows version of the new GigEVision2 interface is only compatible with revision 13.0.3 and higher of the old GigEVision interface. If both, GigEVision2 and GigEVision, interfaces should be used on the same PC you need to make sure to update to this GigEVision revision to ensure compatibility.
• Acquisition and Digital I/O interfaces listed in the reference documentation of open_framegrabber and open_io_device will return the error code H_ERR_COMPONENT_NOT_INSTALLED instead of H_ERR_DLOPEN when loading of the interfaces fails. More information.

IDE

Procedures

Code Export

Miscellaneous

GUI

IDE

HDevelop Language

Procedures

Miscellaneous

New, Improved, or Deleted HDevelop Example Programs

Bug Fixes

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

• 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.
• HDevEngine crashed due to invalid memory access when sharing one HDevProcedure across multiple threads, where the HDevProcCalls get created and destroyed inside the respective thread worker functions. This problem has been fixed.
• Creating and destroying HDevProgram instances could have led to unresolved lines in loaded external procedures and thus to potential errors when loading further programs. This problem has been fixed.
• convert_vector_to_tuple raised an exception with JIT compilation when the input was an empty vector. This problem has been fixed. Now, an empty tuple is returned like in the non-JIT-compiled case.

• When passing empty tuples as input parameters to procedures via HDevEngine/.NET, it was possible for tuple data to become corrupted or even for the application to crash. Note that this problem has already been fixed in HALCON 13.0.1.1.

• 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 Type	Image Size	Filter Size	Available Instruction Set	Speedup
  byte	1600x1200	3x3	AVX2	up to 35%
  byte	1600x1200	5x5	AVX2	up to 35%
  byte	1600x1200	7x7	AVX2	up to 25%
  byte	1600x1200	11x11	AVX2	up to 30%
  byte	1600x1200	21x21	AVX2	up to 35%
  byte	1600x1200	3x1/1x3	AVX2	up to 55%
  byte	1600x1200	5x1/1x5	AVX2	up to 40%
  byte	1600x1200	7x1/1x7	AVX2	up to 25%
  byte	1600x1200	11x1/1x11	AVX2	up to 40%
  byte	1600x1200	21x1/1x21	AVX2	up to 50%

  Image Type	Image Size	Filter Size	Available Instruction Set	Speedup
  uint2	800x600	3x3	AVX2	up to 30%
  uint2	800x600	5x5	AVX2	up to 30%
  uint2	800x600	7x7	AVX2	up to 40%
  uint2	800x600	11x11	AVX2	up to 40%
  uint2	800x600	21x21	AVX2	up to 45%
  uint2	800x600	3x1/1x3	AVX2	up to 80%
  uint2	800x600	5x1/1x5	AVX2	up to 90%
  uint2	800x600	7x1/1x7	AVX2	up to 105%
  uint2	800x600	11x1/1x11	AVX2	up to 115%
  uint2	800x600	21x1/1x21	AVX2	up to 120%

  
  
• find_text now uses an improved parallelization on internal data level, which results in a speedup of up to 50% on a quad core machine with hyperthreading.
• The operators for
  • shape-based matching,
  • shape-based 3D matching,
  • deformable matching, and
  • NCC-based matching
  are now faster when processing a very large number of results.
• mean_image using a 3x3 filter mask is now faster for uint2 images. In particular, the following speedups can be expected:
  

  Image Type	Image Size	Available Instruction Set	Speedup
  uint2	800x600	AVX2	up to 280%
  uint2	1024x768	AVX2	up to 315%
  uint2	1200x960	AVX2	up to 345%
  uint2	1600x1200	AVX2	up to 170%

  
  
• median_image is now faster for byte and uint2 images, filters of size 3x3 and 5x5 (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 3x3 and 5x5.
  rank_rect is now faster for byte and uint2 images and filters of size 3x3 (rank 5) and 5x5 (rank 13).
  In particular the following speedups can be expected for median_image for a 1600x1200 image. Similar values can also be expected for median_rect and rank_rect. Values in parenthesis apply to a 512x512 image:
  

  Image Type	Filter Size	Instruction Set	Implementation Change	Speedup without Parallelization	Speedup with 8-Thread Parallelization	vs. HALCON 13
  byte	3x3	SSE2	Improved	19%	60%	SSE2
  		AVX2	New	72%	100%	SSE2
  		Non-SIMD	Improved	1030%	770%	Non-SIMD
  		MMX	Removed	n/a	n/a	n/a
  	5x5	SSE2	Improved	22%	60%	SSE2
  		AVX2	New	83%	150%	SSE2
  		Non-SIMD	Improved	380%	310%	Non-SIMD
  		MMX	Removed	n/a	n/a	n/a
  uint2	3x3	SSE2	Improved	-7,5% (12,5%)	15%	SSE2
  		SSE41	New	55%	35%	SSE2
  		AVX2	New	115%	40%	SSE2
  		Non-SIMD	Improved	7770%	6850%	Non-SIMD
  		MMX	Removed	n/a	n/a	n/a
  	5x5	SSE2	Improved	-10,1% (1,3%)	-3,7% (30%)	SSE2
  		SSE41	New	54%	65%	SSE2
  		AVX2	New	149%	165%	SSE2
  		Non-SIMD	Improved	3040%	2710%	Non-SIMD
  		MMX	Removed	n/a	n/a	n/a

  
  
• photometric_stereo and reconstruct_height_field_from_gradient are now faster by up to 95% when constructing the cache for the poisson algorithm or when using the poisson algorithm without cache.
• scale_image_max is now faster for uint2 images. In particular, the following speedups compared to previous HALCON versions can be expected:
  

  Image Type	Image Size	Platform	Speedup
  uint2	2048x1600	Windows	up to 55%
  uint2	1600x1200	Windows	up to 55%
  uint2	1024x768	Windows	up to 25%
  uint2	800x600	Windows	up to 18%
  uint2	2048x1600	Windows	up to 60%
  uint2	1600x1200	Linux	up to 60%
  uint2	1024x768	Linux	up to 25%
  uint2	800x600	Linux	up to 20%
  uint2	2048x1600	MacOsX	up to 25%
  uint2	1600x1200	MacOsX	up to 25%
  uint2	1024x768	MacOsX	up to 33%
  uint2	800x600	MacOsX	up to 15%

  
  

3D

Classification

Feature

Graphics

Inspection

Miscellaneous

OCR

Segmentation

System

Timeout

XLD

3D

Bar Code

Calibration

Classification

Compute Device

Data Code

File

Filter

Graphics

Image

Matching

Miscellaneous

OCR

Parallelization

Region

System

Tuple

XLD

• 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'.
• The HDevelop procedure set_display_font now supports Liberation Fonts.
• HALCON has been extended with the procedure remove_dir_recursively to remove a directory recursively.

• 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. Read more.

• 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. Read more.
• Operators in HALCON/.NET that took an array of tool classes as input parameters (such as HObjectModel3D[] or HShapeModel[]) exhibited a resource leak. This problem has been fixed. Note that HTuple-based signatures via HOperatorSet or types that represent tuple data such as HPose[] were not affected.
• Changing the window size resizes also a displayed image. However, when the HKeepAspectRatio option of the HSmartWindowControl was enabled, the image was not displayed with the correct ratio. This problem has been fixed.
• 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. Read more.
• Accessing multiple elements of HTuple at once by indexing with another HTuple (t1[t2]) was inefficient in HALCON/.NET. This problem has been fixed. For pure integral indexing tuples the performance has been improved.
• In Microsoft Visual Studio 2013 Express, trying to view a Form containing a HSmartWindowControl in the Designer led to an error stating that an attempt was made to load a program with an incorrect format. This problem has been fixed.
• If the HSmartWindowControl was set to an arbitrary position inside the father window, the zooming of iconic data returned with wrong results, because the offset between the upper left corner of the father window and the HSmartWindowControl was not considered. This problem has been fixed.
• In some cases, binding the ActualHeight or ActualWidth properties of the HSmartWindowControlWPF could have led to a null pointer exception. This problem has been fixed.
• Calling an operator with a null input parameter caused a memory leak in HALCON/.NET. This problem has been fixed.

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

• The operators
  • clear_all_metrology_models,
  • clear_all_serialized_items,
  • clear_all_surface_matching_results,
  • clear_all_surface_models, and
  • clear_all_text_results
  were erroneously added as static class member function in the C++ and C# language interfaces. This problem has been fixed.
• The HDevEngine/C++ example error_handling.cpp demonstrates different error states that may occur during the execution of an HDevEngine program. Some parts of the test were skipped owing to a procedure that couldn't be loaded. This problem has been fixed.

• The HALCON Variable Inspect extension for Visual Studio displayed a crash message when it was started without a valid license. This problem has been fixed.
• The HALCON Variable Inspect extension for Visual Studio did not support the inspection of images of type 'cyclic'. This problem has been fixed.
• Microsoft Visual Studio creates temporary variables for return values of method calls. The HALCON Variable Inspect extension for Visual Studio displayed these values. But it was not possible to inspect them and they were not deleted from the list until the scope has changed, even if Visual Studio no longer displayed them. This problem has been fixed. Now, these return value variables are no longer displayed in the locals view.
• During a drag and drop operation to the watch window of the HALCON Variable Inspect extension for Visual Studio, the dropped text was moved instead of copied. This problem has been fixed.

• HALCON has been extended with a new image acquisition interface for GigE Vision devices complying with GigE Vision 1.x or GigE Vision 2.x. It supports the operating systems Windows, Linux, and macOS.

• 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. Read more.

Modified Image Acquisition Example Programs

New Image Acquisition Example Programs

The following HDevelop example programs have been added:

Removed Image Acquisition Example Programs

The following HDevelop example programs have been removed:

• 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. Read more.
• The hioTemplate operator get_io_channel_param started with the index 1 to initialize the 'param_name' values. This problem has been fixed.

• Within include/hlib/HObjectModel3D.h, HOM3DAddPoints, HOM3DAddPointsAndMapping, HOM3DGetPoints, HOM3DAddPointsFromImagesRegion, and HOM3DAddPointsFromImagesInvalid did not document that values of point coordinates are treated as 'mm'. This problem has been fixed.
• 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 Programmer's Guide has been improved to describe the default behavior of the implementation class 'HDevOpMultiWindowImpl'.
• The Programmer's Guide has been improved such that the sections for 'Error Handling' provide links to the list of HALCON error codes.
• The Programmer's Guide has been improved. It now describes how to fit a new image (or other content) to the size of the window control in the source code.
• The Programmer's Guide did not mention that collecting database information is not thread-safe when exchanging iconic objects between threads. This problem has been fixed.
• The Programmer's Guide has been extended by the information that the HDevEngine method LoadProgram changes the working directory if a program is loaded.

• The reference manual entries of the following operators contained imprecise restrictions for the parameter Sigma:
  • bilateral_filter
  • derivate_gauss
  • derivate_vector_field
  These problems have been fixed.
• The warning section of the reference manual entry of clear_all_matrices did not mention that the operator is obsolete, and the attention section of the reference manual entry of clear_all_calib_data was missing. These problems have been fixed.
• The reference manual entries for
  • cluster_model_components,
  • find_component_model,
  • find_local_deformable_model,
  • find_planar_uncalib_deformable_model, and
  • find_shape_model_3d
  have been extended to also describe possible behavior at the border of the image or a reduced domain.
• The reference manual entries of create_caltab and gen_caltab have been improved. They now explain how to calculate the size of the generated calibration plate.
• The German reference manual entry of create_planar_calib_deformable_model contained a wrong parameter description of ScaleCMin. This problem has been fixed.
• 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.
• The reference manual entry of create_sheet_of_light_calib_object has been improved to mention that, if the parameters HeightMin and HeightMax were chosen such that the height difference between the truncated pyramid and the ramp was too small, calibrate_sheet_of_light might not have found the calibration object.
• The reference manual entries of edges_image and edges_color did not contain the information that the hysteresis threshold operation is not applied if NMS is set to 'none'. This problem has been fixed.
• The reference manual entry of enqueue_message mentioned a deep copy behavior which was mistakable. This problem has been fixed.
• The overview pages of the reference manuals for image acquisition and I/O interfaces now include a separate section for systems based on Linux for Armv7-A.
• The reference manual entry of set_hsi contained a wrong formula. This problem has been fixed.
• The description of the set_system parameter 'filename_encoding' was outdated and lacked details. This problem has been fixed.
• In the reference manual entries of update_window_pose and set_camera_setup_cam_param, the multi-threading scope was set to local instead of global. This problem has been fixed.
• Within the reference manual entry of write_ocr_class_knn, the default file extension was documented incorrectly as  '.onc' instead of '.okc'. This problem has been fixed.
• 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 Solution Guide Basics has been improved to mention also the texture inspection model in the chapter 'Texture Analysis'.
• The Solution Guide on 3D Vision has been improved. In particular, the recommendations for acquiring calibration images have been revised.
• The Solution Guide Basics has been improved to describe multi-threading issues for compute devices more clearly.

• The Solution Guide on 3D Vision has been extended with a section about camera calibration using a single image.
  The new HDevelop example program
  • solution_guide/3d_vision/camera_calibration_single_image.hdev
  shows a measurement after a single image calibration and explains the systematic error that occurs when measuring outside the calibrated plane.
• In the HDevelop OCR assistant, when training an OCR Classifier, the training might have taken a very long time if the number of trained characters was very high. The reason for this might have been the Hidden Units parameter, where the auto mode produces a too large value for a large number of characters. The description of this parameter has been adapted accordingly in the HDevelop Users Guide.
• The Installation Guide did not accurately describe how many instances of HALCON can be used in parallel. This problem has been fixed.
• The section Limitations of the User's Guide for HALCON for ARM-based Platforms did not mention that OpenCL is currently not supported. This problem has been fixed.
• The in-line operator notation table within the HDevelop User's Guide has been extended.
• The list of color names in appendix B of the HDevelop User's Guide was incomplete. This problem has been fixed. In addition, the numbering of appendices in the HTML version of the manuals now matches the PDF version.
• The Programmer's Guide has been extended with the information that when working with the HALCON Variable Inspect extension for Visual Studio using an older installation of Visual Studio 2013, it might be necessary to install the .NET 4.6 framework.

• With HALCON 17.12 Progress, the HALCON/COM interface is being discontinued, and thus, the following files have been removed from the Windows installation:
  • bin\x64-win64\halconx.dll
  • bin\x64-win64\halconxxl.dll
  • bin\x64-win64\hdevenginex.dll
  • bin\x64-win64\hdevenginexxl.dll
  • bin\x86sse2-win32\halconx.dll
  • bin\x86sse2-win32\halconxxl.dll
  • bin\x86sse2-win32\hdevenginex.dll
  • bin\x86sse2-win32\hdevenginexxl.dll
  • lib\x64-win64\halconx.lib
  • lib\x64-win64\halconxxl.lib
  • lib\x64-win64\hdevenginex.lib
  • lib\x64-win64\hdevenginexxl.lib
  • lib\x86sse2-win32\halconx.lib
  • lib\x86sse2-win32\halconxxl.lib
  • lib\x86sse2-win32\hdevenginex.lib
  • lib\x86sse2-win32\hdevenginexxl.lib
  Furthermore, the examples
  • examples\cpp\mfc\MatchingCOM and
  • examples\delphi\Matching
  have been removed from the installation and support for building HALCON/COM extension package examples has been removed.
  
  
• The usability of the HALCON Windows installer has been improved. Now, the examples are always installed to the user documents folder path.
• Linux armv7a libraries got installed by mistake during compact and runtime installation. This problem has been fixed.
• 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.bat
  are 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.
• 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 IO integration example and the corresponding documentation were not installed during installations on Linux. This problem has been fixed.

• Licensing has been updated to support the new HALCON Progress Edition. HALCON Progress is licensed in a subscription model. Therefore, the developlment license is always time limited. HALCON Progress licenses are also valid for future versions of HALCON Progress, which will be released during an active subscription term.
  Note that this change affects the compatibility. Read more.
• 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.
• When using dongle licenses and starting HALCON processes simultaneously, some processes might have exited with an license error on macOS platforms. This problem has been fixed.
• HALCON was unable to verify the signature of license files containing unknown modules, flags or platforms, which made the licenses non-forward compatible. This problem has been fixed.