=encoding utf8

=head1 NAME

Math::Polygon::Surface - Polygon with exclusions

=head1 SYNOPSIS

 my $outer   = Math::Polygon->new( [1,2], [2,4], [5,7], [1,2] );
 my $surface = Math::Polygon::Surface->new($outer);

=head1 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.

=head1 METHODS

=head2 Constructors

=over 4

=item $obj-E<gt>B<new>( [%options], [$polygons], %options )

=item Math::Polygon::Surface-E<gt>B<new>( [%options], [$polygons], %options )

You may add %options after and/or before the $polygons.  You may also use
the "outer" and "inner" options.  $polygons are references to ARRAYs of points,
each an ARRAY of X and Y, but better instantiated L<Math::Polygon|Math::Polygon> objects.

 -Option--Default
  inner   []
  outer   undef

=over 2

=item inner => ARRAY-OF-POLYGONS

The inner polygons, zero or more L<Math::Polygon|Math::Polygon> objects.

=item outer => POLYGON

The outer polygon, a L<Math::Polygon|Math::Polygon>.

=back

=back

=head2 Attributes

=over 4

=item $obj-E<gt>B<inner>()

Returns a list (often empty) of inner polygons.

=item $obj-E<gt>B<outer>()

Returns the outer polygon.

=back

=head2 Simple calculations

=over 4

=item B<area>()

Returns the area enclosed by the outer polygon, minus the areas of the
inner polygons.
See method L<Math::Polygon::area()|Math::Polygon/"Geometry">.

=item $obj-E<gt>B<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 L<Math::Polygon::bbox()|Math::Polygon/"Geometry">.

=item $obj-E<gt>B<perimeter>()

The length of the border: sums outer and inner perimeters.
See method L<Math::Polygon::perimeter()|Math::Polygon/"Geometry">.

=back

=head2 Clipping

=over 4

=item $obj-E<gt>B<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 $box are mapped on the borders.

All polygons are treated separately.

=item $obj-E<gt>B<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 L<Math::Polygon::lineClip()|Math::Polygon/"Clipping">.

=item $obj-E<gt>B<string>()

Translate the surface structure into some string.  Use Geo::WKT if you
need a standardized format.

Returned is a single string possibly containing multiple lines.  The first
line is the outer, the other lines represent the inner polygons.

=back

=head1 DIAGNOSTICS

=over 4

=item Error: surface requires outer polygon

=back

=head1 SEE ALSO

This module is part of Math-Polygon distribution version 1.04,
built on September 23, 2016. Website: F<http://perl.overmeer.net/geo/>

=head1 LICENSE

Copyrights 2004,2006-2016 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 F<http://www.perl.com/perl/misc/Artistic.html>