ENVISAT Product Reader C API: Main Page

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 `NULL`
  | source_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 `NULL` if 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 `NULL`
  | 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 `NULL` if 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 `NULL` if 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 `0` if 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 `0` if 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 `NULL`
  | index | the index identifying the position of the band, starting with 0, must not be negative

Returns:
  the requested band ID, or `NULL` if 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 `NULL`
  | band_name | the name of the band, must not be `NULL`

Returns:
  the requested band ID, or `NULL` if 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.