Merge pull request from RAMilewski/master

Synopses regions.scad
This commit is contained in:
Revar Desmera 2023-04-05 17:27:42 -07:00 committed by GitHub
commit 8e4b4cc3c0
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23

View file

@ -1,6 +1,6 @@
////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////
// LibFile: regions.scad // LibFile: regions.scad
// This file provides 2D boolean set operations on polygons, where you can // This file provides 2D Boolean set operations on polygons, where you can
// compute, for example, the intersection or union of the shape defined by point lists, producing // compute, for example, the intersection or union of the shape defined by point lists, producing
// a new point list. Of course, such operations may produce shapes with multiple // a new point list. Of course, such operations may produce shapes with multiple
// components. To handle that, we use "regions" which are lists of paths representing the polygons. // components. To handle that, we use "regions" which are lists of paths representing the polygons.
@ -9,7 +9,7 @@
// Includes: // Includes:
// include <BOSL2/std.scad> // include <BOSL2/std.scad>
// FileGroup: Advanced Modeling // FileGroup: Advanced Modeling
// FileSummary: Offsets and boolean geometry of 2D paths and regions. // FileSummary: Offsets and Boolean geometry of 2D paths and regions.
// FileFootnotes: STD=Included in std.scad // FileFootnotes: STD=Included in std.scad
////////////////////////////////////////////////////////////////////// //////////////////////////////////////////////////////////////////////
@ -43,6 +43,9 @@
// Function: is_region() // Function: is_region()
// Synopsis: Returns true if the input appears to be a region.
// Topics: Regions, Paths, Polygons, List Handling
// See Also: is_valid_region(), is_1region(), is_region_simple()
// Usage: // Usage:
// bool = is_region(x); // bool = is_region(x);
// Description: // Description:
@ -52,6 +55,9 @@ function is_region(x) = is_list(x) && is_path(x.x);
// Function: is_valid_region() // Function: is_valid_region()
// Synopsis: Returns true if the input is a valid region.
// Topics: Regions, Paths, Polygons, List Handling
// See Also: is_region(), is_1region(), is_region_simple()
// Usage: // Usage:
// bool = is_valid_region(region, [eps]); // bool = is_valid_region(region, [eps]);
// Description: // Description:
@ -208,6 +214,9 @@ function _polygon_crosses_region(region, poly, eps=EPSILON) =
// Function: is_region_simple() // Function: is_region_simple()
// Synopsis: Returns true if the input is a region with no corner contact.
// Topics: Regions, Paths, Polygons, List Handling
// See Also: is_region(), is_valid_region(), is_1region()
// Usage: // Usage:
// bool = is_region_simple(region, [eps]); // bool = is_region_simple(region, [eps]);
// Description: // Description:
@ -238,12 +247,15 @@ function is_region_simple(region, eps=EPSILON) =
// Function: make_region() // Function: make_region()
// Synopsis: Converts lists of intersecting polygons into valid regions.
// Topics: Regions, Paths, Polygons, List Handling
// See Also: force_region(), region()
//
// Usage: // Usage:
// region = make_region(polys, [nonzero], [eps]); // region = make_region(polys, [nonzero], [eps]);
// Description: // Description:
// Takes a list of polygons that may intersect themselves or cross each other // Takes a list of polygons that may intersect themselves or cross each other
// and converts it into a properly defined region without // and converts it into a properly defined region without these defects.
// these defects.
// Arguments: // Arguments:
// polys = list of polygons to use // polys = list of polygons to use
// nonzero = set to true to use nonzero rule for polygon membership. Default: false // nonzero = set to true to use nonzero rule for polygon membership. Default: false
@ -268,6 +280,9 @@ function make_region(polys,nonzero=false,eps=EPSILON) =
eps=eps); eps=eps);
// Function: force_region() // Function: force_region()
// Synopsis: Given a polygon returns a region.
// Topics: Regions, Paths, Polygons, List Handling
// See Also: make_region(), region()
// Usage: // Usage:
// region = force_region(poly) // region = force_region(poly)
// Description: // Description:
@ -280,6 +295,9 @@ function force_region(poly) = is_path(poly) ? [poly] : poly;
// Section: Turning a region into geometry // Section: Turning a region into geometry
// Module: region() // Module: region()
// Synopsis: Creates the 2D polygons described by the given region or list of polygons.
// Topics: Regions, Paths, Polygons, List Handling
// See Also: make_region(), region()
// Usage: // Usage:
// region(r, [anchor], [spin=], [cp=], [atype=]) [ATTACHMENTS]; // region(r, [anchor], [spin=], [cp=], [atype=]) [ATTACHMENTS];
// Description: // Description:
@ -321,6 +339,9 @@ module region(r, anchor="origin", spin=0, cp="centroid", atype="hull")
// Section: Gometrical calculations with regions // Section: Gometrical calculations with regions
// Function: point_in_region() // Function: point_in_region()
// Synopsis: Tests if a point is inside, outside, or on the border of a region.
// Topics: Regions, Points, Comparison
// See Also: region_area(), are_regions_equal()
// Usage: // Usage:
// check = point_in_region(point, region, [eps]); // check = point_in_region(point, region, [eps]);
// Description: // Description:
@ -356,6 +377,8 @@ function _point_in_region(point, region, eps=EPSILON, i=0, cnt=0) =
// Function: region_area() // Function: region_area()
// Synopsis: Computes the area of the specified valid region.
// Topics: Regions, Area
// Usage: // Usage:
// area = region_area(region); // area = region_area(region);
// Description: // Description:
@ -377,6 +400,8 @@ function region_area(region) =
function _clockwise_region(r) = [for(p=r) clockwise_polygon(p)]; function _clockwise_region(r) = [for(p=r) clockwise_polygon(p)];
// Function: are_regions_equal() // Function: are_regions_equal()
// Synopsis: Returns true if given regions are the same polygons.
// Topics: Regions, Polygons, Comparison
// Usage: // Usage:
// b = are_regions_equal(region1, region2, [either_winding]) // b = are_regions_equal(region1, region2, [either_winding])
// Description: // Description:
@ -483,6 +508,10 @@ function _region_region_intersections(region1, region2, closed1=true,closed2=tru
// Function: split_region_at_region_crossings() // Function: split_region_at_region_crossings()
// Synopsis: Splits regions where polygons touch and at intersections.
// Topics: Regions, Polygons, List Handling
// See Also: region_parts()
//
// Usage: // Usage:
// split_region = split_region_at_region_crossings(region1, region2, [closed1], [closed2], [eps]) // split_region = split_region_at_region_crossings(region1, region2, [closed1], [closed2], [eps])
// Description: // Description:
@ -546,6 +575,9 @@ function split_region_at_region_crossings(region1, region2, closed1=true, closed
// Function: region_parts() // Function: region_parts()
// Synopsis: Splits a region into a list of regions.
// Topics: Regions, List Handling
// See Also: split_region_at_region_crossings()
// Usage: // Usage:
// rgns = region_parts(region); // rgns = region_parts(region);
// Description: // Description:
@ -706,6 +738,8 @@ function _point_dist(path,pathseg_unit,pathseg_len,pt) =
// Function: offset() // Function: offset()
// Synopsis: Takes a 2D path, polygon or region and returns a path offset by an amount.
// Topics: Paths, Polygons, Regions
// Usage: // Usage:
// offsetpath = offset(path, [r=|delta=], [chamfer=], [closed=], [check_valid=], [quality=], [same_length=]) // offsetpath = offset(path, [r=|delta=], [chamfer=], [closed=], [check_valid=], [quality=], [same_length=])
// path_faces = offset(path, return_faces=true, [r=|delta=], [chamfer=], [closed=], [check_valid=], [quality=], [firstface_index=], [flip_faces=]) // path_faces = offset(path, return_faces=true, [r=|delta=], [chamfer=], [closed=], [check_valid=], [quality=], [firstface_index=], [flip_faces=])
@ -879,7 +913,7 @@ function offset(
) )
assert(parallelcheck, "Path contains a segment that reverses direction (180 deg turn)") assert(parallelcheck, "Path contains a segment that reverses direction (180 deg turn)")
let( let(
// This is a boolean array that indicates whether a corner is an outside or inside corner // This is a Boolean array that indicates whether a corner is an outside or inside corner
// For outside corners, the newcorner is an extension (angle 0), for inside corners, it turns backward // For outside corners, the newcorner is an extension (angle 0), for inside corners, it turns backward
// If either side turns back it is an inside corner---must check both. // If either side turns back it is an inside corner---must check both.
// Outside corners can get rounded (if r is specified and there is space to round them) // Outside corners can get rounded (if r is specified and there is space to round them)
@ -1009,6 +1043,9 @@ function _list_three(a,b,c) =
// Function&Module: union() // Function&Module: union()
// Synopsis: Performs a Boolean union operation.
// Topics: Boolean Operations, Regions, Polygons, Shapes2D, Shapes3D
// See Also: difference(), intersection(), diff(), intersect(), exclusive_or()
// Usage: // Usage:
// union() CHILDREN; // union() CHILDREN;
// region = union(regions); // region = union(regions);
@ -1039,6 +1076,9 @@ function union(regions=[],b=undef,c=undef,eps=EPSILON) =
// Function&Module: difference() // Function&Module: difference()
// Synopsis: Performs a Boolean difference operation.
// Topics: Boolean Operations, Regions, Polygons, Shapes2D, Shapes3D
// See Also: union(), intersection(), diff(), intersect(), exclusive_or()
// Usage: // Usage:
// difference() CHILDREN; // difference() CHILDREN;
// region = difference(regions); // region = difference(regions);
@ -1071,6 +1111,9 @@ function difference(regions=[],b=undef,c=undef,eps=EPSILON) =
// Function&Module: intersection() // Function&Module: intersection()
// Synopsis: Performs a Boolean intersection operation.
// Topics: Boolean Operations, Regions, Polygons, Shapes2D, Shapes3D
// See Also: difference(), union(), diff(), intersect(), exclusive_or()
// Usage: // Usage:
// intersection() CHILDREN; // intersection() CHILDREN;
// region = intersection(regions); // region = intersection(regions);
@ -1102,6 +1145,9 @@ function intersection(regions=[],b=undef,c=undef,eps=EPSILON) =
// Function&Module: exclusive_or() // Function&Module: exclusive_or()
// Synopsis: Performs a Boolean exclusive-or operation.
// Topics: Boolean Operations, Regions, Polygons, Shapes2D, Shapes3D
// See Also: union(), difference(), intersection(), diff(), intersect()
// Usage: // Usage:
// exclusive_or() CHILDREN; // exclusive_or() CHILDREN;
// region = exclusive_or(regions); // region = exclusive_or(regions);
@ -1110,7 +1156,7 @@ function intersection(regions=[],b=undef,c=undef,eps=EPSILON) =
// Description: // Description:
// When called as a function and given a list of regions or 2D polygons, // When called as a function and given a list of regions or 2D polygons,
// returns the exclusive_or of all given regions. Result is a single region. // returns the exclusive_or of all given regions. Result is a single region.
// When called as a module, performs a boolean exclusive-or of up to 10 children. Note that when // When called as a module, performs a Boolean exclusive-or of up to 10 children. Note that when
// the input regions cross each other the exclusive-or operator will produce shapes that // the input regions cross each other the exclusive-or operator will produce shapes that
// meet at corners (non-simple regions), which do not render in CGAL. // meet at corners (non-simple regions), which do not render in CGAL.
// Arguments: // Arguments: