diff --git a/comparisons.scad b/comparisons.scad index aa13430..9bf286d 100644 --- a/comparisons.scad +++ b/comparisons.scad @@ -513,9 +513,6 @@ function unique_count(list) = - - - // Section: Sorting @@ -778,7 +775,7 @@ function group_sort(list, idx) = // Function: group_data() // Usage: // groupings = group_data(groups, values); -// Topics: Array Handling +// Topics: List Handling // See Also: zip() // Description: // Given a list of integer group numbers, and an equal-length list of values, diff --git a/linalg.scad b/linalg.scad index ae7f7a4..69f79ef 100644 --- a/linalg.scad +++ b/linalg.scad @@ -88,7 +88,7 @@ module echo_matrix(M,description,sig=4,eps=1e-9) // Function: column() // Usage: // list = column(M, i); -// Topics: Array Handling, List Handling +// Topics: Matrices, List Handling // 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. @@ -115,7 +115,7 @@ function column(M, i) = // Function: submatrix() // Usage: // mat = submatrix(M, idx1, idx2); -// Topics: Matrices, Array Handling +// Topics: Matrices // 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. @@ -180,7 +180,7 @@ function ident(n) = [ // Function: diagonal_matrix() // Usage: // mat = diagonal_matrix(diag, [offdiag]); -// Topics: Matrices, Array Handling +// Topics: Matrices // See Also: column(), submatrix() // Description: // Creates a square matrix with the items in the list `diag` on @@ -197,7 +197,7 @@ function diagonal_matrix(diag, offdiag=0) = // Function: transpose() // Usage: // M = transpose(M, [reverse]); -// Topics: Matrices, Array Handling +// Topics: 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 @@ -286,7 +286,7 @@ function outer_product(u,v) = // Function: submatrix_set() // Usage: // mat = submatrix_set(M, A, [m], [n]); -// Topics: Matrices, Array Handling +// Topics: Matrices // 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 @@ -316,7 +316,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, Array Handling +// Topics: Matrices // 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. @@ -368,7 +368,7 @@ function hstack(M1, M2, M3) = // Function: block_matrix() // Usage: // bmat = block_matrix([[M11, M12,...],[M21, M22,...], ... ]); -// Topics: Matrices, Array Handling +// Topics: Matrices // See Also: column(), submatrix() // Description: // Create a block matrix by supplying a matrix of matrices, which will diff --git a/lists.scad b/lists.scad index 8d829e8..e7a3533 100644 --- a/lists.scad +++ b/lists.scad @@ -6,15 +6,12 @@ ////////////////////////////////////////////////////////////////////// // Terminology: -// **List** = An ordered collection of zero or more items. ie: `["a", "b", "c"]` +// **List** = An ordered collection of zero or more arbitrary items. ie: `["a", "b", "c"]`, or `[3, "a", [4,5]]` // **Vector** = A list of numbers. ie: `[4, 5, 6]` -// **Array** = A nested list of lists, or list of lists of lists, or deeper. ie: `[[2,3], [4,5], [6,7]]` // **Set** = A list of unique items. - // Section: List Query Operations - // Function: is_homogeneous() // Alias: is_homogenous() // Usage: @@ -53,34 +50,34 @@ function _same_type(a,b, depth) = // Function: min_length() // Usage: -// llen = min_length(array); +// llen = min_length(list); // Topics: List Handling // See Also: max_length() // Description: // Returns the length of the shortest sublist in a list of lists. // Arguments: -// array = A list of lists. +// list = A list of lists. // Example: // slen = min_length([[3,4,5],[6,7,8,9]]); // Returns: 3 -function min_length(array) = - assert(is_list(array), "Invalid input." ) - min([for (v = array) len(v)]); +function min_length(list) = + assert(is_list(list), "Invalid input." ) + min([for (v = list) len(v)]); // Function: max_length() // Usage: -// llen = max_length(array); +// llen = max_length(list); // Topics: List Handling // See Also: min_length() // Description: // Returns the length of the longest sublist in a list of lists. // Arguments: -// array = A list of lists. +// list = A list of lists. // Example: // llen = max_length([[3,4,5],[6,7,8,9]]); // Returns: 4 -function max_length(array) = - assert(is_list(array), "Invalid input." ) - max([for (v = array) len(v)]); +function max_length(list) = + assert(is_list(list), "Invalid input." ) + max([for (v = list) len(v)]); @@ -108,7 +105,7 @@ function _list_shape_recurse(v) = // Function: list_shape() // Usage: // dims = list_shape(v, [depth]); -// Topics: Matrices, Array Handling +// Topics: Matrices, List Handling // Description: // Returns the size of a multi-dimensional array, a list of the lengths at each depth. // If the returned value has `dims[i] = j` then it means the ith index ranges of j items. @@ -329,21 +326,21 @@ function list_tail(list, from=1) = // Function: bselect() // Usage: -// array = bselect(array, index); +// sublist = bselect(list, index); // Topics: List Handling // See Also: list_bset() // Description: -// Returns the items in `array` whose matching element in `index` is true. +// Returns the items in `list` whose matching element in `index` is true. // Arguments: -// array = Initial list to extract items from. +// list = Initial list to extract items from. // index = List of booleans. // Example: // a = bselect([3,4,5,6,7], [false,true,true,false,true]); // Returns: [4,5,7] -function bselect(array,index) = - assert(is_list(array)||is_string(array), "Improper array." ) - assert(is_list(index) && len(index)>=len(array) , "Improper index list." ) - is_string(array)? str_join(bselect( [for (x=array) x], index)) : - [for(i=[0:len(array)-1]) if (index[i]) array[i]]; +function bselect(list,index) = + assert(is_list(list)||is_string(list), "Improper list." ) + assert(is_list(index) && len(index)>=len(list) , "Improper index list." ) + is_string(list)? str_join(bselect( [for (x=list) x], index)) : + [for(i=[0:len(list)-1]) if (index[i]) list[i]]; @@ -358,7 +355,7 @@ function bselect(array,index) = // Topics: List Handling // See Also: count(), lerpn() // Description: -// Generates a list or array of `n` copies of the given value `val`. +// Generates a list of `n` copies of the given value `val`. // If the count `n` is given as a list of counts, then this creates a // multi-dimensional array, filled with `val`. // Arguments: @@ -480,7 +477,7 @@ function force_list(value, n=1, fill) = // Topics: List Handling // See Also: select(), list_rotate() // Description: -// Reverses a list/array or string. +// Reverses a list or string. // Arguments: // x = The list or string to reverse. // Example: @@ -604,21 +601,21 @@ function repeat_entries(list, N, exact=true) = // Function: list_pad() // Usage: -// arr = list_pad(array, minlen, [fill]); +// newlist = list_pad(list, minlen, [fill]); // Topics: List Handling // See Also: force_list(), scalar_vec3() // Description: -// If the list `array` is shorter than `minlen` length, pad it to length with the value given in `fill`. +// If the list `list` is shorter than `minlen` length, pad it to length with the value given in `fill`. // Arguments: -// array = A list. +// list = A list. // minlen = The minimum length to pad the list to. // fill = The value to pad the list with. Default: `undef` // Example: // list = [3,4,5]; // nlist = list_pad(list,5,23); // Returns: [3,4,5,23,23] -function list_pad(array, minlen, fill) = - assert(is_list(array), "Invalid input." ) - concat(array,repeat(fill,minlen-len(array))); +function list_pad(list, minlen, fill) = + assert(is_list(list), "Invalid input." ) + concat(list,repeat(fill,minlen-len(list))); // Function: list_set() @@ -969,22 +966,22 @@ function permutations(l,n=2) = // Function: list_to_matrix() // Usage: -// groups = list_to_matrix(v, [cnt], [dflt]); +// groups = list_to_matrix(v, cnt, [dflt]); // Description: -// Takes a flat array of values, and groups items in sets of `cnt` length. +// Takes a flat list of values, and groups items in sets of `cnt` length. // The opposite of this is `flatten()`. -// Topics: Matrices, Array Handling +// Topics: Matrices, List Handling // See Also: column(), submatrix(), hstack(), flatten(), full_flatten() // Arguments: // v = The list of items to group. -// cnt = The number of items to put in each grouping. Default:2 -// dflt = The default value to fill in with if the list is not a multiple of `cnt` items long. Default: 0 +// cnt = The number of items to put in each grouping. +// dflt = The default value to fill in with if the list is not a multiple of `cnt` items long. Default: undef // Example: // v = [1,2,3,4,5,6]; // a = list_to_matrix(v,2) returns [[1,2], [3,4], [5,6]] // b = list_to_matrix(v,3) returns [[1,2,3], [4,5,6]] // c = list_to_matrix(v,4,0) returns [[1,2,3,4], [5,6,0,0]] -function list_to_matrix(v, cnt=2, dflt=0) = +function list_to_matrix(v, cnt, dflt=undef) = [for (i = [0:cnt:len(v)-1]) [for (j = [0:1:cnt-1]) default(v[i+j], dflt)]]; @@ -992,7 +989,7 @@ function list_to_matrix(v, cnt=2, dflt=0) = // Function: flatten() // Usage: // list = flatten(l); -// Topics: Matrices, Array Handling +// Topics: Matrices, List Handling // See Also: column(), submatrix(), hstack(), full_flatten() // Description: // Takes a list of lists and flattens it by one level. @@ -1008,7 +1005,7 @@ function flatten(l) = // Function: full_flatten() // Usage: // list = full_flatten(l); -// Topics: Matrices, Array Handling +// Topics: Matrices, List Handling // See Also: column(), submatrix(), hstack(), flatten() // Description: // Collects in a list all elements recursively found in any level of the given list. diff --git a/mutators.scad b/mutators.scad index 9049693..2e8aadf 100644 --- a/mutators.scad +++ b/mutators.scad @@ -103,16 +103,17 @@ module bounding_box(excess=0, planar=false) { // Description: // Slices an object at a cut plane, and masks away everything that is on one side. The v parameter is either a plane specification or // a normal vector. The s parameter is needed for the module -// version to control the size of the masking cube, which affects preview display. +// version to control the size of the masking cube. If s is too large then the preview display will flip around and display the +// wrong half, but if it is too small it won't fully mask your model. // When called as a function, you must supply a vnf, path or region in p. If planar is set to true for the module version the operation -// is performed in and UP and DOWN are treated as equivalent to BACK and FWD respectively. +// is performed in 2D and UP and DOWN are treated as equivalent to BACK and FWD respectively. // // Arguments: // p = path, region or VNF to slice. (Function version) // v = Normal of plane to slice at. Keeps everything on the side the normal points to. Default: [0,0,1] (UP) // cp = If given as a scalar, moves the cut plane along the normal by the given amount. If given as a point, specifies a point on the cut plane. Default: [0,0,0] -// s = Mask size to use. Use a number larger than twice your object's largest axis. If you make this too large, it messes with centering your view. Ignored for function version. Default: 100 -// planar = If true, perform a 2D operation. When planar, a `v` of `UP` or `DOWN` becomes equivalent of `BACK` and `FWD` respectively. +// s = Mask size to use. Use a number larger than twice your object's largest axis. If you make this too large, OpenSCAD's preview rendering may display the wrong half. (Module version) Default: 100 +// planar = If true, perform a 2D operation. When planar, a `v` of `UP` or `DOWN` becomes equivalent of `BACK` and `FWD` respectively. (Module version). Default: false. // // Examples: // half_of(DOWN+BACK, cp=[0,-10,0]) cylinder(h=40, r1=10, r2=0, center=false); @@ -207,13 +208,15 @@ function half_of(p, v=UP, cp) = // // Description: // Slices an object at a vertical Y-Z cut plane, and masks away everything that is right of it. +// The s parameter is needed for the module +// version to control the size of the masking cube. If s is too large then the preview display will flip around and display the +// wrong half, but if it is too small it won't fully mask your model. // // Arguments: // p = VNF, region or path to slice (function version) -// s = Mask size to use. Use a number larger than twice your object's largest axis. If you make this too large, OpenSCAD's preview rendering may be incorrect. Default: 100 +// s = Mask size to use. Use a number larger than twice your object's largest axis. If you make this too large, OpenSCAD's preview rendering may display the wrong half. (Module version) Default: 100 // x = The X coordinate of the cut-plane. Default: 0 -// planar = If true, perform a 2D operation. -// +// planar = If true, perform a 2D operation. (Module version) Default: false. // Examples: // left_half() sphere(r=20); // left_half(x=-8) sphere(r=20); @@ -247,13 +250,14 @@ function left_half(p,x=0) = half_of(p, LEFT, [x,0,0]); // // Description: // Slices an object at a vertical Y-Z cut plane, and masks away everything that is left of it. -// +// The s parameter is needed for the module +// version to control the size of the masking cube. If s is too large then the preview display will flip around and display the +// wrong half, but if it is too small it won't fully mask your model. // Arguments: // p = VNF, region or path to slice (function version) -// s = Mask size to use. Use a number larger than twice your object's largest axis. If you make this too large, OpenSCAD's preview rendering may be incorrect. Default: 100 +// s = Mask size to use. Use a number larger than twice your object's largest axis. If you make this too large, OpenSCAD's preview rendering may display the wrong half. (Module version) Default: 100 // x = The X coordinate of the cut-plane. Default: 0 -// planar = If true perform a 2D operation. -// +// planar = If true, perform a 2D operation. (Module version) Default: false. // Examples(FlatSpin,VPD=175): // right_half() sphere(r=20); // right_half(x=-5) sphere(r=20); @@ -287,13 +291,14 @@ function right_half(p,x=0) = half_of(p, RIGHT, [x,0,0]); // // Description: // Slices an object at a vertical X-Z cut plane, and masks away everything that is behind it. -// +// The s parameter is needed for the module +// version to control the size of the masking cube. If s is too large then the preview display will flip around and display the +// wrong half, but if it is too small it won't fully mask your model. // Arguments: // p = VNF, region or path to slice (function version) -// s = Mask size to use. Use a number larger than twice your object's largest axis. If you make this too large, OpenSCAD's preview rendering may be incorrect. Default: 100 +// s = Mask size to use. Use a number larger than twice your object's largest axis. If you make this too large, OpenSCAD's preview rendering may display the wrong half. (Module version) Default: 100 // y = The Y coordinate of the cut-plane. Default: 0 -// planar = If true perform a 2D operation. -// +// planar = If true, perform a 2D operation. (Module version) Default: false. // Examples(FlatSpin,VPD=175): // front_half() sphere(r=20); // front_half(y=5) sphere(r=20); @@ -327,13 +332,14 @@ function front_half(p,y=0) = half_of(p, FRONT, [0,y,0]); // // Description: // Slices an object at a vertical X-Z cut plane, and masks away everything that is in front of it. -// +// The s parameter is needed for the module +// version to control the size of the masking cube. If s is too large then the preview display will flip around and display the +// wrong half, but if it is too small it won't fully mask your model. // Arguments: // p = VNF, region or path to slice (function version) -// s = Mask size to use. Use a number larger than twice your object's largest axis. If you make this too large, OpenSCAD's preview rendering may be incorrect. Default: 100 +// s = Mask size to use. Use a number larger than twice your object's largest axis. If you make this too large, OpenSCAD's preview rendering may display the wrong half. (Module version) Default: 100 // y = The Y coordinate of the cut-plane. Default: 0 -// planar = If true perform a 2D operation. -// +// planar = If true, perform a 2D operation. (Module version) Default: false. // Examples: // back_half() sphere(r=20); // back_half(y=8) sphere(r=20); @@ -366,12 +372,13 @@ function back_half(p,y=0) = half_of(p, BACK, [0,y,0]); // // Description: // Slices an object at a horizontal X-Y cut plane, and masks away everything that is above it. -// +// The s parameter is needed for the module +// version to control the size of the masking cube. If s is too large then the preview display will flip around and display the +// wrong half, but if it is too small it won't fully mask your model. // Arguments: // p = VNF, region or path to slice (function version) -// s = Mask size to use. Use a number larger than twice your object's largest axis. If you make this too large, OpenSCAD's preview rendering may be incorrect. Default: 100 +// s = Mask size to use. Use a number larger than twice your object's largest axis. If you make this too large, OpenSCAD's preview rendering may display the wrong half. (Module version) Default: 100 // z = The Z coordinate of the cut-plane. Default: 0 -// // Examples: // bottom_half() sphere(r=20); // bottom_half(z=-10) sphere(r=20); @@ -397,12 +404,13 @@ function bottom_half(p,z=0) = half_of(p,BOTTOM,[0,0,z]); // // Description: // Slices an object at a horizontal X-Y cut plane, and masks away everything that is below it. -// +// The s parameter is needed for the module +// version to control the size of the masking cube. If s is too large then the preview display will flip around and display the +// wrong half, but if it is too small it won't fully mask your model. // Arguments: // p = VNF, region or path to slice (function version) -// s = Mask size to use. Use a number larger than twice your object's largest axis. If you make this too large, OpenSCAD's preview rendering may be incorrect. Default: 100 +// s = Mask size to use. Use a number larger than twice your object's largest axis. If you make this too large, OpenSCAD's preview rendering may display the wrong half. (Module version) Default: 100 // z = The Z coordinate of the cut-plane. Default: 0 -// // Examples(Spin,VPD=175): // top_half() sphere(r=20); // top_half(z=5) sphere(r=20);