METHODS

Instantiation

$class->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.

$class->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];
» Error: transform() expects array of points
$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()

» Error: transformRad() expects array of points

Library introspection

$class->datumInfo( $label )

Returns a hash with information about the specified datum. With listDatums(), all defined LABELS can be found.

$class->ellipsoidInfo( $label )

Returns a hash with information about the specified ellipsis. With listEllipsoids(), all defined LABELS can be found.

$obj->libVersion
$class->libVersion

Returns the version of the proj4 library

$class->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";
 }
$class->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";
 }
$class->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";
 }
$class->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";
 }
$class->typeInfo( $label )

Returns a hash with information about the specified projection type. With listTypes(), all defined LABELS can be found.

$class->unitInfo( $label )

Returns a hash with information about the specified unit. With listUnits(), all defined LABELS can be found.