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.

## Detailed Description

## Function Documentation

## epr_create_compatible_raster()

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 occurred.

## epr_create_raster()

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 occurred.

## epr_create_bitmask_raster()

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 occurred.

## epr_read_band_raster()

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 coordinates 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 coordinate in pixel coordinates (zero-based) of the upper right corner of the source-region
  offset_y | along-track source coordinate in pixel coordinates (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

## epr_get_raster_elem_size()

uint epr_get_raster_elem_size | ( | const EPR_SRaster * | raster | ) |

## epr_get_raster_elem_addr()

void * epr_get_raster_elem_addr | ( | const EPR_SRaster * | raster,
|  | uint | offset )

## epr_get_raster_pixel_addr()

void * epr_get_raster_pixel_addr | ( | const EPR_SRaster * | raster,
|  | uint | x,
|  | uint | y )

## epr_get_raster_line_addr()

void * epr_get_raster_line_addr | ( | const EPR_SRaster * | raster,
|  | uint | y )

## epr_get_raster_width()

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 occurred.

## epr_get_raster_height()

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 occurred.

## epr_get_num_bands()

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_get_band_id_at()

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_get_band_id()

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

## epr_get_band_name()

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.

## epr_free_raster()

void epr_free_raster | ( | EPR_SRaster * | raster | ) |

Release the memory allocated through a raster.

Parameters

  raster | the raster to be released.