cuvis.pyil (python interface layer; required for using the python wrapper)

cuvis.pyil is the python interface binding for the Cuvis SDK written in C (available here).

• Website: https://www.cubert-hyperspectral.com/
• Source code: https://github.com/cubert-hyperspectral/
• Support: http://support.cubert-hyperspectral.com/

For other supported program languages, please have a look at the source code page.

Installation

Prerequisites

First, you need to install the Cuvis C SDK from here. The installation registers the installation path in the environment, which the python interface layer is linked to.

⚠️ If the C SDK is reinstalled into another directory later on, the linkage breaks and the python wrapper might stop working.

Via pip

If you wish to use cuvis-il within another project, from within your project environment, run

pip install cuvis-il

or add cuvis-il to your project requirements.txt or setup.py. We currently provide pre-compiled binaries for Python 3.10, 3.11, 3.12, 3.13 and 3.14, for Windows and for Linux on x86_64 and aarch64. The Linux wheels are built against glibc 2.35 and install on Ubuntu 22.04 and every newer release, 24.04 and 26.04 included.

Via Docker

The image cubertgmbh/cuvis_pyil:<sdk version>-ubuntu<22.04|24.04|26.04>[-arm64] ships the cuvis SDK and the matching cuvis-il in a virtual environment at /opt/venv, already on PATH. The tag names the cuvis SDK version and always points at the newest interface layer built for it.

FROM cubertgmbh/cuvis_pyil:3.5.3-ubuntu24.04
RUN pip install "cuvis==3.5.3.*"

adds the cuvis wrapper, or interactively

docker run -it cubertgmbh/cuvis_pyil:3.5.3-ubuntu24.04 bash
pip install cuvis

Build manually via repository

If you wish to download and use cuvis locally, clone the git repository

git clone git@github.com:cubert-hyperspectral/cuvis.pyil.git
cd cuvis.pyil

and then initialize the submodules.

git submodule update --init --recursive

For building the python stubs for wrapping between C libraries and python, you'll need SWIG (see https://www.swig.org/download.html).

Next make sure that your preferred version of NumPy is manually pre-installed in your go-to environment. See here. Also make sure that the additional build dependencies are installed.

python -m pip install wheel setuptools numpy==YOUR_NUMPY_VERSION -qq 

Then use CMake (see https://cmake.org/download/) to configure and generate your project. CMake will require you to locate the Cuvis C SDK (this should be found automatically, if the Cuvis C SDK is properly installed). Also, you need to point the variable SWIG_EXECUTABLE to the path of the swig.exe.

Build and install the CMake Project via

mkdir build
cd build
cmake  -DCMAKE_BUILD_TYPE=Release -DDOXYGEN_BUILD_DOCUMENTATION=OFF -DPython_ROOT_DIR=venv ..
cmake --build . --target cuvis_pyil --config Release
cp ./_cuvis_pyil.so ../cuvis_il
cp ./cuvis_il.py ../cuvis_il
cd ..
python -m pip install .

This project will then generate the _cuvis_pyil.pyd and cuvis_il.py files needed for running the Cuvis Python SDK wrapper. Those then can be used to install the cuvis_il package.

⚠️ You might also use the cuvis_il.py directly, which provides all functionalities as single methods without organization into objects. Support for code without the additional wrapper is limited, though.

Dependency to NumPy

The python interface layer is dependent on NumPy. Specifically, this means that we need the C headers of the NumPy library. Notice that NumPy has forward compatibility for minor versions. As of version 1.25 NumPy also offers its ABI in a backwards compatible way. To compile the python interface layer install your preferred version of NumPy. For example the newest stable release via

pip install numpy

CMake will try to find the NumPy path using the find_package(Python REQUIRED COMPONENTS Interpreter Development NumPy). To support the usage of a virtual environment, set the Python_ROOT_DIR variable to the directory containing your virtual environment.

Our pre-compiled binaries are compiled with NumPy 2.0.0 for Python 3.10, 3.11 and 3.12, 2.1.0 for Python 3.13 and 2.3.2 for Python 3.14. This should ensure that the bindings are build in a forward and backwards compatible way.

Getting involved

cuvis.hub welcomes your enthusiasm and expertise!

With providing our SDK wrappers on GitHub, we aim for a community-driven open source application development by a diverse group of contributors. Cubert GmbH aims for creating an open, inclusive, and positive community. Feel free to branch/fork this repository for later merge requests, open issues or point us to your application specific projects. Contact us, if you want your open source project to be included and shared on this hub; either if you search for direct support, collaborators or any other input or simply want your project being used by this community. We ourselves try to expand the code base with further more specific applications using our wrappers to provide starting points for research projects, embedders or other users.

Getting help

Directly code related issues can be posted here on the GitHub page, other, more general and application related issues should be directed to the aforementioned Cubert GmbH support page.