API Reference

PyEPR provides Python bindings for the ENVISAT Product Reader C API (EPR API) for reading satellite data from ENVISAT ESA (European Space Agency) mission.

PyEPR is fully object oriented and, as well as the EPR API for C, supports ENVISAT MERIS, AATSR Level 1B and Level 2 and also ASAR data products. It provides access to the data either on a geophysical (decoded, ready-to-use pixel samples) or on a raw data layer. The raw data access makes it possible to read any data field contained in a product file.

Classes

Product

class epr.Product

ENVISAT product.

The Product class provides methods and properties to get information about an ENVISAT product file.

See also

open()

Attributes

file_path

The file’s path including the file name.

mode

String that specifies the mode in which the file is opened.

Possible values: rb for read-only mode, rb+ for read-write mode.

id_string

The product identifier string obtained from the MPH parameter ‘PRODUCT’.

The first 10 characters of this string identify the product type, e.g. “MER_1P__FR” for a MERIS Level 1b full resolution product. The rest of the string decodes product instance properties.

meris_iodd_version

For MERIS L1b and RR and FR to provide backward compatibility.

tot_size

The total size in bytes of the product file.

Methods

get_band(name)

Gets the band corresponding to the specified name.

Parameters

name – the name of the band

Returns

the requested Band instance, or raises a EPRValueError if not found

get_band_at(index)

Gets the Band at the specified position within the product.

Parameters

index – the index identifying the position of the Band, starting with 0, must not be negative

Returns

the requested Band instance, or raises a EPRValueError if not found

get_dataset(name)

Gets the Dataset corresponding to the specified dataset name.

Parameters

name – the Dataset name

Returns

the requested Dataset instance

get_dataset_at(index)

Gets the Dataset at the specified position within the Product.

Parameters

index – the index identifying the position of the Dataset, starting with 0, must not be negative

Returns

the requested Dataset

get_dsd_at(index)

Gets the DSD at the specified position.

Gets the DSD (Dataset descriptor) at the specified position within the Product.

Parameters

index – the index identifying the position of the DSD, starting with 0, must not be negative

Returns

the requested DSD instance

get_num_bands()

Gets the number of all Bands contained in a Product.

get_num_datasets()

Gets the number of all Datasets contained in a Product.

get_num_dsds()

Gets the number of all DSDs (Dataset descriptors) contained in the Product.

get_scene_height()

Gets the Product scene height in pixels.

get_scene_width()

Gets the Product scene width in pixels.

get_mph()

The Record representing the main product header (MPH).

get_sph()

The Record representing the specific product header (SPH).

read_bitmask_raster(bm_expr, xoffset, yoffset, raster)

Calculates a bit-mask raster.

Calculates a bit-mask, composed of flags of the given Product and combined as described in the given bit-mask expression, for the a certain dimension and sub-sampling as defined in the given raster.

Parameters
  • bm_expr – a string holding the logical expression for the definition of the bit-mask. In a bit-mask expression, any number of the flag-names (found in the DDDB) can be composed with “(”, “)”, “NOT”, “AND”, “OR”. Valid bit-mask expression are for example flags.LAND OR flags.CLOUD or NOT flags.WATER AND flags.TURBID_S

  • xoffset – across-track co-ordinate in pixel co-ordinates (zero-based) of the upper right corner of the source-region

  • yoffset – along-track co-ordinate in pixel co-ordinates (zero-based) of the upper right corner of the source-region

  • raster – the raster for the bit-mask. The data type of the raster must be either E_TID_UCHAR or E_TID_CHAR

Returns

zero for success, an error code otherwise

close()

Closes the Product product and free the underlying file descriptor.

This method has no effect if the Product is already closed. Once the Product is closed, any operation on it will raise a ValueError.

As a convenience, it is allowed to call this method more than once; only the first call, however, will have an effect.

flush()

Flush the file stream.

High level interface methods

Note

the following methods are part of the high level Python API and do not have any corresponding function in the C API.

closed

True if the Product is closed.

get_dataset_names()

Return the list of names of the Datasets in the Product.

get_band_names()

Return the list of names of the Bands in the Product.

datasets()

Return the list of Datasets in the Product.

bands()

Return the list of Bands in the Product.

Special methods

The Product class provides a custom implementation of the following special methods:

  • __repr__

  • __str__

  • __enter__

  • __exit__

Dataset

class epr.Dataset

ENVISAT dataset.

The Dataset class contains information about a dataset within an ENVISAT product file which has been opened with the open() function.

A new Dataset instance can be obtained with the Product.get_dataset() or Product.get_dataset_at() methods.

Attributes

description

A short description of the Band contents.

product

The Product instance to which this Dataset belongs to.

Methods

get_name()

Gets the name of the Dataset.

get_dsd()

Gets the Dataset descriptor (DSD).

get_dsd_name()

Gets the name of the DSD (Dataset descriptor).

get_num_records()

Gets the number of Records of the Dataset.

create_record()

Creates a new Record.

Creates a new, empty Record with a structure compatible with the Dataset. Such a Record is typically used in subsequent calls to Dataset.read_record().

Returns

the new Record instance

read_record(index[, record])

Reads specified Record of the Dataset.

The Record is identified through the given zero-based Record index. In order to reduce memory reallocation, a Record (pre-)created by the method Dataset.create_record() can be passed to this method. Data is then read into this given Record.

If no Record (None) is given, the method initiates a new one.

In both cases, the Record in which the data is read into will be returned.

Parameters
  • index – the zero-based Record index (default: 0)

  • record – a pre-created Record to reduce memory reallocation, can be None (default) to let the function allocate a new Record

Returns

the record in which the data has been read into or raises an exception (EPRValueError) if an error occurred

Changed in version 0.9: The index parameter now defaults to zero.

High level interface methods

Note

the following methods are part of the high level Python API and do not have any corresponding function in the C API.

records()

Return the list of Records contained in the Dataset.

Special methods

The Dataset class provides a custom implementation of the following special methods:

  • __repr__

  • __str__

  • __iter__

Record

class epr.Record

Represents a record read from an ENVISAT dataset.

A record is composed of multiple fields.

See also

Field

Attributes

dataset_name

The name of the Dataset to which this Record belongs to.

New in version 0.9.

tot_size

The total size in bytes of the Record.

It includes all data elements of all Fields of a Record in a Product file.

tot_size is a derived variable, it is computed at run-time and not stored in the DSD-DB.

New in version 0.9.

index

Index of the Record within the Dataset.

It is None for empty Records (created with Dataset.create_record() but still not read) and for MPH (see Product.get_mph()) and SPH (see Product.get_sph()) Records.

New in version 0.9.

Methods

get_field(name)

Gets a Field specified by name.

The Field is here identified through the given name. It contains the Field info and all corresponding values.

Parameters

name – the the name of required Field

Returns

the specified Field or raises an exception (EPRValueError) if an error occurred

get_field_at(index)

Gets a Field at the specified position within the Record.

Parameters

index – the zero-based index (position within Record) of the Field

Returns

the Field or raises and exception (EPRValueError) if an error occurred

get_num_fields()

Gets the number of Fields contained in the Record.

print_([ostream])

Write the Record to specified file (default: sys.stdout).

This method writes formatted contents of the Record to specified ostream text file or (default) the ASCII output is be printed to standard output (sys.stdout).

Parameters

ostream – the (opened) output file object

Note

the ostream parameter have to be a real file not a generic stream object like StringIO.StringIO instances.

print_element(field_index, element_index[, ostream])

Write the specified field element to file (default: sys.stdout).

This method writes formatted contents of the specified Field element to the ostream text file or (default) the ASCII output will be printed to standard output (sys.stdout).

Parameters
  • field_index – the index of Field in the Record

  • element_index – the index of element in the specified Field

  • ostream – the (opened) output file object

Note

the ostream parameter have to be a real file not a generic stream object like StringIO.StringIO instances.

get_offset()

Record offset in bytes within the Dataset.

New in version 0.9.

High level interface methods

Note

the following methods are part of the high level Python API and do not have any corresponding function in the C API.

get_field_names()

Return the list of names of the Fields in the Record.

fields()

Return the list of Fields contained in the Record.

Special methods

The Record class provides a custom implementation of the following special methods:

  • __repr__

  • __str__

  • __iter__

Field

class epr.Field

Represents a field within a record.

A Field is composed of one or more data elements of one of the types defined in the internal field_info structure.

See also

Record

Attributes

tot_size

The total size in bytes of all data elements of a Field.

tot_size is a derived variable, it is computed at run-time and not stored in the DSD-DB.

New in version 0.9.

get_description()

Gets the description of the Field.

get_name()

Gets the name of the Field.

get_num_elems()

Gets the number of elements of the Field.

get_type()

Gets the type of the Field.

get_unit()

Gets the unit of the Field.

get_elem([index])

Field single element access.

This function is for getting the elements of a Field.

Parameters

index – the zero-based index of element to be returned, must not be negative. Default: 0.

Returns

the typed value from given Field

get_elems()

Field array element access.

This function is for getting an array of field elements of the Field.

Returns

the data array (numpy.ndarray) having the type of the Field

Changed in version 0.9: the returned numpy.ndarray shares the data buffer with the C Field structure so any change in its contents is also reflected to the Filed object

set_elem(elem[, index])

Set Field array element.

This function is for setting an array of field element of the Field.

Parameters
  • elem – value of the element to set

  • index – the zero-based index of element to be set, must not be negative. Default: 0.

Note

this method does not have any corresponding function in the C API.

New in version 0.9.

set_elems(elems)

Set Field array elements.

This function is for setting an array of Field elements of the Field.

Parameters

elems – np.ndarray of elements to set

Note

this method does not have any corresponding function in the C API.

New in version 0.9.

print_([ostream])

Write the Field to specified file (default: sys.stdout).

This method writes formatted contents of the Field to specified ostream text file or (default) the ASCII output is be printed to standard output (sys.stdout).

Parameters

ostream – the (opened) output file object

Note

the ostream parameter have to be a real file not a generic stream object like StringIO.StringIO instances

get_offset()

Field offset in bytes within the Record.

New in version 0.9.

Special methods

The Field class provides a custom implementation of the following special methods:

  • __repr__

  • __str__

  • __eq__

  • __ne__

  • __len__ 1

Footnotes

1

if the field is a E_TID_STRING field then the __len__() method returns the string length, otherwise the number of elements of the field is returned (same as Field.get_num_elems())

DSD

class epr.DSD

Dataset descriptor.

The DSD class contains information about the properties of a Dataset and its location within an ENVISAT Product file.

Attributes

ds_name

The Dataset name.

ds_offset

The offset of Dataset in the Product file.

ds_size

The size of Dataset in the Product file.

ds_type

The Dataset type descriptor.

dsr_size

The size of dataset record for the given Dataset name.

filename

The filename in the DDDB with the description of this Dataset.

index

The index of this DSD (zero-based).

num_dsr

The number of dataset records for the given Dataset name.

Special methods

The DSD class provides a custom implementation of the following special methods:

  • __repr__

  • __eq__

  • __ne__

Band

class epr.Band

The band of an ENVISAT Product.

The Band class contains information about a band within an ENVISAT Product file which has been opened with the open() function.

A new Band instance can be obtained with the Product.get_band() method.

Attributes

bm_expr

A bit-mask expression used to filter valid pixels.

All others are set to zero.

data_type

The data type of the Band pixels.

Possible values are:

  • * –> the datatype remains unchanged.

  • uint8_t –> 8-bit unsigned integer

  • uint32_t –> 32-bit unsigned integer

  • Float –> 32-bit IEEE floating point

description

A short description of the Band contents.

lines_mirrored

Mirrored lines flag.

If true (=1) lines will be mirrored (flipped) after read into a raster in order to ensure a pixel ordering in raster X direction from WEST to EAST.

product

The Product instance to which this Band belongs to.

sample_model

The sample model operation.

The sample model operation applied to the source Dataset for getting the correct samples from the MDS (for example MERIS L2).

Possible values are:

  • * –> no operation (direct copy)

  • 1OF2 –> first byte of 2-byte interleaved MDS

  • 2OF2 –> second byte of 2-byte interleaved MDS

  • 0123 –> combine 3-bytes interleaved to 4-byte integer

scaling_factor

The scaling factor.

Possible values are:

  • * –> no factor provided (implies scaling_method=*)

  • const –> a floating point constant

  • GADS.field[.field2] –> value is provided in global annotation Dataset with name GADS in Field field. Optionally a second element index for multiple-element fields can be given too

scaling_method

The scaling method which must be applied to the raw source data in order to get the ‘real’ pixel values in geo-physical units.

Possible values are:

  • * –> no scaling applied

  • Linear_Scale –> linear scaling applied:

    y = offset + scale * x
    
  • Log_Scale –> logarithmic scaling applied:

    y = log10(offset + scale * x)
    
scaling_offset

Possible values are:

  • * –> no offset provided (implies scaling_method=*)

  • const –> a floating point constant

  • GADS.field[.field2]` --> value is provided in global annotation :class:`Dataset` with name ``GADS in Field field. Optionally a second element index for multiple-element fields can be given too

spectr_band_index

The (zero-based) spectral Band index.

-1 if this is not a spectral Band.

unit

The geophysical unit for the Band pixel values.

dataset

The source Dataset.

The source Dataset containing the raw data used to create the Band pixel values.

New in version 0.9.

Methods

get_name()

Gets the name of the Band.

create_compatible_raster([src_width, src_height, xstep, ystep])

Creates a Raster which is compatible with the data type of the Band.

The created Raster is used to read the data in it (see Band.read_raster()).

The Raster is defined on the grid of the Product, from which the data are read. Spatial subsets and under-sampling are possible) through the parameter of the method.

A Raster is an object that allows direct access to data of a certain portion of the ENVISAT Product that are read into the it. Such a portion is called the source. The complete ENVISAT Product can be much greater than the source. One can move the Raster over the complete ENVISAT Product and read in turn different parts (always of the size of the source) of it into the Raster. The source is specified by the parameters height and width.

A typical example is a processing in blocks. Lets say, a block has 64x32 pixel. Then, my source has a width of 64 pixel and a height of 32 pixel.

Another example is a processing of complete image lines. Then, my source has a widths of the complete product (for example 1121 for a MERIS RR product), and a height of 1). One can loop over all blocks read into the Raster and process it.

In addition, it is possible to defined a sub-sampling step for a Raster. This means, that the source is not read 1:1 into the Raster, but that only every 2nd or 3rd pixel is read. This step can be set differently for the across track (source_step_x) and along track (source_step_y) directions.

Parameters
  • src_width – the width (across track dimension) of the source to be read into the Raster. Default: scene width (see Product.get_scene_width)

  • src_height – the height (along track dimension) of the source to be read into the Raster. Default: scene height (see Product.get_scene_height)

  • xstep – the sub-sampling step across track of the source when reading into the Raster. Default: 1.

  • ystep – the sub-sampling step along track of the source when reading into the Raster. Default: 1.

Returns

the new Raster instance or raises an exception (EPRValueError) if an error occurred

Note

src_width and src_height are the dimantion of the of the source area. If one specifies a step parameter the resulting Raster will have a size that is smaller that the specifies source size:

raster_size = src_size // step
read_raster([xoffset, yoffset, raster])

Reads (geo-)physical values of the Band of the specified source-region.

The source-region is a defined part of the whole ENVISAT Product image, which shall be read into a Raster. In this routine the co-ordinates are specified, where the source-region to be read starts. The dimension of the region and the sub-sampling are attributes of the Raster into which the data are read.

Parameters
  • xoffset – across-track source co-ordinate in pixel co-ordinates (zero-based) of the upper right corner of the source-region. Default 0.

  • yoffset – along-track source co-ordinate in pixel co-ordinates (zero-based) of the upper right corner of the source-region. Default 0.

  • rasterRaster instance set with appropriate parameters to read into. If not provided a new Raster is instantiated

Returns

the Raster instance in which data are read

This method raises an instance of the appropriate EPRError sub-class if case of errors

High level interface methods

Note

the following methods are part of the high level Python API and do not have any corresponding function in the C API.

read_as_array([width, height, xoffset, yoffset, xstep, ystep])

Reads the specified source region as an numpy.ndarray.

The source-region is a defined part of the whole ENVISAT Product image, which shall be read into a Raster. In this routine the co-ordinates are specified, where the source-region to be read starts. The dimension of the region and the sub-sampling are attributes of the Raster into which the data are read.

Parameters
  • src_width – the width (across track dimension) of the source to be read into the Raster. If not provided reads as much as possible

  • src_height – the height (along track dimension) of the source to be read into the Raster, If not provided reads as much as possible

  • xoffset – across-track source co-ordinate in pixel co-ordinates (zero-based) of the upper right corner of the source-region. Default 0.

  • yoffset – along-track source co-ordinate in pixel co-ordinates (zero-based) of the upper right corner of the source-region. Default 0.

  • xstep – the sub-sampling step across track of the source when reading into the Raster. Default: 1

  • ystep – the sub-sampling step along track of the source when reading into the Raster. Default: 1

Returns

the numpy.ndarray instance in which data are read

This method raises an instance of the appropriate EPRError sub-class if case of errors

Special methods

The Band class provides a custom implementation of the following special methods:

  • __repr__

Raster

class epr.Raster

Represents a raster in which data will be stored.

All ‘size’ parameter are in PIXEL.

Attributes

data_type

The data type of the Band pixels.

All E_TID_* types are possible.

source_height

The height of the source.

source_width

The width of the source.

source_step_x

The sub-sampling for the across-track direction in pixel.

source_step_y

The sub-sampling for the along-track direction in pixel.

High level interface attributes

Note

the following attributess are part of the high level Python API and do not have a counterpart in the C API.

data

Raster data exposed as numpy.ndarray object.

Note

this property shares the data buffer with the Raster object so any change in its contents is also reflected to the Raster object

Note

the Raster objects do not have a Field named data in the corresponding C structure. The EPR_SRaster C structure have a Field named buffer that is a raw pointer to the data buffer and it is not exposed as such in the Python API.

Methods

get_pixel(x, y)

Single pixel access.

This function is for getting the values of the elements of a Raster (i.e. pixel)

Parameters
  • x – the (zero-based) X coordinate of the pixel

  • y – the (zero-based) Y coordinate of the pixel

Returns

the typed value at the given co-ordinate

get_elem_size()

The size in byte of a single element (sample) of this Raster buffer.

get_height()

Gets the Raster height in pixels.

get_width()

Gets the Raster width in pixels.

Special methods

The Raster class provides a custom implementation of the following special methods:

  • __repr__

EPRTime

class epr.EPRTime

Convenience class for time data exchange.

EPRTime is a collections.namedtuple with the following fields:

days
seconds
microseconds

Functions

epr.open(filename, mode='rb')

Open the ENVISAT product.

Opens the ENVISAT Product file with the given file path, reads MPH, SPH and all DSDs, organized the table with parameter of line length and tie points number.

Parameters
  • product_file_path – the path to the ENVISAT Product file

  • mode – string that specifies the mode in which the file is opened. Allowed values: rb for read-only mode, rb+ for read-write mode. Default: mode=`rb`.

Returns

the Product instance representing the specified product. An exception (exceptions.ValueError) is raised if the file could not be opened.

The Product class supports context management so the recommended way to ensure that a product is actually closed as soon as a task is completed is to use the with statement:

with open('ASA_IMP_1PNUPA20060202_ ... _3110.N1') as product:
    dataset = product.get_dataset('MAIN_PROCESSING_PARAMS_ADS')
    record = dataset.read_record(0)
    print(record)
epr.data_type_id_to_str(type_id)

Gets the ‘C’ data type string for the given data type.

epr.get_data_type_size(type_id)

Gets the size in bytes for an element of the given data type.

epr.get_numpy_dtype(type_id)

Return the numpy data-type specified EPR type ID.

New in version 0.9.

epr.get_sample_model_name(model)

Return the name of the specified sample model.

epr.get_scaling_method_name(method)

Return the name of the specified scaling method.

epr.create_raster(data_type, src_width, src_height[, xstep, ystep])

Creates a Raster of the specified data type.

This function can be used to create any type of raster, e.g. for later use as a bit-mask.

Parameters
  • data_type

    the type of the data to stored in the Raster, must be one of E_TID_*.

  • src_width – the width (across track dimension) of the source to be read into the Raster. See description of Band.create_compatible_raster()

  • src_height – the height (along track dimension) of the source to be read into the Raster. See description of Band.create_compatible_raster()

  • xstep – the sub-sampling step across track of the source when reading into the Raster. Default: 1.

  • ystep – the sub-sampling step along track of the source when reading into the Raster. Default: 1.

Returns

the new Raster instance

See also

description of Band.create_compatible_raster()

epr.create_bitmask_raster(src_width, src_height[, xstep, ystep])

Creates a Raster to be used for reading bitmasks.

The Raster returned always is of type byte.

Parameters
  • src_width – the width (across track dimension) of the source to be read into the Raster

  • src_height – the height (along track dimension) of the source to be read into the Raster

  • xstep – the sub-sampling step across track of the source when reading into the Raster. Default: 1.

  • ystep – the sub-sampling step along track of the source when reading into the Raster. Default: 1.

Returns

the new Raster instance or raises an exception (EPRValueError) if an error occurred

See also

the description of Band.create_compatible_raster()

Exceptions

EPRError

exception epr.EPRError

EPR API error.

code

EPR API error code.

__init__([message[, code, *args, **kwargs]])

Initializer.

Parameters
  • message – error message

  • code – EPR error code

EPRValueError

exception epr.EPRValueError

Inherits both EPRError and standard exceptions.ValueError.

Data

epr.__version__

Version string of PyEPR.

epr.EPR_C_API_VERSION

Version string of the wrapped EPR API C library.

Data type identifiers

epr.E_TID_UNKNOWN
epr.E_TID_UCHAR
epr.E_TID_CHAR
epr.E_TID_USHORT
epr.E_TID_SHORT
epr.E_TID_UINT
epr.E_TID_INT
epr.E_TID_FLOAT
epr.E_TID_DOUBLE
epr.E_TID_STRING
epr.E_TID_SPARE
epr.E_TID_TIME

Sample Models

epr.E_SMOD_1OF1
epr.E_SMOD_1OF2
epr.E_SMOD_2OF2
epr.E_SMOD_3TOI
epr.E_SMOD_2TOF

Scaling Methods

epr.E_SMID_NON

No scaling.

epr.E_SMID_LIN

Linear pixel scaling.

epr.E_SMID_LOG

Logarithmic pixel scaling.