Last Update: 2020-08-12

Installation

Overview

If you like to develop an EnMAP-Box application, or more general, a QGIS and Qt application, we recommend to use a state-of-the-art Integrated Development Environment (IDE) like PyCharm. It offers run-time debugging, code completion, spell-checking, syntax highlighting, SCM support, unit-testing and many other helpful things.

Furthermore, we recommend to install QGIS within a conda / anaconda environment. The installation is (almost) the same on macOS, windows or linux, it is much easier to install additional python packages and admin rights are not required, e.g. to update QGIS.

1. Have Git installed

If not, download and install Git from https://git-scm.com/downloads

Check if git is installed to your local shell, e.g. as:

C:\Windows\System32>git --version
git version 2.26.0.windows.1

2. Clone this repository

Clone the EnMAP-Box repository (or a fork) to your local my_repositories folder:

cd my_repositories
git clone https://bitbucket.org/hu-geomatics/enmap-box.git

Now you can use git pull to update your local copy of the EnMAP-Box repository:

cd my_repositories/enmap-box
git pull

Tip

Replace the repo uri with that of your EnMAP-Box repo fork, if you like to provide code via pull requests.

3. Create a QGIS conda environment

The following setup bases on this description and installs QGIS into a Conda environment. It was tested successfully on Windows 10, Ubuntu 18 and macOS.

  1. Create a new conda environment qgis_stable and install qgis from the conda-forge channel

    $>conda create -n qgis-stable -c conda-forge qgis

  2. Activate the new environment

    $>conda activate qgis_stable

  3. Install other required packages, e.g. that listed in enmap-box/requirements.txt and enmap-box/requirements_developers.txt.

    (qgis_stable) $>conda install scikit-learn --channel=conda-forge
(qgis_stable) $>conda install matplotlib --channel=conda-forge

    Some python packages which are not available as conda package can be installed directly with pip.

    (qgis_stable) $>pip install gitpython
(qgis_stable) $>pip install git-lfs

    Note

    Depending on the components and applications you like to use, it might be required to install more packages.

  4. Now you can start QGIS, the Qt Designer and Qt Assistant from your conda shell:

    (qgis_stable) $>qgis
(qgis_stable) $>designer
(qgis_stable) $>assistant

    macOS Users

    If you are using macOS and calling qgis does not show any application window, it might be necessary to set:

    `export QT_MAC_WANTS_LAYER=1`

    This can be done permanently for the qgis_stable environment by:

    `(qgis_stable) conda env config vars set QT_MAC_WANTS_LAYER=1`

  5. Start python and check it’s version. It should be a Python >= 3.7. Calling quit() will close the python interpreter and return you to the conda shell:

    (qgis_stable) C:\>python
Python 3.8.1 | packaged by conda-forge | (default, Jan  5 2020, 20:17:16) [MSC v.1916 64 bit (AMD64)] on win32
Type "help", "copyright", "credits" or "license" for more information.
>>> quit()

(qgis_stable) C:\>

4. Setup PyCharm

  1. Start PyCharm and add my_repositories/enmap-box as new project via File > Open File or Project

  2. If this is not already the case, tell PyCharm where to find your Git-executable. Open File > Settings > Version Control > Git to set Path to Git executable. Press Test to check the used Git version.

    ../_images/pycharm_git_settings.png

    Set the Git executable used by PyCharm

    Tip

    Use where to return the path of a git-executable that is available in your DOS/Linux/macOS shell

    (qgis_stable) C:\>where git
C:\Users\geo_beja\AppData\Local\Programs\Git\cmd\git.exe

  3. Switch to Project: enmap-box > Project Interpreter and add your conda qgis_stable python as project interpreter

    ../_images/pycharm_conda_interpreter_add.png

    Add the qgis_stable python to the list of python interpreters

    ../_images/pycharm_conda_interpreter.png

    Select the qgis_stable python as project interpreter

  4. Switch to Project Structure and add

    • (Linux/Win) <your conda installation>/envs/qgis_stable/Library/python as additional project content root.
    • (macOS) <your conda installation>/envs/qgis_stable/QGIS.app/Contents/MacOS/../Resources/python

    Right-click on the plugins subfolder and select Sources. Now the PyQGIS API is available to your Python installation.

    Tip

    The same way allows you to include other directories to your project’s PYTHONPATH, e.g. to make code available from other folder or repositories.

    ../_images/pycharm_project_content_roots.png

    Use qgis_stable/Library/python as additional content root

  5. (Windows + macOS) set the QGIS_PREFIX_PATH variable

    PyCharm and PyQGIS need the environmental variable QGIS_PREFIX_PATH.

    Typical paths are:

    OS QGIS_PREFIX_PATH
    Windows <your conda installation>\envs\qgis_stable\Library
    Linux <your conda installation>/envs/qgis_stable/Library
    macOS <your conda installation>/envs/qgis_stable/QGIS.app/Contents/Resources

    Open Run > Debug … > Edit Configurations and add the QGIS_PREFIX_PATH to the User environmental variables. This way PyCharm runs python files in a environment with QGIS_PREFIX_PATH defined.

    ../_images/pycharm_QGIS_PREFIX_PATH.png

    Also define the Environment variables for the Python console. Go to File > Settings > Build, Execution, Deployment > Console > Python Console and add QGIS_PREFIX_PATH to the Environment variables.

    ../_images/pycharm_qgispath_console.png

    You might also like to use the conda environment shell in your Pycharm terminal. Open Tools > Terminal and set the shell path to cmd.exe "/K" <your conda installation>\Scripts\activate.bat qgis_stable

    ../_images/pycharm_conda_terminal.png

    How to use the conda terminal in PyCharm

  1. Test the Python environment

    To check if the QGIS API is available, open a Python Console and import the QgsApplication object.

    from qgis.core import QgsApplication
QgsApplication.instance() is None

    The output should return True, as we have not initialized any QgsApplication.

    Now check if we can use the EnMAP-Box API to start the EnMAP-Box

    import enmapbox
enmapbox.run()

    This should initialize a new QgsApplication and start the EnMAP-Box. The outputs printed to the python shell should look like:

    Application state:
QGIS_PREFIX_PATH env var:               D:\miniconda3\envs\qgis_stable\Library
Prefix:         D:\miniconda3\envs\qgis_stable\Library
Plugin Path:            D:\miniconda3\envs\qgis_stable\Library/plugins
Package Data Path:      D:\miniconda3\envs\qgis_stable\Library/.
Active Theme Name:
Active Theme Path:      D:\miniconda3\envs\qgis_stable\Library/./resources/themes\\icons/
Default Theme Path:     :/images/themes/default/
SVG Search Paths:       D:\miniconda3\envs\qgis_stable\Library/./svg/
        C:\Users\geo_beja\AppData\Local\Temp\QGIS-PythonTestConfigPathp1k7w_s_\profiles\default/svg/
User DB Path:   D:\miniconda3\envs\qgis_stable\Library/./resources/qgis.db
Auth DB Path:   C:\Users\geo_beja\AppData\Local\Temp\QGIS-PythonTestConfigPathp1k7w_s_\profiles\default/qgis-auth.db

    If the terminal environment was setup well, you can start the EnMAP-Box from the Terminal window as well by

    (qgis_stable) ..\enmap-box>python enmapbox

Other Tools

The Qt company provides several tools to that help to create Qt applications and are useful for PyQt and PyQGIS users as well.

Qt Assistant

The Qt Assistant allows you to browse fast and offline through Qt help files (*.qch). These files exists for all Qt classes and the QGIS API. They can be generated event with Sphinx, which allows you to provide your own source-code documentation as .qch file as well.

  1. Start the Qt Assistant, e.g. from your PyCharm terminal:

    (qgis_stable) $>assistant

  2. Download the *.qch* files which contain:

    • the Qt API documentation QtDocs.zip (please extract)
    • the QGIS API documentation qgis.qch

    Go to Preferences > Add and add the follwing *.qch files

    File Documentation
    qgis.qch qgis.core, qgis.gui
    qtcore.qch Qt5.QtCore
    qtgui.qch Qt5.QtGui
    qtwidgets.qch Qt5.QtWidgets

    Now you can explore the Qt (Q...) and QGIS (Qgs...) classes

    ../_images/qt_assistant.png

Qt Designer

The Qt Designer is a powerful tool to create GUI frontends by drawing, drag and drop. Created GUI form files are saved in a XML file ending with *.ui. These can be called from python to automatically create the entire GUI backend, e.g. windows and buttons defined with the Qt Designer.

You can start the Qt Designer from your PyCharm terminal by:

(qgis_stable) $>designer
../_images/qt_designer_example.png

Qt Designer showing the metadataeditor.ui for the Metadata editor.

Qt Creator

Qt Creator is the one-in-all IDE to develop Qt C++ applications. It includes the functionality covered by Qt Assistant (here called Help) and Qt Designer (here called form designer) and helps to browse C++ code. It is the preferred tool to explore the QGIS C++ source code, for example if you like to better understand what it does behind the QGIS python API.

Qt and the Qt Creator are available at https://www.qt.io/download. Ensure to install the code documentation for the same Qt version used by QGIS.

../_images/qt_creator_example_ui.png

Qt Creator with opened metadataeditor.ui.

References