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
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 aEPRValueError
if not found
-
get_band_at
(index)¶ Gets the
Band
at the specified position within theproduct
.Parameters: index – the index identifying the position of the Band
, starting with 0, must not be negativeReturns: the requested Band
instance, or raises aEPRValueError
if not found
-
get_dataset
(name)¶ Gets the
Dataset
corresponding to the specified dataset name.Parameters: name – the Dataset
nameReturns: the requested Dataset
instance
-
get_dataset_at
(index)¶ Gets the
Dataset
at the specified position within theProduct
.Parameters: index – the index identifying the position of the Dataset
, starting with 0, must not be negativeReturns: the requested Dataset
-
get_dsd_at
(index)¶ Gets the
DSD
at the specified position.Gets the
DSD
(Dataset
descriptor) at the specified position within theProduct
.Parameters: index – the index identifying the position of the DSD
, starting with 0, must not be negativeReturns: the requested DSD
instance
-
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
orNOT 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
orE_TID_CHAR
Returns: zero for success, an error code otherwise
See also
- 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
-
close
()¶ Closes the
Product
product and free the underlying file descriptor.This method has no effect if the
Product
is already closed. Once theProduct
is closed, any operation on it will raise aValueError
.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.
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()
orProduct.get_dataset_at()
methods.Attributes
Methods
-
create_record
()¶ Creates a new
Record
.Creates a new, empty
Record
with a structure compatible with theDataset
. Such aRecord
is typically used in subsequent calls toDataset.read_record()
.Returns: the new Record
instance
-
read_record
(index[, record])¶ Reads specified
Record
of theDataset
.The
Record
is identified through the given zero-basedRecord
index. In order to reduce memory reallocation, aRecord
(pre-)created by the methodDataset.create_record()
can be passed to this method. Data is then read into this givenRecord
.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 occurredChanged 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.
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
Attributes
-
tot_size
¶ The total size in bytes of the
Record
.It includes all data elements of all
Field
s of aRecord
in aProduct
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 theDataset
.It is None for empty
Record
s (created withDataset.create_record()
but still not read) and for MPH (seeProduct.get_mph()
) and SPH (seeProduct.get_sph()
)Record
s.See also
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 theField
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 theRecord
.Parameters: index – the zero-based index (position within Record
) of theField
Returns: the Field
or raises and exception (EPRValueError
) if an error occurred
-
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: 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 corresponding function in the C API.
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 internalfield_info
structure.See also
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_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 theField
Changed in version 0.9: the returned
numpy.ndarray
shares the data buffer with the CField
structure so any change in its contents is also reflected to theFiled
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 theField
.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
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¶
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 theopen()
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 integeruint32_t
–> 32-bit unsigned integerFloat
–> 32-bit IEEE floating point
-
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.
-
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 MDS2OF2
–> second byte of 2-byte interleaved MDS0123
–> combine 3-bytes interleaved to 4-byte integer
-
scaling_factor
¶ The scaling factor.
Possible values are:
-
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 appliedLinear_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 constantGADS.field[.field2]` --> value is provided in global annotation :class:`Dataset` with name ``GADS
inField
field
. Optionally a second element index for multiple-element fields can be given too
-
dataset
¶ The source
Dataset
.The source
Dataset
containing the raw data used to create theBand
pixel values.New in version 0.9.
Methods
-
create_compatible_raster
([src_width, src_height, xstep, ystep])¶ Creates a
Raster
which is compatible with the data type of theBand
.The created
Raster
is used to read the data in it (seeBand.read_raster()
).The
Raster
is defined on the grid of theProduct
, 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 ENVISATProduct
that are read into the it. Such a portion is called the source. The complete ENVISATProduct
can be much greater than the source. One can move theRaster
over the complete ENVISATProduct
and read in turn different parts (always of the size of the source) of it into theRaster
. 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 theRaster
, 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 (seeProduct.get_scene_width
) - src_height – the height (along track dimension) of the source to be read
into the
Raster
. Default: scene height (seeProduct.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 occurredNote
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
- src_width – the width (across track dimension) of the source to be read
into the
-
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 aRaster
. 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 theRaster
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.
- raster –
Raster
instance set with appropriate parameters to read into. If not provided a newRaster
is instantiated
Returns: the
Raster
instance in which data are readThis method raises an instance of the appropriate
EPRError
sub-class if case of errorsSee also
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 aRaster
. 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 theRaster
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 readThis method raises an instance of the appropriate
EPRError
sub-class if case of errorsSee also
Band.create_compatible_raster()
,create_raster()
andBand.read_raster()
- src_width – the width (across track dimension) of the source to be read
into the
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
-
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.
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
Special methods
The
Raster
class provides a custom implementation of the following special methods:- __repr__
-
Functions¶
-
epr.
open
(filename, mode='rb')¶ Open the ENVISAT product.
Opens the ENVISAT
Product
file with the given file path, reads MPH, SPH and allDSD
s, 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 thewith
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)
- product_file_path – the path to the ENVISAT
-
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_*.See also
- src_width – the width (across track dimension) of the source to be read
into the
Raster
. See description ofBand.create_compatible_raster()
- src_height – the height (along track dimension) of the source to be read
into the
Raster
. See description ofBand.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
instanceSee also
description of
Band.create_compatible_raster()
- data_type –
-
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 typebyte
.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 occurredSee also
the description of
Band.create_compatible_raster()
- src_width – the width (across track dimension) of the source to be read
into the