Release Notes for HALCON 18.11 Steady

Furthermore, please note the following compatibility issues related to licenses:

Please note also the following compatibility issues related to image acquisition interfaces:

Note also the following compatibility issues:

• Applications that store handles as numeric values (Hlong) do not work reliably with the new handle mechanism since these "raw" references are not tracked by reference counting and the handle may get destroyed while still in use. Setting the system parameter 'legacy_handle_mode' to 'true' keeps all handles alive until destroyed explicitly and also allows to pass handles as numeric input values to HALCON operators as in previous HALCON versions. Furthermore, there are API extensions due to the new type and some old API members no longer serve any function with the new handle mechanism. This introduces potential source code incompatibilities which can be prevented by compiling with the preprocessor define HCPP_LEGACY_HANDLE_API. Finally, the new reference mechanism cannot unambiguously represent all legacy ownership states. This concerns scenarios where an application managed multiple instances of OOP classes referencing the same handle (via copying or rewrapping of the handle, typically involving explicit 'Detach' and/or 'InvalidateHandle'). In such cases legacy code may need to be adapted to the new mechanism. More information.
• Due to the introduction of the new HTuple element type HHandle some casts that were allowed previously may become ambiguous. In particular, converting a handle from procedural code to a tool class as in new HShapeModel(tuple) now requires to disambiguate the desired constructor with tuple.H (when using new handles) or tuple.IP (when using legacy mode). More information.
• By converting strings consequently into the current locale the behavior of the program may slightly change and unexpected errors may occur, when characters are used in an HDevelop script that are not supported by the current locale. For instance, when using Japanese file names on a Western system with Latin-1 encoding, the file names were scrambled strings but valid Latin-1 byte sequences. Now the Japanese characters in the file names are replaced by '?' which cannot be used within a path. In addition, different Japanese strings can be re-encoded to the same Latin-1 strings when different Japanese characters are all replaced by '?', this may raise errors when these names are used as class names for a classifier. More information.
• Due to a change of the type of the Grayval parameter of the operator get_grayval, the HALCON/C interface does not provide the native type signature variant of this operator anymore, but only the tuple variant. Due to this change, the types of the passed parameters have to be changed to type HTuple and the function call has to be changed to T_get_grayval, respectively. More information.
• The previous parameter 'cmake_cpp' for the command line option '-export_type' has been renamed to 'cmake'. To specify the target language, now the additional option '-language' is available which accepts the values 'cpp' and 'cs'. More information.
• HalconDotNet.HMouseEventArgsWPF.Button is now nullable type, that means it can take null as value. More information.
• To avoid potential problems with memory management, the HDevEngine/C++ operator SetHDevOperatorImpl no longer supports the automatic deletion of passed HDevOperatorImpl objects, and, as a consequence, no longer supports the parameter mem_set_intern. Instead, the application always has to free HDevOperatorImpl objects. HDevEngine/C++ applications, which use SetHDevOperatorImpl, must be adapted accordingly. More information.
• The protection format for HDevelop files has been changed to improve security. Files with the new protection cannot be used with unpatched HALCON versions published before May 2018. If you need to open these files with older HALCON versions, please update these versions using the patches available for download from our webserver https://www.mvtec.com/download/halcon/. More information.
• By introducing the new handle type, the ownership of the handle resources passes from the user to HALCON. This might lead in conventional programming languages like C, C++ classes, or .NET to undefined behavior and crashes when HALCON handles were not held in HALCON data structures like tuples or handle classes, as HALCON will free the handle resources automatically when the last HALCON structure holding a handle reference is destroyed. For these cases, HALCON offers a legacy mode to transfer the ownership of handles to the user code, i.e., handles have to be cleared explicitly again in this mode. Note that HDevelop does not support the legacy mode. The mode can be switched via the 'legacy_handle_mode' parameter of the operator set_system. But the more proper code adaption in case of this problem is to use HALCON data types instead, like HTuple or the specific semantic handle classes. This allows to keep the ownership on behalf of HALCON and to profit of the new HALCON handle resource guarding. The legacy operators clear_all_* that clear all created handles of a specific semantic type are no longer functional and will be removed in future HALCON versions. C++ classes of former HALCON versions used a local reference counting mechanism to support a shallow copy constructor. This behavior is not fully representable by the new handle mechanism, but generally, code that did not use 'Detach' or 'InvalidateHandle' is not concerned. HALCON/C operators with long type signatures for handles run in legacy mode only. For proper use of these operators, please use the tuple type signature instead. HALCON/COM (legacy) only runs in legacy handle mode. HDevEngine applications that provide custom implementations for dev_* operators must take care when storing window handles to keep their ownership separate from the caller: Handles must be stored and returned as independent copies of HTuple or HHandle instances, not as references to existing instances or as numeric values like Hlong or IntPtr. HDevEngine/.NET applications that use stock implementations HDevFixedWindowImplementation and HDevMultiWindowImplementation are not affected. The signature of the drawing object callback type changed to Herror (stdcall *)(Hphandle,Hphandle,char*). Following error codes are inoperable and have been removed: H_ERR_SOL_INVALID_HANDLE, H_ERR_WFID, H_ERR_WSID, H_ERR_FGWH, H_ERR_IOWH, H_ERR_BC_INVALID_HANDLE, H_ERR_BAR_UNKNOWN, H_ERR_WSKEY, H_ERR_WSKEYH_ERR_WSKEY, H_ERR_INVALID_TEXT_RESULT_ID, H_ERR_METROLOGY_MODEL_INVALID. Minor API differences may prevent source code from compiling out of the box in exceptional cases. Please refer to the Programmer's Guide and the new technical note "Technical Updates" to resolve occurring problems. More information.

• The HALCON/C interface assumes strings to be encoded in UTF-8. This must be taken into account when C applications pass strings with non-ASCII characters to HALCON via the HALCON/C interface.  With SetHcInterfaceStringEncodingIsUtf8(false) at the beginning of the application, the HALCON/C interface can be switched to use the string encoding of the current locale. More information.
• The HALCON/C++ interface assumes strings to be encoded in UTF-8. This must be taken into account when C++ applications pass strings with non-ASCII characters to HALCON via the HALCON/C++ interface. With HalconCpp::SetHcppInterfaceStringEncodingIsUtf8(false) at the beginning of the application, the HALCON/C++ interface can be switched to use the string encoding of the current locale. More information.
• The operators tuple_split, tuple_str_bit_select, tuple_str_first_n, tuple_str_last_n, tuple_strchr, tuple_strlen, tuple_strrchr, tuple_strrstr, tuple_strstr and tuple_substr now operate on Unicode code points. If indices should reference raw bytes, use set_system('tsp_tuple_string_operator_mode', 'byte') to switch these operators to byte mode. More information.
• The behavior of the operators tuple_ord, tuple_ords, tuple_chr, and tuple_chrt has changed so that they may return different results compared to older HALCON versions:
  
  1. True latin-1 characters (ISO88591) work as before because the Unicode codes of these characters are the same as their latin-1-ANSI codes.
  2. Latin-1 extensions like Windows code page 1252 or latin-9 (ISO885915) contain characters with ANSI-codes which differ from their Unicode counterparts, e.g., the EURO sign (€) has different codes in Windows code page 1252, latin-9, and Unicode.
  3. Multi byte characters like Asian letters or any special character in UTF-8 couldn't be processed with tuple_ord and tuple_chr until now. As a workaround it was possible to call tuple_ords and tuple_chrt for creating such a character from a number sequence or converting it into one (according to the current encoding). Such workarounds are no longer needed, but also no longer possible (with the default settings).
  Programs which used these operators with special characters which are not true latin-1 are very likely to need some modifications with the advantage that the new code is interchangeable between different locales and platforms.
  More information.
• The data code readers assume the string encoding of the strings encoded in the symbol to be UTF-8 by default. If the string is encoded in the string encoding of the current locale, use set_data_code_2d_param(DataCode2DHandle, 'string_encoding', 'locale'). More information.
• HDevEngine/C++ assumes strings to be encoded in UTF-8. Non-ASCII strings in the local system encoding are no longer handled correctly since they are interpreted as UTF-8 by default. This can be changed by setting HalconCpp::SetHcppInterfaceStringEncodingIsUtf8(false). More information.
• Applications that read text files with non-ASCII characters may need to be adapted if these files have not been encoded in UTF-8. Text files should therefore be provided in UTF-8 in the future. In addition, applications which use fread_char for reading files byte-wise and rely on the fact that this operator returns exactly one byte, must be adapted. Furthermore, the operator fread_line now returns on all systems, i.e., also on Linux and macOS X, the line ending '\n' when the file was written under Windows with the line break sequence '\r\n' (carriage return + line feed). More information.
• When communicating via send_tuple, receive_tuple, send_data, and receive_data, non-ASCII characters might not be transfered correctly anymore. If the strings of the connection partner are encoded in the encoding of the current locale, the parameter 'string_encoding' of open_socket_accept and open_socket_connect should be set to 'locale'. More information.
• In the very unlikely case that an old lexicon file contains non-ASCII entries in the local-8-bit encoding that all could be misinterpreted as valid UTF-8 words, the lexicon would not represent the expected words. The favored way to solve the problem would be to transcode the lexicon file into UTF-8. If this is not possible because the file must be used by an old HALCON version as a workaround one could enter one entry in the native encoding that cannot be misinterpreted as UTF-8. More information.
• When communicating via serialize_tuple or deserialize_tuple using a previous HALCON version, non-ASCII characters might not be transferred correctly anymore. In that case, you can set the parameter 'write_halcon_files_encoding' or 'read_halcon_files_encoding' of set_system to 'locale' to force HALCON to write or read its files with the current locale system encoding instead of UTF-8. More information.
• Old programs that rely on the locale string encoding may need to be modified for returning the same results on HALCON 18.11. More information.
• If the HDevelop command line option -convert was used to export HDevelop programs to C or C++ programs, until now string constants were encoded with the local-8-bit encoding. Now, the default to encode these strings is UTF-8. By the new option -encoding native this can be changed back to the old behavior. More information.

• The following operators became legacy:
  • dev_map_par,
  • dev_map_prog,
  • dev_map_var,
  • dev_unmap_par,
  • dev_unmap_prog, and
  • dev_unmap_var.
  The operators dev_open_tool and dev_close_tool can be used instead.
• Switching the string encoding of the HALCON library to the local-8-bit encoding of the current locale via set_system('filename_encoding', 'locale') is declared to be legacy now.

Discontinuation of the HALCON/COM Language Interface

The HALCON/COM interface, including the possibility to develop with Delphi, is no longer available.

Planned Discontinuation of the x86-win32 platform version for Windows

MVTec plans to discontinue the x86-win32 platform version for Windows. This might likely to be happening in the course of 2020. We recommend to start switching your applications to the x64-win64 platform version for Windows.

Code Export

GUI

IDE

Procedures

Miscellaneous

Assistants

Code Export

GUI

Help

IDE

Language

Procedures

Miscellaneous

New Functionality

Bug Fixes

New HDevelop Example Programs

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

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

  
  
• derivate_gauss is now slightly faster on Intel compatible processors that support AVX. In particular, the following speedups can be expected:
  

  Image Size	Sigma	Speedup without Parallelization	Speedup with 8-Thread Parallelization
  512x512	1	15%	10%
  	3	21%	10%
  	5	12%	9%
  	7	9%	10%
  	9	8%	7%
  800x600	1	11%	0%
  	3	22%	12%
  	5	16%	13%
  	7	13%	15%
  	9	16%	5%
  1024x768	1	8%	-5%
  	3	18%	11%
  	5	22%	9%
  	7	17%	14%
  	9	18%	8%
  1600x1200	1	8%	0%
  	3	23%	14%
  	5	18%	13%
  	7	12%	9%
  	9	16%	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:
  • derivate_vector_field is up to 18% faster for all supported Components
  • points_foerstner is up to 10% faster for Smoothing 'gauss'
  • critical_points_sub_pix is up to 22% faster for Filter 'gauss' and all supported image types
  • local_max_sub_pix is up to 25% faster for Filter 'gauss' and all supported image types
  
  
• The operator deviation_image is now faster for image types uint2 and real. In particular, the following speedups can be excepted:
  

  Image Size	Image type	Mask Size	Speedup without Parallelization	Speedup with 8-Thread Parallelization
  512x512	uint2	3x3	160%	180%
  		9x9	540%	450%
  		99x99	7000%	4250%
  1600x1200		3x3	170%	65%
  		9x9	525%	265%
  		99x99	7250%	3330%
  512x512	real	3x3	105%	40%
  		9x9	365%	210%
  		99x99	6050%	2500%
  1600x1200		3x3	100%	10%
  		9x9	340%	125%
  		99x99	4800%	2150%

  
  
• find_shape_model, find_shape_models, find_scaled_shape_model, find_scaled_shape_models, find_aniso_shape_model and find_aniso_shape_models are now faster on machines with many cores (estimated more than 8 cores), especially for matching models with larger rotation ranges and/or scale ranges.
  find_local_deformable_model, find_planar_uncalib_deformable_model and find_planar_calib_deformable_model are now faster on machines with more than one core.
• 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.
• The operators gen_gauss_pyramid, zoom_image_factor, and zoom_image_size are now faster for byte images on systems that support SSSE3/AVX2 for the interpolation mode 'constant' and a scale factor of 0.5 when the image width is not divisible by 16/32 without remainder. In particular, the following speedups can be expected:
  

  Operator	Image Size	Available Instruction Set	Speedup
  zoom_image_size zoom_image_factor	700x500	SSSE3	up to 65%
  		AVX2	up to 140%
  	1180x1000	SSSE3	up to 75%
  		AVX2	up to 170%
  	1400x1050	SSSE3	up to 75%
  		AVX2	up to 150%
  gen_gauss_pyramid	700x500	SSSE3	up to 45%
  		AVX2	up to 105%
  	1180x1000	SSSE3	up to 70%
  		AVX2	up to 155%
  	1400x1050	SSSE3	up to 70%
  		AVX2	up 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:
  

  Operator	Image Size	Speedup
  zoom_image_size zoom_image_factor	800x600	up to 45%
  	1024x768	up to 45%
  	1280x960	up to 35%
  	1600x1200	up to 35%
  gen_gauss_pyramid	800x600	up to 35%
  	1024x768	up to 30%
  	1280x960	up to 30%
  	1600x1200	up 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 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

  
  
• 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 Type	Image size	OS	Speedup without Parallelization	Speedup with Parallelization	Available Instruction Set
  byte	512x512	Windows	45%	45%	AVX2
  	800x600		45%	40%	AVX2
  	1024x768		45%	45%	AVX2
  	1600x1200		45%	50%	AVX2
  	2048x2048		40%	45%	AVX2
  	512x512	Linux	35%	40%	AVX2
  	800x600		35%	35%	AVX2
  	1024x768		40%	45%	AVX2
  	1600x1200		55%	60%	AVX2
  	2048x2048		50%	55%	AVX2

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

Bar Code

Calibration

Classification

Compute Device

Data Code

Deep Learning

Feature

File

Filter

Graphics

Inspection

Matching

Miscellaneous

OCR

Segmentation

System

Timeout

Tuple

XLD

3D

Bar Code

Calibration

Classification

Data Code

Deep Learning

Feature

File

Filter

Graphics

Inspection

Images

Matching

Measure

Memory

Miscellaneous

Morphology

OCR

Parallelization

Region

Segmentation

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

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

• In legacy handle mode, the following operators returned tuples with elements of type HANDLE_PAR instead of the converted LONG_PAR: tuple_union, tuple_intersection, tuple_difference, tuple_symmdiff, tuple_uniq, tuple_inverse, tuple_concat, tuple_select_range, tuple_last_n, tuple_first_n, tuple_insert, tuple_replace, tuple_remove, tuple_select_mask, tuple_select, tuple_gen_sequence, and tuple_gen_const. Note that in HDevelop and the HDevEngine only the inline function version of these operators were affected. This problem has been fixed.

• The HALCON/C++ interface has been extended to support HALCON's new handle data type. The new type HHandle has been added. HTuple elements representing handles should be accessed as HHandle (*.H) instead of Hlong (*.L). HHandle is also the base class for object-oriented tool classes that wrap a handle such as HShapeModel, HMatrix, etc. All copies of a handle whether in HTuple or tool class share a common reference counter, so destroying, e.g., a HShapeModel instance no longer destroys the actual shape model if it is still referenced by a HTuple instance. Note that this change affects the compatibility. Read more.

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

• The HALCON/.NET interface has been extended to support HALCON's new handle data type. The new type HHandle has been added. HTuple elements representing handles should be accessed as HHandle (*.H) instead of Hlong (*.L). HHandle is also the base class for object-oriented tool classes that wrap a handle such as HShapeModel, HMatrix, etc. All copies of a handle whether in HTuple or tool class share a common reference counter so disposing e.g. a HShapeModel instance no longer destroys the actual shape model if it is still referenced by a HTuple instance. HTuple is now a disposable class as well to allow deterministic release of handle references stored within an instance. Note that this change affects the compatibility. Read more.
• 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.

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

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

• After a clean has been done in the HALCON Variable Inspect extension for Visual Studio a double click on the selected variable was necessary to update it. Now this can be achieved by a single click on it.

• The HALCON Variable Inspect extension for Visual Studio 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.

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

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

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

• 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

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

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

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

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

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

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