You are here: Start » Introduction » Programming Conventions

Programming Conventions

Organization of the Library

Adaptive Vision Library is a collection of C++ functions that process machine vision related types of data. Each function corresponds to a single data processing operation, e.g. DetectEdges_AsPaths performs a Canny-like 2D edge detection. As a data processing library, it is not particularly object-oriented. It does use, however, modern approach to C++ programming with automatic memory management, exception handling, thread safety and the use of templates where appropriate.

Namespaces

There are two namespaces used:

  • atl – the namespace of types and functions related to Adaptive Template Library.
  • avl – the namespace of types and functions related to Adaptive Vision Library as the whole.
  • avs – Adaptive Vision Studio Code Generator equivalents of Adaptive Vision Library functions. Not recommended to use.

Enumeration Types

All enumeration types in Adaptive Vision Library use C++0x-like namespaces, for example:

namespace EdgeFilter
{
    enum Type
    {
        Canny,
        Deriche,
        Lanser
    };
}

This has two advantages: (1) some identifiers can be shared between different enumeration types; (2) after typing "EdgeFilter::" IntelliSense will display all possible elements of the given enumeration type.

Example:

atl::Array<avl::Path> edges;
avl::Image image, gradientImage;

avl::DetectEdges_AsPaths(image, atl::NIL, avl::EdgeFilter::Canny,
                         2.0f, atl::NIL, 60.0f, 30.0f, atl::NIL, 30.0f, 0.0f, atl::NIL, 0.0f, edges, gradientImage);

Function Parameters

Contrary to standard C++ libraries, machine vision algorithms tend to have many parameters and often compute not single, but many output values. Moreover, diagnostic information is highly important for effective work of a machine vision software engineer. For these reasons, function parameters in Adaptive Vision Library are organized as follows:

  1. First come input parameters, which have "in" prefix.
  2. Second come output parameters, which have "out" prefix and denote the results.
  3. The last come diagnostic output parameters, which have "diag" prefix and contain information that is useful for optimizing parameters (not computed when the diagnostic mode is turned off).

For example, the following function invocation has a number of input parameters, a single output parameter (edges) and a single diagnostic output parameter (gradientImage).

atl::Array<avl::Path> edges;
avl::Image image, gradientImage;

avl::DetectEdges_AsPaths(image, atl::NIL, avl::EdgeFilter::Canny,
                         2.0f, atl::NIL, 60.0f, 30.0f, atl::NIL, 30.0f, 0.0f, atl::NIL, 0.0f, edges, gradientImage);

Diagnostic Output Parameters

Due to efficiency reasons the diagnostic outputs are only computed when the diagnostic mode is turned on. This can be done by calling:

avl::EnableAvlDiagnosticOutputs(true);

In your code you can check if the diagnostic mode is turned on by calling:

if (avl::GetAvlDiagnosticOutputsEnabled())
{
	//...
}

Optional Outputs

Due to efficiency reasons computation of some outputs can be skipped. In function TestImage user can inform function that computation of outMonoImage is not necessary and function can omit computation of this data.

the TestImage Header with last two optional parameters:

void avl::TestImage
(
	avl::TestImageId::Type inImageId,
	atl::Optional<avl::Image&> outRgbImage = atl::NIL,
	atl::Optional<avl::Image&> outMonoImage = atl::NIL
)

Example of using optional outputs:

avl::Image rgb, mono;

// Both outputs are computed
avl::TestImage(avl::TestImageId::Baboon, rgb, mono);

// Only RGB image is computed
avl::TestImage(avl::TestImageId::Baboon, rgb);

// Only mono image is computed
avl::TestImage(avl::TestImageId::Baboon, atl::NIL, mono);

In-Place Data Processing

Some functions can process data in-place, i.e. modifying the input objects instead of computing new ones. There are two approaches used for such functions:

  1. Some filters, e.g. the image drawing routines, use "io" parameters, which work simultaneously as inputs and outputs. For example, the following function invocation draws red circles on the image1 object:
    avl::DrawCircle(image1, circle, atl::NIL, avl::Pixel(255, 0, 0), style);
    
  2. Some filters, e.g. image point transforms, can be given the same object on the input and on the output. For example, the following function invocation negates pixel values without allocating any additional memory:
    avl::NegateImage(image1, atl::NIL, image1);
    

Please note, that simple functions like NegateImage can be executed even 3 times faster in-place than when computing a new output object.

Work Cancellation

Most of long-working functions can be cancelled using CancelCurrentWork function. Cancellation technique is thread-safe, so function CancelCurrentWork can be called from different thread.

To check cancellation status use the IsCurrentWorkCancelled function.

void ProcessingThread()
{
	while (!avl::IsCurrentWorkCancelled())
	{
		std::cout << "Iteration start" << std::endl;
		avl::Delay(10000); // Function with cancellation support
		std::cout << "Iteration complete" << std::endl;
	}
	std::cout << "Processing thread stop" << std::endl;
}

int main()
{
	avl::InitLibrary();
	std::thread thread {ProcessingThread};

	std::cout << "Press Enter to stop execution." << std::endl;
	std::cin.get();

	// Cancel work in ProcessingThread and in avl::Delay
	avl::CancelCurrentWork();
	
	thread.join();

	return 0;
}

Library Initialization

For reasons related to efficiency and thread-safety, before any other function of the AVL library is called, the InitLibrary function should be called first:

int main()
{
	avl::InitLibrary();
	//...
}

Debug Preview

For diagnostic purposes it is useful to be able to preview data of types Image and Region. You can achieve this by using functions from the Debug Preview category. They can be helpful in debugging programs and displaying both intermediate and final data of such types.

avl::Image image;
avl::LoadImage("hello.png", false, image);

// Show loaded image in new window.
avl::DebugPreviewShowNewImage(image);

// Wait until window is closed.
avl::DebugPreviewWaitForWindowsClose();
Previous: Product Overview Next: Adaptive Template Library