Troubleshooting
==========================

.. _troubleshooting-dll-error:

ImportError: DLL load failed while importing _bindings
------------------------------------------------------

The _bindings module contains the code to interface between Python and C++ and is actually a compiled shared library.
Failure to load it often can be attributed to the following causes:

* The dependencies cannot be loaded.
   The _bindings shared library depends on the ImFusionLib shared library, which has a couple of dependencies of its own.
   Make sure that you set the required environment variables as described in :doc:`../getting_started/installing`.
   If the problem persists, you can try ``ldd`` (Linux) or `Dependency Walker <http://dependencywalker.com/>`_ (Windows) to find which libraries could not be located and set ``LD_LIBRARY_PATH`` or ``PATH`` accordingly.
   You can also try to load the shared library directly in Python, which usually gives a better error message::

        >>> import ctypes  # doctest: +SKIP
        >>> ctypes.WinDLL('C:\\Program Files\\ImFusion\\ImFusion Suite\\Suite\\imfusion\\_bindings.cp310-win_amd64.pyd')  # doctest: +SKIP

* There are conflicting dependencies.
   The ImFusionLib comes with its own set of dependencies, e.g. it requires a certain version of the Qt framework. If another module (e.g. PySide2) now loads a different version before, the _bindings module cannot be loaded because of this version conflict. This often happens with Anaconda or other programs in the ``PATH`` environment variable. Try ``ldd`` (Linux) or `Dependency Walker <http://dependencywalker.com/>`_ (Windows) to see where dependencies are loaded from.

Also see, :ref:`pythonpath-issue` if your case is not covered here.

ImportError: undefined symbol
-----------------------------

Linux equivalent of :ref:`troubleshooting-dll-error`

.. _pythonpath-issue:

Other inexplicable import errors
--------------------------------

In the past, the ImFusion Python SDK was not distributed as installable packages but as a folder contained in the ImFusion Suite installer.
To be able to import :mod:`imfusion`, users had to set PYTHONPATH to point to said folder.
If you are having inexplicable errors when importing the imfusion module, please double-check that you do not still have either global or venv-local PYTHONPATH that points to an old ImFusion Suite installation.
The symptoms of this can be anything ranging from license issues (e.g. "invalid license key format") to dependency load issues ("undefined symbol" on Linux, "specified procedure not found" on Windows).

You can diagnose where Python is attempting to load :mod:`imfusion` from by running::

    >>> import importlib  # doctest: +SKIP
    >>> importlib.util.find_spec("imfusion").origin  # doctest: +SKIP

The up-to-date way of installing the Python SDK is described in :doc:`../getting_started/installing`.

RuntimeError: Could not create main OpenGL context
--------------------------------------------------

The :mod:`imfusion` module currently requires an OpenGL context and therefore a GPU.
First thing to check is therefore that you have a GPU and a working driver.
While a discrete GPU is recommended, any integrated GPU works.

If you are using Windows Remote Desktop (RDP) and a Nvidia GPU, you need to run nvidiaopenglrdp.exe which you can download from `Nvidia <https://developer.nvidia.com/nvidia-opengl-rdp>`_.
Otherwise, Windows Remote Desktop won't support OpenGL.
We are currently not aware of a similar solution for AMD or Intel GPUs, other than switching to a different remote desktop tool like Teamviewer or NoMachine.

This issue was also encountered on Linux when there was no X Server running, e.g. on headless server machines.
As a workaround, you can start your python interpreter with``xvfb-run``.
It is part of the ``xvfb`` debian package and provides a software implementation of OpenGL, but will be slower in most situations.

If you are trying to run the module with docker and require proper GPU support, please contact us directly and we can provide a special build.

Floating point parameters are loaded as integers in Properties
--------------------------------------------------------------

Some Python modules change the locale of the program to e.g. German which uses `,` instead of `.` as decimal separator.
You can change the locale with::

    >>> import locale  # doctest: +SKIP
    >>> locale.setlocale(locale.LC_NUMERIC, 'C')  # doctest: +SKIP

See https://docs.python.org/3.7/library/locale.html for details.

Extra whitespace in Windows console
-----------------------------------

On certain setups, all log messages produced by the ImFusionLib contain an extra space after every character, l i k e  t h i s.
This seems to be an issue with Python changing the console mode from O_TEXT to O_BINARY, and log4cxx messing up the encoding.
As a workaround, you can redirect the logging messages to the Python logging module (see :doc:`logging`).