=encoding utf8

=head1 NAME

Math::Polygon::Clip - frame a polygon in a square

=head1 INHERITANCE

 Math::Polygon::Clip
   is an Exporter

=head1 SYNOPSIS

  my @poly  = ( [1,2], [2,4], [5,7], [1, 2] );
  my @box   = ( $xmin, $ymin, $xmax, $ymax );

  my $boxed = polygon_clip \@box, @poly;

=head1 DESCRIPTION

Cut-off all parts of the polygon which are outside the box

=head1 FUNCTIONS

=over 4

=item B<polygon_fill_clip1>(\@box, @points)

Clipping a polygon into rectangles can be done in various ways.
With this algorithm (which I designed myself, but may not be new), the
parts of the polygon which are outside the C<@box> are mapped on the borders.
The polygon stays in one piece.

Returned is one list of points, which is cleaned from double points,
spikes and superfluous intermediate points.

=item B<polygon_fill_clip2>(\@box, @points)

B<To be implemented>.  The polygon falls apart in fragments, which are not
connected: paths which are followed in two directions are removed.
This is required by some applications, like polygons used in geographical
context (country contours and such).

=item B<polygon_fill_clip3>( \@box, $out-$poly, [$in-$polys] )

B<To be implemented>.  A surrounding polygon, with possible
inclussions.

=item B<polygon_line_clip>(\@box, @points)

Returned is a list of ARRAYS (possibly 0 long) containing line pieces
from the input polygon (or line).

example: 

  my @points = ( [1,2], [2,3], [2,0], [1,-1], [1,2] );
  my @bbox   = ( 0, -2, 2, 2 );
  my @l      = polygon_line_clip \@bbox, @points;
  print scalar @l;      # 1, only one piece found
  my @first = @{$l[0]}; # first is [2,0], [1,-1], [1,2]

=back

=head1 SEE ALSO

This module is part of Math-Polygon version 2.00,
built on September 04, 2025. Website: F<http://perl.overmeer.net/CPAN/>

=head1 LICENSE

For contributors see file ChangeLog.

This software is copyright (c) 2004-2025 by Mark Overmeer.

This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.

