Geo::Point(3pm) 					User Contributed Perl Documentation					   Geo::Point(3pm)

NAME

       Geo::Point - a point on the globe

INHERITANCE

	Geo::Point
	  is a Geo::Shape

SYNOPSIS

	use Geo::Point;

	my $p = Geo::Point->latlong(1,2);
	my $p = Geo::Point->longlat(2,1);

	my $w = Geo::Proj->new(wgs84 => ...);
	my $p = Geo::Point->latlong(1,2, 'wgs84');

	my ($lat, $long) = $p->latlong;
	my ($x, $y) = $p->xy;
	my ($x, $y) = $p->in('utm31-wgs84');

	my $p = Geo::Point->xy(1,2);

DESCRIPTION

       One location on the globe, in any coordinate system.  This package tries to hide the maths and the coordinate system in which the point is
       represented.

       One of the most confusing things when handling geometrical data, is that sometimes latlong, sometimes xy are used: horizontal and vertical
       organization reversed.  This packages tries to hide this from your program by providing abstract accessors latlong(), longlat(), xy(), and
       yx().

METHODS

   Constructors
       Geo::Point->fromString(STRING, {PROJECTION])

	   Create a new point from a STRING.  The coordinates can be separated by a comma (preferrably), or blanks.  When the coordinates end on
	   NSEW, the order does not matter, otherwise lat-long or xy order is presumed.

	   This routine is very smart.	It understands:
	    PROJLABEL VALUE VALUE
	    PROJLABEL: VALUE VALUE
	    PROJLABEL, VALUE, VALUE
	    PROJLABEL: VALUE, VALUE
	    VALUE VALUE
	    VALUE, VALUE
	    utm: ZONE, VALUE, VALUE   # also without commas and ':'
	    utm: VALUE, VALUE, ZONE   # also without commas and ':'
	    utm: VALUE, VALUE	      # also without commas and ':'
	    ZONE, VALUE, VALUE	      # also without commas and ':'
	    VALUE, VALUE, ZONE	      # also without commas and ':'

	   The VALUE must be suitable for projection.  If only two values are provided, a "d", single or double quote, or trailing/leading "e",
	   "w", "n", "s" (either lower or upper-case) will force a latlong projection.	Those coordinates must follow the rules of dms2deg().

	   example: point from string

	    my $x = 'utm 31n 12311.123 34242.12'; # utm zone 31N
	    my $x = '12311.123 34242.12 31';	  # utm zone 31
	    my $x = '123.123E 12.34';		  # wgs84  latlong
	    my $x = 'clrk66 123.123 12.34';	  # clrk66 latlong
	    my $x = '12d34'123.1W 11.1123';	  # wgs84  longlat

	    my $p = Geo::Point->fromString($x);

	    # When parsing user applications, you probably want:
	    my $p = eval { Geo::Point->fromString($x) };
	    warn $@ if $@;

       $obj->latlong([LAT, LONG, [PROJ] ] | [PROJ])

       Geo::Point->latlong([LAT, LONG, [PROJ] ] | [PROJ])

	   When called as class method, you create a new point.  Provide a LATitude and LONGitude. The optional PROJection tells in which
	   coordinate system.

	   As instance method, the latitude and longitude are reported.  You can ask it to be translated into the PROJ coordinate system first.

	   When PROJ is undefined, none is presumed. The project must be specified as string, which referse to a projection defined by Geo::Proj.
	   See also longlat(), xy(), and yx().

	   example: latlong as class method

	    my $wgs84 = Geo::Proj->new(wgs84 => ...);
	    my $gp    = Geo::Point->latlong(52.3213, 5.53, 'wgs84');

	   example: latlong as instance method

	    my ($lat, $long) = $gp->latlong('wgs84');

       $obj->longlat([LONG, LAT, [PROJ] ] | [PROJ])

       Geo::Point->longlat([LONG, LAT, [PROJ] ] | [PROJ])

	   Like latlong(), but with the coordinates reversed.  Some applications prefer this.

       Geo::Point->new(OPTIONS)

	Option	 --Defined in	  --Default
	lat			    undef
	latitude		    undef
	long			    undef
	longitude		    undef
	proj	   Geo::Shape	    see Geo::Proj::defaultProjection()
	x			    undef
	y			    undef

	   . lat => COORDINATE

	   . latitude => COORDINATE

	   . long => COORDINATE

	   . longitude => COORDINATE

	   . proj => LABEL

	   . x => COORDINATE

	   . y => COORDINATE

       $obj->xy([X, Y, [PROJ] ] | [PROJ])

       Geo::Point->xy([X, Y, [PROJ] ] | [PROJ])

	   Like latlong() but now for carthesian projections.  Usually, the coordinate order is reversed.  See also yx().

       $obj->yx([Y, X, [PROJ] ] | [PROJ])

       Geo::Point->yx([Y, X, [PROJ] ] | [PROJ])

	   Like latlong() but now for carthesian projections.  Usually, the coordinate order is reversed.  See also xy().

   Attributes
       $obj->proj

	   See "Attributes" in Geo::Shape

       $obj->proj4

	   See "Attributes" in Geo::Shape

   Accessors
       The accessors only work correctly when you are sure that the point is in the right coordinate systems.

       $obj->lat

       $obj->latitude

       $obj->long

       $obj->longitude

       $obj->x

       $obj->y

   Projections
       $obj->in(LABEL|'utm')

	   See "Projections" in Geo::Shape

       $obj->normalize

	   Be sure the that coordinates are between -180/180 longitude, -90/90 lattitude.  No changes for non-latlong projections.

       $obj->projectOn(NICK, POINTS)

	   See "Projections" in Geo::Shape

   Geometry
       $obj->area

	   Always returns zero.

       $obj->bbox

	   The bounding box of a point contains twice itself.

       $obj->bboxCenter

	   See "Geometry" in Geo::Shape

       $obj->bboxRing([XMIN, YMIN, XMAX, YMAX, [PROJ]])

       Geo::Point->bboxRing([XMIN, YMIN, XMAX, YMAX, [PROJ]])

	   See "Geometry" in Geo::Shape

       $obj->distance(OBJECT, [UNIT])

	   See "Geometry" in Geo::Shape

       $obj->distancePointPoint(GEODIST, UNITS, POINT)

	   Compute the distance between the current point and some other POINT in UNITS.  The GEODIST object will do the calculations.	See
	   distance().

       $obj->inBBox(OBJECT)

	   Returns a true value if this point is inside the bounding box of the specified OBJECT.  The borders of the bbox are included.  This is
	   relatively fast to check, even for complex objects.	When the projections differ, the point is translated into the OBJECT's coordinate
	   system, because that one must stay square.

       $obj->perimeter

	   Always returns zero.

       $obj->sameAs(OTHER, TOLERANCE)

   Display
       $obj->coords

	   Returns the coordinates in their usual order, formatted as string with a joining blank;

       $obj->coordsUsualOrder

	   Returns the coordinates in the order which is usual for the projection used.

       $obj->deg2dm(DEGREES, POS, NEG)

       Geo::Point->deg2dm(DEGREES, POS, NEG)

	   See "Display" in Geo::Shape

       $obj->deg2dms(DEGREES, POS, NEG)

       Geo::Point->deg2dms(DEGREES, POS, NEG)

	   See "Display" in Geo::Shape

       $obj->dm([PROJECTION])

	   Like dms(), but doesn't show seconds.

       $obj->dmHTML([PROJECTION])

	   Like dmsHTML(), but does not show seconds.

       $obj->dms([PROJECTION])

	   Show the point as DMS value-pair.  You must be sure that the coordinate is a projection for which is it usefull to represent the values
	   in DMS.  In SCALAR context, one string is returned.	In LIST context, the values are returned separately in latlong order.

	   Be warned, that the returned string may contain single and double quote characters, which may confuse HTML (see dmsHTML()).

       $obj->dms2deg(DMS)

       Geo::Point->dms2deg(DMS)

	   See "Display" in Geo::Shape

       $obj->dmsHTML([PROJECTION])

	   Like dms(), but all character which are troublesome for HTML are translated into character codes.

       $obj->moveWest

	   Move a point from the eastern calculations into the western calculations, resulting in a value below -180.  This is usefull when this
	   point is part of a larger construct, like the corners of a satellite image, which are both sides of the -180 meridian.

	   example: moving West

	    my $point = Geo::Point->latlong(24, 179);
	    $point->moveWest;
	    print $point->long;   # -181;

       $obj->toString([PROJECTION])

	   Returns a string representation of the point, which is also used for stringification.  The default projection is the one of the point.

	   example:

	    print "Point: ",$gp->toString, "
";
	    print "Point: $gp
";   # same

	    print "Point: ",$gp->toString('clrk66'), "
";

DIAGNOSTICS

       Error: UTM requires 3 values: easting, northing, and zone

       Error: can only compare a point to an other Geo::Point

       Error: distance calculation not implemented between a $kind and a $kind

	   Only a subset of all objects can be used in the distance calculation.  The limitation is purely caused by lack of time to implement
	   this.

       Error: dms latitude coordinate not understood: $string

	   See dms2deg() for permitted formats.

       Error: dms longitude coordinate not understood: $string

	   See dms2deg() for permitted formats.

       Error: illegal UTM zone in $string

	   A UTM zone can be detected at the beginning or at the end of the input.  It contains a number (from 1 upto 60) and an optional latitude
	   indication (C upto X, except I and O).

       Error: illegal character in x coordinate $x

       Error: illegal character in y coordinate $y

       Error: in() not implemented for a $class

       Error: too few values in $string (got @parts)

	   Most projection require two parameters, but utm requires three (with zone).

       Error: too many values in $string (got @parts)

	   Most projection require two parameters, but utm requires three (with zone).

       Error: undefined projection $proj for $string

	   The projection you used (or is set as default) is not defined.  See Geo::Proj::new() about how to defined them.

SEE ALSO

       This module is part of Geo-Point distribution version 0.93, built on May 19, 2010. Website: http://perl.overmeer.net/geo/ All modules in
       this suite: "Geo::Point", "Geo::Proj4", "Geo::WKT", "Math::Polygon", "Geo::GML", "Geo::ISO19139", "Geo::EOP", "Geo::Format::Envisat", and
       "Geo::Format::Landsat".

       Please post questions or ideas to the mailinglist at http://geo-perl@list.hut.fi

LICENSE

       Copyrights 2005-2010 by Mark Overmeer. For other contributors see ChangeLog.

       This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.  See
       http://www.perl.com/perl/misc/Artistic.html

perl v5.14.2							    2010-05-19							   Geo::Point(3pm)