EnMAP-Box repository

The EnMAP-Box source code is hosted in a Git repository at https://bitbucket.org/hu-geomatics/enmap-box

Structure

Overview

The repository contains the following files and folders:

Folder/File Purpose
doc/ EnMAP-Box Sphinx *.rst documentation
enmapbox/ EnMAP-Box source code
enmapboxtesting/ Unit tests
scripts/ Scripts to maintain the repository and build the EnMAP-Box QGIS Plugin
examples/ Code examples how to use the EnMAP-Box API
examples/minimumexample/ Exemplary EnMAP-Box Application
site-packages/ Other python libraries the EnMAP-Box depends on
snippets/ Small source code snippets.
CHANGELOG  
LICENCE.txt  
LICENCE.md  
README.md  
__init__.py  
CONTRIBUTORS.md  
index.html  
requirements.txt  
requirements_developer.txt  
setup.py required for read-the-docs installation
.gitignore defines files that should be ignored by the repository
.gitattributes defines binary files that are stored with git-lfs
.readthedocs.yml  

Scripts for Developers

The scripts directory contains scrips to support developers. Ensure that this folder is part of your python path, e.g add it as source in your PyCharm project (left-mouse, mark directory as source):

Script Purpose
scripts/setup_repository.py Creates resource files etc. required to test the EnMAP-Box by calling other scripts
scripts/create_plugin.py Create the EnMAP-Box Plugin ZIP file.
scripts/create_plugin.py Create the two shell-scripts runtests.bat and runtests.sh to run unit tests.
scripts/install_testdata.py Downloads and installs the EnMAP-Box testdata and qgisresources
scripts/compile_resourcefiles.py Complies EnMAP-Box resources (*.svg, *.png) into *_rc.py files
scripts/iconselect.py Opens a browser to show EnMAP-Box and QGIS resources, e.g. icons
scripts/updateexternals.py Update parts of the EnMAP-Box code which are hosted in external repositories. Read here for details.

Generated Folders

Some directories and files are not part of the repository and explicitly ignore in the .gitignore file, but required or created during the development process. These are:

enmapboxtestdata/ Official EnMAP-Box testdata. Not part of repository code, can be installed calling scripts/install:_testdata.py.
qgisresources/ QGIS resources compiled as python modules. Read here for details.
deploy/ Builds of the EnMAP-Box plugin.
deploy/enmapboxplugin Folder with last EnMAP-Box Plugin build.
deploy/enmapboxplugin.3.X…zip Zipped version of a EnMAP-box Plugin build.

Install the EnMAP-Box repository

  1. Open your shell, clone the EnMAP-Box repository and pull large binary files:

    cd <my_repositories>
    git clone https://bitbucket.org/hu-geomatics/enmap-box.git
    cd enmap-box
    git lfs pull
    
  2. Add <my_repositories>/enmapbox/ as source location to your PyCharm project

    (instead of that in your QGIS active profile!)

  3. (Optional) install the QGIS source code repository.

    For the next step, but also if you like to discover the QGIS ++ code, it is recommended to install the QGIS repository as well. Some EnMAP-Box scripts can use data from the QGIS source code, e.g. to show images that otherwise are available on runtime in the QGIS Desktop application only.

    cd <my_repositories>
    git clone https://github.com/qgis/QGIS.git
    

    Now define a environmental variable QGIS_REPO in the IDE / PyCharm startup script (dev_setup_pycharm)

    OS Command
    Windows set QGIS_REPO=<my_repositories/QGIS>
    Linux /macOS DIR_REPO=<my_repositories/QGIS> export QGIS_REPO
  4. Run scripts/setup_repository.py to create Qt resource modules and perform a dependency check.

    The EnMAP-Box uses the Qt resource system (see https://doc.qt.io/qt-5/resources.html for details) to access icons. This step creates for each Qt resource file (filename.qrc) a corresponding python module (filename.py) that contains a binary encrypted description of resources (icons, images, etc.). During startup, these resources are loaded and can be accessed by resource path strings.

    The EnMAP-Box re-uses several icons provided by the QGIS desktop application. For example, the QGIS icon for raster layers is available at :/images/themes/default/mIconPolygonLayer.svg and can be visualized in the QGIS python shell as followed:

    icon = QIcon(r':/images/themes/default/mIconRaster.svg')
    label = QLabel()
    label.setPixmap(icon.pixmap(QSize(150,150)))
    label.show()
    
    ../_images/resources_qgis_icon_example.png

    The QGIS icon for raster (mIconRaster.svg)

    If we start and develop application from inside PyCharm, we usually don’t have access to QGIS desktop application resources. However, if you have downloaded the QGIS repository as described above, scripts/setup_repository.py will look for it, compile the resource files and write them into folder enmap-box/qgisresources.

Install / Update EnMAP-Box Testdata

The most-recent EnMAP-Box testdata is hosted on https://bitbucket.org/hu-geomatics/enmap-box-testdata/get/master.zip If missing or outdatet, it will be downloaded and installed after a user clicks on Project > Load Example Data. The downloaded data will be extracted into <root>/enmapboxtestdata, with <root> either being the EnMAP-Box repository folder or the QGIS plugin installation folder.

The testdata can be download explicitly:

import enmapbox.dependencycheck
enmapbox.dependencycheck.installTestData(ask=False, overwrite_existing=True)

Get Updates from other Repositories

The EnMAP-Box includes source-code from external projects. How these source contribute to the EnMAP-Box repository is described in scripts/updateexternals.py. In general, such remote locations are desribed by a RemoteInfo entry:

RemoteInfo.create(r'https://foobar.org/remoterepo.git',
                  prefixLocal=r'site-packages/remotepackage',
                  prefixRemote=r'remotepackage',
                  remoteBranch='master')

The combination of remote and local location, as well as the respective branch, is not accessible via the key remoterepo. Updating code from a remote location, i.e. copy changes from https://foobar.org/remoterepo.git/remotepackage to <enmapboxrepository>/site-packages/remotepackage, can be done with:

import make.updateexternals
make.updateexternals.updateRemotes('remoterepo')

It is possible to register multiple combinations of local and remote prefixes to the same key, what allows to copy different folders of a remote repository into different folders of the EnMAP-Box repository.