MeteoIODoc  MeteoIODoc-2.6.0
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
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 }
 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 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 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 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 return +/- 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 informations are available).If the slope/azimuth/normals/curvature tables were manually updated, this method will NOT perform any work (it requires the count of slopes/curvature failures to be greater than zero) More...
 
Grid2DObject getHillshade (const double &elev=38., const double &azimuth=0.) const
 Computes the hillshade for the dem This "fake illumination" method is used to better show the relief on maps. More...
 
double getHorizon (const size_t &ix1, const size_t &iy1, const double &bearing) const
 Returns the tangente of the horizon from a given point looking toward a given bearing. More...
 
double getHorizon (const Coords &point, const double &bearing) const
 Returns the tangente of the horizon from a given point looking toward a given bearing. More...
 
void getHorizon (const Coords &point, const double &increment, std::vector< std::pair< double, double > > &horizon) const
 Returns the horizon from a given point looking 360 degrees around by increments. More...
 
double getCellSkyViewFactor (const size_t &ii, const size_t &jj) const
 Compute the sky view factors for the terrain radiation based on the DEM. This is based on Manners, J., S. B. Vosper, and N. Roberts, "Radiative transfer over resolved topographic features for high‐resolution weather prediction", Quarterly journal of the royal meteorological society, 138.664, pp720-733, 2012. More...
 
DEMObjectoperator= (const Grid2DObject &)
 Assignement operator. More...
 
DEMObjectoperator= (const double &value)
 Assignement operator. More...
 
DEMObjectoperator+= (const double &rhs)
 
const DEMObject operator+ (const double &rhs) const
 
DEMObjectoperator+= (const Grid2DObject &rhs)
 
const DEMObject operator+ (const Grid2DObject &rhs) const
 
DEMObjectoperator-= (const double &rhs)
 
const DEMObject operator- (const double &rhs) const
 
DEMObjectoperator-= (const Grid2DObject &rhs)
 
const DEMObject operator- (const Grid2DObject &rhs) const
 
DEMObjectoperator*= (const double &rhs)
 
const DEMObject operator* (const double &rhs) const
 
DEMObjectoperator*= (const Grid2DObject &rhs)
 
const DEMObject operator* (const Grid2DObject &rhs) const
 
DEMObjectoperator/= (const double &rhs)
 
const DEMObject operator/ (const double &rhs) const
 
DEMObjectoperator/= (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)
 
virtual ~Grid2DObject ()
 
 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...
 
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 size (size_t &o_ncols, size_t &o_nrows) const
 
size_t size () const
 
size_t getNx () const
 
size_t getNy () 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 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...
 
bool clusterization (const std::vector< double > &thresholds, const std::vector< double > &ids)
 Partitional algorithm to classify each point of the grid. The classification is given by a list of growing thresholds, the 'clusters' are then a simple range of values. Each cluster comes with an 'id' that replaces the values of the points. More...
 
Grid2DObjectoperator= (const Grid2DObject &)
 Assignement operator. More...
 
Grid2DObjectoperator= (const double &value)
 Assignement operator. More...
 
Grid2DObjectoperator+= (const double &rhs)
 
const Grid2DObject operator+ (const double &rhs) const
 
Grid2DObjectoperator+= (const Grid2DObject &rhs)
 
const Grid2DObject operator+ (const Grid2DObject &rhs) const
 
Grid2DObjectoperator-= (const double &rhs)
 
const Grid2DObject operator- (const double &rhs) const
 
Grid2DObjectoperator-= (const Grid2DObject &rhs)
 
const Grid2DObject operator- (const Grid2DObject &rhs) const
 
Grid2DObjectoperator*= (const double &rhs)
 
const Grid2DObject operator* (const double &rhs) const
 
Grid2DObjectoperator*= (const Grid2DObject &rhs)
 
const Grid2DObject operator* (const Grid2DObject &rhs) const
 
Grid2DObjectoperator/= (const double &rhs)
 
const Grid2DObject operator/ (const double &rhs) const
 
Grid2DObjectoperator/= (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::iostream & operator<< (std::iostream &os, const DEMObject &dem)
 
std::iostream & operator>> (std::iostream &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...
 

Member Enumeration Documentation

Keywords for selecting the toString formats.

Enumerator
FULL 

Provide all the usually necessary information.

SHORT 

Simplified, lat/lon only.

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

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

Constructor & Destructor Documentation

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_algorithmspecify the default algorithm to use for slope computation (default=DFLT)
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_ncolsnumber of colums in the grid2D
i_nrowsnumber of rows in the grid2D
i_cellsizevalue for cellsize in grid2D
i_llcornerlower lower corner point
i_algorithmspecify the default algorithm to use for slope computation (default=DFLT)
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_cellsizevalue for cellsize in grid2D
i_llcornerlower lower corner point
i_altitudegrid2D of elevations
i_updatealso update slope/normals/curvatures and their min/max? (default=true)
i_algorithmspecify the default algorithm to use for slope computation (default=DFLT)
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_demgrid contained in a Grid2DObject
i_updatealso update slope/normals/curvatures and their min/max? (default=true)
i_algorithmspecify the default algorithm to use for slope computation (default=DFLT)
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_demdem contained in a DEMDObject
i_nxX coordinate of the new origin
i_nyY coordinate of the new origin
i_ncolsnumber of columns for the subset dem
i_nrowsnumber of rows for the subset dem
i_updatealso update slope/normals/curvatures and their min/max? (default=true)
i_algorithmspecify the default algorithm to use for slope computation (default=DFLT)

Member Function Documentation

double mio::DEMObject::getCellSkyViewFactor ( const size_t &  ii,
const size_t &  jj 
) const

Compute the sky view factors for the terrain radiation based on the DEM. This is based on Manners, J., S. B. Vosper, and N. Roberts, "Radiative transfer over resolved topographic features for high‐resolution weather prediction", Quarterly journal of the royal meteorological society, 138.664, pp720-733, 2012.

Parameters
iix coordinate of the cell whose view factor should be computed
jjy coordinate of the cell whose view factor should be computed
Returns
sky view factor
int mio::DEMObject::getDefaultAlgorithm ( ) const

Get the default slope calculation algorithm.

Returns
default algorithm to use for slope computation
Grid2DObject mio::DEMObject::getHillshade ( const double &  elev = 38.,
const double &  azimuth = 0. 
) const

Computes the hillshade for the dem This "fake illumination" method is used to better show the relief on maps.

Parameters
elevelevation (in degrees) of the source of light
azimuthazimuth (in degrees) of the source of light
Returns
hillshade grid that containing the illumination
double mio::DEMObject::getHorizon ( const size_t &  ix1,
const size_t &  iy1,
const double &  bearing 
) const

Returns the tangente of the horizon from a given point looking toward a given bearing.

Parameters
ix1x index of the origin point
iy1y index of the origin point
bearingdirection given by a compass bearing
Returns
tangente of angle above the horizontal (in deg)
double mio::DEMObject::getHorizon ( const Coords point,
const double &  bearing 
) const

Returns the tangente of the horizon from a given point looking toward a given bearing.

Parameters
pointthe origin point
bearingdirection given by a compass bearing
Returns
tangente of angle above the horizontal (in deg)
void mio::DEMObject::getHorizon ( const Coords point,
const double &  increment,
std::vector< std::pair< double, double > > &  horizon 
) const

Returns the horizon from a given point looking 360 degrees around by increments.

Parameters
pointthe origin point
incrementto the bearing between two angles
horizonvector of heights above a given angle
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
bool mio::DEMObject::operator!= ( const DEMObject in) const

Operator that tests for inequality.

const DEMObject mio::DEMObject::operator* ( const double &  rhs) const
const DEMObject mio::DEMObject::operator* ( const Grid2DObject rhs) const
DEMObject & mio::DEMObject::operator*= ( const double &  rhs)
DEMObject & mio::DEMObject::operator*= ( const Grid2DObject rhs)
const DEMObject mio::DEMObject::operator+ ( const double &  rhs) const
const DEMObject mio::DEMObject::operator+ ( const Grid2DObject rhs) const
DEMObject & mio::DEMObject::operator+= ( const double &  rhs)
DEMObject & mio::DEMObject::operator+= ( const Grid2DObject rhs)
const DEMObject mio::DEMObject::operator- ( const double &  rhs) const
const DEMObject mio::DEMObject::operator- ( const Grid2DObject rhs) const
DEMObject & mio::DEMObject::operator-= ( const double &  rhs)
DEMObject & mio::DEMObject::operator-= ( const Grid2DObject rhs)
const DEMObject mio::DEMObject::operator/ ( const double &  rhs) const
const DEMObject mio::DEMObject::operator/ ( const Grid2DObject rhs) const
DEMObject & mio::DEMObject::operator/= ( const double &  rhs)
DEMObject & mio::DEMObject::operator/= ( const Grid2DObject rhs)
DEMObject& mio::DEMObject::operator= ( const Grid2DObject )

Assignement operator.

DEMObject & mio::DEMObject::operator= ( const double &  value)

Assignement operator.

bool mio::DEMObject::operator== ( const DEMObject in) const

Operator that tests for equality.

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.

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 informations are available).If the slope/azimuth/normals/curvature tables were manually updated, this method will NOT perform any work (it requires the count of slopes/curvature failures to be greater than zero)

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

void mio::DEMObject::setDefaultAlgorithm ( const slope_type i_algorithm)

Sets the default slope calculation algorithm.

Parameters
i_algorithmspecify the default algorithm to use for slope computation
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_flagparameters to update
const std::string mio::DEMObject::toString ( const FORMATS type = FULL) const
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
algorithmalgorithm 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.

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
algorithmalgorithm to use for computing slope, azimuth and normals
void mio::DEMObject::updateAllMinMax ( )

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

Friends And Related Function Documentation

std::iostream& operator<< ( std::iostream &  os,
const DEMObject dem 
)
friend
std::iostream& operator>> ( std::iostream &  is,
DEMObject dem 
)
friend

Member Data Documentation

Array2D<double> mio::DEMObject::azi
Array2D<double> mio::DEMObject::curvature
double mio::DEMObject::max_altitude
double mio::DEMObject::max_curvature
double mio::DEMObject::max_slope
double mio::DEMObject::min_altitude
double mio::DEMObject::min_curvature
double mio::DEMObject::min_slope
Array2D<double> mio::DEMObject::Nx
Array2D<double> mio::DEMObject::Ny
Array2D<double> mio::DEMObject::Nz
Array2D<double> mio::DEMObject::slope

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