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.