You are here: Start » PyAVL » PyAVL - AVL Relation

PyAVL - AVL Relation

Overview

PyAVL is a wrapper of the Aurora Vision Library, which means that when a function of the AVL module is called, a native AVL function is called. The native library (AVL.dll on Windows, libAVL.so on Linux) has to be available to the extension module of PyAVL. Installing PyAVL with pip as described in Installation takes care of that.

The names of the functions and of their parameters are the same as in AVL/C++, so the description of a function in the Function Reference applies to its Python version. This page lists the differences that result from the differences between the languages.

Functions

In C++ the functions of the library are accessed through the avl namespace. In PyAVL all of them are functions of the AVL module. For example, avl::ThresholdImage is called as AVL.ThresholdImage.

The order of the arguments is different from the C++ function. In Python:

• the required inputs are passed first, as positional arguments, followed by the outputs that are objects with their own memory, for example images and regions;
• the optional inputs and the inputs with default values that are rarely changed are passed by name, as keyword arguments, and they can be skipped.

The C++ declaration of the function that thresholds an image:

void ThresholdImage
(
	const Image& inImage,
	Optional<const Region&> inRoi,
	Optional<real> inMinValue,
	Optional<real> inMaxValue,
	real inFuzziness,
	Image& outMonoImage
);

and the equivalent Python function:

def ThresholdImage(inImage, outMonoImage, /, *, inRoi=None, inMinValue=128.0, inMaxValue=None, inFuzziness=0.0)

The two calls below do the same:

avl::ThresholdImage(image, atl::NIL, 128.0f, atl::NIL, 0.0f, mono);

AVL.ThresholdImage(image, mono, inMinValue=128.0)

Types

Most of the native AVL types have their counterpart in the AVL module with the same name, for example avl::Image is AVL.Image and avl::Point2D is AVL.Point2D. The members of the types are properties with names starting with an upper case letter: the C++ field point.x is point.X in Python.

The objects of PyAVL are normal Python objects. Their native data is released automatically when the last reference to the object is gone, so there is nothing to dispose, as opposed to AVL.NET. Objects can be duplicated with copy.copy. The types that store a block of memory, such as Image, Surface and ByteBuffer, support the Python buffer protocol, see Interoperability with Other Libraries.

The table below lists how different types are handled in PyAVL:

Outputs

The outputs of C++ functions are passed by reference. In PyAVL an output is returned from the function, unless it is an object that has its own memory:

• The outputs that are numbers, strings, enumerations, arrays, optional or conditional values and small structures such as Point2D, Box or Segment2D are returned. The conditional outputs are None when the value is nil.
• When a function has more than one returned output, the result is a named tuple, so the outputs are accessed by their names, for example result.diagKernelRadiusX. A function without returned outputs returns None.
• The outputs that are larger objects, such as Image, Region, Path or Matrix, are created by the caller and passed as arguments, as in C++. Because the memory of such an object can be reused, it is possible to process many images without allocating new ones. The same holds for the arguments that are both input and output, such as the image modified by the drawing functions.

import AVL

region = AVL.Region()
AVL.CreateBoxRegion(AVL.Box(20, 20, 160, 160), 400, 400, region)    # region is an argument

box = AVL.RegionBoundingBox(region)                                 # Box is returned

smoothed = AVL.Image()
result = AVL.SmoothImage_Gauss(image, smoothed, inStdDevX=3.5)      # smoothed is an argument
print(result.diagKernelRadiusX, result.diagKernelRadiusY)           # named results

Diagnostic Outputs

The diagnostic outputs that are numbers or other simple values are returned together with the other outputs, as the diagKernelRadiusX value in the example above. The diagnostic outputs that are larger objects, such as images or regions, are optional arguments with the default value None, and they are available only by name. Pass an object to such an argument to receive the diagnostic data. When the argument is skipped, the data is not produced.

Arguments with Default Values

As in C++, the arguments that have a default value can be skipped, but this is not reproduced for every argument. In PyAVL the optional inputs and the inputs with default values that are rarely changed are keyword arguments. Their default values are visible in the signature of the function, for example in the type stub files. The optional inputs of the atl::Optional types have the default value None, which corresponds to atl::NIL. The optional region of interest of the functions is the keyword argument inRoi. All other arguments are required, even if the C++ function declares a default value for them.

States and Enumeration Functions

The functions that keep a state between the calls take a state object as the first argument. The state object is created with the constructor of the class that has the name of the state, without arguments, for example AVL.ReadDataCodes_State().

The functions that enumerate items, such as AVL.EnumerateImages, work as Python iterators and replace the loop with a state object of C++:

for image, path, name in AVL.EnumerateImages("images/", inRepeat=False):
    print(name)

Errors

The exceptions of the native library are converted to Python exceptions. They are derived from AVL.AVLError, except for the cancellation and for the lack of memory:

Python exceptions that are not related to the library, such as TypeError for an argument of a wrong type, are raised in the usual way.

Threads

The Python interpreter lock is released while a native function is running. Other Python threads can therefore run in parallel with a long image processing function.

Differences

• The Python operators for locations, points, vectors, shapes and matrices have no counterpart in the function list of AVL; see Operators on Geometry Types and Working with Matrices.
• AVL.DebugPreview is available on Windows only.
• The deep learning functions are not a part of the AVL module. They are provided by the AVLDL module, see Deep Learning (PyAVL-DL).

See Also

• PyAVL
• First Steps
• Interoperability with Other Libraries