You are here: Start » AVL.NET » Code Migration Guide to version 5.5

Code Migration Guide to version 5.5

1. Introduction
2. Installation
3. Target frameworks
4. Namespace and function container
5. Nullable types
6. Lists
7. Disposing
8. Reduced overloads
9. MoveTo and CopyTo
10. Diagnostic outputs
11. Settings
12. WinForms specific

Introduction

Aurora Vision Library 5.5 introduces numerous optimizations and API changes that may invalidate user code after upgrading from earlier versions of the Aurora Vision Library. This also affects the Macrofilter .NET Interface assemblies generated in Aurora Vision Studio. This article outlines the most significant changes and provides guidance on updating code in applications that reference the AVL.NET assemblies and Macrofilter .NET Interface assemblies.

Installation

The assemblies for Aurora Vision Library 5.5 are provided as NuGet packages. This simplifies the referencing process by allowing you to install the appropriate NuGet packages instead of manually referencing assemblies and copying native dependencies to the output directories.

The Aurora Vision Library 5.5 installer simplifies the installation of NuGet packages by adding the installation directory to the local NuGet source.

There are several NuGet packages available for installation, depending on the user's needs.

Target frameworks

Most of the packages target the .NET Standard 2.0 making them compatible with most of the .NET implementations. Selected packages target only windows-specific framework monikers.

Namespace and function container

Root namespace in the Aurora Vision Library 5.5 is Avl instead of AvlNet and the function container is now the Avl.Invoke class.

using Image imageSum = new();
AvlNet.AVL.AddImages(image1, image2, null, 1.0f, imageSum);

using Image imageSum = new();
Avl.Invoke.AddImages(image1, image2, null, 1.0f, imageSum);

Nullable types

The AvlNet.NullableRef and AvlNet.SafeNullableRef types are removed and the System.Nullable<T> is no longer used in the library API. Those types do not provide information about whether the underlying type is atl::Conditional<T> or atl::Optional<T>. The Aurora Vision Library 5.5 introduces Atl.Conditional<T> and Atl.Optional<T> to address that confusion.

// empty optional references
NullableRef<Region> emptyOpt1 = null;
NullableRef<Region> emptyOpt2 = new NullableRef<Region>();

// empty optional values
int? emptyOpt3 = null;
int? emptyOpt4 = new int?();

// non-empty optional references
using Region roi = new();
NullableRef<Region> optRoi1 = new NullableRef<Region>(roi);
NullableRef<Region> optRoi2 = AvlNet.Nullable.Create<Region>(roi);
NullableRef<Region> optRoi3 = roi;

// non-empty optional values
int? opt4 = 5;
int? opt5 = new int?(5);

// empty optional references
Optional<Region> emptyRoi1 = null;
Optional<Region> emptyRoi2 = new Optional<Region>();
Optional<Region> emptyRoi3 = Optional.Empty<Region>();

// empty optional values
Optional<int> emptyOpt4 = null;
Optional<int> emptyOpt5 = new Optional<int>();
Optional<int> emptyOpt6 = Optional.Empty<int>();

// non-empty optional references
using Region roi = new();
Optional<Region> optRoi1 = new Optional<Region>(roi);
Optional<Region> optRoi2 = Optional.WithValue(roi);
Optional<Region> optRoi3 = Optional.WithValue<Region>();
Optional<Region> optRoi4 = roi;

// non-empty optional values
Optional<int> opt5 = 5;
Optional<int> opt6 = new Optional<int>(5);
Optional<int> opt7 = Optional.WithValue<int>(); // default(int)
Optional<int> opt8 = Optional.WithValue<int>(5);

Lists

atl::Array known from the C++ AVL, is reflected by the List class instead of the IList interface. This makes the API more coherent and usage easier for nested collections.

Disposing

There are no longer safe collections (AvlNet.SafeList<T>) and safe nullable types (AvlNet.SafeNullableRef<T>). These types were designed to simplify the disposal process but resulted in AVL functions using interfaces in the argument types. Since AVL functions no longer accept interface arguments, there is a disposable Avl.Utils.Disposables class that helps dispose of complex objects which do not implement the System.IDisposable interface but contain items that need to be disposed.

using (var roi = new SafeNullableRef<Region>())
using (var images = new SafeList<Image>())
{
    // use the objects
}

using (var disposables = new Disposables())
{
    var roi = new Region();
    var images = new List<Image>();

    // Subscribe objects for disposal
    roi.DisposeWith(disposables);
    images.DisposeWith(disposables);

    // use the objects
}

Reduced overloads

The Aurora Vision Library 5.5 does not include function overloads where optional input parameters (most commonly Atl.Optional<Avl.Region> inRoi) are omitted. These parameters must always be provided, even if the value is empty. There are two ways to pass an empty optional value: using the Atl.Optional.Empty<T>() helper method or simply the null keyword.

However, more optional parameters with default values have been defined to closely mimic the C++ AVL signatures, particularly for optional and diagnostic outputs - outputs that should only be computed when the argument value is not empty.

MoveTo and CopyTo

Types that hold native data, such as Avl.Image, can now be moved using IMoveable<T>.MoveTo(<T>) methods, similar to how the move assignment works in C++. In fact, the method calls that operator under the hood.

Similarly, there is ICopyable<T>.CopyTo(<T>) method that performs the copy assignment on the native data.

Most of the types containing the native data, implement both the IMoveable<T> and the ICopyable<T> interfaces as long as the underlying C++ types can be moved (have the move assignment operator and move constructor defined) and copied (have copy assignment operator and copy constructor defined).

Diagnostic outputs

The Aurora Vision Library 5.5 introduces the Avl.Diagnostic<T> type for diagnostic outputs. These outputs have a default value of null, making them optional.

Settings

The class AvlNet.Settings, known from Aurora Vision Library 5.4, no longer exists. Instead, diagnostic mode can be modified and examined in the same way as in native AVL, using functions:

• Avl.Invoke.EnableAvlDiagnosticOutputs
• Avl.Invoke.GetAvlDiagnosticOutputsEnabled

WinForms specific

The core assemblies of the Aurora Vision Library 5.5 for .NET are platform-agnostic. However, there are dedicated NuGet packages available for interoperability with the WinForms framework, which include the following:

// using Bitmap = System.Drawing.Bitmap;
using Image image = new();

Bitmap bitmap = image.CreateBitmap(); // member

// display the bitmap

// using Bitmap = System.Drawing.Bitmap;
// using Avl;
using Image image = new();

Bitmap bitmap = image.ToBitmap(); // extension

// display the bitmap