Installation
============

OS Support
----------

Currently, we support Windows. Some pyd files are not available for other platforms. We are working on it.

Python Version
--------------

We support Python 3.10.x.

`Python 3.10.11 <https://www.python.org/downloads/release/python-31011/>`_ is recommended for the best performance and compatibility.
For your information `Blender <https://www.blender.org/>`_ 4.0 is also using Python 3.10.

.. note::
    You can also use :

    - `miniconda <https://docs.anaconda.com/miniconda/install/#quick-command-line-install>`_ or anaconda. Miniconda with Python 3.10 is available `here <https://repo.anaconda.com/miniconda/Miniconda3-py310_24.9.2-0-Windows-x86_64.exe>`_. By default, the miniconda's installation path is `C:\\Users\\username\\AppData\\Local\\miniconda3`. You can change it during the installation.
    - `uv <https://docs.astral.sh/uv/guides/projects>`_ which is an extremely fast Python package and project manager, written in Rust. uv can install multiple versions of Python and replace pip.

.. attention::
    We are now preparing a version for Python 3.11. It will be available soon.
    Blender 4.1 and above is using Python 3.11.


VC++ Redistributable
--------------------

You need to install the `Visual C++ Redistributable <https://support.microsoft.com/en-us/help/2977003/the-latest-supported-visual-c-downloads>`_ to run the package.

Virtual environment
-------------------

We strongly recommend to create a virtual environment for your installation. This will avoid conflicts with other packages that you may have installed on your machine:

``python -m venv myenv``

Then activate it:

``myenv\Scripts\activate`` (Windows)

.. note::
    With (mini)conda, you can `manage virtual environments easily <https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html>`_. You can create a new environment with the following command:

    ``conda create --name myenv python=3.10``

    Then activate it:

    ``conda activate myenv``

Then you can install the package as described below.

Via Pip
-------

Once your Python environment is set up. You can install our main package via pip:

``pip install wolfhece`` or ``pip install wolfhece --user``

.. note::
    ``user`` option is needed if you don't have the right to install packages globally.

For **wolfgpu**, the wheel is **not available** at Pypi. `Contact us <mailto:pierre.archambeau@uliege.be>`_ to get the wheel.


Dependencies will be installed automatically **BUT** :ref:`Gdal<gdal_package>` and :ref:`Graphviz<graphviz>` are not installed automatically. You need to install them manually.

.. attention::
    `Conda <https://www.anaconda.com/blog/understanding-conda-and-pip>`_ is more powerful than pip and can install
    gdal and graphviz packages. You can use the following commands:

    ``conda install -c conda-forge gdal``

    ``conda install -c conda-forge graphviz``

Check
-------

Once installed, check the installation by typing:

``wolf_check``

If all is fine, you should see the following message:

.. image:: _static/install/wolf_check.png
    :alt: check installation

GPU capabilities
----------------

We use OpenGL shaders to accelerate the rendering of the scene.
If your GPU does not support OpenGL 4.6, we cannot guarantee full compatibility.

.. note::
    if `wolfgpu` is installed, you can check the GPU capabilities by typing:

    ``wolfgpu --gpu-info``


Upgrade
-------

To upgrade the package, you can use the following command:

``pip install --upgrade wolfhece``


GDAL
----

.. _gdal_package:

You need to install GDAL to use the package.

`GDAL <https://gdal.org/>`_ is a library for geospatial data processing. It is used by many GIS (Geographic Information System) software to read and write geospatial data. It is also used by many satellite image processing software.

.. warning::
    It is quite common to encounter difficulties in installing this package. Here are some tips for installing it on your machine.

    To install the GDAL package, **avoid to try** ``pip install GDAL``. If you are lucky, it will work. If not, you will have to install it manually.
    We recommended to install the GDAL package by
    downloading the desired version from this `website <https://github.com/cgohlke/geospatial-wheels/releases>`_  and
    then install it using "pip install myfile.whl" where myfile.whl corresponds to the downloaded file.

    Or use `conda` environment as described above.

Graphviz
--------

For the hydrology part, you need to install `Graphviz <https://graphviz.org/>`_.

Graphviz is an open-source graph visualization software. It has several main graph layout programs. It is used by many software to visualize graphs.

.. warning::
    Graphviz must be accessible from the command line.

    You can check this by typing ``dot -V`` in a command prompt. If it is not accessible, you need to add the path to the Graphviz bin folder to the PATH environment variable.

    Or use `conda` environment as described above.

Dependencies
------------

The package has several DLLs files that are needed to run the package. These files are mainly located in the package subfolder `/libs`.

If necessary, you can analyze the dependencies of the pyd with the "pyi-bindepend" tool from PyInstaller, or the "dumpbin" tool from VisualStudio.

.. attention::
    `wolfhece` uses Numpy.

    - 2.1.x versions are compatible with Numpy 1.23.5.
    - 2.2.x versions are compatible with Numpy 2.1.x

    There are a lot of changes in Numpy 2.0.x.

    Our package has been largely tested with Numpy 1.23.5.

    The tests are passing with Numpy 2.1.x but we cannot guarantee that all the features are working with Numpy 2.1.x. If you encounter problems, please report them to us asap.