You are here: Start » FIL.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

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

Installation

The assemblies for FabImage 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 FabImage 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 FabImage Library 5.5 is Fil instead of FilNet and the function container is now the Fil.Invoke class.

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

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

Nullable types

The FilNet.NullableRef and FilNet.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 ftl::Conditional<T> or ftl::Optional<T>. The FabImage Library 5.5 introduces Ftl.Conditional<T> and Ftl.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 = FilNet.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

ftl::Array known from the C++ FIL, 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 (FilNet.SafeList<T>) and safe nullable types (FilNet.SafeNullableRef<T>). These types were designed to simplify the disposal process but resulted in FIL functions using interfaces in the argument types. Since FIL functions no longer accept interface arguments, there is a disposable Fil.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 FabImage Library 5.5 does not include function overloads where optional input parameters (most commonly Ftl.Optional<Fil.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 Ftl.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++ FIL 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 Fil.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 FabImage Library 5.5 introduces the Fil.Diagnostic<T> type for diagnostic outputs. These outputs have a default value of null, making them optional.

Settings

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

• Fil.Invoke.EnableFilDiagnosticOutputs
• Fil.Invoke.GetFilDiagnosticOutputsEnabled

WinForms specific

The core assemblies of the FabImage 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 Fil;
using Image image = new();

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

// display the bitmap