## grits-util grits-util — Geographic utilities |

## Synopsis

    #define             EARTH_C
    #define             EARTH_R
    #define             EAST
    #define             FOV_DIST
    struct              GritsBounds;
    struct              GritsPoint;
    #define             MPPX                                (dist)
    #define             NORTH
    #define             SOUTH
    #define             WEST
    #define             azim2lon                            (azim)
    void                crossd                              (gdouble *a,
                                                             gdouble *b,
                                                             gdouble *out);
    void                crossd3                             (gdouble *a,
                                                             gdouble *b,
                                                             gdouble *c,
                                                             gdouble *out);
    #define             deg2rad                             (deg)
    gdouble             distd                               (gdouble *a,
                                                             gdouble *b);
    #define             elev2rad                            (elev)
    void                free_points                         (GritsPoints *points);
    void                grits_bounds_set_bounds             (GritsBounds *bounds,
                                                             gdouble n,
                                                             gdouble s,
                                                             gdouble e,
                                                             gdouble w);
    void                grits_point_set_lle                 (GritsPoint *point,
                                                             gdouble lat,
                                                             gdouble lon,
                                                             gdouble elev);
    #define             incl2lat                            (incl)
    #define             lat2incl                            (lat)
    gdouble             lengthd                             (gdouble *a);
    gdouble             ll2m                                (gdouble lon_dist,
                                                             gdouble lat);
    void                lle2xyz                             (gdouble lat,
                                                             gdouble lon,
                                                             gdouble elev,
                                                             gdouble *x,
                                                             gdouble *y,
                                                             gdouble *z);
    #define             lon2azim                            (lon)
    gdouble             lon_avg                             (gdouble a,
                                                             gdouble b);
    void                normd                               (gdouble *a);
    GritsPoints *       parse_points                        (const gchar *string,
                                                             const gchar *group_sep,
                                                             const gchar *point_sep,
                                                             const gchar *coord_sep,
                                                             GritsBounds *bounds,
                                                             GritsPoint *center);
    #define             rad2deg                             (rad)
    #define             rad2elev                            (rad)
    void                xyz2ll                              (gdouble x,
                                                             gdouble y,
                                                             gdouble z,
                                                             gdouble *lat,
                                                             gdouble *lon);
    void                xyz2lle                             (gdouble x,
                                                             gdouble y,
                                                             gdouble z,
                                                             gdouble *lat,
                                                             gdouble *lon,
                                                             gdouble *elev);

## 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_C

    #define EARTH_C (2*G_PI*EARTH_R)

Circumference of the earth at the equator

### EARTH_R

    #define EARTH_R (6371000)

Radius of the earth

### EAST

    #define EAST  180

Eastern most longitude

### FOV_DIST

    #define FOV_DIST   (1039.23)

Used by GritsOpenGL to set up the drawing window

### struct GritsBounds

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

### struct GritsPoint

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

### MPPX()

    #define MPPX(dist) (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

### NORTH

    #define NORTH  90

Latitude at the north poll

### SOUTH

    #define SOUTH -90

Latitude at the south poll

### 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

### 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

### deg2rad()

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

Convert degrees to radians

`deg` : | the angle in degrees
Returns : | the angle in radians

### 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

### 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

### free_points ()

    void                free_points                         (GritsPoints *points);

Frees all data allocated by parse_points

`points` : | Array of points allocated by `parse_points()`

### 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

### 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

### 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

### lengthd ()

    gdouble             lengthd                             (gdouble *a);

Calculate the length (magnitude) of a vector.

`a` : | the vector
Returns : | the length

### 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

### 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

### lon2azim()

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

Convert longitude to azimuth

`lon` : | the longitude
Returns : | the azimuth in radians

### 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

### normd ()

    void                normd                               (gdouble *a);

Normalize a vector to a mangitude of 1

`a` : | the first longitude

### 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

### rad2deg()

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

Convert radians to degrees

`rad` : | the angle in radians
Returns : | the angle in degrees

### 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

### 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

### 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