2 * Copyright (C) 2009-2010 Andy Spencer <andy753421@gmail.com>
4 * This program is free software: you can redistribute it and/or modify
5 * it under the terms of the GNU General Public License as published by
6 * the Free Software Foundation, either version 3 of the License, or
7 * (at your option) any later version.
9 * This program is distributed in the hope that it will be useful,
10 * but WITHOUT ANY WARRANTY; without even the implied warranty of
11 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
12 * GNU General Public License for more details.
14 * You should have received a copy of the GNU General Public License
15 * along with this program. If not, see <http://www.gnu.org/licenses/>.
20 * @short_description: Geographic utilities
22 * Miscellaneous utility functions, these deal mostly with coordinate
23 * conversion. Below are some examples that should help demonstrate how these
27 * <title>Terminology</title>
30 * rad - Radians, also radius
31 * m - Meters, for earth-based distances
32 * px - Pixels, for screen-based distances
34 * height - Height, the distance above the geoid (ground)
35 * elev - Elevation, the distance above the spheroid
36 * rad - Radius, the distance from the center of the earth
38 * lat - Latitude, amount north-south, -90 (S) .. 90 (N)
39 * lon - Longitude, amount east-west, -180 (W) .. 180 (E)
40 * incl - Inclination, polar equiv of latitude, Pi .. 0
41 * azim - Azimuth, polar equiv of longitude, -Pi .. Pi
43 * x - 0° lon is positive
44 * y - 90° lon is positive
45 * z - North pole is positive
47 * llh - lat,lon,height
56 * <title>Conversions</title>
58 * lat lon elev -> x y z
59 * lle2xyz: 0.0, 0.0, 0.0 -> 0.0, 0.0, 10.0
60 * lle2xyz: 90.0, 0.0, 0.0 -> 0.0, 10.0, 0.0
61 * lle2xyz: 0.0, 90.0, 0.0 -> 10.0, 0.0, 0.0
63 * x y z -> lat lon elev
64 * xyz2lle: 10.0, 0.0, 0.0 -> 0.0, 90.0, 0.0
65 * xyz2lle: 0.0, 10.0, 0.0 -> 90.0, 0.0, 0.0
66 * xyz2lle: 0.0, 0.0, 10.0 -> 0.0, 0.0, 0.0
83 * @elev: the elevation
84 * @x: the resulting x coordinate
85 * @y: the resulting y coordinate
86 * @z: the resulting z coordinate
88 * Convert a point from latitude, longitude, and elevation to x, y and z
91 void lle2xyz(gdouble lat, gdouble lon, gdouble elev,
92 gdouble *x, gdouble *y, gdouble *z)
94 gdouble rad = elev2rad(elev);
95 gdouble azim = lon2azim(lon);
96 gdouble incl = lat2incl(lat);
97 *z = rad * cos(azim) * sin(incl);
98 *x = rad * sin(azim) * sin(incl);
104 * @x: the x coordinate
105 * @y: the y coordinate
106 * @z: the z coordinate
107 * @lat: the resulting latitude
108 * @lon: the resulting longitude
109 * @elev: the resulting elevation
111 * Convert a point from x, y and z coordinates to latitude, longitude, and
114 void xyz2lle(gdouble x, gdouble y, gdouble z,
115 gdouble *lat, gdouble *lon, gdouble *elev)
117 gdouble rad = sqrt(x*x + y*y + z*z);
118 *lat = incl2lat(acos(y / rad));
119 *lon = azim2lon(atan2(x,z));
120 *elev = rad2elev(rad);
125 * @x: the x coordinate
126 * @y: the y coordinate
127 * @z: the z coordinate
128 * @lat: the resulting latitude
129 * @lon: the resulting longitude
131 * Get the latitude and longitude for a x, y, z value.
133 void xyz2ll(gdouble x, gdouble y, gdouble z,
134 gdouble *lat, gdouble *lon)
136 gdouble rad = sqrt(x*x + y*y + z*z);
137 *lat = incl2lat(acos(y / rad));
138 *lon = azim2lon(atan2(x,z));
143 * @lon_dist: the distance in degrees of longitude
144 * @lat: the latitude to calculate at
146 * Calculate the distance of longitudinal span at a particular latitude.
148 * Returns: the distance in meters
150 gdouble ll2m(gdouble lon_dist, gdouble lat)
152 gdouble azim = (-lat+90)/180*M_PI;
153 gdouble rad = sin(azim) * EARTH_R;
154 gdouble circ = 2 * M_PI * rad;
155 return lon_dist/360 * circ;
160 * @a: the first point
161 * @b: the second point
163 * Calculate the distance between two three dimensional points.
165 * Returns: the distance between the points
167 gdouble distd(gdouble *a, gdouble *b)
169 return sqrt((a[0]-b[0])*(a[0]-b[0]) +
170 (a[1]-b[1])*(a[1]-b[1]) +
171 (a[2]-b[2])*(a[2]-b[2]));
176 * @a: the first longitude
177 * @b: the second longitude
179 * Calculate the average longitude between two longitudes. This is smart about
180 * which side of the globe the resulting longitude is placed on.
182 * Returns: the average
184 gdouble lon_avg(gdouble a, gdouble b)
186 gdouble diff = ABS(a-b);
187 gdouble avg = (a+b)/2;