.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Geo::Proj 3pm"
.TH Geo::Proj 3pm "2019-02-21" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Geo::Proj \- Handling projections
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& use Geo::Proj;
\&
\& my $wgs84 = Geo::Proj\->new   # predefined if import()
\&  ( nick  => \*(Aqwgs84\*(Aq
\&  , proj4 => \*(Aq+proj=latlong +datum=WGS84 +ellps=WGS84\*(Aq
\&  );
\&
\& my $clrk = Geo::Proj\->new
\&  ( nick  => \*(Aqclark66\*(Aq
\&  , proj4 => [proj => "merc", ellps => "clrk66", lon_0 => \-96]
\&  );
\&
\& my $point_wgs84= Geo::Point\->latlong(56.12, 4.40, \*(Aqwgs84\*(Aq);
\& 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, \*(Aqclark66\*(Aq, $point_wgs84);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A point on Earth's surface can be represented in many different coordinate
systems.  The Geo::Proj4 module wraps the popular Open Source \f(CW\*(C`libproj\*(C'\fR
library to convert between those coordinate systems; a very complex job.
.PP
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
\&\f(CW\*(C`nick\*(C'\fR) hides all complicated parameters for the actual projection .
.PP
\&\s-1WARNING 1:\s0 this class will collect all nicks, which means that calling
\&\fBnew()\fR with the same label twice will have the second ignored.
.PP
\&\s-1WARNING 2:\s0 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 '\fBimport()\fR' yourself, or define the
wgs84 projection yourself.
.SH "METHODS"
.IX Header "METHODS"
.SS "Constructors"
.IX Subsection "Constructors"
.ie n .IP "Geo::Proj\->\fBnew\fR( [$nick], %options )" 4
.el .IP "Geo::Proj\->\fBnew\fR( [$nick], \f(CW%options\fR )" 4
.IX Item "Geo::Proj->new( [$nick], %options )"
Create a new object.
.Sp
.Vb 5
\& \-Option\-\-Default
\&  name    <from proj4>
\&  nick    <required>
\&  proj4   <required>
\&  srid    undef
.Ve
.RS 4
.IP "name => \s-1STRING\s0" 2
.IX Item "name => STRING"
.PD 0
.IP "nick => \s-1LABEL\s0" 2
.IX Item "nick => LABEL"
.PD
The abbrevated name for this projection.
.IP "proj4 => OBJECT|ARRAY|STRING" 2
.IX Item "proj4 => OBJECT|ARRAY|STRING"
The \s-1ARRAY\s0 or \s-1STRING\s0 will by used to create a Geo::Proj4 object
by calling \fBGeo::Proj4::new()\fR.  You may also specify such an
prepared \s-1OBJECT.\s0
.IP "srid => \s-1INTEGER\s0" 2
.IX Item "srid => INTEGER"
\&\s-1SRID\s0 stands for \*(L"Spatial Reference System \s-1ID\*(R",\s0 which is just an index
in a table of spatial descriptions as used by \s-1SQL.\s0 Only \s-1INTEGER\s0 values
larger than 0 are permitted.
.RE
.RS 4
.RE
.SS "Attributes"
.IX Subsection "Attributes"
.ie n .IP "$obj\->\fBname\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBname\fR()" 4
.IX Item "$obj->name()"
The full, official name of the projection
.ie n .IP "$obj\->\fBnick\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBnick\fR()" 4
.IX Item "$obj->nick()"
Simple abbreviating of the projection.
.ie n .IP "$obj\->\fBproj4\fR( [ <$nick|$proj4> ] )" 4
.el .IP "\f(CW$obj\fR\->\fBproj4\fR( [ <$nick|$proj4> ] )" 4
.IX Item "$obj->proj4( [ <$nick|$proj4> ] )"
.PD 0
.IP "Geo::Proj\->\fBproj4\fR( [ <$nick|$proj4> ] )" 4
.IX Item "Geo::Proj->proj4( [ <$nick|$proj4> ] )"
.PD
Returns the projection library handle (a Geo::Proj4) to be used by this
component.  As class method, the \f(CW$nick\fR is specified for a lookup.  In case
a \f(CW$proj4\fR is specified, that is returned.
.Sp
example:
.Sp
.Vb 4
\& my $wgs84 = Geo::Proj\->new(nick => \*(Aqwgs84\*(Aq, ...);
\& my $wgs84_proj4 = Geo::Proj\->proj4(\*(Aqwgs84\*(Aq);
\& my $wgs84_proj4 = Geo::Proj\->proj4($wgs84);
\& my $wgs84_proj4 = $wgs84\->proj4;
.Ve
.ie n .IP "$obj\->\fBsrid\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBsrid\fR()" 4
.IX Item "$obj->srid()"
The \*(L"Spatial Reference System \s-1ID\*(R"\s0 if known.
.SS "Projecting"
.IX Subsection "Projecting"
.IP "Geo::Proj\->\fBdefaultProjection\fR( [ <$nick|$proj> ] )" 4
.IX Item "Geo::Proj->defaultProjection( [ <$nick|$proj> ] )"
The \f(CW$nick\fR must be defined with \fBnew()\fR.  Returned is the Geo::Proj object
for the default projection.  The default is the first name created,
which probably is 'wgs84' (when \fBimport()\fR had a chance)
.IP "Geo::Proj\->\fBdumpProjections\fR( [$fh] )" 4
.IX Item "Geo::Proj->dumpProjections( [$fh] )"
Print details about the defined projections to the \f(CW$fh\fR, which
defaults to the selected.  Especially useful for debugging.
.IP "Geo::Proj\->\fBlistProjections\fR()" 4
.IX Item "Geo::Proj->listProjections()"
Returns a sorted lost of projection nicks.
.IP "Geo::Proj\->\fBprojection\fR( <$nick|$proj> )" 4
.IX Item "Geo::Proj->projection( <$nick|$proj> )"
Returns the Geo::Proj object, defined with \f(CW$nick\fR.  In case such an
object is passed in as \f(CW$proj\fR, it is returned unaffected.  This method is
used where in other methods \s-1NICKS\s0 or \f(CW$proj\fR can be used as arguments.
.Sp
example:
.Sp
.Vb 2
\& my $wgs84 = Geo::Proj\->projection(\*(Aqwgs84\*(Aq);
\& my $again = Geo::Proj\->projection($wgs84);
.Ve
.ie n .IP "$obj\->\fBto\fR( [<$proj|$nick>], <$proj|$nick>, $point|ARRAY\-of\-$points )" 4
.el .IP "\f(CW$obj\fR\->\fBto\fR( [<$proj|$nick>], <$proj|$nick>, \f(CW$point\fR|ARRAY\-of\-$points )" 4
.IX Item "$obj->to( [<$proj|$nick>], <$proj|$nick>, $point|ARRAY-of-$points )"
.PD 0
.ie n .IP "Geo::Proj\->\fBto\fR( [<$proj|$nick>], <$proj|$nick>, $point|ARRAY\-of\-$points )" 4
.el .IP "Geo::Proj\->\fBto\fR( [<$proj|$nick>], <$proj|$nick>, \f(CW$point\fR|ARRAY\-of\-$points )" 4
.IX Item "Geo::Proj->to( [<$proj|$nick>], <$proj|$nick>, $point|ARRAY-of-$points )"
.PD
Expects an Geo::Proj to project the \f(CW$point\fR or \f(CW$points\fR to.  The work
is done by \fBGeo::Proj4::transform()\fR.  As class method, you have to
specify two nicks or projections.
.Sp
Be warned that this \fBto()\fR method expects POINTs which are
\&\fBnot\fR Geo::Point objects, but which themselves are an \s-1ARRAY\s0
containing X,Y and optionally a Z coordinate.
.Sp
example:
.Sp
.Vb 3
\& my $p2 = $wgs84\->to(\*(Aqutm31\-wgs84\*(Aq, $p1);
\& my $p2 = $wgs84\->to($utm, $p1);
\& my $p2 = Geo::Proj\->to(\*(Aqwgs84\*(Aq, \*(Aqutm31\-wgs84\*(Aq, $p1);
.Ve
.SS "\s-1UTM\s0"
.IX Subsection "UTM"
.ie n .IP "Geo::Proj\->\fBUTMprojection\fR( <$datum|$proj|undef>, $zone )" 4
.el .IP "Geo::Proj\->\fBUTMprojection\fR( <$datum|$proj|undef>, \f(CW$zone\fR )" 4
.IX Item "Geo::Proj->UTMprojection( <$datum|$proj|undef>, $zone )"
The \f(CW$proj\fR is a Geo::Proj which is used to collect the datum
information from if no \f(CW$datum\fR 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.
.Sp
example:
.Sp
.Vb 2
\& my $proj = Geo::Proj\->UTMprojection(\*(AqWGS84\*(Aq, 31) or die;
\& print $proj\->nick;    # for instance utm31\-wgs84
.Ve
.ie n .IP "$obj\->\fBbestUTMprojection\fR( $point, [$proj|$nick] )" 4
.el .IP "\f(CW$obj\fR\->\fBbestUTMprojection\fR( \f(CW$point\fR, [$proj|$nick] )" 4
.IX Item "$obj->bestUTMprojection( $point, [$proj|$nick] )"
.PD 0
.ie n .IP "Geo::Proj\->\fBbestUTMprojection\fR( $point, [$proj|$nick] )" 4
.el .IP "Geo::Proj\->\fBbestUTMprojection\fR( \f(CW$point\fR, [$proj|$nick] )" 4
.IX Item "Geo::Proj->bestUTMprojection( $point, [$proj|$nick] )"
.PD
Returns the best \s-1UTM\s0 projection for some \f(CW$point\fR.  As class method, you
specify the nickname or the object for the point.
.Sp
example:
.Sp
.Vb 3
\& my $point = Geo::Point\->longlat(2.234, 52.12);
\& my $proj  = Geo::Proj\->bestUTMprojection($point);
\& print $proj\->nick;    # for instance utm31\-wgs84
.Ve
.ie n .IP "$obj\->\fBzoneForUTM\fR($point)" 4
.el .IP "\f(CW$obj\fR\->\fBzoneForUTM\fR($point)" 4
.IX Item "$obj->zoneForUTM($point)"
.PD 0
.IP "Geo::Proj\->\fBzoneForUTM\fR($point)" 4
.IX Item "Geo::Proj->zoneForUTM($point)"
.PD
Provided some point, figure-out which zone is most optimal for representing
the point.  In \s-1LIST\s0 context, zone number, zone letter, and meridian are
returned as separate scalars.  In \s-1LIST\s0 context, the zone number and letter
are returned as one..
.Sp
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.
.SH "OVERLOADING"
.IX Header "OVERLOADING"
.ie n .IP "overload: \fB'""""' (stringification)\fR" 4
.el .IP "overload: \fB'``''' (stringification)\fR" 4
.IX Item "overload: '""""' (stringification)"
Returns the nick-name for this projection.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of Geo-Point distribution version 0.98,
built on February 01, 2019. Website: \fIhttp://perl.overmeer.net/CPAN/\fR
.SH "LICENSE"
.IX Header "LICENSE"
Copyrights 2005\-2019 by [Mark Overmeer]. For other contributors see ChangeLog.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See \fIhttp://dev.perl.org/licenses/\fR