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)
struct              GritsPoint;
void                grits_point_set_lle                 (GritsPoint *point,
                                                         gdouble lat,
                                                         gdouble lon,
                                                         gdouble elev);
struct              GritsBounds;
void                grits_bounds_set_bounds             (GritsBounds *bounds,
                                                         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);
void                crossd                              (gdouble *a,
                                                         gdouble *b,
                                                         gdouble *out);
void                crossd3                             (gdouble *a,
                                                         gdouble *b,
                                                         gdouble *c,
                                                         gdouble *out);
gdouble             lengthd                             (gdouble *a);
void                normd                               (gdouble *a);
gdouble             lon_avg                             (gdouble a,
                                                         gdouble b);
GritsPoints *       parse_points                        (const gchar *string,
                                                         const gchar *group_sep,
                                                         const gchar *point_sep,
                                                         const gchar *coord_sep,
                                                         GritsBounds *bounds,
                                                         GritsPoint *center);
void                free_points                         (GritsPoints *points);

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

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


Example 2. 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


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

struct GritsPoint

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

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

struct GritsBounds

struct GritsBounds {
	gdouble n, s, e, w;
};

grits_bounds_set_bounds ()

void                grits_bounds_set_bounds             (GritsBounds *bounds,
                                                         gdouble n,
                                                         gdouble s,
                                                         gdouble e,
                                                         gdouble w);

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

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

crossd ()

void                crossd                              (gdouble *a,
                                                         gdouble *b,
                                                         gdouble *out);

Calculate the cross product of two vectors

a :

 the first vector

b :

 the second vector

crossd3 ()

void                crossd3                             (gdouble *a,
                                                         gdouble *b,
                                                         gdouble *c,
                                                         gdouble *out);

Calculate the cross product of three points

a :

 the left point

b :

 the center point

c :

 the right point

out :

 the cross product

lengthd ()

gdouble             lengthd                             (gdouble *a);

Calculate the length (magnitude) of a vector.

a :

 the vector

Returns :

 the length

normd ()

void                normd                               (gdouble *a);

Normalize a vector to a mangitude of 1

a :

 the first longitude

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

parse_points ()

GritsPoints *       parse_points                        (const gchar *string,
                                                         const gchar *group_sep,
                                                         const gchar *point_sep,
                                                         const gchar *coord_sep,
                                                         GritsBounds *bounds,
                                                         GritsPoint *center);

Parse a string of the form: string -> group [group_sep group] ... group -> point [point_sep point] ... point -> latitude coord_sep longitude [coord_sep elevation]

For example parse_points("30,-80 30,-120 50,-120 50,-80", "\t", " ", ",");

string :

 String representation of the points

group_sep :

 Group separator

point_sep :

 Point separator

coord_sep :

 Coordinate separator

bounds :

 The bounding box of all the points, or NULL

center :

 The center of the bounds, or NULL

Returns :

 zero-terminated array of groups of points

free_points ()

void                free_points                         (GritsPoints *points);

Frees all data allocated by parse_points

points :

 Array of points allocated by parse_points()
Generated by GTK-Doc V1.16