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:
- CVBNet for all .Net/CLR based languages (.Net runtime 4.0 or higher)
- CVB++ for C++ 11 compilers (vc14, gcc 5.x)
- 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
andReleaseObject
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 theIDisposable
interface and life-time management may either be left to the common language runtime or implemented explicitly by callingDispose
or (preferable) using theusing
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
andStemmer.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…
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 | + | + | o |
Foundation Package* | o | o | o |
Barcode | o | ||
Blob | |||
Color | |||
GEVServer | |||
GPUprocessing | |||
Manto | - | ||
Minos | + | ||
Movie2 | + | + | + |
Polimago | + | ||
Sil | + | ||
ShapeFinder | - | ||
* 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. |