This file provides some mathematical operations that apply to each entry in a vector. It provides normalization and angle computation, and it provides functions for searching lists of vectors for matches to a given vector.

To use, add the following lines to the beginning of your file:

include <BOSL2/std.scad>

1. Section: Vector Testing

   • is_vector() – Returns true if the given value is a vector.

2. Section: Scalar operations on vectors

   • add_scalar() – Adds a scalar value to every item in a vector.
   • v_mul() – Returns the element-wise multiplication of two equal-length vectors.
   • v_div() – Returns the element-wise division of two equal-length vectors.
   • v_abs() – Returns the absolute values of the given vector.
   • v_floor() – Returns the values of the given vector, rounded down.
   • v_ceil() – Returns the values of the given vector, rounded up.
   • v_lookup() – Like lookup(), but it can interpolate between vector results.

3. Section: Vector Properties

   • unit() – Returns the unit length of a given vector.
   • v_theta() – Returns the angle counter-clockwise from X+ on the XY plane.
   • vector_angle() – Returns the minor angle between two vectors.
   • vector_axis() – Returns the perpendicular axis between two vectors.
   • vector_bisect() – Returns the vector that bisects two vectors.

4. Section: Vector Searching

   • pointlist_bounds() – Returns the min and max bounding coordinates for the given list of points.
   • closest_point() – Finds the closest point in a list of points.
   • furthest_point() – Finds the furthest point in a list of points.
   • vector_search() – Finds points in a list that are close to a given point.
   • vector_search_tree() – Makes a distance search tree for a list of points.
   • vector_nearest() – Finds the k nearest points in a list to a given point.

Synopsis: Returns true if the given value is a vector.

Topics: Vectors, Math

See Also: is_matrix(), is_path(), is_region()

Usage:

• bool = is_vector(v, [length], [zero=], [all_nonzero=], [eps=]);

Description:

Returns true if v is a list of finite numbers.

Arguments:

Example 1:

include <BOSL2/std.scad>
is_vector(4);                          // Returns false
is_vector([4,true,false]);             // Returns false
is_vector([3,4,INF,5]);                // Returns false
is_vector([3,4,5,6]);                  // Returns true
is_vector([3,4,undef,5]);              // Returns false
is_vector([3,4,5],3);                  // Returns true
is_vector([3,4,5],4);                  // Returns true
is_vector([]);                         // Returns false
is_vector([0,4,0],3,zero=false);       // Returns true
is_vector([0,0,0],zero=false);         // Returns false
is_vector([0,0,1e-12],zero=false);     // Returns false
is_vector([0,1,0],all_nonzero=false);  // Returns false
is_vector([1,1,1],all_nonzero=false);  // Returns true
is_vector([],zero=false);              // Returns false

Synopsis: Adds a scalar value to every item in a vector.

Topics: Vectors, Math

See Also: v_mul(), v_div()

Usage:

• v_new = add_scalar(v, s);

Description:

Given a vector and a scalar, returns the vector with the scalar added to each item in it.

Arguments:

Example 1:

include <BOSL2/std.scad>
a = add_scalar([1,2,3],3);            // Returns: [4,5,6]

Synopsis: Returns the element-wise multiplication of two equal-length vectors.

Topics: Vectors, Math

See Also: add_scalar(), v_div()

Usage:

• v3 = v_mul(v1, v2);

Description:

Element-wise multiplication. Multiplies each element of v1 by the corresponding element of v2. Both v1 and v2 must be the same length. Returns a vector of the products. Note that the items in v1 and v2 can be anything that OpenSCAD will multiply.

Arguments:

Example 1:

include <BOSL2/std.scad>
v_mul([3,4,5], [8,7,6]);  // Returns [24, 28, 30]

Synopsis: Returns the element-wise division of two equal-length vectors.

Topics: Vectors, Math

See Also: add_scalar(), v_mul()

Usage:

• v3 = v_div(v1, v2);

Description:

Element-wise vector division. Divides each element of vector v1 by the corresponding element of vector v2. Returns a vector of the quotients.

Arguments:

Example 1:

include <BOSL2/std.scad>
v_div([24,28,30], [8,7,6]);  // Returns [3, 4, 5]

Synopsis: Returns the absolute values of the given vector.

Topics: Vectors, Math

See Also: v_floor(), v_ceil()

Usage:

• v2 = v_abs(v);

Description:

Returns a vector of the absolute value of each element of vector v.

Arguments:

Example 1:

include <BOSL2/std.scad>
v_abs([-1,3,-9]);  // Returns: [1,3,9]

Synopsis: Returns the values of the given vector, rounded down.

Topics: Vectors, Math

See Also: v_abs(), v_ceil()

Usage:

• v2 = v_floor(v);

Description:

Returns the given vector after performing a floor() on all items.

Synopsis: Returns the values of the given vector, rounded up.

Topics: Vectors, Math

See Also: v_abs(), v_floor()

Usage:

• v2 = v_ceil(v);

Description:

Returns the given vector after performing a ceil() on all items.

Synopsis: Like lookup(), but it can interpolate between vector results.

Topics: Vectors, Math

See Also: v_abs(), v_floor(), v_ceil()

Usage:

• v2 = v_lookup(x, v);

Description:

Works just like the built-in function lookup(), except that it can also interpolate between vector result values of the same length.

Arguments:

Example 1:

include <BOSL2/std.scad>
x = v_lookup(4.5, [[4, [3,4,5]], [5, [5,6,7]]]);  // Returns: [4,5,6]

Synopsis: Returns the unit length of a given vector.

Topics: Vectors, Math

See Also: v_abs(), v_floor(), v_ceil()

Usage:

• v = unit(v, [error]);

Description:

Returns the unit length normalized version of vector v. If passed a zero-length vector, asserts an error unless error is given, in which case the value of error is returned.

Arguments:

Example 1:

include <BOSL2/std.scad>
v1 = unit([10,0,0]);   // Returns: [1,0,0]
v2 = unit([0,10,0]);   // Returns: [0,1,0]
v3 = unit([0,0,10]);   // Returns: [0,0,1]
v4 = unit([0,-10,0]);  // Returns: [0,-1,0]
v5 = unit([0,0,0],[1,2,3]);    // Returns: [1,2,3]
v6 = unit([0,0,0]);    // Asserts an error.

Synopsis: Returns the angle counter-clockwise from X+ on the XY plane.

Topics: Vectors, Math

See Also: unit()

Usage:

• theta = v_theta([X,Y]);

Description:

Given a vector, returns the angle in degrees counter-clockwise from X+ on the XY plane.

Synopsis: Returns the minor angle between two vectors.

Topics: Vectors, Math

See Also: unit(), v_theta()

Usage:

• ang = vector_angle(v1,v2);
• ang = vector_angle([v1,v2]);
• ang = vector_angle(PT1,PT2,PT3);
• ang = vector_angle([PT1,PT2,PT3]);

Description:

If given a single list of two vectors, like vector_angle([V1,V2]), returns the angle between the two vectors V1 and V2. If given a single list of three points, like vector_angle([A,B,C]), returns the angle between the line segments AB and BC. If given two vectors, like vector_angle(V1,V2), returns the angle between the two vectors V1 and V2. If given three points, like vector_angle(A,B,C), returns the angle between the line segments AB and BC.

Arguments:

Example 1:

include <BOSL2/std.scad>
ang1 = vector_angle(UP,LEFT);     // Returns: 90
ang2 = vector_angle(RIGHT,LEFT);  // Returns: 180
ang3 = vector_angle(UP+RIGHT,RIGHT);  // Returns: 45
ang4 = vector_angle([10,10], [0,0], [10,-10]);  // Returns: 90
ang5 = vector_angle([10,0,10], [0,0,0], [-10,10,0]);  // Returns: 120
ang6 = vector_angle([[10,0,10], [0,0,0], [-10,10,0]]);  // Returns: 120

Synopsis: Returns the perpendicular axis between two vectors.

Topics: Vectors, Math

See Also: unit(), v_theta(), vector_angle()

Usage:

• axis = vector_axis(v1,v2);
• axis = vector_axis([v1,v2]);
• axis = vector_axis(PT1,PT2,PT3);
• axis = vector_axis([PT1,PT2,PT3]);

Description:

If given a single list of two vectors, like vector_axis([V1,V2]), returns the vector perpendicular the two vectors V1 and V2. If given a single list of three points, like vector_axis([A,B,C]), returns the vector perpendicular to the plane through a, B and C. If given two vectors, like vector_axis(V1,V2), returns the vector perpendicular to the two vectors V1 and V2. If given three points, like vector_axis(A,B,C), returns the vector perpendicular to the plane through a, B and C.

Arguments:

Example 1:

include <BOSL2/std.scad>
axis1 = vector_axis(UP,LEFT);     // Returns: [0,-1,0] (FWD)
axis2 = vector_axis(RIGHT,LEFT);  // Returns: [0,-1,0] (FWD)
axis3 = vector_axis(UP+RIGHT,RIGHT);  // Returns: [0,1,0] (BACK)
axis4 = vector_axis([10,10], [0,0], [10,-10]);  // Returns: [0,0,-1] (DOWN)
axis5 = vector_axis([10,0,10], [0,0,0], [-10,10,0]);  // Returns: [-0.57735, -0.57735, 0.57735]
axis6 = vector_axis([[10,0,10], [0,0,0], [-10,10,0]]);  // Returns: [-0.57735, -0.57735, 0.57735]

Synopsis: Returns the vector that bisects two vectors.

Topics: Vectors, Math

See Also: unit(), v_theta(), vector_angle(), vector_axis()

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.

Synopsis: Returns the min and max bounding coordinates for the given list of points.

Topics: Geometry, Bounding Boxes, Bounds

See Also: closest_point()

Usage:

• pt_pair = pointlist_bounds(pts);

Description:

Finds the bounds containing all the points in pts which can be a list of points in any dimension. Returns a list of two items: a list of the minimums and a list of the maximums. For example, with 3d points [[MINX, MINY, MINZ], [MAXX, MAXY, MAXZ]]

Arguments:

Synopsis: Finds the closest point in a list of points.

Topics: Geometry, Points, Distance

See Also: pointlist_bounds(), furthest_point()

Usage:

• index = closest_point(pt, points);

Description:

Given a list of points, finds the index of the closest point to pt.

Arguments:

Synopsis: Finds the furthest point in a list of points.

Topics: Geometry, Points, Distance

See Also: pointlist_bounds(), closest_point()

Usage:

• index = furthest_point(pt, points);

Description:

Given a list of points, finds the index of the furthest point from pt.

Arguments:

Synopsis: Finds points in a list that are close to a given point.

Topics: Search, Points, Closest

See Also: vector_search_tree(), vector_nearest()

Usage:

• indices = vector_search(query, r, target);

Description:

Given a list of query points query and a target to search, finds the points in target that match each query point. A match holds when the distance between a point in target and a query point is less than or equal to r. The returned list will have a list for each query point containing, in arbitrary order, the indices of all points that match that query point. The target may be a simple list of points or a search tree. When target is a large list of points, a search tree is constructed to speed up the search with an order around O(log n) per query point. For small point lists, a direct search is done dispensing a tree construction. Alternatively, target may be a search tree built with vector_search_tree(). In that case, that tree is parsed looking for matches. An empty list of query points will return a empty output list. An empty list of target points will return a output list with an empty list for each query point.

Arguments:

Example 1: A set of four queries to find points within 1 unit of the query. The circles show the search region and all have radius 1.

include <BOSL2/std.scad>
$fn=32;
k = 2000;
points = list_to_matrix(rands(0,10,k*2,seed=13333),2);
queries = [for(i=[3,7],j=[3,7]) [i,j]];
search_ind = vector_search(queries, points, 1);
move_copies(points) circle(r=.08);
for(i=idx(queries)){
    color("blue")stroke(move(queries[i],circle(r=1)), closed=true, width=.08);
    color("red") move_copies(select(points, search_ind[i])) circle(r=.08);
}

Example 2: when a series of searches with different radius are needed, its is faster to pre-compute the tree

include <BOSL2/std.scad>
$fn=32;
k = 2000;
points = list_to_matrix(rands(0,10,k*2),2,seed=13333);
queries1 = [for(i=[3,7]) [i,i]];
queries2 = [for(i=[3,7]) [10-i,i]];
r1 = 1;
r2 = .7;
search_tree = vector_search_tree(points);
search_1 = vector_search(queries1, r1, search_tree);
search_2 = vector_search(queries2, r2, search_tree);
move_copies(points) circle(r=.08);
for(i=idx(queries1)){
    color("blue")stroke(move(queries1[i],circle(r=r1)), closed=true, width=.08);
    color("red") move_copies(select(points, search_1[i])) circle(r=.08);
}
for(i=idx(queries2)){
    color("green")stroke(move(queries2[i],circle(r=r2)), closed=true, width=.08);
    color("red") move_copies(select(points, search_2[i])) circle(r=.08);
}

Synopsis: Makes a distance search tree for a list of points.

Topics: Search, Points, Closest

See Also: vector_nearest(), vector_search()

Usage:

• tree = vector_search_tree(points,leafsize);

Description:

Construct a search tree for the given list of points to be used as input to the function vector_search(). The use of a tree speeds up the search process. The tree construction stops branching when a tree node represents a number of points less or equal to leafsize. Search trees are ball trees. Constructing the tree should be O(n log n) and searches should be O(log n), though real life performance depends on how the data is distributed, and it will deteriorate for high data dimensions. This data structure is useful when you will be performing many searches of the same data, so that the cost of constructing the tree is justified. (See https://en.wikipedia.org/wiki/Ball_tree) For a small lists of points, the search with a tree may be more expensive than direct comparisons. The argument treemin sets the minimum length of point set for which a tree search will be done by vector_search. For an empty list of points it returns an empty list.

Arguments:

Example 1: A set of four queries to find points within 1 unit of the query. The circles show the search region and all have radius 1.

include <BOSL2/std.scad>
$fn=32;
k = 2000;
points = random_points(k, scale=10, dim=2,seed=13333);
queries = [for(i=[3,7],j=[3,7]) [i,j]];
search_tree = vector_search_tree(points);
search_ind = vector_search(queries,1,search_tree);
move_copies(points) circle(r=.08);
for(i=idx(queries)){
    color("blue") stroke(move(queries[i],circle(r=1)), closed=true, width=.08);
    color("red")  move_copies(select(points, search_ind[i])) circle(r=.08);
}

Synopsis: Finds the k nearest points in a list to a given point.

Topics: Search, Points, Closest

See Also: vector_search(), vector_search_tree()

Usage:

• indices = vector_nearest(query, k, target);

Description:

Search target for the k points closest to point query. The input target is either a list of points to search or a search tree pre-computed by `vector_search_tree(). A list is returned containing the indices of the points found in sorted order, closest point first.

Arguments:

Example 1: Four queries to find the 15 nearest points. The circles show the radius defined by the most distant query result. Note they are different for each query.

include <BOSL2/std.scad>
$fn=32;
k = 1000;
points = list_to_matrix(rands(0,10,k*2,seed=13333),2);
tree = vector_search_tree(points);
queries = [for(i=[3,7],j=[3,7]) [i,j]];
search_ind = [for(q=queries) vector_nearest(q, 15, tree)];
move_copies(points) circle(r=.08);
for(i=idx(queries)){
    circle = circle(r=norm(points[last(search_ind[i])]-queries[i]));
    color("red")  move_copies(select(points, search_ind[i])) circle(r=.08);
    color("blue") stroke(move(queries[i], circle), closed=true, width=.08);
}