<< Click to Display Table of Contents >> Navigation:  Introduction > API Guide

Introduction

Over the past 20+ years the functionality of Common Vision Blox has been accessible through several hundred functions exported by a few dozen DLLs. These functions were exported in a way that was compatible with Visual C++, Delphi and Visual Basic - arguably three of the major programming languages for Windows applications when Common Vision Blox was first published. Starting with Common Vision Blox 13.2, this application programming interface (API) - henceforth called the C-style API (of Common Vision Blox) - has been supplemented with three newly developed APIs targeted at specific programming environments: CVB.Net, CVB++ and CVBpy. This page is intended to give a brief introduction into these three APIs, highlight the design ideas behind them and give an overview over which tools are accessible in each API.

 

Why new APIs?

When the C-style API of Common Vision Blox was designed, one of the aims was to support C (and the nascent C++), Delphi and Visual Basic with a reasonable maintenance effort. To that end, the API had to be more or less restricted to types and other syntactical constructs that were mappable to all target languages. A procedural API consisting of - in C terminology - extern "C" __stdcall functions and using only the most elementary data types was the logical result. A welcome side-effect of this simplicity was that the C-style API was immediately usable not only in the .Net languages when they arrived on the market in 2002 but also (though unsupported) in a number of other environments like LabView or Matlab for those users willing to put in the effort.

Today, object oriented programming and object oriented techniques and patterns are considered state-of-the-art and it has been generally accepted that these provide an ease-of-use and a degree of flexibility that is superior to procedural programming (ideally resulting in a reduced time to market for software that can build on these advantages). This already starts with the built-in features of today's development environments: If one has e.g. an image object, the development environment can easily show all the methods and properties available on that object; the same is not true if one just has a bland image handle and a number of functions that accept one of those handles. And it doesn't stop just there: Objects with a defined and automatic lifetime management are much more easily integrated into OOP-patterns than a collection of pointers and functions. And the bare minimum approach that the C-style API of Common Vision Blox had to take by necessity precludes the use of complex data types (objects) which would have been necessary to provide a consistently object-oriented approach.

Therefore the decision was made to add a consistently object-oriented API layer for Common Vision Blox. With the exception of the .Net language family such an API layer is by definition language and/or runtime dependent. Also, the implementation and maintenance effort is significant, so the number of languages/environments that can actually be supported is limited. Based on the selection criteria "platform independence", "popularity" and "flexibility" the languages/environments ultimately selected were .Net, C++ and Python, making the naming obvious: CVB.Net, CVB++ and CVBpy.

 

Specifications

Layers

The new APIs - CVB.Net, CVB++ and CVBpy - are all built on the C-style API (with CVBpy in turn also relying on CVB++ as its basis - simply because the implementation of the Python wrappers became much easier with the CVB++ classes than it would have been with the C-style API):

Of course this implicitly also means that the three new APIs will not make the C-style API obsolete in any way. To the contrary: It will continue to be the basis for all the other APIs and will be fully maintained in the future and will continue to be available for those who either do not want or cannot move to one of the new APIs.

 

Design Rationale

When designing the CVB.Net, CVB++ and CVBpy APIs, the following considerations were the cornerstones for the design decisions:

•build lean and efficient wrappers on top of the C-style API that do not introduce a noticeable performance penalty at runtime

•consistently use object oriented idioms to make the new APIs easily understandable and facilitate easy integration into object oriented programming patterns

•embed the new APIs natively into their respective programming environments by adopting naming and usage patterns generally established in the respective environments so that users will not perceive the CVB API as something alien to the rest of their tool chain

•prioritize native embedding over congruence with the C-style API - even if this means the users familiar with the C-style API may not immediately recognize everything at first sight

•make lifetime management of CVB object automatic by using language-specific constructs like smart pointers or reference types, thus eliminating the need for "manual" reference counting which is one of the most common sources of usage errors in the C-style API.

•use native container objects where it makes sense rather than relying on CVB-specific containers like e.g. PIXELLIST

•raise exceptions for errors rather than just returning a simple value that may (too) easily be ignored by the caller

 

Stability Commitment

Although it was not put down in writing anywhere, the original C-style API of Common Vision Blox did apply a fairly strict stability commitment: The API did (more or less...) not change in the sense that function signatures were altered or functions removed entirely. Admittedly there were occasions where function behavior needed to change between versions and over the years there was the odd case where it was not possible to circumvent some of the aforementioned changes. But in general, the developers behind Common Vision Blox were working under the assumption that what has been released to the public did by default have to remain unchanged. For the C-style API this will continue to be the case.

Of course, restricting changes to the API to only the absolutely necessary ones does have its drawbacks. The entire API effectively becomes static and inconsistent naming of code items or inconsistent (or improveworthy) signature choices cannot simply be corrected as they would break compatibility on the binary level as well as on the source code level. The go-to solution in those cases is to gradually introduce new functions like e.g. ListPixelEx (which does the same job as ListPixel, only with doubles rather than ints). While fixing the problem at hand, these constructs arguably won't improve the overall appeal and quality of the API, and it was therefore decided that the CVB.Net, CVB++ and CVBpy API will be allowed to be more dynamic insofar as they may actually change between different releases!

What may - at least to some and at first - sound like a developer's nightmare is actually not so bad when looked at more closely. First of all this will allow the APIs themselves to become better over time and be easier to use and understand as they evolve. But - even more importantly - the three different APIs have different ways to deal in user-friendly ways with these changes that were not available to the original C-style API:

•CVB.Net consists of a set of regular .net assemblies that can make use of the entire feature set of the Common Language Runtime. In particular they have been given an AssemblyVersion attribute which will allow an application built versus CVB.Net to correctly identify and load the precise version(s) of the DLL(s) against which it has been built. Furthermore, they are installed into the Global Assembly Cache (GAC) incrementally (i. e. every new version of Common Vision Blox will not only install the current build of the CVB.Net DLLs in the GAC, but also all the older released versions). Thanks to that, changes to the CVB.Net API in a later release of Common Vision Blox will not break binary compatibility with an executable that has been built versus an older version of CVB.Net!

•CVB++ comes as a collection of header files that contain references to the C-style API functions - which will continue to be static. The actual C++ API will be compiled directly into the binaries generated with it and is not part of the DLLs in Commons Vision Blox. This is why future changes to the CVB++ API will not break binary compatibility.

•The situation with CVBpy is somewhat different in that there is no binary compatibility to be broken as Python is usually not compiled into a stand-alone binary.

To summarize: Even with the deliberately more dynamic new APIs binary compatibility will not be broken by future changes.

Of course, changes to the existing APIs will - in all three cases - potentially break backward compatibility on the source code level. However, even these breaks can be circumvented:

•CVB.Net applications can refer to the correct GAC-installed CVB.Net DLLs rather than the most recent ones found in %CVB%\Lib\Net and continue to compile versus older builds of the CVB.Net API.

•Applications built versus CVB++ can continue using older versions of the API by simply copying the contents of the %CVB%\Lib\C\cvb folder into the project and using the older fileset from there.

•Similarly, CVBpy applications can be made working again after API changes by reverting to older versions of the CVBpy wheel.

To summarize: Future API changes do not necessarily require that existing application will need to be migrated

Any of these three cases, is not a generally recommended approach, but a quick fix for those situations where one doesn't have the time to properly migrate the source code. Keeping up with the API is generally recommended and should not actually prove too difficult - STEMMER IMAGING is committed to providing all the required information up front plus the compiler will do a good job of pointing out the code locations that need to be changed.

With binary backward compatibility not actually being much of an issue and source code compatibility being at least one that can be dealt with easily, the principle "stable API at all costs" will not apply for CVB.Net, CVB++ and CVBpy, so signatures, names etc. may change as needed in future releases if the need arises.

 

Overview

The following table gives an overview of which Common Vision Blox module is supported in which API context. More detailed and API-specific usage hints and introductions are located in the "Programming with Common Vision Blox" section of the online help.

•The first column gives the name of the DLL. Users already familiar with Common Vision Blox will likely recognize these, which makes them a good entry point. Note that not all DLLs are available for all platforms (see the different markings at the bottom of the table).

•The three columns under the heading C-style give an overview over what tools/DLLs are accessible from which languages through the C-style API of Common Vision Blox.

•The column CVB.Net obviously lists the modules that are accessible through the CVB.Net API. The mapping rules are fairly straightforward:

oEverything from the Image Manager block (red background) can be found in the assembly Stemmer.Cvb.dll

oEverything from the Foundation Package block (mint-colored background) can be found in the assembly Stemmer.Cvb.Foundation.dll

oEverything from the tools block (gray background) has - if implemented - been put into a DLL that bears the tool name (e.g. Stemmer.Cvb.Minos.dll, Stemmer.Cvb.Polimago.dll etc.)

•The column CVB++  lists the modules that are accessible through the CVB++ API. The mapping rules are:

oEverything from the Image Manager block (red background) can be found in the Cvb namespace.

oEverything from the Foundation Package block (mint-colored background) can be found in Cvb::Foundation namespace (with the sole exception of the OPC UA tool which is located in the Cvb::OpcUA namespace).

oEverything from the tools block (gray background) has - if implemented - been put into a namespace that bears the tool name (e.g. Cvb::Minos, Cvb::Polimago etc.)

•The column CVBpy obviously lists the modules that are accessible through the CVBpy API. The mapping rules are again fairly straightforward:

oEverything from the Image Manager block (red background) can be found in module cvb

oEverything from the Foundation Package block (mint-colored background) can be found in cvb.foundation module (or cvb.opcua module).

oEverything from the tools block (gray background) has - if implemented - been put into a namespace that bears the tool name (e.g. cvb.minos, cvb.polimago etc.)