NAME
    Geo::Proj4 - Wrap the powerful PROJ.4 cartographic projections library

SYNOPSIS
      use Geo::Proj4;

      my $proj = Geo::Proj4->new(
            proj => "merc", ellps => "clrk66", lon_0 => -96 );

      my ($x, $y) = $proj->forward($lat, $lon);

      my ($lat, $lon) = $proj->inverse($x, $y);

DESCRIPTION
    This perl library converts geodetic latitude and longitude into an
    enormous variety of cartographic projections and back. Geo::Proj4 uses
    XS to wrap the PROJ.4 cartographic projections library. You will need to
    have the PROJ.4 library installed in order to build and use this module.
    You can get source code and binaries for the PROJ.4 library from its
    home page at http://www.remotesensing.org/proj/. See the pj_init(3)
    manpage for details on the internals.

METHODS
    new( %args )
          my $proj = Geo::Proj4->new(
                    proj => "merc", ellps => "clrk66", lon_0 => -96 );

        The contructor accepts a hash of parameters that will be passed on
        to the PROJ.4 library. You must supply a "proj" parameter
        identifying the target projection. Specify boolean parameters (e.g.
        the south parameter to the UTM projection) with a matching value of
        undef.

        Covering all the possible projections and their arguments in PROJ.4
        is well beyond the scope of this document. However, the cs2cs
        utility that ships with PROJ.4 will list the projections it knows
        about by running cs2cs -lp, the ellipsoid models it knows with the
        -le parameter, the units it knows about with -lu, and the geodetic
        datums it knows with -ld. Read the cs2cs(1) manpage for more
        details.

        Alternately, you can read the PROJ.4 documentation, which can be
        found on the project's homepage. There are links to PDFs, text
        documentation, a FAQ, and more.

    forward( $lat, $lon )
          my ($x, $y) = $proj->forward($lat, $lon);

        Perform a forward projection from latitude and longitude to the
        cartographic projection represented by $proj. Latitude and longitude
        are assumed to be in degrees, with latitude south of the Equator and
        longitude west of the Prime Meridian given with negative values. $x
        and $y are typically returned in meters, or whatever units are
        relevant to the given projection.

        If PROJ.4 encounters an error, forward() will return undef for both
        values.

    inverse( $x, $y )
          my ($lat, $lon) = $proj->inverse($x, $y);

        Perform an inverse projection from the cartographic projection
        represented by $proj back into latitude and longitude. Units and
        error conditions are as described above.

EXAMPLES
      To Convert from Lat/Long to UTM:
      #!/usr/bin/perl

      use strict;
      use Geo::Proj4;

      my $proj = Geo::Proj4->new( proj => "utm", zone => 10 );
      my ($x, $y) = $proj->forward(38.40342, -122.81856);
      print "conversion to UTM: y is  $y\n";
      print "conversion to UTM: x is  $x\n";

      my ($lat, $long) = $proj->inverse($x, $y);
      print "inverse conversion: lat is $lat \n" ;
      print "inverse conversion: long is $long \n" ;

ERRATA, BUGS, TODO, ETC.
    One common source of errors is that latitude and longitude are swapped,
    or that the values have the wrong sign. Make sure you give negative
    values for south latitude and west longitude.

    PROJ.4 offers a "pj_transform()" function that would be really cool to
    add to this module, but... PROJ.4 expects spherical coordinates (i.e.
    lat and long) in radians, whereas most ordinary people think of lat and
    long in degrees. Ordinarily, Geo::Proj4 takes care of this for you
    transparently, but in the case of the proposed "transform()" method, the
    list of points to be transformed between two cartographic projections
    might be spherical or planar in zero, one, or both of the input and
    output lists. We could supply helper functions to allow a developer to
    perform the degree-to-radian and reverse as needed before or after the
    call to "transform()", but... would anyone use this, or would you just
    rely on cs2cs?

    Passing undef as the value to a boolean parameter is an ugly interface.

    Needs more tests! Especially of border cases.

    Needs more samples in the samples directory!

SEE ALSO
    PROJ.4 home page: http://www.remotesensing.org/proj/

    Mapping Hacks home page: http://www.mappinghacks.com

    proj(1), cs2cs(1), pj_init(3), Geo::Dymaxion(3pm),
    Geo::Coordinates::UTM(3pm)

AUTHORS
    Schuyler Erle <schuyler@nocat.net>

    Rich Gibson <rich@nocat.net>

EFFUSIVE THANKS TO...
    Frank Warmerdam, maintainer of PROJ.4 and all around most excellent
    person.

    Gerald Evenden. 'Essentially all work (on PROJ.4) was done by Gerald...'

COPYRIGHT
    Copyright (C) 2004 by Schuyler Erle and Rich Gibson

LICENSE
    This library is free software; you can redistribute it and/or modify it
    under the same terms as Perl itself, either Perl version 5.8.3 or, at
    your option, any later version of Perl 5 you may have available.