[GRASS-SVN] r58164 - grass/branches/develbranch_6/lib/gis

[svn_grass at osgeo.org]

Author: neteler
Date: 2013-11-07 04:12:02 -0800 (Thu, 07 Nov 2013)
New Revision: 58164

Modified:
   grass/branches/develbranch_6/lib/gis/area_poly1.c
Log:
area_poly1.c function documentation improved (contributed by Richard Roger richard.roger at water dot nsw dot gov dot au)

Modified: grass/branches/develbranch_6/lib/gis/area_poly1.c
===================================================================
--- grass/branches/develbranch_6/lib/gis/area_poly1.c	2013-11-07 12:11:06 UTC (rev 58163)
+++ grass/branches/develbranch_6/lib/gis/area_poly1.c	2013-11-07 12:12:02 UTC (rev 58164)
@@ -1,10 +1,9 @@
-
 /**
  * \file area_poly1.c
  *
  * \brief GIS Library - Polygon area calculation routines.
  *
- * (C) 2001-2008 by the GRASS Development Team
+ * (C) 2001-2013 by the GRASS Development Team
  *
  * This program is free software under the GNU General Public License
  * (>=v2). Read the file COPYING that comes with GRASS for details.
@@ -18,7 +17,6 @@
 #include <grass/gis.h>
 #include "pi.h"
 
-
 #define TWOPI M_PI + M_PI
 
 static double QA, QB, QC;
@@ -98,9 +96,32 @@
  * <b>n</b> pairs of <b>lat,long</b> vertices for latitude-longitude 
  * grids.
  * <br>
- * <b>Note:</b> This routine assumes grid lines on the connecting the 
- * vertices (as opposed to geodesics).
+ * <b>Note:</b> This routine computes the area of a polygon on the
+ * ellipsoid.  The sides of the polygon are rhumb lines and, in general,
+ * not geodesics.  Each side is actually defined by a linear relationship
+ * between latitude and longitude, i.e., on a rectangular/equidistant
+ * cylindrical/Plate Carr{'e}e grid, the side would appear as a
+ * straight line.  For two consecutive vertices of the polygon, 
+ * (lat_1, long1) and (lat_2,long_2), the line joining them (i.e., the
+ * polygon's side) is defined by:
+ *                                     lat_2  -  lat_1 
+ *     lat = lat_1 + (long - long_1) * ---------------
+ *                                     long_2 - long_1
+ * where long_1 < long < long_2.
+ *   The values of QbarA, etc., are determined by the integration of
+ * the Q function.  Into www.integral-calculator.com, paste this 
+ * expression :
  *
+ * sin(x)+ (2/3)e^2(sin(x))^3 + (3/5)e^4(sin(x))^5 + (4/7)e^6(sin(x))^7
+ *
+ * and you'll get their values.  (Last checked 30 Oct 2013). 
+ *
+ * This function correctly computes (within the limits of the series
+ * approximation) the area of a quadrilateral on the ellipsoid when
+ * two of its sides run along meridians and the other two sides run
+ * along parallels of latitude.
+
+ *
  * \param[in] lon array of longitudes
  * \param[in] lat array of latitudes
  * \param[in] n number of lat,lon pairs