From: Andy Spencer Date: Mon, 8 Feb 2010 22:26:51 +0000 (+0000) Subject: Document gis-util X-Git-Tag: v0.4~64 X-Git-Url: http://pileus.org/git/?p=grits;a=commitdiff_plain;h=6cbd796209e724ddff668447337069539498c243 Document gis-util --- diff --git a/src/gis-util.c b/src/gis-util.c index c25b57c..587dd5c 100644 --- a/src/gis-util.c +++ b/src/gis-util.c @@ -15,6 +15,59 @@ * along with this program. If not, see . */ +/** + * 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. + * + * + * Terminology + * + * 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 + * + * + * + * + * Conversions + * + * 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 + * + * + */ + #include #include @@ -23,6 +76,18 @@ /****************** * 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) { @@ -34,6 +99,18 @@ void lle2xyz(gdouble lat, gdouble lon, gdouble elev, *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) { @@ -43,6 +120,16 @@ void xyz2lle(gdouble x, gdouble y, gdouble z, *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) { @@ -51,6 +138,15 @@ void xyz2ll(gdouble x, gdouble y, gdouble 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; @@ -59,6 +155,15 @@ gdouble ll2m(gdouble lon_dist, gdouble lat) 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]) + @@ -66,6 +171,16 @@ gdouble distd(gdouble *a, gdouble *b) (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); diff --git a/src/gis-util.h b/src/gis-util.h index 234bb16..c783896 100644 --- a/src/gis-util.h +++ b/src/gis-util.h @@ -20,62 +20,150 @@ #include +/** + * EARTH_R: + * + * Radius of the earth + */ #define EARTH_R (6371000) + +/** + * EARTH_C: + * + * Circumference of the earth at the equator + */ #define EARTH_C (2*G_PI*EARTH_R) + +/** + * NORTH: + * + * Latitude at the north poll + */ #define NORTH 90 + +/** + * SOUTH: + * + * Latitude at the south poll + */ #define SOUTH -90 + +/** + * EAST: + * + * Eastern most longitude + */ #define EAST 180 + +/** + * WEST: + * + * Western most longitude + */ #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) + +/** + * lat2incl: + * @lat: the latitude + * + * Convert latitude to inclination + * + * Returns: the inclination in radians + */ #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) + +/** + * 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) +/** + * deg2rad: + * @deg: the angle in degrees + * + * Convert degrees to radians + * + * Returns: the angle in radians + */ #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) + +/******** + * Misc * + ********/ +/** + * FOV_DIST: + * + * Used by GisOpenGL to set up the drawing window + */ #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,