.\" 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::Proj4 3pm"
.TH Geo::Proj4 3pm "2019-07-11" "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::Proj4 \- PROJ.4 cartographic projections library
.SH "INHERITANCE"
.IX Header "INHERITANCE"
.Vb 2
\& Geo::Proj4
\&   is a DynaLoader
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\&  use Geo::Proj4;
\&
\&  my $proj = Geo::Proj4\->new(proj => "merc",
\&     ellps => "clrk66", lon_0 => \-96)
\&       or die "parameter error: ".Geo::Proj4\->error. "\en";
\&
\&  my $proj = Geo::Proj4\->new("+proj=merc +ellps=clrk66 +lon_0=\-96")
\&       or die "parameter error: ".Geo::Proj4\->error. "\en";
\&
\&  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, \e@points);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
The Open Source \s-1PROJ.4\s0 library converts between geographic coordinate
systems.  It is able to convert between geodetic latitude and longitude
(\s-1LL,\s0 most commonly the \s-1WGS84\s0 projection), into an enormous variety of
other cartographic projections (\s-1XY,\s0 usually \s-1UTM\s0).
.PP
\&\s-1WARNING:\s0 It is not always clear what the source projection is when
\&\fBforward()\fR or \fBinverse()\fR 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 \fBtransform()\fR.
.SH "METHODS"
.IX Header "METHODS"
.SS "Instantiation"
.IX Subsection "Instantiation"
.IP "Geo::Proj4\->\fBnew\fR($string|%options)" 4
.IX Item "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 \f(CW\*(C`cs2cs \-lP\*(C'\fR.  The manual
page of \f(CW\*(C`cs2cs\*(C'\fR explains how the configuration works.
.Sp
Two ways are provided to define the projection.  Either, use a list
of \f(CW%options\fR, which are pairs of parameters, or pass one string which
contains all parameters at once.  You must supply a \f(CW\*(C`proj\*(C'\fR parameter.
.Sp
In case of an \s-1OPTION\s0 list: \s-1WARNING:\s0 Specify boolean parameters (e.g. the
south parameter to the \s-1UTM\s0 projection) with a matching value of undef.
.Sp
example:
.Sp
.Vb 3
\& 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");
.Ve
.SS "Accessors"
.IX Subsection "Accessors"
.ie n .IP "$obj\->\fBdatum\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBdatum\fR()" 4
.IX Item "$obj->datum()"
Tries to return a datum name for this projection.
.ie n .IP "$obj\->\fBdump\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBdump\fR()" 4
.IX Item "$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.
.IP "Geo::Proj4\->\fBerror\fR()" 4
.IX Item "Geo::Proj4->error()"
Returns a dualvar (see Scalar::Util) containing the
error number and error string of the last reported error.
.Sp
example:
.Sp
.Vb 6
\& my $proj = Geo::Proj4\->new(...);
\& unless(defined $proj)
\& {   my $error = Geo::Proj4\->error;
\&     warn "error\-code: ".$error+0;
\&     warn "error\-string: $error\en";
\& }
.Ve
.ie n .IP "$obj\->\fBhasInverse\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBhasInverse\fR()" 4
.IX Item "$obj->hasInverse()"
Returns whether the reverse function for the projection exists.  Some
projections are one-way.
.ie n .IP "$obj\->\fBisGeocentric\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBisGeocentric\fR()" 4
.IX Item "$obj->isGeocentric()"
Returns true when the source projection is using a geocentric coordinate
system; i.e. uses x\-y coordinates.
.ie n .IP "$obj\->\fBisGeodesic\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBisGeodesic\fR()" 4
.IX Item "$obj->isGeodesic()"
Returns true when the source projection is using a geodetic coordinate
system; i.e. uses lat long coordinates.  Same as \fBisLatlong()\fR
.ie n .IP "$obj\->\fBisLatlong\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBisLatlong\fR()" 4
.IX Item "$obj->isLatlong()"
Returns true when the source projection is using a geodetic coordinate
system; i.e. uses lat long coordinates.  Same as \fBisGeodesic()\fR.
.ie n .IP "$obj\->\fBnormalized\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBnormalized\fR()" 4
.IX Item "$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.
.ie n .IP "$obj\->\fBprojection\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBprojection\fR()" 4
.IX Item "$obj->projection()"
Returns the projection type.
.SS "Converters"
.IX Subsection "Converters"
.ie n .IP "$obj\->\fBforward\fR($latitude, $longitude)" 4
.el .IP "\f(CW$obj\fR\->\fBforward\fR($latitude, \f(CW$longitude\fR)" 4
.IX Item "$obj->forward($latitude, $longitude)"
Perform a forward projection from \f(CW$latitude\fR and \f(CW$longitude\fR (\s-1LL\s0) to the
cartographic projection (\s-1XY\s0) represented by the Geo::Proj4 instance.
.Sp
\&\s-1WARNING:\s0 for historic reasons, latitude and longitude are assumed to be in 
(floating point) degrees, although the library expects rads.  See
\&\fBforwardRad()\fR. A latitude south of the Equator and longitude west of
the Prime Meridian given with negative values.
.Sp
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 \s-1LONG,LAT\s0 (not lat,long!)
.Sp
On error, \f(CW\*(C`forward\*(C'\fR will return undef for both values.
.Sp
example:
.Sp
.Vb 2
\& my ($x, $y) = $proj\->forward($lat, $lon);
\& my ($long2, $lat2) = $proj\->forward($lat, $lon);
.Ve
.ie n .IP "$obj\->\fBforwardRad\fR($latitude, $longitude)" 4
.el .IP "\f(CW$obj\fR\->\fBforwardRad\fR($latitude, \f(CW$longitude\fR)" 4
.IX Item "$obj->forwardRad($latitude, $longitude)"
Perform a forward projection from \f(CW$latitude\fR and \f(CW$longitude\fR (\s-1LL\s0) to the
cartographic projection (\s-1XY\s0) represented by the Geo::Proj4 instance.
This function reflects to library function \f(CW\*(C`forward()\*(C'\fR, expecting
radians, not degrees.
.ie n .IP "$obj\->\fBinverse\fR(($x,$y) | ($lat,$long))" 4
.el .IP "\f(CW$obj\fR\->\fBinverse\fR(($x,$y) | ($lat,$long))" 4
.IX Item "$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.
.Sp
\&\s-1WARNING:\s0 for historic reasons, latitude and longitude are assumed to be in 
(floating point) degrees, although the library expects rads.  See
\&\fBinverseRad()\fR.
.Sp
On error, \f(CW\*(C`inverse\*(C'\fR will return undef for both values.
.Sp
example:
.Sp
.Vb 4
\&  if($proj\->hasInverse)
\&  {  my ($lat, $lon) = $proj\->inverse($x, $y);
\&     ...
\&  }
.Ve
.ie n .IP "$obj\->\fBinverseRad\fR(($x,$y) | ($lat|$long))" 4
.el .IP "\f(CW$obj\fR\->\fBinverseRad\fR(($x,$y) | ($lat|$long))" 4
.IX Item "$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
\&\fBinverse()\fR.
.ie n .IP "$obj\->\fBtransform\fR($to, $point|ARRAY\-of\-$points)" 4
.el .IP "\f(CW$obj\fR\->\fBtransform\fR($to, \f(CW$point\fR|ARRAY\-of\-$points)" 4
.IX Item "$obj->transform($to, $point|ARRAY-of-$points)"
Translate the \f(CW$points\fR into the projecten of \f(CW$to\fR.  Each point is specified
as two or three values in an \s-1ARRAY.\s0  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 \fBtransformRad()\fR
.Sp
example:
.Sp
.Vb 2
\& 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];
.Ve
.ie n .IP "$obj\->\fBtransformRad\fR($to, $point|ARRAY\-of\-$points)" 4
.el .IP "\f(CW$obj\fR\->\fBtransformRad\fR($to, \f(CW$point\fR|ARRAY\-of\-$points)" 4
.IX Item "$obj->transformRad($to, $point|ARRAY-of-$points)"
Translate the \f(CW$points\fR into the projecten of \f(CW$to\fR.  Each point is specified
as two or three values in an \s-1ARRAY.\s0  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 \fBtransform()\fR
.SS "Library introspection"
.IX Subsection "Library introspection"
.IP "Geo::Proj4\->\fBdatumInfo\fR($label)" 4
.IX Item "Geo::Proj4->datumInfo($label)"
Returns a hash with information about the specified datum.  With
\&\fBlistDatums()\fR, all defined \s-1LABELS\s0 can be found.
.IP "Geo::Proj4\->\fBellipsoidInfo\fR($label)" 4
.IX Item "Geo::Proj4->ellipsoidInfo($label)"
Returns a hash with information about the specified ellipsis.  With
\&\fBlistEllipsoids()\fR, all defined \s-1LABELS\s0 can be found.
.ie n .IP "$obj\->\fBlibVersion\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBlibVersion\fR()" 4
.IX Item "$obj->libVersion()"
.PD 0
.IP "Geo::Proj4\->\fBlibVersion\fR()" 4
.IX Item "Geo::Proj4->libVersion()"
.PD
Returns the version of the proj4 library
.IP "Geo::Proj4\->\fBlistDatums\fR()" 4
.IX Item "Geo::Proj4->listDatums()"
Returns a list with all defined datum labels.
.Sp
example:
.Sp
.Vb 4
\& foreach my $id (Geo::Proj4\->listDatums)
\& {   my $def = Geo::Proj4\->datum($id);
\&     print "$id = $def\->{ellips_id}\en";
\& }
.Ve
.IP "Geo::Proj4\->\fBlistEllipsoids\fR()" 4
.IX Item "Geo::Proj4->listEllipsoids()"
Returns a list with all defined ellips labels.
.Sp
example:
.Sp
.Vb 4
\& foreach my $id (Geo::Proj4\->listEllipsoids)
\& {   my $def = Geo::Proj4\->ellipsoid($id);
\&     print "$id = $def\->{name}\en";
\& }
.Ve
.IP "Geo::Proj4\->\fBlistTypes\fR()" 4
.IX Item "Geo::Proj4->listTypes()"
Returns a list with all defined projection types.
.Sp
example:
.Sp
.Vb 4
\& foreach my $id (Geo::Proj4\->listTypes)
\& {   my $def = Geo::Proj4\->type($id);
\&     print "$id = $def\->{description}\en";
\& }
.Ve
.IP "Geo::Proj4\->\fBlistUnits\fR()" 4
.IX Item "Geo::Proj4->listUnits()"
Returns a list with all defined unit labels.
.Sp
example:
.Sp
.Vb 4
\& foreach my $id (Geo::Proj4\->listUnits)
\& {   my $def = Geo::Proj4\->unit($id);
\&     print "$id = $def\->{name}\en";
\& }
.Ve
.IP "Geo::Proj4\->\fBtypeInfo\fR($label)" 4
.IX Item "Geo::Proj4->typeInfo($label)"
Returns a hash with information about the specified projection type.  With
\&\fBlistTypes()\fR, all defined \s-1LABELS\s0 can be found.
.IP "Geo::Proj4\->\fBunitInfo\fR($label)" 4
.IX Item "Geo::Proj4->unitInfo($label)"
Returns a hash with information about the specified unit.  With
\&\fBlistUnits()\fR, all defined \s-1LABELS\s0 can be found.
.SH "DETAILS"
.IX Header "DETAILS"
.SS "Install"
.IX Subsection "Install"
Geo::Proj4 uses \s-1XS\s0 to wrap the \s-1PROJ.4\s0 cartographic projections library. You
will need to have the \s-1PROJ.4\s0 library installed in order to build and use
this module. You can get source code and binaries for the \s-1PROJ.4\s0 library
from its home page at <http://www.remotesensing.org/proj/>.
.SS "Projections"
.IX Subsection "Projections"
Covering all the possible projections and their arguments in \s-1PROJ.4\s0
is well beyond the scope of this document. However, the \f(CWcs2cs(1)\fR
utility that ships with \s-1PROJ.4\s0 will list the projections it knows about
by running \fBcs2cs \-lp\fR, the ellipsoid models it knows with the \fB\-le\fR
parameter, the units it knows about with \fB\-lu\fR, and the geodetic datums
it knows with \fB\-ld\fR. Read \fBcs2cs\fR\|(1) for more details.
.PP
Alternately, you can read the \s-1PROJ.4\s0 documentation, which can be found
on the project's homepage. There are links to PDFs, text documentation,
a \s-1FAQ,\s0 and more.
.SS "Bugs"
.IX Subsection "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 \fBforward()\fR and \fBinverse()\fR
cause this problem, always flipping the coordinate order.  The
\&\fBtransform()\fR method is much easier: input and output in x\-y/long\-lat
order.
.PP
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.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.IP "Error: \fBtransform()\fR expects array of points" 4
.IX Item "Error: transform() expects array of points"
.PD 0
.IP "Error: \fBtransformRad()\fR expects array of points" 4
.IX Item "Error: transformRad() expects array of points"
.PD
.SH "REFERENCES"
.IX Header "REFERENCES"
See the Geo::Point website at <http://perl.overmeer.net/geo/> for
an html version of this and related modules;
.PP
Effusive thanks to Frank Warmerdam (maintainer of \s-1PROJ.4\s0) and Gerald
Evenden (main contributor of \s-1PROJ.4\s0). Their \s-1PROJ.4\s0 library home page:
<http://www.remotesensing.org/proj/>
.PP
\&\fBproj\fR\|(1), \fBcs2cs\fR\|(1), \fBpj_init\fR\|(3).
.SH "COPYRIGHTS"
.IX Header "COPYRIGHTS"
Developed and maintained by Mark Overmeer <markov@cpan.org>.
Copyright (c) 2004\-2018 by the authors. All rights reserved.
.PP
Originally Written by Schuyler Erle <schuyler@nocat.net> and
Rich Gibson <rich@nocat.net>.  Their site: Mapping Hacks home
page: <http://www.mappinghacks.com>
.SH "LICENSE"
.IX Header "LICENSE"
This library is free software; you can redistribute it and/or modify
it under the same terms as Perl itself.