You are here: Start » Technical Issues » .NET Macrofilter Interface Generator

.NET Macrofilter Interface Generator

Introduction

Generation of macrofilter interfaces allows to design complex applications without loosing comfort of visual programming which comes from the environment of Adaptive Vision Studio.

The most common reasons people choose .NET Macrofilter Interfaces are:

  • Creating applications with very complex or highly interactive HMI.
  • Creating applications that connect to external databases or devices which can be accessed more easily with .NET libraries.
  • Creating flexible systems which can be modified without recompiling the source code of an application.

Macrofilters can be treated as mini-programs which can be run independently of each other. Adaptive Vision Studio enables to use those macrofilters in such programming languages as C# or C++/CLI and execute them as regular class methods. Because those methods are just interfaces to the macrofilters, there is no need to re-generate the assembly after each change made to the AVCODE (the graphical program).

Requirements

In order to build and use a .NET Macrofilter Interface assembly, the following applications must be present in the user's machine:

BuildingRunning
Adaptive Vision Professional 5.0 Adaptive Vision Professional 5.0 or
Adaptive Vision Runtime 5.0
Microsoft Visual Studio 2015
(or greater)
Microsoft Visual C++ Redistributable Package of the same bitness (32/64) as the generated assembly and the same version as Microsoft Visual Studio used to build the assembly.

.NET Macrofilter Interface Assembly Generator

Macrofilters may be interfaced for use in such managed languages as C# or Visual Basic. Such interface is generated into a Dynamic Link Library (dll), which can be then referenced in a Visual C# project. To generate a dll library for the current Adaptive Vision Studio project, fill in all necessary options in the .NET Macrofilter Interface Generator form that can be opened from File » Generate .NET Macrofilter Interface...

Output page

Namespace
Defines the name of the main library class container.
Macrofilter Interface Class Name
Defines the name of the class, where all macrofilters will be available as methods (with the same signatures as macrofilters).
Generate sample Microsoft Visual Studio solution
Generates empty Microsoft Visual Studio C# WinForms project that uses to-be created Macrofilter .NET Interface assembly.
Link Adaptive Vision Project Files
Includes current Adaptive Vision project files to the C# project as links. This way Adaptive Vision project files (*.avproj, *.avcode, *.avlib) are guaranteed to be easily accessible from the application output directory, e.g. with following line of code (assuming the project is Inspection.avproj):
macrofilters = InspectionMacrofilters.Create(@"adaptivevision\Inspection.avproj");
Path to the generated dll library
Location of the to-be generated assembly.

Interface page

Check box list
List of all macrofilters and User Types defined in the current Adaptive Vision project that a .NET Interface may be generated for.

Compiler page

Environment
Selection of which Microsoft Visual Studio build tools should be used to build an assembly. The drop down list is populated with all detected compatible tools in the system, including Microsoft Visual Studio and Microsoft Visual Studio Build Tools environments. If none of detected are suitable, custom environment may be used. Then, MSBuild.exe location and target Microsoft Visual Studio version properties need to be defined manually.
MSBuild location
Shows the path to the actual MSBuild.exe according to the selected environment. Editable, when Custom environment is selected.
Microsoft Visual Studio version
Defines the generated sample C# project format (sln and csproj files).
Windows SDK version
Allows choosing the appropriate SDK version when generating Macrofilter .Net Interface. The list contains all detected SDK versions in the system.

Advanced page

Assembly Signing
Enables signing the generated Macrofilter .NET Assembly with given private key and makes it a Strong-Named assembly. Keys may be generated e.g. in Strong Name Tool or in Microsoft Visual Studio IDE (C# project properties page).

.NET Macrofilter Interface Assembly Usage

Initialization

Once a generated library is referenced in a Visual C# project, macrofilters chosen in the .NET Macrofilter Interface Assembly Generator form are available as instance methods of the class defined in the Macrofilter Interface Class Name text box (MacrofilterInterfaceClass), in the Output page. However, in order to successfully execute these methods, a few Adaptive Vision libraries must be initialized, i.e. Executor.dll and available Filter Libraries. It is done in a static method named MacrofilterInterfaceClass.Create, so no additional operations are necessary. To achieve the best performance, such initialization should be performed only once in application lifetime, and only one instance of the MacrofilterInterfaceClass class should exist in an application.

MacrofilterInterfaceClass.Create static method receives a path to either *.avcode, *.avproj or *.avexe path, for which the dll library was generated. It is suggested to wrap MacrofilterInterfaceClass instantiating with a try-catch statement, since the Create method may throw exceptions, e.g. when some required libraries are missing or are corrupted.

Finalization

MacrofilterInterfaceClass class implements the IDisposable interface, in which the Dispose() method, libraries' releasing and other cleaning ups are performed. It is a good practice to clean up on application closure.

Bitness

Generated assembly bitness is the same as the used Adaptive Vision Studio bitness. That is why the user application needs to have its target platform adjusted to avoid libraries' format mismatch. For example, if Adaptive Vision Studio 64-bit was used, the user application needs to have its target platform switched to the x64 option.

Diagnostic mode

The macrofilter execution mode can be modified with DiagnosticMode property of the generated Macrofilter .NET Interface class. It enables both checking and enabling/disabling the diagnostic mode.

Dialogs

It is possible to edit geometrical primitives the same way as in Adaptive Vision Studio. All that need to be done is to use appropriate classes from the Avl.NET.Designers.dll assembly. Dialog classes are defined in AvlNet.Designers namespace. For more info see the AVL.NET Dialogs article.

Full AVL.NET

With Adaptive Vision Library installed one can take advantage of full AVL.NET functionality in the applications that use Macrofilter .NET Interface assemblies. Just follow the instructions from Getting Started with Adaptive Vision Library .NET.

Example

Introduction

This example is a step-by-step demonstration of the .NET Macrofilter Interface Assembly generation and usage. To run this example at least Adaptive Vision Studio Professional 5.0 and Microsoft Visual Studio 2015 are required. Visual C# will be used to execute macrofilters.

Creating Adaptive Vision Project

We have to have some Adaptive Vision Studio project, which macrofilter we want to use in our application. For demonstrative purposes the project will be as simple as possible, just thresholding Lena's image with parameters provided in a Visual C# application's GUI. The macrofilter we would like to run in a C# application will be ThresholdLena (see: Creating Macrofilters). The whole macrofilter consists of two filters as in the image below:

A basic ThresholdLena macrofilter used in example.

Generating .NET Macrofilter Interface Assembly

Having a ready Adaptive Vision Studio project, a .NET Macrofilter Interface assembly may be generated from File » Generate .NET Macrofilter Interface.... If the project has not been saved yet, you will be prompted to do it now.

In the Output page of the .NET Macrofilter Interface dialog check the Generate Visual Studio Solution option to create a default C# project with required configuration properly set for the current Adaptive Vision Studio installation. It is suggested to check also the Link Adaptive Vision Project Files check box to include necessary files to the C# project.

In the Interface page check the ThresholdLena to generate .NET Macrofilter Interface for the macrofilter. This macrofilter will be accessible as C# method later on.

When ready, click Generate to generate an assembly, which will allow us to run the ThresholdLena macrofilter in a Visual C# application.

Methods provided by macrofilter interface class.

Using .NET Macrofilter Interface Assembly in a Visual C# application

Having generated the ExampleMacrofilters.dll we may include it into Visual C# application references and have access to the only type exposed by the library, i.e. AdaptiveVision.ExampleMacrofilters class (if you have checked the Generate Visual Studio Solution option in the Generate .NET Macrofilter Interface dialog, you may proceed to the next paragraph since all references are already set, as well as a ready-to-run starter application). Aside from generated ExampleMacrofilters.dll there is also the Avl.NET.TS.dll assembly which has to be referenced if any of the AVL types are used in the application. In this example the AvlNet.Image type will be used to obtain an image from ThresholdLena macrofilter so Avl.NET.TS.dll is essential here.

As it was mentioned before, instantiation of this class should be performed once during application lifetime. As so, Form1's constructor is a perfect place for such an initialization. Instance of the ExampleMacrofilters should be then kept in the Form1 class as a private member:

using AvlNet;
using AdaptiveVision;
    public partial class Form1 : Form
    {

        /// <summary>
        /// Object that provides access to the macrofilters defined in the Adaptive Vision Studio project.
        /// </summary>
        private readonly ThresholdLenaMacrofilters macros;

        public Form1()
        {
            InitializeComponent();
            try
            {
                string avsProjectPath = @"adaptivevision\ThresholdLena.avproj";
                macros = ThresholdLenaMacrofilters.Create(avsProjectPath);
            }
            catch (Exception e)
            {
                MessageBox.Show(e.Message);
            }
        }

ExampleMacrofilters class does not provide a public constructor. Instead, instances of the ExampleMacrofilters class can only be obtained through it's static method Create accepting a path to either *.avcode, *.avproj or *.avexe file. In this example it takes the path to the *.avcode file with the definition of ThresholdLena macrofilter. Example.avcode passed to the Create method means, that the runtime will look for the *.avcode file in the application output directory. To guarantee that this file will be found, it should be included in the project and its "Copy to Output Directory" property should be set to either "Copy always" or "Copy if newer".

The C# project is prepared to run the macrofilters as methods. Since ThresholdLena outputs an image taking two optional float values, which stand for threshold's minimum and maximum values, let's add one PictureBox and two TrackBar controls with value range equal to 0-255:

Changing a value of either of track bars calls the UpdateImage() method, where ThresholdLena macrofilter is executed and calculated image is printed in the PictureBox control:

private void UpdateImage()
{
    try
    {
        //create an empty image buffer to be populated in the ThresholdLena macrofilter
        using (var image = new Image())
        {
            //call macrofilter
            macros.ThresholdLena(minTrackBar.Value, maxTrackBar.Value, image);

            //dispose previous background if necessary
            pictureBox1.Image?.Dispose();

            //get System.Drawing.Bitmap object from resulting AvlNet.Image
            pictureBox1.Image = image.CreateBitmap();
        }
    }
    catch (Exception ex)
    {
        MessageBox.Show(
            ex.Message,
            "Macrofilter Interlace Application",
            MessageBoxButtons.OK, MessageBoxIcon.Error);
    }
}

On application closing, all resources loaded in ExampleMacrofilters.Create(...) method, should be released. It is achieved in ExampleMacrofilters.Dispose() instance method, which should be called during disposing of containing form, in Form1.Dispose(bool) override:

protected override void Dispose(bool disposing)
{
    if (disposing)
    {
        if (components != null)
            components.Dispose();

        //Release resources held by the Macrofilter .NET Interface object
        if (macros != null)
            macros.Dispose();
    }

    base.Dispose(disposing);
}

Hints

  • Generated macrofilter interface class offers also Exit() method which allows user to disconnect from Adaptive Vision environment.
  • Every step macrofilter contains specific resetting method, which resets an internal state. For example method ResetLenaThreshold() resets internal register values and any iteration states.
  • Best way to create an application using macrofilter interfaces is to use encrypted avexe files. It secures application code from further modifications.
  • Diagnostic mode can be switched on and off with IsDiagnosticModeEnabled static property of the AvlNet.Settings class.
  • The application using Macrofilter .NET interface may also reference the AVL's AvlNet.dll assembly to enable direct AVL function calls from the user code (see Getting Started with Adaptive Vision Library .NET for referencing the AvlNet.dll in the user applications).
Previous: C++ Code Generator Next: Remote License Upgrade