NAME

Geo::Proj4 - Wrap the powerful PROJ.4 cartographic projections library

SYNOPSIS

use Geo::Proj4;

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

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

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

DESCRIPTION

This perl library converts geodetic latitude and longitude into an enormous variety of cartographic projections and back. 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/. See pj_init(3) for details on the internals.

METHODS

new( %args )

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

The contructor accepts a hash of parameters that will be passed on to the PROJ.4 library. You must supply a proj parameter identifying the target projection. Specify boolean parameters (e.g. the south parameter to the UTM projection) with a matching value of undef.

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

forward( $lat, $lon )

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

Perform a forward projection from latitude and longitude to the cartographic projection represented by $proj. Latitude and longitude are assumed to be in degrees, with latitude south of the Equator and longitude west of the Prime Meridian given with negative values. $x and $y are typically returned in meters, or whatever units are relevant to the given projection.

If PROJ.4 encounters an error, forward() will return undef for both values.

inverse( $x, $y )

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

Perform an inverse projection from the cartographic projection represented by $proj back into latitude and longitude. Units and error conditions are as described above.

EXAMPLES

To Convert from Lat/Long to UTM:
#!/usr/bin/perl

use strict;
use Geo::Proj4;

my $proj = Geo::Proj4->new( proj => "utm", zone => 10 );
my ($x, $y) = $proj->forward(38.40342, -122.81856);
print "conversion to UTM: y is  $y\n";
print "conversion to UTM: x is  $x\n";

my ($lat, $long) = $proj->inverse($x, $y);
print "inverse conversion: lat is $lat \n" ;
print "inverse conversion: long is $long \n" ;

ERRATA, BUGS, TODO, ETC.

One common source of errors is that latitude and longitude are swapped, or that the values have the wrong sign. Make sure you give negative values for south latitude and west longitude.

PROJ.4 offers a pj_transform() function that would be really cool to add to this module, but... PROJ.4 expects spherical coordinates (i.e. lat and long) in radians, whereas most ordinary people think of lat and long in degrees. Ordinarily, Geo::Proj4 takes care of this for you transparently, but in the case of the proposed transform() method, the list of points to be transformed between two cartographic projections might be spherical or planar in zero, one, or both of the input and output lists. We could supply helper functions to allow a developer to perform the degree-to-radian and reverse as needed before or after the call to transform(), but... would anyone use this, or would you just rely on cs2cs?

Passing undef as the value to a boolean parameter is an ugly interface.

Needs more tests! Especially of border cases.

Needs more samples in the samples directory!

SEE ALSO

PROJ.4 home page: http://www.remotesensing.org/proj/

Mapping Hacks home page: http://www.mappinghacks.com

proj(1), cs2cs(1), pj_init(3), Geo::Dymaxion(3pm), Geo::Coordinates::UTM(3pm)

AUTHORS

Schuyler Erle <schuyler@nocat.net>

Rich Gibson <rich@nocat.net>

EFFUSIVE THANKS TO...

Frank Warmerdam, maintainer of PROJ.4 and all around most excellent person.

Gerald Evenden. 'Essentially all work (on PROJ.4) was done by Gerald...'

COPYRIGHT

Copyright (C) 2004 by Schuyler Erle and Rich Gibson

LICENSE

This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.8.3 or, at your option, any later version of Perl 5 you may have available.