Image Layers Configuration#

Image layers are configured in an imagelayers.ini file. Each INI section defines one layer. The section name is used as the layer identifier.

There are three types of image sources supported by orthoseg:

  • WMS: a standard OGC Web Map Service.

  • WMTS: a standard OGC Web Map Tile Service.

  • File / GDAL: a local raster file, a directory containing raster files, or any source supported by the GDAL WMS driver (including e.g. XYZ tile services configured via an .xml file).

The layer type is determined automatically based on which keys are present in the section.

Note

An example imagelayers.ini is shipped with the sample projects so you can use it as a starting point.

WMS layers#

A section is treated as a WMS layer when wms_server_url is present.

wms_server_url#
Type:

str

Required:

yes

Default:

(none)

Base URL of the WMS endpoint, e.g. https://geo.api.vlaanderen.be/omw/wms?.

wms_layernames#
Type:

str

Required:

yes

Default:

(none)

Comma-separated list of WMS layer names to request.

wms_layerstyles#
Type:

str

Required:

no

Default:

default

Comma-separated list of styles, one per layer listed in wms_layernames.

wms_version#
Type:

str

Required:

no

Default:

1.3.0

WMS protocol version, e.g. 1.1.1 or 1.3.0.

wms_username#
Type:

str

Required:

no

Default:

(none)

Username for password-protected WMS services.

wms_password#
Type:

str

Required:

no

Default:

(none)

Password for password-protected WMS services.

Example

[BEFL-2019]
wms_server_url = https://geo.api.vlaanderen.be/omw/wms?
wms_layernames = OMWRGB19VL
wms_layerstyles = default
wms_version = 1.3.0
projection = epsg:31370
bbox = 174900, 176400, 175300, 176600
use_cache = ifavailable
nb_concurrent_calls = 1

WMTS layers#

A section is treated as a WMTS layer when wmts_server_url is present.

wmts_server_url#
Type:

str

Required:

yes

Default:

(none)

Base URL of the WMTS endpoint.

wmts_layernames#
Type:

str

Required:

yes

Default:

(none)

Comma-separated list of WMTS layer names.

wmts_layerstyles#
Type:

str

Required:

no

Default:

default

Comma-separated list of styles.

wmts_version#
Type:

str

Required:

no

Default:

1.0.0

WMTS protocol version.

wmts_tile_matrix_set#
Type:

str

Required:

yes

Default:

(none)

Tile matrix set identifier to use, e.g. BPL72VL.

Example

[BEFL-2019-WMTS]
wmts_server_url = https://geo.api.vlaanderen.be/omw/wmts?
wmts_layernames = omwrgb19vl
wmts_layerstyles = default
wmts_version = 1.0.0
wmts_tile_matrix_set = BPL72VL
projection = epsg:31370
bbox = 174900, 176400, 175300, 176600

File and GDAL layers#

A section is treated as a file-based layer when the path key is present.

The path can point to:

  • any georeference raster file, like a geotiff, a virtual raster (.vrt), or any other format that can be read by GDAL.

  • a GDAL WMS .xml configuration file. This can be used to connect to web sources supported by GDAL, such as XYZ/TMS tile services.

  • a directory containing georeferenced raster files that can be read by GDAL.

More details on these options are given below.

path#
Type:

str

Required:

yes

Default:

(none)

Path to a local raster layer.

This can be:

  • any georeference raster file, like a geotiff, a virtual raster (.vrt), or any other format that can be read by GDAL.

  • a GDAL WMS .xml configuration file. This can be used to connect to web sources supported by GDAL, such as XYZ/TMS tile services. See the GDAL WMS driver documentation for details on how to write the .xml file.

  • a directory containing georeferenced raster files that can be read by GDAL. In this case, the file_patterns key must be used to specify which files belong to the layer. Orthoseg will create a virtual raster, orthoseg.vrt, with all files that match the patterns specified in file_patterns and use it as the source for the layer. In addition, orthoseg will create a file called orthoseg.gpkg containing the footprints of all the individual files that match the patterns. This file will be used as the region of interest file (roi_filepath) for the layer.

file_patterns#
Type:

str

Required:

no

Default:

(none)

Comma-separated list of glob patterns to select files when path points to a directory.

Examples:

# This selects all .tif in the directory, excluding subdirectories
file_patterns = *.tif

# This selects all .tif and .jpg files in the directory and all its subdirectories
file_patterns = **/*.tif, **/*.jpg

Example: local raster file

[BEFL-TEST-s2-fields-2023]
path = ./fields/input_raster/BEFL-TEST-s2_2023-05-01_2023-07-01_B08-B04-B03_min_byte.tif
projection = epsg:32631
image_format = image/png
bbox = 174900, 176200, 175300, 176700
nb_concurrent_calls = 2

Example: XYZ tile service via GDAL WMS XML

[OSM-XYZ]
path = ./imagelayer_osm.xml
projection = epsg:3857
image_format = image/jpeg
bbox = 525500, 6603100, 525600, 6603200
nb_concurrent_calls = 4

See the GDAL WMS driver documentation for details on how to write the .xml file.

Example: directory of raster files

[RANDOM-RASTER-FILES]
path = ./random_raster_files/
file_patterns = **/*.tif, **/*.jpg
projection = epsg:32631
image_format = image/jpeg

Common keys#

The following keys can be used for all layer types.

use_cache#
Type:

str

Required:

no

Default:

yes

Whether to cache downloaded images on disk.

Possible values:

  • yes: always use the on-disk cache.

  • no: never cache; re-download every time.

  • ifavailable: use the cache when it exists, otherwise download.

projection#
Type:

str

Required:

yes

Default:

(none)

The CRS of the layer expressed as an EPSG code, e.g. epsg:31370.

switch_axes#
Type:

bool

Required:

no

Default:

(auto-detected)

Set to True if the x and y axes of bounding boxes must be swapped when querying the service. When left empty orthoseg determines this automatically from the projection.

layername#
Type:

str

Required:

no

Default:

(section name)

Override the layer name used internally. Defaults to the INI section name.

image_format#
Type:

str

Required:

no

Default:

image/jpeg

MIME type for the images that are requested and stored, e.g. image/jpeg, image/png.

bbox#
Type:

str

Required:

no

Default:

(none)

Bounding box of the region of interest (ROI) for the layer.

IT needs to be specified as four comma-separated coordinates in the layer’s projection: xmin, ymin, xmax, ymax.

When creating a prediction cache or running a prediction without cache, only tiles of the prediction grid that intersect the ROI are downloaded/predicted.

If your ROI is not a simple rectangle, you can use roi_filepath as an alternative, as this supports complex and/or multiple geometries. When both are specified, bbox takes precedence.

Example:

bbox = 174900, 176400, 175300, 176600
roi_filepath#
Type:

str

Required:

no

Default:

(none)

Path to a vector file that defines the region of interest (ROI) for the layer.

When creating a prediction cache or running a prediction without cache, only tiles of the prediction grid that intersect the ROI are downloaded/predicted.

When the ROI is a simple rectangle, you can use bbox as an alternative. When both are specified, bbox takes precedence.

Example:

roi_filepath = ./roi_files/my_layer_roi.gpkg
grid_xmin#
Type:

float

Required:

no

Default:

0

X-coordinate of the grid origin used when tiling the prediction cache.

grid_ymin#
Type:

float

Required:

no

Default:

0

Y-coordinate of the grid origin used when tiling the prediction cache.

nb_concurrent_calls#
Type:

int

Required:

no

Default:

1

Maximum number of parallel requests sent to the image source.

random_sleep#
Type:

float

Required:

no

Default:

(none)

When set, a random delay of up to this many seconds is used between consecutive requests to reduce server load.

image_pixels_ignore_border#
Type:

int

Required:

no

Default:

(none)

When the image source adds a watermark or artefact on the border, set this to the number of border pixels to strip. orthoseg requests an image that is this many pixels larger in all directions and then crops the border before saving.