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.
ENVISAT product
The Product class provides methods and properties to get information about an ENVISAT product file.
See also
Attributes
The file’s path including the file name
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.
For MERIS L1b and RR and FR to provide backward compatibility
The total size in bytes of the product file
Methods
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 |
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 |
Gets the dataset corresponding to the specified dataset name
Parameters: | name – the dataset name |
---|---|
Returns: | the requested Dataset instance |
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 |
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 |
Gets the number of all bands contained in a product
Gets the number of all datasets contained in a product
Gets the product’s scene height in pixels
Gets the product’s scene width in pixels
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: |
|
---|---|
Returns: | zero for success, an error code otherwise |
See also
High level interface methods
Note
the following methods are part of the high level Python API and do not have any correspondent function in the C API.
Return the list of names of the datasets in the product
Return the list of names of the bands in the product
Return the list of dataset in the product
Return the list of bands in the product
Special methods
The Product class provides a custom implementation of the following special methods:
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
A short description of the band’s contents
Methods
Gets the name of the dataset
Gets the dataset descriptor (DSD)
Gets the name of the DSD (dataset descriptor)
Gets the number of records of the dataset
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 |
---|
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: |
|
---|---|
Returns: | the record in which the data has been read into or raises an exception (EPRValueError) if an error occurred |
High level interface methods
Note
the following methods are part of the high level Python API and do not have any correspondent function in the C API.
Return the list of records contained in the dataset
Special methods
The Dataset class provides a custom implementation of the following special methods:
Represents a record read from an ENVISAT dataset
A record is composed of multiple fields.
See also
Methods
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 |
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 |
Gets the number of fields contained in the record
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
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: |
|
---|
Note
the ostream parameter have to be a real file not a generic stream object like StringIO.StringIO instances
High level interface methods
Note
the following methods are part of the high level Python API and do not have any correspondent function in the C API.
Return the list of names of the fields in the product
Return the list of fields contained in the record
Special methods
The Record class provides a custom implementation of the following special methods:
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
Gets the description of the field
Gets the name of the field
Gets the number of elements of the field
Gets the type of the field
Gets the unit of the field
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 |
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 |
---|
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
Special methods
The Field class provides a custom implementation of the following special methods:
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()) |
Dataset descriptor
The DSD class contains information about the properties of a dataset and its location within an ENVISAT product file
Attributes
The dataset name
The offset of dataset-information the product file
The size of dataset-information in dataset product file
The dataset type descriptor
The size of dataset record for the given dataset name
The filename in the DDDB with the description of this dataset
The index of this DSD (zero-based)
The number of dataset records for the given dataset name
Special methods
The DSD class provides a custom implementation of the following special methods:
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
A bit-mask expression used to filter valid pixels
All others are set to zero
The data type of the band’s pixels
Possible values are:
A short description of the band’s contents
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.
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:
The scaling factor
Possible values are:
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)
Possible values are:
The (zero-based) spectral band index
-1 if this is not a spectral band
The geophysical unit for the band’s pixel values
Methods
Gets the name of the band
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: |
|
---|---|
Returns: | the new raster instance or raises an exception (EPRValueError) if an error occurred |
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: |
|
---|---|
Returns: | the Raster instance in which data are read |
This method raises an instance of the appropriate EPRError sub-class if case of errors
See also
High level interface methods
Note
the following methods are part of the high level Python API and do not have any correspondent function in the C API.
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: |
|
---|---|
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
See also
Band.create_compatible_raster(), create_raster() and Band.read_raster()
Special methods
The Band class provides a custom implementation of the following special methods:
Represents a raster in which data will be stored
All ‘size’ parameter are in PIXEL.
Attributes
The data type of the band’s pixels
All E_TID_* types are possible
The height of the source
The width of the source
The sub-sampling for the across-track direction in pixel
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.
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
Single pixel access
This function is for getting the values of the elements of a raster (i.e. pixel)
Parameters: |
|
---|---|
Returns: | the typed value at the given co-ordinate |
The size in byte of a single element (sample) of this raster’s buffer
Gets the raster’s height in pixels
Gets the raster’s width in pixels
Special methods
The Raster class provides a custom implementation of the following special methods:
Opens 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 |
---|---|
Returns: | the Product instance representing the specified product. An exception (exceptions.ValueError) is raised if the file could not be opened. |
Gets the ‘C’ data type string for the given data type
Gets the size in bytes for an element of the given data type
Return the name of the specified sample model
Return the name of the specified scaling method
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: |
|
---|---|
Returns: | the new Raster instance |
See also
description of Band.create_compatible_raster()
Creates a raster to be used for reading bitmasks
The raster returned always is of type byte.
Parameters: |
|
---|---|
Returns: | the new raster instance or raises an exception (EPRValueError) if an error occurred |
See also
the description of Band.create_compatible_raster()
Inherits both EPRError and standard exceptions.ValueError