Merge pull request #1153 from adrianVmariano/master

add synopsis to coords and linalg

coords.scad

@@ -16,6 +16,7 @@
 //   pt = point2d(p, [fill]);
 // Topics: Coordinates, Points
 // See Also: path2d(), point3d(), path3d()
+// Synopsis: Convert a vector to 2d. 
 // Description:
 //   Returns a 2D vector/point from a 2D or 3D vector.  If given a 3D point, removes the Z coordinate.
 // Arguments:
@@ -29,6 +30,7 @@ function point2d(p, fill=0) = assert(is_list(p)) [for (i=[0:1]) (p[i]==undef)? f
 //   pts = path2d(points);
 // Topics: Coordinates, Points, Paths
 // See Also: point2d(), point3d(), path3d()
+// Synopsis: Convert a path to 2d. 
 // Description:
 //   Returns a list of 2D vectors/points from a list of 2D, 3D or higher dimensional vectors/points.
 //   Removes the extra coordinates from higher dimensional points.  The input must be a path, where
@@ -47,6 +49,7 @@ function path2d(points) =
 //   pt = point3d(p, [fill]);
 // Topics: Coordinates, Points
 // See Also: path2d(), point2d(), path3d()
+// Synopsis: Convert a vector to 3d. 
 // Description:
 //   Returns a 3D vector/point from a 2D or 3D vector.
 // Arguments:
@@ -61,6 +64,7 @@ function point3d(p, fill=0) =
 // Usage:
 //   pts = path3d(points, [fill]);
 // Topics: Coordinates, Points, Paths
+// Synopsis: Convert a path to 3d. 
 // See Also: point2d(), path2d(), point3d()
 // Description:
 //   Returns a list of 3D vectors/points from a list of 2D or higher dimensional vectors/points
@@ -85,6 +89,7 @@ function path3d(points, fill=0) =
 // Usage:
 //   pt = point4d(p, [fill]);
 // Topics: Coordinates, Points
+// Synopsis: Convert a vector to 4d. 
 // See Also: point2d(), path2d(), point3d(), path3d(), path4d()
 // Description:
 //   Returns a 4D vector/point from a 2D or 3D vector.
@@ -100,6 +105,7 @@ function point4d(p, fill=0) = assert(is_list(p))
 //   pt = path4d(points, [fill]);
 // Topics: Coordinates, Points, Paths
 // See Also: point2d(), path2d(), point3d(), path3d(), point4d()
+// Synopsis: Convert a path to 4d.  
 // Description:
 //   Returns a list of 4D vectors/points from a list of 2D or 3D vectors/points.
 // Arguments:
@@ -132,6 +138,7 @@ function path4d(points, fill=0) =
 //   pt = polar_to_xy(r, theta);
 //   pt = polar_to_xy([r, theta]);
 // Topics: Coordinates, Points, Paths
+// Synopsis: Convert 2d polar coordinates to cartesian coordinates. 
 // See Also: xy_to_polar(), xyz_to_cylindrical(), cylindrical_to_xyz(), xyz_to_spherical(), spherical_to_xyz()
 // Description:
 //   Convert polar coordinates to 2D cartesian coordinates.
@@ -161,6 +168,7 @@ function polar_to_xy(r,theta=undef) = let(
 //   r_theta = xy_to_polar(x,y);
 //   r_theta = xy_to_polar([X,Y]);
 // Topics: Coordinates, Points, Paths
+// Synopsis: Convert 2d cartesian coordinates to polar coordinates (radius and angle)
 // See Also: polar_to_xy(), xyz_to_cylindrical(), cylindrical_to_xyz(), xyz_to_spherical(), spherical_to_xyz()
 // Description:
 //   Convert 2D cartesian coordinates to polar coordinates.
@@ -189,6 +197,7 @@ function xy_to_polar(x,y=undef) = let(
 //   xy = project_plane(plane, p);
 // Usage: To get a transform matrix
 //   M = project_plane(plane)
+// Synopsis: Project a set of points onto a specified plane, returning 2d points.  
 // Description:
 //   Maps the provided 3d point(s) from 3D coordinates to a 2d coordinate system defined by `plane`.  Points that are not
 //   on the specified plane will be projected orthogonally onto the plane.  This coordinate system is useful if you need
@@ -264,6 +273,7 @@ function project_plane(plane,p) =
 //   xyz = lift_plane(plane, p);
 // Usage: to get transform matrix
 //   M =  lift_plane(plane);
+// Synopsis: Map a list of 2d points onto a plane in 3d. 
 // Topics: Coordinates, Points, Paths
 // See Also: project_plane()
 // Description:
@@ -316,7 +326,8 @@ function lift_plane(plane, p) =
 //   pt = cylindrical_to_xyz(r, theta, z);
 //   pt = cylindrical_to_xyz([r, theta, z]);
 // Topics: Coordinates, Points, Paths
-// See Also: xyz_to_cylindrical(), xyz_to_spherical(), spherical_to_xyz()
+// See Also: xyz_to_cylindrical(), xy_to_polar(), polar_to_xy(), xyz_to_spherical(), spherical_to_xyz()
+// Synopsis: Convert cylindrical coordinates to cartesian coordinates. 
 // Description:
 //   Convert cylindrical coordinates to 3D cartesian coordinates.  Returns [X,Y,Z] cartesian coordinates.
 // Arguments:
@@ -338,7 +349,8 @@ function cylindrical_to_xyz(r,theta=undef,z=undef) = let(
 //   rtz = xyz_to_cylindrical(x,y,z);
 //   rtz = xyz_to_cylindrical([X,Y,Z]);
 // Topics: Coordinates, Points, Paths
-// See Also: cylindrical_to_xyz(), xyz_to_spherical(), spherical_to_xyz()
+// Synopsis: Convert 3d cartesian coordinates to cylindrical coordinates. 
+// See Also: cylindrical_to_xyz(), xy_to_polar(), polar_to_xy(), xyz_to_spherical(), spherical_to_xyz()
 // Description:
 //   Convert 3D cartesian coordinates to cylindrical coordinates.  Returns [radius,theta,Z].
 //   Theta is the angle counter-clockwise of X+ on the XY plane.  Z is height above the XY plane.
@@ -360,8 +372,9 @@ function xyz_to_cylindrical(x,y=undef,z=undef) = let(
 //   pt = spherical_to_xyz([r, theta, phi]);
 // Description:
 //   Convert spherical coordinates to 3D cartesian coordinates.  Returns [X,Y,Z] cartesian coordinates.
+// Synopsis: Convert spherical coordinates to 3d cartesian coordinates. 
 // Topics: Coordinates, Points, Paths
-// See Also: cylindrical_to_xyz(), xyz_to_spherical(), xyz_to_cylindrical()
+// See Also: cylindrical_to_xyz(), xyz_to_spherical(), xyz_to_cylindrical(), altaz_to_xyz(), xyz_to_altaz()
 // Arguments:
 //   r = distance from origin.
 //   theta = angle in degrees, counter-clockwise of X+ on the XY plane.
@@ -381,7 +394,8 @@ function spherical_to_xyz(r,theta=undef,phi=undef) = let(
 //   r_theta_phi = xyz_to_spherical(x,y,z)
 //   r_theta_phi = xyz_to_spherical([X,Y,Z])
 // Topics: Coordinates, Points, Paths
-// See Also: cylindrical_to_xyz(), spherical_to_xyz(), xyz_to_cylindrical()
+// Synopsis: Convert 3d cartesian coordinates to spherical coordinates. 
+// See Also: cylindrical_to_xyz(), spherical_to_xyz(), xyz_to_cylindrical(), altaz_to_xyz(), xyz_to_altaz()
 // Description:
 //   Convert 3D cartesian coordinates to spherical coordinates.  Returns [r,theta,phi], where phi is
 //   the angle from the Z+ pole, and theta is degrees counter-clockwise of X+ on the XY plane.
@@ -403,6 +417,7 @@ function xyz_to_spherical(x,y=undef,z=undef) = let(
 //   pt = altaz_to_xyz([alt, az, r]);
 // Topics: Coordinates, Points, Paths
 // See Also: cylindrical_to_xyz(), xyz_to_spherical(), spherical_to_xyz(), xyz_to_cylindrical(), xyz_to_altaz()
+// Synopsis: Convert altitude/azimuth/range to 3d cartesian coordinates. 
 // Description:
 //   Convert altitude/azimuth/range coordinates to 3D cartesian coordinates.
 //   Returns [X,Y,Z] cartesian coordinates.
@@ -426,6 +441,7 @@ function altaz_to_xyz(alt,az=undef,r=undef) = let(
 //   alt_az_r = xyz_to_altaz([X,Y,Z]);
 // Topics: Coordinates, Points, Paths
 // See Also: cylindrical_to_xyz(), xyz_to_spherical(), spherical_to_xyz(), xyz_to_cylindrical(), altaz_to_xyz()
+// Synopsis: Convert 3d cartesian coordinates to [altitude,azimuth,range]. 
 // Description:
 //   Convert 3D cartesian coordinates to altitude/azimuth/range coordinates.
 //   Returns [altitude,azimuth,range], where altitude is angle above the

linalg.scad

@@ -34,6 +34,7 @@
 // Usage:
 //   test = is_matrix(A, [m], [n], [square])
 // Topics: Matrices
+// Synopsis: Check if input is a numeric matrix, optionally of specified size
 // 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.
@@ -57,6 +58,7 @@ function is_matrix(A,m,n,square=false) =
 // Description:
 //   Returns true if the input matrix is symmetric, meaning it approximately equals its transpose.  
 //   The matrix can have arbitrary entries.  
+// Synopsis: Checks if matrix is symmetric
 // Arguments:
 //   A = matrix to test
 //   eps = epsilon for comparing equality.  Default: 1e-12
@@ -73,6 +75,7 @@ function is_matrix_symmetric(A,eps=1e-12) =
 //   or around the origin if `centered` is true. 
 //   The matrix must be 3x3 (representing a 2d transformation) or 4x4 (representing a 3d transformation).
 //   You can set `dim` to 2 to require a 2d transform (3x3 matrix) or to 3 to require a 3d transform (4x4 matrix).
+// Synopsis: Check if a transformation matrix represents a rotation.
 // Arguments:
 //   A = matrix to test
 //   dim = if set, specify dimension in which the transform operates (2 or 3)
@@ -97,6 +100,7 @@ function is_rotation(A,dim,centered=false) =
 //    echo_matrix(M, [description], [sig], [sep], [eps]);
 //    dummy = echo_matrix(M, [description], [sig], [sep], [eps]),
 // Topics: Matrices
+// Synopsis: Print a matrix neatly to the console.
 // 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
@@ -138,6 +142,7 @@ module echo_matrix(M,description,sig=4,sep=1,eps=1e-9)
 // Description:
 //   Extracts entry `i` from each list in M, or equivalently column i from the matrix M, and returns it as a vector.  
 //   This function will return `undef` at all entry positions indexed by i not found in M.
+// Synopsis: Extract a column from a matrix.
 // Arguments:
 //   M = The given list of lists.
 //   i = The index to fetch
@@ -161,6 +166,7 @@ function column(M, i) =
 //   mat = submatrix(M, idx1, idx2);
 // Topics: Matrices, Arrays
 // See Also: column(), block_matrix(), submatrix_set()
+// Synopsis: Extract a submatrix from a matrix
 // 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.
 // Arguments:
@@ -195,6 +201,7 @@ function submatrix(M,idx1,idx2) =
 // Topics: Affine, Matrices, Transforms
 // Description:
 //   Create an `n` by `n` square identity matrix.
+// Synopsis: Return identity matrix.
 // Arguments:
 //   n = The size of the identity matrix square, `n` by `n`.
 // Example:
@@ -229,7 +236,8 @@ function ident(n) = [
 // Description:
 //   Creates a square matrix with the items in the list `diag` on
 //   its diagonal.  The off diagonal entries are set to offdiag,
-//   which is zero by default. 
+//   which is zero by default.
+// Synopsis: Make a diagonal matrix.
 // Arguments:
 //   diag = A list of items to put in the diagnal cells of the matrix.
 //   offdiag = Value to put in non-diagonal matrix cells.
@@ -242,6 +250,7 @@ function diagonal_matrix(diag, offdiag=0) =
 // Usage:
 //    M = transpose(M, [reverse]);
 // Topics: Linear Algebra, Matrices
+// Synopsis: Transpose a matrix
 // 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
@@ -320,8 +329,9 @@ function transpose(M, reverse=false) =
 // Usage:
 //   x = outer_product(u,v);
 // Topics: Linear Algebra, Matrices
+// Synopsis: Compute the outer product of two vectors. 
 // Description:
-//   Compute the outer product of two vectors, a matrix.  
+//   Compute the outer product of two vectors, which is a matrix.
 // Usage:
 //   M = outer_product(u,v);
 function outer_product(u,v) =
@@ -333,6 +343,7 @@ function outer_product(u,v) =
 //   mat = submatrix_set(M, A, [m], [n]);
 // Topics: Matrices, Arrays
 // See Also: column(), submatrix()
+// Synopsis: Takes a matrix as input and change values in a 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
 //   you can specify offset coordinates m and n.  If A (as adjusted by m and n) extends beyond the bounds
@@ -361,6 +372,7 @@ function submatrix_set(M,A,m=0,n=0) =
 //   A = hstack(M1, M2)
 //   A = hstack(M1, M2, M3)
 //   A = hstack([M1, M2, M3, ...])
+// Synopsis: Make a new matrix by stacking matrices horizontally.
 // Topics: Matrices, Arrays
 // See Also: column(), submatrix(), block_matrix()
 // Description:
@@ -415,6 +427,7 @@ function hstack(M1, M2, M3) =
 //    bmat = block_matrix([[M11, M12,...],[M21, M22,...], ... ]);
 // Topics: Matrices, Arrays
 // See Also: column(), submatrix()
+// Synopsis: Make a new matrix from a block of matrices. 
 // Description:
 //    Create a block matrix by supplying a matrix of matrices, which will
 //    be combined into one unified matrix.  Every matrix in one row
@@ -461,6 +474,7 @@ function block_matrix(M) =
 // Usage:
 //   solv = linear_solve(A,b,[pivot])
 // Topics: Matrices, Linear Algebra
+// Synopsis: Solve Ax=b or, for overdetermined case, solve the least square problem. 
 // 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.
@@ -498,6 +512,7 @@ function linear_solve(A,b,pivot=true) =
 // Usage:
 //   x = linear_solve3(A,b)
 // Topics: Matrices, Linear Algebra
+// Synopsis: Fast solution to Ax=b where A is 3x3.
 // 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.
@@ -523,6 +538,7 @@ function linear_solve3(A,b) =
 // Usage:
 //    mat = matrix_inverse(A)
 // Topics: Matrices, Linear Algebra
+// Synopsis: General matrix inverse. 
 // 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.
@@ -536,6 +552,7 @@ function matrix_inverse(A) =
 // Function: rot_inverse()
 // Usage:
 //   B = rot_inverse(A)
+// Synopsis: Invert 2d or 3d rotation transformations. 
 // Topics: Matrices, Linear Algebra, Affine
 // Description:
 //   Inverts a 2d (3x3) or 3d (4x4) rotation matrix.  The matrix can be a rotation around any center,
@@ -558,6 +575,7 @@ function rot_inverse(T) =
 // Usage:
 //   x = null_space(A)
 // Topics: Matrices, Linear Algebra
+// Synopsis: Return basis for the null space of A. 
 // 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. 
@@ -575,6 +593,7 @@ function null_space(A,eps=1e-12) =
 // Usage:
 //   qr = qr_factor(A,[pivot]);
 // Topics: Matrices, Linear Algebra
+// Synopsis: Compute QR factorization of a matrix.
 // 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)
@@ -626,6 +645,7 @@ function _swap_matrix(n,i,j) =
 // Usage:
 //   x = back_substitute(R, b, [transpose]);
 // Topics: Matrices, Linear Algebra
+// Synopsis: Solve an upper triangular system, Rx=b.  
 // 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.
@@ -658,6 +678,7 @@ function _back_substitute(R, b, x=[]) =
 // Usage:
 //   L = cholesky(A);
 // Topics: Matrices, Linear Algebra
+// Synopsis: Compute the Cholesky factorization of a matrix. 
 // 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
@@ -694,6 +715,7 @@ function _cholesky(A,L,n) =
 // Usage:
 //   d = det2(M);
 // Topics: Matrices, Linear Algebra
+// Synopsis: Compute determinant of 2x2 matrix.
 // Description:
 //   Rturns the determinant for the given 2x2 matrix.
 // Arguments:
@@ -710,6 +732,7 @@ function det2(M) =
 // Usage:
 //   d = det3(M);
 // Topics: Matrices, Linear Algebra
+// Synopsis: Compute determinant of 3x3 matrix.
 // Description:
 //   Returns the determinant for the given 3x3 matrix.
 // Arguments:
@@ -727,6 +750,7 @@ function det3(M) =
 // Usage:
 //   d = det4(M);
 // Topics: Matrices, Linear Algebra
+// Synopsis: Compute determinant of 4x4 matrix. 
 // Description:
 //   Returns the determinant for the given 4x4 matrix.
 // Arguments:
@@ -751,6 +775,7 @@ function det4(M) =
 // Topics: Matrices, Linear Algebra
 // Description:
 //   Returns the determinant for the given square matrix.
+// Synopsis: compute determinant of an arbitrary square matrix. 
 // Arguments:
 //   M = The NxN square matrix to get the determinant of.
 // Example:
@@ -782,6 +807,7 @@ function determinant(M) =
 // Usage:
 //    norm_fro(A)
 // Topics: Matrices, Linear Algebra
+// Synopsis: Compute Frobenius norm of a matrix
 // 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.
@@ -795,6 +821,7 @@ function norm_fro(A) =
 // Usage:
 //   matrix_trace(M)
 // Topics: Matrices, Linear Algebra
+// Synopsis: Compute the trace of a square matrix. 
 // Description:
 //   Computes the trace of a square matrix, the sum of the entries on the diagonal.  
 function matrix_trace(M) =

shapes3d.scad

@@ -3159,7 +3159,7 @@ module path_text(path, text, font, size, thickness, lettersize, offset=0, revers
 
   start = center ? (path_length(path) - textlength)/2 : 0;
    
-  pts = path_cut_points(path, add_scalar([ each cumsum(lcenter)],start+0*lsize[0]/2), direction=true);
+  pts = path_cut_points(path, add_scalar(cumsum(lcenter),start), direction=true);
 
   usernorm = is_def(normal);
   usetop = is_def(top);