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

.NET Macrofilter Interface Generator

Introduction

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

The most common usages:

  • Designing applications with a very complex HMI with a lot of parameters and floating windows.
  • Connecting Adaptive Vision applications which connects to external databases or devices which can be accessed using the .NET environment.
  • Creating flexible systems which can be modified without recompiling the source code of an application.
  • Designing vision system using C# without additional environmental overhead.

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 Visual C# or Visual 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.

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 4.7 Adaptive Vision Professional 4.7 or
Adaptive Vision Runtime 4.7
Visual Studio 2010 Express (or greater) for 32-bit systems
Visual Studio 2010 Professional (or greater) for 64-bit systems

.NET Macrofilter Interface Assembly Generator

Macrofilters may be interfaced for use in such managed languages as Visual 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).
Path to the generated dll library
Location of the assembly.

Macrofilters page

Check box list
List of all macrofilters in the current project that a .NET Macrofilter Interface may be generated for.

Advanced page

Compiler environment
Selection of which Visual Studio compiler should be used to build a library.
MSBuild location
Selection of a location of MSBuild necessary for compiling a interface library.

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

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 4.7 and Microsoft Visual Studio 2010 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 it 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 LenaThreshold 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 .NET Macrofilter Interface window check Generate Visual Studio 2010 Solution option to create a default C# project with required configuration set properly for the current Adaptive Vision Studio installation.

Also, check the ThresholdLena in the Macrofilters page to generate .NET Macrofilter Interface for the macrofilter.

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 2010 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.Kit.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.Kit.dll is required 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 AdaptiveVision;
    using AvlNet;
    ...
    public partial class Form1 : Form
    {
        /// <summary>
        /// Object that provides access to the macrofilters defined in the Adaptive Vision Studio project.
        /// </summary>
        private ExampleMacrofilters macros;

        public Form1()
        {
            InitializeComponent();
            try 
            {
                macros = ExampleMacrofilters.Create(@"Example.avproj");
            }
            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
            {
                //AvlNet.Image class comes from the AVL.NET.Kit.dll assembly
                Image image;

                //call macrofilter
                macros.ThresholdLena(trackBarMin.Value, trackBarMax.Value, out image);

                try
                {
                    //dispose previous background if necessary
                    if (pictureBox1.Image != null)
                    {
                        pictureBox1.Image.Dispose();
                        pictureBox1.Image = null;
                    }

                    //get System.Drawing.Bitmap object from resulting AvlNet.Image
                    pictureBox1.Image = image.CreateBitmap();
                }
                finally
                {
                    //dispose resulting AvlNet.Image since it will not be needed any more
                    image.Dispose();
                }
            }
            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 can be called in Form1.OnClosed override:


        protected override void OnClosed(EventArgs e)
        {
            //Release resources held by the Macrofilter .NET Interface object
            if (macros != null)
                macros.Dispose();

            base.OnClosed(e);
        }

Notes:

  1. Generated macrofilter interface class offers also Exit() method which allows user to disconnect from Adaptive Vision environment.
  2. Every step macrofilter contains specific resetting method, which resets an internal state. For example method ResetLenaThreshold() resets internal register values and any iteration states.
  3. Best way to create an application using macrofilter interfaces is to use encrypted avexe files. It secures application code from further modifications.
Previous: C++ Code Generator Next: Remote License Upgrade