The London Perl and Raku Workshop takes place on 26th Oct 2024. If your company depends on Perl, please consider sponsoring and/or attending.
 / 
Geo-Point-0.03
River stage one • 7 direct dependents • 8 total dependents
/ Geo::Shape

NAME

Geo::Shape - base class for 2-dimensional points on the earth surface

SYNOPSIS

 !!!! BETA code, see README !!!!
 use Geo::Shape;

 my $p1 = Geo::Point->new(lat => 2.17, ...);
 my $p2 = Geo::Point->latlong(2.17, 3.14);   # wgs84 is default

 my $p3 = $p1->in('wgs84');                  # conversion
 my $p4 = $p1->in('utm');                    # conversion

DESCRIPTION

Base class for the many geo-spatial objects defined by the GeoPoint distribution.

METHODS

Constructors

Geo::Shape->new(OPTIONS)

    Create a new object.

     Option--Defined in--Default
 proj                <see Geo::Proj::defaultProjection()

    . proj LABEL

Attributes

$obj->proj

    Returns the nick of the projection used by the component.

Projections

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

    The coordinates of this point in a certain projection, refered to with the LABEL. The projection is defined with new(). When simply 'utm' is provided, the best UTM zone is selected.

    In LIST context, the coordinates are returned. In SCALAR context, a new object is returned.

    Example:

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

  # implicit conversion to wgs84, if not already in latlong
  my ($lat, $long) = $pr->latlong;

  # will select an utm zone for you
  my $p_utm    = $gp->in('utm');
  my ($x, $y)  = $p_utm->xy;
  my $label    = $p_utm->proj;
  my ($datum, $zone) = $label =~ m/^utm-(\w+)-(\d+)$/;

$obj->projectOn(NICK, POINTS)

    The POINTS are ARRAYS with each an X and Y coordinate of a single point in space. A list of transformed POINTS is returned, which is empty if no change is needed. The return list is preceeded by a projection NICK which is the result, usually the same as the provided NICK, but in some cases (for instance UTM) it may be different.

Geometry

$obj->area

    Returns the area covered by the geo structure. Points will return zero.

$obj->bbox

    Returns the bounding box of the object as four coordinates, respectively xmin, ymin, xmax, ymax. The values are expressed in the coordinate system of the object.

$obj->bboxCenter

    Returns a Geo::Point which represent the middle of the object. It is the center of the bounding box. The values is cached, once computed.

    Be warned that the central point in one projection system may be quite different from the central point in some other projectionsystem .

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

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

    Returns a Geo::Line which describes the outer bounds of the object called upon, counter-clockwise and left-bottom first. As class method, you need to specify the limits and the PROJection.

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

    Calculate the distance between this object and some other object. For many combinations of objects this is not supported or only partially supported.

    This calculation is performed with Geo::Distance in accurate mode. The default UNIT is kilometers. Other units are provided in the manual page of Geo::Distance. As extra unit, degrees and radians are added as well as the km alias for kilometer.

$obj->equal(OBJECT, [TOLERANCE])

    Same object, maybe defined as different object, maybe in a different coordinate system. When the coordinate systems are equivalent, no conversions are done. Otherwise, the second OBJECT is converted into the coordinate system of the callee.

$obj->perimeter

    Returns the length of the outer border of the object's components. For points, this returns zero.

$obj->sameAs(OTHER, TOLERANCE)

    See equal(). This method expects the OTHER object to have the same projection as the object at hand.

Display

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

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

    Like deg2dms() but without showing seconds.

    Example:

     print $point->deg2dm(0.12, 'e', 'w');
 print Geo::Shape->deg2dm(0.12, 'e', 'w');

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

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

    Example:

     print $point->deg2dms(0.12, 'e', 'w');
 print Geo::Shape->deg2dms(0.12, 'e', 'w');

$obj->dms2deg(DMS)

Geo::Shape->dms2deg(DMS)

    Accepts for instance 3d12'24.123, 3d12"E, 3.12314w, n2.14, s3d12", -12d34, and returns floating point degrees.

DIAGNOSTICS

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: in() not implemented for a $class

REFERENCES

See the Geo::Point website at http://perl.overmeer.net/geopoint for more details.

COPYRIGHTS

Module version 0.03. Written by Mark Overmeer (geopoint@overmeer.net). See the ChangeLog for other contributors.

Copyright (c) 2004-2005 by the author(s). All rights reserved. This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.