Provided by: libgeo-proj4-perl_1.09-2build1_amd64 bug

NAME

       Geo::Proj4 - PROJ.4 cartographic projections library

INHERITANCE

        Geo::Proj4
          is a DynaLoader

SYNOPSIS

         use Geo::Proj4;

         my $proj = Geo::Proj4->new(proj => "merc",
            ellps => "clrk66", lon_0 => -96)
              or die "parameter error: ".Geo::Proj4->error. "\n";

         my $proj = Geo::Proj4->new("+proj=merc +ellps=clrk66 +lon_0=-96")
              or die "parameter error: ".Geo::Proj4->error. "\n";

         my $proj = Geo::Proj4->new(init => "epsg:28992");

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

         if($proj->hasInverse)
         {   my ($lat, $lon) = $proj->inverse($x, $y);
             ...
         }

         my $proj = Geo::Proj4->new(init => "epsg:26985") or die;
         my ($lat, $lon) = $proj->inverse(401717.80, 130013.88);

         my $point = [ 123.12, -5.4 ];
         my $projected_point = $from->transform($to, $point);
         my $projected_multi = $from->transform($to, \@points);

DESCRIPTION

       The Open Source PROJ.4 library converts between geographic coordinate systems.  It is able
       to convert between geodetic latitude and longitude (LL, most commonly the WGS84
       projection), into an enormous variety of other cartographic projections (XY, usually UTM).

       WARNING: It is not always clear what the source projection is when forward() or inverse()
       are used, i.e. in what projection system the source data is expected to be in.  Therefore,
       you can better be specific on both source and destination projection and use transform().

METHODS

   Instantiation
       Geo::Proj4->new($string|%options)
           The object defines the target projection, but that's easier said than done:
           projections have different parameter needs.  The parameters which can (or need to) be
           used are listed with "cs2cs -lP".  The manual page of "cs2cs" explains how the
           configuration works.

           Two ways are provided to define the projection.  Either, use a list of %options, which
           are pairs of parameters, or pass one string which contains all parameters at once.
           You must supply a "proj" parameter.

           In case of an OPTION list: WARNING: Specify boolean parameters (e.g. the south
           parameter to the UTM projection) with a matching value of undef.

           example:

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

            my $proj = Geo::Proj4->new("+proj=merc +ellps=clrk66 +lon_0=096")
               or die Geo::Proj4->error;

            my $proj = Geo::Proj4->new(init => "epsg:$epsg");

   Accessors
       $obj->datum()
           Tries to return a datum name for this projection.

       $obj->dump()
           Write the definition in extended form to stdout.  This output cannot be caught,
           because it is done on stdio level, below the reach of PerlIO.

       Geo::Proj4->error()
           Returns a dualvar (see Scalar::Util) containing the error number and error string of
           the last reported error.

           example:

            my $proj = Geo::Proj4->new(...);
            unless(defined $proj)
            {   my $error = Geo::Proj4->error;
                warn "error-code: ".$error+0;
                warn "error-string: $error\n";
            }

       $obj->hasInverse()
           Returns whether the reverse function for the projection exists.  Some projections are
           one-way.

       $obj->isGeocentric()
           Returns true when the source projection is using a geocentric coordinate system; i.e.
           uses x-y coordinates.

       $obj->isGeodesic()
           Returns true when the source projection is using a geodetic coordinate system; i.e.
           uses lat long coordinates.  Same as isLatlong()

       $obj->isLatlong()
           Returns true when the source projection is using a geodetic coordinate system; i.e.
           uses lat long coordinates.  Same as isGeodesic().

       $obj->normalized()
           Returns a string which is produced by the library based on the data extracted from the
           initiation parameters.  This string may be more explicit than the passed values, and
           could be used for debugging.

       $obj->projection()
           Returns the projection type.

   Converters
       $obj->forward($latitude, $longitude)
           Perform a forward projection from $latitude and $longitude (LL) to the cartographic
           projection (XY) represented by the Geo::Proj4 instance.

           WARNING: for historic reasons, latitude and longitude are assumed to be in (floating
           point) degrees, although the library expects rads.  See forwardRad(). A latitude south
           of the Equator and longitude west of the Prime Meridian given with negative values.

           Returned are two values, usually X and Y in meters, or whatever units are relevant to
           the given projection.  When the destination projection also than the order of
           parameters will be returned as LONG,LAT (not lat,long!)

           On error, "forward" will return undef for both values.

           example:

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

       $obj->forwardRad($latitude, $longitude)
           Perform a forward projection from $latitude and $longitude (LL) to the cartographic
           projection (XY) represented by the Geo::Proj4 instance.  This function reflects to
           library function "forward()", expecting radians, not degrees.

       $obj->inverse(($x,$y) | ($lat,$long))
           Perform an inverse projection from the (cartographic) projection represented by this
           Geo::Proj4 object, back into latitude and longitude values.

           WARNING: for historic reasons, latitude and longitude are assumed to be in (floating
           point) degrees, although the library expects rads.  See inverseRad().

           On error, "inverse" will return undef for both values.

           example:

             if($proj->hasInverse)
             {  my ($lat, $lon) = $proj->inverse($x, $y);
                ...
             }

       $obj->inverseRad(($x,$y) | ($lat|$long))
           Perform an inverse projection from the (cartographic) projection represented by this
           Geo::Proj4 object, back into latitude and longitude values.  Latitude and longitude
           are assumed to be in radians. See inverse().

       $obj->transform($to, $point|ARRAY-of-$points)
           Translate the $points into the projecten of $to.  Each point is specified as two or
           three values in an ARRAY.  In case of latlong source or destination projections,
           coordinates are translated into radians and/or back.  Both input and output values are
           always in X-Y/LongLat order.  See transformRad()

           example:

            my $from  = Geo::Proj4->new("+proj=latlong +datum=NAD83");
            my $to    = Geo::Proj4->new("+proj=utm +zone=10 +datum=WGS84");

            my $point = [ 1.12, 3.25 ];  # See Geo::Point
            my $pr_point = $from->transform($to, $point);

            my $pr    = $from->transform($to, [ $point1, $point2 ]);
            my $pr_point1 = $pr->[0];
            my $pr_point2 = $pr->[1];

       $obj->transformRad($to, $point|ARRAY-of-$points)
           Translate the $points into the projecten of $to.  Each point is specified as two or
           three values in an ARRAY.  In case of latlong source or destination projections,
           coordinates are expected to be in radians.  Both input and output values are always in
           X-Y/LongLat order.  See transform()

   Library introspection
       Geo::Proj4->datumInfo($label)
           Returns a hash with information about the specified datum.  With listDatums(), all
           defined LABELS can be found.

       Geo::Proj4->ellipsoidInfo($label)
           Returns a hash with information about the specified ellipsis.  With listEllipsoids(),
           all defined LABELS can be found.

       $obj->libVersion()
       Geo::Proj4->libVersion()
           Returns the version of the proj4 library

       Geo::Proj4->listDatums()
           Returns a list with all defined datum labels.

           example:

            foreach my $id (Geo::Proj4->listDatums)
            {   my $def = Geo::Proj4->datum($id);
                print "$id = $def->{ellips_id}\n";
            }

       Geo::Proj4->listEllipsoids()
           Returns a list with all defined ellips labels.

           example:

            foreach my $id (Geo::Proj4->listEllipsoids)
            {   my $def = Geo::Proj4->ellipsoid($id);
                print "$id = $def->{name}\n";
            }

       Geo::Proj4->listTypes()
           Returns a list with all defined projection types.

           example:

            foreach my $id (Geo::Proj4->listTypes)
            {   my $def = Geo::Proj4->type($id);
                print "$id = $def->{description}\n";
            }

       Geo::Proj4->listUnits()
           Returns a list with all defined unit labels.

           example:

            foreach my $id (Geo::Proj4->listUnits)
            {   my $def = Geo::Proj4->unit($id);
                print "$id = $def->{name}\n";
            }

       Geo::Proj4->typeInfo($label)
           Returns a hash with information about the specified projection type.  With
           listTypes(), all defined LABELS can be found.

       Geo::Proj4->unitInfo($label)
           Returns a hash with information about the specified unit.  With listUnits(), all
           defined LABELS can be found.

DETAILS

   Install
       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/>.

   Projections
       Covering all the possible projections and their arguments in PROJ.4 is well beyond the
       scope of this document. However, the cs2cs(1) 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 cs2cs(1) 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.

   Bugs
       One common source of errors is that latitude and longitude are swapped: some projection
       systems use lat-long, other use x-y which is a swapped order.  Especially the forward()
       and inverse() cause this problem, always flipping the coordinate order.  The transform()
       method is much easier: input and output in x-y/long-lat order.

       Also be warned  that the values must have the right sign. Make sure you give negative
       values for south latitude and west longitude.  For calculating projections, this is more
       important than on maps.

DIAGNOSTICS

       Error: transform() expects array of points
       Error: transformRad() expects array of points

REFERENCES

       See the Geo::Point website at <http://perl.overmeer.net/geo/> for an html version of this
       and related modules;

       Effusive thanks to Frank Warmerdam (maintainer of PROJ.4) and Gerald Evenden (main
       contributor of PROJ.4). Their PROJ.4 library home page:
       <http://www.remotesensing.org/proj/>

       proj(1), cs2cs(1), pj_init(3).

COPYRIGHTS

       Developed and maintained by Mark Overmeer <markov@cpan.org>.  Copyright (c) 2004-2018 by
       the authors. All rights reserved.

       Originally Written by Schuyler Erle <schuyler@nocat.net> and Rich Gibson <rich@nocat.net>.
       Their site: Mapping Hacks home page: <http://www.mappinghacks.com>

LICENSE

       This library is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.