RasterElement Class Reference

A three-dimensional data set. More...

#include <RasterElement.h>

Inheritance diagram for RasterElement:

List of all members.

Public Member Functions

virtual double getPixelValue (DimensionDescriptor column, DimensionDescriptor row, DimensionDescriptor band=DimensionDescriptor(), ComplexComponent component=COMPLEX_MAGNITUDE) const =0

virtual DataAccessor getDataAccessor (DataRequest *pRequest=NULL)=0

virtual DataAccessor getDataAccessor (DataRequest *pRequest=NULL) const =0

virtual void incrementDataAccessor (DataAccessorImpl &accessor)=0

virtual void updateData ()=0

virtual uint64_t sanitizeData (double value=0.0)=0

virtual Statistics * getStatistics (DimensionDescriptor band=DimensionDescriptor()) const =0

virtual RasterElement * createChip (DataElement *pParent, const std::string &appendName, const std::vector< DimensionDescriptor > &selectedRows, const std::vector< DimensionDescriptor > &selectedColumns, const std::vector< DimensionDescriptor > &selectedBands=std::vector< DimensionDescriptor >()) const =0

virtual bool copyDataToChip (RasterElement *pRasterChip, const std::vector< DimensionDescriptor > &selectedRows, const std::vector< DimensionDescriptor > &selectedColumns, const std::vector< DimensionDescriptor > &selectedBands, bool &abort, Progress *pProgress=NULL) const =0

virtual RasterElement * copyShallow (const std::string &name, DataElement *pParent) const =0

virtual void setTerrain (RasterElement *pTerrain)=0

virtual const RasterElement * getTerrain () const =0

virtual bool createTemporaryFile ()=0

virtual bool createMemoryMappedPager ()=0

virtual bool createInMemoryPager ()=0

virtual bool createDefaultPager ()=0

virtual bool setPager (RasterPager *pPager)=0

virtual RasterPager * getPager () const =0

virtual const std::string & getTemporaryFilename () const =0

virtual const void * getRawData () const =0

virtual void * getRawData ()=0

virtual bool writeRawData (void *pData, InterleaveFormatType interleaveType, unsigned int startRow, unsigned int numRows, unsigned int startColumn, unsigned int numColumns, unsigned int startBand, unsigned int numBands)=0

virtual LocationType convertPixelToGeocoord (LocationType pixel, bool quick=false, bool *pAccurate=NULL) const =0

virtual std::vector< LocationType > convertPixelsToGeocoords (const std::vector< LocationType > &pixels, bool quick=false, bool *pAccurate=NULL) const =0

virtual LocationType convertGeocoordToPixel (LocationType geocoord, bool quick=false, bool *pAccurate=NULL) const =0

virtual std::vector< LocationType > convertGeocoordsToPixels (const std::vector< LocationType > &geocoords, bool quick=false, bool *pAccurate=NULL) const =0

virtual bool isGeoreferenced () const =0

virtual void updateGeoreferenceData ()=0

virtual void setGeoreferencePlugin (Georeference *pGeo)=0

virtual Georeference * getGeoreferencePlugin () const =0

Static Public Member Functions

static const std::string & signalTerrainSet ()

static const std::string & signalGeoreferenceModified ()

static const std::string & signalDataModified ()

Protected Member Functions

virtual ~RasterElement ()

Detailed Description

A three-dimensional data set.

The RasterElement class is commonly used for three dimensional data sets that are processed by the user.

When dealing with RasterElements that have NaN(Not a number) values, be sure to sanitize the data before doing anything with the dataset. Failure to do so may lead to unexpected results.

This subclass of Subject will notify upon the following conditions:

The following method is called: updateData().
Everything else documented in DataElement.

See also:: DataElement

Examples:: SampleRasterElementImporter.cpp, SampleRasterElementImporter.h, Tutorial/Tutorial3.cpp, Tutorial/Tutorial4.cpp, and Tutorial/Tutorial5.cpp.

Definition at line 45 of file RasterElement.h.

Constructor & Destructor Documentation

virtual RasterElement::~RasterElement ( ) [protected, virtual]

This should be destroyed by calling ModelServices::destroyElement.

Definition at line 573 of file RasterElement.h.

Member Function Documentation

static const std::string& RasterElement::signalTerrainSet ( ) [static]

Emitted with any<RasterElement*> when the associated terrain object is changed.

Definition at line 51 of file RasterElement.h.

static const std::string& RasterElement::signalGeoreferenceModified ( ) [static]

Emitted when the RasterElement's georeferencing has been changed.

Definition at line 56 of file RasterElement.h.

static const std::string& RasterElement::signalDataModified ( ) [static]

Emitted when the RasterElement's data has been changed.

Definition at line 61 of file RasterElement.h.

virtual double RasterElement::getPixelValue	(	DimensionDescriptor	column,
		DimensionDescriptor	row,
		DimensionDescriptor	band = `DimensionDescriptor()`,
		ComplexComponent	component = `COMPLEX_MAGNITUDE`
	)			const `[pure virtual]`

Returns an individual data value in the cube.

Parameters:

	column	The column of the pixel to check. This must be gotten from the RasterDataDescriptor's column vector.
	row	The row of the pixel to check. This must be gotten from the RasterDataDescriptor's row vector.
	band	The band of the pixel to check. A default-constructed value can be passed in if multiple bands are not present. For a non-default value, it be gotten from the RasterDataDescriptor's column vector.
	component	The complex data component for which to get the data value. For non-complex data, this value is ignored.

Returns:: The data value at the given column, row, and band. A value of 0.0 is returned if the pixel value could not be obtained.

virtual DataAccessor RasterElement::getDataAccessor ( DataRequest * pRequest = NULL ) [pure virtual]

Get a DataAccessor with the parameters contained within the given request.

Warning:: The returned DataAccessor must be deleted prior to the deletion of this RasterElement.

Parameters:

pRequest

Requested access parameters. If NULL, then the default parameters will be used. This method takes ownership of the DataRequest object.

Returns:: A DataAccessor for the dataset. If the request was invalid or unable to be filled, an invalid DataAccessor will be returned. Callers should check the returned object's DataAccessor::isValid().

virtual DataAccessor RasterElement::getDataAccessor ( DataRequest * pRequest = NULL ) const [pure virtual]

Get a DataAccessor with the parameters contained within the given request.

This const overloaded method is exactly like the non-const version, except that it cannot be used with a writable DataRequest.

Warning:: The returned DataAccessor must be deleted prior to the deletion of this RasterElement.

Parameters:

pRequest

Requested access parameters. If NULL, then the default parameters will be used. This method takes ownership of the DataRequest object.

Returns:: A DataAccessor for the dataset. If the request was invalid or unable to be filled, an invalid DataAccessor will be returned. Callers should check the returned object's DataAccessor::isValid().

See also:: DataRequest::setWritable()

virtual void RasterElement::incrementDataAccessor ( DataAccessorImpl & accessor ) [pure virtual]

Increments the Data Accessor to the next segment of memory.

The incrementDataAccessor() method steps to the next segment within the Matrix. This notifies the Data Accessor that the algorithm is complete with the current segment.

See also:: DataAccessor

virtual void RasterElement::updateData ( ) [pure virtual]

Notifies all observers of the object that its data has changed.

Subject Notifications:: This method will notify RasterElement::signalDataModified.

virtual uint64_t RasterElement::sanitizeData ( double value = 0.0 ) [pure virtual]

Sanitize the data in the object.

This method will iterate over the dataset and replace all instances of floating point NaNs with the specified value.

Parameters:

value

The value to use for all instances of floating point NaNs. This value will be cast (via static_cast) to the underlying EncodingType of the dataset.

Returns:: The number of data values which were sanitized. If this value is non-zero, RasterElement::updateData() will be called before returning.

See also:: RasterElement::updateData()

virtual Statistics* RasterElement::getStatistics ( DimensionDescriptor band = DimensionDescriptor() ) const [pure virtual]

Returns statistics for the given band data.

Parameters:

band

The band for which to get its statistics.

Returns:: A pointer to the Statistics object from which individual statistics values for the given band can be set or retrieved. If invalid, this will get the first band's statistics.

virtual RasterElement* RasterElement::createChip	(	DataElement *	pParent,
		const std::string &	appendName,
		const std::vector< DimensionDescriptor > &	selectedRows,
		const std::vector< DimensionDescriptor > &	selectedColumns,
		const std::vector< DimensionDescriptor > &	selectedBands = `std::vector< DimensionDescriptor >()`
	)			const `[pure virtual]`

This method will create a new RasterElement which is a chip of the object it is called on.

Its active row, column, and band vectors will correctly refer to the same original and on-disk numbers of the original cube. The new cube will match the original RasterElement's processing location (on-disk (not read-only) or in-memory). Except for the name and parent, a RasterElement created with this function should be indistinguishable from one chipped on import from the same file.

The DimensionDescriptor vectors should be created by copying the descriptors of the desired rows, columns, or bands from the DataDescriptor of the source RasterElement. These must be in ascending order, without duplication.

Parameters:

	pParent	The element to use for the parent of the created cube.
	appendName	What to append to the name of the RasterElement. ie. "_chip" would transform the name "A.sio" to "A_chip.sio". Passing an empty string will result in using the RasterElement's name as the chipped name.
	selectedRows	The DimensionDescriptors (unmodified from this object) for the rows which should be included in this chip. Passing an empty vector will result in using the RasterElement's rows as the chipped rows.
	selectedColumns	The DimensionDescriptors (unmodified from this object) for the columns which should be included in this chip. Passing an empty vector will result in using the RasterElement's columns as the chipped columns.
	selectedBands	The DimensionDescriptors (unmodified from this object) for the bands which should be included in this chip. Passing an empty vector will result in using the RasterElement's bands as the chipped bands.

Returns:: A pointer to the created RasterElement

See also:: RasterElement::copy(), RasterElement::copyDataToChip()

virtual bool RasterElement::copyDataToChip	(	RasterElement *	pRasterChip,
		const std::vector< DimensionDescriptor > &	selectedRows,
		const std::vector< DimensionDescriptor > &	selectedColumns,
		const std::vector< DimensionDescriptor > &	selectedBands,
		bool &	abort,
		Progress *	pProgress = `NULL`
	)			const `[pure virtual]`

This method will copy data from this RasterElement to the chip RasterElement.

Only the cube data will be copied -- no other data from the DataDescriptor will be copied.

The DimensionDescriptor vectors should be created by copying the descriptors of the desired rows, columns, or bands from the DataDescriptor of the source RasterElement. These must be in ascending order, without duplication.

Parameters:

	pRasterChip	The chip to copy data to.
	selectedRows	The DimensionDescriptors (unmodified from this object) for the rows which should be included in this chip.
	selectedColumns	The DimensionDescriptors (unmodified from this object) for the columns which should be included in this chip.
	selectedBands	The DimensionDescriptors (unmodified from this object) for the bands which should be included in this chip.
	abort	A flag which can be set externally to abort. Set this to true when abort is desired.
	pProgress	The progress object to report the current progress to.

Returns:: True if the operation succeeded, false otherwise

See also:: RasterElement::copy(), RasterElement::createChip()

virtual RasterElement* RasterElement::copyShallow	(	const std::string &	name,
		DataElement *	pParent
	)			const `[pure virtual]`

Creates a new raster element with the same values as this element but without copying the raster data.

The method creates a new element based on the data contained in this element, which includes a copy of all data in the data descriptor. It is similar to RasterElement::copy() but does not copy the raw raster data so it is faster. This is useful if you are going to modify the raw raster data but otherwise would like a duplicate of the raster element.

Parameters:

	name	The name for the created raster element, which can be the same as this object's name if the parent is different than this object's parent.
	pParent	The parent element for the created data element, which can be the same as this object's parent if the name is different than this object's name.

Returns:: A pointer to the new raster element. NULL is returned if the element cannot be copied or if the given parent is the same as this object's parent and the given name is the same as this object's name.

virtual void RasterElement::setTerrain ( RasterElement * pTerrain ) [pure virtual]

Sets a terrain map of the RasterElement.

Parameters:

pTerrain

A pointer to an object containing terrain information of the data cube. It is assumed that the passed in RasterElement is coregistered with this RasterElement.

Subject Notifications:: This method will notify signalTerrainSet() with any<RasterElement*>.

virtual const RasterElement* RasterElement::getTerrain ( ) const [pure virtual]

Gets a terrain map of the RasterElement.

NOTE: When the RasterElement is destroyed, it will destroy its associated terrain object. DO NOT attempt to set the same terrain object in two different RasterElements.

Returns:: A pointer to an object containing terrain information of the data cube. Returns NULL on RasterElements that have not had their terrain map set.

virtual bool RasterElement::createTemporaryFile ( ) [pure virtual]

Creates an empty temporary file.

This method creates an empty temporary file to be used for on-disk processing. After creating the temp file, createMemoryMappedPager() is called to create a pager plug-in that uses the data parameters specificed in the data descriptor. Therefore, there is no need to call createMemoryMappedPager() or setPager() after calling this method.

The size of the temporary file is the size of the subset specified in the data descriptor. If no subset is specified, the size of the file equals the size of the data. There are no header, trailer, preline, postline, preband, or postband bytes.

The created filename can be retrieved to copy data into the file by calling getTemporaryFilename().

Returns:: Returns true if the temporary file was created successfully; otherwise returns false.

virtual bool RasterElement::createMemoryMappedPager ( ) [pure virtual]

Creates a default pager plug-in instance that will be used by this object to map data from the original file on disk into memory.

This method creates a default raster pager plug-in that is used to access the data using the data parameters specified in the file descriptor. It is typically used in the read-only processing case. To set a custom pager plug-in, call the setPager() method instead.

Returns:: Returns true if the default pager plug-in was successfully created; otherwise returns false.

virtual bool RasterElement::createInMemoryPager ( ) [pure virtual]

Creates a default pager plug-in instance that will be used by this object to store data in memory.

This method creates a default raster pager plug-in that is used to access the data using the data parameters specified in the data descriptor.

This method does not usually need to be called from a plug-in. RasterElements with ProcessingLocation::IN_MEMORY automatically have an in-memory pager created for them.

Returns:: Returns true if the default pager plug-in was successfully created; otherwise returns false.

virtual bool RasterElement::createDefaultPager ( ) [pure virtual]

If there is no pager set into the RasterElement, create a default one.

This method create an appropriate default pager, including blank space to use for the data.

Returns:: True if there was already a pager or a default one was successfully created, false otherwise.

virtual bool RasterElement::setPager ( RasterPager * pPager ) [pure virtual]

Sets the raster pager plug-in instance that will be used by this object to access the data.

This method provides the means to set a custom pager plug-in that is used to access the data. To create a default pager plug-in, call createMemoryMappedPager() instead.

Parameters:

pPager

The raster pager plug-in instance that should be used to page data into the application.

Returns:: Returns true if the given pager plug-in can be used by this object; otherwise returns false.

Examples:: SampleRasterElementImporter.cpp.

virtual RasterPager* RasterElement::getPager ( ) const [pure virtual]

Returns the raster pager plug-in instance that will be used by this object to access the data.

Returns:: Returns the raster pager plug-in instance used by this object.

virtual const std::string& RasterElement::getTemporaryFilename ( ) const [pure virtual]

Returns the filename that contains the data used for on-disk processing.

Returns:: The filename from which on-disk processing will occur. An empty string is returned if there is no temporary file.

virtual const void* RasterElement::getRawData ( ) const [pure virtual]

Returns a read-only pointer to the data values in memory.

This method will return non-NULL only if the entire dataset can be accessed concurrently. This will not be true for all RasterElements. This method should only be used to implement an optimized version of an algorithm. The general case is to use a DataAccessor.

The calling object must interpret the handle according to the data type and interleave. No conversions are available.

Returns:: A read-only pointer to the data if it can be accessed as a whole, NULL otherwise.

See also:: RasterDataDescriptor::getDataType()

virtual void* RasterElement::getRawData ( ) [pure virtual]

Returns a pointer to the data values in memory.

This method will return non-NULL only if the entire dataset can be accessed concurrently. This will not be true for all RasterElements. This method should only be used to implement an optimized version of an algorithm. The general case is to use a DataAccessor.

The calling object must interpret the handle according to the data type and interleave. No conversions are available.

Returns:: A pointer to the data if it can be accessed as a whole, NULL otherwise.

See also:: RasterDataDescriptor::getDataType()

virtual bool RasterElement::writeRawData	(	void *	pData,
		InterleaveFormatType	interleaveType,
		unsigned int	startRow,
		unsigned int	numRows,
		unsigned int	startColumn,
		unsigned int	numColumns,
		unsigned int	startBand,
		unsigned int	numBands
	)			`[pure virtual]`

Copies data from a buffer of the specified format.

Parameters:

	pData	A buffer containing the data to write.
	interleaveType	The interleave of the given data.
	startRow	The first row to write.
	numRows	The number of rows to write.
	startColumn	The first column to write.
	numColumns	The number of columns to write.
	startBand	The first bands to write.
	numBands	The number of bands to write.

Returns:: Returns true on success; false otherwise.

virtual LocationType RasterElement::convertPixelToGeocoord	(	LocationType	pixel,
		bool	quick = `false`,
		bool *	pAccurate = `NULL`
	)			const `[pure virtual]`

Returns a geocoordinate corresponding to a given scene pixel location.

Parameters:

	pixel	The scene pixel location as a LocationType.
	quick	Set this to true if less accurate results are acceptable in exchange for speed.
	pAccurate	Evaluation of the accuracy of the computed location as determined by the Georeference plug-in. When `NULL`, no accuracy check is performed.

Returns:: The corresponding geocoordinate as a LocationType.

virtual std::vector<LocationType> RasterElement::convertPixelsToGeocoords	(	const std::vector< LocationType > &	pixels,
		bool	quick = `false`,
		bool *	pAccurate = `NULL`
	)			const `[pure virtual]`

Returns geocoordinates for multiple pixel locations.

This method uses the convertPixelToGeocoord() method to perform the conversion for each pixel location.

Parameters:

	pixels	The pixel locations for which to get their geocoordinates.
	quick	Set this to true if less accurate results are acceptable in exchange for speed.
	pAccurate	Evaluation of the accuracy of the computed locations as determined by the Georeference plug-in. When `NULL`, no accuracy checks are performed.

Returns:: A vector containing the geocoordinates that correspond to each pixel location in the given vector.

virtual LocationType RasterElement::convertGeocoordToPixel	(	LocationType	geocoord,
		bool	quick = `false`,
		bool *	pAccurate = `NULL`
	)			const `[pure virtual]`

Returns a scene pixel location corresponding to a given geocoordinate.

Parameters:

	geocoord	The geocoordinate as a LocationType.
	quick	Set this to true if less accurate results are acceptable in exchange for speed.
	pAccurate	Evaluation of the accuracy of the computed location as determined by the Georeference plug-in. When `NULL`, no accuracy check is performed.

Returns:: The corresponding pixel location as a LocationType.

virtual std::vector<LocationType> RasterElement::convertGeocoordsToPixels	(	const std::vector< LocationType > &	geocoords,
		bool	quick = `false`,
		bool *	pAccurate = `NULL`
	)			const `[pure virtual]`

Returns pixel locations for multiple geocoordinates.

This method uses the convertGeocoordToPixel() method to perform the conversion for each geocoordinate.

Parameters:

	geocoords	The geocoordinates for which to get the pixel locations.
	quick	Set this to true if less accurate results are acceptable in exchange for speed.
	pAccurate	Evaluation of the accuracy of the computed locations as determined by the Georeference plug-in. When `NULL`, no accuracy checks are performed.

Returns:: A vector containing the pixel locations that correspond to each geocoordinate in the given vector.

virtual bool RasterElement::isGeoreferenced ( ) const [pure virtual]

Determine if the RasterElement has been georeferenced.

Returns:: True if the RasterElement is georeferenced, false otherwise.

virtual void RasterElement::updateGeoreferenceData ( ) [pure virtual]

Notify the RasterElement that the georeferencing data has been updated.

This method is typically called by a Georeference plugin.

Subject Notifications:: This method will notify Raster::signalGeoreferenceModified.

virtual void RasterElement::setGeoreferencePlugin ( Georeference * pGeo ) [pure virtual]

Set a plugin to perform all georeferencing computations.

Parameters:

pGeo

The plugin to use for georeferencing.

Subject Notifications:: This method will notify Raster::signalGeoreferenceModified.

virtual Georeference* RasterElement::getGeoreferencePlugin ( ) const [pure virtual]

Get the plugin currently used.

Returns:: The plugin used.


Public Member Functions
virtual double	getPixelValue (DimensionDescriptor column, DimensionDescriptor row, DimensionDescriptor band=DimensionDescriptor(), ComplexComponent component=COMPLEX_MAGNITUDE) const =0
virtual DataAccessor	getDataAccessor (DataRequest *pRequest=NULL)=0
virtual DataAccessor	getDataAccessor (DataRequest *pRequest=NULL) const =0
virtual void	incrementDataAccessor (DataAccessorImpl &accessor)=0
virtual void	updateData ()=0
virtual uint64_t	sanitizeData (double value=0.0)=0
virtual Statistics *	getStatistics (DimensionDescriptor band=DimensionDescriptor()) const =0
virtual RasterElement *	createChip (DataElement *pParent, const std::string &appendName, const std::vector< DimensionDescriptor > &selectedRows, const std::vector< DimensionDescriptor > &selectedColumns, const std::vector< DimensionDescriptor > &selectedBands=std::vector< DimensionDescriptor >()) const =0
virtual bool	copyDataToChip (RasterElement pRasterChip, const std::vector< DimensionDescriptor > &selectedRows, const std::vector< DimensionDescriptor > &selectedColumns, const std::vector< DimensionDescriptor > &selectedBands, bool &abort, Progress pProgress=NULL) const =0
virtual RasterElement *	copyShallow (const std::string &name, DataElement *pParent) const =0
virtual void	setTerrain (RasterElement *pTerrain)=0
virtual const RasterElement *	getTerrain () const =0
virtual bool	createTemporaryFile ()=0
virtual bool	createMemoryMappedPager ()=0
virtual bool	createInMemoryPager ()=0
virtual bool	createDefaultPager ()=0
virtual bool	setPager (RasterPager *pPager)=0
virtual RasterPager *	getPager () const =0
virtual const std::string &	getTemporaryFilename () const =0
virtual const void *	getRawData () const =0
virtual void *	getRawData ()=0
virtual bool	writeRawData (void *pData, InterleaveFormatType interleaveType, unsigned int startRow, unsigned int numRows, unsigned int startColumn, unsigned int numColumns, unsigned int startBand, unsigned int numBands)=0
virtual LocationType	convertPixelToGeocoord (LocationType pixel, bool quick=false, bool *pAccurate=NULL) const =0
virtual std::vector< LocationType >	convertPixelsToGeocoords (const std::vector< LocationType > &pixels, bool quick=false, bool *pAccurate=NULL) const =0
virtual LocationType	convertGeocoordToPixel (LocationType geocoord, bool quick=false, bool *pAccurate=NULL) const =0
virtual std::vector< LocationType >	convertGeocoordsToPixels (const std::vector< LocationType > &geocoords, bool quick=false, bool *pAccurate=NULL) const =0
virtual bool	isGeoreferenced () const =0
virtual void	updateGeoreferenceData ()=0
virtual void	setGeoreferencePlugin (Georeference *pGeo)=0
virtual Georeference *	getGeoreferencePlugin () const =0
Static Public Member Functions
static const std::string &	signalTerrainSet ()
static const std::string &	signalGeoreferenceModified ()
static const std::string &	signalDataModified ()
Protected Member Functions
virtual	~RasterElement ()