Release Notes for HALCON 12.0.4

This document provides the release notes for MVTec HALCON 12.0.4, as released in February 2018.

HALCON 12.0.4 is primarily a maintenance release that fixes known bugs in HALCON 12.0.3; besides, it provides some added functionality. Note, that only the Runtime Version which includes the HDevEngine, the HALCON Library and language interfaces is shipped with HALCON 12.0.4.


Addendum to the Release Notes of HALCON 12.0.4

The originally released version of HALCON 12.0.4 had a few issues:

  • 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. 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 web server https://www.mvtec.com/download/halcon/.
  • In rare cases, get_data_code_2d_results crashed during print quality inspection.
  • Creating an HDevProcedure instance from a local procedure in an HDevProgram did not work when that local procedure referenced other local procedures.

Therefore, the original version HALCON 12.0.4 was substituted by an updated version HALCON 12.0.4.2.

To find out which version is currently installed, please open the dialog "Help->About" in HDevelop. The fixed version of the HALCON library is indicated by: "HALCON version: 12.0.4.1 (11.07.2018)". The file version of the HALCON library can also be checked with the following operator call: get_system('file_version',FileVersion), or, under Windows, by inspecting the file properties of the files halcon.dll and halconxl.dll.


Compatibility

Licenses

HALCON 12.0 licenses are also valid for HALCON 12.0.4. In contrast, all HALCON 11.0 licenses or licenses of earlier versions must be replaced or upgraded. Please contact your local distributor.

HALCON Library

HALCON 12.0.4 is fully compatible with HALCON 12.0 except for the changed behavior of some operators owing to bug fixes. Compared to HALCON 11.0, many extensions have been introduced. Thus, the HALCON 12.0 libraries are not compatible with HALCON 11.0 or earlier versions.

In detail, please note the following incompatibilities with respect to HALCON 12.0.3:

  • A bugfix for find_text requires an adaption of the HDevelop example 'ocr_lot_number.hdev' in order to preserve its functionality. Since no example programs are delivered with HALCON 12.0.4, please adapt 'ocr_lot_number.hdev' as follows: replace set_text_model_param (TextModel, 'stroke_width', 7) with set_text_model_param (TextModel, 'stroke_width', 8). More information.
  • The results and scores of surface-based matching can change for scenes where the average distance between neighboring points is larger than 0.001. More information.
  • For get_circle_pose the order of the output poses may be reversed with respect to the old behavior when the distance of the circle to the camera is smaller than or roughly equal to its radius. More information.

HALCON Applications

Applications (i.e., executables) developed with HALCON 12.0, HALCON 12.0.1, HALCON 12.0.2, or HALCON 12.0.3 can be used with HALCON 12.0.4, i.e., HALCON 12.0.4 is binary compatible with HALCON 12.0, HALCON 12.0.1, HALCON 12.0.2, and HALCON 12.0.3.

All programs (C, C++, .NET, or COM) that have been developed with HALCON 11.0.x must be recompiled. The incompatibility with HALCON 11.0.x or earlier versions mainly concerns the binaries, with only few changes in the language interfaces. If you encounter problems during recompiling your programs, please check the detailed description of changes below and for HALCON 12.0, HALCON 12.0.1, HALCON 12.0.2, and HALCON 12.0.3, respectively.

Please note that applications using HALCON/.NET (and HDevEngine/.NET) have local copies of the corresponding assemblies (halcondotnet.dll etc.). In order to benefit from the bug fixes in the HALCON/.NET interface, you must either replace the assemblies manually or recompile the projects. If you do not recompile the application, you need to add an application configuration file mapping the application's expected assembly version to the new version. See the Programmer's Guide for more information.

Image Acquisition Interfaces

If you have developed your own acquisition interfaces with HALCON 12.0, HALCON 12.0.1, HALCON 12.0.2, or HALCON 12.0.3, you can use them with HALCON 12.0.4 without further action.

Digital I/O Interfaces

If you have developed your own digital I/O interfaces with HALCON 12.0, HALCON 12.0.1, HALCON 12.0.2, or HALCON 12.0.3, you can use them with HALCON 12.0.4 without further action.

Extension Packages

Extension packages developed with HALCON 12.0, HALCON 12.0.1, HALCON 12.0.2, or HALCON 12.0.3 can be used with HALCON 12.0.4 without further action. Extension packages developed with HALCON 11.0.x or earlier versions must be re-generated. Note that the old makefiles for HALCON/C++ must be adapted according to the sample makefile under extension_packages/halconuser.

Planned Discontinuation of the HALCON/C++ (legacy) Language Interface

MVTec plans to discontinue the HALCON/C++ (legacy) language interface. The timeline for this discontinuation includes the following steps:

  • HALCON 12.0.4:

    • There are warnings when compiling HALCON/C++ (legacy) projects.
  • HALCON 17.12 and higher:

    • The HALCON/C++ (legacy) interface is not available anymore.

Planned Discontinuation of the Support of FLEXid Dongles

For HALCON 13 and higher, FLEXid dongles are no longer supported and will be substituted by CodeMeter dongles. Note that HALCON 12 will furtheron support FLEXid dongles. For HALCON 12.0.3 and higher, also CodeMeter dongles are supported, if a valid HALCON 13 license file is available.

Detailed Description of Changes in HALCON 12.0.4

The changes in HALCON 12.0.4 are described with respect to HALCON 12.0.3. The detailed description of changes in previous HALCON versions can be found in the release notes of the previous HALCON versions.

HDevEngine

Bug Fixes

  • Destroying an HDevProcedureCall object did not release the referenced memory until the associated HDevProcedure object was destroyed too. This problem has been fixed.
  • When executed with JIT-compilation, the HDevelop operator convert_vector_to_tuple sporadically raised a low level error or crashed if the vector argument of the operator was an expression. 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.
  • Setting control vectors as input parameters of a procedure call in HDevEngine created a memory leak. This problem has been fixed.
  • HDevelop could have remained in an inconsistent state if procedures containing nested try-catch statements were executed JIT-compiled. This problem has been fixed.
  • Procedures may refer to multiple procedures with the same name, either directly via the import statement or indirectly for private library procedures. However, when used in engine applications via HDevProcedure, such procedures did not work correctly. This problem has been fixed.
  • 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. This problem has been fixed.
  • HDevEngine crashed due to invalid memory access when sharing one HDevProcedure across multiple threads and each thread created and destroyed its own HDevProcCalls. 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.
  • JIT-compiled HDevelop procedures that used long-running HALCON operators caused performance problems with par_start. This problem has been fixed.
  • HDevelop behaved inconsistently or crashed when executing procedures containing vector operations with erroneous index expressions JIT-compiled. This problem has been fixed.
  • The import statement in HDevelop did not resolve UNC paths on Windows correctly, leading to invalid procedure paths and problems resolving external procedures. This problem has been fixed.
  • HDevelop's vector method .remove raised an exception when executed JIT-compiled with an index value beyond the vectors end, but didn't so when executed non-JIT-compiled. This problem has been fixed. Now, no exception is raised in both cases.
  • Loading two or more programs into the same instance of HDevEngine sometimes led to unresolved procedure calls. This problem has been fixed.

HALCON Library

Speedup

  • sample_object_model_3d did not sample sphere and cylinder primitives as accurately as possible. Additionally, when sampling in mode 'fast_compute_normals', the normal vectors of those primitives would have pointed inward instead of outward. These problems have been fixed. Additionally, sampling spheres is now up to 670% faster, sampling cylinders is up to 8500% faster.

Bug Fixes

3D
  • The operators might have returned wrong score values in rare cases or might have crashed in rare cases. For binocular_disparity_mg and binocular_distance_mg the problem only occurred when 'CalculateScore' was set to 'true'. For reconstruct_surface_stereo the problem only occurred when 'disparity_method' was set to 'binocular_mg' using set_stereo_model_param. This problem has been fixed.
  • binocular_disparity_ms and binocular_distance_ms sometimes crashed when the operators were executed parallelized and the image size was greater than approximately 9 megapixels. This problem has been fixed.
  • binocular_disparity_ms and binocular_distance_ms crashed after running out of memory. This problem has been fixed. Now, the error 6001 ("Not enough memory available") is returned.
  • binocular_disparity_ms and binocular_distance_ms sometimes crashed for large images and disparity ranges. This problem has been fixed.
  • binocular_disparity_ms and binocular_distance_ms had a restriction on the disparity range. The disparity range could not be larger than 256. This problem has been fixed.
  • In rare cases, binocular_distance incorrectly reduced the domain of the result at the lower and upper parts when 'parallelize_operators' was set to 'true' in set_system. This problem has been fixed.
  • The execution time of connection_object_model_3d could have varied by a large factor when executed with parallelization enabled, even for identical input. This problem has been fixed.
  • During surface-based matching the normals computed from XYZ-mappings, e.g., by the operators create_surface_model and find_surface_model, were not scale invariant. Most notably, if the distance between neighboring points exceeded 1, the normals could have pointed into wrong directions. This problem has been fixed. The normals are now computed in a way that is invariant to the scale of the model and the data. Note that this change affects the compatibility. Read more.
  • In rare cases, find_shape_model_3d returned matches with a Score smaller than MinScore. This problem has been fixed.
  • find_shape_model_3d crashed in rare cases if the camera parameters did not match the setup. This problem has been fixed.
  • get_circle_pose in some cases did not work if the distance of the circle to the camera was smaller than its radius. This problem has been fixed. Note that this change affects the compatibility. Read more.
  • pose_average returned wrong quality measure values and the respective documentation was not clear. This problem has been fixed.
  • prepare_object_model_3d in rare cases did not close all holes during the triangulation
    of the given 3D object model, i.e., if the parameter Purpose was set to
    'segmentation' and 'max_area_holes' was used. This problem has been fixed.
  • project_object_model_3d with the generic parameter 'hidden_surface_removal' set to 'false' could have returned wrong results in rare cases. This problem has been fixed.
  • read_object_model_3d threw an error when reading OBJ files that contained too many white space characters at certain positions. Additionally, polygons with more than 1000 vertices were truncated, and only the first 1000 vertices were returned. These problems have been fixed. The operator now reads OBJ files with arbitrary white space characters and no longer truncates polygons with more than 1000 vertices.
  • read_object_model_3d returned a wrong error message when a binary format with unsupported data was read. This problem has been fixed. Now, the error message 9541 ("At least one attribute is not supported") is returned.
  • register_object_model_3d_pair might have crashed if an input model contained only primitives. This problem has been fixed.
  • When passing a 3D object model that contains only a primitive as second parameter to register_object_model_3d_pair, the 3D object model sometimes was handled incorrectly, leading to a deadlock when using it in a subsequent operator. This problem has been fixed.
  • set_sheet_of_light_param crashed when a calibration object of the wrong type, i.e., no DXF model, was passed. This problem has been fixed.
  • simplify_object_model_3d sometimes crashed if a triangle of the input object model was degenerated by containing the same point two or three times. This problem has been fixed.
  • triangulate_object_model_3d might have frozen in rare cases when 'greedy_mesh_erosion' >= 1 was set. This problem has been fixed.
  • union_object_model_3d did not raise an error if the passed parameter 'Method' was incorrect. This problem has been fixed. union_object_model_3d now returns the errors 1202 ("Wrong type of control parameter 2"), 1302 ("Wrong value of control parameter 2") and 1402 ("Wrong number of values of control parameter 2").
  • In rare cases, when passing invalid 3D object model handles to union_object_model_3d, exception H_ERR_WIPT1 instead of H_ERR_WIPV1 was raised. This problem has been fixed.
  • volume_object_model_3d_relative_to_plane sometimes returned wrong results when a triangle of the 3D object model intersected the plane. This problem has been fixed. Also, the reference manual entry has been clarified and extended.
Bar Code
  • get_bar_code_result with 'quality_isoiec15416' used in very rare cases uninitialized image values to evaluate the quiet zone. This problem has been fixed.
  • get_bar_code_result threw an exception and then crashed for quality inspection in rare cases when the symbol region was outside the image. This problem has been fixed.
Calibration
Classification
Compute Device
  • HALCON may have crashed after destroying the tuple returned by get_compute_device_param with GenParamName='asynchronous_execution' or GenParamName='alloc_pinned'. This problem has been fixed.
Data Code
  • In rare cases, find_data_code_2d for QR codes might have returned the error 3513 ("Internal error: number of chords too big for num_max"). This problem has been fixed.
  • find_data_code_2d for Data Matrix ECC 200 codes in very rare cases did not find symbols when 'module_gap_min' was set to 'no' or 'small' and 'module_gap_max' was set to 'big', although the symbols could be found when 'module_gap' was set to 'big'. This problem has been fixed.
  • find_data_code_2d for Data Matrix ECC 200 codes in very rare cases did not find symbols when a timeout was set, although the same symbols could be found when no timeout was set. This problem has been fixed.
  • find_data_code_2d returned duplicated results in some cases although 'discard_undecoded_results' was 'true'. This problem has been fixed.
  • The Data Matrix ECC 200 code reader could have accessed invalid memory when reading invalid content of symbols. This problem has been fixed.
  • The Aztec code reader could have crashed in very rare cases. This problem has been fixed.
  • get_data_code_2d_param returned wrong default values of 'version_max' and 'symbol_size_max' for Micro QR Codes. This problem has been fixed.
  • get_data_code_2d_results in rare cases could have returned invalid results or crashed when querying print quality grades of Aztec codes. This problem has been fixed.
  • get_data_code_2d_results crashed for 'quality_isoiec15415_values', 'quality_aimdpm_1_2006_values', and 'quality_semi_t10_values' when the symbol was near the image border. This problem has been fixed.
  • get_data_code_2d_results in rare cases returned the error 6006 ("Tmp-memory management: could not find memory element") when querying quality parameters for QR codes. This problem has been fixed.
  • In rare cases get_data_code_2d_results caused a memory leak for Data Matrix ECC 200 codes if 'ResultNames' was set to 'quality_iso15415' or 'quality_aimdpm_1_2006'. This problem has been fixed.
  • get_data_code_2d_results used a wrong contrast value for grading the fixed pattern of Data Matrix ECC 200, QR codes, and Micro QR codes for AIM DPM-1-2006. This problem has been fixed.
  • read_data_code_2d_model and read_sheet_of_light_model returned the error 8725 ("Invalid file format for bar code model"), when the file was corrupt. This problem has been fixed. Now, read_data_code_2d_model returns the error 8867 ("Invalid file format of data code model") and read_sheet_of_light_model returns the error 3786 ("Invalid file format for sheet-of-light model").
  • The parameter 'contrast_min' of set_data_code_2d_param did not accept values greater than 100 for the Aztec code reader. To be consistent with the other code readers, this restriction has been removed.
File
  • Calling set_current_dir for absolute paths caused the .NET API call Directory.GetCurrentDir() to crash. This problem has been fixed for path lengths up to 247 characters.
  • The operators sometimes did not return the correct error code if the disk to which the data should be written was full. This problem has been fixed.
  • write_image crashed in HALCON XL for the formats png and jp2 and image sizes bigger than those supported by the corresponding third party library internally used. This problem has been fixed: a proper error code is returned in this case.
Filter
  • convol_image returned incorrect results with byte images and separable filter masks that have more than 8 columns and 'mirrored' border treatment. This problem has been fixed.
  • edges_image returned different results in subsequent calls when executed on OpenCL compute devices. This problem has been fixed.
  • edges_sub_pix and edges_color_sub_pix could have returned contours consisting of single points for the filter 'sobel_fast'. This problem has been fixed.
  • mean_sp read the parameters 'MaskWidth' and 'MaskHeight' in the wrong order. This problem has been fixed.
  • mult_image did not correctly multiply byte images for small multiplication factors. This problem has been fixed.
  • phase_correlation_fft sometimes returned an indefinite output. This problem has been fixed.
  • points_harris_binomial might have crashed in very rare cases. This problem has been fixed.
Graphics
Image
  • full_domain crashed if an image with width or height equal to 0 was passed. This problem has been fixed.
Matching
Measure
Miscellaneous
  • gen_grid_rectification_map could have crashed in very rare cases. This problem has been fixed.
  • get_circle_pose crashed if an integer or float value was passed to the parameter 'OutputType'. This problem has been fixed.
  • inpainting_texture in rare cases could have returned wrong results. This problem has been fixed.
  • interpolate_scattered_data usually returned incorrectly interpolated values if the number of points that have been used to create the interpolator exceeded 500, or if the number of evaluated points exceeded 4500. This problem has been fixed. Now, the operator might be slower in some cases.
OCR
  • clear_text_model sometimes crashed if the text model parameter 'ocr_classifier' has been set before with set_text_model_param and set_text_model_param returned an error. This problem has been fixed.
  • concat_ocr_trainf did not always close all opened file handles. This problem has been fixed.
  • find_text crashed in rare cases with text models of mode 'manual'. This problem has been fixed.
  • find_text crashed when using an OCR classifier with less than three classes. This problem has been fixed.
  • find_text in manual mode could have produced inconsistent results over multiple executions. This problem has been fixed. Note that this change affects the compatibility. Read more.
  • find_text returned an error for multichannel images. This problem has been fixed. Now, instead of throwing an error the first image channel is used for text segmentation.
  • get_text_result returned error messages that were not helpful if the result name is not available for the selected mode. This problem has been fixed. Now, the HALCON error code 8338 is returned.
  • trainf_ocr_class_svm might have crashed for corrupted input files. This problem has been fixed.
  • write_ocr_trainf and write_ocr_trainf_image did not close the train file, if an error due to an empty character region was returned. This problem has been fixed.
Parallelization
  • The automatic operator parallelization (AOP) has had a memory leak on channel level for operators that support AOP on tuple level as well as on channel level and have more than one iconic input parameter. Operators that are concerned are This problem has been fixed.
  • The set_system parameter 'tsp_thread_num' set the number of AOP threads to a number that was one below when setting the maximum available threads. The problem occurred when 'tsp_thread_num' was set to a smaller number before. This problem has been fixed.
  • After disabling and enabling compute devices, there was a small memory leak when calling operators with automatic operator parallelization. This problem has been fixed.
Region
  • partition_rectangle sometimes processed vertically discontiguous input regions incorrectly. This problem has been fixed.
Segmentation
  • local_min and local_max could have returned wrong results for images with a width of 1. This problem has been fixed.
System
  • If an operator emitted an extended error message, HDevelop crashed after closing HDevelop. This problem has been fixed.
  • Setting the 'help_dir' via set_system had no effect. This problem has been fixed.
  • try_lock_mutex returned a semantically inverted busy flag when running in HDevelop under Windows. This problem has been fixed.
Tuple
  • tuple_replace crashed in rare cases when the same index was replaced more than once. It also caused a memory leak in other rare cases. These problems have been fixed.
  • tuple_string crashed when called with a large field width. The HDevelop language construct $ was affected as well. This problem has been fixed.
XLD

HALCON/C++

Bug Fixes

  • When copying a C++ HTuple created using one of the array constructors with a size of zero or one, HALCON could have crashed when the HTuples were freed. This problem has been fixed.
  • There was a memory leak in the methods HTupleVector::Concat and HObjectVector::Concat. This problem has been fixed.

HALCON/.NET

Bug Fixes

  • Passing empty strings to HALCON operators via the HALCON/.NET language interface caused an error when the system parameter 'filename_encoding' was set to 'utf8'. This includes that it was not possible to call DevOpenWindow via HDevEngine with HDevOpMultiWindowImpl, since it internally passes an empty string to the machine parameter of OpenWindow. This problem has been fixed.
  • 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.
  • Calling an operator with a null input parameter caused a memory leak in HALCON/.NET. This problem has been fixed.
  • The Serialize() member functions in the .NET interfaces crashed in rare cases. This problem has been fixed.

Image Acquisition Interfaces

The latest information about new interface revisions and newly supported image acquisition devices can be found on MVTec's web server. 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.

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.

Supported Operating Systems

Windows

HALCON 12.0.4 has been compiled for the following Windows platform versions:

  • x86sse2-win32 platform version for Windows Vista/7/8/8.1/10 or Windows Server 2008/2012/2016 on x86 processors with SSE2 extension, i.e., Intel Pentium 4 / AMD Athlon 64 or higher
  • x64-win64 platform version for Windows Vista/7/8/8.1/10 or Windows Server 2008/2012/2016 x64 Edition on Intel 64 or AMD64 processors

Miscellaneous

Licensing

  • If a license file started with an UTF-8 byte order marker, HALCON ignored the first license entry. This problem has been fixed.
  • In rare cases HALCON rejected certain valid MAC addresses for licensing. 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.

The major new features of HALCON 12.0.4 are described with respect to HALCON 12.0.3. Follow the links below to read about major new features of previous HALCON versions.

The changes in HALCON 12.0.4 are described with respect to HALCON 12.0.3. Follow the links below to read about changes in previous HALCON versions.