mio::DEMObject Class Reference

Detailed Description

A class to represent DEMs and automatically compute some properties. This class stores elevation grids and their georeferencing, expressed as the lower-left coordinates, the cellsize (cells are assumed to be square) and a nodata code for potentially empty cells (The nodata parameter is supposed to be IOUtils::nodata). This class also automatically computes local slope, azimuth, curvature, normals and minimal/maximal for normalization. Various algorithms are available to compute these properties (see mio::DEMObject::slope_type) and it is possible to toggle between automatic refresh or not. Several other DEM related values can be computed, such as the horizon, displacements within the DEM, etc.

Author

Gaël Rosset - Mathias Bavay

Date

2009-07-20

#include <DEMObject.h>

Public Types
enum	slope_type {   DFLT , FLEM , HICK , HORN ,   CORR , D8 }
	Keywords for slope computation algorithm. More...
enum	update_type {   NO_UPDATE =0 , SLOPE =1 , NORMAL =2 , CURVATURE =4 ,   UPDATE_UNSET }
	Keywords for automatic update of parameters. They can be combined with "|". More...
enum	FORMATS { FULL , SHORT }
	Keywords for selecting the toString formats. More...

Public Member Functions
	DEMObject (const slope_type &i_algorithm=DFLT)
	Default constructor. Initializes all variables to 0, except lat/long which are initialized to IOUtils::nodata. More...
	DEMObject (const size_t &ncols_in, const size_t &nrows_in, const Coords &llcorner_in, const double &init)
	Constructor that sets a constant DEM. More...
	DEMObject (const size_t &ncols_in, const size_t &nrows_in, const double &cellsize_in, const Coords &llcorner_in, const slope_type &i_algorithm=DFLT)
	Constructor that sets variables. More...
	DEMObject (const double &cellsize_in, const Coords &llcorner_in, const Array2D< double > &altitude_in, const bool &i_update=true, const slope_type &i_algorithm=DFLT)
	Constructor that sets variables. More...
	DEMObject (const Grid2DObject &dem_in, const bool &i_update=true, const slope_type &i_algorithm=DFLT)
	Constructor that sets variables from a Grid2DObject. More...
	DEMObject (const DEMObject &i_dem, const size_t &i_nx, const size_t &i_ny, const size_t &i_ncols, const size_t &i_nrows, const bool &i_update=true, const slope_type &i_algorithm=DFLT)
	Constructor that sets variables from a subset of another DEMObject, given an origin (X,Y) (first index being 0) and a number of columns and rows. More...
void	setDefaultAlgorithm (const std::string &i_algorithm)
	Sets the default slope calculation algorithm. More...
void	setDefaultAlgorithm (const slope_type &i_algorithm)
	Sets the default slope calculation algorithm. More...
int	getDefaultAlgorithm () const
	Get the default slope calculation algorithm. More...
void	setUpdatePpt (const update_type &in_update_flag)
	Set the properties that will be calculated by the object when updating The following properties can be turned on/off: slope/azimuth and/or normals, and/or curvatures. Flags are combined using the binary "|" operator. More...
int	getUpdatePpt () const
	Get the properties that will be calculated by the object when updating. More...
void	setCurvatureScale (const double &in_curvature_scale)
	Set the curvature length scale for calculating curvature. More...
void	update (const std::string &algorithm)
	Force the computation of the local slope, azimuth, normal vector and curvature. It has to be called manually since it can require some time to compute. Without this call, the above mentionned parameters are NOT up to date. More...
void	update (const slope_type &algorithm=DFLT)
	Force the computation of the local slope, azimuth, normal vector and curvature. It has to be called manually since it can require some time to compute. Without this call, the above mentionned parameters are NOT up to date. More...
void	updateAllMinMax ()
	Recomputes the min/max of altitude, slope and curvature It returns +/- std::numeric_limits<double> ::max() for a given parameter if its grid was empty/undefined. More...
void	printFailures ()
	Prints the list of points that have an elevation different than nodata but no slope or curvature Such points can happen if they are surrounded by too many points whose elevation is nodata If no such points exist, it prints nothing. More...
void	sanitize ()
	Clean up the DEM Object When computing the slope and curvature, it is possible to get points where the elevation is known but where no slope/azimuth/normals/curvature could be computed. This method sets the elevation to nodata for such points, so that latter use of the DEM would be simpler (simply test the elevation in order to know if the point can be used and it guarantees that all other information is available). More...
DEMObject &	operator= (const Grid2DObject &)
	Assignement operator. More...
DEMObject &	operator= (const double &value)
	Assignement operator. More...
DEMObject &	operator+= (const double &rhs)
const DEMObject	operator+ (const double &rhs) const
DEMObject &	operator+= (const Grid2DObject &rhs)
const DEMObject	operator+ (const Grid2DObject &rhs) const
DEMObject &	operator-= (const double &rhs)
const DEMObject	operator- (const double &rhs) const
DEMObject &	operator-= (const Grid2DObject &rhs)
const DEMObject	operator- (const Grid2DObject &rhs) const
DEMObject &	operator*= (const double &rhs)
const DEMObject	operator* (const double &rhs) const
DEMObject &	operator*= (const Grid2DObject &rhs)
const DEMObject	operator* (const Grid2DObject &rhs) const
DEMObject &	operator/= (const double &rhs)
const DEMObject	operator/ (const double &rhs) const
DEMObject &	operator/= (const Grid2DObject &rhs)
const DEMObject	operator/ (const Grid2DObject &rhs) const
bool	operator== (const DEMObject &in) const
	Operator that tests for equality. More...
bool	operator!= (const DEMObject &in) const
	Operator that tests for inequality. More...
const std::string	toString (const FORMATS &type=FULL) const
Public Member Functions inherited from mio::Grid2DObject
double &	operator() (const size_t &ix, const size_t &iy)
double	operator() (const size_t &ix, const size_t &iy) const
double &	operator() (const size_t &i)
double	operator() (const size_t &i) const
const std::string	toString () const
	Grid2DObject ()
	Default constructor. Initializes all variables to 0, except lat/long which are initialized to IOUtils::nodata. More...
	Grid2DObject (const size_t &ncols, const size_t &nrows, const double &cellsize, const Coords &i_llcorner)
	Grid2DObject (const size_t &ncols, const size_t &nrows, const double &cellsize, const Coords &i_llcorner, const double &init)
	Grid2DObject (const Grid2DObject &i_grid, const double &init)
	Grid2DObject (const double &cellsize, const Coords &i_llcorner, const Array2D< double > &grid2D_in)
	Grid2DObject (const Grid2DObject &i_grid2Dobj, const size_t &i_nx, const size_t &i_ny, const size_t &i_ncols, const size_t &i_nrows)
	constructs an object as a subset of another grid object More...
bool	gridify (Coords &point) const
	Compute the positional parameters that are not already known This means that the Coords::point object that is given either contains geographic coordinates or grid indices. This method will calculate the missing ones (so that (i,j) match with (lat,lon) and (east,north)). If the given point had a "NULL" projection, it will be set to the grid's. More...
bool	gridify (std::vector< Coords > &vec_points, const bool &keep_invalid=false) const
	Compute the positional parameters that are not already known This means that the Coords::point object that is given either contains geographic coordinates or grid indices. This method will calculate the missing ones (so that (i,j) match with (lat,lon) and (east,north)). Any point that is either invalid or outside the grid is removed from the vector. If the given point had a "NULL" projection, it will be set to the grid's. More...
bool	gridify (std::vector< StationData > &vec_points, const bool &keep_invalid=false) const
void	set (const size_t &ncols, const size_t &nrows, const double &cellsize, const Coords &i_llcorner)
	Set all variables in one go. More...
void	set (const double &cellsize, const Coords &i_llcorner, const Array2D< double > &grid2D_in)
	Set all variables in one go. Notably the member grid2D of type Array2D<double> will be destroyed and recreated to size ncols x nrows. More...
void	set (const size_t &ncols, const size_t &nrows, const double &cellsize, const Coords &i_llcorner, const double &init)
void	set (const Grid2DObject &i_grid, const double &init)
void	rescale (const double &i_cellsize)
	Rescale (bilinear resampling) the grid to match the given cell size. More...
void	compute_spatial_mean (const double &radius)
	Spatially average the grid over a given radius. More...
void	size (size_t &o_ncols, size_t &o_nrows) const
size_t	size () const
size_t	getNx () const
size_t	getNy () const
double	getMin () const
double	getMax () const
double	getMean () const
void	clear ()
	deletes the data, but keeps geolocalization More...
bool	empty () const
	Check if a grid does not contain any data (but it can contain geolocalization) More...
bool	allNodata () const
bool	isSameGeolocalization (const Grid2DObject &target) const
	check if the current Grid2DObject has the same geolocalization attributes as another Grid2DObject (as well as same cells). The grid coordinates (xllcorner & yllcorner) are NOT checked as these might be tweaked for convenience (like between input grid and local grid) More...
void	binning (const std::vector< double > &thresholds, const std::vector< double > &ids)
	Partitional algorithm to classify each point of the grid into a 'bin'. The classification is given by a list of growing thresholds, the 'bins' are then a simple range of values. Threshold values will be put into the next higher bin. Each bin comes with an 'id' that replaces the values of the points. More...
std::vector< double >	extractPoints (const std::vector< std::pair< size_t, size_t > > &Pts) const
	extract point values from grid More...
Grid2DObject &	operator= (const double &value)
	Assignement operator. More...
Grid2DObject &	operator+= (const double &rhs)
const Grid2DObject	operator+ (const double &rhs) const
Grid2DObject &	operator+= (const Grid2DObject &rhs)
const Grid2DObject	operator+ (const Grid2DObject &rhs) const
Grid2DObject &	operator-= (const double &rhs)
const Grid2DObject	operator- (const double &rhs) const
Grid2DObject &	operator-= (const Grid2DObject &rhs)
const Grid2DObject	operator- (const Grid2DObject &rhs) const
Grid2DObject &	operator*= (const double &rhs)
const Grid2DObject	operator* (const double &rhs) const
Grid2DObject &	operator*= (const Grid2DObject &rhs)
const Grid2DObject	operator* (const Grid2DObject &rhs) const
Grid2DObject &	operator/= (const double &rhs)
const Grid2DObject	operator/ (const double &rhs) const
Grid2DObject &	operator/= (const Grid2DObject &rhs)
const Grid2DObject	operator/ (const Grid2DObject &rhs) const
bool	operator== (const Grid2DObject &in) const
	Operator that tests for equality. More...
bool	operator!= (const Grid2DObject &in) const
	Operator that tests for inequality. More...

Public Attributes
Array2D< double >	slope
Array2D< double >	azi
Array2D< double >	curvature
Array2D< double >	Nx
Array2D< double >	Ny
Array2D< double >	Nz
double	min_altitude
double	min_slope
double	min_curvature
double	max_altitude
double	max_slope
double	max_curvature
Public Attributes inherited from mio::Grid2DObject
Array2D< double >	grid2D
	the grid itself (simple 2D table containing the values for each point) More...
Coords	llcorner
	lower left corner of the grid More...
double	cellsize
	dimension in meters of a cell (considered to be square) More...

Friends
std::ostream &	operator<< (std::ostream &os, const DEMObject &dem)
std::istream &	operator>> (std::istream &is, DEMObject &dem)

Additional Inherited Members
Protected Member Functions inherited from mio::Grid2DObject
void	setValues (const double &cellsize, const Coords &i_llcorner)
bool	WGS84_to_grid (Coords &point) const
	Converts WGS84 coordinates into grid coordinates (i,j) More...
bool	grid_to_WGS84 (Coords &point) const
	Converts grid coordinates (i,j) into WGS84 coordinates. More...
bool	isLatlon () const
void	reproject ()
double	calculate_cellsize (const double &i_ur_lat, const double &i_ur_lon) const
void	setLatLon (const double &i_ur_lat, const double &i_ur_lon)
Static Protected Member Functions inherited from mio::Grid2DObject
static double	calculate_XYcellsize (const std::vector< double > &vecX, const std::vector< double > &vecY)
Protected Attributes inherited from mio::Grid2DObject
double	ur_lat
double	ur_lon
bool	isLatLon

Member Enumeration Documentation

FORMATS

enum mio::DEMObject::FORMATS

Keywords for selecting the toString formats.

Enumerator
FULL	Provide all the usually necessary information.
SHORT	Simplified, lat/lon only.

slope_type

enum mio::DEMObject::slope_type

Keywords for slope computation algorithm.

Enumerator
DFLT	whatever algorithm that has been defined as default
FLEM	four nearest neighbors (Fleming and Hoffer, 1979). It seems to be the same as (Zevenbergen and Thorne, 1987)
HICK	maximum downhill slope method (Dunn and Hickey, 1998)
HORN	eight neighbor algorithm (Horn, 1981) as used by ArcGIS. It seems to be the same as (Corripio, 2002) but for border cells.
CORR	surface normal vector using the two triangle method (Corripio, 2003) and eight-neighbor algorithm (Horn, 1981) for border cells
D8	discretized azimuth directions (angles for N, NE, etc) and slope rounded to nearest integer

update_type

enum mio::DEMObject::update_type

Keywords for automatic update of parameters. They can be combined with "|".

Enumerator
NO_UPDATE	no updates at all
SLOPE	update the slopes
NORMAL	update the normals
CURVATURE	update the curvatures
UPDATE_UNSET	property not set

Constructor & Destructor Documentation

DEMObject() [1/6]

mio::DEMObject::DEMObject

(

const slope_type &

i_algorithm = DFLT

)

Default constructor. Initializes all variables to 0, except lat/long which are initialized to IOUtils::nodata.

Parameters

i_algorithm

specify the default algorithm to use for slope computation (default=DFLT)

DEMObject() [2/6]

mio::DEMObject::DEMObject	(	const size_t &	ncols_in,
		const size_t &	nrows_in,
		const Coords &	llcorner_in,
		const double &	init
	)

Constructor that sets a constant DEM.

The resulting DEM will have the same elevation everywhere, constant slope (flat) and curvature (flat).

Parameters

ncols_in	number of colums in the grid2D
nrows_in	number of rows in the grid2D
llcorner_in	lower lower corner point
init	initial value to fill the DEM with

DEMObject() [3/6]

mio::DEMObject::DEMObject	(	const size_t &	i_ncols,
		const size_t &	i_nrows,
		const double &	i_cellsize,
		const Coords &	i_llcorner,
		const slope_type &	i_algorithm = DFLT
	)

Constructor that sets variables.

Parameters

i_ncols	number of colums in the grid2D
i_nrows	number of rows in the grid2D
i_cellsize	value for cellsize in grid2D
i_llcorner	lower lower corner point
i_algorithm	specify the default algorithm to use for slope computation (default=DFLT)

DEMObject() [4/6]

mio::DEMObject::DEMObject	(	const double &	i_cellsize,
		const Coords &	i_llcorner,
		const Array2D< double > &	i_altitude,
		const bool &	i_update = true,
		const slope_type &	i_algorithm = DFLT
	)

Constructor that sets variables.

Parameters

i_cellsize	value for cellsize in grid2D
i_llcorner	lower lower corner point
i_altitude	grid2D of elevations
i_update	also update slope/normals/curvatures and their min/max? (default=true)
i_algorithm	specify the default algorithm to use for slope computation (default=DFLT)

DEMObject() [5/6]

mio::DEMObject::DEMObject	(	const Grid2DObject &	i_dem,
		const bool &	i_update = true,
		const slope_type &	i_algorithm = DFLT
	)

Constructor that sets variables from a Grid2DObject.

Parameters

i_dem	grid contained in a Grid2DObject
i_update	also update slope/normals/curvatures and their min/max? (default=true)
i_algorithm	specify the default algorithm to use for slope computation (default=DFLT)

DEMObject() [6/6]

mio::DEMObject::DEMObject	(	const DEMObject &	i_dem,
		const size_t &	i_nx,
		const size_t &	i_ny,
		const size_t &	i_ncols,
		const size_t &	i_nrows,
		const bool &	i_update = true,
		const slope_type &	i_algorithm = DFLT
	)

Constructor that sets variables from a subset of another DEMObject, given an origin (X,Y) (first index being 0) and a number of columns and rows.

Parameters

i_dem	dem contained in a DEMDObject
i_nx	X coordinate of the new origin
i_ny	Y coordinate of the new origin
i_ncols	number of columns for the subset dem
i_nrows	number of rows for the subset dem
i_update	also update slope/normals/curvatures and their min/max? (default=true)
i_algorithm	specify the default algorithm to use for slope computation (default=DFLT)

Member Function Documentation

getDefaultAlgorithm()

int mio::DEMObject::getDefaultAlgorithm

(

)

const

Get the default slope calculation algorithm.

Returns

default algorithm to use for slope computation

getUpdatePpt()

int mio::DEMObject::getUpdatePpt

(

)

const

Get the properties that will be calculated by the object when updating.

Returns

combination of flags set with the binary "|" operator

operator!=()

bool mio::DEMObject::operator!=

(

const DEMObject &

in

)

const

Operator that tests for inequality.

operator*() [1/2]

const DEMObject mio::DEMObject::operator*

(

const double &

rhs

)

const

operator*() [2/2]

const DEMObject mio::DEMObject::operator*

(

const Grid2DObject &

rhs

)

const

operator*=() [1/2]

DEMObject & mio::DEMObject::operator*=

(

const double &

rhs

)

operator*=() [2/2]

DEMObject & mio::DEMObject::operator*=

(

const Grid2DObject &

rhs

)

operator+() [1/2]

const DEMObject mio::DEMObject::operator+

(

const double &

rhs

)

const

operator+() [2/2]

const DEMObject mio::DEMObject::operator+

(

const Grid2DObject &

rhs

)

const

operator+=() [1/2]

DEMObject & mio::DEMObject::operator+=

(

const double &

rhs

)

operator+=() [2/2]

DEMObject & mio::DEMObject::operator+=

(

const Grid2DObject &

rhs

)

operator-() [1/2]

const DEMObject mio::DEMObject::operator-

(

const double &

rhs

)

const

operator-() [2/2]

const DEMObject mio::DEMObject::operator-

(

const Grid2DObject &

rhs

)

const

operator-=() [1/2]

DEMObject & mio::DEMObject::operator-=

(

const double &

rhs

)

operator-=() [2/2]

DEMObject & mio::DEMObject::operator-=

(

const Grid2DObject &

rhs

)

operator/() [1/2]

const DEMObject mio::DEMObject::operator/

(

const double &

rhs

)

const

operator/() [2/2]

const DEMObject mio::DEMObject::operator/

(

const Grid2DObject &

rhs

)

const

operator/=() [1/2]

DEMObject & mio::DEMObject::operator/=

(

const double &

rhs

)

operator/=() [2/2]

DEMObject & mio::DEMObject::operator/=

(

const Grid2DObject &

rhs

)

operator=() [1/2]

DEMObject & mio::DEMObject::operator=

(

const double &

value

)

Assignement operator.

operator=() [2/2]

DEMObject & mio::DEMObject::operator=

(

const Grid2DObject &

)

Assignement operator.

operator==()

bool mio::DEMObject::operator==

(

const DEMObject &

in

)

const

Operator that tests for equality.

printFailures()

void mio::DEMObject::printFailures

(

)

Prints the list of points that have an elevation different than nodata but no slope or curvature Such points can happen if they are surrounded by too many points whose elevation is nodata If no such points exist, it prints nothing.

sanitize()

void mio::DEMObject::sanitize

(

)

Clean up the DEM Object When computing the slope and curvature, it is possible to get points where the elevation is known but where no slope/azimuth/normals/curvature could be computed. This method sets the elevation to nodata for such points, so that latter use of the DEM would be simpler (simply test the elevation in order to know if the point can be used and it guarantees that all other information is available).

Note

The update flags are used in order to know which properties should be checked. So if update_flag==SLOPE but there are curvatures and they are later used, they won't have been cleaned!

IMPORTANT: calling this method DOES change the table of elevations!

setCurvatureScale()

void mio::DEMObject::setCurvatureScale

(

const double &

in_curvature_scale

)

Set the curvature length scale for calculating curvature.

setDefaultAlgorithm() [1/2]

void mio::DEMObject::setDefaultAlgorithm

(

const slope_type &

i_algorithm

)

Sets the default slope calculation algorithm.

Parameters

i_algorithm

specify the default algorithm to use for slope computation

setDefaultAlgorithm() [2/2]

void mio::DEMObject::setDefaultAlgorithm

(

const std::string &

algorithm

)

Sets the default slope calculation algorithm.

Parameters

algorithm

specify the default algorithm to use for slope computation

setUpdatePpt()

void mio::DEMObject::setUpdatePpt

(

const update_type &

in_update_flag

)

Set the properties that will be calculated by the object when updating The following properties can be turned on/off: slope/azimuth and/or normals, and/or curvatures. Flags are combined using the binary "|" operator.

Parameters

in_update_flag

parameters to update

toString()

const std::string mio::DEMObject::toString

(

const FORMATS &

type = FULL

)

const

update() [1/2]

void mio::DEMObject::update

(

const slope_type &

algorithm = DFLT

)

Force the computation of the local slope, azimuth, normal vector and curvature. It has to be called manually since it can require some time to compute. Without this call, the above mentionned parameters are NOT up to date.

Parameters

algorithm

algorithm to use for computing slope, azimuth and normals

update() [2/2]

void mio::DEMObject::update

(

const std::string &

algorithm

)

Force the computation of the local slope, azimuth, normal vector and curvature. It has to be called manually since it can require some time to compute. Without this call, the above mentionned parameters are NOT up to date.

Parameters

algorithm

algorithm to use for computing slope, azimuth and normals it is either: HICK that uses the maximum downhill slope method (Dunn and Hickey, 1998) FLEMING uses a 4 neighbors algorithm (Fleming and Hoffer, 1979) CORRIPIO that uses the surface normal vector using the two triangle method given in Corripio (2002) and the eight-neighbor algorithm of Horn (1981) for border cells. D8 uses CORRIPIO but discretizes the resulting azimuth to 8 cardinal directions and the slope is rounded to the nearest degree. Curvature and normals are left untouched.

The azimuth is always computed using the Hodgson (1998) algorithm.

updateAllMinMax()

void mio::DEMObject::updateAllMinMax

(

)

Recomputes the min/max of altitude, slope and curvature It returns +/- std::numeric_limits<double> ::max() for a given parameter if its grid was empty/undefined.

Friends And Related Function Documentation

operator<<

std::ostream & operator<< ( std::ostream &  os, const DEMObject &  dem  )

friend

operator>>

std::istream & operator>> ( std::istream &  is, DEMObject &  dem  )

friend

Member Data Documentation

azi

Array2D<double> mio::DEMObject::azi

curvature

Array2D<double> mio::DEMObject::curvature

max_altitude

double mio::DEMObject::max_altitude

max_curvature

double mio::DEMObject::max_curvature

max_slope

double mio::DEMObject::max_slope

min_altitude

double mio::DEMObject::min_altitude

min_curvature

double mio::DEMObject::min_curvature

min_slope

double mio::DEMObject::min_slope

Nx

Array2D<double> mio::DEMObject::Nx

Ny

Array2D<double> mio::DEMObject::Ny

Nz

Array2D<double> mio::DEMObject::Nz

slope

Array2D<double> mio::DEMObject::slope

---

The documentation for this class was generated from the following files:

• DEMObject.h
• DEMObject.cc