grits-util

grits-util — Geographic utilities

Synopsis

#define             EARTH_R
#define             EARTH_C
#define             NORTH
#define             SOUTH
#define             EAST
#define             WEST
#define             azim2lon                            (azim)
#define             lon2azim                            (lon)
#define             incl2lat                            (incl)
#define             lat2incl                            (lat)
#define             rad2elev                            (rad)
#define             elev2rad                            (elev)
#define             deg2rad                             (deg)
#define             rad2deg                             (rad)
                    GritsPoint;
void                grits_point_set_lle                 (GritsPoint *point,
                                                         gdouble lat,
                                                         gdouble lon,
                                                         gdouble elev);
                    GritsBBox;
void                grits_bbox_set_bounds               (GritsBBox *bbox,
                                                         gdouble n,
                                                         gdouble s,
                                                         gdouble e,
                                                         gdouble w);
#define             FOV_DIST
#define             MPPX                                (dist)
void                lle2xyz                             (gdouble lat,
                                                         gdouble lon,
                                                         gdouble elev,
                                                         gdouble *x,
                                                         gdouble *y,
                                                         gdouble *z);
void                xyz2lle                             (gdouble x,
                                                         gdouble y,
                                                         gdouble z,
                                                         gdouble *lat,
                                                         gdouble *lon,
                                                         gdouble *elev);
void                xyz2ll                              (gdouble x,
                                                         gdouble y,
                                                         gdouble z,
                                                         gdouble *lat,
                                                         gdouble *lon);
gdouble             ll2m                                (gdouble lon_dist,
                                                         gdouble lat);
gdouble             distd                               (gdouble *a,
                                                         gdouble *b);
gdouble             lon_avg                             (gdouble a,
                                                         gdouble b);

Description

Miscellaneous utility functions, these deal mostly with coordinate conversion. Below are some examples that should help demonstrate how these functions work.

Example 1. Terminology

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="syntax" content="cpp" />
<meta name="settings" content="use_css,use_xhtml" />
<style type="text/css">

pre { white-space: pre-wrap; font-family: monospace; color: #000000; background-color: #ffffff; }
body { white-space: pre-wrap; font-family: monospace; color: #000000; background-color: #ffffff; }
.Constant { color: #0000c0; text-decoration: underline; }
.Statement { color: #008080; font-weight: bold; }

</style>
</head>
<body><pre>
deg    - Degrees
rad    - Radians, also radius
m      - Meters, <span class="Statement">for</span> earth-based distances
px     - Pixels, <span class="Statement">for</span> 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, -<span class="Constant">90</span> (S) .. <span class="Constant">90</span> (N)
lon    - Longitude, amount east-west, -<span class="Constant">180</span> (W) .. <span class="Constant">180</span> (E)
incl   - Inclination, polar equiv of  latitude, Pi .. <span class="Constant">0</span>
azim   - Azimuth, polar equiv of longitude, -Pi .. Pi

x      -  <span class="Constant">0</span>° lon is positive
y      - <span class="Constant">90</span>° 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
</pre></body></html>


Example 2. Conversions

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="syntax" content="cpp" />
<meta name="settings" content="use_css,use_xhtml" />
<style type="text/css">

pre { white-space: pre-wrap; font-family: monospace; color: #000000; background-color: #ffffff; }
body { white-space: pre-wrap; font-family: monospace; color: #000000; background-color: #ffffff; }
.Constant { color: #0000c0; text-decoration: underline; }
.Statement { color: #008080; font-weight: bold; }

</style>
</head>
<body><pre>
lat    lon   elev -&gt;      x      y      z
<span class="Statement">lle2xyz</span>:    <span class="Constant">0.0</span>,   <span class="Constant">0.0</span>,   <span class="Constant">0.0</span> -&gt;    <span class="Constant">0.0</span>,   <span class="Constant">0.0</span>,  <span class="Constant">10.0</span>
lle2xyz:   <span class="Constant">90.0</span>,   <span class="Constant">0.0</span>,   <span class="Constant">0.0</span> -&gt;    <span class="Constant">0.0</span>,  <span class="Constant">10.0</span>,   <span class="Constant">0.0</span>
<span class="Statement">lle2xyz</span>:    <span class="Constant">0.0</span>,  <span class="Constant">90.0</span>,   <span class="Constant">0.0</span> -&gt;   <span class="Constant">10.0</span>,   <span class="Constant">0.0</span>,   <span class="Constant">0.0</span>

              x      y      z -&gt;    lat    lon   elev
xyz2lle:   <span class="Constant">10.0</span>,   <span class="Constant">0.0</span>,   <span class="Constant">0.0</span> -&gt;    <span class="Constant">0.0</span>,  <span class="Constant">90.0</span>,   <span class="Constant">0.0</span>
<span class="Statement">xyz2lle</span>:    <span class="Constant">0.0</span>,  <span class="Constant">10.0</span>,   <span class="Constant">0.0</span> -&gt;   <span class="Constant">90.0</span>,   <span class="Constant">0.0</span>,   <span class="Constant">0.0</span>
<span class="Statement">xyz2lle</span>:    <span class="Constant">0.0</span>,   <span class="Constant">0.0</span>,  <span class="Constant">10.0</span> -&gt;    <span class="Constant">0.0</span>,   <span class="Constant">0.0</span>,   <span class="Constant">0.0</span>
</pre></body></html>


Details

EARTH_R

#define EARTH_R (6371000)

Radius of the earth


EARTH_C

#define EARTH_C (2*G_PI*EARTH_R)

Circumference of the earth at the equator


NORTH

#define NORTH  90

Latitude at the north poll


SOUTH

#define SOUTH -90

Latitude at the south poll


EAST

#define EAST  180

Eastern most longitude


WEST

#define WEST -180

Western most longitude


azim2lon()

#define azim2lon(azim) ((azim)*180/G_PI)

Convert azimuth to longitude

azim :

the azimuth in radians

Returns :

the longitude

lon2azim()

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

Convert longitude to azimuth

lon :

the longitude

Returns :

the azimuth in radians

incl2lat()

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

Convert inclination to latitude

incl :

the inclination in radians

Returns :

the latitude

lat2incl()

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

Convert latitude to inclination

lat :

the latitude

Returns :

the inclination in radians

rad2elev()

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

Convert radius to elevation

rad :

the radius in meters

Returns :

the elevation in meters above the earth surface

elev2rad()

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

Convert elevation to radius

elev :

the elevation in meters above the earth surface

Returns :

the radius in meters

deg2rad()

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

Convert degrees to radians

deg :

the angle in degrees

Returns :

the angle in radians

rad2deg()

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

Convert radians to degrees

rad :

the angle in radians

Returns :

the angle in degrees

GritsPoint

typedef struct {
	gdouble lat, lon, elev;
} GritsPoint;


grits_point_set_lle ()

void                grits_point_set_lle                 (GritsPoint *point,
                                                         gdouble lat,
                                                         gdouble lon,
                                                         gdouble elev);

Set the latitude, longitude, and elevation for a point.

point :

the point to modify

lat :

the new latitude

lon :

the new longitude

elev :

the new elevation

GritsBBox

typedef struct {
	gdouble n, s, e, w;
} GritsBBox;


grits_bbox_set_bounds ()

void                grits_bbox_set_bounds               (GritsBBox *bbox,
                                                         gdouble n,
                                                         gdouble s,
                                                         gdouble e,
                                                         gdouble w);

Set the north, south, east, and west edges of the bounding box

bbox :

n :

the north edge

s :

the south edge

e :

the east edge

w :

the west edge

FOV_DIST

#define FOV_DIST   2000.0

Used by GritsOpenGL to set up the drawing window


MPPX()

#define MPPX(dist) (4*dist/FOV_DIST)

Get the resolution that a point would be drawn at on the screen

dist :

the distance between the eye and the point in question

Returns :

the resolution in meters per pixel

lle2xyz ()

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

Convert a point from latitude, longitude, and elevation to x, y and z coordinates.

lat :

the latitude

lon :

the longitude

elev :

the elevation

x :

the resulting x coordinate

y :

the resulting y coordinate

z :

the resulting z coordinate

xyz2lle ()

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

Convert a point from x, y and z coordinates to latitude, longitude, and elevation.

x :

the x coordinate

y :

the y coordinate

z :

the z coordinate

lat :

the resulting latitude

lon :

the resulting longitude

elev :

the resulting elevation

xyz2ll ()

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

Get the latitude and longitude for a x, y, z value.

x :

the x coordinate

y :

the y coordinate

z :

the z coordinate

lat :

the resulting latitude

lon :

the resulting longitude

ll2m ()

gdouble             ll2m                                (gdouble lon_dist,
                                                         gdouble lat);

Calculate the distance of longitudinal span at a particular latitude.

lon_dist :

the distance in degrees of longitude

lat :

the latitude to calculate at

Returns :

the distance in meters

distd ()

gdouble             distd                               (gdouble *a,
                                                         gdouble *b);

Calculate the distance between two three dimensional points.

a :

the first point

b :

the second point

Returns :

the distance between the points

lon_avg ()

gdouble             lon_avg                             (gdouble a,
                                                         gdouble b);

Calculate the average longitude between two longitudes. This is smart about which side of the globe the resulting longitude is placed on.

a :

the first longitude

b :

the second longitude

Returns :

the average