Merge branch 'master' into master

attachments.scad

@@ -2103,10 +2103,7 @@ function reorient(
         orient = default(orient, UP),
         region = !is_undef(region)? region :
             !is_undef(path)? [path] :
-            undef
-    )
-//    (anchor==CENTER && spin==0 && orient==UP && p!=undef)? p :
-    let(
+            undef,
         geom = is_def(geom)? geom :
             attach_geom(
                 size=size, size2=size2, shift=shift,
@@ -2617,12 +2614,25 @@ function _find_anchor(anchor, geom) =
             bot = point3d(v_mul(point2d(size )/2, axy), -h/2),
             top = point3d(v_mul(point2d(size2)/2, axy) + shift, h/2),
             pos = point3d(cp) + lerp(bot,top,u) + offset,
-            vecs = [
-                if (anch.x!=0) unit(rot(from=UP, to=[(top-bot).x,0,h], p=[axy.x,0,0]), UP),
-                if (anch.y!=0) unit(rot(from=UP, to=[0,(top-bot).y,h], p=[0,axy.y,0]), UP),
-                if (anch.z!=0) anch==CENTER? UP : unit([0,0,anch.z],UP)
-            ],
-            vec = anchor==CENTER? UP : rot(from=UP, to=axis, p=unit(sum(vecs) / len(vecs))),
+            vecs = anchor==CENTER? [UP]
+              : [
+                    if (anch.x!=0) unit(rot(from=UP, to=[(top-bot).x,0,h], p=[axy.x,0,0]), UP),
+                    if (anch.y!=0) unit(rot(from=UP, to=[0,(top-bot).y,h], p=[0,axy.y,0]), UP),
+                    if (anch.z!=0) unit([0,0,anch.z],UP)
+                ],
+            vec2 = anchor==CENTER? UP
+              : len(vecs)==1? unit(vecs[0],UP)
+              : len(vecs)==2? vector_bisect(vecs[0],vecs[1])
+              : let(
+                    v1 = vector_bisect(vecs[0],vecs[2]),
+                    v2 = vector_bisect(vecs[1],vecs[2]),
+                    p1 = plane_from_normal(yrot(90,p=v1)),
+                    p2 = plane_from_normal(xrot(-90,p=v2)),
+                    line = plane_intersection(p1,p2),
+                    v3 = unit(line[1]-line[0],UP) * anch.z
+                )
+                unit(v3,UP),
+            vec = rot(from=UP, to=axis, p=vec2),
             pos2 = rot(from=UP, to=axis, p=pos)
         ) [anchor, pos2, vec, oang]
     ) : type == "conoid"? ( //r1, r2, l, shift

examples/BOSL2logo.scad

@@ -11,11 +11,11 @@ xdistribute(50) {
 	recolor("#f77")
 	diff("hole")
 	cuboid([45,45,10], chamfer=10, edges=[RIGHT+BACK,RIGHT+FRONT], anchor=FRONT) {
-		cuboid([30,30,11], chamfer=5, edges=[RIGHT+BACK,RIGHT+FRONT], $tags="hole");
+		tag("hole")cuboid([30,30,11], chamfer=5, edges=[RIGHT+BACK,RIGHT+FRONT]);
 		attach(FRONT,BACK, overlap=5) {
-			diff("hole")
+			diff("hole2")
 			cuboid([45,45,10], rounding=15, edges=[RIGHT+BACK,RIGHT+FRONT]) {
-				cuboid([30,30,11], rounding=10, edges=[RIGHT+BACK,RIGHT+FRONT], $tags="hole");
+				tag("hole2")cuboid([30,30,11], rounding=10, edges=[RIGHT+BACK,RIGHT+FRONT]);
 			}
 		}
 	}
@@ -50,4 +50,3 @@ xdistribute(50) {
 				nut("M12", thickness=10, diameter=20);
 	}
 }
-

linalg.scad

@@ -33,6 +33,7 @@
 // Function: is_matrix()
 // Usage:
 //   test = is_matrix(A, [m], [n], [square])
+// Topics: Matrices
 // Description:
 //   Returns true if A is a numeric matrix of height m and width n with finite entries.  If m or n
 //   are omitted or set to undef then true is returned for any positive dimension.
@@ -52,6 +53,7 @@ function is_matrix(A,m,n,square=false) =
 // Function: is_matrix_symmetric()
 // Usage:
 //   b = is_matrix_symmetric(A, [eps])
+// Topics: Matrices
 // Description:
 //   Returns true if the input matrix is symmetric, meaning it approximately equals its transpose.  
 //   The matrix can have arbitrary entries.  
@@ -65,6 +67,7 @@ function is_matrix_symmetric(A,eps=1e-12) =
 // Function: is_rotation()
 // Usage:
 //   b = is_rotation(A, [dim], [centered])
+// Topics: Affine, Matrices, Transforms
 // Description:
 //   Returns true if the input matrix is a square affine matrix that is a rotation around any point,
 //   or around the origin if `centered` is true. 
@@ -93,6 +96,7 @@ function is_rotation(A,dim,centered=false) =
 // Usage:
 //    echo_matrix(M, [description], [sig], [sep], [eps]);
 //    dummy = echo_matrix(M, [description], [sig], [sep], [eps]),
+// Topics: Matrices
 // Description:
 //    Display a numerical matrix in a readable columnar format with `sig` significant
 //    digits.  Values smaller than eps display as zero.  If you give a description
@@ -129,7 +133,7 @@ module echo_matrix(M,description,sig=4,sep=1,eps=1e-9)
 // Function: column()
 // Usage:
 //   list = column(M, i);
-// Topics: Matrices, List Handling
+// Topics: Matrices, List Handling, Arrays
 // See Also: select(), slice()
 // Description:
 //   Extracts entry `i` from each list in M, or equivalently column i from the matrix M, and returns it as a vector.  
@@ -155,7 +159,7 @@ function column(M, i) =
 // Function: submatrix()
 // Usage:
 //   mat = submatrix(M, idx1, idx2);
-// Topics: Matrices
+// Topics: Matrices, Arrays
 // See Also: column(), block_matrix(), submatrix_set()
 // Description:
 //   The input must be a list of lists (a matrix or 2d array).  Returns a submatrix by selecting the rows listed in idx1 and columns listed in idx2.
@@ -188,7 +192,7 @@ function submatrix(M,idx1,idx2) =
 // Function: ident()
 // Usage:
 //   mat = ident(n);
-// Topics: Affine, Matrices
+// Topics: Affine, Matrices, Transforms
 // Description:
 //   Create an `n` by `n` square identity matrix.
 // Arguments:
@@ -220,7 +224,7 @@ function ident(n) = [
 // Function: diagonal_matrix()
 // Usage:
 //   mat = diagonal_matrix(diag, [offdiag]);
-// Topics: Matrices
+// Topics: Affine, Matrices
 // See Also: column(), submatrix()
 // Description:
 //   Creates a square matrix with the items in the list `diag` on
@@ -237,7 +241,7 @@ function diagonal_matrix(diag, offdiag=0) =
 // Function: transpose()
 // Usage:
 //    M = transpose(M, [reverse]);
-// Topics: Matrices
+// Topics: Linear Algebra, Matrices
 // See Also: submatrix(), block_matrix(), hstack(), flatten()
 // Description:
 //    Returns the transpose of the given input matrix.  The input can be a matrix with arbitrary entries or
@@ -315,6 +319,7 @@ function transpose(M, reverse=false) =
 // Function: outer_product()
 // Usage:
 //   x = outer_product(u,v);
+// Topics: Linear Algebra, Matrices
 // Description:
 //   Compute the outer product of two vectors, a matrix.  
 // Usage:
@@ -326,7 +331,7 @@ function outer_product(u,v) =
 // Function: submatrix_set()
 // Usage:
 //   mat = submatrix_set(M, A, [m], [n]);
-// Topics: Matrices
+// Topics: Matrices, Arrays
 // See Also: column(), submatrix()
 // Description:
 //   Sets a submatrix of M equal to the matrix A.  By default the top left corner of M is set to A, but
@@ -356,7 +361,7 @@ function submatrix_set(M,A,m=0,n=0) =
 //   A = hstack(M1, M2)
 //   A = hstack(M1, M2, M3)
 //   A = hstack([M1, M2, M3, ...])
-// Topics: Matrices
+// Topics: Matrices, Arrays
 // See Also: column(), submatrix(), block_matrix()
 // Description:
 //   Constructs a matrix by horizontally "stacking" together compatible matrices or vectors.  Vectors are treated as columsn in the stack.
@@ -408,7 +413,7 @@ function hstack(M1, M2, M3) =
 // Function: block_matrix()
 // Usage:
 //    bmat = block_matrix([[M11, M12,...],[M21, M22,...], ... ]);
-// Topics: Matrices
+// Topics: Matrices, Arrays
 // See Also: column(), submatrix()
 // Description:
 //    Create a block matrix by supplying a matrix of matrices, which will
@@ -455,6 +460,7 @@ function block_matrix(M) =
 // Function: linear_solve()
 // Usage:
 //   solv = linear_solve(A,b,[pivot])
+// Topics: Matrices, Linear Algebra
 // Description:
 //   Solves the linear system Ax=b.  If `A` is square and non-singular the unique solution is returned.  If `A` is overdetermined
 //   the least squares solution is returned. If `A` is underdetermined, the minimal norm solution is returned.
@@ -463,7 +469,7 @@ function block_matrix(M) =
 //   want to solve Ax=b1 and Ax=b2 that you need to form the matrix `transpose([b1,b2])` for the right hand side and then
 //   transpose the returned value.  The solution is computed using QR factorization.  If `pivot` is set to true (the default) then
 //   pivoting is used in the QR factorization, which is slower but expected to be more accurate.
-// Usage:
+// Arguments:
 //   A = Matrix describing the linear system, which need not be square
 //   b = right hand side for linear system, which can be a matrix to solve several cases simultaneously.  Must be consistent with A.
 //   pivot = if true use pivoting when computing the QR factorization.  Default: true
@@ -491,6 +497,7 @@ function linear_solve(A,b,pivot=true) =
 // Function: linear_solve3()
 // Usage:
 //   x = linear_solve3(A,b)
+// Topics: Matrices, Linear Algebra
 // Description:
 //   Fast solution to a 3x3 linear system using Cramer's rule (which appears to be the fastest
 //   method in OpenSCAD).  The input `A` must be a 3x3 matrix.  Returns undef if `A` is singular.
@@ -515,6 +522,7 @@ function linear_solve3(A,b) =
 // Function: matrix_inverse()
 // Usage:
 //    mat = matrix_inverse(A)
+// Topics: Matrices, Linear Algebra
 // Description:
 //    Compute the matrix inverse of the square matrix `A`.  If `A` is singular, returns `undef`.
 //    Note that if you just want to solve a linear system of equations you should NOT use this function.
@@ -528,6 +536,7 @@ function matrix_inverse(A) =
 // Function: rot_inverse()
 // Usage:
 //   B = rot_inverse(A)
+// Topics: Matrices, Linear Algebra, Affine
 // Description:
 //   Inverts a 2d (3x3) or 3d (4x4) rotation matrix.  The matrix can be a rotation around any center,
 //   so it may include a translation.  This is faster and likely to be more accurate than using `matrix_inverse()`.  
@@ -548,6 +557,7 @@ function rot_inverse(T) =
 // Function: null_space()
 // Usage:
 //   x = null_space(A)
+// Topics: Matrices, Linear Algebra
 // Description:
 //   Returns an orthonormal basis for the null space of `A`, namely the vectors {x} such that Ax=0.
 //   If the null space is just the origin then returns an empty list. 
@@ -564,6 +574,7 @@ function null_space(A,eps=1e-12) =
 // Function: qr_factor()
 // Usage:
 //   qr = qr_factor(A,[pivot]);
+// Topics: Matrices, Linear Algebra
 // Description:
 //   Calculates the QR factorization of the input matrix A and returns it as the list [Q,R,P].  This factorization can be
 //   used to solve linear systems of equations.  The factorization is `A = Q*R*transpose(P)`.  If pivot is false (the default)
@@ -614,6 +625,7 @@ function _swap_matrix(n,i,j) =
 // Function: back_substitute()
 // Usage:
 //   x = back_substitute(R, b, [transpose]);
+// Topics: Matrices, Linear Algebra
 // Description:
 //   Solves the problem Rx=b where R is an upper triangular square matrix.  The lower triangular entries of R are
 //   ignored.  If transpose==true then instead solve transpose(R)*x=b.
@@ -645,6 +657,7 @@ function _back_substitute(R, b, x=[]) =
 // Function: cholesky()
 // Usage:
 //   L = cholesky(A);
+// Topics: Matrices, Linear Algebra
 // Description:
 //   Compute the cholesky factor, L, of the symmetric positive definite matrix A.
 //   The matrix L is lower triangular and `L * transpose(L) = A`.  If the A is
@@ -680,6 +693,7 @@ function _cholesky(A,L,n) =
 // Function: det2()
 // Usage:
 //   d = det2(M);
+// Topics: Matrices, Linear Algebra
 // Description:
 //   Rturns the determinant for the given 2x2 matrix.
 // Arguments:
@@ -695,6 +709,7 @@ function det2(M) =
 // Function: det3()
 // Usage:
 //   d = det3(M);
+// Topics: Matrices, Linear Algebra
 // Description:
 //   Returns the determinant for the given 3x3 matrix.
 // Arguments:
@@ -711,6 +726,7 @@ function det3(M) =
 // Function: det4()
 // Usage:
 //   d = det4(M);
+// Topics: Matrices, Linear Algebra
 // Description:
 //   Returns the determinant for the given 4x4 matrix.
 // Arguments:
@@ -732,6 +748,7 @@ function det4(M) =
 // Function: determinant()
 // Usage:
 //   d = determinant(M);
+// Topics: Matrices, Linear Algebra
 // Description:
 //   Returns the determinant for the given square matrix.
 // Arguments:
@@ -764,6 +781,7 @@ function determinant(M) =
 // Function: norm_fro()
 // Usage:
 //    norm_fro(A)
+// Topics: Matrices, Linear Algebra
 // Description:
 //    Computes frobenius norm of input matrix.  The frobenius norm is the square root of the sum of the
 //    squares of all of the entries of the matrix.  On vectors it is the same as the usual 2-norm.
@@ -776,8 +794,14 @@ function norm_fro(A) =
 // Function: matrix_trace()
 // Usage:
 //   matrix_trace(M)
+// Topics: Matrices, Linear Algebra
 // Description:
 //   Computes the trace of a square matrix, the sum of the entries on the diagonal.  
 function matrix_trace(M) =
    assert(is_matrix(M,square=true), "Input to trace must be a square matrix")
    [for(i=[0:1:len(M)-1])1] * [for(i=[0:1:len(M)-1]) M[i][i]];
+
+
+
+// vim: expandtab tabstop=4 shiftwidth=4 softtabstop=4 nowrap
+

shapes3d.scad

@@ -670,11 +670,12 @@ module prismoid(
         rounding=rounding, chamfer=chamfer, 
         rounding1=rounding1, rounding2=rounding2,
         chamfer1=chamfer1, chamfer2=chamfer2,
-        l=l, height=height, length=length, center=CENTER, _return_dim=true
+        l=l, height=height, length=length, anchor=BOT, _return_dim=true
     );
     anchor = get_anchor(anchor, center, BOT, BOT);
     attachable(anchor,spin,orient, size=vnf_s1_s2_shift[1], size2=vnf_s1_s2_shift[2], shift=vnf_s1_s2_shift[3]) {
-        vnf_polyhedron(vnf_s1_s2_shift[0], convexity=4);
+        down(vnf_s1_s2_shift[1].z/2)
+            vnf_polyhedron(vnf_s1_s2_shift[0], convexity=4);
         children();
     }
 }

structs.scad

@@ -2,7 +2,7 @@
 // LibFile: structs.scad
 //   This file provides manipulation of "structs".  A "struct" is a data structure that
 //   associates arbitrary keys with values and allows you to get and set values
-//   by key.  
+//   by key.
 // Includes:
 //   include <BOSL2/std.scad>
 //   include <BOSL2/structs.scad>
@@ -19,14 +19,15 @@
 // An empty list `[]` is an empty structure and can be used wherever a structure input is required.
 
 // Function: struct_set()
+// Topics: Data Structures, Dictionaries
 // Usage:
-//   struct_set(struct, key, value, [grow=])
-//   struct_set(struct, [key1, value1, key2, value2, ...], [grow=])
+//   struct2 = struct_set(struct, key, value, [grow=]);
+//   struct2 = struct_set(struct, [key1, value1, key2, value2, ...], [grow=]);
 // Description:
-//   Sets the key(s) in the structure to the specified value(s), returning a new updated structure.  If a key
-//   exists its value is changed, otherwise the key is added to the structure.  If grow is set to false then
+//   Sets the key(s) in the structure to the specified value(s), returning a new updated structure.  If a
+//   key exists its value is changed, otherwise the key is added to the structure.  If `grow=false` then
 //   it is an error to set a key not already defined in the structure.  If you specify the same key twice
-//   that is also an error.  Note that key order will change when you change a key's value.   
+//   that is also an error.  Note that key order will change when you change a key's value.
 // Arguments:
 //   struct = input structure.
 //   key = key to set or list of key,value pairs to set
@@ -36,7 +37,7 @@
 function struct_set(struct, key, value, grow=true) =
   is_def(value) ? struct_set(struct,[key,value],grow=grow)
   :
-  assert(is_list(key) && len(key)%2==0, "[key,value] pair list is not a list or has an odd length") 
+  assert(is_list(key) && len(key)%2==0, "[key,value] pair list is not a list or has an odd length")
   let(
       new_entries = [for(i=[0:1:len(key)/2-1]) [key[2*i], key[2*i+1]]],
       newkeys = column(new_entries,0),
@@ -54,15 +55,16 @@ function struct_set(struct, key, value, grow=true) =
 function _format_key(key) = is_string(key) ? str("\"",key,"\""): key;
 
 // Function: struct_remove()
+// Topics: Data Structures, Dictionaries
 // Usage:
-//   struct_remove(struct, key)
+//   struct2 = struct_remove(struct, key);
 // Description:
 //   Remove key or list of keys from a structure.  If you want to remove a single key which is a list
 //   you must pass it as a singleton list, or struct_remove will attempt to remove the listed items as keys.
-//   If you list the same item multiple times for removal it will be removed without error.  
+//   If you list the same item multiple times for removal it will be removed without error.
 // Arguments:
 //   struct = input structure
-//   key = a single key or list of keys to remove.  
+//   key = a single key or list of keys to remove.
 function struct_remove(struct, key) =
    !is_list(key) ? struct_remove(struct, [key]) :
     let(ind = search(key, struct))
@@ -70,8 +72,9 @@ function struct_remove(struct, key) =
 
 
 // Function: struct_val()
+// Topics: Data Structures, Dictionaries
 // Usage:
-//   struct_val(struct, key, default)
+//   val = struct_val(struct, key, default);
 // Description:
 //   Returns the value for the specified key in the structure, or default value if the key is not present
 // Arguments:
@@ -85,8 +88,9 @@ function struct_val(struct, key, default=undef) =
 
 
 // Function: struct_keys()
+// Topics: Data Structures, Dictionaries
 // Usage:
-//   keys = struct_keys(struct)
+//   keys = struct_keys(struct);
 // Description:
 //   Returns a list of the keys in a structure
 // Arguments:
@@ -95,8 +99,10 @@ function struct_keys(struct) = column(struct,0);
 
 
 // Function&Module: echo_struct()
+// Topics: Data Structures, Dictionaries
 // Usage:
-//   echo_struct(struct, [name])
+//   echo_struct(struct, [name]);
+//   foo = echo_struct(struct, [name]);
 // Description:
 //   Displays a list of structure keys and values, one pair per line, for easier reading.
 // Arguments:
@@ -114,8 +120,9 @@ module echo_struct(struct,name="") {
 
 
 // Function: is_struct()
+// Topics: Data Structures, Dictionaries
 // Usage:
-//   is_struct(struct)
+//   bool = is_struct(struct);
 // Description:
 //   Returns true if the input is a list of pairs, false otherwise.
 function is_struct(x) =

transforms.scad

@@ -82,6 +82,7 @@ _NO_ARG = [true,[123232345],false];
 // Usage: Get Translation Matrix
 //   mat = move(v);
 //
+// Synopsis: Translates children in an arbitrary direction.
 // Topics: Affine, Matrices, Transforms, Translation
 // See Also: left(), right(), fwd(), back(), down(), up(), spherical_to_xyz(), altaz_to_xyz(), cylindrical_to_xyz(), polar_to_xy()
 //
@@ -167,6 +168,7 @@ function translate(v=[0,0,0], p=_NO_ARG) = move(v=v, p=p);
 // Usage: Get Translation Matrix
 //   mat = left(x);
 //
+// Synopsis: Translates children leftwards (X-).
 // Topics: Affine, Matrices, Transforms, Translation
 // See Also: move(), right(), fwd(), back(), down(), up()
 //
@@ -210,6 +212,7 @@ function left(x=0, p=_NO_ARG) =
 // Usage: Get Translation Matrix
 //   mat = right(x);
 //
+// Synopsis: Translates children rightwards (X+).
 // Topics: Affine, Matrices, Transforms, Translation
 // See Also: move(), left(), fwd(), back(), down(), up()
 //
@@ -263,6 +266,7 @@ function xmove(x=0, p=_NO_ARG) =
 // Usage: Get Translation Matrix
 //   mat = fwd(y);
 //
+// Synopsis: Translates children forwards (Y-).
 // Topics: Affine, Matrices, Transforms, Translation
 // See Also: move(), left(), right(), back(), down(), up()
 //
@@ -306,6 +310,7 @@ function fwd(y=0, p=_NO_ARG) =
 // Usage: Get Translation Matrix
 //   mat = back(y);
 //
+// Synopsis: Translates children backwards (Y+).
 // Topics: Affine, Matrices, Transforms, Translation
 // See Also: move(), left(), right(), fwd(), down(), up()
 //
@@ -359,6 +364,7 @@ function ymove(y=0,p=_NO_ARG) =
 // Usage: Get Translation Matrix
 //   mat = down(z);
 //
+// Synopsis: Translates children downwards (Z-).
 // Topics: Affine, Matrices, Transforms, Translation
 // See Also: move(), left(), right(), fwd(), back(), up()
 //
@@ -400,6 +406,7 @@ function down(z=0, p=_NO_ARG) =
 // Usage: Get Translation Matrix
 //   mat = up(z);
 //
+// Synopsis: Translates children upwards (Z+).
 // Topics: Affine, Matrices, Transforms, Translation
 // See Also: move(), left(), right(), fwd(), back(), down()
 //
@@ -467,6 +474,7 @@ function zmove(z=0, p=_NO_ARG) =
 //   M = rot(a, v, [cp=], [reverse=]);
 //   M = rot(from=, to=, [a=], [reverse=]);
 //
+// Synopsis: Rotates children in various ways.
 // Topics: Affine, Matrices, Transforms, Rotation
 // See Also: xrot(), yrot(), zrot()
 //
@@ -562,6 +570,7 @@ function rot(a=0, v, cp, from, to, reverse=false, p=_NO_ARG, _m) =
 // Usage: As a function to return rotation matrix
 //   mat = xrot(a, [cp=]);
 //
+// Synopsis: Rotates children around the X axis using the right-hand rule.
 // Topics: Affine, Matrices, Transforms, Rotation
 // See Also: rot(), yrot(), zrot()
 //
@@ -608,6 +617,7 @@ function xrot(a=0, p=_NO_ARG, cp) = rot([a,0,0], cp=cp, p=p);
 // Usage: Get Rotation Matrix
 //   mat = yrot(a, [cp=]);
 //
+// Synopsis: Rotates children around the Y axis using the right-hand rule.
 // Topics: Affine, Matrices, Transforms, Rotation
 // See Also: rot(), xrot(), zrot()
 //
@@ -654,6 +664,7 @@ function yrot(a=0, p=_NO_ARG, cp) = rot([0,a,0], cp=cp, p=p);
 // Usage: As Function to return rotation matrix
 //   mat = zrot(a, [cp=]);
 //
+// Synopsis: Rotates children around the Z axis using the right-hand rule.
 // Topics: Affine, Matrices, Transforms, Rotation
 // See Also: rot(), xrot(), yrot()
 //
@@ -705,6 +716,7 @@ function zrot(a=0, p=_NO_ARG, cp) = rot(a, cp=cp, p=p);
 //   pts = scale(v, p, [cp=]);
 // Usage: Get Scaling Matrix
 //   mat = scale(v, [cp=]);
+// Synopsis: Scales children arbitrarily.
 // Topics: Affine, Matrices, Transforms, Scaling
 // See Also: xscale(), yscale(), zscale()
 // Description:
@@ -748,7 +760,6 @@ function scale(v=1, p=_NO_ARG, cp=[0,0,0]) =
 
 // Function&Module: xscale()
 //
-//
 // Usage: As Module
 //   xscale(x, [cp=]) CHILDREN;
 // Usage: Scale Points
@@ -756,6 +767,7 @@ function scale(v=1, p=_NO_ARG, cp=[0,0,0]) =
 // Usage: Get Affine Matrix
 //   mat = xscale(x, [cp=]);
 //
+// Synopsis: Scales children along the X axis.
 // Topics: Affine, Matrices, Transforms, Scaling
 // See Also: scale(), yscale(), zscale()
 //
@@ -810,6 +822,7 @@ function xscale(x=1, p=_NO_ARG, cp=0) =
 // Usage: Get Affine Matrix
 //   mat = yscale(y, [cp=]);
 //
+// Synopsis: Scales children along the Y axis.
 // Topics: Affine, Matrices, Transforms, Scaling
 // See Also: scale(), xscale(), zscale()
 //
@@ -864,6 +877,7 @@ function yscale(y=1, p=_NO_ARG, cp=0) =
 // Usage: Get Affine Matrix
 //   mat = zscale(z, [cp=]);
 //
+// Synopsis: Scales children along the Z axis.
 // Topics: Affine, Matrices, Transforms, Scaling
 // See Also: scale(), xscale(), yscale()
 //
@@ -920,6 +934,7 @@ function zscale(z=1, p=_NO_ARG, cp=0) =
 //   pt = mirror(v, p);
 // Usage: Get Reflection/Mirror Matrix
 //   mat = mirror(v);
+// Synopsis: Reflects children across an arbitrary plane.
 // Topics: Affine, Matrices, Transforms, Reflection, Mirroring
 // See Also: xflip(), yflip(), zflip()
 // Description:
@@ -991,6 +1006,7 @@ function mirror(v, p=_NO_ARG) =
 // Usage: Get Affine Matrix
 //   mat = xflip([x=]);
 //
+// Synopsis: Reflects children across the YZ plane.
 // Topics: Affine, Matrices, Transforms, Reflection, Mirroring
 // See Also: mirror(), yflip(), zflip()
 //
@@ -1045,6 +1061,7 @@ function xflip(p=_NO_ARG, x=0) =
 // Usage: Get Affine Matrix
 //   mat = yflip([y=]);
 //
+// Synopsis: Reflects children across the XZ plane.
 // Topics: Affine, Matrices, Transforms, Reflection, Mirroring
 // See Also: mirror(), xflip(), zflip()
 //
@@ -1099,6 +1116,7 @@ function yflip(p=_NO_ARG, y=0) =
 // Usage: Get Affine Matrix
 //   mat = zflip([z=]);
 //
+// Synopsis: Reflects children across the XY plane.
 // Topics: Affine, Matrices, Transforms, Reflection, Mirroring
 // See Also: mirror(), xflip(), yflip()
 //
@@ -1154,6 +1172,7 @@ function zflip(p=_NO_ARG, z=0) =
 //   map = frame_map(x=VECTOR1, y=VECTOR2, [reverse=]);
 //   map = frame_map(x=VECTOR1, z=VECTOR2, [reverse=]);
 //   map = frame_map(y=VECTOR1, z=VECTOR2, [reverse=]);
+// Synopsis: Rotates and possibly skews children from one frame of reference to another.
 // Topics: Affine, Matrices, Transforms, Rotation
 // See Also: rot(), xrot(), yrot(), zrot()
 // Description:
@@ -1240,6 +1259,7 @@ module frame_map(x,y,z,p,reverse=false)
 // Usage: Get Affine Matrix
 //   mat = skew([sxy=]|[axy=], [sxz=]|[axz=], [syx=]|[ayx=], [syz=]|[ayz=], [szx=]|[azx=], [szy=]|[azy=]);
 // Topics: Affine, Matrices, Transforms, Skewing
+// Synopsis: Skews children along various axes.
 //
 // Description:
 //   Skews geometry by the given skew factors.
@@ -1363,6 +1383,7 @@ function is_2d_transform(t) =    // z-parameters are zero, except we allow t[2][
 // Usage:
 //   pts = apply(transform, points);
 // Topics: Affine, Matrices, Transforms
+// Synopsis: Applies a transformation matrix to a point, list of points, array of points, or VNF.
 // Description:
 //   Applies the specified transformation matrix `transform` to a point, point list, bezier patch or VNF.
 //   When `points` contains 2D or 3D points the transform matrix may be a 4x4 affine matrix or a 3x4 

tutorials/Transforms.md

@@ -158,10 +158,8 @@ Constant                       | Value        | Direction
 `RIGHT`                        | `[ 1, 0, 0]` | Towards X+
 `FWD`, `FORWARD`, `FRONT`      | `[ 0,-1, 0]` | Towards Y-
 `BACK`                         | `[ 0, 1, 0]` | Towards Y+
-`DOWN`, `BOTTOM`, `BOT`, `BTM` | `[ 0, 0,-1]` | Towards Z-
+`DOWN`, `BOTTOM`, `BOT`        | `[ 0, 0,-1]` | Towards Z-
 `UP`, `TOP`                    | `[ 0, 0, 1]` | Towards Z+
-`ALLNEG`                       | `[-1,-1,-1]` | Towards X-Y-Z-
-`ALLPOS`                       | `[ 1, 1, 1]` | Towards X+Y+Z+
 
 This lets you rewrite the above vector rotation more clearly as:
 ```openscad

vectors.scad

@@ -284,6 +284,26 @@ function vector_axis(v1,v2=undef,v3=undef) =
             ) unit(cross(w1,w3));
 
 
+// Function: vector_bisect()
+// Usage:
+//   newv = vector_bisect(v1,v2);
+// Description:
+//   Returns a unit vector that exactly bisects the minor angle between two given vectors.
+//   If given two vectors that are directly opposed, returns `undef`.
+function vector_bisect(v1,v2) =
+    assert(is_vector(v1))
+    assert(is_vector(v2))
+    assert(!approx(norm(v1),0), "Zero length vector.")
+    assert(!approx(norm(v2),0), "Zero length vector.")
+    assert(len(v1)==len(v2), "Vectors are of different sizes.")
+    let( v1 = unit(v1), v2 = unit(v2) )
+    approx(v1,-v2)? undef :
+    let(
+        axis = vector_axis(v1,v2),
+        ang = vector_angle(v1,v2),
+        v3 = rot(ang/2, v=axis, p=v1)
+    ) v3;
+
 
 
 // Section: Vector Searching