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 package tries to hide this from your program by providing
abstract accessors
latlong(),
longlat(),
xy(), and
yx().
Extends "DESCRIPTION" in Geo::Shape.
METHODS¶
Extends "METHODS" in Geo::Shape.
Constructors¶
Extends "Constructors" in Geo::Shape.
- 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 longlat() 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¶
Extends "Attributes" in Geo::Shape.
- $obj->proj()
- Inherited, see "Attributes" in Geo::Shape
- $obj->proj4()
- Inherited, 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¶
Extends "Projections" in Geo::Shape.
- $obj->in(<$label|'utm'>)
- Inherited, 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)
- Inherited, see "Projections" in Geo::Shape
Geometry¶
Extends "Geometry" in Geo::Shape.
- $obj->area()
- Always returns zero.
- $obj->bbox()
- The bounding box of a point contains twice itself.
- $obj->bboxCenter()
- Inherited, see "Geometry" in Geo::Shape
- $obj->bboxRing([$xmin, $ymin, $xmax, $ymax, [$proj]])
- Geo::Point->bboxRing([$xmin, $ymin, $xmax, $ymax, [$proj]])
- Inherited, see "Geometry" in Geo::Shape
- $obj->distance($object, [$unit])
- Inherited, 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¶
Extends "Display" in Geo::Shape.
- $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)
- Inherited, see "Display" in Geo::Shape
- $obj->deg2dms($degrees, $pos, $neg)
- Geo::Point->deg2dms($degrees, $pos, $neg)
- Inherited, 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 useful 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)
- Inherited, 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 useful 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, "\n";
print "Point: $gp\n"; # same
print "Point: ",$gp->toString('clrk66'), "\n";
OVERLOAD¶
Extends "OVERLOAD" in Geo::Shape.
- overload: '""' (stringification)
- Inherited, see "OVERLOAD" in Geo::Shape
- overload: 'bool' (truth value)
- Inherited, see "OVERLOAD" in Geo::Shape
DIAGNOSTICS¶
- Error: UTM requires 3 values: easting, northing, and zone
- Error: can only compare a point to another 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.96, built on January 21,
2014. 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-2014 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