You are here: Start » Using Python Wrapper

Using Python Wrapper

Aurora Vision Library Lite includes a Python wrapper - a native extension module that exposes the full Aurora Vision Library to Python 3.12 programs. The wrapper is installed together with Aurora Vision Library Lite and does not require a separate download or a PyPI package.

Requirements

Python 3.12 (64-bit). Other versions are not supported.
Aurora Vision Library Lite installed on the machine. The wrapper files are placed in the installation folder during the standard AVL setup.
Windows 10 or 11 (64-bit).

The wrapper is distributed as a compiled .pyd file (a Windows native Python extension). It does not require compilation. A pyproject.toml file is included alongside the .pyd to support editable pip installation.

Setting Up Access to the Wrapper

To use the wrapper, Python needs to be able to find the .pyd file. Python wrappers are linking dynamically to the Aurora Vision Library DLLs, so the folder containing these DLLs must also be accessible.

There are three ways to make the wrapper importable in Python. Choose the method that best fits your workflow. All examples below use C:\Program Files\Aurora Vision\Aurora Vision Library 5.7\bin\x64 as a placeholder for the actual path to the folder containing the .pyd file and pyproject.toml. Replace it with the real path from your installation.

Option 1: Editable pip Install (Recommended)

This method registers the wrapper as an installed package. It requires running the command once and works automatically in every Python session afterwards.

Open a command prompt or PowerShell window.
Run the following command, replacing the placeholder with the actual path:
pip install -e C:\Program Files\Aurora Vision\Aurora Vision Library 5.7\bin\x64

After this, you can import the wrapper in any Python script without any further configuration using import AVL.

To verify the installation:

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

Option 2: PYTHONPATH Environment Variable

This method adds the wrapper folder to Python's module search path via an environment variable. It does not modify the Python installation and is easy to set per-project or per-session.

For the current session only (command prompt):

set PYTHONPATH=C:\Program Files\Aurora Vision\Aurora Vision Library 5.7\bin\x64;%PYTHONPATH%

For the current session only (PowerShell):

$env:PYTHONPATH = "C:\Program Files\Aurora Vision\Aurora Vision Library 5.7\bin\x64;$env:PYTHONPATH"

Permanently (system-wide): add C:\Program Files\Aurora Vision\Aurora Vision Library 5.7\bin\x64 to the PYTHONPATH user environment variable via System Properties → Environment Variables.

Once the variable is set, use import AVL in your script.

Option 3: PATH Extension

Python also discovers extensions placed in directories listed on the system PATH. This method requires no changes to PYTHONPATH but affects all executables looking up DLLs, so it is better suited for development machines than production deployments.

Temporarily in a script (affects only the running process): add the following lines before the import:

import sys
sys.path.insert(0, r"C:\Program Files\Aurora Vision\Aurora Vision Library 5.7\bin\x64")
import AVL

For the current PowerShell session only:

$env:PATH = "C:\Program Files\Aurora Vision\Aurora Vision Library 5.7\bin\x64;$env:PATH"

Once the folder is on the path, use import AVL in your script.

Verifying the Installation

Run the following command to confirm the wrapper loads correctly:

python -c "import AVL; print(dir(AVL))"

A successful run prints a long list of Aurora Vision function names. If you see an ImportError instead, refer to the Troubleshooting section below.

First Steps

API Conventions

The Python wrapper exposes all Aurora Vision Library functions directly under the AVL module. A few conventions are worth knowing before you start:

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 (e.g. diagBrightnessProfile, diagGradientMagnitudeImage). These default to None and have no effect unless explicitly passed.

Short Example

The following script loads an image, applies Gaussian smoothing and checks for a colored region — the same pattern used in the inspection examples shipped with Aurora Vision Library Lite:

import AVL

# Load an image from disk
image = AVL.Image()
AVL.LoadImage("sample.png", image)

# Smooth the image
smoothed = AVL.Image()
AVL.SmoothImage_Gauss(image, smoothed, inStdDevX=3)

# Define an inspection region (circle) and check for a color presence
spot   = AVL.Circle2D(AVL.Point2D(200.0, 200.0), 50)
region = AVL.ShapeRegion(spot)
result = AVL.CheckPresence_PixelAmount(
    smoothed, region,
    inBeginHue=26, inEndHue=52,
    inMinSaturation=42, inMinBrightness=62,
    inMinAmount=0.8
)

print("Present:", result.outIsPresent, "  Amount:", result.outAmount)

For more complete examples see the examples/avl/08 Python/ folder in the Aurora Vision Library Lite installation directory.

Troubleshooting

ImportError: DLL load failed while importing AVL

The wrapper depends on AVL.dll and its native dependencies. If Python cannot locate them, the import fails with a DLL load error. To fix this:

Make sure Aurora Vision Library Lite is properly installed (run the installer again if in doubt).
Ensure that the bin folder of Aurora Vision Library Lite (containing AVL.dll) is on the system PATH. The standard installer sets this automatically.
Check that you are running a 64-bit Python. The wrapper is built for 64-bit only.

ModuleNotFoundError: No module named 'AVL'

Python cannot find the wrapper. Verify that exactly one of the three setup methods was applied correctly:

If using pip editable install, confirm the install succeeded: run pip show AVL and check that the location points to the correct folder.
If using PYTHONPATH, confirm the variable contains the correct path in the current session: run echo %PYTHONPATH% (cmd) or $env:PYTHONPATH (PowerShell).
If using sys.path.insert, confirm the insert happens before the import statement and that the path string is correct.

Wrong Python Version

The wrapper is compiled for Python 3.12 only. Using any other Python version produces a DLL load failed or Invalid module error. Verify your active Python version:

python --version

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

Path Precedence Conflicts

If both PYTHONPATH and sys.path.insert are used in the same session, Python searches locations in the order they appear in sys.path. An earlier entry shadows a later one. To inspect the current search order:

python -c "import sys; [print(p) for p in sys.path]"

If an incorrect or stale path appears before the correct wrapper folder, remove it or reorder the entries.

Hints

Use a virtual environment to manage dependencies and avoid conflicts with other Python packages.
Using help() function to explore available functions and their usage.
File .pyi provides type hints for the wrapper for most popular IDEs.