You are here: Start » Getting Started » Python API

Python API

Aurora Vision Library provides Python packages that expose the Aurora Vision Library and Deep Learning inference to Python 3.12 programs:

  • PyAvl —the core Aurora Vision Library wrapper. Gives access to the full image processing, geometry, and machine vision function set. Imported as import AVL. Available since Aurora Vision Library 5.7.
  • PyAvl-DL —the Deep Learning inference wrapper. Gives access to all DL Deploy filters (object detection, classification, anomaly detection, OCR, etc.). Imported as import AVLDL. Requires PyAvl. Available since Aurora Vision Library 5.7.

Both packages ship as pre-compiled native extension modules (.pyd on Windows, .so on Linux) placed in the installation folder during the standard Aurora Vision Library setup. No compilation is required.

Requirements

  • Python 3.12 (64-bit). Other versions are not supported.
  • Aurora Vision Library installed on the machine.
  • Aurora Vision Deep Learning add-on installed (for PyAvl-DL only).
  • Windows 11 (64-bit) or a supported 64-bit Linux distribution.

Installation Files

Each package and all its supporting files are placed in a single directory inside the corresponding installation.

The directory contains everything pip needs to build and register a wheel:

PyAvl

  • AVL.pyd / AVL.so —the PyAvl extension module
  • AVL.pyi —type stub file for IDE support
  • pyproject.toml, hatch_build.py —pip build metadata and the build hook that packages the native files into a wheel
  • AVL.dll and its runtime dependencies (Windows)
  • Shared library runtime dependencies (Linux)

PyAvl-DL

  • AVLDL.pyd / AVLDL.so —the PyAvl-DL extension module
  • AVLDL.pyi —type stub file for IDE support
  • pyproject.toml, hatch_build.py —pip build metadata and the build hook
  • AVLDL.dll and its runtime dependencies (Windows)
  • CUDA and OnnxRuntime DLLs from the Deps_x64 directory (Windows, GPU builds)
  • Shared library runtime dependencies (Linux)

No files need to be copied or moved —pip reads them directly from these folders.

Setup on Windows

Install the packages from the directories inside the Aurora Vision Library installation:

  1. Open a command prompt or PowerShell window.
  2. Install PyAvl:

    pip install "<avl_install_dir>\Library\bin\x64"

  3. Install PyAvl-DL (optional, requires the Deep Learning add-on):

    pip install "<dl_install_dir>\Library\bin\x64"

After this, import AVL and import AVLDL work in every Python session.

To verify:

python -c "import AVL; print('AVL imported successfully')"

python -c "import AVLDL; print('AVLDL imported successfully')"

Setup on Linux

On Linux, Aurora Vision Library installs the package files into:

  • PyAvl: /opt/AuroraVision/AVL-5.7/lib/x86_64-linux-gnu/
  • PyAvl-DL: /opt/AuroraVision/AVLDL-5.7/lib/x86_64-linux-gnu/

Run pip install directly from these directories:

pip install "/opt/AuroraVision/AVL-5.7/lib/x86_64-linux-gnu/"

pip install "/opt/AuroraVision/AVLDL-5.7/lib/x86_64-linux-gnu/"

The build hook (hatch_build.py) packages the extension module, type stubs, and all shared library dependencies directly into the wheel. No LD_LIBRARY_PATH configuration is needed.

To verify:

python3 -c "import AVL; print('AVL imported successfully')"

python3 -c "import AVLDL; print('AVLDL imported successfully')"

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.

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)

PyAvl Example —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}")

Image Acquisition

PyAvl includes built-in support for image acquisition from industrial cameras via GigE Vision and GenICam. No third-party camera SDK is required.

  • GigE Vision —enumerate and connect to GigE Vision cameras on the network using AVL.GigEVision_FindDevices and AVL.GigEVision_OpenDevice.
  • GenICam parameters —read and write camera parameters (exposure, gain, gamma, etc.) through the GenICam interface via dev.GetParamExists, dev.SetFloatParam, and related methods.
  • Streaming —start continuous acquisition with dev.StartAcquisition and grab frames directly into AVL.Image objects with dev.ReceiveImage.

PyAvl Example —GigE Vision Streaming

Enumerate GigE Vision devices, connect, and capture frames in a loop:

import AVL

# Find all GigE Vision cameras on the network (2 second timeout)
devices = AVL.GigEVision_FindDevices(2000)
if not devices:
    raise RuntimeError("No GigE Vision devices found")

# Open the first available device
dev = AVL.GigEVision_OpenDevice(devices[0].IpAddress)

# Acquire and process frames
dev.StartAcquisition(dev.GetPixelFormats()[0])
frame = AVL.Image()

try:
    while True:
        dev.ReceiveImage(frame)
        # process frame here ...
finally:
    dev.StopAcquisition()
    dev.Close()

Included Examples

The Aurora Vision Library installation includes ready-to-run Python examples:

  • PyAvl —examples/avl/08 Python/
  • PyAvl-DL —examples/deep_learning/

Troubleshooting

ImportError: DLL load failed while importing AVL (Windows)

The wrapper depends on AVL.dll. If Python cannot locate it:

  • Ensure you ran pip install from the correct directory. The build hook packages all required DLLs into the wheel.
  • Confirm you are running 64-bit Python 3.12.

ImportError: DLL load failed while importing AVLDL (Windows)

The DL wrapper depends on AVLDL.dll and CUDA/OnnxRuntime DLLs:

  • Ensure both PyAvl and PyAvl-DL are installed via pip install.
  • Ensure the Deep Learning add-on is installed on the machine.
  • For GPU inference, verify CUDA drivers are installed.

ImportError: cannot open shared object (Linux)

If the shared libraries cannot be found:

  • Confirm the pip install completed without errors. On Linux, pip packages all shared library dependencies directly into the wheel.
  • Re-run pip install from the installation directory to refresh the package.

ModuleNotFoundError: No module named 'AVL'

Python cannot find the extension module:

  • Run pip show pyavl and confirm the installation is present.
  • Confirm you are using the same Python environment where the package was installed.

ModuleNotFoundError: No module named 'AVLDL'

Python cannot find the DL extension module:

  • Run pip show pyavl-dl and confirm the installation is present.
  • PyAvl-DL depends on PyAvl. Run pip show pyavl to confirm PyAvl is also installed.

Wrong Python Version

The wrapper is compiled for Python 3.12 only. Verify:

python --version

If the output is not Python 3.12.x, switch to Python 3.12 before importing.

Hints

  • Use a virtual environment to isolate dependencies and avoid version conflicts.
  • Use the help() function to explore available functions and their signatures at the Python prompt.
  • .pyi stub files sit alongside the extension module and enable IDE code completion and static type checking.
  • PyAvl-DL requires PyAvl. Install PyAvl first, then PyAvl-DL.

See Also

Previous: Using Library on Android Next: Technical Issues