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

.NET Macrofilter Interface Generator

• Introduction
• Requirements
• .NET compatibility
• .NET Macrofilter Interface Assembly Generator
  • Output page
  • Interface page
  • Advanced page
• .NET Macrofilter Interface Assembly Usage
  • Initialization
  • Finalization
  • Canceling execution
  • Bitness
  • Diagnostic mode
  • Dialogs
  • Full AVL.NET
• Example
  • Introduction
  • Creating Aurora Vision Project
  • Generating .NET Macrofilter Interface Assembly
  • Using .NET Macrofilter Interface Assembly in a Visual C# application
• Hints

Introduction

Generation of macrofilter interfaces allows to design complex applications without loosing comfort of visual programming which comes from the environment of Aurora 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. Aurora Vision Studio enables to use those macrofilters in .NET languages 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) as long as the signature of the macrofilters do not change.

Requirements

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

.NET compatibility

The .NET Macrofilter Interface assembly is always build as .NET Standard 2.0 assembly so it can be utilized with most .NET implementations and products. See the .NET Standard article for full list of compatible implementations.

.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 Aurora 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.

Type Name

Defines the name of the class, where all macrofilters will be available as methods (with the same signatures as macrofilters).

Create Sample Project

Generates empty Microsoft Visual Studio C# WinForms project that uses to-be created Macrofilter .NET Interface assembly.

Assembly Path

Location of the to-be generated assembly.

Interface page

The interface page contains all macrofilters and user types that can be included in the generated .NET Interface assembly.

Advanced page

.NET Macrofilter Interface assembly may be Strong-Named. This can be done with signing the assembly with given private key that either can be generated with the Strong Name Tool or in the Microsoft Visual Studio IDE (C# project properties page).

Assembly Signing

Enables signing the generated Macrofilter .NET Assembly with given private key and makes it a 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 Aurora Vision libraries must be initialized, i.e. Executor.dll and available Filter Libraries. It is done in a MacrofilterInterfaceClass's constructor, 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 constructor accepts a path to either *.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 constructor 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.

Canceling execution

The macrofilter execution can be cancelled with the System.Threading.CancellationToken argument, each macrofilter method accepts.

Bitness

Only x64 platform is supported in the generated Macrofilter .NET Interface assembly. This requires the client application to be compiled for the x64 platform as well

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 Aurora 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 Aurora 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 Aurora 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 Aurora Vision Studio Professional 5.5 and Microsoft Visual Studio 2015 are required. Visual C# will be used to execute macrofilters.

Creating Aurora Vision Project

We have to have some Aurora 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 Aurora 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 Create Sample Project option to create a default C# project with required configuration properly set for the current Aurora Vision Studio installation.

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. AuroraVision.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 AvlNet.Types.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 AvlNet.Types.dll is essential here. The required dependency can also be added as AvlNet.Types NuGet package from the NuGet source installed with the Aurora Vision Studio installation.

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 Avl;
using AuroraVision;
    public partial class Form1 : Form
    {

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

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

ExampleMacrofilters constructor accepts a path to either *.avproj or *.avexe file. In this example it takes the path to the *.avproj file with the definition of ThresholdLena macrofilter. Example.avproj passed to the constructor means, that the runtime will look for the *.avproj 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.ToBitmap();
        }
    }
    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 implements the System.IDisposable interface with the Dispose method which allows user to disconnect from Aurora 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.
• The application using Macrofilter .NET interface may also reference the AVL's AvlNet package to enable direct AVL function calls from the user code (see Getting Started with Aurora Vision Library .NET for referencing the AvlNet.dll in the user applications).