table of contents
Geo::Point(3pm) | User Contributed Perl Documentation | Geo::Point(3pm) |
NAME¶
Geo::Point - a point on the globeINHERITANCE¶
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
$obj-> latlong([LAT, LONG, [PROJ] ] | [PROJ])
Geo::Point-> latlong([LAT, LONG, [PROJ] ] | [PROJ])
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 ':'
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 $@;
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
example: latlong as instance method
$obj-> longlat([LONG, LAT, [PROJ] ] | [PROJ])
Geo::Point-> longlat([LONG, LAT, [PROJ] ] | [PROJ])
my $wgs84 = Geo::Proj->new(wgs84 => ...); my $gp = Geo::Point->latlong(52.3213, 5.53, 'wgs84');
my ($lat, $long) = $gp->latlong('wgs84');
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-> projSee "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-> yProjections¶
$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-> areaAlways 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-> coordsReturns 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
$obj-> toString([PROJECTION])
my $point = Geo::Point->latlong(24, 179); $point->moveWest; print $point->long; # -181;
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, "\n"; print "Point: $gp\n"; # same print "Point: ",$gp->toString('clrk66'), "\n";
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 $kindOnly 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.fiLICENSE¶
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.html2010-05-19 | perl v5.14.2 |