Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Geo::Proj4(3)	      User Contributed Perl Documentation	 Geo::Proj4(3)

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.

perl v5.24.1			  2014-01-21			 Geo::Proj4(3)

NAME | INHERITANCE | SYNOPSIS | DESCRIPTION | METHODS | DETAILS | DIAGNOSTICS | REFERENCES | COPYRIGHTS | LICENSE

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Geo::Proj4&sektion=3&manpath=FreeBSD+12.1-RELEASE+and+Ports>

home | help