NAME

       pj_init - initialize cartographic projection
       pj_init_plus - initialize cartographic projection
       pj_fwd - forward cartographic projection
       pj_inv - inverse cartographic projection
       pj_transform - transform between coordinate systems
       pj_free - de-initialize projection

SYNOPSIS

       #include <proj_api.h>

       projPJ pj_init(int argc, char **argv)

       projPJ pj_init_plus(const char *defn)

       projUV pj_fwd(projUV val, projPJ proj)

       projUV pj_inv(projUV val, projPJ proj)

       int pj_transform(projPJ src_cs, projPJ dst_cs, long point_count,
                        int point_offset, double *x, double *y, double *z)

       void pj_free(projPJ proj)

DESCRIPTION

       Procedure  pj_init  selects  and  initializes  a cartographic projection with its argument
       control parameters.  Argc is the number of elements in the array of control  strings  argv
       that  each contain individual cartographic control keyword assignments (+ proj arguments).
       The list must contain at least  the  proj=projection  and  Earth's  radius  or  elliptical
       parameters.   If  the  initialization  of  the projection is successful a valid address is
       returned otherwise a NULL value.

       The pj_init_plus function  operates  similarly  to  pj_init  but  takes  a  single  string
       containing  the  definition,  with  each parameter prefixed with a plus sign.  For example
       "+proj=utm +zone=11 +ellps=WGS84".

       Once initialization is performed either forward or inverse projections  can  be  performed
       with  the  returned  value  of  pj_init used as the argument proj.  The argument structure
       projUV values u and v contain respective longitude and latitude or x and y.  Latitude  and
       longitude  are  in  radians.  If a projection operation fails, both elements of projUV are
       set to HUGE_VAL (defined in math.h).

       Note: all projections have a forward mode, but some do not have an inverse projection.  If
       the projection does not have an inverse the projPJ structure element inv will be NULL.

       The  pj_transform  function  may  be  used  to  transform  points between the two provided
       coordinate systems.  In addition to converting between cartographic projection coordinates
       and  geographic  coordinates,  this  function  also takes care of datum shifts if possible
       between the source and destination coordinate system.  Unlike pj_fwd and pj_inv it is also
       allowable for the coordinate system definitions (PJ *) to be geographic coordinate systems
       (defined as +proj=latlong).  The x, y and z arrays contain the input values of the points,
       and are replaced with the output values.  The point_offset should indicate the spacing the
       of x,y,z arrays, normally 1.  The function returns zero on success, or  the  error  number
       (also in pj_errno) on failure.

       Memory associated with the projection may be freed with pj_free.

EXAMPLE

       The  following  program  reads  latitude and longitude values in decimal degrees, performs
       Mercator projection with a Clarke 1866 ellipsoid and a 33°  latitude  of  true  scale  and
       prints the projected cartesian values in meters:
       #include <proj_api.h>

       main(int argc, char **argv) {
            char *args[] = { "proj=merc", "ellps=clrk66", "lat_ts=33" };
            projUV p;
            projPJ pj;

            if (!(pj = pj_init(3, args)))
               exit(1);
            while (scanf("%lf %lf", &p.v, &p.u) == 2) {
               p.u *= DEG_TO_RAD;
               p.v *= DEG_TO_RAD;
               p = pj_fwd(p, pj);
               printf("%.2f\t%.2f\n", p.u, p.v);
            }
            exit(0);
       }

LIBRARY

       libproj.a - library of projections and support procedures

SEE ALSO

       http://proj.osgeo.org/ProjAPI, proj(1),
       Cartographic  Projection  Procedures  for  the UNIX Environment—A User's Manual, (Evenden,
       1990, Open-file report 90-284).

HOME PAGE

       http://proj.osgeo.org

                                       2001/04/05 Rel. 4.4                             PJ_INIT(3)