From ff0b221ed6067a9dd8a016c3be19d024fbff76ee Mon Sep 17 00:00:00 2001 From: Richard Milewski Date: Tue, 4 Apr 2023 23:36:14 -0700 Subject: [PATCH] Synopses: regions.scad --- regions.scad | 48 ++++++++++++++++++++++++++++++++++++++---------- 1 file changed, 38 insertions(+), 10 deletions(-) diff --git a/regions.scad b/regions.scad index 3eb87f0..dbb30b6 100644 --- a/regions.scad +++ b/regions.scad @@ -1,6 +1,6 @@ ////////////////////////////////////////////////////////////////////// // 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 // 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. @@ -9,7 +9,7 @@ // Includes: // include // 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 ////////////////////////////////////////////////////////////////////// @@ -44,7 +44,7 @@ // Function: is_region() // Synopsis: Returns true if the input appears to be a region. -// Topics: Regions, Paths, Polygons, Lists +// Topics: Regions, Paths, Polygons, List Handling // See Also: is_valid_region(), is_1region(), is_region_simple() // Usage: // bool = is_region(x); @@ -56,7 +56,7 @@ function is_region(x) = is_list(x) && is_path(x.x); // Function: is_valid_region() // Synopsis: Returns true if the input is a valid region. -// Topics: Regions, Paths, Polygons, Lists +// Topics: Regions, Paths, Polygons, List Handling // See Also: is_region(), is_1region(), is_region_simple() // Usage: // bool = is_valid_region(region, [eps]); @@ -215,7 +215,7 @@ function _polygon_crosses_region(region, poly, eps=EPSILON) = // Function: is_region_simple() // Synopsis: Returns true if the input is a region with no corner contact. -// Topics: Regions, Paths, Polygons, Lists +// Topics: Regions, Paths, Polygons, List Handling // See Also: is_region(), is_valid_region(), is_1region() // Usage: // bool = is_region_simple(region, [eps]); @@ -248,7 +248,7 @@ function is_region_simple(region, eps=EPSILON) = // Function: make_region() // Synopsis: Converts lists of intersecting polygons into valid regions. -// Topics: Regions, Paths, Polygons, Lists +// Topics: Regions, Paths, Polygons, List Handling // See Also: force_region(), region() // // Usage: @@ -281,7 +281,7 @@ function make_region(polys,nonzero=false,eps=EPSILON) = // Function: force_region() // Synopsis: Given a polygon returns a region. -// Topics: Regions, Paths, Polygons, Lists +// Topics: Regions, Paths, Polygons, List Handling // See Also: make_region(), region() // Usage: // region = force_region(poly) @@ -296,7 +296,7 @@ function force_region(poly) = is_path(poly) ? [poly] : poly; // Module: region() // Synopsis: Creates the 2D polygons described by the given region or list of polygons. -// Topics: Regions, Paths, Polygons, Lists +// Topics: Regions, Paths, Polygons, List Handling // See Also: make_region(), region() // Usage: // region(r, [anchor], [spin=], [cp=], [atype=]) [ATTACHMENTS]; @@ -339,6 +339,9 @@ module region(r, anchor="origin", spin=0, cp="centroid", atype="hull") // Section: Gometrical calculations with regions // 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: // check = point_in_region(point, region, [eps]); // Description: @@ -374,6 +377,8 @@ function _point_in_region(point, region, eps=EPSILON, i=0, cnt=0) = // Function: region_area() +// Synopsis: Computes the area of the specified valid region. +// Topics: Regions, Area // Usage: // area = region_area(region); // Description: @@ -395,6 +400,8 @@ function region_area(region) = function _clockwise_region(r) = [for(p=r) clockwise_polygon(p)]; // Function: are_regions_equal() +// Synopsis: Returns true if given regions are the same polygons. +// Topics: Regions, Polygons, Comparison // Usage: // b = are_regions_equal(region1, region2, [either_winding]) // Description: @@ -501,6 +508,10 @@ function _region_region_intersections(region1, region2, closed1=true,closed2=tru // 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: // split_region = split_region_at_region_crossings(region1, region2, [closed1], [closed2], [eps]) // Description: @@ -564,6 +575,9 @@ function split_region_at_region_crossings(region1, region2, closed1=true, closed // Function: region_parts() +// Synopsis: Splits a region into a list of regions. +// Topics: Regions, List Handling +// See Also: split_region_at_region_crossings() // Usage: // rgns = region_parts(region); // Description: @@ -724,6 +738,8 @@ function _point_dist(path,pathseg_unit,pathseg_len,pt) = // Function: offset() +// Synopsis: Takes a 2D path, polygon or region and returns a path offset by an amount. +// Topics: Paths, Polygons, Regions // Usage: // 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=]) @@ -897,7 +913,7 @@ function offset( ) assert(parallelcheck, "Path contains a segment that reverses direction (180 deg turn)") 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 // 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) @@ -1027,6 +1043,9 @@ function _list_three(a,b,c) = // 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: // union() CHILDREN; // region = union(regions); @@ -1057,6 +1076,9 @@ function union(regions=[],b=undef,c=undef,eps=EPSILON) = // 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: // difference() CHILDREN; // region = difference(regions); @@ -1089,6 +1111,9 @@ function difference(regions=[],b=undef,c=undef,eps=EPSILON) = // 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: // intersection() CHILDREN; // region = intersection(regions); @@ -1120,6 +1145,9 @@ function intersection(regions=[],b=undef,c=undef,eps=EPSILON) = // 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: // exclusive_or() CHILDREN; // region = exclusive_or(regions); @@ -1128,7 +1156,7 @@ function intersection(regions=[],b=undef,c=undef,eps=EPSILON) = // Description: // 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. -// 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 // meet at corners (non-simple regions), which do not render in CGAL. // Arguments: