You are here: Start » Getting Started » Python API

Python API

Aurora Vision Library provides a Python package that exposes the Aurora Vision Library 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.

The package ships as a pre-compiled native extension module (.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.
  • Windows 11 (64-bit) or a supported 64-bit Linux distribution.

Installation Files

The package and all its supporting files are placed in the same directory inside the Aurora Vision Library installation.

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

  • 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 file into a wheel
  • AVL.dll and its runtime dependencies (Windows)
  • Shared library runtime dependencies (Linux)

No files need to be copied or moved — pip reads them directly from this folder.

Setup on Windows

Install PyAvl from the package directory inside the Aurora Vision Library installation:

  1. Open a command prompt or PowerShell window.
  2. Run:

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

After this, import AVL works in every Python session. The generated .pth file stores the absolute path to the installation directory, so if Aurora Vision Library is moved or reinstalled at a different location, run pip install again to update the registered path.

To verify:

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

If you prefer not to use pip, you can instead set up access manually:

  • PYTHONPATH (current session, cmd): set PYTHONPATH=<install_dir>\Library\bin\x64;%PYTHONPATH%
  • PYTHONPATH (current session, PowerShell): $env:PYTHONPATH = "<install_dir>\Library\bin\x64;$env:PYTHONPATH"
  • PYTHONPATH permanently: add the path via System Properties → Environment Variables.
  • Inside a script: import sys; sys.path.insert(0, r"<install_dir>\Library\bin\x64") before the import.

When using the manual methods you must also ensure the bin\x64 folder is on the system PATH so that AVL.dll can be located. The standard installer sets this automatically; the pip install handles it via the .pth file and does not require PATH changes.

Setup on Linux

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

/opt/AuroraVision/AVL-5.7/lib/x86_64-linux-gnu/

Run pip install directly from this directory:

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

The build hook (hatch_build.py) packages AVL.so, AVL.pyi, and a .pth file into the wheel. The .pth file uses ctypes to load the shared library dependencies at Python startup so that no manual LD_LIBRARY_PATH configuration is needed. The path is recorded at install time, so if Aurora Vision Library is upgraded or reinstalled at a different path, run pip install again to update it.

To verify:

python3 -c "import AVL; print('AVL 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 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/

Troubleshooting

ImportError: DLL load failed while importing AVL (Windows)

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

  • Ensure the bin\x64 folder is on the system PATH. The standard installer sets this automatically; the pip install handles it via the .pth file.
  • Confirm you are running 64-bit Python.

ImportError: cannot open shared object (Linux)

If the .pth file did not load the shared library correctly:

  • Confirm the pip install completed without errors and that the .pth file is present in your site-packages.
  • As a fallback, add the installation lib/x86_64-linux-gnu directory to LD_LIBRARY_PATH: export LD_LIBRARY_PATH=/opt/AuroraVision/AVL-5.7/lib/x86_64-linux-gnu:$LD_LIBRARY_PATH

ModuleNotFoundError: No module named 'AVL'

Python cannot find the extension module:

  • pip install: run pip show pyavl and confirm the location points to the correct folder.
  • PYTHONPATH: confirm the variable is set in the current session.
  • sys.path.insert: confirm the insert happens before the import statement.

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.

See Also

Previous: Using User Filters on Linux Next: Technical Issues