Merge pull request #1429 from adrianVmariano/master

sparse cuboid + doc fixes

.openscad_docsgen_rc

@@ -69,7 +69,7 @@ PrioritizeFiles:
   walls.scad
   wiring.scad
 DefineHeader(BulletList): Side Effects
-DefineHeader(Table;Headers=Anchor Name|Position): Extra Anchors
+DefineHeader(Table;Headers=Anchor Name|Position): Named Anchors
 DefineHeader(Table;Headers=Anchor Type|What it is): Anchor Types
 DefineHeader(Table;Headers=Name|Definition): Terminology
 DefineHeader(BulletList): Requirements

attachments.scad

@@ -2957,7 +2957,7 @@ function reorient(
     axis=UP, override, 
     geom,
     p=undef
-) =
+) = 
     assert(is_undef(anchor) || is_vector(anchor) || is_string(anchor), str("Got: ",anchor))
     assert(is_undef(spin)   || is_vector(spin,3) || is_num(spin), str("Got: ",spin))
     assert(is_undef(orient) || is_vector(orient,3), str("Got: ",orient))
@@ -3571,7 +3571,7 @@ function _force_anchor_2d(anchor) =
 ///   geom = The geometry description of the shape.
 function _find_anchor(anchor, geom) =
     is_string(anchor)? (
-          anchor=="origin"? [anchor, CENTER, UP, 0]
+          anchor=="origin"? [anchor, CENTER, UP, 0]    // Ok that this returns 3d anchor in the 2d case?
         : let(
               anchors = last(geom),
               found = search([anchor], anchors, num_returns_per_match=1)[0]

bottlecaps.scad

@@ -31,7 +31,7 @@ include <rounding.scad>
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: `CENTER`
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
-// Extra Anchors:
+// Named Anchors:
 //   "tamper-ring" = Centered at the top of the anti-tamper ring channel.
 //   "support-ring" = Centered at the bottom of the support ring.
 // Example:
@@ -160,7 +160,7 @@ function  pco1810_neck(wall=2, anchor="support-ring", spin=0, orient=UP) =
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: `CENTER`
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
-// Extra Anchors:
+// Named Anchors:
 //   "inside-top" = Centered on the inside top of the cap.
 // Examples:
 //   pco1810_cap();
@@ -236,7 +236,7 @@ function pco1810_cap(h, r, d, wall, texture="none", anchor=BOTTOM, spin=0, orien
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: `CENTER`
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
-// Extra Anchors:
+// Named Anchors:
 //   "tamper-ring" = Centered at the top of the anti-tamper ring channel.
 //   "support-ring" = Centered at the bottom of the support ring.
 // Example:
@@ -362,7 +362,7 @@ function pco1881_neck(wall=2, anchor="support-ring", spin=0, orient=UP) =
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: `CENTER`
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
-// Extra Anchors:
+// Named Anchors:
 //   "inside-top" = Centered on the inside top of the cap.
 // Examples:
 //   pco1881_cap();
@@ -431,7 +431,7 @@ function pco1881_cap(wall=2, texture="none", anchor=BOTTOM, spin=0, orient=UP) =
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: `CENTER`
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
-// Extra Anchors:
+// Named Anchors:
 //   "support-ring" = Centered at the bottom of the support ring.
 // Example:
 //   generic_bottle_neck();
@@ -564,7 +564,7 @@ function generic_bottle_neck(
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: `CENTER`
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
-// Extra Anchors:
+// Named Anchors:
 //   "inside-top" = Centered on the inside top of the cap.
 // Examples:
 //   generic_bottle_cap(thread_depth=2,neck_od=INCH,height=INCH/2);

gears.scad

@@ -1643,7 +1643,7 @@ module ring_gear2d(
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: `CENTER`
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
-// Extra Anchors:
+// Named Anchors:
 //   "root" = At the base of the teeth, at the center of rack.
 //   "root-left" = At the base of the teeth, at the left end of the rack.
 //   "root-right" = At the base of the teeth, at the right end of the rack.
@@ -1912,7 +1912,7 @@ function rack(
 //   rounding = If true, rack tips and valleys are slightly rounded.  Default: true
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: `CENTER`
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
-// Extra Anchors:
+// Named Anchors:
 //   "root" = At the height of the teeth, at the center of rack.
 //   "root-left" = At the height of the teeth, at the left end of the rack.
 //   "root-right" = At the height of the teeth, at the right end of the rack.
@@ -2363,7 +2363,7 @@ module crown_gear(
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: "pitchbase"
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
-// Extra Anchors:
+// Named Anchors:
 //   "pitchbase" = With the base of the pitch cone in the XY plane, centered at the origin.  This is the natural height for the gear, and the default anchor.
 //   "apex" = At the pitch cone apex for the bevel gear.
 //   "flattop" = At the top of the flat top of the bevel gear.

masks3d.scad

@@ -249,20 +249,6 @@ module chamfer_cylinder_mask(r, chamfer, d, ang=45, from_end=false, anchor=CENTE
 //               rounding_edge_mask(l=p.z, r=25);
 //       }
 //   }
-// Example: Acute angle 
-//   ang=60;
-//   difference() {
-//       pie_slice(ang=ang, h=50, r=100);
-//       zflip_copy(z=25)
-//          #rounding_corner_mask(r=20, ang=ang);
-//   }
-// Example: Obtuse angle 
-//   ang=120;
-//   difference() {
-//       pie_slice(ang=ang, h=50, r=30);
-//       zflip_copy(z=25)
-//          #rounding_corner_mask(r=20, ang=ang);
-//   }
 
 function rounding_edge_mask(l, r, ang=90, r1, r2, d, d1, d2, excess=0.1, anchor=CENTER, spin=0, orient=UP, h,height,length) = no_function("rounding_edge_mask");
 module rounding_edge_mask(l, r, ang=90, r1, r2, excess=0.01, d1, d2,d,r,length, h, height, anchor=CENTER, spin=0, orient=UP,
@@ -274,7 +260,7 @@ module rounding_edge_mask(l, r, ang=90, r1, r2, excess=0.01, d1, d2,d,r,length,
     dummy = assert(all_nonnegative([r1,r2]), "radius/diameter value(s) must be nonnegative")
             assert(all_positive([length]), "length/l/h/height must be a positive value")
             assert(is_finite(ang) && ang>0 && ang<180, "ang must be a number between 0 and 180");
-    steps = ceil(segs(r)*(180-ang)/360);
+    steps = ceil(segs(max(r1,r2))*(180-ang)/360);
     function make_path(r) =
         let(
              arc = r==0 ? repeat([0,0],steps+1)
@@ -383,8 +369,21 @@ module rounding_edge_mask(l, r, ang=90, r1, r2, excess=0.01, d1, d2,d,r,length,
 //       corner_mask(TOP)
 //           #rounding_corner_mask(r=20);
 //   }
-// Example: Acute angle mask
-// 
+// Example(VPR=[71.8,0,345.8],VPT=[57.0174,43.8496,24.5863],VPD=263.435,NoScales): Acute angle 
+//   ang=60;
+//   difference() {
+//       pie_slice(ang=ang, h=50, r=100);
+//       zflip_copy(z=25)
+//          #rounding_corner_mask(r=20, ang=ang);
+//   }
+// Example(VPR=[62.7,0,5.4],VPT=[6.9671,22.7592,20.7513],VPD=192.044): Obtuse angle 
+//   ang=120;
+//   difference() {
+//       pie_slice(ang=ang, h=50, r=30);
+//       zflip_copy(z=25)
+//          #rounding_corner_mask(r=20, ang=ang);
+//   }
+
 function rounding_corner_mask(r, ang, d, style="octa", excess=0.1, anchor=CENTER, spin=0, orient=UP) = no_function("rounding_corner_mask");
 module rounding_corner_mask(r, ang=90, d, style="octa", excess=0.1, anchor=CENTER, spin=0, orient=UP)
 {

math.scad

@@ -1374,7 +1374,7 @@ function quadratic_roots(a,b,c,real=false) =
 
 
 // Function: polynomial() 
-// Synopsis: Calculates a polynomial equation at a given value.
+// Synopsis: Evaluate a polynomial at a real or complex value.
 // Topics: Math, Complex Numbers
 // See Also: quadratic_roots(), polynomial(), poly_mult(), poly_div(), poly_add(), poly_roots()
 // Usage:
@@ -1394,7 +1394,7 @@ function polynomial(p,z,k,total) =
 
 
 // Function: poly_mult()
-// Synopsis: Returns the polynomial result of multiplying two polynomial equations.
+// Synopsis: Compute product of two polynomials, returning a polynomial.
 // Topics: Math
 // See Also: quadratic_roots(), polynomial(), poly_mult(), poly_div(), poly_add(), poly_roots()
 // Usage:
@@ -1416,7 +1416,7 @@ function poly_mult(p,q) =
 
 
 // Function: poly_div()
-// Synopsis: Returns the polynomial quotient and remainder results of dividing two polynomial equations.
+// Synopsis: Returns the polynomial quotient and remainder results of dividing two polynomials.
 // Topics: Math
 // See Also: quadratic_roots(), polynomial(), poly_mult(), poly_div(), poly_add(), poly_roots()
 // Usage:
@@ -1457,7 +1457,7 @@ function _poly_trim(p,eps=0) =
 
 
 // Function: poly_add()
-// Synopsis: Returns the polynomial sum of adding two polynomial equations.
+// Synopsis: Returns the polynomial sum of adding two polynomials.
 // Topics: Math
 // See Also: quadratic_roots(), polynomial(), poly_mult(), poly_div(), poly_add(), poly_roots()
 // Usage:
@@ -1475,7 +1475,7 @@ function poly_add(p,q) =
 
 
 // Function: poly_roots()
-// Synopsis: Returns all complex number roots of the given real polynomial.
+// Synopsis: Returns all complex valued roots of the given real polynomial.
 // Topics: Math, Complex Numbers
 // See Also: quadratic_roots(), polynomial(), poly_mult(), poly_div(), poly_add(), poly_roots()
 // Usage:
@@ -1563,7 +1563,8 @@ function _poly_roots(p, pderiv, s, z, tol, i=0) =
 //   parts are zero.  You can specify eps, in which case the test is
 //   z.y/(1+norm(z)) < eps.  Because
 //   of poor convergence and higher error for repeated roots, such roots may
-//   be missed by the algorithm because their imaginary part is large.
+//   be missed by the algorithm because error can make their imaginary parts
+//   large enough to appear non-zero.  
 // Arguments:
 //   p = polynomial to solve as coefficient list, highest power term first
 //   eps = used to determine whether imaginary parts of roots are zero

metric_screws.scad

@@ -373,7 +373,7 @@ function get_metric_nut_thickness(size) = lookup(size, [
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: `CENTER`
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
-// Extra Anchors:
+// Named Anchors:
 //   "base" = At the base of the head.
 //   "countersunk" = At the head height that would be just barely exposed when countersunk.
 // Examples:
@@ -434,7 +434,7 @@ module generic_screw(
 //   anchor = Translate so anchor point is at origin (0,0,0).  See [anchor](attachments.scad#subsection-anchor).  Default: `CENTER`
 //   spin = Rotate this many degrees around the Z axis after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   orient = Vector to rotate top towards, after spin.  See [orient](attachments.scad#subsection-orient).  Default: `UP`
-// Extra Anchors:
+// Named Anchors:
 //   "base" = At the base of the head.
 //   "countersunk" = At the head height that would be just barely exposed when countersunk.
 //   "shank" = At the bottom start of the unthreaded shank.

regions.scad

@@ -314,6 +314,8 @@ function force_region(poly) = is_path(poly) ? [poly] : poly;
 //   spin = Rotate this many degrees after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   cp = Centerpoint for determining intersection anchors or centering the shape.  Determintes the base of the anchor vector.  Can be "centroid", "mean", "box" or a 2D point.  Default: "centroid"
 //   atype = Set to "hull" or "intersect" to select anchor type.  Default: "hull"
+// Named Anchors:
+//   "origin" = The native position of the region.
 // Anchor Types:
 //   "hull" = Anchors to the virtual convex hull of the region.
 //   "intersect" = Anchors to the outer edge of the region.
@@ -1192,6 +1194,8 @@ function _list_three(a,b,c) =
 //   When called as a function and given a list of regions or 2D polygons,
 //   returns the union of all given regions and polygons.  Result is a single region.
 //   When called as the built-in module, makes the union of the given children.
+//   This function is **much** slower than the native union module acting on geometry,
+//   so you should only use it when you need a point list for further processing.  
 // Arguments:
 //   regions = List of regions to union.
 // Example(2D):
@@ -1227,6 +1231,8 @@ function union(regions=[],b=undef,c=undef,eps=EPSILON) =
 //   takes the first region or polygon and differences away all other regions/polygons from it.  The resulting
 //   region is returned.
 //   When called as the built-in module, makes the set difference of the given children.
+//   This function is **much** slower than the native difference module acting on geometry,
+//   so you should only use it when you need a point list for further processing.  
 // Arguments:
 //   regions = List of regions or polygons to difference.
 // Example(2D):
@@ -1299,6 +1305,8 @@ function intersection(regions=[],b=undef,c=undef,eps=EPSILON) =
 //   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.  
+//   This function is **much** slower than the native intersection module acting on geometry,
+//   so you should only use it when you need a point list for further processing.  
 // Arguments:
 //   regions = List of regions or polygons to exclusive_or
 // Example(2D): As Function.  A linear_sweep of this shape fails to render in CGAL.  

rounding.scad

@@ -951,6 +951,11 @@ function _path_join(paths,joint,k=0.5,i=0,result=[],relocate=true,closed=false)
 //   spin = Rotate this many degrees after anchor.  See [spin](attachments.scad#subsection-spin).  Default: `0`
 //   cp = Centerpoint for determining intersection anchors or centering the shape.  Determintes the base of the anchor vector.  Can be "centroid", "mean", "box" or a 2D point.  Default: "centroid"
 //   atype = Set to "hull" or "intersect" to select anchor type.  Default: "hull"
+// Named Anchors:
+//   "origin" = The native position of the region.
+// Anchor Types:
+//   "hull" = Anchors to the virtual convex hull of the region.
+//   "intersect" = Anchors to the outer edge of the region.
 // Example(2D):  Basic examples illustrating flat, round, and pointed ends, on a finely sampled arc and a path made from 3 segments.
 //   arc = arc(points=[[1,1],[3,4],[6,3]],n=50);
 //   path = [[0,0],[6,2],[9,7],[8,10]];
@@ -1047,7 +1052,7 @@ function _path_join(paths,joint,k=0.5,i=0,result=[],relocate=true,closed=false)
 //   right(12)
 //     offset_stroke(path, width=1, closed=true);
 function offset_stroke(path, width=1, rounded=true, start, end, check_valid=true, quality=1, chamfer=false, closed=false,
-                       atype="hull", anchor, spin, cp="centroid") =
+                       atype="hull", anchor="origin", spin, cp="centroid") =
         let(path = force_path(path))
         assert(is_path(path,2),"path is not a 2d path")
         let(
@@ -1091,7 +1096,7 @@ function offset_stroke(path, width=1, rounded=true, start, end, check_valid=true
                           reverse(slice(right_path,startpath[2],-1-endpath[1])),
                           startpath[0]
                   )
-         )
+         ) 
          reorient(anchor=anchor, spin=spin, two_d=true, path=pts, extent=atype=="hull", cp=cp, p=pts);
 
 function os_pointed(dist,loc=0) =
@@ -1374,7 +1379,7 @@ module offset_stroke(path, width=1, rounded=true, start, end, check_valid=true,
 //   intersect = Anchors to the surface of the linear sweep of the path, ignoring any end roundings.
 //   surf_hull = Anchors to the convex hull of the offset_sweep shape, including end treatments.
 //   surf_intersect = Anchors to the surface of the offset_sweep shape, including any end treatments.
-// Extra Anchors:
+// Named Anchors:
 //   "base" = Anchor to the base of the shape in its native position, ignoring any "extra"
 //   "top" = Anchor to the top of the shape in its native position, ignoring any "extra"
 //   "zcenter" = Center shape in the Z direction in the native XY position, ignoring any "extra"
@@ -2082,6 +2087,11 @@ function _rp_compute_patches(top, bot, rtop, rsides, ktop, ksides, concave) =
 //   orient = Vector to rotate top towards after spin  (module only)
 //   atype = Select "hull" or "intersect" anchor types.  (module only) Default: "hull"
 //   cp = Centerpoint for determining "intersect" anchors or centering the shape.  Determintes the base of the anchor vector.  Can be "centroid", "mean", "box" or a 3D point.  (module only) Default: "centroid"
+// Named Anchors:
+//   "origin" = The native position of the prism.
+// Anchor Types:
+//   "hull" = Anchors to the virtual convex hull of the prism. 
+//   "intersect" = Anchors to the surface of the prism.
 // Example: Uniformly rounded pentagonal prism
 //   rounded_prism(pentagon(3), height=3,
 //                 joint_top=0.5, joint_bot=0.5, joint_sides=0.5);
@@ -2792,7 +2802,7 @@ Access to the derivative smoothing parameter?
 //   orient = Vector to rotate top towards after spin  (module only)
 //   atype = Select "hull" or "intersect" anchor types.  (module only) Default: "hull"
 //   cp = Centerpoint for determining "intersect" anchors or centering the shape.  Determintes the base of the anchor vector.  Can be "centroid", "mean", "box" or a 3D point.  (module only) Default: "centroid"
-// Extra Anchors:
+// Named Anchors:
 //   "root" = Root point of the joiner prism, pointing out in the direction of the prism axis
 //   "end" = End point of the joiner prism, pointing out in the direction of the prism axis
 // Example(3D,NoScales): Here is the simplest case, a circular prism with a specified length standing vertically on a plane.