Provided by: libgeo-point-perl_0.94-1_all bug

NAME

       Geo::Proj - Handling projections

SYNOPSIS

        use Geo::Proj;

        my $wgs84 = Geo::Proj->new   # predefined if import()
         ( nick  => 'wgs84'
         , proj4 => '+proj=latlong +datum=WGS84 +ellps=WGS84'
         );

        my $clrk = Geo::Proj->new
         ( nick  => 'clark66'
         , proj4 => [proj => "merc", ellps => "clrk66", lon_0 => -96]
         );

        my $point_wgs84= Geo::Point->latlong(56.12, 4.40, 'wgs84');
        my $point_wgs84= Geo::Point->latlong(56.12, 4.40, $wgs84);

        my $point_clrk = $point_wgs84->in($clrk);
        my $point_clrk = Geo::Proj->to($wgs84, $clrk, $point_wgs84);
        my $point_clrk = Geo::Proj->to($wgs84, 'clark66', $point_wgs84);

DESCRIPTION

       A point on Earth's surface can be represented in many different coordinate systems.  The
       Geo::Proj4 module wraps the popular Open Source "libproj" library to convert between those
       coordinate systems; a very complex job.

       Within a program, however, you like some extra abstraction from that library: to be able
       to simply label a point to its system, and then forget about all transformations which may
       be necessary.  The label (or "nick") hides all complicated parameters for the actual
       projection .

       WARNING 1: this class will collect all nicks, which means that calling new() with the same
       label twice will have the second ignored.

       WARNING 2: the wgs84 nickname is predefined, but only if this module is 'used' with
       import.  So if you decide to use 'require' to dynamically load this module, then don't
       forget to call 'import()' yourself, or define the wgs84 projection yourself.

METHODS

   Constructors
       Geo::Proj->new([NICK], OPTIONS)
           Create a new object.

            -Option--Default
             name    <from proj4>
             nick    <required>
             proj4   <required>
             srid    undef

           name => STRING
           nick => LABEL
             The abbrevated name for this projection.

           proj4 => OBJECT|ARRAY|STRING
             The ARRAY or STRING will by used to create a Geo::Proj4 object by calling
             Geo::Proj4::new().  You may also specify such an prepared OBJECT.

           srid => INTEGER
             SRID stands for "Spatial Reference System ID", which is just an index in a table of
             spatial descriptions as used by SQL. Only INTEGER values larger than 0 are
             permitted.

   Attributes
       $obj->name()
           The full, official name of the projection

       $obj->nick()
           Simple abbreviating of the projection.

       $obj->proj4([NICK|PROJ4])
       Geo::Proj->proj4([NICK|PROJ4])
           Returns the projection library handle (a Geo::Proj4) to be used by this component.  As
           class method, the NICK is specified for a lookup.  In case a PROJ4 is specified, that
           is returned.

           example:

            my $wgs84 = Geo::Proj->new(nick => 'wgs84', ...);
            my $wgs84_proj4 = Geo::Proj->proj4('wgs84');
            my $wgs84_proj4 = Geo::Proj->proj4($wgs84);
            my $wgs84_proj4 = $wgs84->proj4;

       $obj->srid()
           The "Spatial Reference System ID" if known.

   Projecting
       Geo::Proj->defaultProjection([NICK|PROJ])
           The NICK must be defined with new().  Returned is the Geo::Proj object for the default
           projection.  The default is the first name created, which probably is 'wgs84' (when
           import() had a chance)

       Geo::Proj->dumpProjections([FILEHANDLE])
           Print details about the defined projections to the FILEHANDLE, which defaults to the
           selected.  Especially useful for debugging.

       Geo::Proj->listProjections()
           Returns a sorted lost of projection nicks.

       Geo::Proj->projection(NICK|PROJ)
           Returns the Geo::Proj object, defined with NICK.  In case such an object is passed in
           as PROJ, it is returned unaffected.  This method is used where in other methods NICKS
           or PROJ can be used as arguments.

           example:

            my $wgs84 = Geo::Proj->projection('wgs84');
            my $again = Geo::Proj->projection($wgs84);

       $obj->to([PROJ|NICK], PROJ|NICK, POINT|ARRAY-OF-POINTS)
       Geo::Proj->to([PROJ|NICK], PROJ|NICK, POINT|ARRAY-OF-POINTS)
           Expects an Geo::Proj to project the POINT or POINTS to.  The work is done by
           Geo::Proj4::transform().  As class method, you have to specify two nicks or
           projections.

           Be warned that this to() method expects POINTs which are not Geo::Point objects, but
           which themselves are an ARRAY containing X,Y and optionally a Z coordinate.

           example:

            my $p2 = $wgs84->to('utm31-wgs84', $p1);
            my $p2 = $wgs84->to($utm, $p1);
            my $p2 = Geo::Proj->to('wgs84', 'utm31-wgs84', $p1);

   UTM
       Geo::Proj->UTMprojection(DATUM|PROJ|undef, ZONE)
           The PROJ is a Geo::Proj which is used to collect the datum information from if no
           DATUM was specified explicitly.  It may also be a string which is the name of a datum,
           as known by proj4.  Undef will be replaced by the default projection.

           example:

            my $proj = Geo::Proj->UTMprojection('WGS84', 31) or die;
            print $proj->nick;    # for instance utm31-wgs84

       $obj->bestUTMprojection(POINT, [PROJ|NICK])
       Geo::Proj->bestUTMprojection(POINT, [PROJ|NICK])
           Returns the best UTM projection for some POINT.  As class method, you specify the
           nickname or the object for the point.

           example:

            my $point = Geo::Point->longlat(2.234, 52.12);
            my $proj  = Geo::Proj->bestUTMprojection($point);
            print $proj->nick;    # for instance utm31-wgs84

       $obj->zoneForUTM(POINT)
       Geo::Proj->zoneForUTM(POINT)
           Provided some point, figure-out which zone is most optimal for representing the point.
           In LIST context, zone number, zone letter, and meridian are returned as separate
           scalars.  In LIST context, the zone number and letter are returned as one..

           This code is stolen from Geo::Coordinates::UTM, because that module immediately starts
           to do computations with this knowledge, which is not wanted here.  Probably a lot of
           zones are missing.

OVERLOADING

       overload: '""' (stringification)()
           Returns the nick-name for this projection.

SEE ALSO

       This module is part of Geo-Point distribution version 0.94, built on December 21, 2012.
       Website: http://perl.overmeer.net/geo/ All modules in this suite: "Geo::Point",
       "Geo::Proj4", "Geo::WKT", "Math::Polygon", "Geo::GML", "Geo::ISO19139", "Geo::EOP",
       "Geo::Format::Envisat", and "Geo::Format::Landsat".

       Please post questions or ideas to the mailinglist at http://geo-perl@list.hut.fi

LICENSE

       Copyrights 2005-2012 by [Mark Overmeer]. For other contributors see ChangeLog.

       This program is free software; you can redistribute it and/or modify it under the same
       terms as Perl itself.  See http://www.perl.com/perl/misc/Artistic.html