eGrabber .NET migration guide

Why new assemblies?

The Coaxlink_NetApi assembly suffers from several limitations and annoyances.

• The API was not as rich as the eGrabber C++ classes from the beginning.
• It did not catch up with the latest eGrabber improvements (e.g. camera discovery and multi-bank support are not available).
• It’s departing from the new Python API, which is very close to the eGrabber C++ classes.
• Some API methods depend on the custom type Euresys.SizeT¹, which cannot be used as a simple integer type.
• The event callbacks are defined as delegates rather than usual methods.
• For technical reasons, Coaxlink_NetApi object handles cannot be used accross AppDomains.

The new EGrabber.NETFramework assembly fixes all those issues. It’s based on the same design as the new Python bindings but tailored to the .NET Framework runtime.

The new EGrabber.NET assembly has the same benefits as EGrabber.NETFramework but targets the new open-source and cross-platform implementation of .NET previously called .NET Core.

Updating the assembly reference

Obviously, the project files referencing the old assembly need to be updated to reference the new one.

IntelliSense and inline documentation

Visual Studio is of great help while migrating from Coaxlink_NetApi to EGrabber.NETFramework or EGrabber.NET. You can explore the Euresys.EGrabber API with the IntelliSense auto-complete feature of the IDE. In addition, the API is fully documented and the documentation is directly available in the IDE².

.NET Framework

The new EGrabber.NETFramework requires a more recent .NET Framework.

.NET (Core)

The new EGrabber.NET does not require .NET Framework but requires another version called .NET.

Namespaces

The eGrabber classes are now in the namespace Euresys.EGrabber.

Basic migration rules

Here are the basic migration rules.

• In the Coaxlink_NetApi API, method names are written in camelCase whereas in EGrabber.NETFramework and EGrabber.NET, method names are written in CamelCase to improve consistency with .NET naming conventions; For example, the Coaxlink_NetApi method reallocBuffers becomes ReallocBuffers in EGrabber.NETFramework;

• Some methods are now properties (e.g. EGrabber.Width, EGrabber.Height), those changes are straightforward;

• Other differences:

  Coaxlink_NetApi	EGrabber.NETFramework and EGrabber.NET
  getInfoMODULE(cmd, out ...)	Module.GetInfo<TYPE>(cmd)
  getIntegerMODULE(f)	Module.Get<long>(f), Module.Get<int>(f)…
  (cf. note below)	Module.Get<bool>(f)
  getFloatMODULE(f)	Module.Get<double>(f), Module.Get<float>(f)
  getStringMODULE(f)	Module.Get<string>(f)
  getStringListMODULE(f)	Module.Get<string[]>(f)
  setIntegerMODULE(f, v)	Module.Set<long>(f, v), Module.Set<int>(f, v)…
  (cf. note below)	Module.Set<bool>(f, v)
  setFloatMODULE(f, v)	Module.Set<double>(f, v), Module.Set<float>(f, v)
  setStringMODULE(f, v)	Module.Set<string>(f, v)
  executeMODULE(f)	Module.Execute(f)
  enableEVENT_DATAEvent(f)	EnableEvent(EventType.EVENT_DATA)
  disableEVENT_DATAEvent(f)	DisableEvent(EventType.EVENT_DATA)

  where

  • MODULE can be replaced by SystemModule, InterfaceModule, DeviceModule, StreamModule, or RemoteModule;
  • Module can be replaced by System, Interface, Device, Stream, or Remote;
  • EVENT_DATA can be replaced by NewBufferData, DataStreamData, IoToolboxData, CicData, CxpInterfaceData, DeviceErrorData, CxpDeviceData, or RemoteDeviceData.

Note: with the Coaxlink_NetApi assembly, setting/getting bool values had to be done using methods setIntegerMODULE/getIntegerMODULE (with values 1 and 0) or using methods setStringMODULE/getStringMODULE (with values "True" and "False"). Both of these options still work, but the new EGrabber.NETFramework and EGrabber.NET assemblies improve bool support by providing explicit methods Set<bool> and Get<bool>.

Callback models

The different callback models of Coaxlink_NetApi assembly are no longer present in the new EGrabber.NETFramework and EGrabber.NET assemblies, which only expose an interface based on the “callback on demand” variant of EGrabber. The Python bindings only expose this model and this proved to be sufficient to support all the use cases as this model can be used to build the other variants.

In the table below, we show how to migrate from an old callback model to the new API.

As you can see, the ProcessEventsAsync approach is superior to the previous callback models.

• It’s more flexible because it provides a finer grain control over event processing handling. It’s easier to configure different processing tasks focusing either on a unique event type or on a particular set of event types.
• It follows the .NET common practices as it returns a Task object that can be operated using the standard API.

Discovery

The eGrabber discovery is now part of the new EGrabber.NETFramework and EGrabber.NET assemblies, so we can easily

• discovery available grabbers or cameras;
• create EGrabber objects for the discovered grabbers or cameras.

For example, the following piece of code creates an EGrabber object for the first discovered camera (if available):

using Euresys.EGrabber;

var gentl = new EGenTL();
var discovery = new EGrabberDiscovery(gentl);
discovery.Discover();
if (discovery.CameraCount == 0)
{
    throw new Exception("No cameras discovered");
}
var grabber = new EGrabber(discovery.Cameras[0]);

Please refer to the programmer’s guide for further details about the eGrabber discovery.

Selecting another GenTL provider

When an EGenTL object is created, the default GenTL producer is used (typically coaxlink.cti). However, it’s possible to select a specific producer in the code as follows:

var gentlCoaxlink = new EGenTL(CtiPath.Coaxlink); // loads `coaxlink.cti` -- Coaxlink cards and CoaXPress cameras
var gentlGigelink = new EGenTL(CtiPath.Gigelink); // loads `gigelink.cti` -- Network cards and GigE Vision cameras
var gentlGrablink = new EGenTL(CtiPath.Grablink); // loads `grablink.cti` -- Grablink Duo cards and Camera Link cameras

Converting buffers

The FormatConverter class is no longer present in the new EGrabber.NETFramework and EGrabber.NET assemblies but the functionality is still available.

There are three options for converting image buffers from a pixel format to another:

• Using the low-level EGenTL.ImageConvert, refer to the inline documentation available in the IDE;
• Using Buffer.Convert or ScopedBuffer.Convert, which create a ConvertedBuffer object containing the converted buffer in an automatically allocated memory region; the pixel data can be accessed using the property ConvertedBuffer.Pixels;
• Using Buffer.ConvertTo or ScopedBuffer.ConvertTo, which convert the buffer into a destination buffer provided by the user.

eGrabber Exceptions

Like in the Coaxlink_NetApi assembly, all the eGrabber exception classes are available in the new EGrabber.NETFramework and EGrabber.NET assemblies but with the CamelCase naming convention. The migration should be straightforward.

Using Open eVision EGrabberBridge

The EGrabberBridge now supports Coaxlink_NetApi and EGrabber.NETFramework assemblies (this requires Open eVision 24.02 or later).

using (EGrabberImageBW8 image = new EGrabberImageBW8(buffer.getInfo()))
{
    // Use the EGrabberImageBW8 as an Open eVision EImage Object
    // Here an inversion of the image is performed
    EImageBW8 invertedImage = new EImageBW8(image.Width, image.Height);
    EasyImage.Oper(EArithmeticLogicOperation.Invert, image, invertedImage);
}

using (EGrabberImageBW8 image = new EGrabberImageBW8(buffer.GetInfo()))
{
    // Use the EGrabberImageBW8 as an Open eVision EImage Object
    // Here an inversion of the image is performed
    EImageBW8 invertedImage = new EImageBW8(image.Width, image.Height);
    EasyImage.Oper(EArithmeticLogicOperation.Invert, image, invertedImage);
}

using (EGrabberImageC24 image = new EGrabberImageC24(bufferMono8))
{
    // The buffer containing Mono8 data is automatically converted
    // to BGR8 data before creating the EGrabberImageC24 object
    // ...
}

Sample programs

Please have a look at the samples in the cs and vb directories which have been adapted to use the new interface.