.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Geo::Shape 3pm"
.TH Geo::Shape 3pm "2019-02-21" "perl v5.28.1" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Geo::Shape \- base class for 2\-dimensional points on the earth surface
.SH "INHERITANCE"
.IX Header "INHERITANCE"
.Vb 5
\& Geo::Shape is extended by
\&   Geo::Line
\&   Geo::Point
\&   Geo::Space
\&   Geo::Surface
.Ve
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 1
\& 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(\*(Aqwgs84\*(Aq);                  # conversion
\& my $p4 = $p1\->in(\*(Aqutm\*(Aq);                    # conversion
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Base class for the many geo-spatial objects defined by the GeoPoint
distribution.
.SH "METHODS"
.IX Header "METHODS"
.SS "Constructors"
.IX Subsection "Constructors"
.ie n .IP "$obj\->\fBnew\fR(%options)" 4
.el .IP "\f(CW$obj\fR\->\fBnew\fR(%options)" 4
.IX Item "$obj->new(%options)"
.PD 0
.IP "Geo::Shape\->\fBnew\fR(%options)" 4
.IX Item "Geo::Shape->new(%options)"
.PD
Create a new object.
.Sp
.Vb 2
\& \-Option\-\-Default
\&  proj    see Geo::Proj::defaultProjection()
.Ve
.RS 4
.IP "proj => \s-1LABEL\s0" 2
.IX Item "proj => LABEL"
.RE
.RS 4
.RE
.SS "Attributes"
.IX Subsection "Attributes"
.PD 0
.ie n .IP "$obj\->\fBproj\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBproj\fR()" 4
.IX Item "$obj->proj()"
.PD
Returns the nickname of the projection used by the component.
\&\fBBe warned:\fR this is not a Geo::Point object, but just a label.
.ie n .IP "$obj\->\fBproj4\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBproj4\fR()" 4
.IX Item "$obj->proj4()"
Returns the proj4 object which handles the projection.
.SS "Projections"
.IX Subsection "Projections"
.ie n .IP "$obj\->\fBin\fR( <$label|'utm'> )" 4
.el .IP "\f(CW$obj\fR\->\fBin\fR( <$label|'utm'> )" 4
.IX Item "$obj->in( <$label|'utm'> )"
The coordinates of this point in a certain projection, referred to with
the \f(CW$label\fR.  The projection is defined with \fBnew()\fR.  When simply
\&'utm' is provided, the best \s-1UTM\s0 zone is selected.
.Sp
In \s-1LIST\s0 context, the coordinates are returned.  In \s-1SCALAR\s0 context,
a new object is returned.
.Sp
example:
.Sp
.Vb 1
\&  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(\*(Aqutm\*(Aq);
\&  my ($x, $y)  = $p_utm\->xy;
\&  my $label    = $p_utm\->proj;
\&  my ($datum, $zone) = $label =~ m/^utm\-(\ew+)\-(\ed+)$/;
.Ve
.ie n .IP "$obj\->\fBprojectOn\fR($nick, @points)" 4
.el .IP "\f(CW$obj\fR\->\fBprojectOn\fR($nick, \f(CW@points\fR)" 4
.IX Item "$obj->projectOn($nick, @points)"
The \f(CW@points\fR 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 \f(CW$nick\fR, but in
some cases (for instance \s-1UTM\s0) it may differ.
.SS "Geometry"
.IX Subsection "Geometry"
.ie n .IP "$obj\->\fBarea\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBarea\fR()" 4
.IX Item "$obj->area()"
Returns the area covered by the geo structure. Points will return zero.
.ie n .IP "$obj\->\fBbbox\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBbbox\fR()" 4
.IX Item "$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.
.ie n .IP "$obj\->\fBbboxCenter\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBbboxCenter\fR()" 4
.IX Item "$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.
.Sp
Be warned that the central point in one projection system may be quite
different from the central point in some other projectionsystem .
.ie n .IP "$obj\->\fBbboxRing\fR( [$xmin, $ymin, $xmax, $ymax, [$proj]] )" 4
.el .IP "\f(CW$obj\fR\->\fBbboxRing\fR( [$xmin, \f(CW$ymin\fR, \f(CW$xmax\fR, \f(CW$ymax\fR, [$proj]] )" 4
.IX Item "$obj->bboxRing( [$xmin, $ymin, $xmax, $ymax, [$proj]] )"
.PD 0
.ie n .IP "Geo::Shape\->\fBbboxRing\fR( [$xmin, $ymin, $xmax, $ymax, [$proj]] )" 4
.el .IP "Geo::Shape\->\fBbboxRing\fR( [$xmin, \f(CW$ymin\fR, \f(CW$xmax\fR, \f(CW$ymax\fR, [$proj]] )" 4
.IX Item "Geo::Shape->bboxRing( [$xmin, $ymin, $xmax, $ymax, [$proj]] )"
.PD
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.
.ie n .IP "$obj\->\fBdistance\fR( $object, [$unit] )" 4
.el .IP "\f(CW$obj\fR\->\fBdistance\fR( \f(CW$object\fR, [$unit] )" 4
.IX Item "$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.
.Sp
This calculation is performed with Geo::Distance in accurate mode.
The default \f(CW$unit\fR is kilometers.  Other units are provided in the manual
page of Geo::Distance.  As extra unit, \f(CW\*(C`degrees\*(C'\fR and \f(CW\*(C`radians\*(C'\fR are
added as well as the \f(CW\*(C`km\*(C'\fR alias for kilometer.
.ie n .IP "$obj\->\fBperimeter\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBperimeter\fR()" 4
.IX Item "$obj->perimeter()"
Returns the length of the outer border of the object's components.  For
points, this returns zero.
.SS "Display"
.IX Subsection "Display"
.ie n .IP "$obj\->\fBdeg2dm\fR($degrees, $pos, $neg)" 4
.el .IP "\f(CW$obj\fR\->\fBdeg2dm\fR($degrees, \f(CW$pos\fR, \f(CW$neg\fR)" 4
.IX Item "$obj->deg2dm($degrees, $pos, $neg)"
.PD 0
.ie n .IP "Geo::Shape\->\fBdeg2dm\fR($degrees, $pos, $neg)" 4
.el .IP "Geo::Shape\->\fBdeg2dm\fR($degrees, \f(CW$pos\fR, \f(CW$neg\fR)" 4
.IX Item "Geo::Shape->deg2dm($degrees, $pos, $neg)"
.PD
Like \fBdeg2dms()\fR but without showing seconds.
.Sp
example:
.Sp
.Vb 2
\& print $point\->deg2dm(0.12, \*(Aqe\*(Aq, \*(Aqw\*(Aq);
\& print Geo::Shape\->deg2dm(0.12, \*(Aqe\*(Aq, \*(Aqw\*(Aq);
.Ve
.ie n .IP "$obj\->\fBdeg2dms\fR($degrees, $pos, $neg)" 4
.el .IP "\f(CW$obj\fR\->\fBdeg2dms\fR($degrees, \f(CW$pos\fR, \f(CW$neg\fR)" 4
.IX Item "$obj->deg2dms($degrees, $pos, $neg)"
.PD 0
.ie n .IP "Geo::Shape\->\fBdeg2dms\fR($degrees, $pos, $neg)" 4
.el .IP "Geo::Shape\->\fBdeg2dms\fR($degrees, \f(CW$pos\fR, \f(CW$neg\fR)" 4
.IX Item "Geo::Shape->deg2dms($degrees, $pos, $neg)"
.PD
Translate floating point \f(CW$degrees\fR into a \*(L"degrees minutes seconds\*(R"
notation.  An attempt is made to handle rounding errors.
.Sp
example:
.Sp
.Vb 2
\& print $point\->deg2dms(\-12.34, \*(AqE\*(Aq, \*(AqW\*(Aq);\*(Aq     # \-\-> 12d20\*(Aq24"W
\& print Geo::Shape\->deg2dms(52.1234, \*(AqE\*(Aq, \*(AqW\*(Aq); # \-\-> 52d07\*(Aq24"E
.Ve
.ie n .IP "$obj\->\fBdms2deg\fR($dms)" 4
.el .IP "\f(CW$obj\fR\->\fBdms2deg\fR($dms)" 4
.IX Item "$obj->dms2deg($dms)"
.PD 0
.IP "Geo::Shape\->\fBdms2deg\fR($dms)" 4
.IX Item "Geo::Shape->dms2deg($dms)"
.PD
Accepts for instance 3d12'24.123, 3d12\*(L"E, 3.12314w, n2.14, s3d12\*(R",
\&\-12d34, and returns floating point degrees.
.SH "OVERLOAD"
.IX Header "OVERLOAD"
.ie n .IP "overload: \fB'""""' (stringification)\fR" 4
.el .IP "overload: \fB'``''' (stringification)\fR" 4
.IX Item "overload: '""""' (stringification)"
Returns a string \*(L"$proj($lat,$long)\*(R" or \*(L"$proj($x,$y)\*(R".  The \f(CW$proj\fR
is the nickname you have assigned to the projection.
.IP "overload: \fB'bool' (truth value)\fR" 4
.IX Item "overload: 'bool' (truth value)"
A point is always true: defined.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.ie n .IP "Error: distance calculation not implemented between a $kind and a $kind" 4
.el .IP "Error: distance calculation not implemented between a \f(CW$kind\fR and a \f(CW$kind\fR" 4
.IX Item "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.
.ie n .IP "Error: \fBin()\fR not implemented for a $class" 4
.el .IP "Error: \fBin()\fR not implemented for a \f(CW$class\fR" 4
.IX Item "Error: in() not implemented for a $class"
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of Geo-Point distribution version 0.98,
built on February 01, 2019. Website: \fIhttp://perl.overmeer.net/CPAN/\fR
.SH "LICENSE"
.IX Header "LICENSE"
Copyrights 2005\-2019 by [Mark Overmeer]. For other contributors see ChangeLog.
.PP
This program is free software; you can redistribute it and/or modify it
under the same terms as Perl itself.
See \fIhttp://dev.perl.org/licenses/\fR