You are here: Start » PyAVL » First Steps

First Steps

API Conventions

The wrapper follows these calling conventions:

Positional and keyword arguments. Required inputs are passed positionally; optional parameters are available as named keyword arguments with default values.
Named result objects. Functions that return multiple outputs return a named result object with fields accessible by name, for example r.outEdge.
Mutating functions. Some functions fill output objects passed as arguments and return None. This applies to operations that write into pre-allocated image or map buffers.
Diagnostic outputs. Many functions accept optional diag... keyword arguments that expose intermediate data useful for debugging. These default to None and have no effect unless explicitly passed.
Operators. Geometry types, Location and Matrix support the Python operators +, -, *, / and @. See Operators on Geometry Types and Working with Matrices.

PyAVL Example —Loading and Basic Operations

Load an image, inspect its properties, and apply common image operations:

import AVL

# Built-in test image (no file required)
image = AVL.Image()
AVL.TestImage(inImageId=AVL.TestImageId.Lena, outRgbImage=image)

# Access image properties
print(f"Size: {image.Width}x{image.Height}, channels: {image.Depth}, type: {image.Type}")

# Basic transformations - each writes into a new image
multiplied = AVL.Image()
AVL.MultiplyImage(image, 2, multiplied)         # brighten

smoothed = AVL.Image()
AVL.SmoothImage_Gauss(image, smoothed, inStdDevX=3.5)

thresholded = AVL.Image()
AVL.ThresholdImage(image, thresholded, inMinValue=128)

AVL.SaveImage(smoothed, "smoothed.png")

PyAVL Example —Region Operations

Build a region from geometric shapes, apply morphological operations, then draw all three results onto a white canvas and save:

import AVL

# Build a region from two boxes and a circle
r1, r2, r3 = AVL.Region(), AVL.Region(), AVL.Region()
AVL.CreateBoxRegion(AVL.Box(20, 20, 160, 160), 400, 400, r1)
AVL.CreateCircleRegion(AVL.Circle2D(300, 100, 80), 400, 400, r2)
AVL.RegionUnion(r1, r2, r3)

print(f"Input area:  {AVL.RegionArea(r3)} px^2")

# Morphological operations
eroded = AVL.Region()
AVL.ErodeRegion(r3, eroded, inRadiusX=20)
print(f"After erode: {AVL.RegionArea(eroded)} px^2")

skeleton = AVL.Region()
AVL.SkeletonizeRegion(r3, skeleton)
print(f"Skeleton:    {AVL.RegionArea(skeleton)} px^2")

# Draw all three onto a white canvas and save
canvas = AVL.Image()
AVL.EmptyImage(400, 200, canvas, inColor=AVL.Pixel(255, 255, 255))
AVL.DrawRegion(canvas, r3,      AVL.Pixel(0, 120, 255), 0.5)   # input - blue
AVL.DrawRegion(canvas, eroded,  AVL.Pixel(255, 80,  0), 0.7)   # eroded - orange
AVL.DrawRegion(canvas, skeleton, AVL.Pixel(0, 200,  0), 1.0)   # skeleton - green
AVL.SaveImage(canvas, "regions.png")

PyAVL-DL Example —OCR (Reading Characters)

Deploy a pretrained OCR model and read characters from an image:

import AVL
import AVLDL

# Deploy pretrained OCR model (one-time initialization)
model_id = AVLDL.ReadCharactersModelId()
AVLDL.DL_ReadCharacters_Deploy(model_id, inPretrainedModelType=AVLDL.OcrPretrainedModel.Extended)

# Load an image and run OCR
image = AVL.Image()
AVL.LoadImage("text_image.png", image)

result = AVLDL.DL_ReadCharacters(image, model_id, AVLDL.Polarity.Any, inCharHeight=35)

# Merge individual characters into text lines
lines = AVL.MergeCharactersIntoLines(result.outCharacters, 8.0, 0.25)
for line in lines.outStrings:
    print(line)

AVLDL.DL_ReadCharacters_Unload(model_id)

Error Handling

AVL raises specific exception types depending on the failure. Catch them individually for precise error reporting:

import AVL

try:
    image = AVL.Image()
    AVL.LoadImage("sample.png", image)   # raises AVL.IOError if file not found

    region = AVL.Region()
    AVL.CreateBoxRegion(AVL.Box(0, 0, 300, 200), 300, 200, region)
    AVL.AddToImage(image, 10, image, inRoi=region)   # raises AVL.DomainError if ROI exceeds image bounds

except AVL.IOError as e:
    print(f"File loading error: {e}")

except AVL.DomainError as e:
    print(f"Data processing error: {e}")

Python operators on Aurora Vision types report errors in the same way. A combination of operands for which the operator is not defined raises the standard Python TypeError, while an invalid value, such as matrices of incompatible sizes, raises AVL.DomainError.

Execution Control

PyAVL provides functions that control how the functions of Aurora Vision Library are executed:

Function	Description
`EnableSSEAcceleration`, `GetSSEAccelerationEnabled`	Switches the `SSE` acceleration on or off and reads its state.
`EnableAVX2Acceleration`, `GetAVX2AccelerationEnabled`	Switches the `AVX2` acceleration on or off and reads its state.
`EnableNEONAcceleration`, `GetNEONAccelerationEnabled`	Switches the `NEON` acceleration on or off and reads its state.
`SetParallelComputing`, `GetParallelComputingThreadsCount`	Switches the parallel computing on or off, sets the number of threads and reads it.
`EnableAvlDiagnosticOutputs`, `GetAvlDiagnosticOutputsEnabled`	Switches the diagnostic outputs on or off and reads their state.
`DischargeAVLImageMemoryPools`	Releases the memory kept in the image memory pools.
`CancelCurrentWork`, `ResetCancellation`, `IsCurrentWorkCancelled`	Cancels the work in progress, clears the cancellation and checks whether the work was cancelled.