Skip to content

HDevEngine in .NET applicationsπŸ”—

This chapter explains how to use HDevEngine in C# and VB.NET applications. The .NET classes are very similar to the C++ classes. Their exact definition is available in the IDE help and in the generated API reference.

BasicsπŸ”—

The C++ classes described in About the main classes and methods of HDevEngine have direct .NET counterparts. The object model is similar, but the member names and parameter handling follow the .NET conventions.

Adding HDevEngine to a .NET applicationπŸ”—

No HDevEngine-specific actions are required. See the general instructions for adding HALCON .NET support to a .NET Core application.

To use HDevEngine in Visual Studio, add a reference to the HDevEngine .NET assembly. The assembly is typically part of the HALCON .NET installation and is added via the Solution Explorer.

If you want to use the XL variant, use the XL versions of the HALCON .NET and HDevEngine .NET assemblies instead.

ExamplesπŸ”—

This section explains how to use HDevEngine in .NET applications. The .NET classes are very similar to the C++ classes. Their exact definition can be seen in the IDE help and in the generated API reference.

The example applications show how to:

  • execute an HDevelop program
  • execute HDevelop procedures
  • implement display operators
  • handle errors
  • use multithreading

Creating an HDevEngine/.NET applicationπŸ”—

This section explains how to create a simple HDevEngine/.NET application with .NET Core. For a more comprehensive description, read Using HDevEngine/.NET.

  1. Install the .NET Core SDK for your system.
  2. Run the following commands in a command line:

    dotnet new console -n hdevengine-example
    cd hdevengine-example
    dotnet add package MVTec.HalconDotNet -v 26111
    
  3. Change the content of Program.cs to:

    using System;
    using System.Diagnostics;
    using System.IO;
    
    using HalconDotNet;
    
    namespace hdevengine_example
    {
      class Program
      {
        static void Main(string[] args)
        {
          string ExampleDir = HSystem.GetSystem("example_dir");
          string ProcedurePath = "/hdevengine/procedures";
    
          HDevEngine Engine = new HDevEngine();
          Engine.SetProcedurePath(Path.GetFullPath(ExampleDir + ProcedurePath));
    
          HImage Image = new HImage("fin2");
    
          HDevProcedure Procedure = new HDevProcedure("detect_fin");
          HDevProcedureCall ProcCall = new HDevProcedureCall(Procedure);
    
          ProcCall.SetInputIconicParamObject("Image", Image);
          ProcCall.Execute();
    
          HTuple FinArea = ProcCall.GetOutputCtrlParamTuple("FinArea");
          Console.WriteLine(String.Format("Fin Area: {0}", FinArea.I));
        }
      }
    }
    
  4. To run the application, type the following command in a command line:

    dotnet run
    

    β€· As a result, you should see the following output: Fin Area: 1634.

Using HDevEngine/.NETπŸ”—

This section explains how to use HDevEngine/.NET with the help of example applications written in C#. These applications reside in the subdirectory %HALCONEXAMPLES%\hdevengine\c#. Most examples use Windows Forms, which is only available for .NET Core on Windows. The HDevEngine/.NET-specific information also applies to .NET Core in general.

For some examples, Visual Basic .NET versions are available in %HALCONEXAMPLES%\hdevengine\vb.net. They are identical except for the standard differences between the two languages.

The example applications show how to:

  • execute an HDevelop program
  • execute HDevelop procedures
  • implement display operators
  • handle errors
  • use multithreading

Executing an HDevelop programπŸ”—

In this section, we explain how to load and execute an HDevelop program with HDevEngine. The code fragments stem from the example application ExecProgram, which checks the boundary of a plastic part for fins. The application contains two buttons to load and execute the HDevelop program.

Step 1: InitializationπŸ”—

First, we create a global instance of the main HDevEngine class clHDevEngineName.

private HDevEngine MyEngine = new HDevEngine();

Upon loading the form, we store the path to the HDevelop program and set the external procedure path with the method SetProcedurePath:

string ProgramPathString;

private void ExecProgramForm_Load(object sender, System.EventArgs e)
{
  string ExampleDir = HSystem.GetSystem("example_dir");
  string ProcedurePath = "/hdevengine/procedures";
  MyEngine.SetProcedurePath(Path.GetFullPath(ExampleDir + ProcedurePath));

  ProgramPathString = Path.GetFullPath(
    ExampleDir + "/hdevengine/hdevelop/fin_detection.hdev"
  );
}

Note that the latter is only necessary if the HDevelop program calls external procedures.

Step 2: Load programπŸ”—

When you click the button to load the HDevelop program, an instance of the class clHDevProgramName is created with the path of the program as a parameter. Furthermore, an instance of clHDevProgramCallName is created for later use. Note that the working directory changes when a program is loaded.

Exceptions occurring in the constructors are handled with the standard C# error handling mechanism:

private void LoadBtn_Click(object sender, System.EventArgs e)
{
  try
  {
    HDevProgram Program = new HDevProgram(ProgramPathString);
    ProgramCall = new HDevProgramCall(Program);
  }
  catch (HDevEngineException Ex)
  {
    MessageBox.Show(Ex.Message, "HDevEngine Exception");
    return;
  }

  ...
}

More information on error handling can be found in Error handling.

Step 3: Execute programπŸ”—

When you click the button to execute the program, the method Execute is called:

private void RunProgram()
{
  try
  {
    try
    {
      ProgramCall.Execute();
    }
  ...
  }
}

Step 4: Get resultsπŸ”—

That is all you need to do to execute an HDevelop program. You can also access its results, i.e., its variables, with the method GetCtrlVarTuple. In the example program, the area of the extracted fin is queried and displayed:

double FinArea;
FinArea = ProgramCall.GetCtrlVarTuple("FinArea");
Window.SetTposition(150, 20);
Window.WriteString("Fin Area: ");

Note that program variables can only be accessed when the program has terminated.

General: display resultsπŸ”—

How to display results while the program is running is described in Display.

Executing HDevelop proceduresπŸ”—

This section describes example applications that execute HDevelop procedures.

  • a single external procedure
  • multiple local and external procedures

Executing an external HDevelop procedureπŸ”—

In this section, we explain how to load and execute an external HDevelop procedure with HDevEngine. The code fragments stem from the example application ExecExtProc, which checks the boundary of a plastic part for fins. The result display is programmed explicitly instead of relying on the internal display operators.

Step 1: InitializationπŸ”—

As when executing an HDevelop program, we create a global instance of the main HDevEngine class and set the external procedure path when the form is loaded. If the external procedure comes from a procedure library, the external procedure path may include the name of the library file.

private HDevEngine MyEngine = new HDevEngine();

private void ExecExtProcForm_Load(object sender, System.EventArgs e)
{
  string ProcedurePath = "/hdevengine/procedures";
  ...
  MyEngine.SetProcedurePath(Path.GetFullPath(ExampleDir + ProcedurePath));
}

In contrast to the C++ version of this example application, we want to display the results not in a free-floating graphics window, but inside the form, that is, inside an instance of HSmartWindowControl. For calling HALCON operators, we declare a global variable of the class HWindow for the underlying HALCON window. Upon loading the form, we set this variable to the HALCON window in the HSmartWindowControl and initialize the window:

private HWindow Window;

private void WindowControl_Load(object sender, EventArgs e)
{
  Window = WindowControl.HalconWindow;

  Window.SetDraw("margin");
  Window.SetLineWidth(4);
}

Step 2: Load procedureπŸ”—

When you click the button Load, the HDevelop procedure is loaded with the constructor of the class clHDevProcedureName, specifying the name of the procedure. A corresponding procedure call is created as an instance of the class clHDevProcedureCallName. Exceptions occurring in the constructors are handled with the standard C# error handling mechanism. More information on error handling can be found in Error handling.

private void LoadBtn_Click(object sender, System.EventArgs e)
{
  try
  {
    HDevProcedure Procedure = new HDevProcedure("detect_fin");
    ProcCall = new HDevProcedureCall(Procedure);
  }
  catch (HDevEngineException Ex)
  {
    MessageBox.Show(Ex.Message, "HDevEngine Exception");
    return;
  }
}

Executing a procedure consists of multiple steps. First, we load an example image sequence:

private void ExecuteBtn_Click(object sender, System.EventArgs e)
{
  HFramegrabber Framegrabber = new HFramegrabber();
  Framegrabber.OpenFramegrabber("File", 1, 1, 0, 0, 0, 0, "default",
     -1, "default", -1, "default", "fin.seq", "default", -1, -1);

Step 3: Set input parameters of the procedureπŸ”—

Each image should now be processed by the procedure, which has the following signature:

procedure detect_fin (Image: FinRegion: : FinArea)

We pass the image as an input object by storing it in the instance of clHDevProcedureCallName with the method SetInputIconicParamObject. Which parameter is set is specified via its name; as an alternative, you can specify it via its index.

HImage Image = new HImage();
HRegion FinRegion;
HTuple FinArea;

for (int i = 0; i <= 2; i++)
{
  Image.GrabImage(Framegrabber);
  Image.DispObj(Window);

  ProcCall.SetInputIconicParamObject("Image", Image);

As an alternative to passing parameters, you can also use global variables in HDevEngine. You set the value of a global variable with the methods SetGlobalIconicVarObject or SetGlobalCtrlVarTuple and query it with GetGlobalIconicVarObject or GetGlobalCtrlVarTuple. However, take care not to overwrite the value of a variable of one program with that of another, because each global variable can have only one value at a time for all running HDevEngine instances.

Step 4: Execute procedureπŸ”—

Now, we execute the procedure with the method Execute:

ProcCall.Execute();

Step 5: Get output parameters of the procedureπŸ”—

If the procedure was executed successfully, we can access its results, i.e., the fin region and its area, with the methods GetOutputIconicParamRegion and GetOutputCtrlParamTuple of the class clHDevProcedureCallName. Again, you can specify the parameter via its name or index. Note that you can get iconic output objects either as instances of the corresponding class, here HRegion, or as instances of HObject by using GetOutputIconicParamObject.

FinRegion = ProcCall.GetOutputIconicParamRegion("FinRegion");
FinArea = ProcCall.GetOutputCtrlParamTuple("FinArea");

Step 6: Display results of the procedureπŸ”—

Finally, we display the results in the graphics window:

this.Invoke((MethodInvoker)delegate
{
  Image.DispObj(Window);
  Window.SetColor("red");
  Window.DispObj(FinRegion);
  Window.SetColor("white");
  Window.SetTposition(150, 20);
  Window.WriteString("FinArea: " + FinArea.D);
});

Executing local and external HDevelop proceduresπŸ”—

The example application ExecProcedures executes local and external HDevelop procedures with HDevEngine. It mimics the behavior of the HDevelop program described in Executing an HDevelop program. The display of results is partly programmed explicitly and partly delegated to an HDevelop procedure using the implementation of the internal display operators described in Display.

Local and external procedures are created and executed in exactly the same way. The only difference is that, in order to use a local procedure, you must load the program it is contained in, whereas to load external procedures you must set the procedure path. In the example, the image-processing procedure is local and the other is external.

private HDevProcedureCall InitAcqProcCall;
private HDevProcedureCall ProcessImageProcCall;
private HDevProcedureCall VisualizeDetailsProcCall;

private void ExecProceduresForm_Load(object sender, System.EventArgs e)
{
  string ProcedurePath = "/hdevengine/procedures";
  ...
  MyEngine.SetProcedurePath(Path.GetFullPath(ExampleDir + ProcedurePath));
}
private void LoadBtn_Click(object sender, System.EventArgs e)
{
  try
  {
    HDevProgram Program = new HDevProgram(ProgramPathString);

    HDevProcedure InitAcqProc = new HDevProcedure(Program, "init_acquisition");
    HDevProcedure ProcessImageProc = new HDevProcedure(Program, "detect_fin");
    HDevProcedure VisualizeDetailsProc =
          new HDevProcedure(Program, "display_zoomed_region");

    InitAcqProcCall = new HDevProcedureCall(InitAcqProc);
    ProcessImageProcCall = new HDevProcedureCall(ProcessImageProc);
    VisualizeDetailsProcCall = new HDevProcedureCall(VisualizeDetailsProc);
  ...
}

One of the procedures opens the image acquisition device. It returns the corresponding handle, which is stored in an instance of the class HFramegrabber.

private HFramegrabber Framegrabber;

private void InitAcqBtn_Click(object sender, System.EventArgs e)
{
  InitAcqProcCall.Execute();
  Framegrabber =
      new HFramegrabber(InitAcqProcCall.GetOutputCtrlParamTuple("AcqHandle").H);
  ...
}

In the example application, the device is closed when the application terminates and calls the finalizer of the class HFramegrabber, which in turn calls the operator CloseFramegrabber. If you use an HDevelop procedure for closing the connection to the device, you would invalidate the handle so that the finalizer raises an exception.

As in the previous example, the results of image processing are displayed manually by calling HALCON/.NET operators. When the button Visualize Details is clicked, an HDevelop procedure is executed that zooms into the extracted fin. For this, we pass an implementation of HDevelop’s internal display operators and remove it again after the procedure has been executed.

private void VisualizeDetailsBtn_Click(object sender, System.EventArgs e)
{
  MyEngine.SetHDevOperators(MyHDevOperatorImpl);

  VisualizeDetailsProcCall.SetInputIconicParamObject("Image", Image);
  VisualizeDetailsProcCall.SetInputIconicParamObject("Region", FinRegion);
  VisualizeDetailsProcCall.SetInputCtrlParamTuple("ZoomScale", 2);
  VisualizeDetailsProcCall.SetInputCtrlParamTuple("Margin", 5);
  VisualizeDetailsProcCall.Execute();

  MyEngine.SetHDevOperators(null);
}

The instance of the implementation class is initialized with the HALCON window of the form.

private HDevOpMultiWindowImpl MyHDevOperatorImpl;

private void WindowControl_Load(object sender, EventArgs e)
{
  Window = WindowControl.HalconWindow;
  ...
  MyHDevOperatorImpl = new HDevOpMultiWindowImpl(Window);
}

If the class HDevOpMultiWindowImpl is initialized without specifying the window, a new HALCON window opens automatically to emulate the behavior of HDevelop. Consequently, using the operator dev_open_window in your HDevelop program or procedure opens another window. The newly opened window is set active automatically.

DisplayπŸ”—

In contrast to the C++ version of HDevEngine, HDevEngine/.NET already provides convenience implementations of HDevelop’s internal display operators in the form of two classes:

  • HDevOpFixedWindowImpl directs all display operators to a single graphics window passed to the constructor, even if the HDevelop program or procedure uses multiple windows.
  • HDevOpMultiWindowImpl can handle multiple graphics windows. You can pass an arbitrary number of graphics windows in the constructor; if the HDevelop program or procedure uses more than these, HDevEngine opens additional free-floating windows.

In the example code, some of the actual program and procedure execution is delegated to a background thread. This is good practice, because long-running execution would otherwise lead to an unresponsive GUI. Furthermore, HDevelop code that uses interactive drawing objects would not work with HSmartWindowControl if the GUI thread is blocked.

While HALCON display operators are thread-safe, access to Windows Forms elements is not. For example, enabling buttons or setting label texts is not thread-safe. Therefore, result visualization is delegated back to the GUI thread using Invoke() calls in these examples.

Finally, using dev_* operators for visualization via HDevOpFixedWindowImpl or HDevOpMultiWindowImpl is limited in multithreaded applications that execute multiple procedures in parallel. This is because there is only one global active window at any given time, as controlled by dev_set_window, so threads cannot control their output windows independently. This behavior is consistent with HDevelop, which also has only one active window when using multiple threads via par_start.

If parallel visualization is desired, we recommend writing explicit visualization code using HALCON operators that output directly to the desired window. For more information, see Creating multithreaded applications.

The example program ExecProgram uses HDevOpMultiWindowImpl. To use this class, or HDevOpFixedWindowImpl, pass an instance of it to HDevEngine with the method SetHDevOperators:

private void WindowControl_Load(object sender, EventArgs e)
{
  Window = WindowControl.HalconWindow;

  MyEngine.SetHDevOperators(new HDevOpMultiWindowImpl(Window));
}

If your application has special display requirements that are not satisfied by these two classes, you can provide your own implementation of the display operators similar to the C++ version of HDevelop by creating a class implementing the interface IHDevOperators and overriding methods such as DevOpenWindow, DevDisplay, and others.

Error handlingπŸ”—

In this section, we take a closer look at exceptions in HDevEngine. The code fragments in the following stem from the example application ErrorHandling, which provokes and catches different types of exceptions when you press some buttons.

HDevEngine throws exceptions as instances of the class clHDevEngineExceptionName, which contains the exception type, a message describing the exception, and, depending on the exception type, information such as the name of the executed procedure or the HALCON error code.

In the example application, the following procedure displays all the information contained in clHDevEngineExceptionName in a message box:

private void DisplayException(HDevEngineException Ex)
{
  string FullMessage = "Message: <" + Ex.Message + ">" +
    ",  Error in program / procedure: <" + Ex.ProcedureName + ">" +
    ",  program line: <" + Ex.LineText + ">" +
    ",  line number: <" + Ex.LineNumber + ">" +
    ",  HALCON Error Number: <" + Ex.HalconError + ">";

  string Title = "HDevEngine Exception (Category: " +
    Ex.Category.ToString() + ")";

  MessageBox.Show(FullMessage, Title);
}

This procedure is called when an exception occurs. The example applications described in the previous sections display only the exception message.

try
{
  HDevProgram Program = new HDevProgram(ProgramPathString);
  new HDevProgramCall(Program);
}
catch (HDevEngineException Ex)
{
  DisplayException(Ex);
  return;
}

The first exception occurs when the application tries to load a non-existing HDevelop program. In this case, only the message contains useful information.

The next exception occurs when executing a procedure in which an input parameter is not initialized. This now contains very detailed information about where the error occurred and why.

The final exception is triggered when executing a procedure in which the call to the operator closing_circle fails because the third parameter is invalid.

procedure detect_fin_with_error_inpnotinit (Image: FinRegion: : FinArea)
  binary_threshold (NotExistingImage, Dark, 'max_separability', 'dark', UsedThreshold)
  ...
procedure detect_fin_with_error_call (Image: FinRegion: : FinArea)
  binary_threshold (Image, Dark, 'max_separability', 'dark', UsedThreshold)
  difference (Image, Dark, Background)
  dev_set_color ('blue')
  dev_display (Background)
  closing_circle (Background, ClosedBackground, -1)
  ...

With the method UserData, you can also access user exception data that is thrown within an HDevelop program or procedure by the operator throw, similarly to dev_get_exception_data.

If an exception is not caught within the procedure, the procedure call is cleaned up. This destroys all subthreads and clears all values of the input and output parameters. Therefore, we recommend that you always set all input parameters before executing a call, even if some of them did not change.

Note that you can configure the behavior of HDevEngine when loading programs or procedures that contain invalid lines or unresolved procedure calls with the method SetEngineAttribute.

Creating multithreaded applicationsπŸ”—

HALCON provides two C# example applications that use multithreading with HDevEngine/.NET:

  • MultiThreading speeds up the application by executing the same HDevelop procedure in parallel using two threads.
  • MultiThreadingTwoWindows executes different procedures in parallel.

In the following, we briefly list the most important rules to observe when creating multithreaded HDevEngine applications. Also look at the general information about parallel programming using HALCON.

  • When multiple threads execute HDevelop programs in parallel, each thread must create its own instance of the corresponding clHDevProgramCallName.
  • The external procedure path and the implementation of HDevelop’s display operators are global settings for all HDevEngine instances.
  • We recommend setting them via a separate HDevEngine instance to keep the code more readable.

Executing a procedure in parallel by multiple threadsπŸ”—

The example application MultiThreading exploits multi-core or multi-processor systems by executing the same HDevelop procedure in parallel by two threads. The procedure finds bottle caps using shape-based matching.

The main thread initializes the application by training the shape model via an HDevelop procedure and by creating and initializing the other three threads: two processing threads and the control thread, which controls the two processing threads.

The control thread acquires the images and passes them to the processing threads, which process the images and pass back the results. The control thread collects the results, but does not display them itself, because all activities in the HALCON window must be performed by the thread that created it, namely the main thread.

The application is initialized in the event handler of the Init button.

private void InitButton_Click(object sender, System.EventArgs e)

Switch off automatic operator parallelization:

HOperatorSet.SetSystem("parallelize_operators", "false");

Then create an instance of clHDevEngineName and set the path for searching the HDevelop procedures:

HDevEngine MyEngine = new HDevEngine();
string ProcedurePath = "/hdevengine/procedures";
...
MyEngine.SetProcedurePath(Path.GetFullPath(ExampleDir + ProcedurePath));

Train the shape model:

HDevProcedureCall ProcTrain;

HDevProcedure Procedure = new HDevProcedure("train_shape_model");
ProcTrain = new HDevProcedureCall(Procedure);
ProcTrain.Execute();

Store the model data:

public HTuple ModelID;
public HXLD ModelContours;

ModelID = ProcTrain.GetOutputCtrlParamTuple("ModelID");
ModelContours = ProcTrain.GetOutputIconicParamXld("ModelContours");

Create and initialize the processing engines:

public class EngineThread
{
  Thread WorkerObject = null;
  HDevProcedureCall ProcCall;
  HTuple ModelID;
  HXLD ModelContours;
  public AutoResetEvent EngineIsReady;

  public EngineThread(MultiThreadingForm mainForm)
  {
    ModelID = mainForm.ModelID;
    ModelContours = mainForm.ModelContours;
    EngineIsReady = new AutoResetEvent(true);
  }

The main thread creates and initializes two instances of this class and stores their events:

EngineThread WorkerEngine1;
EngineThread WorkerEngine2;
AutoResetEvent Engine1Ready;
AutoResetEvent Engine2Ready;

WorkerEngine1 = new EngineThread(this);
WorkerEngine1.Init();
Engine1Ready = WorkerEngine1.EngineIsReady;

WorkerEngine2 = new EngineThread(this);
WorkerEngine2.Init();
Engine2Ready = WorkerEngine2.EngineIsReady;

An EngineThread initializes itself by creating the procedure call for detecting the caps in the images. Because the input parameters concerning the shape model are the same for each call, they can be set once in advance:

public void Init()
{
  HDevProcedure Procedure = new HDevProcedure("detect_shape");
  ProcCall = new HDevProcedureCall(Procedure);
  ProcCall.SetInputCtrlParamTuple("ModelID", ModelID);
  ProcCall.SetInputIconicParamObject("ModelContours", ModelContours);
}

Finally, initialize the image acquisition. The handle is stored in a variable of the form so that the control thread can access it.

private HFramegrabber AcqHandle;

string ImagePath = Path.GetFullPath(ExampleDir + "/images/cap_illumination");
AcqHandle = new HFramegrabber("File", 1, 1, 0, 0, 0, 0, "default", -1,
  "default", -1, "default", ImagePath, "default", -1, -1);

When the user clicks the Run button, the application starts processing images in a loop.

private void RunButton_Click(object sender, System.EventArgs e)
{
  WorkerEngine1.Run();
  WorkerEngine2.Run();

The corresponding method creates and starts the thread and sets the ready signal:

public void Run()
{
  EngineIsReady.Set();
  WorkerObject = new Thread(new ThreadStart(Process));
  WorkerObject.Start();
}

Then the main thread starts the control thread:

ControlThread = new Thread(new ThreadStart(Run));
ControlThread.Start();

The control thread waits until one of the processing engines is ready and then acquires the next image and passes it to the engine:

EngineThread WorkerEngine;

public void Run()
{
  HImage Image;

  while (!StopEventHandle.WaitOne(0, true))
  {
    if (Engine1Ready.WaitOne(0, true))
      WorkerEngine = WorkerEngine1;
    else if (Engine2Ready.WaitOne(0, true))
      WorkerEngine = WorkerEngine2;
    else
      continue;

    Image = AcqHandle.GrabImageAsync(-1);
    WorkerEngine.SetImage(Image);

The engine stores the image in a member variable:

private HImage InputImage = null;

public void SetImage(HImage Img)
{
  InputImage = Img;
}

The processing threads wait until an image is available and then execute the HDevelop procedure with that image as input:

public void Process()
{
  while (!DelegatedStopEvent.WaitOne(0, true))
  {
    if (InputImage == null)
      continue;

    ProcCall.SetInputIconicParamObject("Image", InputImage);
    ProcCall.Execute();

These examples show the same pattern used throughout the .NET interface: configure the engine once, create independent call objects per worker, and keep the shared global state to a minimum.