.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32)
.\"
.\" 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
..
.if !\nF .nr F 0
.if \nF>0 \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
..
.    if !\nF==2 \{\
.        nr % 0
.        nr F 2
.    \}
.\}
.\" ========================================================================
.\"
.IX Title "Math::Polygon::Surface 3pm"
.TH Math::Polygon::Surface 3pm "2016-12-28" "perl v5.24.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"
Math::Polygon::Surface \- Polygon with exclusions
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\& my $outer   = Math::Polygon\->new( [1,2], [2,4], [5,7], [1,2] );
\& my $surface = Math::Polygon::Surface\->new($outer);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
A surface is one polygon which represents the outer bounds of an
array, plus optionally a list of polygons which represent exclusions
from that outer polygon.
.SH "METHODS"
.IX Header "METHODS"
.SS "Constructors"
.IX Subsection "Constructors"
.ie n .IP "$obj\->\fBnew\fR( [%options], [$polygons], %options )" 4
.el .IP "\f(CW$obj\fR\->\fBnew\fR( [%options], [$polygons], \f(CW%options\fR )" 4
.IX Item "$obj->new( [%options], [$polygons], %options )"
.PD 0
.ie n .IP "Math::Polygon::Surface\->\fBnew\fR( [%options], [$polygons], %options )" 4
.el .IP "Math::Polygon::Surface\->\fBnew\fR( [%options], [$polygons], \f(CW%options\fR )" 4
.IX Item "Math::Polygon::Surface->new( [%options], [$polygons], %options )"
.PD
You may add \f(CW%options\fR after and/or before the \f(CW$polygons\fR.  You may also use
the \*(L"outer\*(R" and \*(L"inner\*(R" options.  \f(CW$polygons\fR are references to ARRAYs of points,
each an \s-1ARRAY\s0 of X and Y, but better instantiated Math::Polygon objects.
.Sp
.Vb 3
\& \-Option\-\-Default
\&  inner   []
\&  outer   undef
.Ve
.RS 4
.IP "inner => ARRAY-OF-POLYGONS" 2
.IX Item "inner => ARRAY-OF-POLYGONS"
The inner polygons, zero or more Math::Polygon objects.
.IP "outer => \s-1POLYGON\s0" 2
.IX Item "outer => POLYGON"
The outer polygon, a Math::Polygon.
.RE
.RS 4
.RE
.SS "Attributes"
.IX Subsection "Attributes"
.ie n .IP "$obj\->\fBinner\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBinner\fR()" 4
.IX Item "$obj->inner()"
Returns a list (often empty) of inner polygons.
.ie n .IP "$obj\->\fBouter\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBouter\fR()" 4
.IX Item "$obj->outer()"
Returns the outer polygon.
.SS "Simple calculations"
.IX Subsection "Simple calculations"
.IP "\fBarea\fR()" 4
.IX Item "area()"
Returns the area enclosed by the outer polygon, minus the areas of the
inner polygons.
See method \fIMath::Polygon::area()\fR.
.ie n .IP "$obj\->\fBbbox\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBbbox\fR()" 4
.IX Item "$obj->bbox()"
Returns a list with four elements: (xmin, ymin, xmax, ymax), which describe
the bounding box of the surface, which is the bbox of the outer polygon.
See method \fIMath::Polygon::bbox()\fR.
.ie n .IP "$obj\->\fBperimeter\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBperimeter\fR()" 4
.IX Item "$obj->perimeter()"
The length of the border: sums outer and inner perimeters.
See method \fIMath::Polygon::perimeter()\fR.
.SS "Clipping"
.IX Subsection "Clipping"
.ie n .IP "$obj\->\fBfillClip1\fR($box)" 4
.el .IP "\f(CW$obj\fR\->\fBfillClip1\fR($box)" 4
.IX Item "$obj->fillClip1($box)"
Clipping a polygon into rectangles can be done in various ways.
With this algorithm, the parts of the polygon which are outside
the \f(CW$box\fR are mapped on the borders.
.Sp
All polygons are treated separately.
.ie n .IP "$obj\->\fBlineClip\fR($box)" 4
.el .IP "\f(CW$obj\fR\->\fBlineClip\fR($box)" 4
.IX Item "$obj->lineClip($box)"
Returned is a list of ARRAYS-OF-POINTS containing line pieces
from the input surface.  Lines from outer and inner polygons are
undistinguishable.
See method \fIMath::Polygon::lineClip()\fR.
.ie n .IP "$obj\->\fBstring\fR()" 4
.el .IP "\f(CW$obj\fR\->\fBstring\fR()" 4
.IX Item "$obj->string()"
Translate the surface structure into some string.  Use Geo::WKT if you
need a standardized format.
.Sp
Returned is a single string possibly containing multiple lines.  The first
line is the outer, the other lines represent the inner polygons.
.SH "DIAGNOSTICS"
.IX Header "DIAGNOSTICS"
.IP "Error: surface requires outer polygon" 4
.IX Item "Error: surface requires outer polygon"
.SH "SEE ALSO"
.IX Header "SEE ALSO"
This module is part of Math-Polygon distribution version 1.05,
built on December 28, 2016. Website: \fIhttp://perl.overmeer.net/geo/\fR
.SH "LICENSE"
.IX Header "LICENSE"
Copyrights 2004,2006\-2016 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://www.perl.com/perl/misc/Artistic.html\fR