Release Notes for HALCON 13.0.1

• In very rare cases, the improvement of the determination of the module position of Data Matrix ECC 200 code for quality assessment can affect the detection of Data Matrix ECC 200 codes using find_data_code_2d. More information.
• Due to an improvement with respect to the calculation of the range of rotations, the operators
  find_shape_model,
  find_shape_models,
  find_scaled_shape_model,
  find_scaled_shape_models,
  find_aniso_shape_model,
  find_aniso_shape_models,
  find_ncc_model, and
  find_ncc_models
  may return different or additional results compared to previous HALCON versions. The reason is that the angle range may now be larger for models created from a negative starting angle to a positive angle and smaller for models created for a full circle. 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.
• Note that query_bar_code_params does not support overridden functions anymore. More information.
• Extended attributes of 3D object models that are bound to the object itself, not to points, triangles, polygons, or lines, are no longer copied by union_object_model_3d. Additionally, some attributes that previously were not in the output 3D object model now are copied. More information.

IDE

Miscellaneous

Assistants

GUI

IDE

Procedures

Code Export

Miscellaneous

New, Improved, or Deleted HDevelop Example Programs

Bug Fixes

• HDevelop terminated when attempting to connect to an external engine application in SDI mode. This problem has been fixed.
• Deactivated or invalid lines in a procedure could have caused a crash when debugging the procedure within an HDevEngine application. This problem has been fixed.
• In HDevelop code it is possible to split long commands over multiple lines using the line continuation character (backslash). However, a command that was split over more than two lines did not display correctly when debugging it in an external HDevEngine application. This problem has been fixed.
• On Linux, string operations executed in HDevEngine were not thread-safe. This could have led to crashes in very rare cases. 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.
• 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.
• It was possible for engine applications to leak large amounts of memory when they were being debugged remotely via HDevelop. This problem has been fixed.
• In HDevEngine applications, trying to execute a procedure JIT-compiled led to a crash if the regarding procedure contained dev_disp_text. This problem has been fixed.
• Exported C / C++ code could have failed to run correctly as a standalone program on macOS 10.12. This problem has been fixed.

• In HDevEngine/.NET, program and procedure paths with special characters were not properly encoded with the system parameter 'filename_encoding' set to 'utf8'. This problem has been fixed. It is now possible to use arbitrary characters in directory names (even those not supported by the local encoding).

• bit_lshift worked incorrectly for 'int4' images in 32-bit environments. This problem has been fixed. The operator is now up to 300% faster for all supported image types.
• 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.

3D

Calibration

Data Code

Feature

Graphics

Region

System

3D

Bar Code

Calibration

Classification

Compute Device

Data Code

File

Filter

Graphics

Inspection

Image

Matching

Measure

Miscellaneous

OCR

Parallelization

Region

Segmentation

System

Tuple

XLD

• The procedure gen_camera_setup_object_model_3d has been improved. The parameters ConeLength and CameraSize can now be set to 'auto'. Then, these values are estimated automatically based on the lines of sight of the cameras.
• HALCON has been extended with a set of new examples and procedures to facilitate the hand-eye calibration for a setup with a stationary camera and pick-and-place applications for setups both with a stationary camera and a moving camera (attached to the robot arm):
  The HDevelop example program
  • hdevelop/Calibration/Hand-Eye/calibrate_hand_eye_stationary_cam_approx.hdev
  shows two workflows how to calibrate the hand-eye parameters of a setup with stationary camera, either with a HALCON calibration plate, or with user-defined target points.
  The HDevelop example programs
  • hdevelop/Applications/Robot-Vision/pick_and_place_with_2d_matching_stationary_cam.hdev and
  • hdevelop/Applications/Robot-Vision/pick_and_place_with_2d_matching_moving_cam.hdev
  show how to use shape-based 2D matching to find objects in 3D. Additionally, you can perform a rudimentary path planning for your robot to train how to approach, grasp, and move the object.
  These example programs use new procedures, which are available in the procedure library procedures/general/hand_eye.hdpl. The most important new procedures are:
  • calibrate_robot_touching_point,
  • collect_single_image_calibration_data and calibrate_camera_and_plane_single_image, which allow you to calibrate your camera setup with a single image,
  • calibrate_hand_eye_stationary_cam_approx and calibrate_hand_eye_stationary_cam_approx_without_calib_plate,
  • obtain_3d_pose_of_match_stationary_cam and obtain_3d_pose_of_match_moving_cam, which allow you to use shape-based 2D matching to get the 3D position of these matches, and
  • prepare_poses_and_rectification_data_stationary_cam and prepare_poses_and_rectification_data_moving_cam to prepare the necessary data for the two previous procedures.
  Additionally, the procedure library contains procedures to help you visualize your setup in 3D, like for example gen_current_setup_moving_cam_object_model_3d. You can see how to use these procedures in the above-mentioned examples.
  The procedure library visualize_object_model_3d.hdvp has been extended with the procedure gen_arrow_object_model_3d, which can be used to create 3D arrows for visualization.
• get_data_code_2d_results has been extended for Data Matrix ECC 200 codes by the ResultNames parameters:
  • 'quality_isoiec15415_reflectance_margin_module_grades',
  • 'quality_isoiec15415_rows',
  • 'quality_isoiec15415_cols',
  • 'quality_aimdpm_1_2006_reflectance_margin_module_grades',
  • 'quality_aimdpm_1_2006_rows', and
  •  'quality_aimdpm_1_2006_cols'.
  These parameters allow to visualize the position and grading of individual data code modules used during quality assessment.
  The new HDevelop procedure
  • procedures/general/dev_display_data_code_2d_print_quality_results.hdvp
  can be used to display the print quality results for Data Matrix ECC 200 codes and it uses the new operator parameters listed above. It displays the reflectance margin grading of the individual data code modules and their position.
  The new HDevelop example program
  • hdevelop/Identification/Data-Code/ecc200_print_quality_modules.hdev
  inspects the print quality of individual modules of an Data Matrix ECC 200 code by using the new procedure.
  The HDevelop example program
  • hdevelop/Identification/Data-Code/ecc200_print_quality.hdev
  has been adapted in order to show how the new procedure can be used

• The HDevelop standard procedure scale_image_range did not support image arrays. This problem has been fixed.
• The value list of the parameters Row and Column for disp_message did not contain predefined values, such as 'top' and 'bottom'. Furthermore, some parts of the documentation were not adapted to the predefined values. These problems have been fixed.

• 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.
• Setting control vectors as input parameters of a procedure call in HDevEngine created a memory leak. This problem has been fixed.
• There was a memory leak in the methods HTupleVector::Concat and HObjectVector::Concat. This problem has been fixed.

• The HSmartWindowControlWPF has been improved. WindowSize and HImagePart were not WPF compliant. Now, these properties support TwoWay binding. Additionally, the new property HDisplayCurrentObject has been added to display any HALCON object directly through binding as well. To demonstrate the binding, a new C# example BindingWPF has been added.
• The HSmartWindowControlWPF property now supports a further parameter HZoomFactor. If the HZoomContent property is active, the HZoomFactor parameter has a direct impact on the behavior of the HSmartWindowControlWPF zoom option and allows to influence the step size.
• The HSmartWindowControl and HSmartWindowControlWPF now provide the event HErrorNotify. This event allows the user to react to errors that take place internally within the control, but can have external causes, like for example an unplugged dongle or a missing license file. The Programmer's Guide has been adapted accordingly.
• The HALCON Variable Inspect extension for Visual Studio now supports also Visual Basic .net.

• The Programmer's Guide incorrectly stated that .NET client profiles are supported in HALCON 13.0. This problem has been fixed.
• 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.
• When embedding a HSmartWindowControlWPF in a Grid with no minimal nor maximal sizes specified, like for example this one:
  <Grid.RowDefinitions>
  <RowDefinition />
  <RowDefinition />
  </Grid.RowDefinitions>
  <Grid.ColumnDefinitions>
  <ColumnDefinition />
  <ColumnDefinition />
  </Grid.ColumnDefinitions>,
  the HSmartWindowControl WPF could have failed to initialize. This problem has been fixed.
• HSmartWindowControl.HImagePart returned an incorrect width and height. This problem has been fixed.
• When overloading the Loaded event of HSmartWindowControlWPF, the property HalconID returned -1 for an uninitialized window. In contrast to that, the HalconWindow property returned an initialized window. This problem has been fixed. Both cases now behave equally, i.e., when querying the ID property, the handle of the new window is returned.
• If the HSmartWindowControl was used inside Visual Studio together with a HALCON x64 build environment, a BadImageFormatException was thrown. The HSmartWindowControl was not displayed. This problem has been fixed.

• Programs using the HALCON/COM interface could have hung when exiting. This problem has been fixed.

• The HDevEngine example exec_programs_mt could have crashed when it was started with a non-existent HDevelop script. This problem has been fixed.
• The Visual Studio example project examples/cpp/mfc/MatchingCOM/vs2005/Matching.sln had no 64-bit platform target. This problem has been fixed.
• The use_debug_server example for HDevEngine was not included in the xcode project for macOS. This problem has been fixed.
• Exported C / C++ code could have failed to run correctly as a standalone program on macOS 10.12. This problem has been fixed.

• The HALCON Variable Inspect extension for Visual Studio now supplies a way to release the retrieved data via clicking on the tool bar button clear data window. This can be used in case of low memory to free the already retrieved data.
• The usability of the HALCON Variable Inspect Extension for Visual Studio has been improved. Instead of displaying all local variables as default, now the watch list is displayed. This improves the performance especially if many HALCON variables are used in the current scope.
• The HALCON operator reference can now be opened via the HALCON Variable Inspect extension for Visual Studio using the context menu entry HALCON Help or the shortcut ALT+H.
• The Programmer's Guide has been updated regarding the changes in the HALCON Variable Inspect extension for Visual Studio.
• The HALCON Variable Inspect extension for Visual Studio now stores settings made by the user. These are the used layout direction, the option "Only display last iconic object", and the selected tab Watch or Locals.
• The HALCON Variable Inspect extension for Visual Studio now retrieves .Net HTuple faster, no matter which HTuple type is retrieved.
• The HALCON Variable Inspect extension for Visual Studio now supports the Visual Studio versions 2013, 2015 and 2017.
• The GUI of the HALCON Variable Inspect extension for Visual Studio has been updated according to the new speed up. In particular, no longer needed table entries have been removed and other entries have been optimized.
• The HALCON Variable Inspect extension for Visual Studio now supports also Visual Basic .net.
• A great speed up has been achieved inside the HALCON Variable Inspect extension for Visual Studio for retrieving and visualizing iconic HALCON objects.

• If the HALCON Variable Inspect extension for Visual Studio was closed at the start of a debug session and only opened after execution had already halted (e.g., after a breakpoint), its GUI was disabled until a further execution step was executed (e.g., by pressing F10). This problem has been fixed.
• In the HALCON Variable Inspect extension for Visual Studio, removing many variables from the watch was very slow. This problem has been fixed.
• Displaying an already retrieved HALCON variable in the HALCON Variable Inspect extension for Visual Studio was very time consuming. This problem has been fixed.
• In special cases, the HALCON Variable Inspect Extension for Visual Studio erroneously reported a licensing error. The same error could have occurred in case of user-specific HALCON 32-bit applications. This problem has been fixed. Note that this problem has already been fixed in HALCON 13.0.0.1.
  
• The HALCON Variable Inspect extension for Visual Studio displayed gray values in the status bar, even on areas where the image domain has not been set. This problem has been fixed. Now it displays only gray values, when the domain of the image is defined at the mouse position. In general, the gray values of the first image on the stack are displayed.
• The HALCON Variable Inspect extension for Visual Studio did not correctly display polygons, since the x and y values of the points were swapped. This problem has been fixed.
• The HALCON Variable Inspect extension for Visual Studio could not be used with the HALCON/C++ interface. The attempt to retrieve data always failed. The Status "System.NullReferenceException: Object reference not set to an instance of an object" was displayed. This problem has been fixed.
• In the HALCON Variable Inspect extension for Visual Studio, the button "Fit image into graphics window" after scrolling and zooming a none image object did not work as expected. This problem has been fixed.
• Within the HALCON Variable Inspect extension for Visual Studio, to Minimize and maximize an embedded HSmartWindowControlWPF led to an exception. When maximizing the window, a render function with invalid parameters was called. This problem has been fixed.
• The HALCON Variable Inspect extension for Visual Studio sometimes crashed while inspecting variables in the Watch tab. This problem has been fixed.
• With the HALCON Variable Inspect extension for Visual Studio, HALCON control values could not be inspected if the Watch window of Visual Studio has been set to Hexadecimal display. This problem has been fixed.

• GenApi has been updated to version 3.0.2, which is required by the GenICamTL, GigEVision, and USB3Vision image acquisition interfaces.

• The 'File' interface failed to read images stored in the hobj format. This problem has been fixed.
• With the redesign of the HALCON website the general installation instructions for image acquisition and digital I/O interfaces were removed. To compensate this, installation instructions were added to the reference documentation of all the image acquisition and digital I/O interfaces.

Modified Image Acquisition Example Programs

New Image Acquisition Example Programs

The following HDevelop example programs have been added:

• With the redesign of the HALCON website the general installation instructions for image acquisition and digital I/O interfaces were removed. To compensate this, installation instructions were added to the reference documentation of all the image acquisition and digital I/O interfaces.
• The example I/O interface included with the I/O interface template could not be built for HALCON 13.0. This problem has been fixed.

• The license of the image and I/O acquisition template source code has been adapted so that it can be redistributed now.
• The I/O integration interface example hioExample was missing. In particular, the following files were missing: CIOEvent.cpp, CIOEvent.h, CIOVirtualDAQ.cpp, CIOVirtualDAQ.h, CIOVirtual.h, hioExample.cpp, hioExample_param.h, and hioExample_param.in. Furthermore, the complete directory io_integration/doc was missing. These problems have been fixed.
• The io_integration examples failed to build on macOS because HMessageQueue.h could not be included. This problem has been fixed.
• HALCON has been extended by a new HDevelop example
  • io_integration/hioexample_test.hdev
  that demonstrates the functionality of the hioExample interface.

• The Programmer's Guide has been updated to clarify that JIT-compiled procedures are already being compiled at the moment a corresponding HDevProcedureCall or HDevProgramCall instance is created.
• The Programmer's Guide erroneously stated that you can reset the external procedure paths by passing an empty string to SetProcedurePath. This problem has been fixed.
• The Programmer's Guide incorrectly stated that .NET client profiles are supported in HALCON 13.0. This problem has been fixed.
• The Programmer's Manual has been extended by the information that HALCON uses spinlocks by default, and what problems can thus occur when using real-time scheduling or more threads than available CPUs. 
• The Programmer's Guide has been extended by some general hints for developing graphical applications.
• Since HALCON 12.0.2, the mechanism to terminate the HALCON library has been changed by introducing a new function FinalizeHALCONLibrary(). Now, the correct way to close all HALCON threads and free resources is to call the function FinalizeHALCONLibrary() before unloading halcon.dll. The Programmer's Guide missed this information. This problem has been fixed.
• The Programmer's Guide has been updated regarding the changes in the HALCON Variable Inspect extension for Visual Studio.
• The HSmartWindowControl and HSmartWindowControlWPF now provide the event HErrorNotify. This event allows the user to react to errors that take place internally within the control, but can have external causes, like for example an unplugged dongle or a missing license file. The Programmer's Guide has been adapted accordingly.
• The list of error codes in the Extension Package Programmer's Manual was missing some error messages regarding license errors. This problem has been fixed.

• The SemType of the output parameter Angle of the operators angle_ll and angle_lx was real when it should have been angle.rad. This problem has been fixed.
• The reference manual entry of apply_metrology_model has been slightly enhanced to clarify that for fitting a second instance of the metrology object no edge positions are used that were already used for the fitting of the first instance.
• The reference manual entry of find_data_code_2d contained a link to a wrong operator. This problem has been fixed.
• The reference manual entries for
  • find_shape_model,
  • find_shape_models,
  • find_aniso_shape_model,
  • find_aniso_shape_models,
  • find_scaled_shape_model, and
  • find_scaled_shape_models
  have been extended to also describe possible behavior at the border of the image or a reduced domain.
• In the reference manual entry of find_surface_model, the description of the settings 'fast' and 'mls' of the parameter 'scene_normal_computation' has been improved. In the 'fast' mode, if the 3D scene already contains normals, these are used. In contrast, in the 'mls' mode, the normals of the sampled scene are computed anew, regardless whether it already contains normals or not.
• In the reference manual entry of get_data_code_2d_results, it was incorrectly described that the parameter 'decode' in 'quality_isoiec15415' always takes the grade 4, meaning that the code could be decoded. Actually, the decode quality is graded 4 when the code could be decoded according to the reference decode algorithm defined in the standard, and 0 otherwise. This problem has been fixed. Note that HALCON's decode algorithm differs from the reference decode algorithm. Thus, in many cases HALCON can decode the symbol although the decode grade according to the standard is 0.
• Since HALCON 13.0, get_font_extents and get_string_extents return floating point precise values. However, the output parameters still had the semantic type "integer". This problem has been fixed.
• The reference manual entry of get_system did not mention in which unit the values for 'temporary_mem_reservoir_block_sizes' and 'tsp_temporary_mem_cache_block_sizes' are given (bytes). This problem has been fixed.
• The reference manual entry of gray_projections now describes the special case when there are no region points available for the calculation of particular projections.
• The reference manual entry of lines_gauss has been extended by a short explanation of the 'contrast' attribute.
• The reference manual entry of paint_xld has been improved. It was not clear enough what 'touching segments' meant. Now, it is described more clearly that segments that are very close (lying in neighboring pixels) do not work correctly with this operator, and that you can influence the behavior with the set_system parameter 'neighborhood'. Additionally, the parameter description of 'neighborhood' in the manual reference entry of set_system has been extended with an image explaining the two settings.
• In the English and Japanese reference manual entries of points_harris, the Attention text was not complete. This problem has been fixed.
• The reference manual entries of set_color and dev_set_color have been extended with a color table to simplify the selection of transparent colors.
• The code example in the reference manual entry of set_font has not been adapted to the new font notation introduced with HALCON 13.0. This problem has been fixed.
• Since HALCON 13, using the set_system parameter 'flush_graphic' is no longer recommended as it might lead to unexpected results. Instead, it is recommended to set the parameter 'flush' of set_window_param to 'false' and then call flush_buffer to transfer the buffer to the graphics window. The reference manual entry of set_system has been adapted accordingly.
• The reference manual entry of tuple_split stated that the examined strings are split into the substrings between the separators. This was not quite correct. Actually, it splits the strings into the substrings divided by the separators. This problem has been fixed.
• The reference manual entry of write_object_model_3d has been improved to state more clearly which attributes could be stored in the *.obj file format using HALCON. In particular, HALCON supports the writing of 3D points, polygons, normals, and triangles (which are stored as polygons).
• The documentation of descriptor-based matching has been improved. The documentation was inconsistent regarding the planarity of the objects that can be matched. Now, both the reference manual and the Solution Guide Matching explain that the part of the object that is visible in the image when creating the descriptor-based matching model needs to be planar.

• The documentation of descriptor-based matching has been improved. The documentation was inconsistent regarding the planarity of the objects that can be matched. Now, both the reference manual and the Solution Guide Matching explain that the part of the object that is visible in the image when creating the descriptor-based matching model needs to be planar.

• The Installation Guide has been extended with information regarding restrictions related to CodeMeter dongles and the CodeMeter Runtime version. Actually, if you are using a CodeMeter dongle and CodeMeter Runtime is running, CodeMeter Runtime needs to be at least version 5.00. Otherwise, the dongle is not recognized correctly and HALCON throws an error regarding the license file.
• The chapter "Programming HDevelop" in the HDevelop User's Guide has been slightly extended to show how to explicitly open graphics windows in the program.
• In the documentation, now also Windows 8.1 is listed as supported platform.

• The profiles generated by the Linux installer when installing to a relative path did not set the environment variables correctly. This problem has been fixed.
• The I/O integration interface example hioExample was missing. In particular, the following files were missing: CIOEvent.cpp, CIOEvent.h, CIOVirtualDAQ.cpp, CIOVirtualDAQ.h, CIOVirtual.h, hioExample.cpp, hioExample_param.h, and hioExample_param.in. Furthermore, the complete directory io_integration/doc was missing. These problems have been fixed.
• On macOS, the two header files HMessageQueue.h and HObjectModel3D.h were missing. This problem has been fixed.
• After uninstalling HALCON, a previous active version was not restored. This problem has been fixed. Now, the path and the COM library of the previous active version are restored again.
• After uninstalling HALCON, the path of a previous active version was not restored correctly. The HALCON entries in the path environment variable were not separated by semicolons. This problem has been fixed.
• HALCON is now also available for ARM-based platforms.  I.e., the Linux installer, which can be downloaded as usual from the MVTec website, has been extended by the option to additionally install the components necessary for ARM-based platforms. These components include:
  • HALCON libraries including HDevEngine,
  • two example programs for C++ and HDevEngine,
  • image acquisition interfaces (Video4Linux2, File, GenICamTL, GigEVision), and
  • a tar-file for the installation of the runtime files on an ARM-based platform.
  Additionally, hbench has been extended by a new reference CPU, which is an ARM Cortex-A9.
• For the Linux installation, the requirement for LSB compliance has been removed.

• When encountering an empty license file, HALCON could have crashed. This problem has been fixed.
• If a license file started with an UTF-8 byte order marker, HALCON ignored the first license entry. This problem has been fixed.
• The Installation Guide has been extended with information regarding restrictions related to CodeMeter dongles and the CodeMeter Runtime version. Actually, if you are using a CodeMeter dongle and CodeMeter Runtime is running, CodeMeter Runtime needs to be at least version 5.00. Otherwise, the dongle is not recognized correctly and HALCON throws an error regarding the license file.
• In rare cases HALCON rejected certain valid MAC addresses for licensing. This problem has been fixed.
• When using dongle licenses and starting HALCON processes simultaneously, some processes might have exited with an license error on Windows platforms. This problem has been fixed.
• On macOS, HALCON could not correctly detect CodeMeter dongles if CodeMeter Runtime was installed. This problem has been fixed.
• When using a dongle for licensing, HALCON now regularly checks if the dongle is still available.
  
• The list of error codes in the Extension Package Programmer's Manual was missing some error messages regarding license errors. This problem has been fixed.

• The HALCON compiler hcomp did not always write all warning and error messages to stderr. Additionally, on Windows, all output was written to stdout instead of stderr. These problems have been fixed.