Document gis-util

diff --git a/src/gis-util.c b/src/gis-util.c
index c25b57c4ed0116902b7a06457d60a76011ab401c..587dd5c10d26e3418a1d80b0ef6c282d37117011 100644 (file)
--- a/src/gis-util.c
+++ b/src/gis-util.c
@@ -15,6 +15,59 @@
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 
  * along with this program.  If not, see <http://www.gnu.org/licenses/>.
  */
 

+/**
+ * SECTION:gis-util
+ * @short_description: Geographic utilities
+ *
+ * Miscellaneous utility functions, these deal mostly with coordinate
+ * conversion. Below are some examples that should help demonstrate how these
+ * functions work.
+ *
+ * <example>
+ * <title>Terminology</title>
+ * <programlisting>
+ * deg    - Degrees
+ * rad    - Radians, also radius
+ * m      - Meters, for earth-based distances
+ * px     - Pixels, for screen-based distances
+ *
+ * height - Height, the distance above the geoid (ground)
+ * elev   - Elevation, the distance above the spheroid
+ * rad    - Radius, the distance from the center of the earth
+ *
+ * lat    - Latitude, amount north-south, -90 (S) .. 90 (N)
+ * lon    - Longitude, amount east-west, -180 (W) .. 180 (E)
+ * incl   - Inclination, polar equiv of  latitude, Pi .. 0
+ * azim   - Azimuth, polar equiv of longitude, -Pi .. Pi
+ *
+ * x      -  0° lon is positive
+ * y      - 90° lon is positive
+ * z      - North pole is positive
+ *
+ * llh    - lat,lon,height
+ * lle    - lat,lon,elev
+ * llr    - lat,lon,rad
+ * pol    - incl,azim,rad
+ * xyz    - x,y,z
+ * </programlisting>
+ * </example>
+ *
+ * <example>
+ * <title>Conversions</title>
+ * <programlisting>
+ *             lat    lon   elev ->      x      y      z
+ * lle2xyz:    0.0,   0.0,   0.0 ->    0.0,   0.0,  10.0
+ * lle2xyz:   90.0,   0.0,   0.0 ->    0.0,  10.0,   0.0
+ * lle2xyz:    0.0,  90.0,   0.0 ->   10.0,   0.0,   0.0
+ *
+ *               x      y      z ->    lat    lon   elev
+ * xyz2lle:   10.0,   0.0,   0.0 ->    0.0,  90.0,   0.0
+ * xyz2lle:    0.0,  10.0,   0.0 ->   90.0,   0.0,   0.0
+ * xyz2lle:    0.0,   0.0,  10.0 ->    0.0,   0.0,   0.0
+ * </programlisting>
+ * </example>
+ */
+

 #include <glib.h>
 #include <math.h>
 
 #include <glib.h>
 #include <math.h>
 


@@ -23,6 +76,18 @@
 /******************
  * Global helpers *
  ******************/
 /******************
  * Global helpers *
  ******************/

+/**
+ * lle2xyz:
+ * @lat:  the latitude
+ * @lon:  the longitude
+ * @elev: the elevation
+ * @x:    the resulting x coordinate
+ * @y:    the resulting y coordinate
+ * @z:    the resulting z coordinate
+ *
+ * Convert a point from latitude, longitude, and elevation to x, y and z
+ * coordinates.
+ */

 void lle2xyz(gdouble lat, gdouble lon, gdouble elev,
                gdouble *x, gdouble *y, gdouble *z)
 {
 void lle2xyz(gdouble lat, gdouble lon, gdouble elev,
                gdouble *x, gdouble *y, gdouble *z)
 {


@@ -34,6 +99,18 @@ void lle2xyz(gdouble lat, gdouble lon, gdouble elev,
        *y = rad * cos(incl);
 }
 
        *y = rad * cos(incl);
 }
 

+/**
+ * xyz2lle:
+ * @x:    the x coordinate
+ * @y:    the y coordinate
+ * @z:    the z coordinate
+ * @lat:  the resulting latitude
+ * @lon:  the resulting longitude
+ * @elev: the resulting elevation
+ *
+ * Convert a point from x, y and z coordinates to latitude, longitude, and
+ * elevation.
+ */

 void xyz2lle(gdouble x, gdouble y, gdouble z,
                gdouble *lat, gdouble *lon, gdouble *elev)
 {
 void xyz2lle(gdouble x, gdouble y, gdouble z,
                gdouble *lat, gdouble *lon, gdouble *elev)
 {


@@ -43,6 +120,16 @@ void xyz2lle(gdouble x, gdouble y, gdouble z,
        *elev = rad2elev(rad);
 }
 
        *elev = rad2elev(rad);
 }
 

+/**
+ * xyz2ll:
+ * @x:    the x coordinate
+ * @y:    the y coordinate
+ * @z:    the z coordinate
+ * @lat:  the resulting latitude
+ * @lon:  the resulting longitude
+ *
+ * Get the latitude and longitude for a x, y, z value.
+ */

 void xyz2ll(gdouble x, gdouble y, gdouble z,
                gdouble *lat, gdouble *lon)
 {
 void xyz2ll(gdouble x, gdouble y, gdouble z,
                gdouble *lat, gdouble *lon)
 {


@@ -51,6 +138,15 @@ void xyz2ll(gdouble x, gdouble y, gdouble z,
        *lon = azim2lon(atan2(x,z));
 }
 
        *lon = azim2lon(atan2(x,z));
 }
 

+/**
+ * ll2m:
+ * @lon_dist: the distance in degrees of longitude
+ * @lat:      the latitude to calculate at
+ *
+ * Calculate the distance of longitudinal span at a particular latitude. 
+ *
+ * Returns: the distance in meters
+ */

 gdouble ll2m(gdouble lon_dist, gdouble lat)
 {
        gdouble azim = (-lat+90)/180*M_PI;
 gdouble ll2m(gdouble lon_dist, gdouble lat)
 {
        gdouble azim = (-lat+90)/180*M_PI;


@@ -59,6 +155,15 @@ gdouble ll2m(gdouble lon_dist, gdouble lat)
        return lon_dist/360 * circ;
 }
 
        return lon_dist/360 * circ;
 }
 

+/**
+ * distd:
+ * @a: the first point
+ * @b: the second point
+ *
+ * Calculate the distance between two three dimensional points.
+ *
+ * Returns: the distance between the points
+ */

 gdouble distd(gdouble *a, gdouble *b)
 {
        return sqrt((a[0]-b[0])*(a[0]-b[0]) +
 gdouble distd(gdouble *a, gdouble *b)
 {
        return sqrt((a[0]-b[0])*(a[0]-b[0]) +


@@ -66,6 +171,16 @@ gdouble distd(gdouble *a, gdouble *b)
                    (a[2]-b[2])*(a[2]-b[2]));
 }
 
                    (a[2]-b[2])*(a[2]-b[2]));
 }
 

+/**
+ * lon_avg:
+ * @a: the first longitude
+ * @b: the second longitude
+ *
+ * Calculate the average longitude between two longitudes. This is smart about
+ * which side of the globe the resulting longitude is placed on.
+ *
+ * Returns: the average
+ */

 gdouble lon_avg(gdouble a, gdouble b)
 {
        gdouble diff = ABS(a-b);
 gdouble lon_avg(gdouble a, gdouble b)
 {
        gdouble diff = ABS(a-b);

diff --git a/src/gis-util.h b/src/gis-util.h
index 234bb16b84f091dd4a365774adb88aa5a3fdc242..c7838966709f9c74f8cb5a3de23b54f9b486280f 100644 (file)
--- a/src/gis-util.h
+++ b/src/gis-util.h
@@ -20,62 +20,150 @@
 
 #include <glib.h>
 
 
 #include <glib.h>
 

+/**
+ * EARTH_R:
+ *
+ * Radius of the earth
+ */

 #define EARTH_R (6371000)
 #define EARTH_R (6371000)

+
+/**
+ * EARTH_C:
+ *
+ * Circumference of the earth at the equator
+ */

 #define EARTH_C (2*G_PI*EARTH_R)
 #define EARTH_C (2*G_PI*EARTH_R)

+
+/**
+ * NORTH:
+ *
+ * Latitude at the north poll
+ */

 #define NORTH  90
 #define NORTH  90

+
+/**
+ * SOUTH:
+ *
+ * Latitude at the south poll
+ */

 #define SOUTH -90
 #define SOUTH -90

+
+/**
+ * EAST:
+ *
+ * Eastern most longitude
+ */

 #define EAST  180
 #define EAST  180

+
+/**
+ * WEST:
+ *
+ * Western most longitude
+ */

 #define WEST -180
 
 #define WEST -180
 

+/***************
+ * Conversions *
+ ***************/

 /**
 /**

- * Terms
- * -----
- * deg    - Degrees
- * rad    - Radians, also radius
- * m      - Meters, for earth-based distances
- * px     - Pixels, for screen-based distances
+ * azim2lon:
+ * @azim: the azimuth in radians

  *
  *

- * height - Height, the distance above the geoid (ground)
- * elev   - Elevation, the distance above the spheroid
- * rad    - Radius, the distance from the center of the earth
+ * Convert azimuth to longitude

  *
  *

- * lat    - Latitude, amount north-south, -90 (S) .. 90 (N)
- * lon    - Longitude, amount east-west, -180 (W) .. 180 (E)
- * incl   - Inclination, polar equiv of  latitude, Pi .. 0
- * azim   - Azimuth, polar equiv of longitude, -Pi .. Pi
+ * Returns: the longitude 
+ */
+#define azim2lon(azim) ((azim)*180/G_PI)
+
+/**
+ * lon2azim:
+ * @lon: the longitude

  *
  *

- * x      -  0° lon is positive
- * y      - 90° lon is positive
- * z      - North pole is positive
+ * Convert longitude to azimuth 

  *
  *

- * llh    - lat,lon,height
- * lle    - lat,lon,elev
- * llr    - lat,lon,rad
- * pol    - incl,azim,rad
- * xyz    - x,y,z
+ * Returns: the azimuth in radians

  */
  */

+#define lon2azim(lon)  ((lon)*G_PI/180)

 
 /**
 
 /**

- *             lat    lon   elev ->      x      y      z
- * lle2xyz:    0.0,   0.0,   0.0 ->    0.0,   0.0,  10.0
- * lle2xyz:   90.0,   0.0,   0.0 ->    0.0,  10.0,   0.0
- * lle2xyz:    0.0,  90.0,   0.0 ->   10.0,   0.0,   0.0
+ * incl2lat:
+ * @incl: the inclination in radians

  *
  *

- *               x      y      z ->    lat    lon   elev
- * xyz2lle:   10.0,   0.0,   0.0 ->    0.0,  90.0,   0.0
- * xyz2lle:    0.0,  10.0,   0.0 ->   90.0,   0.0,   0.0
- * xyz2lle:    0.0,   0.0,  10.0 ->    0.0,   0.0,   0.0
+ * Convert inclination to latitude
+ *
+ * Returns: the latitude

  */
  */

-

 #define incl2lat(incl) (90-(incl)*180/G_PI)
 #define incl2lat(incl) (90-(incl)*180/G_PI)

+
+/**
+ * lat2incl:
+ * @lat: the latitude
+ *
+ * Convert latitude to inclination
+ *
+ * Returns: the inclination in radians
+ */

 #define lat2incl(lat)  ((90-(lat))*G_PI/180)
 #define lat2incl(lat)  ((90-(lat))*G_PI/180)

+
+/**
+ * rad2elev:
+ * @rad: the radius in meters
+ *
+ * Convert radius to elevation
+ *
+ * Returns: the elevation in meters above the earth surface
+ */

 #define rad2elev(rad)  ((rad)-EARTH_R)
 #define rad2elev(rad)  ((rad)-EARTH_R)

+
+/**
+ * elev2rad:
+ * @elev: the elevation in meters above the earth surface
+ *
+ * Convert elevation to radius
+ *
+ * Returns: the radius in meters
+ */

 #define elev2rad(elev) ((elev)+EARTH_R)
 
 #define elev2rad(elev) ((elev)+EARTH_R)
 

+/**
+ * deg2rad:
+ * @deg: the angle in degrees
+ *
+ * Convert degrees to radians
+ *
+ * Returns: the angle in radians
+ */

 #define deg2rad(deg) (((deg)*G_PI)/180.0)
 #define deg2rad(deg) (((deg)*G_PI)/180.0)

+
+/**
+ * rad2deg:
+ * @rad: the angle in radians
+ *
+ * Convert radians to degrees
+ *
+ * Returns: the angle in degrees
+ */

 #define rad2deg(rad) (((rad)*180.0)/G_PI)
 
 #define rad2deg(rad) (((rad)*180.0)/G_PI)
 

+
+/********
+ * Misc *
+ ********/
+/**
+ * FOV_DIST:
+ *
+ * Used by GisOpenGL to set up the drawing window
+ */

 #define FOV_DIST   2000.0
 #define FOV_DIST   2000.0

+
+/**
+ * MPPX:
+ * @dist: the distance between the eye and the point in question
+ *
+ * Get the resolution that a point would be drawn at on the screen
+ *
+ * Returns: the resolution in meters per pixel
+ */

 #define MPPX(dist) (4*dist/FOV_DIST)
 
 void lle2xyz(gdouble lat, gdouble lon, gdouble elev,
 #define MPPX(dist) (4*dist/FOV_DIST)
 
 void lle2xyz(gdouble lat, gdouble lon, gdouble elev,