Introducing: Experimental CVB.Net, CVB++ and CVBpy API

Introduction

The Common Vision Blox API is a child of its time, and the decision to restrict it to a pure C(-like) API was a deliberate and conscious one: It enabled the use of :cvb: in all popular programming environments back when it was originally conceived (namely Visual Basic 6, Delphi and Visual C++ 6) without the need for additional layers/wrappers. And even more: :cvb: was easily adaptable to those programming environments that became major players in the following years (like e.g. the .Net/CLR based languages or LabView). All but the most exotic tools/languages can usually deal with C imports, and :cvb: has been used in all the aforementioned languages and environments as well as Smalltalk, Java, MatLab and Autohotkey - all thanks to the decision for its simplistic API and the diligence of our customers.

On the other hand, a simple C API of course has its limitations: In a C API the structure and interactions of the objects that the programmer is dealing with are not immediately apparent in the structure of the API, making it harder for users to find their way (to put it differently: a C API offers much less guidance to its intended use than an object oriented API). Furthermore it does not adapt easily to object oriented programming patterns without which writing complex applications becomes a tedious and error-prone task.

Over time we have made the experience that quite a few customers have written their own wrappers for the :cvb: API. Some did it to adapt :cvb: to programming patterns that they wanted to use in their applications, others to simplify certain aspects of the use of :cvb: (the lifetime management of IMG objects, GenApi node map handling or the use of Overlay Plugins in .Net applications - to give just three typical examples…). And we did the same: When writing Trade Show demos, when writing applications for :cvb: (like the Management Console or TeachBench) we have often also come up with wrappers to simplify the task.

And over time, the determination grew to give the functionality of :cvb: a new look by consolidating and documenting the available wrappers into what is to become CVBNet, CVB++ and CVBpy

Design Goals

The new API currently comes in three flavors:

  1. CVBNet for all .Net/CLR based languages (.Net runtime 4.0 or higher)
  2. CVB++ for C++ 11 compilers (vc14, gcc 5.x)
  3. CVBpy for Python 3.6

CVBNet is using P/Invoke on the C-DLLs, CVB++ use the C-functions directly, and the CVBpy extension module is using CVB++.

  • The main goal is to integrate the functionality of :cvb: into each language in a way that feels natural for programmers already using the language. The goal was not to make the three APIs identical no matter what and subtle differences definitely exist between the three APIs. For example CVBNet of course makes use of properties, indexers, events and other concepts natural to C# programmers which have no direct correspondence in C++, whereas CVB++ may use templates in some places which are inaccessible in C#.
  • One of the aims was to completely rid the API of the need to explicitly cater to the correct disposal of objects that are no longer needed. The correct use of ShareObject and ReleaseObject in the C API is a recurring source of confusion. With CVBNet and CVB++ there is no need to use either of these functions: In CVBNet the types that may need disposal all implement the IDisposable interface and life-time management may either be left to the common language runtime or implemented explicitly by calling Dispose or (preferable) using the using keyword; in CVB++ the image and similar objects are wrapped in smart pointers that handle object lifetime automatically.
  • Error handling has been adapted to consequently use exceptions to report failure. For all three languages involved, exceptions are a natural means of propagating runtime errors, ideally enriched with diagnostic information. In situations where return codes may be preferable over exceptions Try... methods have been added to avoid exceptions.
  • Inheritance should is to be used to properly model object interactions and dependencies in the new wrappers, ideally making working with them more intuitive (and rewarding).
  • Unlike the C API which remained stable once published, API stability is not a chief objective. This doesn’t mean that we’re going to change the API at a whim whenever we feel like. If, however, a design choice turns out to be ill-conceived or outdated we’ll take the liberty to modify it.
  • CVBNet is - with the exception of Stemmer.Cvb.Forms and Stemmer.Cvb.Wpf - compliant with .Net Core 2.0 and may therefore also be used on platforms other than Windows.

Things to Keep in Mind

We are deliberately publishing the new wrappers at a very early stage of their development to give (potential) users the possibility to influence the further development through their feedback. We have chosen a fast-track deployment through nightly builds for that end, which does have implications. To put it straight: All three APIs are currently strictly experimental. This means:

  • The APIs are subject to change if at some point it turns out that a given design choice was not a good one - so one should not rely on the APIs remaining stable between different builds.
  • Test status of the APIs is mixed. Parts of CVBNet have seen a fair share of use in internal projects already and may be considered stable. Other parts are still at earlier stages of development and are more likely to still have flaws. An overview of the current status may be found at the end of this post.
  • The downloadable installers may be short lived and superseded on an almost nightly basis and versions are not tracked, so users should be aware that they cannot rely on a given build of the installers to still be available tomorrow. We’ll try to keep track of the most notable changes in this forum.

Bearing all that in mind, the new wrappers are currently under heavy development. Using them now in productive applications might incur breaking changes when updating to new versions. Of course, anything based on them should be thoroughly tested before deployment to the target site.

For API-specific information (and discussion) please follow these links:

Where to get it?

Currently only two Windows installers exist which are downloadable through the links below:

Please choose the installer that matches the architecture of your :cvb: installation. Each installer installs all three APIs along with the necessary runtime files (needed for CVBNet and CVBpy), the documentation (in the %CVB%\Doc folder; Cvb.Net.chm for CVBNet, Cvb++.chm for CVB++) and a few tutorials (installed into the Image Manager tutorial sub folder or the tool sub folder of %CVB%\Tutorial).

As pointed out previously, these installers will be updated fairly frequently and older versions will currently not be preserved. Linux setups will follow at a later point - for the time being, Linux users who want to give CVB++ a try may copy the file set installed under %CVB%\Lib\C\cvb to ${CVB}/include/cvb (CVB++ is a header-only library and does not require any additional files) as well as the tutorial sources…

:exclamation: Hint: Earlier versions of the installer had issues with upgrade setups not upgrading all the required files. If you downloaded and installed a version prior to the 2nd of November 2017, 3:30 pm then please uninstall your previous Bindings Preview and then download and install the one from here.

Coverage

Currently the coverage and test state of the different APIs with respect to the :cvb: tools is as follows:

Category CVBNet CVB++ CVBpy
Image Manager :white_check_mark: + :white_check_mark: + :white_check_mark: o
Foundation Package* :white_check_mark: o :white_check_mark: o :white_check_mark: o
Barcode :white_check_mark: o :x: :x:
Blob :x: :x: :x:
Color :x: :x: :x:
GEVServer :x: :x: :x:
GPUprocessing :x: :x: :x:
Manto :white_check_mark: - :x: :x:
Minos :white_check_mark: + :x: :x:
Movie2 :white_check_mark: + :white_check_mark: + :white_check_mark: +
Polimago :white_check_mark: + :x: :x:
Sil :white_check_mark: + :x: :x:
ShapeFinder :white_check_mark: - :x: :x:
* Foundation Package includes BayerToRGB, Edge, LightMeter; TextOut and Arithmetic currently not covered. TextOut will be covered in the near future, Arithmetic is unlikely to be covered because effectively its feature set is already available based on the implementation in CVFoundation.dll.
8 Likes

Is CVBNet still going to be updated? Is there any new progress? I just started learning CVB. I used the Adaptive Vision library. Its image acquisition performance is poor. But I am not used to the CVB acquisition method (can only use the ocx control to collect? In the .net environment). Very unexpectedly found CVBNet in the forum. It was discovered that it was released in 2017. Does it have continuous updates? Or is there a continuous update plan? Is it worth learning?

Hi @soultower!

Yes, CVB.Net is still updated and maintained. The latest version of the installer is 1.00.000 and was released on the 18th of October 2018. The plan is to make CVB.Net, CVB++ and CVBpy part of the 13.2 release, after which the standard installer for :cvb: will automatically install all the object oriented wrappers every time you install :cvb:. So yes, from our point of view, CVB.Net is definitely worth learning :slight_smile:

I know the forum entry makes the impression that nothing changed since 2017, but that is because we have only ever edited the forum entry rather than add new ones and the files referred to by the download links have usually been updated silently in the past.

As far as acquisition is concerned: You basically have three options in C#.

  • If you are using the CVB.Net wrappers, then have a look at the StreamDisplay or the WpfGenICam example for simple examples how to implement an image acquisition with our CVB.Net wrapper (if you have installed the CVB.Net setup downloadable from the initial post you will find those examples in the folder %CVB%\Tutorial\Image Manager\Cvb.Net). The approach is fairly simple once you are familiar with it, yet it provides all the flexibility you need.
  • If you are using what I’d call the classic (C-)API of :cvb: then VCGrabConsoleExample in %CVB%\Tutorial\Image Manager\VC shows you a simple approach for image acquisition on the DLL level. It’s written in C++, not C#, but I think you’ll be capable of mapping the function calls to their counterparts found in the iCVCDriver.dll in %CVB%\Lib\Net. Note that for maximum throughput it’ll probably be necessary to place the acquisition (basically the repetitive call to Cvb.Driver.IGrab2.GWait() into a thread of its own to decouple acquisition and processing.
  • Third and lastly you can use the Image OCX, an ActiveX control. This implements an acquisition thread of its own and invokes an event handler (ImageSnaped [sic!]) whenever a new image arrived. The Image OCX by and large provides a more convenient approach to the DLL’s functionality, but is limited in terms of complexity (for example syncing to the acquired images of two cameras is easier with the DLL).

If I were to express a recommendation (which is probably heavily biased…) I’d go for CVB.Net as it provides a reasonable balance between flexibility and convenience.

1 Like

A post was split to a new topic: Pixel access on Image

Am I missing something? I can’t for the life of me find the .Net assemblies that you reference in the tutorial. I find the iXXX.dll, but no Stemmer.Cvb.* Is there somewhere I can download them?

Hi @Ben

Currently those wrappers do not (yet) install with the “regular” :cvb: setup. They will, however, be part of the 13.02.000 (and higher) installation which is due to be released this summer. Meanwhile please follow the link in the original post to download our add-on setup with the new wrappers:

2 Likes

Thanks, I thought the link was dead, but it was our proxy blocking the download :upside_down_face:

1 Like

Aaaaah… The joy of security :wink:

Please note that starting with Common Vision Blox 13.02.000 the wrappers described here are part of the official distribution of Common Vision Blox! In other words: If you want to use this, please download and install Common Vision Blox 13.02.000.

1 Like