Clarify units for the DEM classes (#595)

* Avoid users asking whether the height and elevation functions are the
  same
* Match common conventions like in GDAL to refer to things in "raster"
  coordinates with "pixels" indicating each point on a DEM
* https://gdal.org/tutorials/raster_api_tut.html

Signed-off-by: Ryan Friedman <[email protected]>

Author: Ryanf55

geospatial/include/gz/common/geospatial/Dem.hh

@@ -58,8 +58,8 @@ namespace gz
       public: int Load(const std::string &_filename = "");
 
       /// \brief Get the elevation of a terrain's point in meters.
-      /// \param[in] _x X coordinate of the terrain.
-      /// \param[in] _y Y coordinate of the terrain.
+      /// \param[in] _x X coordinate of the terrain in raster coordinates.
+      /// \param[in] _y Y coordinate of the terrain in raster coordinates.
       /// \return Terrain's elevation at (x,y) in meters or infinity if illegal
       /// coordinates were provided.
       public: double Elevation(double _x, double _y);

geospatial/include/gz/common/geospatial/HeightmapData.hh

@@ -37,7 +37,7 @@ namespace gz
       /// Ex: A subsampling of 2 in a terrain of 129x129 means that the height
       /// vector will be 257 * 257.
       /// \param[in] _vertSize Number of points per row.
-      /// \param[in] _size Real dimmensions of the terrain.
+      /// \param[in] _size Real dimensions of the terrain.
       /// \param[in] _scale Vector3 used to scale the height.
       /// \param[in] _flipY If true, it inverts the order in which the vector
       /// is filled.
@@ -48,11 +48,11 @@ namespace gz
           std::vector<float> &_heights) const = 0;
 
       /// \brief Get the terrain's height.
-      /// \return The terrain's height.
+      /// \return The terrain's height [pixels].
       public: virtual unsigned int Height() const = 0;
 
       /// \brief Get the terrain's width.
-      /// \return The terrain's width.
+      /// \return The terrain's width [pixels].
       public: virtual unsigned int Width() const = 0;
 
       /// \brief Get the maximum terrain's elevation.