NAME

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

INHERITANCE

        Geo::Shape is extended by
          Geo::Line
          Geo::Point
          Geo::Space
          Geo::Surface

SYNOPSIS

        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--Default
             proj    see Geo::Proj::defaultProjection()

           proj => LABEL

   Attributes
       $obj->proj()
           Returns the nickname of the projection used by the component.  Be warned: this is not
           a Geo::Point object, but just a label.

       $obj->proj4()
           Returns the proj4 object which handles the projection.

   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
           returned list is preceded by the projection nick of the result; usually the same as
           the provided $nick, but in some cases (for instance UTM) it may differ.

   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->perimeter()
           Returns the length of the outer border of the object's components.  For points, this
           returns zero.

   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)
           Translate floating point $degrees into a "degrees minutes seconds" notation.  An
           attempt is made to handle rounding errors.

           example:

            print $point->deg2dms(-12.34, 'E', 'W');'     # --> 12d20'24"W
            print Geo::Shape->deg2dms(52.1234, 'E', 'W'); # --> 52d07'24"E

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

OVERLOAD

       overload: '""' (stringification)
           Returns a string "$proj($lat,$long)" or "$proj($x,$y)".  The $proj is the nickname you
           have assigned to the projection.

       overload: 'bool' (truth value)
           A point is always true: defined.

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

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