Creating an application with HALCON Script Engine

Preview restriction

HALCON Script Engine supports C++ and .NET Core at the moment. Hence, only these languages are described in the following.

At a glance

C++.NET

The following settings are required for a project to use HALCON Script Engine with C++:

WindowsLinux

• Include path: %HALCONROOT%\include
• Library path: %HALCONROOT%\lib\%HALCONARCH%
  (runtime libraries: hscriptenginecpp.dll and halconcpp.dll)
• Include file: hscriptenginecpp\HScriptEngine.h

• Link libraries: hscriptenginecpp.lib and halconcpp.lib (as the API is based on HALCON/C++)

  HALCON XL applications

  If you want to use HALCON XL, link the libraries hscriptenginecppxl.lib and halconcppxl.lib instead.
  Only use HALCON XL when you need its features.

• Include path: $HALCONROOT/include
• Library path: $HALCONROOT/lib/$HALCONARCH
• Include file: hscriptenginecpp/HScriptEngine.h

• Link libraries: libhscriptenginecpp.so and libhalconcpp.so (as the API is based on HALCON/C++)

  HALCON XL applications

  If you want to use HALCON XL, link the libraries libhscriptenginecppxl.so and libhalconcppxl.so instead.
  Only use HALCON XL when you need its features.

The following settings are required for a project to use HALCON Script Engine with .NET (C#, Visual Basic.NET, etc.).

Adding a package reference for HALCON/.NET

You need the following NuGet  packages for a HScriptEngine/.NET application:

MVTec.HScriptEngineDotNet

This package is dependent on MVTec.HalconDotNet, which will be pulled automatically.

MVTec.HalconDotNet-Windows (optional)

This package targets .NET Core 3.1 and additionally includes Windows Forms and WPF controls for integrating HALCON windows into GUI applications. Required when using HWindowControl. This package can only be used on Windows as other .NET Core 3.1 implementations do not offer Windows Forms or WPF support.

HALCON XL applications

If you want to use HALCON XL, use the corresponding XL packages MVTec.HScriptEngineDotNetXL (with dependency MVTec.HalconDotNetXL) and MVTec.HalconDotNetXL-Windows instead.
Only use HALCON XL when you need its features.

Use the following command to add package references to your project:

dotnet add package <PACKAGE_NAME> -v 26050

About versioning

While NuGet uses semantic versioning (“SemVer”)  to version packages, HALCON versions are not SemVer compatible. To avoid unnecessary conflicts, .NET Core packages receive a SemVer-compatible version by combining the major, minor, and revision into a new version, for example:

Table 1: SemVer-compatible versions of HALCON/.NET for .NET Core

HALCON version		HALCON/.NET package version
22.11.1	→	22111.0.0
25.11.0	→	25110.0.0
26.05.0	→	26050.0.0

HALCON/.NET is not a self-contained package but an interface to the native HALCON library. Therefore, the package version used by your project has to match the installed HALCON version exactly.

Even for maintenance releases, which are backwards compatible at application level, mixing of binaries from different releases is not recommended because the internal communication between HALCON/.NET and the native HALCON library is not guaranteed to be always compatible. Therefore, the revision of the HALCON release is also part of the SemVer major version.
The SemVer minor and patch version are reserved for fully backwards-compatible intermediate releases of the package itself. See Using a newer HALCON/.NET release for updating dependencies.

Updating to a newer HALCON/.NET release

.NET Core projects resolve a specific version the moment you add the package. If you want to update to a newer HALCON version, for example from 25.11.0 to 26.05.0, you must change the version specified in your project.

Example

For example, change your project’s .csproj from

<PackageReference Include="MVTec.HScriptEngineDotNet" Version="25110.0.0 " />

to

<PackageReference Include="MVTec.HScriptEngineDotNet" Version="26050.0.0" />

For the available classes and methods, see About the main classes and methods of HALCON Script Engine.

How to develop applications with HALCON Script Engine

With HALCON Script Engine, you can execute complete HALCON Script programs or individual procedures. Note that HALCON Script and thus HALCON Script Engine do not differentiate between programs and procedures: A program is just the “main” procedure.

Which approach is better depends on the stage of development and on your task:

• When developing the image processing part of your application, you create a HALCON Script program. Thus, as a first test of your application, it is useful to execute the program via HALCON Script Engine. This test will already assure that the general configuration of your application (environment variables, procedure path, etc.) is correct. The HALCON Script Engine program itself should of course use the same procedures that you plan to execute from the programmed application.
• After you finished its development, you integrate the image processing part into your programmed application by executing the corresponding procedures. Typically, you display image processing results by using the methods of the underlying HALCON programming language interface — that is: HALCON/C++ for HScriptEngine/C++, or HALCON/.NET for HScriptEngine/.NET (C#, Visual Basic.NET, etc.) — but you can also encapsulate recurring display tasks in HSCRIPT procedures.

Further, keep the following in mind:

• You can execute only procedures with public scope using the HALCON Script Engine. However, you can execute procedures with private scope either as part of a public procedure or an entire HALCON Script “main” program.
• All occurrences of the stop statement are ignored when executing a program using the HALCON Script Engine.

How to create an executable program with HScriptEngine

C++.NET

The general workflow to create an application with HScriptEngine/C++ is as follows:

1. In your application, include the main header file HScriptEngine.h and use the corresponding namespaces:

   #include "hscriptenginecpp/HScriptEngine.h"
   using namespace HalconCpp;
   using namespace HScriptEngineCpp;
   

2. Compile the application using the following include paths:

   WindowsLinux

   /I "$(HALCONROOT)\include" /I "$(HALCONROOT)\include\halconcpp"
   /I "$(HALCONROOT)\include\hscriptenginecpp"
   

   -I$HALCONROOT/include -I$HALCONROOT/include/halconcpp
   -I$HALCONROOT/include/hscriptenginecpp
   

3. Link the following libraries:

   WindowsLinux

   /libpath:"$(HALCONROOT)\lib\$(HALCONARCH)" hscriptenginecpp.lib halconcpp.lib
   

   If you need HALCON XL, link the corresponding *xl.lib libraries instead.

   -L$HALCONROOT/lib/$HALCONARCH -lhscriptenginecpp -lhalconcpp
   

   If you need HALCON XL, link the corresponding *xl libraries instead.

The workflow to create an application with HScriptEngine/.NET using just a command-line SDK is as follows:

1. Install the .NET Core SDK for your system (.NET Core 3.1 or later).
2. Run the following commands in a command line:

   dotnet new console -n hscriptengine-example
   cd hscriptengine-example
   dotnet add package MVTec.HScriptEngineDotNet -v 26050
   

3. Write the program, for example, Program.cs:

   using System;
   
   using HalconDotNet;
   using HScriptEngineDotNet;
   
   namespace ExecProcedures
   {
     class Program
     {
      ...
     }
   }
   

4. To execute the application, run the following command in a command line:

   dotnet run
   

Tip

You can of course also use an IDE like Visual Studio 2022 (or later) to create a project of the desired type. Use the package manager to add a reference to MVTec.HScriptEngineDotNet.

For more information, see the example project.