Plugins¶
xcube’s functionality can be extended by plugins. A plugin contributes extensions to specific extension points defined by xcube. Plugins are detected and dynamically loaded, once the available extensions need to be inquired.
Installing Plugins¶
Plugins are installed by simply installing the plugin’s package into xcube’s Python environment.
In order to be detected by xcube, an plugin package’s name must either start with xcube_
or the plugin package’s setup.py
file must specify an entry point in the group
xcube_plugins
. Details are provided below in section plugin_development.
Available Plugins¶
SENTINEL Hub¶
The xcube_sh plugin adds support for the SENTINEL Hub Cloud API. It extends xcube by a new Python API
function xcube_sh.cube.open_cube
to create data cubes from SENTINEL Hub on-the-fly. It also
adds a new CLI command xcube sh gen
to generate and write data cubes created from SENTINEL Hub
into the file system.
ESA CCI Open Data Portal¶
The xcube_cci plugin provides support for the ESA CCI Open Data Portal.
Copernicus Climate Data Store¶
The xcube_cds plugin provides support for the Copernicus Climate Data Store.
Cube Generation¶
xcube’s GitHub organisation currently hosts a few plugins that add new input processor extensions (see below) to xcube’s data cube generation tool xcube gen. They are very specific but are a good starting point for developing your own input processors:
xcube_gen_bc - adds new input processors for specific Ocean Colour Earth Observation products derived from the Sentinel-3 OLCI measurements.
xcube_gen_rbins - adds new input processors for specific Ocean Colour Earth Observation products derived from the SEVIRI measurements.
xcube_gen_vito - adds new input processors for specific Ocean Colour Earth Observation products derived from the Sentinel-2 MSI measurements.
Plugin Development¶
Plugin Definition¶
An xcube plugin is a Python package that is installed in xcube’s Python environment. xcube can detect plugins either
by naming convention (more simple);
by entry point (more flexible).
By naming convention: Any Python package named xcube_<name>
that defines a plugin initializer function
named init_plugin
either defined in xcube_<name>/plugin.py
(preferred) or xcube_<name>/__init__.py
is an xcube plugin.
By entry point: Any Python package installed using Setuptools that
defines a non-empty entry point group xcube_plugins
is an xcube plugin. An entry point in the
xcube_plugins
group has the format <name> = <fully-qualified-module-path>:<init-func-name>
,
and therefore specifies where plugin initializer function named <init-func-name>
is found.
As an example, refer to the xcube standard plugin definitions in xcube’s
setup.py file.
For more information on Setuptools entry points refer to section Creating and discovering plugins in the Python Packing User Guide and Dynamic Discovery of Services and Plugins in the Setuptools documentation.
Initializer Function¶
xcube plugins are initialized using a dedicated function that has a single extension registry argument
of type xcube.util.extension.ExtensionRegistry
, that is used by plugins’s to register their extensions
to xcube. By convention, this function is called init_plugin
, however, when using entry points,
it can have any name. As an example, here is the initializer function of the SENTINEL Hub plugin
xcube_sh/plugin.py
::
from xcube.constants import EXTENSION_POINT_CLI_COMMANDS
from xcube.util import extension
def init_plugin(ext_registry: extension.ExtensionRegistry):
"""xcube SentinelHub extensions"""
ext_registry.add_extension(loader=extension.import_component('xcube_sh.cli:cli'),
point=EXTENSION_POINT_CLI_COMMANDS,
name='sh_cli')
Extension Points and Extensions¶
When a plugin is loaded, it adds its extensions to predefined extension points defined by xcube. xcube defines the following extension points:
xcube.core.gen.iproc
: input processor extensionsxcube.core.dsio
: dataset I/O extensionsxcube.cli
: Command-line interface (CLI) extensions
An extension is added to the extension registry’s add_extension
method. The extension registry is
passed to the plugin initializer function as its only argument.
Input Processor Extensions¶
Input processors are used the xcube gen
CLI command and gen_cube
API function.
An input processor is responsible for processing individual time slices after they have been
opened from their sources and before they are appended to or inserted into the data cube
to be generated. New input processors are usually programmed to support the characteristics
of specific xcube gen
inputs, mostly specific Earth Observation data products.
By default, xcube uses a standard input processor named default
that expects inputs
to be individual NetCDF files that conform to the CF-convention. Every file is expected
to contain a single spatial image with dimensions lat
and lon
and the time
is expected to be given as global attributes.
If your input files do not conform with the default
expectations, you can extend xcube
and write your own input processor. An input processor is an implementation of the
xcube.core.gen.iproc.InputProcessor
or xcube.core.gen.iproc.XYInputProcessor
class.
As an example take a look at the implementation of the default
input processor
xcube.core.gen.iproc.DefaultInputProcessor or the various input processor plugins mentioned above.
The extension point identifier is defined by the constant xcube.constants.EXTENSION_POINT_INPUT_PROCESSORS
.
Dataset I/O Extensions¶
More coming soon…
The extension point identifier is defined by the constant xcube.constants.EXTENSION_POINT_DATASET_IOS
.
CLI Extensions¶
CLI extensions enhance the xcube
command-line tool by new sub-commands.
The xcube CLI is implemented using the click library, therefore the extension
components must be click commands or command groups.
The extension point identifier is defined by the constant xcube.constants.EXTENSION_POINT_CLI_COMMANDS
.