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; "Geo::GML",
"Geo::Point", "Geo::WKT" and "Math::Polygon"
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 <geo@overmeer.net>. Copyright
(c) 2004-2007 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.