1. Introduction
The ENVISAT Product Reader API for C (epr-c-api) is a library of data
structures and functions for simple access to MERIS, AATSR and ASAR products. You can use
them in your programs to retrieve directly the geophysically coded values, e.g.
such as the chlorophyll concentration in mg/m³, in a data matrix.
The epr-c-api is generic, i.e. it has no instrument specific functions
but utilises the generic ENVISAT product format. However, it is not necessary for a user of the
epr-c-api to know the ENVISAT product format - the
epr-c-api knows it, and that's sufficient.
All a user of the epr-c-api has to know are a few functions and the name
of the geophysical variable he wants to get. In fact, the epr-c-api can
do more: all information stored in ENVISAT products can be retrieved in a unique way, just by
requesting it identified by its name, without worrying too much where and how it is stored in the
world of the ENVISAT product format.
Now, here's the tricky bit: there are many different products and the number of items stored in each product is huge. Therefore a ENVISAT Data Products documentation is included in the BEAM software homepage, which describes the internal structure of each supported product. In order to access a certain item such as a dataset, record, band or flag you have to consult the data product documentation for he correct name or ID for the dataset, record, band or flag you want to access.
2. Using the API in your own C-Programs
The epr-c-api is written in pure ANSI C and should compile with
every ANSI conformant C-compiler:
- Copy all
*.h*.cfiles contained in the distribution'ssrcfolder to your own source folder of your project and include them in your development environment (makefile or IDE). - Include the public API header
epr-api.hin your C source files. - Optionally refer to the example code in
src/examplesdirectory
3. API Design
3.1 Basic Concepts
Given here are some of the basic concepts of the API.
- The API works exclusively with pointers to dynamically allocated structures.
For every structure type in the API a constructor/desctructor function pair always exists:
X epr_create_X(...)andvoid epr_free_X(X). Example: For the typeEPR_SRecord*these functions areEPR_SRecord* epr_create_record(...)andvoid epr_free_record(EPR_SRecord*). -
In most cases, the first parameter is the object on which the function is operating.
For example,
uint epr_get_num_fields(const EPR_SRecord* record). - Access functions exist for all important members of structures. So, the
user of the API should not need to work directly with the API structures but
with functions to get values. For example, if you use the
epr_get_pixel_as_floatto access a pixel value of raster, your code is less dependent on API changes as if you would have directly accessed a structure member. - A central concept is that all items, which can be retrieved from ENVISAT
products, are identified by name. For example, to access the MERIS L1B radiance
of band 1, you have to call
epr_get_dataset_id(product_id, "Radiance_1")But how do you know, what name you should use for the data you want to retrieve? There are three possibilities:- The ENVISAT Data Products documentation provides all valid names used in the all supported data products. All tables in the documentation have a similar structure, the first column is always contains the longed-for name.
- One can use VISAT to open a product. The names shown in VISAT in the product browser are the same as in the ENVISAT data product tables documentation and are hence those needed.
-
One can open a product using the
epr-c-api, scan all datasets in a look and print the names of the datasets and records by the access function. The same can be done with all fields of a record.
3.2 Data Access Types
The API provides two access types for ENVISAT data:
- Access of data as it is stored in the product (we call this basic or raw data access) and
- Access to the geophysical raster data (what we call this geophysical data access).
The difference between the two is how they treat the measurement data: Access type (1) returns the data in its native data product structure: as datasets, records and fields. This gives a direct read access to the raw data as it is stored in the data product, without any interpretation of the content. For example, the MERIS L1B measurement data set MDS 15 stores chlorophyll, vegetation index or cloud top height in the same byte. The content has to be interpreted depending on the surface type, which itself is coded in MDS 20. To get the true geophysical value one needs to retrieve the proper scaling factors from a certain GADS. Access type (2) decodes all this and provides, for example, a data matrix with the chlorophyll concentration in a float variable in its geophysical units, i.e. mg/m³. The data of the measurement datasets and the tie-point values, i.e. geometry, geo-location and meteorological data, are available by this method. The tie-point data are interpolated to the corresponding image grid.
3.3 Working with the Basic/Raw Data Access
| Level | Correspondence in ENVISAT product |
| Product | ENVISAT product file |
| Dataset | Dataset, e.g. Main Product Header MPH, or a Measurement Data Set MDS. A dataset contains records. For example, the MERIS L1b MDS1 contains many records with radiance values. |
| Record | A single record within a dataset. A record contains many fields. For example, a record within the MERIS L1b MDS1 contains a time-stamp field, a quality flag field and then a field with as many radiance values as contained in the width of the image. |
| Field | A field within a record. Fields can be a scalar or a vector. In the example, the time stamp and quality flag are scalars while the radiance field is a vector of the length of an image line. |
| Element | Optional. If a field is a vector, these are the elements of that vector. In the example each element of the radiance field is the radiance of a certain pixel. |
On each level of the hierarchy, functions exist to point to a certain instance of it, e.g. a certain product, dataset or record and so on. That function generally requires the name of the item to be retrieved. All possible names can be found in the DDDB , and the name of the most important items are listed here. The function returns an identifier of that instance. The identifier is not the instance but a pointer to it. It is used to get the values of the instance by using access functions.
For example,
my_product_id = epr_open_product("my_MERIS_product");
returns the identifier to the my_product_id
which points to the product contained in the file "my_MERIS_product".
rad1_id = epr_get_dataset_id(my_product_id, "Radiance_1");
This my_product_id is used
get the identifier rad1_id
which points to the Radiance_1
dataset. Now, one can call
num_rec = epr_get_num_records(rad1_id);
to get the number of records which this dataset contains. Finally one can loop over all records and gets its fields and elements. See the examples to get a complete code example.
3.4 Working with Geophysical Data Access
To work with geophysical data is easier than the basic access. No such deep hierarchy exists. Instead of accessing datasets, so called bands will be accessed. A band directly includes one single geophysical variable.
For example,
my_product_id = epr_open_product(my_product_file_path);
my_chl_id = epr_create_band_id(my_product_id, "algal_1");
returns the identifier to a band containing the chlorophyll product. Now, the actual data are read into a raster.
chl_raster = epr_create_compatible_raster(my_chl_id, ...);
status = epr_read_band_raster(chl_raster, ...);
The raster
chl_raster now contains the data as two dimensional
matrix of pixel. To get the value of a pixel at a certain index
(i,j), one should use the access function:
chl_pixel = epr_get_pixel_as_float(chl_raster, i, j);
(See also the examples ndvi.c for complete example codes.)
The concept of the raster allows spatial subsets and undersampling: A certain portion of the ENVISAT product will be read into the raster. This 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.
A typical example is a processing in blocks. Lets say, a block has 64x32 pixel. Then, the source has a width of 64 pixel and a height of 32 pixel. Another example is a processing of complete image lines. Then, the 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 or image lines, read into the raster and process it. It is, of course, also possible to define a raster of the size of the complete product.
In addition, it is possible to define a subsampling 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 and along track directions.
3.5 Bit masks
MERIS and AATSR provide many so called flags, which are binary information
indicating a certain state of a pixel. For example, this can be a quality indicator,
which, if set, indicates that the value of the pixel is invalid. Other example
are a cloud flag, indicating that this pixel is a measurement above a cloud,
or a coastline flag. The flags are stored in a packed format inside the ENVISAT
products, but the epr-c-api provides a function to easily
access the flags.
It returns a bit-mask, which is a byte array that matches the corresponding
image raster and is 1 where the flag is set and 0 elsewhere. Even more, this
functions permits to formulate a bit-mask expression to combine any number of
flags in a logical expression and returns the resulting combined bit-mask:
bm_expr = "flags.LAND OR flags.CLOUD";
status = epr_read_bitmask_raster(product_id, bm_expr, ..., bm_raster);
This is an example to get a bit-mask which masks out all land and cloud pixels.
The names of the flags are found in the
DDDB.
The epr_read_bitmask_raster function read from product,
identified by product_id, the flags and stores the resulting
bit-mask in the raster bm_raster.
See the examples for the complete code.
4. API Function Group Index
The epr-c-api provides the following group of functions:
| (1) | Initialisation | Functions for setting up the environment of the API and releasing memory when the API is closed. |
| (2) | Logging | Functions to manage logging information |
| (3) | Error handling | Functions for determining the behaviour of the API in case of errors, and of getting information about runtime errors |
| (4) | Input / Output | Opening and closing ENVISAT products and writing data to a file or stdout. |
| (5) | Basic data access | Functions to retrieve raw data as stored in ENVISAT products |
| (6) | Geophysical data access | Functions to retrieve geophysically interpreted data in a raster matrix |
| (7) | Bit masks | Functions for generating bit masks from the flags included in ENVISAT products. |
| ENVISAT Product Reader API for C |
|
Data Structures
Here are the data structures with brief descriptions:| EPR_BandId | The EPR_BandId structure contains information about a band within an ENVISAT product file which has been opened with the epr_open_product() API function |
| EPR_DatasetId | The EPR_DatasetId structure contains information about a dataset within an ENVISAT product file which has been opened with the epr_open_product() API function |
| EPR_DatasetRef | The EPR_DatasetRef structure represents the information from dddb with the reference to data name (in dddb), field-name and index of the element in field-array, in which (by name) searchable values are located |
| EPR_DSD | The EPR_DSD structure contains information about the propertier of a dataset properties and its location within an ENVISAT product file |
| EPR_Field | Represents a field within a record |
| EPR_FlagDef | Represents a flag-field within a flag-record |
| EPR_ProductId | The EPR_ProductId structure contains information about an ENVISAT product file which has been opened with the epr_open_product() function |
| EPR_Raster | Represents a raster in which data will be stored |
| EPR_Record | The EPR_Record structure represents a record instance read from an ENVISAT dataset |
| EPR_Time | Represents a binary time value field in ENVISAT records |
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Data Structure Index
| EPR_DatasetRef | EPR_Field | EPR_ProductId | EPR_Record | |
| EPR_BandId | EPR_DSD | EPR_FlagDef | EPR_Raster | EPR_Time | |
| EPR_DatasetId |
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
epr_api.h File Reference
#include <stdio.h>#include "epr_ptrarray.h"#include <stdlib.h>Go to the source code of this file.
Data Structures | |
| struct | EPR_ProductId |
The EPR_ProductId structure contains information about an ENVISAT product file which has been opened with the epr_open_product() function. More... | |
| struct | EPR_DatasetId |
The EPR_DatasetId structure contains information about a dataset within an ENVISAT product file which has been opened with the epr_open_product() API function. More... | |
| struct | EPR_DSD |
The EPR_DSD structure contains information about the propertier of a dataset properties and its location within an ENVISAT product file. More... | |
| struct | EPR_Record |
The EPR_Record structure represents a record instance read from an ENVISAT dataset. More... | |
| struct | EPR_Field |
| Represents a field within a record. More... | |
| struct | EPR_Raster |
| Represents a raster in which data will be stored. More... | |
| struct | EPR_DatasetRef |
The EPR_DatasetRef structure represents the information from dddb with the reference to data name (in dddb), field-name and index of the element in field-array, in which (by name) searchable values are located. More... | |
| struct | EPR_FlagDef |
| Represents a flag-field within a flag-record. More... | |
| struct | EPR_BandId |
The EPR_BandId structure contains information about a band within an ENVISAT product file which has been opened with the epr_open_product() API function. More... | |
| struct | EPR_Time |
| Represents a binary time value field in ENVISAT records. More... | |
Defines | |
| #define | EPR_PRODUCT_API_NAME_STR "ENVISAT Product Reader API" |
| #define | EPR_PRODUCT_API_VERSION_STR "2.2" |
| #define | EPR_MAGIC_PRODUCT_ID 0xCAFFEE64 |
| #define | EPR_MAGIC_DATASET_ID 0xEFEABDCA |
| #define | EPR_MAGIC_BAND_ID 0xFEC21ABD |
| #define | EPR_MAGIC_RECORD 0x7BABACAE |
| #define | EPR_MAGIC_FIELD 0xBA0BABBA |
| #define | EPR_MAGIC_RASTER 0x0BABA0EB |
| #define | EPR_MAGIC_FLAG_DEF 0xCABA11AD |
| #define | TRUE 1 |
| #define | FALSE 0 |
| #define | EPR_PRODUCT_ID_STRLEN 48 |
Typedefs | |
| typedef enum EPR_DataTypeId | EPR_EDataTypeId |
| typedef enum EPR_ErrCode | EPR_EErrCode |
| typedef enum EPR_LogLevel | EPR_ELogLevel |
| typedef enum EPR_SampleModel | EPR_ESampleModel |
| typedef enum EPR_ScalingMethod | EPR_EScalingMethod |
| typedef struct EPR_ProductId | EPR_SProductId |
| typedef struct EPR_DatasetId | EPR_SDatasetId |
| typedef struct EPR_BandId | EPR_SBandId |
| typedef struct EPR_Record | EPR_SRecord |
| typedef struct EPR_RecordInfo | EPR_SRecordInfo |
| typedef struct EPR_Field | EPR_SField |
| typedef struct EPR_FieldInfo | EPR_SFieldInfo |
| typedef struct EPR_DSD | EPR_SDSD |
| typedef struct EPR_Raster | EPR_SRaster |
| typedef struct EPR_FlagDef | EPR_SFlagDef |
| typedef struct EPR_ParamElem | EPR_SParamElem |
| typedef struct EPR_Time | EPR_STime |
| typedef struct EPR_DatasetRef | EPR_SDatasetRef |
| typedef struct EPR_BitmaskTerm | EPR_SBitmaskTerm |
| typedef struct EPR_FlagSet | EPR_SFlagSet |
| typedef void(* | EPR_FErrHandler )(EPR_EErrCode err_code, const char *err_message) |
| typedef void(* | EPR_FLogHandler )(EPR_ELogLevel log_level, const char *log_message) |
| typedef int | epr_boolean |
| typedef unsigned char | uchar |
| typedef unsigned short | ushort |
| typedef unsigned int | uint |
| typedef unsigned long | ulong |
| typedef int | EPR_Magic |
Enumerations | |
| enum | EPR_DataTypeId { e_tid_unknown = 0, e_tid_uchar = 1, e_tid_char = 2, e_tid_ushort = 3, e_tid_short = 4, e_tid_uint = 5, e_tid_int = 6, e_tid_float = 7, e_tid_double = 8, e_tid_string = 11, e_tid_spare = 13, e_tid_time = 21 } |
The | |
| enum | EPR_ErrCode { e_err_none = 0, e_err_null_pointer = 1, e_err_illegal_arg = 2, e_err_illegal_state = 3, e_err_out_of_memory = 4, e_err_index_out_of_range = 5, e_err_illegal_conversion = 6, e_err_illegal_data_type = 7, e_err_file_not_found = 101, e_err_file_access_denied = 102, e_err_file_read_error = 103, e_err_file_write_error = 104, e_err_file_open_failed = 105, e_err_file_close_failed = 106, e_err_api_not_initialized = 201, e_err_invalid_product_id = 203, e_err_invalid_record = 204, e_err_invalid_band = 205, e_err_invalid_raster = 206, e_err_invalid_dataset_name = 207, e_err_invalid_field_name = 208, e_err_invalid_record_name = 209, e_err_invalid_product_name = 210, e_err_invalid_band_name = 211, e_err_invalid_data_format = 212, e_err_invalid_value = 213, e_err_invalid_keyword_name = 214, e_err_unknown_endian_order = 216, e_err_flag_not_found = 301, e_err_invalid_ddbb_format = 402 } |
The | |
| enum | EPR_LogLevel { e_log_debug = -1, e_log_info = 0, e_log_warning = 1, e_log_error = 2 } |
The | |
| enum | EPR_SampleModel { e_smod_1OF1 = 0, e_smod_1OF2 = 1, e_smod_2OF2 = 2, e_smod_3TOI = 3, e_smod_2TOF = 4 } |
| enum | EPR_ScalingMethod { e_smid_non = 0, e_smid_lin = 1, e_smid_log = 2 } |
Functions | |
| int | epr_init_api (EPR_ELogLevel log_level, EPR_FLogHandler log_handler, EPR_FErrHandler err_handler) |
| Initializes the ENVISAT product reader API. | |
| void | epr_close_api () |
| Closes the ENVISAT product reader API by releasing all resources allocated by the API. | |
| int | epr_set_log_level (EPR_ELogLevel log_level) |
| Sets the log level for the ENVISAT API. | |
| void | epr_set_log_handler (EPR_FLogHandler log_handler) |
| Sets the log handler for the ENVISAT API. | |
| void | epr_log_message (EPR_ELogLevel log_level, const char *log_message) |
A default implementation for a logging function to be passed into the epr_init() function. | |
| void | epr_set_err_handler (EPR_FErrHandler err_handler) |
| Sets the error handler for the ENVISAT API. | |
| EPR_EErrCode | epr_get_last_err_code () |
| Gets the error code of the error that occured during the last API function call. | |
| const char * | epr_get_last_err_message () |
| Gets the error message of the error that occured during the last API function call. | |
| void | epr_clear_err () |
| Clears the last error. | |
| EPR_SProductId * | epr_open_product (const char *product_file_path) |
| 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; returns a file identifier for the product. | |
| int | epr_close_product (EPR_SProductId *product_id) |
| Closes the ENVISAT product file determined by the given product identifier. | |
| void | epr_print_record (const EPR_SRecord *record, FILE *ostream) |
| void | epr_print_field (const EPR_SField *field, FILE *ostream) |
| void | epr_print_element (const EPR_SRecord *record, uint field_index, uint element_index, FILE *ostream) |
| void | epr_dump_record (const EPR_SRecord *record) |
| void | epr_dump_field (const EPR_SField *field) |
| void | epr_dump_element (const EPR_SRecord *record, uint field_index, uint element_index) |
| uint | epr_get_scene_width (const EPR_SProductId *product_id) |
| Gets the product's scene width in pixels. | |
| uint | epr_get_scene_height (const EPR_SProductId *product_id) |
| Gets the product's scene height in pixels. | |
| uint | epr_get_num_datasets (EPR_SProductId *product_id) |
| Gets the number off all datasets contained in a product. | |
| EPR_SDatasetId * | epr_get_dataset_id_at (EPR_SProductId *product_id, uint index) |
| Gets the dataset_id at the specified position within the product. | |
| EPR_SDatasetId * | epr_get_dataset_id (EPR_SProductId *product_id, const char *dataset_name) |
| Gets the dataset_id coresponding to the specified dataset name. | |
| const char * | epr_get_dataset_name (EPR_SDatasetId *dataset_id) |
| Gets the name of the dataset for the given dataset ID. | |
| const char * | epr_get_dsd_name (const EPR_SDatasetId *dataset_id) |
| Gets the name of the dsd for the given dataset ID. | |
| EPR_SRecord * | epr_get_mph (const EPR_SProductId *product_id) |
Gets the MPH record from the given product_id. | |
| EPR_SRecord * | epr_get_sph (const EPR_SProductId *product_id) |
Gets the SPH record from the given product_id. | |
| const EPR_SDSD * | epr_get_dsd (const EPR_SDatasetId *dataset_id) |
Gets the dataset descriptor (DSD) for the dataset specified by dataset_id. | |
| uint | epr_get_num_records (const EPR_SDatasetId *dataset_id) |
Gets the number of records of the dataset specified by dataset_id. | |
| uint | epr_get_num_dsds (const EPR_SProductId *product_id) |
| EPR_SDSD * | epr_get_dsd_at (const EPR_SProductId *product_id, uint dsd_index) |
| EPR_SRecord * | epr_create_record (EPR_SDatasetId *dataset_id) |
| Creates a new, empty record with a structure compatible with the dataset specified by dataset_id. | |
| EPR_SRecord * | epr_read_record (EPR_SDatasetId *dataset_id, uint record_index, EPR_SRecord *record) |
| Reads a record of a dataset specified by dataset_id. | |
| void | epr_free_record (EPR_SRecord *record) |
| Frees the memory allocated through the given record. | |
| const EPR_SField * | epr_get_field (const EPR_SRecord *record, const char *field_name) |
| Gets a field from the given record. | |
| uint | epr_get_num_fields (const EPR_SRecord *record) |
| Gets the number of fields contained in the given record. | |
| const EPR_SField * | epr_get_field_at (const EPR_SRecord *record, uint field_index) |
| Gets a field at the specified position within the record. | |
| const char * | epr_get_field_unit (const EPR_SField *field) |
| Gets the unit of the field. | |
| const char * | epr_get_field_description (const EPR_SField *field) |
| Gets the description of the field. | |
| uint | epr_get_field_num_elems (const EPR_SField *field) |
| Gets the number of elements of the field. | |
| const char * | epr_get_field_name (const EPR_SField *field) |
| Gets the name of the field. | |
| EPR_EDataTypeId | epr_get_field_type (const EPR_SField *field) |
| Gets the type of the field. | |
| char | epr_get_field_elem_as_char (const EPR_SField *field, uint elem_index) |
| uchar | epr_get_field_elem_as_uchar (const EPR_SField *field, uint elem_index) |
| short | epr_get_field_elem_as_short (const EPR_SField *field, uint elem_index) |
| ushort | epr_get_field_elem_as_ushort (const EPR_SField *field, uint elem_index) |
| int | epr_get_field_elem_as_int (const EPR_SField *field, uint elem_index) |
| uint | epr_get_field_elem_as_uint (const EPR_SField *field, uint elem_index) |
| float | epr_get_field_elem_as_float (const EPR_SField *field, uint elem_index) |
| double | epr_get_field_elem_as_double (const EPR_SField *field, uint elem_index) |
| const EPR_STime * | epr_get_field_elem_as_mjd (const EPR_SField *field) |
| const char * | epr_get_field_elem_as_str (const EPR_SField *field) |
| const char * | epr_get_field_elems_char (const EPR_SField *field) |
| const uchar * | epr_get_field_elems_uchar (const EPR_SField *field) |
| const short * | epr_get_field_elems_short (const EPR_SField *field) |
| const ushort * | epr_get_field_elems_ushort (const EPR_SField *field) |
| const int * | epr_get_field_elems_int (const EPR_SField *field) |
| const uint * | epr_get_field_elems_uint (const EPR_SField *field) |
| const float * | epr_get_field_elems_float (const EPR_SField *field) |
| const double * | epr_get_field_elems_double (const EPR_SField *field) |
| uint | epr_copy_field_elems_as_ints (const EPR_SField *field, int *buffer, uint num_elems) |
| uint | epr_copy_field_elems_as_uints (const EPR_SField *field, uint *buffer, uint num_elems) |
| uint | epr_copy_field_elems_as_floats (const EPR_SField *field, float *buffer, uint num_elems) |
| uint | epr_copy_field_elems_as_doubles (const EPR_SField *field, double *buffer, uint num_elems) |
| EPR_SRaster * | epr_create_compatible_raster (EPR_SBandId *band_id, uint source_width, uint source_height, uint source_step_x, uint source_step_y) |
| Creates a raster which is compatible with the data type contained in the band identified by band_id. | |
| EPR_SRaster * | epr_create_raster (EPR_EDataTypeId data_type, uint source_width, uint source_height, uint source_step_x, uint source_step_y) |
| Creates a raster of the specified data type. | |
| EPR_SRaster * | epr_create_bitmask_raster (uint source_width, uint source_height, uint source_step_x, uint source_step_y) |
| Creates a raster to be used for reading bitmasks. | |
| int | epr_read_band_raster (EPR_SBandId *band_id, int offset_x, int offset_y, EPR_SRaster *raster) |
| Reads (geo-)physical values of the given band of the specified source-region. | |
| uint | epr_get_raster_elem_size (const EPR_SRaster *raster) |
| void * | epr_get_raster_elem_addr (const EPR_SRaster *raster, uint offset) |
| void * | epr_get_raster_pixel_addr (const EPR_SRaster *raster, uint x, uint y) |
| void * | epr_get_raster_line_addr (const EPR_SRaster *raster, uint y) |
| uint | epr_get_raster_width (EPR_SRaster *raster) |
| Gets the raster's scene width in pixels. | |
| uint | epr_get_raster_height (EPR_SRaster *raster) |
| Gets the raster's scene height in pixels. | |
| uint | epr_get_num_bands (EPR_SProductId *product_id) |
| Gets the number of all bands contained in a product. | |
| EPR_SBandId * | epr_get_band_id_at (EPR_SProductId *product_id, uint index) |
| Gets the band ID at the specified position within the product. | |
| EPR_SBandId * | epr_get_band_id (EPR_SProductId *product_id, const char *band_name) |
| Gets the band ID corresponding to the specified name. | |
| const char * | epr_get_band_name (EPR_SBandId *band_id) |
| Gets the name of the band for the given band ID. | |
| void | epr_free_raster (EPR_SRaster *raster) |
| Release the memory allocated through a raster. | |
| uint | epr_get_pixel_as_uint (const EPR_SRaster *raster, int x, int y) |
| This group of functions is for getting the values of the elements of a raster (i.e. | |
| int | epr_get_pixel_as_int (const EPR_SRaster *raster, int x, int y) |
| float | epr_get_pixel_as_float (const EPR_SRaster *raster, int x, int y) |
| double | epr_get_pixel_as_double (const EPR_SRaster *raster, int x, int y) |
| int | epr_read_bitmask_raster (EPR_SProductId *product_id, const char *bm_expr, int offset_x, int offset_y, EPR_SRaster *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. | |
| uint | epr_get_data_type_size (EPR_EDataTypeId data_type_id) |
| Gets the size in bytes for an element of the given data type. | |
| const char * | epr_data_type_id_to_str (EPR_EDataTypeId data_type_id) |
| Gets the 'C' data type string for the given data type. | |
Define Documentation
| #define EPR_PRODUCT_API_NAME_STR "ENVISAT Product Reader API" |
| #define EPR_PRODUCT_API_VERSION_STR "2.2" |
| #define EPR_MAGIC_PRODUCT_ID 0xCAFFEE64 |
| #define EPR_MAGIC_DATASET_ID 0xEFEABDCA |
| #define EPR_MAGIC_BAND_ID 0xFEC21ABD |
| #define EPR_MAGIC_RECORD 0x7BABACAE |
| #define EPR_MAGIC_FIELD 0xBA0BABBA |
| #define EPR_MAGIC_RASTER 0x0BABA0EB |
| #define EPR_MAGIC_FLAG_DEF 0xCABA11AD |
| #define TRUE 1 |
| #define FALSE 0 |
| #define EPR_PRODUCT_ID_STRLEN 48 |
Typedef Documentation
| typedef enum EPR_DataTypeId EPR_EDataTypeId |
| typedef enum EPR_ErrCode EPR_EErrCode |
| typedef enum EPR_LogLevel EPR_ELogLevel |
| typedef enum EPR_SampleModel EPR_ESampleModel |
| typedef enum EPR_ScalingMethod EPR_EScalingMethod |
| typedef struct EPR_ProductId EPR_SProductId |
| typedef struct EPR_DatasetId EPR_SDatasetId |
| typedef struct EPR_BandId EPR_SBandId |
| typedef struct EPR_Record EPR_SRecord |
| typedef struct EPR_RecordInfo EPR_SRecordInfo |
| typedef struct EPR_Field EPR_SField |
| typedef struct EPR_FieldInfo EPR_SFieldInfo |
| typedef struct EPR_Raster EPR_SRaster |
| typedef struct EPR_FlagDef EPR_SFlagDef |
| typedef struct EPR_ParamElem EPR_SParamElem |
| typedef struct EPR_DatasetRef EPR_SDatasetRef |
| typedef struct EPR_BitmaskTerm EPR_SBitmaskTerm |
| typedef struct EPR_FlagSet EPR_SFlagSet |
| typedef void(* EPR_FErrHandler)(EPR_EErrCode err_code, const char *err_message) |
| typedef void(* EPR_FLogHandler)(EPR_ELogLevel log_level, const char *log_message) |
| typedef int epr_boolean |
| typedef unsigned char uchar |
| typedef unsigned short ushort |
| typedef unsigned int uint |
| typedef unsigned long ulong |
| typedef int EPR_Magic |
Enumeration Type Documentation
| enum EPR_DataTypeId |
The EPR_DataTypeId enumeration lists all possible data types for field elements in ENVISAT dataset records.
- Enumerator:
e_tid_unknown The ID for unknown types.
e_tid_uchar An array of unsigned 8-bit integers, C type is
uchar*e_tid_char An array of signed 8-bit integers, C type is
char*e_tid_ushort An array of unsigned 16-bit integers, C type is
ushort*e_tid_short An array of signed 16-bit integers, C type is
short*e_tid_uint An array of unsigned 32-bit integers, C type is
uint*e_tid_int An array of signed 32-bit integers, C type is
int*e_tid_float An array of 32-bit floating point numbers, C type is
float*e_tid_double An array of 64-bit floating point numbers, C type is
double*e_tid_string A zero-terminated ASCII string, C type is
char*e_tid_spare An array of unsigned character, C type is
uchar*e_tid_time A time (MJD) structure, C type is
EPR_Time
| enum EPR_ErrCode |
The EPR_ErrCode enumeration lists all possible error codes for the ENVISAT product reader API.
- Enumerator:
| enum EPR_LogLevel |
| enum EPR_SampleModel |
| enum EPR_ScalingMethod |
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Here is a list of all struct and union fields with links to the structures/unions they belong to:
- b -
- band_ids : EPR_ProductId
- band_name : EPR_BandId
- bit_mask : EPR_FlagDef
- bm_expr : EPR_BandId
- buffer : EPR_Raster
- d -
- data_type : EPR_Raster , EPR_BandId
- dataset_id : EPR_DatasetRef
- dataset_ids : EPR_ProductId
- dataset_name : EPR_DatasetId
- dataset_ref : EPR_BandId
- days : EPR_Time
- description : EPR_DatasetId , EPR_FlagDef , EPR_BandId
- ds_name : EPR_DSD
- ds_offset : EPR_DSD
- ds_size : EPR_DSD
- ds_type : EPR_DSD
- dsd : EPR_DatasetId
- dsd_array : EPR_ProductId
- dsd_name : EPR_DatasetId
- dsr_size : EPR_DSD
- e -
- elem_index : EPR_DatasetRef
- elem_size : EPR_Raster
- elems : EPR_Field
- f -
- field_index : EPR_DatasetRef
- fields : EPR_Record
- file_path : EPR_ProductId
- filename : EPR_DSD
- flag_coding : EPR_BandId
- i -
- id_string : EPR_ProductId
- index : EPR_DSD
- info : EPR_Field , EPR_Record
- istream : EPR_ProductId
- l -
- lines_mirrored : EPR_BandId
- m -
- magic : EPR_ProductId , EPR_DatasetId , EPR_Record , EPR_BandId , EPR_Field , EPR_FlagDef , EPR_Raster , EPR_DSD
- meris_iodd_version : EPR_ProductId
- microseconds : EPR_Time
- mph_record : EPR_ProductId
- n -
- name : EPR_FlagDef
- num_dsr : EPR_DSD
- num_fields : EPR_Record
- p -
- param_table : EPR_ProductId
- product_id : EPR_BandId , EPR_DatasetId
- r -
- raster_height : EPR_Raster
- raster_width : EPR_Raster
- record_descriptor : EPR_DatasetId
- record_info : EPR_DatasetId
- record_info_cache : EPR_ProductId
- s -
- sample_model : EPR_BandId
- scaling_factor : EPR_BandId
- scaling_method : EPR_BandId
- scaling_offset : EPR_BandId
- scene_height : EPR_ProductId
- scene_width : EPR_ProductId
- seconds : EPR_Time
- source_height : EPR_Raster
- source_step_x : EPR_Raster
- source_step_y : EPR_Raster
- source_width : EPR_Raster
- spectr_band_index : EPR_BandId
- sph_record : EPR_ProductId
- t -
- tot_size : EPR_ProductId
- u -
- unit : EPR_BandId
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
- b -
- band_ids : EPR_ProductId
- band_name : EPR_BandId
- bit_mask : EPR_FlagDef
- bm_expr : EPR_BandId
- buffer : EPR_Raster
- d -
- data_type : EPR_Raster , EPR_BandId
- dataset_id : EPR_DatasetRef
- dataset_ids : EPR_ProductId
- dataset_name : EPR_DatasetId
- dataset_ref : EPR_BandId
- days : EPR_Time
- description : EPR_DatasetId , EPR_FlagDef , EPR_BandId
- ds_name : EPR_DSD
- ds_offset : EPR_DSD
- ds_size : EPR_DSD
- ds_type : EPR_DSD
- dsd : EPR_DatasetId
- dsd_array : EPR_ProductId
- dsd_name : EPR_DatasetId
- dsr_size : EPR_DSD
- e -
- elem_index : EPR_DatasetRef
- elem_size : EPR_Raster
- elems : EPR_Field
- f -
- field_index : EPR_DatasetRef
- fields : EPR_Record
- file_path : EPR_ProductId
- filename : EPR_DSD
- flag_coding : EPR_BandId
- i -
- id_string : EPR_ProductId
- index : EPR_DSD
- info : EPR_Field , EPR_Record
- istream : EPR_ProductId
- l -
- lines_mirrored : EPR_BandId
- m -
- magic : EPR_ProductId , EPR_DatasetId , EPR_Record , EPR_BandId , EPR_Field , EPR_FlagDef , EPR_Raster , EPR_DSD
- meris_iodd_version : EPR_ProductId
- microseconds : EPR_Time
- mph_record : EPR_ProductId
- n -
- name : EPR_FlagDef
- num_dsr : EPR_DSD
- num_fields : EPR_Record
- p -
- param_table : EPR_ProductId
- product_id : EPR_BandId , EPR_DatasetId
- r -
- raster_height : EPR_Raster
- raster_width : EPR_Raster
- record_descriptor : EPR_DatasetId
- record_info : EPR_DatasetId
- record_info_cache : EPR_ProductId
- s -
- sample_model : EPR_BandId
- scaling_factor : EPR_BandId
- scaling_method : EPR_BandId
- scaling_offset : EPR_BandId
- scene_height : EPR_ProductId
- scene_width : EPR_ProductId
- seconds : EPR_Time
- source_height : EPR_Raster
- source_step_x : EPR_Raster
- source_step_y : EPR_Raster
- source_width : EPR_Raster
- spectr_band_index : EPR_BandId
- sph_record : EPR_ProductId
- t -
- tot_size : EPR_ProductId
- u -
- unit : EPR_BandId
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Here is a list of all functions, variables, defines, enums, and typedefs with links to the files they belong to:
- e -
- e_err_api_not_initialized : epr_api.h
- e_err_file_access_denied : epr_api.h
- e_err_file_close_failed : epr_api.h
- e_err_file_not_found : epr_api.h
- e_err_file_open_failed : epr_api.h
- e_err_file_read_error : epr_api.h
- e_err_file_write_error : epr_api.h
- e_err_flag_not_found : epr_api.h
- e_err_illegal_arg : epr_api.h
- e_err_illegal_conversion : epr_api.h
- e_err_illegal_data_type : epr_api.h
- e_err_illegal_state : epr_api.h
- e_err_index_out_of_range : epr_api.h
- e_err_invalid_band : epr_api.h
- e_err_invalid_band_name : epr_api.h
- e_err_invalid_data_format : epr_api.h
- e_err_invalid_dataset_name : epr_api.h
- e_err_invalid_ddbb_format : epr_api.h
- e_err_invalid_field_name : epr_api.h
- e_err_invalid_keyword_name : epr_api.h
- e_err_invalid_product_id : epr_api.h
- e_err_invalid_product_name : epr_api.h
- e_err_invalid_raster : epr_api.h
- e_err_invalid_record : epr_api.h
- e_err_invalid_record_name : epr_api.h
- e_err_invalid_value : epr_api.h
- e_err_none : epr_api.h
- e_err_null_pointer : epr_api.h
- e_err_out_of_memory : epr_api.h
- e_err_unknown_endian_order : epr_api.h
- e_log_debug : epr_api.h
- e_log_error : epr_api.h
- e_log_info : epr_api.h
- e_log_warning : epr_api.h
- e_smid_lin : epr_api.h
- e_smid_log : epr_api.h
- e_smid_non : epr_api.h
- e_smod_1OF1 : epr_api.h
- e_smod_1OF2 : epr_api.h
- e_smod_2OF2 : epr_api.h
- e_smod_2TOF : epr_api.h
- e_smod_3TOI : epr_api.h
- e_tid_char : epr_api.h
- e_tid_double : epr_api.h
- e_tid_float : epr_api.h
- e_tid_int : epr_api.h
- e_tid_short : epr_api.h
- e_tid_spare : epr_api.h
- e_tid_string : epr_api.h
- e_tid_time : epr_api.h
- e_tid_uchar : epr_api.h
- e_tid_uint : epr_api.h
- e_tid_unknown : epr_api.h
- e_tid_ushort : epr_api.h
- epr_boolean : epr_api.h
- epr_clear_err() : epr_api.h
- epr_close_api() : epr_api.h
- epr_close_product() : epr_api.h
- epr_copy_field_elems_as_doubles() : epr_api.h
- epr_copy_field_elems_as_floats() : epr_api.h
- epr_copy_field_elems_as_ints() : epr_api.h
- epr_copy_field_elems_as_uints() : epr_api.h
- epr_create_bitmask_raster() : epr_api.h
- epr_create_compatible_raster() : epr_api.h
- epr_create_raster() : epr_api.h
- epr_create_record() : epr_api.h
- epr_data_type_id_to_str() : epr_api.h
- EPR_DataTypeId : epr_api.h
- epr_dump_element() : epr_api.h
- epr_dump_field() : epr_api.h
- epr_dump_record() : epr_api.h
- EPR_EDataTypeId : epr_api.h
- EPR_EErrCode : epr_api.h
- EPR_ELogLevel : epr_api.h
- EPR_ErrCode : epr_api.h
- EPR_ESampleModel : epr_api.h
- EPR_EScalingMethod : epr_api.h
- EPR_FErrHandler : epr_api.h
- EPR_FLogHandler : epr_api.h
- epr_free_raster() : epr_api.h
- epr_free_record() : epr_api.h
- epr_get_band_id() : epr_api.h
- epr_get_band_id_at() : epr_api.h
- epr_get_band_name() : epr_api.h
- epr_get_data_type_size() : epr_api.h
- epr_get_dataset_id() : epr_api.h
- epr_get_dataset_id_at() : epr_api.h
- epr_get_dataset_name() : epr_api.h
- epr_get_dsd() : epr_api.h
- epr_get_dsd_at() : epr_api.h
- epr_get_dsd_name() : epr_api.h
- epr_get_field() : epr_api.h
- epr_get_field_at() : epr_api.h
- epr_get_field_description() : epr_api.h
- epr_get_field_elem_as_char() : epr_api.h
- epr_get_field_elem_as_double() : epr_api.h
- epr_get_field_elem_as_float() : epr_api.h
- epr_get_field_elem_as_int() : epr_api.h
- epr_get_field_elem_as_mjd() : epr_api.h
- epr_get_field_elem_as_short() : epr_api.h
- epr_get_field_elem_as_str() : epr_api.h
- epr_get_field_elem_as_uchar() : epr_api.h
- epr_get_field_elem_as_uint() : epr_api.h
- epr_get_field_elem_as_ushort() : epr_api.h
- epr_get_field_elems_char() : epr_api.h
- epr_get_field_elems_double() : epr_api.h
- epr_get_field_elems_float() : epr_api.h
- epr_get_field_elems_int() : epr_api.h
- epr_get_field_elems_short() : epr_api.h
- epr_get_field_elems_uchar() : epr_api.h
- epr_get_field_elems_uint() : epr_api.h
- epr_get_field_elems_ushort() : epr_api.h
- epr_get_field_name() : epr_api.h
- epr_get_field_num_elems() : epr_api.h
- epr_get_field_type() : epr_api.h
- epr_get_field_unit() : epr_api.h
- epr_get_last_err_code() : epr_api.h
- epr_get_last_err_message() : epr_api.h
- epr_get_mph() : epr_api.h
- epr_get_num_bands() : epr_api.h
- epr_get_num_datasets() : epr_api.h
- epr_get_num_dsds() : epr_api.h
- epr_get_num_fields() : epr_api.h
- epr_get_num_records() : epr_api.h
- epr_get_pixel_as_double() : epr_api.h
- epr_get_pixel_as_float() : epr_api.h
- epr_get_pixel_as_int() : epr_api.h
- epr_get_pixel_as_uint() : epr_api.h
- epr_get_raster_elem_addr() : epr_api.h
- epr_get_raster_elem_size() : epr_api.h
- epr_get_raster_height() : epr_api.h
- epr_get_raster_line_addr() : epr_api.h
- epr_get_raster_pixel_addr() : epr_api.h
- epr_get_raster_width() : epr_api.h
- epr_get_scene_height() : epr_api.h
- epr_get_scene_width() : epr_api.h
- epr_get_sph() : epr_api.h
- epr_init_api() : epr_api.h
- epr_log_message() : epr_api.h
- EPR_LogLevel : epr_api.h
- EPR_Magic : epr_api.h
- EPR_MAGIC_BAND_ID : epr_api.h
- EPR_MAGIC_DATASET_ID : epr_api.h
- EPR_MAGIC_FIELD : epr_api.h
- EPR_MAGIC_FLAG_DEF : epr_api.h
- EPR_MAGIC_PRODUCT_ID : epr_api.h
- EPR_MAGIC_RASTER : epr_api.h
- EPR_MAGIC_RECORD : epr_api.h
- epr_open_product() : epr_api.h
- epr_print_element() : epr_api.h
- epr_print_field() : epr_api.h
- epr_print_record() : epr_api.h
- EPR_PRODUCT_API_NAME_STR : epr_api.h
- EPR_PRODUCT_API_VERSION_STR : epr_api.h
- EPR_PRODUCT_ID_STRLEN : epr_api.h
- epr_read_band_raster() : epr_api.h
- epr_read_bitmask_raster() : epr_api.h
- epr_read_record() : epr_api.h
- EPR_SampleModel : epr_api.h
- EPR_SBandId : epr_api.h
- EPR_SBitmaskTerm : epr_api.h
- EPR_ScalingMethod : epr_api.h
- EPR_SDatasetId : epr_api.h
- EPR_SDatasetRef : epr_api.h
- EPR_SDSD : epr_api.h
- epr_set_err_handler() : epr_api.h
- epr_set_log_handler() : epr_api.h
- epr_set_log_level() : epr_api.h
- EPR_SField : epr_api.h
- EPR_SFieldInfo : epr_api.h
- EPR_SFlagDef : epr_api.h
- EPR_SFlagSet : epr_api.h
- EPR_SParamElem : epr_api.h
- EPR_SProductId : epr_api.h
- EPR_SRaster : epr_api.h
- EPR_SRecord : epr_api.h
- EPR_SRecordInfo : epr_api.h
- EPR_STime : epr_api.h
- f -
- FALSE : epr_api.h
- t -
- TRUE : epr_api.h
- u -
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
- EPR_MAGIC_BAND_ID : epr_api.h
- EPR_MAGIC_DATASET_ID : epr_api.h
- EPR_MAGIC_FIELD : epr_api.h
- EPR_MAGIC_FLAG_DEF : epr_api.h
- EPR_MAGIC_PRODUCT_ID : epr_api.h
- EPR_MAGIC_RASTER : epr_api.h
- EPR_MAGIC_RECORD : epr_api.h
- EPR_PRODUCT_API_NAME_STR : epr_api.h
- EPR_PRODUCT_API_VERSION_STR : epr_api.h
- EPR_PRODUCT_ID_STRLEN : epr_api.h
- FALSE : epr_api.h
- TRUE : epr_api.h
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
- e -
- e_err_api_not_initialized : epr_api.h
- e_err_file_access_denied : epr_api.h
- e_err_file_close_failed : epr_api.h
- e_err_file_not_found : epr_api.h
- e_err_file_open_failed : epr_api.h
- e_err_file_read_error : epr_api.h
- e_err_file_write_error : epr_api.h
- e_err_flag_not_found : epr_api.h
- e_err_illegal_arg : epr_api.h
- e_err_illegal_conversion : epr_api.h
- e_err_illegal_data_type : epr_api.h
- e_err_illegal_state : epr_api.h
- e_err_index_out_of_range : epr_api.h
- e_err_invalid_band : epr_api.h
- e_err_invalid_band_name : epr_api.h
- e_err_invalid_data_format : epr_api.h
- e_err_invalid_dataset_name : epr_api.h
- e_err_invalid_ddbb_format : epr_api.h
- e_err_invalid_field_name : epr_api.h
- e_err_invalid_keyword_name : epr_api.h
- e_err_invalid_product_id : epr_api.h
- e_err_invalid_product_name : epr_api.h
- e_err_invalid_raster : epr_api.h
- e_err_invalid_record : epr_api.h
- e_err_invalid_record_name : epr_api.h
- e_err_invalid_value : epr_api.h
- e_err_none : epr_api.h
- e_err_null_pointer : epr_api.h
- e_err_out_of_memory : epr_api.h
- e_err_unknown_endian_order : epr_api.h
- e_log_debug : epr_api.h
- e_log_error : epr_api.h
- e_log_info : epr_api.h
- e_log_warning : epr_api.h
- e_smid_lin : epr_api.h
- e_smid_log : epr_api.h
- e_smid_non : epr_api.h
- e_smod_1OF1 : epr_api.h
- e_smod_1OF2 : epr_api.h
- e_smod_2OF2 : epr_api.h
- e_smod_2TOF : epr_api.h
- e_smod_3TOI : epr_api.h
- e_tid_char : epr_api.h
- e_tid_double : epr_api.h
- e_tid_float : epr_api.h
- e_tid_int : epr_api.h
- e_tid_short : epr_api.h
- e_tid_spare : epr_api.h
- e_tid_string : epr_api.h
- e_tid_time : epr_api.h
- e_tid_uchar : epr_api.h
- e_tid_uint : epr_api.h
- e_tid_unknown : epr_api.h
- e_tid_ushort : epr_api.h
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
- e -
- epr_clear_err() : epr_api.h
- epr_close_api() : epr_api.h
- epr_close_product() : epr_api.h
- epr_copy_field_elems_as_doubles() : epr_api.h
- epr_copy_field_elems_as_floats() : epr_api.h
- epr_copy_field_elems_as_ints() : epr_api.h
- epr_copy_field_elems_as_uints() : epr_api.h
- epr_create_bitmask_raster() : epr_api.h
- epr_create_compatible_raster() : epr_api.h
- epr_create_raster() : epr_api.h
- epr_create_record() : epr_api.h
- epr_data_type_id_to_str() : epr_api.h
- epr_dump_element() : epr_api.h
- epr_dump_field() : epr_api.h
- epr_dump_record() : epr_api.h
- epr_free_raster() : epr_api.h
- epr_free_record() : epr_api.h
- epr_get_band_id() : epr_api.h
- epr_get_band_id_at() : epr_api.h
- epr_get_band_name() : epr_api.h
- epr_get_data_type_size() : epr_api.h
- epr_get_dataset_id() : epr_api.h
- epr_get_dataset_id_at() : epr_api.h
- epr_get_dataset_name() : epr_api.h
- epr_get_dsd() : epr_api.h
- epr_get_dsd_at() : epr_api.h
- epr_get_dsd_name() : epr_api.h
- epr_get_field() : epr_api.h
- epr_get_field_at() : epr_api.h
- epr_get_field_description() : epr_api.h
- epr_get_field_elem_as_char() : epr_api.h
- epr_get_field_elem_as_double() : epr_api.h
- epr_get_field_elem_as_float() : epr_api.h
- epr_get_field_elem_as_int() : epr_api.h
- epr_get_field_elem_as_mjd() : epr_api.h
- epr_get_field_elem_as_short() : epr_api.h
- epr_get_field_elem_as_str() : epr_api.h
- epr_get_field_elem_as_uchar() : epr_api.h
- epr_get_field_elem_as_uint() : epr_api.h
- epr_get_field_elem_as_ushort() : epr_api.h
- epr_get_field_elems_char() : epr_api.h
- epr_get_field_elems_double() : epr_api.h
- epr_get_field_elems_float() : epr_api.h
- epr_get_field_elems_int() : epr_api.h
- epr_get_field_elems_short() : epr_api.h
- epr_get_field_elems_uchar() : epr_api.h
- epr_get_field_elems_uint() : epr_api.h
- epr_get_field_elems_ushort() : epr_api.h
- epr_get_field_name() : epr_api.h
- epr_get_field_num_elems() : epr_api.h
- epr_get_field_type() : epr_api.h
- epr_get_field_unit() : epr_api.h
- epr_get_last_err_code() : epr_api.h
- epr_get_last_err_message() : epr_api.h
- epr_get_mph() : epr_api.h
- epr_get_num_bands() : epr_api.h
- epr_get_num_datasets() : epr_api.h
- epr_get_num_dsds() : epr_api.h
- epr_get_num_fields() : epr_api.h
- epr_get_num_records() : epr_api.h
- epr_get_pixel_as_double() : epr_api.h
- epr_get_pixel_as_float() : epr_api.h
- epr_get_pixel_as_int() : epr_api.h
- epr_get_pixel_as_uint() : epr_api.h
- epr_get_raster_elem_addr() : epr_api.h
- epr_get_raster_elem_size() : epr_api.h
- epr_get_raster_height() : epr_api.h
- epr_get_raster_line_addr() : epr_api.h
- epr_get_raster_pixel_addr() : epr_api.h
- epr_get_raster_width() : epr_api.h
- epr_get_scene_height() : epr_api.h
- epr_get_scene_width() : epr_api.h
- epr_get_sph() : epr_api.h
- epr_init_api() : epr_api.h
- epr_log_message() : epr_api.h
- epr_open_product() : epr_api.h
- epr_print_element() : epr_api.h
- epr_print_field() : epr_api.h
- epr_print_record() : epr_api.h
- epr_read_band_raster() : epr_api.h
- epr_read_bitmask_raster() : epr_api.h
- epr_read_record() : epr_api.h
- epr_set_err_handler() : epr_api.h
- epr_set_log_handler() : epr_api.h
- epr_set_log_level() : epr_api.h
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
- epr_boolean : epr_api.h
- EPR_EDataTypeId : epr_api.h
- EPR_EErrCode : epr_api.h
- EPR_ELogLevel : epr_api.h
- EPR_ESampleModel : epr_api.h
- EPR_EScalingMethod : epr_api.h
- EPR_FErrHandler : epr_api.h
- EPR_FLogHandler : epr_api.h
- EPR_Magic : epr_api.h
- EPR_SBandId : epr_api.h
- EPR_SBitmaskTerm : epr_api.h
- EPR_SDatasetId : epr_api.h
- EPR_SDatasetRef : epr_api.h
- EPR_SDSD : epr_api.h
- EPR_SField : epr_api.h
- EPR_SFieldInfo : epr_api.h
- EPR_SFlagDef : epr_api.h
- EPR_SFlagSet : epr_api.h
- EPR_SParamElem : epr_api.h
- EPR_SProductId : epr_api.h
- EPR_SRaster : epr_api.h
- EPR_SRecord : epr_api.h
- EPR_SRecordInfo : epr_api.h
- EPR_STime : epr_api.h
- uchar : epr_api.h
- uint : epr_api.h
- ulong : epr_api.h
- ushort : epr_api.h
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Bitmask
Functions | |
| int | epr_read_bitmask_raster (EPR_SProductId *product_id, const char *bm_expr, int offset_x, int offset_y, EPR_SRaster *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. | |
Function Documentation
| int epr_read_bitmask_raster | ( | EPR_SProductId * | product_id, | |
| const char * | bm_expr, | |||
| int | offset_x, | |||
| int | offset_y, | |||
| EPR_SRaster * | 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:
-
product_id Identifier of the ENVISAT product for which the bit-mask shall be created. This is used by the function to retreive the needed flags. bm_expr A string holding the logical expression for the defintion 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".offset_x across-track co-ordinate in pixel co-ordinates (zero-based) of the upper right corner of the source-region offset_y 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
- See also:
- create_band_raster
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Copy Field Elems This group of functions is for copying the data of the given field into the given
[Basic Data Access]
buffer of elements by selected type. More...
Functions | |
| uint | epr_copy_field_elems_as_ints (const EPR_SField *field, int *buffer, uint num_elems) |
| uint | epr_copy_field_elems_as_uints (const EPR_SField *field, uint *buffer, uint num_elems) |
| uint | epr_copy_field_elems_as_floats (const EPR_SField *field, float *buffer, uint num_elems) |
| uint | epr_copy_field_elems_as_doubles (const EPR_SField *field, double *buffer, uint num_elems) |
Detailed Description
buffer of elements by selected type.
The actual number of elements copied is the minimum of the given number of elements (the buffer's size) and the actual number of elements contained in the field.
If the actual field data type is not selected type, the function automatically performs the conversion.
- Parameters:
-
field the field from which to copy the elements buffer the buffer in which to copy the data num_elems the number of elements in the given buffer
- Returns:
- the actual number of elements copied
Function Documentation
| uint epr_copy_field_elems_as_ints | ( | const EPR_SField * | field, | |
| int * | buffer, | |||
| uint | num_elems | |||
| ) |
| uint epr_copy_field_elems_as_uints | ( | const EPR_SField * | field, | |
| uint * | buffer, | |||
| uint | num_elems | |||
| ) |
| uint epr_copy_field_elems_as_floats | ( | const EPR_SField * | field, | |
| float * | buffer, | |||
| uint | num_elems | |||
| ) |
| uint epr_copy_field_elems_as_doubles | ( | const EPR_SField * | field, | |
| double * | buffer, | |||
| uint | num_elems | |||
| ) |
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Basic Data Access
Modules | |
| Dataset Access | |
| Record Access | |
| Field Access | |
| Field Single Element Access | |
This group of functions is for getting the elements of a field as a typed value. | |
| Field Array Element Access This group of functions is for getting an array of field elements | |
of a certain data type. | |
| Copy Field Elems This group of functions is for copying the data of the given field into the given | |
buffer of elements by selected type. | |
Functions | |
| uint | epr_get_scene_width (const EPR_SProductId *product_id) |
| Gets the product's scene width in pixels. | |
| uint | epr_get_scene_height (const EPR_SProductId *product_id) |
| Gets the product's scene height in pixels. | |
Function Documentation
| uint epr_get_scene_width | ( | const EPR_SProductId * | product_id | ) |
Gets the product's scene width in pixels.
- Parameters:
-
product_id the product identifier, must not be NULL
- Returns:
- the product's total scene width in pixels, or
0if an error occured.
| uint epr_get_scene_height | ( | const EPR_SProductId * | product_id | ) |
Gets the product's scene height in pixels.
- Parameters:
-
product_id the product identifier, must not be NULL
- Returns:
- the product's total scene height in pixels, or
0if an error occured.
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Dataset Access
[Basic Data Access]
Functions | |
| uint | epr_get_num_datasets (EPR_SProductId *product_id) |
| Gets the number off all datasets contained in a product. | |
| EPR_SDatasetId * | epr_get_dataset_id_at (EPR_SProductId *product_id, uint index) |
| Gets the dataset_id at the specified position within the product. | |
| EPR_SDatasetId * | epr_get_dataset_id (EPR_SProductId *product_id, const char *dataset_name) |
| Gets the dataset_id coresponding to the specified dataset name. | |
| const char * | epr_get_dataset_name (EPR_SDatasetId *dataset_id) |
| Gets the name of the dataset for the given dataset ID. | |
| const char * | epr_get_dsd_name (const EPR_SDatasetId *dataset_id) |
| Gets the name of the dsd for the given dataset ID. | |
| EPR_SRecord * | epr_get_mph (const EPR_SProductId *product_id) |
Gets the MPH record from the given product_id. | |
| EPR_SRecord * | epr_get_sph (const EPR_SProductId *product_id) |
Gets the SPH record from the given product_id. | |
| const EPR_SDSD * | epr_get_dsd (const EPR_SDatasetId *dataset_id) |
Gets the dataset descriptor (DSD) for the dataset specified by dataset_id. | |
| uint | epr_get_num_records (const EPR_SDatasetId *dataset_id) |
Gets the number of records of the dataset specified by dataset_id. | |
| uint | epr_get_num_dsds (const EPR_SProductId *product_id) |
| EPR_SDSD * | epr_get_dsd_at (const EPR_SProductId *product_id, uint dsd_index) |
Function Documentation
| uint epr_get_num_datasets | ( | EPR_SProductId * | product_id | ) |
Gets the number off all datasets contained in a product.
- Parameters:
-
product_id the product identifier, must not be NULL
- Returns:
- the number off all dataset
| EPR_SDatasetId* epr_get_dataset_id_at | ( | EPR_SProductId * | product_id, | |
| uint | index | |||
| ) |
Gets the dataset_id at the specified position within the product.
- Parameters:
-
product_id the product identifier, must not be NULLindex the index identifying the position of the dataset, starting with 0, must not be negative
- Returns:
- the requested dataset_id
| EPR_SDatasetId* epr_get_dataset_id | ( | EPR_SProductId * | product_id, | |
| const char * | dataset_name | |||
| ) |
Gets the dataset_id coresponding to the specified dataset name.
- Parameters:
-
product_id the product identifier, must not be NULLdataset_name the dataset name, must not be NULL
- Returns:
- the requested dataset_id
| const char* epr_get_dataset_name | ( | EPR_SDatasetId * | dataset_id | ) |
Gets the name of the dataset for the given dataset ID.
- Parameters:
-
dataset_id the dataset identifier, must not be NULL
- Returns:
- the name of the dataset.
| const char* epr_get_dsd_name | ( | const EPR_SDatasetId * | dataset_id | ) |
Gets the name of the dsd for the given dataset ID.
- Parameters:
-
dataset_id the dataset identifier, must not be NULL
- Returns:
- the name of the dsd.
| EPR_SRecord* epr_get_mph | ( | const EPR_SProductId * | product_id | ) |
Gets the MPH record from the given product_id.
- Parameters:
-
product_id the product identifier, must not be NULL
- Returns:
- the MPH record or
NULLif an error occured.
| EPR_SRecord* epr_get_sph | ( | const EPR_SProductId * | product_id | ) |
Gets the SPH record from the given product_id.
- Parameters:
-
product_id the product identifier, must not be NULL
- Returns:
- the SPH record or
NULLif an error occured.
| const EPR_SDSD* epr_get_dsd | ( | const EPR_SDatasetId * | dataset_id | ) |
Gets the dataset descriptor (DSD) for the dataset specified by dataset_id.
- Parameters:
-
dataset_id the dataset identifier, must not be NULL
- Returns:
- the pointer at the dsd or
NULLif an error occured.
| uint epr_get_num_records | ( | const EPR_SDatasetId * | dataset_id | ) |
Gets the number of records of the dataset specified by dataset_id.
- Parameters:
-
dataset_id the dataset identifier, must not be NULL
- Returns:
- the number of records or
0if an error occured.
| uint epr_get_num_dsds | ( | const EPR_SProductId * | product_id | ) |
| EPR_SDSD* epr_get_dsd_at | ( | const EPR_SProductId * | product_id, | |
| uint | dsd_index | |||
| ) |
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Error Handling
Functions | |
| void | epr_set_err_handler (EPR_FErrHandler err_handler) |
| Sets the error handler for the ENVISAT API. | |
| EPR_EErrCode | epr_get_last_err_code () |
| Gets the error code of the error that occured during the last API function call. | |
| const char * | epr_get_last_err_message () |
| Gets the error message of the error that occured during the last API function call. | |
| void | epr_clear_err () |
| Clears the last error. | |
Function Documentation
| void epr_set_err_handler | ( | EPR_FErrHandler | err_handler | ) |
Sets the error handler for the ENVISAT API.
- Parameters:
-
err_handler the new error handler (function pointer), can be NULL, if errors shall not be reported
| EPR_EErrCode epr_get_last_err_code | ( | ) |
Gets the error code of the error that occured during the last API function call.
- Returns:
- the error code,
e_err_noneor zero if no error occured
| const char* epr_get_last_err_message | ( | ) |
Gets the error message of the error that occured during the last API function call.
- Returns:
- the error message,
NULLif no error occured
| void epr_clear_err | ( | ) |
Clears the last error.
After calling this function, calling epr_get_last_err_code returns e_err_none or zero and epr_get_last_err_message returns NULL.
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Field Access
[Basic Data Access]
Functions | |
| const EPR_SField * | epr_get_field (const EPR_SRecord *record, const char *field_name) |
| Gets a field from the given record. | |
| uint | epr_get_num_fields (const EPR_SRecord *record) |
| Gets the number of fields contained in the given record. | |
| const EPR_SField * | epr_get_field_at (const EPR_SRecord *record, uint field_index) |
| Gets a field at the specified position within the record. | |
| const char * | epr_get_field_unit (const EPR_SField *field) |
| Gets the unit of the field. | |
| const char * | epr_get_field_description (const EPR_SField *field) |
| Gets the description of the field. | |
| uint | epr_get_field_num_elems (const EPR_SField *field) |
| Gets the number of elements of the field. | |
| const char * | epr_get_field_name (const EPR_SField *field) |
| Gets the name of the field. | |
| EPR_EDataTypeId | epr_get_field_type (const EPR_SField *field) |
| Gets the type of the field. | |
Function Documentation
| const EPR_SField* epr_get_field | ( | const EPR_SRecord * | record, | |
| const char * | field_name | |||
| ) |
Gets a field from the given record.
The field is here identified through the given name.
It contains the field info and all corresponding values.
- Parameters:
-
record the record identifier, must not be NULLfield_name the the name of required field, must not be NULL.
- Returns:
- the field or
NULLif an error occured.
| uint epr_get_num_fields | ( | const EPR_SRecord * | record | ) |
Gets the number of fields contained in the given record.
- Parameters:
-
record the record to be analysed, must not be NULL
- Returns:
- the fields number or
0if an error occured.
| const EPR_SField* epr_get_field_at | ( | const EPR_SRecord * | record, | |
| uint | field_index | |||
| ) |
Gets a field at the specified position within the record.
- Parameters:
-
record the record from the field shall be returned, must not be NULLfield_index the zero-based index (position within record) of the field
- Returns:
- the field or
NULLif an error occured.
| const char* epr_get_field_unit | ( | const EPR_SField * | field | ) |
Gets the unit of the field.
- Parameters:
-
field the field from which the unit shall be returned, must not be NULL
- Returns:
- the field unit or
NULLif an error occured.
| const char* epr_get_field_description | ( | const EPR_SField * | field | ) |
Gets the description of the field.
- Parameters:
-
field field from which the description shall be returned, must not be NULL
- Returns:
- the field description or
NULLif an error occured.
| uint epr_get_field_num_elems | ( | const EPR_SField * | field | ) |
Gets the number of elements of the field.
- Parameters:
-
field field to be analysed, must not be NULL
- Returns:
- the number of elements of the field or
0if an error occured.
| const char* epr_get_field_name | ( | const EPR_SField * | field | ) |
Gets the name of the field.
- Parameters:
-
field field to be analysed, must not be NULL
- Returns:
- the field name or
NULLif an error occured.
| EPR_EDataTypeId epr_get_field_type | ( | const EPR_SField * | field | ) |
Gets the type of the field.
- Parameters:
-
field field to be analysed, must not be NULL
- Returns:
- the field type or
0if an error occured.
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Field Array Element Access This group of functions is for getting an array of field elements
[Basic Data Access]
of a certain data type. More...
Functions | |
| const char * | epr_get_field_elems_char (const EPR_SField *field) |
| const uchar * | epr_get_field_elems_uchar (const EPR_SField *field) |
| const short * | epr_get_field_elems_short (const EPR_SField *field) |
| const ushort * | epr_get_field_elems_ushort (const EPR_SField *field) |
| const int * | epr_get_field_elems_int (const EPR_SField *field) |
| const uint * | epr_get_field_elems_uint (const EPR_SField *field) |
| const float * | epr_get_field_elems_float (const EPR_SField *field) |
| const double * | epr_get_field_elems_double (const EPR_SField *field) |
Detailed Description
of a certain data type.
If the given field is not of the expected type, the functions return NULL.
- Parameters:
-
field the field, must not be NULL
- Returns:
- the data array of the expected type or
NULLif the field is of a different type
Function Documentation
| const char* epr_get_field_elems_char | ( | const EPR_SField * | field | ) |
| const uchar* epr_get_field_elems_uchar | ( | const EPR_SField * | field | ) |
| const short* epr_get_field_elems_short | ( | const EPR_SField * | field | ) |
| const ushort* epr_get_field_elems_ushort | ( | const EPR_SField * | field | ) |
| const int* epr_get_field_elems_int | ( | const EPR_SField * | field | ) |
| const uint* epr_get_field_elems_uint | ( | const EPR_SField * | field | ) |
| const float* epr_get_field_elems_float | ( | const EPR_SField * | field | ) |
| const double* epr_get_field_elems_double | ( | const EPR_SField * | field | ) |
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Field Single Element Access
[Basic Data Access]
This group of functions is for getting the elements of a field as a typed value. More...
Functions | |
| char | epr_get_field_elem_as_char (const EPR_SField *field, uint elem_index) |
| uchar | epr_get_field_elem_as_uchar (const EPR_SField *field, uint elem_index) |
| short | epr_get_field_elem_as_short (const EPR_SField *field, uint elem_index) |
| ushort | epr_get_field_elem_as_ushort (const EPR_SField *field, uint elem_index) |
| int | epr_get_field_elem_as_int (const EPR_SField *field, uint elem_index) |
| uint | epr_get_field_elem_as_uint (const EPR_SField *field, uint elem_index) |
| float | epr_get_field_elem_as_float (const EPR_SField *field, uint elem_index) |
| double | epr_get_field_elem_as_double (const EPR_SField *field, uint elem_index) |
| const EPR_STime * | epr_get_field_elem_as_mjd (const EPR_SField *field) |
| const char * | epr_get_field_elem_as_str (const EPR_SField *field) |
Detailed Description
This group of functions is for getting the elements of a field as a typed value.
Typed value means that the returned variable is of a certain variable type, e.g. such as short or float.
The type is located in the field info. See epr_get_field_type.
One field must have one type only.
- Parameters:
-
field the field, must not be NULLelem_index the zero-based index of element to be returned, must not be negative.
- Returns:
- the typed value from given field
Function Documentation
| char epr_get_field_elem_as_char | ( | const EPR_SField * | field, | |
| uint | elem_index | |||
| ) |
| uchar epr_get_field_elem_as_uchar | ( | const EPR_SField * | field, | |
| uint | elem_index | |||
| ) |
| short epr_get_field_elem_as_short | ( | const EPR_SField * | field, | |
| uint | elem_index | |||
| ) |
| ushort epr_get_field_elem_as_ushort | ( | const EPR_SField * | field, | |
| uint | elem_index | |||
| ) |
| int epr_get_field_elem_as_int | ( | const EPR_SField * | field, | |
| uint | elem_index | |||
| ) |
| uint epr_get_field_elem_as_uint | ( | const EPR_SField * | field, | |
| uint | elem_index | |||
| ) |
| float epr_get_field_elem_as_float | ( | const EPR_SField * | field, | |
| uint | elem_index | |||
| ) |
| double epr_get_field_elem_as_double | ( | const EPR_SField * | field, | |
| uint | elem_index | |||
| ) |
| const EPR_STime* epr_get_field_elem_as_mjd | ( | const EPR_SField * | field | ) |
| const char* epr_get_field_elem_as_str | ( | const EPR_SField * | field | ) |
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Geopysical Data Access
Modules | |
| Raster Data Access | |
| Single Pixel Access | |
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
API Initialisation
Functions | |
| int | epr_init_api (EPR_ELogLevel log_level, EPR_FLogHandler log_handler, EPR_FErrHandler err_handler) |
| Initializes the ENVISAT product reader API. | |
| void | epr_close_api () |
| Closes the ENVISAT product reader API by releasing all resources allocated by the API. | |
Function Documentation
| int epr_init_api | ( | EPR_ELogLevel | log_level, | |
| EPR_FLogHandler | log_handler, | |||
| EPR_FErrHandler | err_handler | |||
| ) |
Initializes the ENVISAT product reader API.
- Parameters:
-
log_level the log level. All logging messages with a log level lower than the given one, will be supressed log_handler the log handler function pointer which will be used for logging, can be NULL, if logging shall be disablederr_handler the new error handler (function pointer), can be NULL, if errors shall not be reported
- Returns:
- zero for success, an error code otherwise
| void epr_close_api | ( | ) |
Closes the ENVISAT product reader API by releasing all resources allocated by the API.
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Input / Output
Modules | |
| Product IO | |
| Writing to a file or standard output | |
This group of functions is for writing an object to a file or standard output. | |
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Logging
Functions | |
| int | epr_set_log_level (EPR_ELogLevel log_level) |
| Sets the log level for the ENVISAT API. | |
| void | epr_set_log_handler (EPR_FLogHandler log_handler) |
| Sets the log handler for the ENVISAT API. | |
| void | epr_log_message (EPR_ELogLevel log_level, const char *log_message) |
A default implementation for a logging function to be passed into the epr_init() function. | |
Function Documentation
| int epr_set_log_level | ( | EPR_ELogLevel | log_level | ) |
Sets the log level for the ENVISAT API.
All logging messages with a log level lower than the given one, will be supressed, thus the log handler will not be called for such messages.
- Parameters:
-
log_level the new log level. All logging messages with a log level lower than the given one, will be supressed
- Returns:
- zero for success, an error code otherwise
| void epr_set_log_handler | ( | EPR_FLogHandler | log_handler | ) |
Sets the log handler for the ENVISAT API.
- Parameters:
-
log_handler the log handler function pointer which will be used for logging, can be NULL, if logging shall be disabled
- See also:
- epr_log_message
| void epr_log_message | ( | EPR_ELogLevel | log_level, | |
| const char * | log_message | |||
| ) |
A default implementation for a logging function to be passed into the epr_init() function.
The function writes to stdout, the format is: log_level date time log_message.
- Parameters:
-
log_level the log level log_message the log message
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Product IO
[Input / Output]
Functions | |
| EPR_SProductId * | epr_open_product (const char *product_file_path) |
| 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; returns a file identifier for the product. | |
| int | epr_close_product (EPR_SProductId *product_id) |
| Closes the ENVISAT product file determined by the given product identifier. | |
Function Documentation
| EPR_SProductId* epr_open_product | ( | const char * | product_file_path | ) |
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;
returns a file identifier for the product.
The ENVISAT product reader API must be initialized before.
- Parameters:
-
product_file_path the path to the ENVISAT product file
- Returns:
- the product identifier, or
NULLif the file could not be opened.epr_get_error_code()should be called in this case in order to obtain the error code.
| int epr_close_product | ( | EPR_SProductId * | product_id | ) |
Closes the ENVISAT product file determined by the given product identifier.
- Parameters:
-
product_id the product identifier, if NULLthe function immediately returns zero.
- Returns:
- zero for success, an error code otherwise
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Raster Data Access
[Geopysical Data Access]
Functions | |
| EPR_SRaster * | epr_create_compatible_raster (EPR_SBandId *band_id, uint source_width, uint source_height, uint source_step_x, uint source_step_y) |
| Creates a raster which is compatible with the data type contained in the band identified by band_id. | |
| EPR_SRaster * | epr_create_raster (EPR_EDataTypeId data_type, uint source_width, uint source_height, uint source_step_x, uint source_step_y) |
| Creates a raster of the specified data type. | |
| EPR_SRaster * | epr_create_bitmask_raster (uint source_width, uint source_height, uint source_step_x, uint source_step_y) |
| Creates a raster to be used for reading bitmasks. | |
| int | epr_read_band_raster (EPR_SBandId *band_id, int offset_x, int offset_y, EPR_SRaster *raster) |
| Reads (geo-)physical values of the given band of the specified source-region. | |
| uint | epr_get_raster_elem_size (const EPR_SRaster *raster) |
| void * | epr_get_raster_elem_addr (const EPR_SRaster *raster, uint offset) |
| void * | epr_get_raster_pixel_addr (const EPR_SRaster *raster, uint x, uint y) |
| void * | epr_get_raster_line_addr (const EPR_SRaster *raster, uint y) |
| uint | epr_get_raster_width (EPR_SRaster *raster) |
| Gets the raster's scene width in pixels. | |
| uint | epr_get_raster_height (EPR_SRaster *raster) |
| Gets the raster's scene height in pixels. | |
| uint | epr_get_num_bands (EPR_SProductId *product_id) |
| Gets the number of all bands contained in a product. | |
| EPR_SBandId * | epr_get_band_id_at (EPR_SProductId *product_id, uint index) |
| Gets the band ID at the specified position within the product. | |
| EPR_SBandId * | epr_get_band_id (EPR_SProductId *product_id, const char *band_name) |
| Gets the band ID corresponding to the specified name. | |
| const char * | epr_get_band_name (EPR_SBandId *band_id) |
| Gets the name of the band for the given band ID. | |
| void | epr_free_raster (EPR_SRaster *raster) |
| Release the memory allocated through a raster. | |
Function Documentation
| EPR_SRaster* epr_create_compatible_raster | ( | EPR_SBandId * | band_id, | |
| uint | source_width, | |||
| uint | source_height, | |||
| uint | source_step_x, | |||
| uint | source_step_y | |||
| ) |
Creates a raster which is compatible with the data type contained in the band identified by band_id.
The created raster is used to read the data in it (see epr_read_band_raster).
The raster is defined on the grid of the product, from which the data are read. Spatial subsets and undersampling are possible) through the parameter of the function.
The concept of defining the raster is such: A certain portion of the ENVISAT product will be read into the raster. This 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 parameter source_height and source_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 subsampling 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:
-
band_id the band identifier. The raster will be compatible with the data type of that band; must not be NULLsource_width the width (across track dimension) of the source to be read into the raster. See text above. source_height the height (along track dimension) of the source to be read into the raster. See text above. source_step_x the subsampling step across track of the source when reading into the raster. See text above. source_step_y the subsampling step along track of the source when reading into the raster. See text above.
- Returns:
- the new raster instance or
NULLif an error occured.
| EPR_SRaster* epr_create_raster | ( | EPR_EDataTypeId | data_type, | |
| uint | source_width, | |||
| uint | source_height, | |||
| uint | source_step_x, | |||
| uint | source_step_y | |||
| ) |
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 not be NULLsource_width the width (across track dimension) of the source to be read into the raster. See description of epr_create_compatible_raster. source_height the height (along track dimension) of the source to be read into the raster. See description of epr_create_compatible_raster. source_step_x the subsampling step across track of the source when reading into the raster. See description of epr_create_compatible_raster. source_step_y the subsampling step along track of the source when reading into the raster. See description of epr_create_compatible_raster.
- Returns:
- the new raster instance or
NULLif an error occured.
| EPR_SRaster* epr_create_bitmask_raster | ( | uint | source_width, | |
| uint | source_height, | |||
| uint | source_step_x, | |||
| uint | source_step_y | |||
| ) |
Creates a raster to be used for reading bitmasks.
The raster returned always is of type byte.
- Parameters:
-
source_width the width (across track dimension) of the source to be read into the raster. See description of epr_create_compatible_raster. source_height the height (along track dimension) of the source to be read into the raster. See description of epr_create_compatible_raster. source_step_x the subsampling step across track of the source when reading into the raster. See description of epr_create_compatible_raster. source_step_y the subsampling step along track of the source when reading into the raster. See description of epr_create_compatible_raster.
- Returns:
- the new raster instance or
NULLif an error occured.
| int epr_read_band_raster | ( | EPR_SBandId * | band_id, | |
| int | offset_x, | |||
| int | offset_y, | |||
| EPR_SRaster * | raster | |||
| ) |
Reads (geo-)physical values of the given 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:
-
band_id the identified of the band to be read into the raster. offset_x across-track source co-ordinate in pixel co-ordinates (zero-based) of the upper right corner of the source-region offset_y along-track source co-ordinate in pixel co-ordinates (zero-based) of the upper right corner of the source-region raster the identifier to given raster information and raster buffer
- Returns:
- zero for success, and error code otherwise
- See also:
- epr_create_compatible_raster
- epr_create_rater
| uint epr_get_raster_elem_size | ( | const EPR_SRaster * | raster | ) |
| void* epr_get_raster_elem_addr | ( | const EPR_SRaster * | raster, | |
| uint | offset | |||
| ) |
| void* epr_get_raster_pixel_addr | ( | const EPR_SRaster * | raster, | |
| uint | x, | |||
| uint | y | |||
| ) |
| void* epr_get_raster_line_addr | ( | const EPR_SRaster * | raster, | |
| uint | y | |||
| ) |
| uint epr_get_raster_width | ( | EPR_SRaster * | raster | ) |
Gets the raster's scene width in pixels.
- Parameters:
-
raster the raster identifier, must not be NULL
- Returns:
- the raster's total scene width in pixels, or
0if an error occured.
| uint epr_get_raster_height | ( | EPR_SRaster * | raster | ) |
Gets the raster's scene height in pixels.
- Parameters:
-
raster the product identifier, must not be NULL
- Returns:
- the raster's total scene height in pixels, or
0if an error occured.
| uint epr_get_num_bands | ( | EPR_SProductId * | product_id | ) |
Gets the number of all bands contained in a product.
- Parameters:
-
product_id the source product ID, must not be NULL
- Returns:
- the number off all bands
| EPR_SBandId* epr_get_band_id_at | ( | EPR_SProductId * | product_id, | |
| uint | index | |||
| ) |
Gets the band ID at the specified position within the product.
- Parameters:
-
product_id the source product ID, must not be NULLindex the index identifying the position of the band, starting with 0, must not be negative
- Returns:
- the requested band ID, or
NULLif not found
| EPR_SBandId* epr_get_band_id | ( | EPR_SProductId * | product_id, | |
| const char * | band_name | |||
| ) |
Gets the band ID corresponding to the specified name.
- Parameters:
-
product_id the source product ID, must not be NULLband_name the name of the band, must not be NULL
- Returns:
- the requested band ID, or
NULLif not found
| const char* epr_get_band_name | ( | EPR_SBandId * | band_id | ) |
Gets the name of the band for the given band ID.
- Parameters:
-
band_id the band identifier, must not be NULL
- Returns:
- the name of the band.
| void epr_free_raster | ( | EPR_SRaster * | raster | ) |
Release the memory allocated through a raster.
- Parameters:
-
raster the raster to be released.
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Record Access
[Basic Data Access]
Functions | |
| EPR_SRecord * | epr_create_record (EPR_SDatasetId *dataset_id) |
| Creates a new, empty record with a structure compatible with the dataset specified by dataset_id. | |
| EPR_SRecord * | epr_read_record (EPR_SDatasetId *dataset_id, uint record_index, EPR_SRecord *record) |
| Reads a record of a dataset specified by dataset_id. | |
| void | epr_free_record (EPR_SRecord *record) |
| Frees the memory allocated through the given record. | |
Function Documentation
| EPR_SRecord* epr_create_record | ( | EPR_SDatasetId * | dataset_id | ) |
Creates a new, empty record with a structure compatible with the dataset specified by dataset_id.
Such a record is typically used in subsequent calls to epr_read_record.
- Parameters:
-
dataset_id the dataset identifier, must not be NULL
- Returns:
- the new record instance or
NULLif an error occured.
| EPR_SRecord* epr_read_record | ( | EPR_SDatasetId * | dataset_id, | |
| uint | record_index, | |||
| EPR_SRecord * | record | |||
| ) |
Reads a record of a dataset specified by dataset_id.
The record is identified through the given dataset identifier and the given zero-based record index. In order to reduce memory reallocation, a record (pre-) created by the function epr_create_record can be passed to this function. Data is then read into this given record. If no record (NULL) is given, the function initiates a new one. In both cases, the record in which the data is read into will be returned.
- Parameters:
-
dataset_id the dataset identifier, must not be NULLrecord_index the zero-based record index record a pre-created record to reduce memory reallocation, can be NULLto let the function allocate a new record
- Returns:
- the record in which the data has been read into or
NULLif an error occured.
| void epr_free_record | ( | EPR_SRecord * | record | ) |
Frees the memory allocated through the given record.
After calling this function the given record pointer becomes invalid and should not be used anymore.
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Single Pixel Access
[Geopysical Data Access]
Functions | |
| uint | epr_get_pixel_as_uint (const EPR_SRaster *raster, int x, int y) |
| This group of functions is for getting the values of the elements of a raster (i.e. | |
| int | epr_get_pixel_as_int (const EPR_SRaster *raster, int x, int y) |
| float | epr_get_pixel_as_float (const EPR_SRaster *raster, int x, int y) |
| double | epr_get_pixel_as_double (const EPR_SRaster *raster, int x, int y) |
Function Documentation
| uint epr_get_pixel_as_uint | ( | const EPR_SRaster * | raster, | |
| int | x, | |||
| int | y | |||
| ) |
This group of functions is for getting the values of the elements of a raster (i.e.
pixel) in a type-safe way.
- Parameters:
-
raster the raster which contains the pixel, must not be NULLx the (zero-based) X co-ordinate of the pixel y the (zero-based) Y co-ordinate of the pixel
- Returns:
- the typed value at the given co-ordinate.
| int epr_get_pixel_as_int | ( | const EPR_SRaster * | raster, | |
| int | x, | |||
| int | y | |||
| ) |
| float epr_get_pixel_as_float | ( | const EPR_SRaster * | raster, | |
| int | x, | |||
| int | y | |||
| ) |
| double epr_get_pixel_as_double | ( | const EPR_SRaster * | raster, | |
| int | x, | |||
| int | y | |||
| ) |
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Utility Functions
Functions | |
| uint | epr_get_data_type_size (EPR_EDataTypeId data_type_id) |
| Gets the size in bytes for an element of the given data type. | |
| const char * | epr_data_type_id_to_str (EPR_EDataTypeId data_type_id) |
| Gets the 'C' data type string for the given data type. | |
Function Documentation
| uint epr_get_data_type_size | ( | EPR_EDataTypeId | data_type_id | ) |
Gets the size in bytes for an element of the given data type.
| const char* epr_data_type_id_to_str | ( | EPR_EDataTypeId | data_type_id | ) |
Gets the 'C' data type string for the given data type.
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Writing to a file or standard output
[Input / Output]
This group of functions is for writing an object to a file or standard output. More...
Functions | |
| void | epr_print_record (const EPR_SRecord *record, FILE *ostream) |
| void | epr_print_field (const EPR_SField *field, FILE *ostream) |
| void | epr_print_element (const EPR_SRecord *record, uint field_index, uint element_index, FILE *ostream) |
| void | epr_dump_record (const EPR_SRecord *record) |
| void | epr_dump_field (const EPR_SField *field) |
| void | epr_dump_element (const EPR_SRecord *record, uint field_index, uint element_index) |
Detailed Description
This group of functions is for writing an object to a file or standard output.
An object can be:
- record
- field
- field element
If FILE* istream is given, the ASCII file will be outputed, else printed to standard output device.
In case record and/or field:
- Parameters:
-
record the record, must not be NULLfield the field, must not be NULL
In case field element:
- Parameters:
-
record the record, must not be NULLfield_index the index of field in the given record element_index the index of element in the given field ostream the identifier of the output file.
Function Documentation
| void epr_print_record | ( | const EPR_SRecord * | record, | |
| FILE * | ostream | |||
| ) |
| void epr_print_field | ( | const EPR_SField * | field, | |
| FILE * | ostream | |||
| ) |
| void epr_print_element | ( | const EPR_SRecord * | record, | |
| uint | field_index, | |||
| uint | element_index, | |||
| FILE * | ostream | |||
| ) |
| void epr_dump_record | ( | const EPR_SRecord * | record | ) |
| void epr_dump_field | ( | const EPR_SField * | field | ) |
| void epr_dump_element | ( | const EPR_SRecord * | record, | |
| uint | field_index, | |||
| uint | element_index | |||
| ) |
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
ENVISAT Product Reader C API Documentation
2.2
1. Introduction
The ENVISAT Product Reader API for C (epr-c-api) is a library of data
structures and functions for simple access to MERIS, AATSR and ASAR products. You can use
them in your programs to retrieve directly the geophysically coded values, e.g.
such as the chlorophyll concentration in mg/m³, in a data matrix.
The epr-c-api is generic, i.e. it has no instrument specific functions
but utilises the generic ENVISAT product format. However, it is not necessary for a user of the
epr-c-api to know the ENVISAT product format - the
epr-c-api knows it, and that's sufficient.
All a user of the epr-c-api has to know are a few functions and the name
of the geophysical variable he wants to get. In fact, the epr-c-api can
do more: all information stored in ENVISAT products can be retrieved in a unique way, just by
requesting it identified by its name, without worrying too much where and how it is stored in the
world of the ENVISAT product format.
Now, here's the tricky bit: there are many different products and the number of items stored in each product is huge. Therefore a ENVISAT Data Products documentation is included in the BEAM software homepage, which describes the internal structure of each supported product. In order to access a certain item such as a dataset, record, band or flag you have to consult the data product documentation for he correct name or ID for the dataset, record, band or flag you want to access.
2. Using the API in your own C-Programs
The epr-c-api is written in pure ANSI C and should compile with
every ANSI conformant C-compiler:
- Copy all
*.h*.cfiles contained in the distribution'ssrcfolder to your own source folder of your project and include them in your development environment (makefile or IDE). - Include the public API header
epr-api.hin your C source files. - Optionally refer to the example code in
src/examplesdirectory
3. API Design
3.1 Basic Concepts
Given here are some of the basic concepts of the API.
- The API works exclusively with pointers to dynamically allocated structures.
For every structure type in the API a constructor/desctructor function pair always exists:
X epr_create_X(...)andvoid epr_free_X(X). Example: For the typeEPR_SRecord*these functions areEPR_SRecord* epr_create_record(...)andvoid epr_free_record(EPR_SRecord*). -
In most cases, the first parameter is the object on which the function is operating.
For example,
uint epr_get_num_fields(const EPR_SRecord* record). - Access functions exist for all important members of structures. So, the
user of the API should not need to work directly with the API structures but
with functions to get values. For example, if you use the
epr_get_pixel_as_floatto access a pixel value of raster, your code is less dependent on API changes as if you would have directly accessed a structure member. - A central concept is that all items, which can be retrieved from ENVISAT
products, are identified by name. For example, to access the MERIS L1B radiance
of band 1, you have to call
epr_get_dataset_id(product_id, "Radiance_1")But how do you know, what name you should use for the data you want to retrieve? There are three possibilities:- The ENVISAT Data Products documentation provides all valid names used in the all supported data products. All tables in the documentation have a similar structure, the first column is always contains the longed-for name.
- One can use VISAT to open a product. The names shown in VISAT in the product browser are the same as in the ENVISAT data product tables documentation and are hence those needed.
-
One can open a product using the
epr-c-api, scan all datasets in a look and print the names of the datasets and records by the access function. The same can be done with all fields of a record.
3.2 Data Access Types
The API provides two access types for ENVISAT data:
- Access of data as it is stored in the product (we call this basic or raw data access) and
- Access to the geophysical raster data (what we call this geophysical data access).
The difference between the two is how they treat the measurement data: Access type (1) returns the data in its native data product structure: as datasets, records and fields. This gives a direct read access to the raw data as it is stored in the data product, without any interpretation of the content. For example, the MERIS L1B measurement data set MDS 15 stores chlorophyll, vegetation index or cloud top height in the same byte. The content has to be interpreted depending on the surface type, which itself is coded in MDS 20. To get the true geophysical value one needs to retrieve the proper scaling factors from a certain GADS. Access type (2) decodes all this and provides, for example, a data matrix with the chlorophyll concentration in a float variable in its geophysical units, i.e. mg/m³. The data of the measurement datasets and the tie-point values, i.e. geometry, geo-location and meteorological data, are available by this method. The tie-point data are interpolated to the corresponding image grid.
3.3 Working with the Basic/Raw Data Access
| Level | Correspondence in ENVISAT product |
| Product | ENVISAT product file |
| Dataset | Dataset, e.g. Main Product Header MPH, or a Measurement Data Set MDS. A dataset contains records. For example, the MERIS L1b MDS1 contains many records with radiance values. |
| Record | A single record within a dataset. A record contains many fields. For example, a record within the MERIS L1b MDS1 contains a time-stamp field, a quality flag field and then a field with as many radiance values as contained in the width of the image. |
| Field | A field within a record. Fields can be a scalar or a vector. In the example, the time stamp and quality flag are scalars while the radiance field is a vector of the length of an image line. |
| Element | Optional. If a field is a vector, these are the elements of that vector. In the example each element of the radiance field is the radiance of a certain pixel. |
On each level of the hierarchy, functions exist to point to a certain instance of it, e.g. a certain product, dataset or record and so on. That function generally requires the name of the item to be retrieved. All possible names can be found in the DDDB , and the name of the most important items are listed here. The function returns an identifier of that instance. The identifier is not the instance but a pointer to it. It is used to get the values of the instance by using access functions.
For example,
my_product_id = epr_open_product("my_MERIS_product");
returns the identifier to the my_product_id
which points to the product contained in the file "my_MERIS_product".
rad1_id = epr_get_dataset_id(my_product_id, "Radiance_1");
This my_product_id is used
get the identifier rad1_id
which points to the Radiance_1
dataset. Now, one can call
num_rec = epr_get_num_records(rad1_id);
to get the number of records which this dataset contains. Finally one can loop over all records and gets its fields and elements. See the examples to get a complete code example.
3.4 Working with Geophysical Data Access
To work with geophysical data is easier than the basic access. No such deep hierarchy exists. Instead of accessing datasets, so called bands will be accessed. A band directly includes one single geophysical variable.
For example,
my_product_id = epr_open_product(my_product_file_path);
my_chl_id = epr_create_band_id(my_product_id, "algal_1");
returns the identifier to a band containing the chlorophyll product. Now, the actual data are read into a raster.
chl_raster = epr_create_compatible_raster(my_chl_id, ...);
status = epr_read_band_raster(chl_raster, ...);
The raster
chl_raster now contains the data as two dimensional
matrix of pixel. To get the value of a pixel at a certain index
(i,j), one should use the access function:
chl_pixel = epr_get_pixel_as_float(chl_raster, i, j);
(See also the examples ndvi.c for complete example codes.)
The concept of the raster allows spatial subsets and undersampling: A certain portion of the ENVISAT product will be read into the raster. This 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.
A typical example is a processing in blocks. Lets say, a block has 64x32 pixel. Then, the source has a width of 64 pixel and a height of 32 pixel. Another example is a processing of complete image lines. Then, the 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 or image lines, read into the raster and process it. It is, of course, also possible to define a raster of the size of the complete product.
In addition, it is possible to define a subsampling 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 and along track directions.
3.5 Bit masks
MERIS and AATSR provide many so called flags, which are binary information
indicating a certain state of a pixel. For example, this can be a quality indicator,
which, if set, indicates that the value of the pixel is invalid. Other example
are a cloud flag, indicating that this pixel is a measurement above a cloud,
or a coastline flag. The flags are stored in a packed format inside the ENVISAT
products, but the epr-c-api provides a function to easily
access the flags.
It returns a bit-mask, which is a byte array that matches the corresponding
image raster and is 1 where the flag is set and 0 elsewhere. Even more, this
functions permits to formulate a bit-mask expression to combine any number of
flags in a logical expression and returns the resulting combined bit-mask:
bm_expr = "flags.LAND OR flags.CLOUD";
status = epr_read_bitmask_raster(product_id, bm_expr, ..., bm_raster);
This is an example to get a bit-mask which masks out all land and cloud pixels.
The names of the flags are found in the
DDDB.
The epr_read_bitmask_raster function read from product,
identified by product_id, the flags and stores the resulting
bit-mask in the raster bm_raster.
See the examples for the complete code.
4. API Function Group Index
The epr-c-api provides the following group of functions:
| (1) | Initialisation | Functions for setting up the environment of the API and releasing memory when the API is closed. |
| (2) | Logging | Functions to manage logging information |
| (3) | Error handling | Functions for determining the behaviour of the API in case of errors, and of getting information about runtime errors |
| (4) | Input / Output | Opening and closing ENVISAT products and writing data to a file or stdout. |
| (5) | Basic data access | Functions to retrieve raw data as stored in ENVISAT products |
| (6) | Geophysical data access | Functions to retrieve geophysically interpreted data in a raster matrix |
| (7) | Bit masks | Functions for generating bit masks from the flags included in ENVISAT products. |
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
Modules
Here is a list of all modules:Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
EPR_BandId Struct Reference
The EPR_BandId structure contains information about a band within an ENVISAT product file which has been opened with the epr_open_product() API function.
More...
#include <epr_api.h>
Data Fields | |
| EPR_Magic | magic |
| The magic number for this structure. | |
| EPR_SProductId * | product_id |
| The ID of the product to which this band belongs to. | |
| char * | band_name |
| The name as presented to the user in a band selection dialog (also known as spectral subset). | |
| int | spectr_band_index |
| The (zero-based) spectral band index. | |
| EPR_SDatasetRef | dataset_ref |
| The reference of the source dataset containing the raw data used to create the band's pixel values. | |
| EPR_ESampleModel | sample_model |
| The sample model operation applied to the source dataset for getting the correct samples from the MDS (for example MERIS L2). | |
| EPR_EDataTypeId | data_type |
| The data type of the band's pixel values. | |
| EPR_EScalingMethod | 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. | |
| float | scaling_offset |
| The scaling offset. | |
| float | scaling_factor |
| The scaling factor. | |
| char * | bm_expr |
| A bit-mask expression used to filter valid pixels. | |
| EPR_SPtrArray * | flag_coding |
| The flag coding is a list of EPR_SFlag instances. | |
| char * | unit |
| The geophysical unit for the band's pixel values. | |
| char * | description |
| A short description of the band's contents. | |
| epr_boolean | lines_mirrored |
| 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. | |
Detailed Description
The EPR_BandId structure contains information about a band within an ENVISAT product file which has been opened with the epr_open_product() API function.
A new EPR_BandId instance can be obtained with the epr_get_band_id() API function.
- See also:
- epr_open_product
- epr_get_band_id
Field Documentation
The magic number for this structure.
IMPORTANT: This must always be the first member of this structure.
The ID of the product to which this band belongs to.
| char* EPR_BandId::band_name |
The name as presented to the user in a band selection dialog (also known as spectral subset).
The (zero-based) spectral band index.
-1 if this is not a spectral band.
The reference of the source dataset containing the raw data used to create the band's pixel values.
The external format used in the DDDB is MDS-name.field, where field is a one-based index (field=1 corresponds to the first field)
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
The data type of the band's pixel values.
Possible values are:
*--> the datatype remains unchanged.uint8_t--> 8-bit unsigned integeruint32_t--> 32-bit unsigned integerFloat--> 32-bit IEEE floating point
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 * xLog_Scale--> logarithmic scaling applied: y = log10(offset + scale * x)
The scaling offset.
Possible values are:
*--> no offset provided (implies scaling_method=*)const--> a floating point constantGADS.field[.field2]--> value is provided in global annotation dataset with nameGADSin fieldfield. Optionally a second element index for multiple-element fields can be given too
The scaling factor.
Possible values are:
*--> no factor provided (implies scaling_method=*)const--> a floating point constantGADS.field[.field2]--> value is provided in global annotation dataset with nameGADSin fieldfield. Optionally a second element index for multiple-element fields can be given too
| char* EPR_BandId::bm_expr |
A bit-mask expression used to filter valid pixels.
All others are set to zero.
| EPR_SPtrArray* EPR_BandId::flag_coding |
The flag coding is a list of EPR_SFlag instances.
It determines each of the flags used in this band (= flags dataset). Each flag has a name, a bit-index and a description.
| char* EPR_BandId::unit |
The geophysical unit for the band's pixel values.
| char* EPR_BandId::description |
A short description of the band's contents.
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 documentation for this struct was generated from the following file:
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
EPR_DSD Struct Reference
The EPR_DSD structure contains information about the propertier of a dataset properties and its location within an ENVISAT product file.
More...
#include <epr_api.h>
Data Fields | |
| EPR_Magic | magic |
| The magic number for this structure. | |
| int | index |
| The index of this DSD (zero-based). | |
| char * | ds_name |
| The dataset name. | |
| char * | ds_type |
| The dataset type descriptor. | |
| char * | filename |
| The filename in the DDDB with the description of this dataset. | |
| uint | ds_offset |
| The offset of dataset-information the product file. | |
| uint | ds_size |
| The size of dataset-information in dataset product file. | |
| uint | num_dsr |
| The number of dataset records for the given dataset name. | |
| uint | dsr_size |
| The size of dataset record for the given dataset name. | |
Detailed Description
The EPR_DSD structure contains information about the propertier of a dataset properties and its location within an ENVISAT product file.
- See also:
- epr_read_each_dsd
Field Documentation
The magic number for this structure.
IMPORTANT: This must always be the first member of this structure.
| int EPR_DSD::index |
The index of this DSD (zero-based).
| char* EPR_DSD::ds_name |
The dataset name.
| char* EPR_DSD::ds_type |
The dataset type descriptor.
| char* EPR_DSD::filename |
The filename in the DDDB with the description of this dataset.
The offset of dataset-information the product file.
The size of dataset-information in dataset product file.
The number of dataset records for the given dataset name.
The size of dataset record for the given dataset name.
The documentation for this struct was generated from the following file:
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
EPR_DatasetId Struct Reference
The EPR_DatasetId structure contains information about a dataset within an ENVISAT product file which has been opened with the epr_open_product() API function.
More...
#include <epr_api.h>
Data Fields | |
| EPR_Magic | magic |
| The magic number for this structure. | |
| EPR_SProductId * | product_id |
| The ID of the product to which this dataset belongs to. | |
| char * | dsd_name |
| The name as presented to the user in a dsd selection dialog. | |
| const EPR_SDSD * | dsd |
| The dataset descriptor obtained from the current product. | |
| char * | dataset_name |
| The name as presented to the user in a dataset selection dialog. | |
| struct RecordDescriptor * | record_descriptor |
| The record descriptor found in the DDDB for this dataset. | |
| EPR_SRecordInfo * | record_info |
| The record info which describes a record of this dataset. | |
| char * | description |
| A short description of the band's contents. | |
Detailed Description
The EPR_DatasetId structure contains information about a dataset within an ENVISAT product file which has been opened with the epr_open_product() API function.
A new EPR_DatasetId instance can be obtained with the epr_get_dataset_id() or epr_get_dataset_id_at() API functions.
Field Documentation
The magic number for this structure.
IMPORTANT: This must always be the first member of this structure.
The ID of the product to which this dataset belongs to.
| char* EPR_DatasetId::dsd_name |
The name as presented to the user in a dsd selection dialog.
| const EPR_SDSD* EPR_DatasetId::dsd |
The dataset descriptor obtained from the current product.
The name as presented to the user in a dataset selection dialog.
| struct RecordDescriptor* EPR_DatasetId::record_descriptor |
The record descriptor found in the DDDB for this dataset.
The record info which describes a record of this dataset.
A short description of the band's contents.
The documentation for this struct was generated from the following file:
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
EPR_DatasetRef Struct Reference
The EPR_DatasetRef structure represents the information from dddb
with the reference to data name (in dddb), field-name and index of the element in field-array, in which (by name) searchable values are located.
More...
#include <epr_api.h>
Data Fields | |
| EPR_SDatasetId * | dataset_id |
| int | field_index |
| int | elem_index |
Detailed Description
The EPR_DatasetRef structure represents the information from dddb
with the reference to data name (in dddb), field-name and index of the element in field-array, in which (by name) searchable values are located.
Example for the search for a scaling_offset information: This information for the reflec_10 is described with the Scaling_Factor_GADS.22.10 In dataset_id the searched ENVISAT product name (e.g. MER_RR__2P) is located.
In the corresponding file (e.g. /product/MER_RR__2P.dd) the path, how to find that information will be decribed. In that file, in the field number 22 there is an information about the location of the searched value in the ENVISAT product data.
- See also:
- EPR_SDatasetId
Field Documentation
The documentation for this struct was generated from the following file:
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
EPR_Field Struct Reference
Represents a field within a record. More...
#include <epr_api.h>
Data Fields | |
| EPR_Magic | magic |
| The magic number for this structure. | |
| EPR_SFieldInfo * | info |
| The corresponding field info for this field. | |
| void * | elems |
| The elements of this field. | |
Detailed Description
Represents a field within a record.
A field is composed of one or more data elements of one of the types defined in the in field_info.
- See also:
- EPR_Record
Field Documentation
The magic number for this structure.
IMPORTANT: This must always be the first member of this structure.
The corresponding field info for this field.
supplierCardinality 1
| void* EPR_Field::elems |
The elements of this field.
In order to use the data, this member must be casted to one of the following array data types:
unsigned char*- array of unsigned 8-bit integer elementschar*- array of signed 8-bit integer fieldsunsigned short*- array of unsigned 16-bit integer elementsshort*- array of signed 16-bit integer elementsunsigned int*- array of unsigned 32-bit integer elementsint*- array of signed 32-bit integer elementsfloat*- array of signed 32-bit floating point elementsdouble*- array of signed 64-bit floating point elementsEPR_STime*- array of MJD elements
Dedicated access routine are available The element type is given by info->data_type_id and the array length by info->num_elems.
The documentation for this struct was generated from the following file:
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
EPR_FlagDef Struct Reference
Represents a flag-field within a flag-record. More...
#include <epr_api.h>
Data Fields | |
| EPR_Magic | magic |
| The magic number for this structure. | |
| char * | name |
| The flag name. | |
| uint | bit_mask |
| The bit mask describing this flag. | |
| char * | description |
| The flag description. | |
Detailed Description
Represents a flag-field within a flag-record.
Field Documentation
The magic number for this structure.
IMPORTANT: This must always be the first member of this structure.
| char* EPR_FlagDef::name |
The flag name.
The bit mask describing this flag.
| char* EPR_FlagDef::description |
The flag description.
The documentation for this struct was generated from the following file:
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
EPR_ProductId Struct Reference
The EPR_ProductId structure contains information about an ENVISAT product file which has been opened with the epr_open_product() function.
More...
#include <epr_api.h>
Data Fields | |
| EPR_Magic | magic |
| The magic number for this structure. | |
| char * | file_path |
| The file's path including the file name. | |
| FILE * | istream |
The input stream as returned by the ANSI C fopen function for the given file path. | |
| uint | tot_size |
| The total size in bytes of the product file. | |
| uint | scene_width |
| The total width of product's scene raster in pixels. | |
| uint | scene_height |
| The total height of product's scene raster in pixels. | |
| char | id_string [EPR_PRODUCT_ID_STRLEN+1] |
| The product identifier string obtained from the MPH parameter 'PRODUCT'. | |
| EPR_SRecord * | mph_record |
| The record representing the main product header (MPH). | |
| EPR_SRecord * | sph_record |
| The record representing the specific product header (SPH). | |
| EPR_SPtrArray * | dsd_array |
| An array containing all (!) DSDs read from the product's specific product header (SPH). | |
| EPR_SPtrArray * | record_info_cache |
| Cache for record infos. | |
| EPR_SPtrArray * | param_table |
| A table containing dynamic field info parameters. | |
| EPR_SPtrArray * | dataset_ids |
| Contains and array of all dataset IDs for the product (type EPR_SDatasetId*). | |
| EPR_SPtrArray * | band_ids |
| Contains and array of all band IDs for the product (type EPR_SBandId*). | |
| int | meris_iodd_version |
| For MERIS L1b and RR and FR to provide backward compatibility. | |
Detailed Description
The EPR_ProductId structure contains information about an ENVISAT product file which has been opened with the epr_open_product() function.
- See also:
- epr_open_product
Field Documentation
The magic number for this structure.
IMPORTANT: This must always be the first member of this structure.
| char* EPR_ProductId::file_path |
The file's path including the file name.
| FILE* EPR_ProductId::istream |
The input stream as returned by the ANSI C fopen function for the given file path.
The total size in bytes of the product file.
The total width of product's scene raster in pixels.
The total height of product's scene raster in pixels.
| char EPR_ProductId::id_string[EPR_PRODUCT_ID_STRLEN+1] |
The product identifier string obtained from the MPH parameter 'PRODUCT'.
The first 10 characters of this string identify the 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.
The record representing the main product header (MPH).
The record representing the specific product header (SPH).
| EPR_SPtrArray* EPR_ProductId::dsd_array |
An array containing all (!) DSDs read from the product's specific product header (SPH).
| EPR_SPtrArray* EPR_ProductId::record_info_cache |
Cache for record infos.
Contains all record infos read from the database for this file so far.
The reason for caching record infos on a per-file-base is that a some record infos instances can contain file related content such as the number of pixels in a measurecment dataset record (MDSR).
| EPR_SPtrArray* EPR_ProductId::param_table |
A table containing dynamic field info parameters.
Dynamic field info parameters are created at runtime because the are derived from the product file contents and can not be staically stored in the record info database.
| EPR_SPtrArray* EPR_ProductId::dataset_ids |
Contains and array of all dataset IDs for the product (type EPR_SDatasetId*).
| EPR_SPtrArray* EPR_ProductId::band_ids |
Contains and array of all band IDs for the product (type EPR_SBandId*).
For MERIS L1b and RR and FR to provide backward compatibility.
The documentation for this struct was generated from the following file:
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
EPR_Raster Struct Reference
Represents a raster in which data will be stored. More...
#include <epr_api.h>
Data Fields | |
| EPR_Magic | magic |
| The magic number for this structure. | |
| EPR_EDataTypeId | data_type |
| The data type of the band's pixel values. | |
| uint | elem_size |
| The size in byte of a single element (sample) of this raster's buffer. | |
| uint | source_width |
| The width of the source . | |
| uint | source_height |
| The height of the source. | |
| uint | source_step_x |
| The sub-sampling for the across-track direction in pixel. | |
| uint | source_step_y |
| The sub-sampling for the along-track direction in pixel. | |
| uint | raster_width |
| The width of the raster in pixel. | |
| uint | raster_height |
| The height of the raster in pixel. | |
| void * | buffer |
| The elements of this raster. | |
Detailed Description
Represents a raster in which data will be stored.
All 'size' parameter are in PIXEL.
Field Documentation
The magic number for this structure.
IMPORTANT: This must always be the first member of this structure.
The data type of the band's pixel values.
All corresponding with EPR_DataTypeId types are possible
The size in byte of a single element (sample) of this raster's buffer.
The width of the source .
The height of the source.
The sub-sampling for the across-track direction in pixel.
The sub-sampling for the along-track direction in pixel.
The width of the raster in pixel.
raster_width = (source_width - 1) / source_step_x + 1
The height of the raster in pixel.
raster_height = (source_height - 1) / source_step_y + 1
| void* EPR_Raster::buffer |
The elements of this raster.
Its volume is raster_width * raster_height * sizeof(data_type) in bytes.
The documentation for this struct was generated from the following file:
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
EPR_Record Struct Reference
The EPR_Record structure represents a record instance read from an ENVISAT dataset.
More...
#include <epr_api.h>
Data Fields | |
| EPR_Magic | magic |
| The magic number for this structure. | |
| EPR_SRecordInfo * | info |
| The corresponding record info for this record (a 'soft' pointer). | |
| uint | num_fields |
| The number of fields contained in this record. | |
| EPR_SField ** | fields |
| The record fields. | |
Detailed Description
The EPR_Record structure represents a record instance read from an ENVISAT dataset.
A record is composed of multiple fields.
- See also:
- EPR_Field
Field Documentation
The magic number for this structure.
IMPORTANT: This must always be the first member of this structure.
The corresponding record info for this record (a 'soft' pointer).
The number of fields contained in this record.
The value is always equal info->field_infos->length and is provided here for convenience only.
The record fields.
An array of EPR_Field* of length info->num_fields
The documentation for this struct was generated from the following file:
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002
| ENVISAT Product Reader API for C |
|
EPR_Time Struct Reference
Represents a binary time value field in ENVISAT records. More...
#include <epr_api.h>
Data Fields | |
| int | days |
| uint | seconds |
| uint | microseconds |
Detailed Description
Represents a binary time value field in ENVISAT records.
Refer to ENVISAT documentation for the exact definition of this data type.
Field Documentation
| int EPR_Time::days |
The documentation for this struct was generated from the following file:
Generated on Mon Aug 2 15:24:00 2010
ENVISAT Product Reader C API
Written by
Brockmann Consult,
© 2002