
=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


$obj-E<gt>B<new>([OPTIONS], [POLYGONS], [OPTIONS])

Math::Polygon::Surface-E<gt>B<new>([OPTIONS], [POLYGONS], [OPTIONS])

=over 4

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  Defined in       Default
 inner                    []     
 outer                    undef  

. inner ARRAY-OF-POLYGONS

=over 4

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

=back

. outer POLYGON

=over 4

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

=back

=back

=head2 Attributes


$obj-E<gt>B<inner>

=over 4

Returns a list (often empty) of inner polygons.

=back

$obj-E<gt>B<outer>

=over 4

Returns the outer polygon.

=back

=head2 Simple calculations


B<area>

=over 4

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

=back

$obj-E<gt>B<bbox>

=over 4

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/"Simple calculations">.

=back

$obj-E<gt>B<perimeter>

=over 4

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

=back

=head2 Clipping


$obj-E<gt>B<fillClip1>(BOX)

=over 4

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.

=back

$obj-E<gt>B<lineClip>(BOX)

=over 4

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

=back



=head1 DIAGNOSTICS

I<Error:> Surface requires outer polygon







=head1 REFERENCES

See the Math::Polygon website at L<http://perl.overmeer.net/geo> for more details.

=head1 COPYRIGHTS

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

Copyright (c) 2004 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.


