A collection of examples how to use the EnMAP-Box.

View the Project on GitHub EnMAP-Box/enmapbox-training

Part II: Working with Spectral Libraries

This tutorial shows example on how the EnMAP-Box can be used to manage Spectral Libraries.


Most exercises of this tutorial use the EnMAP-Box example data, which can be opened by Project > Load Example Data.

Load example data

Some exercises use ASD Field Spectrometer binary files (*.asd), which are located in this repository in enmapbox-training/EARSeL2022/Data_Part_II. You may:

It is furthermore recommended to disable other QGIS plugins. An easy way doing so is to create a new QGIS profile “enmap-box tutorial” and install a fresh EnMAP-Box installation to.

Create new user profile

1. Collect profiles

  1. Open the EnMAP-Box and load the example data from Project > Load Example Data.

    If not done automatically, open a new map view and add the enmap_berlin.bsq and hires_berlin.bsq to it.

  2. Activate the Identify map tool and it’s option to collect Profiles Indentify map tool bar

  3. Click on a raster image pixel to open a new Spectral Library window and show the pixel profile.

    Example Pixel position and profile

  4. Profiles obtained from pixel positions are considered as current or temporary profile candidates. The last profile candidate will be replaced by a new one each time you click on a new pixel position.

  5. Click on Add profile(s) to keep candidate profiles in the spectral library. You can activate Add profiles automatically to keep new profiles automatically in the spectral library.

    Profiles and Profile Candidates

2. Profiles in Vector Layers?

The EnMAP-Box stores spectral profiles in vector layers. This way we can:

Open the Layer properties of the Spectral Library and have a look on its different properties:

Spectral Profiles are stored in binary (BLOB) or text (VARCHAR) fields of unlimited length. These field types may be used for other purposes as well. To use them explicitly for Spectral Profiles, the field editor widget type must be set to SpectralProfile.

Attriubte Form Properties

Because EnMAP-Box spectral libraries are vector layers, we can add them to a map canvas and display the positions of collected pixel profiles.

  1. Close the Layer properties
  2. Open a map canvas context menu
  3. Add “MySpeclib” as vector layer

Example Map canvas and spectral profiles

3. Profile sources and pixel locations

The Identify tool selects profiles from top-most raster layer by default. The Spectral Profile Sources panel allows to change this behaviour and to control:

  1. Change the profile source to enmap_berlin.bsq. This way you will always collect profiles from the same image. Profile Source Panel EnMAP

  2. In addition, open the map context menu Crosshair > Pixel grid and select the enmap_berlin.bsq.

    Crosshair Pixel Grid Menu

    Crosshair Pixel Grid Canvas

  3. Continue identifying pixel profiles by selecting locations using the hires_berlin.bsq as reference. As an alternative to the mouse you may use the short-cuts to change the pixel positions:

    Shortcut Action
    Arrow Move the map
    CTRL + Arrow Select next pixel in arrow direction
    CTRL + S Add the selected pixel profile candidate

It is possible to collect and compare profiles from different raster sources at the same time:

  1. Add a second profile source relation Green Plus icon
  2. Use hires_berlin.bsq as profile source and identify a profile for both images
  3. Collect new pixel profiles

    Profile Source Panel HighRes

In a similar way you can compare profiles from the same raster image but using a different sampling methods.

  1. Change the second relation to sample from enmap_berlin.bsq using a 3x3 Kernel mean profile.
  2. Collect new pixel profiles Profile Source Panel Kernel 3x3

4. The Spectral Library Window

The Spectral Library window offers (almost) the same tools like the standard QGIS attribute table. In addition, it provides views and features specifically to visualize and manage spectral profiles.

Spectral Library Widget Toolbar

4.1. Table View

The Table View can be used to modify profile attributes. Use it (in edit mode) to change the values in the name column.

Edit mode icon

You can add further metadata fields:

  1. Click the Add layer field icon button to open the Add Field dialog.
  2. Select a data type that allows to store profiles (e.g. text or binary fields)
  3. Checking Use to store Spectral Profiles is a fast way to create a new profile field, as it will set the editor widget automatically to Spectral Profile. Add field dialog

You can remove fields:

  1. Click on Remove fields icon to open the Remove Fields dialog.
  2. Select fields that you like to remove and press Ok

You can use the field calculator field calculator icon to modify values in the name field using an expression. Field Calculator example

QGIS uses a transactional model to tracks modifications in an internal buffer.

4.2. Form View

Form View icon The Form View uses the widgets that have been specified in the layer properties > Attribute Form to display attribute values. If can be used to display and (in edit mode) modify profiles in a JSON or table view.

Form View example

4.3. Profile Plot

The Profile Plot displays spectral profiles. Toggling the Profile View icon icon shows or hides the plot panel. This can be useful, for example to enlarge the attribute table and focus on attribute modifications.

You can adjust the extent of the visualized data range

You can export the entire plot scene or visible view box using the context menu > Export

Profile Plot export

4.4. Plot Settings

Plot Settings icon The Plot settings control the profile visualization. You can define multiple visualization groups that described how profiles from a specific field and with specific attributes should be visualized.

Vegetation profiles

  1. Open a second spectral library viewer that displays the library_berlin.gpkg Go to the Data Source panel, open the library_berlin.gpkg context menu and click Open Spectral Library Viewer
  2. Open the Plot Settings Plot Settings icon
  3. Rename the name of the default visualization group to vegetation (double-click into the name)
  4. Set a filter expression to show vegetation profiles only, e.g. "level_1" = 'vegetation' Profile filter
  5. Change the profile color to green
  6. Add a second visualization group Add Visualization Group for impervious surfaces, using a red color. Two visualization groups

5. Load and Save Spectral Libraries

Loading or Saving a spectral library means to load or save vector files.

Style and other layer specific information are not saved in the data source file, but the QGIS project or a QGIS specific sidecar .qml file. Open the layer properties > *Symbology > Style > Save Default to create or update the .qml file and ensure that the *Spectral Profile fields will be restored when re-opening the data set.

Save as Default context menu

6. Export profiles

The Export dialog allows you to export all or selected profiles as Geopackage (.gpkg), GeoJSON (.geoson) or ENVI Spectral Library (*.sli).

Export as ENVI files

The ENVI Spectral Library does not allow saving profiles with different spectral settings (number of bands, wavelength units, FWHM, …) in the same file. Therefore, you need to select one (out of multiple) profile fields. Profile with different spectral settings will be exported into different ENVI files.

7. Import profiles

Icon import profiles The Import Dialog is used to load profiles from none-vector files into an existing spectral library.

  1. Open a new “empty” spectral library window
  2. Activate the edit mode and remove the “profiles” field
  3. Open the import dialog
  4. Select “ASD Field Spectrometer”
  5. Select the ASD files in Data_Part_II\ASD

    The source files contain more attributes than we have defined in our spectral library. Add the Reference and the Spectrum field using the Copy missing source fields dialog.

  6. Define how source attributes, i.e. attributes of a single *.asd file are mapped to attributes of the spectral library. Press Ok to import the ASD file profiles.
  7. Add the library to the map canvas to visualize the GPS positions
  8. Finally, use the plot settings menu to give reference and spectrum profiles a different color

    Example imported ASD profiles

8. Spectral Profile JSON format

The EnMAP-Box stores the minimum data to plot a single profile in a JSON object. In its most simple way, this JSON object contains a single array “y” of length n, with n = number of spectral profile values:

    "y": [34, 23, 45, 63, 45]

In this case it can be assumed that the corresponding 'x' values are an increasing band index "x": [0, 1, 2, 3, 4]

The JSON object can describe the "x", the axis units and a vector of bad band values explicitly:

member content
y an array with n profile values
x an array with n profile value locations, e.g. the band wavelengths
yUnit string that describes the unit of y values, e.g. “Reflectance”
xUnit string that describes the x value unit, e.g. “nm” or “Nanometers”
bbl a “bad band list”, i.e. a vector with n bad-band multipliers. 0 = masked, > 0 = not masked

Other metadata to describe spectra profiles are stored in additional vector layer fields.

As JSON objet, a single hyperspectral EnMAP profile may therefore look like:


Note that conceptually profile objects can differ in its wavelength etc.

9. Create/Modify Profiles with spectralMath

As you already know, the Field Calculator can modify attribute values of all or selected features (aka rows).

We can use it to calculate spectral profiles as well:

  1. Open the Table View and activate the layer Edit mode
  2. Create a new Spectral Profile field based on a text field called “Reflectance” img.png
  3. Open the field calculator field calculator icon
  4. Use the spectralMath function to calculate reflectances from the ASD radiances measured from field spectra and its corresponding white reference.

    spectralMath("<profile field 1>", ..., "<profile field n>",
    '<python code>', '<output format>')
    spectralMath("Spectrum",  "Reference",
    'y = y1 / y2', 'text')

    The last function argument defines the output format. As our “Reflectance” field is based on text field, we need to specify the function output as “text” as well.


  5. Press “ok” to calculate the reflectance values.
  6. Hide the plot visualizations for “Reflectance” and “Spectrum” and auto-scale to the
    reflectance values within the range 0 to 1.


10. Spectral Processing


Spectral Processing

The Spectral Processing framework allows you to use raster processing algorithms to create new profiles. Field values of your spectral library will be converted into artificial one-line raster images. In principally, this can be done with most of the field types:

Field Type Raster Size
(band, height, n)
Spectral Profile nb, 1, n int / float
integer 1, 1, n int
float 1, 1, n float
text 1, 1, n int (classification)

These temporary raster images are input to standard QGIS processing algorithms or QGIS processing models. If they generate raster outputs, these outputs can be converted back into field values of the spectral library:

Raster Output Speclib Field Type
(>1, 1, n) int/float Spectral Profile
(1, 1, n) int int
(1, 1, n) float float

This allows you to use the same algorithms to modify spectral profiles as you may want to use to manipulate raster images. Furthermore, you can make use the QGIS model builder to create (potentially very large and complex) models and use them for both, spectral libraries and raster image processing.


  1. Open the library_berlin.gpkg in a Spectral Library Viewer
  2. Activate the layer Edit mode.
  3. Open the Spectral Processing Dialog
    • select Spectral Resampling to Landsat8 (enmapbox:SpectralResamplingToLandsat89Oli) as processing algorithm
    • select profiles (177 bands, Micrometer) as input. These profiles will be converted into a single line raster image with 177 bands.
    • define the field where to write outputs to. Either select an existing field or type the name of a new one.

    Spectral Processing Dialog

  4. Press Ok to start the processing.

    (Bug notice: run this step twice)

  5. Close the Spectral Processing Dialog, open the plot settings and visualize the resampled Landsat profiles.


Caveats & Limitations


EnMAP-Box Source Code: https://bitbucket.org/hu-geomatics/enmap-box

EnMAP-Box Documentation: https://enmap-box.readthedocs.io

QGIS User Guide: https://docs.qgis.org/latest/en/docs/user_manual/index.html