Getting Started

This section demonstrate the basic usage of PyHDRL, i.e. it will show a number of examples of the Python API of the different HDRL algorithms. For comparison, the examples may also show the equivalent code using the HDRL C API. This will help developers familiar with the C API to quickly adopt the Python API in their Python scripts.

PyHDRL is a standard Python module, which is imported in your Python scripts as hdrl:

import hdrl

The module hdrl has two submodules: hdrl.core and hdrl.func. The high level HDRL algorithms are provided by the submodule hdrl.func. The supporting data types for these algorithms are implemented in the hdrl.core submodule. Strictly speaking there is also A third submodule hdrl.debug. However, this submodule is not intended for regular development. It is meant to be used internally to validate type conversions between PyCPL and PyHDRL. Developers can simply ignore hdrl.debug.

The complete description of the different PyHDRL classes and functions is available in the API Reference.

PyHDRL Interface Design

The PyHDRL module is constructed in a near identical fashion to PyCPL and shares many of its design influences. For example, to provide the developers with a more pythonic interface to HDRL, it was decided to not provide a Parameter class as an interface to hdrl_parameter objects. Instead, access to HDRL functionalities are provided via classes whose constructors are instantiated with the parameters required by the ubiquitous _parameter_create functions. Member functions of these classes then allow most functionalities to be executed, with the remainder reserved for static functions.

This is demonstrated in the following equivalent HDRL and PyHDRL pseudocode examples from the tests for hdrl.func.Flat:

// HDRL pseudocode
hdrl_image * master = NULL;
cpl_image * contrib_map = NULL;
hdrl_parameter * collapse_params = hdrl_collapse_mean_parameter_create();
hdrl_parameter *flat_params = hdrl_flat_parameter_create(filter_size_x, filter_size_y, HDRL_FLAT_FREQ_LOW);
hdrl_flat_compute(imglist, NULL, collapse_params, flat_params, &master, &contrib_map);

# PyHDRL pseudocode
stat_mask = None
collapse = hdrl.func.Collapse.Mean()
flat = hdrl.func.Flat(filter_size_x, filter_size_y, hdrl.func.Flat.Mode.FreqLow)
results = flat.compute(imglist, collapse, stat_mask)
# results is a namedtuple (FlatResult) containing:
#     the master image (hdrl.core.Image) - accessible via results.master
#     the contribution map (cpl.core.Image) - accessible via results.contrib_map

As seen in the PyHDRL example above, named tuples are used for the return values of several functions, e.g. returned HDRL values and in functions that return multiple images.

To be continued…