diff --git a/coords.scad b/coords.scad index 393af7b..159c3af 100644 --- a/coords.scad +++ b/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() +// 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 diff --git a/linalg.scad b/linalg.scad index 3cecdb9..35c9822 100644 --- a/linalg.scad +++ b/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() +// 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) = diff --git a/shapes3d.scad b/shapes3d.scad index c395339..207c930 100644 --- a/shapes3d.scad +++ b/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);