diff --git a/geometry.scad b/geometry.scad index 0221a2b..3e3c05b 100644 --- a/geometry.scad +++ b/geometry.scad @@ -10,7 +10,8 @@ // Function: point_on_segment2d() // Usage: -// point_on_segment2d(point, edge); +// pt = point_on_segment2d(point, edge); +// Topics: Geometry, Points, Segments // Description: // Determine if the point is on the line segment between two points. // Returns true if yes, and false if not. @@ -45,7 +46,8 @@ function _valid_plane(p, eps=EPSILON) = is_vector(p,4) && ! approx(norm(p),0,eps // Function: point_left_of_line2d() // Usage: -// point_left_of_line2d(point, line); +// pt = point_left_of_line2d(point, line); +// Topics: Geometry, Points, Lines // Description: // Return >0 if point is left of the line defined by `line`. // Return =0 if point is on the line. @@ -60,7 +62,8 @@ function point_left_of_line2d(point, line) = // Function: collinear() // Usage: -// collinear(a, [b, c], [eps]); +// test = collinear(a, [b, c], [eps]); +// Topics: Geometry, Points, Collinearity // Description: // Returns true if the points `a`, `b` and `c` are co-linear or if the list of points `a` is collinear. // Arguments: @@ -80,7 +83,8 @@ function collinear(a, b, c, eps=EPSILON) = // Function: point_line_distance() // Usage: -// point_line_distance(line, pt); +// pt = point_line_distance(line, pt); +// Topics: Geometry, Points, Lines, Distance // Description: // Finds the perpendicular distance of a point `pt` from the line `line`. // Arguments: @@ -97,6 +101,7 @@ function point_line_distance(pt, line) = // Function: point_segment_distance() // Usage: // dist = point_segment_distance(pt, seg); +// Topics: Geometry, Points, Segments, Distance // Description: // Returns the closest distance of the given point to the given line segment. // Arguments: @@ -115,6 +120,8 @@ function point_segment_distance(pt, seg) = // Function: segment_distance() // Usage: // dist = segment_distance(seg1, seg2); +// Topics: Geometry, Segments, Distance +// See Also: convex_collision(), convex_distance() // Description: // Returns the closest distance of the two given line segments. // Arguments: @@ -131,8 +138,9 @@ function segment_distance(seg1, seg2) = // Function: line_normal() // Usage: -// line_normal([P1,P2]) -// line_normal(p1,p2) +// vec = line_normal([P1,P2]) +// vec = line_normal(p1,p2) +// Topics: Geometry, Lines // Description: // Returns the 2D normal vector to the given 2D line. This is otherwise known as the perpendicular vector counter-clockwise to the given ray. // Arguments: @@ -172,7 +180,8 @@ function _general_line_intersection(s1,s2,eps=EPSILON) = // Function: line_intersection() // Usage: -// line_intersection(l1, l2); +// pt = line_intersection(l1, l2); +// Topics: Geometry, Lines, Intersections // Description: // Returns the 2D intersection point of two unbounded 2D lines. // Returns `undef` if the lines are parallel. @@ -190,7 +199,8 @@ function line_intersection(l1,l2,eps=EPSILON) = // Function: line_ray_intersection() // Usage: -// line_ray_intersection(line, ray); +// pt = line_ray_intersection(line, ray); +// Topics: Geometry, Lines, Rays, Intersections // Description: // Returns the 2D intersection point of an unbounded 2D line, and a half-bounded 2D ray. // Returns `undef` if they do not intersect. @@ -210,7 +220,8 @@ function line_ray_intersection(line,ray,eps=EPSILON) = // Function: line_segment_intersection() // Usage: -// line_segment_intersection(line, segment); +// pt = line_segment_intersection(line, segment); +// Topics: Geometry, Lines, Segments, Intersections // Description: // Returns the 2D intersection point of an unbounded 2D line, and a bounded 2D line segment. // Returns `undef` if they do not intersect. @@ -231,7 +242,8 @@ function line_segment_intersection(line,segment,eps=EPSILON) = // Function: ray_intersection() // Usage: -// ray_intersection(s1, s2); +// pt = ray_intersection(s1, s2); +// Topics: Geometry, Lines, Rays, Intersections // Description: // Returns the 2D intersection point of two 2D line rays. // Returns `undef` if they do not intersect. @@ -251,7 +263,8 @@ function ray_intersection(r1,r2,eps=EPSILON) = // Function: ray_segment_intersection() // Usage: -// ray_segment_intersection(ray, segment); +// pt = ray_segment_intersection(ray, segment); +// Topics: Geometry, Rays, Segments, Intersections // Description: // Returns the 2D intersection point of a half-bounded 2D ray, and a bounded 2D line segment. // Returns `undef` if they do not intersect. @@ -272,7 +285,8 @@ function ray_segment_intersection(ray,segment,eps=EPSILON) = // Function: segment_intersection() // Usage: -// segment_intersection(s1, s2); +// pt = segment_intersection(s1, s2); +// Topics: Geometry, Segments, Intersections // Description: // Returns the 2D intersection point of two 2D line segments. // Returns `undef` if they do not intersect. @@ -293,7 +307,8 @@ function segment_intersection(s1,s2,eps=EPSILON) = // Function: line_closest_point() // Usage: -// line_closest_point(line,pt); +// pt = line_closest_point(line,pt); +// Topics: Geometry, Lines, Distance // Description: // Returns the point on the given 2D or 3D `line` that is closest to the given point `pt`. // The `line` and `pt` args should either both be 2D or both 3D. @@ -351,7 +366,8 @@ function line_closest_point(line,pt) = // Function: ray_closest_point() // Usage: -// ray_closest_point(seg,pt); +// pt = ray_closest_point(seg,pt); +// Topics: Geometry, Rays, Distance // Description: // Returns the point on the given 2D or 3D ray `ray` that is closest to the given point `pt`. // The `ray` and `pt` args should either both be 2D or both 3D. @@ -414,7 +430,8 @@ function ray_closest_point(ray,pt) = // Function: segment_closest_point() // Usage: -// segment_closest_point(seg,pt); +// pt = segment_closest_point(seg,pt); +// Topics: Geometry, Segments, Distance // Description: // Returns the point on the given 2D or 3D line segment `seg` that is closest to the given point `pt`. // The `seg` and `pt` args should either both be 2D or both 3D. @@ -471,7 +488,8 @@ function segment_closest_point(seg,pt) = // Function: line_from_points() // Usage: -// line_from_points(points, [fast], [eps]); +// line = line_from_points(points, [fast], [eps]); +// Topics: Geometry, Lines, Points // Description: // Given a list of 2 or more collinear points, returns a line containing them. // If `fast` is false and the points are coincident or non-collinear, then `undef` is returned. @@ -496,6 +514,7 @@ function line_from_points(points, fast=false, eps=EPSILON) = // Usage: // C = law_of_cosines(a, b, c); // c = law_of_cosines(a, b, C); +// Topics: Geometry, Triangles // Description: // Applies the Law of Cosines for an arbitrary triangle. Given three side lengths, returns the // angle in degrees for the corner opposite of the third side. Given two side lengths, and the @@ -529,6 +548,7 @@ function law_of_cosines(a, b, c, C) = // Usage: // B = law_of_sines(a, A, b); // b = law_of_sines(a, A, B); +// Topics: Geometry, Triangles // Description: // Applies the Law of Sines for an arbitrary triangle. Given two triangle side lengths and the // angle between them, returns the angle of the corner opposite of the second side. Given a side @@ -561,7 +581,8 @@ function law_of_sines(a, A, b, B) = // Function: tri_calc() // Usage: -// tri_calc(ang,ang2,adj,opp,hyp); +// triangle = tri_calc(ang,ang2,adj,opp,hyp); +// Topics: Geometry, Triangles // Description: // Given a side length and an angle, or two side lengths, calculates the rest of the side lengths // and angles of a right triangle. Returns [ADJACENT, OPPOSITE, HYPOTENUSE, ANGLE, ANGLE2] where @@ -633,6 +654,7 @@ function tri_calc(ang,ang2,adj,opp,hyp) = // Function: hyp_opp_to_adj() // Usage: // adj = hyp_opp_to_adj(hyp,opp); +// Topics: Geometry, Triangles // Description: // Given the lengths of the hypotenuse and opposite side of a right triangle, returns the length // of the adjacent side. @@ -650,6 +672,7 @@ function hyp_opp_to_adj(hyp,opp) = // Function: hyp_ang_to_adj() // Usage: // adj = hyp_ang_to_adj(hyp,ang); +// Topics: Geometry, Triangles // Description: // Given the length of the hypotenuse and the angle of the primary corner of a right triangle, // returns the length of the adjacent side. @@ -667,6 +690,7 @@ function hyp_ang_to_adj(hyp,ang) = // Function: opp_ang_to_adj() // Usage: // adj = opp_ang_to_adj(opp,ang); +// Topics: Geometry, Triangles // Description: // Given the angle of the primary corner of a right triangle, and the length of the side opposite of it, // returns the length of the adjacent side. @@ -684,6 +708,7 @@ function opp_ang_to_adj(opp,ang) = // Function: hyp_adj_to_opp() // Usage: // opp = hyp_adj_to_opp(hyp,adj); +// Topics: Geometry, Triangles // Description: // Given the length of the hypotenuse and the adjacent side, returns the length of the opposite side. // Arguments: @@ -700,6 +725,7 @@ function hyp_adj_to_opp(hyp,adj) = // Function: hyp_ang_to_opp() // Usage: // opp = hyp_ang_to_opp(hyp,adj); +// Topics: Geometry, Triangles // Description: // Given the length of the hypotenuse of a right triangle, and the angle of the corner, returns the length of the opposite side. // Arguments: @@ -716,6 +742,7 @@ function hyp_ang_to_opp(hyp,ang) = // Function: adj_ang_to_opp() // Usage: // opp = adj_ang_to_opp(adj,ang); +// Topics: Geometry, Triangles // Description: // Given the length of the adjacent side of a right triangle, and the angle of the corner, returns the length of the opposite side. // Arguments: @@ -732,6 +759,7 @@ function adj_ang_to_opp(adj,ang) = // Function: adj_opp_to_hyp() // Usage: // hyp = adj_opp_to_hyp(adj,opp); +// Topics: Geometry, Triangles // Description: // Given the length of the adjacent and opposite sides of a right triangle, returns the length of thee hypotenuse. // Arguments: @@ -748,6 +776,7 @@ function adj_opp_to_hyp(adj,opp) = // Function: adj_ang_to_hyp() // Usage: // hyp = adj_ang_to_hyp(adj,ang); +// Topics: Geometry, Triangles // Description: // For a right triangle, given the length of the adjacent side, and the corner angle, returns the length of the hypotenuse. // Arguments: @@ -764,6 +793,7 @@ function adj_ang_to_hyp(adj,ang) = // Function: opp_ang_to_hyp() // Usage: // hyp = opp_ang_to_hyp(opp,ang); +// Topics: Geometry, Triangles // Description: // For a right triangle, given the length of the opposite side, and the corner angle, returns the length of the hypotenuse. // Arguments: @@ -796,6 +826,7 @@ function hyp_adj_to_ang(hyp,adj) = // Function: hyp_opp_to_ang() // Usage: // ang = hyp_opp_to_ang(hyp,opp); +// Topics: Geometry, Triangles // Description: // For a right triangle, given the lengths of the hypotenuse and the opposite sides, returns the angle of the corner. // Arguments: @@ -812,6 +843,7 @@ function hyp_opp_to_ang(hyp,opp) = // Function: adj_opp_to_ang() // Usage: // ang = adj_opp_to_ang(adj,opp); +// Topics: Geometry, Triangles // Description: // For a right triangle, given the lengths of the adjacent and opposite sides, returns the angle of the corner. // Arguments: @@ -827,7 +859,8 @@ function adj_opp_to_ang(adj,opp) = // Function: triangle_area() // Usage: -// triangle_area(a,b,c); +// area = triangle_area(a,b,c); +// Topics: Geometry, Triangles, Area // Description: // Returns the area of a triangle formed between three 2D or 3D vertices. // Result will be negative if the points are 2D and in clockwise order. @@ -851,7 +884,8 @@ function triangle_area(a,b,c) = // Function: plane3pt() // Usage: -// plane3pt(p1, p2, p3); +// plane = plane3pt(p1, p2, p3); +// Topics: Geometry, Planes // Description: // Generates the normalized cartesian equation of a plane from three 3d points. // Returns [A,B,C,D] where Ax + By + Cz = D is the equation of a plane. @@ -873,7 +907,8 @@ function plane3pt(p1, p2, p3) = // Function: plane3pt_indexed() // Usage: -// plane3pt_indexed(points, i1, i2, i3); +// plane = plane3pt_indexed(points, i1, i2, i3); +// Topics: Geometry, Planes // Description: // Given a list of 3d points, and the indices of three of those points, // generates the normalized cartesian equation of a plane that those points all @@ -899,7 +934,8 @@ function plane3pt_indexed(points, i1, i2, i3) = // Function: plane_from_normal() // Usage: -// plane_from_normal(normal, [pt]) +// plane = plane_from_normal(normal, [pt]) +// Topics: Geometry, Planes // Description: // Returns a plane defined by a normal vector and a point. // Arguments: @@ -957,7 +993,8 @@ function _covariance_evec_eval(points) = // Function: plane_from_points() // Usage: -// plane_from_points(points, , ); +// plane = plane_from_points(points, , ); +// Topics: Geometry, Planes, Points // Description: // Given a list of 3 or more coplanar 3D points, returns the coefficients of the normalized cartesian equation of a plane, // that is [A,B,C,D] where Ax+By+Cz=D is the equation of the plane and norm([A,B,C])=1. @@ -991,7 +1028,8 @@ function plane_from_points(points, fast=false, eps=EPSILON) = // Function: plane_from_polygon() // Usage: -// plane_from_polygon(points, [fast], [eps]); +// plane = plane_from_polygon(points, [fast], [eps]); +// Topics: Geometry, Planes, Polygons // Description: // Given a 3D planar polygon, returns the normalized cartesian equation of its plane. // Returns [A,B,C,D] where Ax+By+Cz=D is the equation of the plane where norm([A,B,C])=1. @@ -1020,7 +1058,8 @@ function plane_from_polygon(poly, fast=false, eps=EPSILON) = // Function: plane_normal() // Usage: -// plane_normal(plane); +// vec = plane_normal(plane); +// Topics: Geometry, Planes // Description: // Returns the unit length normal vector for the given plane. // Arguments: @@ -1033,6 +1072,7 @@ function plane_normal(plane) = // Function: plane_offset() // Usage: // d = plane_offset(plane); +// Topics: Geometry, Planes // Description: // Returns coeficient D of the normalized plane equation `Ax+By+Cz=D`, or the scalar offset of the plane from the origin. // This value may be negative. @@ -1048,6 +1088,7 @@ function plane_offset(plane) = // Function: projection_on_plane() // Usage: // pts = projection_on_plane(plane, points); +// Topics: Geometry, Planes, Projection // Description: // Given a plane definition `[A,B,C,D]`, where `Ax+By+Cz=D`, and a list of 2d or // 3d points, return the 3D orthogonal projection of the points on the plane. @@ -1083,6 +1124,7 @@ function projection_on_plane(plane, points) = // Function: plane_point_nearest_origin() // Usage: // pt = plane_point_nearest_origin(plane); +// Topics: Geometry, Planes, Distance // Description: // Returns the point on the plane that is closest to the origin. // Arguments: @@ -1094,7 +1136,8 @@ function plane_point_nearest_origin(plane) = // Function: point_plane_distance() // Usage: -// point_plane_distance(plane, point) +// dist = point_plane_distance(plane, point) +// Topics: Geometry, Planes, Distance // Description: // Given a plane as [A,B,C,D] where the cartesian equation for that plane // is Ax+By+Cz=D, determines how far from that plane the given point is. @@ -1130,6 +1173,7 @@ function _general_plane_line_intersection(plane, line, eps=EPSILON) = // Function: normalize_plane() // Usage: // nplane = normalize_plane(plane); +// Topics: Geometry, Planes // Description: // Returns a new representation [A,B,C,D] of `plane` where norm([A,B,C]) is equal to one. function normalize_plane(plane) = @@ -1140,6 +1184,7 @@ function normalize_plane(plane) = // Function: plane_line_angle() // Usage: // angle = plane_line_angle(plane,line); +// Topics: Geometry, Planes, Lines, Angle // Description: // Compute the angle between a plane [A, B, C, D] and a 3d line, specified as a pair of 3d points [p1,p2]. // The resulting angle is signed, with the sign positive if the vector p2-p1 lies on @@ -1159,6 +1204,7 @@ function plane_line_angle(plane, line) = // Function: plane_line_intersection() // Usage: // pt = plane_line_intersection(plane, line, [bounded], [eps]); +// Topics: Geometry, Planes, Lines, Intersection // Description: // Takes a line, and a plane [A,B,C,D] where the equation of that plane is `Ax+By+Cz=D`. // If `line` intersects `plane` at one point, then that intersection point is returned. @@ -1187,6 +1233,7 @@ function plane_line_intersection(plane, line, bounded=false, eps=EPSILON) = // Function: polygon_line_intersection() // Usage: // pt = polygon_line_intersection(poly, line, [bounded], [eps]); +// Topics: Geometry, Polygons, Lines, Intersection // Description: // Takes a possibly bounded line, and a 3D planar polygon, and finds their intersection point. // If the line and the polygon are on the same plane then returns a list, possibly empty, of 3D line @@ -1246,7 +1293,9 @@ function polygon_line_intersection(poly, line, bounded=false, eps=EPSILON) = // Function: plane_intersection() // Usage: -// plane_intersection(plane1, plane2, [plane3]) +// line = plane_intersection(plane1, plane2) +// pt = plane_intersection(plane1, plane2, plane3) +// Topics: Geometry, Planes, Intersection // Description: // Compute the point which is the intersection of the three planes, or the line intersection of two planes. // If you give three planes the intersection is returned as a point. If you give two planes the intersection @@ -1277,7 +1326,8 @@ function plane_intersection(plane1,plane2,plane3) = // Function: coplanar() // Usage: -// coplanar(points,); +// test = coplanar(points,); +// Topics: Geometry, Coplanarity // Description: // Returns true if the given 3D points are non-collinear and are on a plane. // Arguments: @@ -1304,7 +1354,8 @@ function _pointlist_greatest_distance(points,plane) = // Function: points_on_plane() // Usage: -// points_on_plane(points, plane, ); +// test = points_on_plane(points, plane, ); +// Topics: Geometry, Planes, Points // Description: // Returns true if the given 3D points are on the given plane. // Arguments: @@ -1320,7 +1371,8 @@ function points_on_plane(points, plane, eps=EPSILON) = // Function: in_front_of_plane() // Usage: -// in_front_of_plane(plane, point); +// test = in_front_of_plane(plane, point); +// Topics: Geometry, Planes // Description: // Given a plane as [A,B,C,D] where the cartesian equation for that plane // is Ax+By+Cz=D, determines if the given 3D point is on the side of that @@ -1339,6 +1391,7 @@ function in_front_of_plane(plane, point) = // Function&Module: circle_2tangents() // Usage: As Function // circ = circle_2tangents(pt1, pt2, pt3, r|d, ); +// Topics: Geometry, Circles, Tangents // Usage: As Module // circle_2tangents(pt1, pt2, pt3, r|d, ,
); // Description: @@ -1449,6 +1502,7 @@ module circle_2tangents(pt1, pt2, pt3, r, d, h, center=false) { // Usage: As Function // circ = circle_3points(pt1, pt2, pt3); // circ = circle_3points([pt1, pt2, pt3]); +// Topics: Geometry, Circles // Usage: As Module // circle_3points(pt1, pt2, pt3, ,
); // circle_3points([pt1, pt2, pt3], ,
); @@ -1527,6 +1581,7 @@ module circle_3points(pt1, pt2, pt3, h, center=false) { // Function: circle_point_tangents() // Usage: // tangents = circle_point_tangents(r|d, cp, pt); +// Topics: Geometry, Circles, Tangents // Description: // Given a 2d circle and a 2d point outside that circle, finds the 2d tangent point(s) on the circle for a // line passing through the point. Returns a list of zero or more 2D tangent points. @@ -1561,6 +1616,7 @@ function circle_point_tangents(r, d, cp, pt) = // Function: circle_circle_tangents() // Usage: // segs = circle_circle_tangents(c1, r1|d1, c2, r2|d2); +// Topics: Geometry, Circles, Tangents // Description: // Computes 2d lines tangents to a pair of circles in 2d. Returns a list of line endpoints [p1,p2] where // p2 is the tangent point on circle 1 and p2 is the tangent point on circle 2. @@ -1643,6 +1699,7 @@ function circle_circle_tangents(c1,r1,c2,r2,d1,d2) = // Function: circle_line_intersection() // Usage: // isect = circle_line_intersection(c,,,,); +// Topics: Geometry, Circles, Lines, Intersection // Description: // Find intersection points between a 2d circle and a line, ray or segment specified by two points. // By default the line is unbounded. @@ -1683,7 +1740,8 @@ function circle_line_intersection(c,r,d,line,bounded=false,eps=EPSILON) = // Function: noncollinear_triple() // Usage: -// noncollinear_triple(points); +// test = noncollinear_triple(points); +// Topics: Geometry, Noncollinearity // Description: // Finds the indices of three good non-collinear points from the pointlist `points`. // If all points are collinear returns [] when `error=true` or an error otherwise . @@ -1715,7 +1773,8 @@ function noncollinear_triple(points,error=true,eps=EPSILON) = // Function: pointlist_bounds() // Usage: -// pointlist_bounds(pts); +// pt_pair = pointlist_bounds(pts); +// Topics: Geometry, Bounding Boxes, Bounds // 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 @@ -1734,7 +1793,8 @@ function pointlist_bounds(pts) = // Function: closest_point() // Usage: -// closest_point(pt, points); +// index = closest_point(pt, points); +// Topics: Geometry, Points, Distance // Description: // Given a list of `points`, finds the index of the closest point to `pt`. // Arguments: @@ -1748,7 +1808,8 @@ function closest_point(pt, points) = // Function: furthest_point() // Usage: -// furthest_point(pt, points); +// index = furthest_point(pt, points); +// Topics: Geometry, Points, Distance // Description: // Given a list of `points`, finds the index of the furthest point from `pt`. // Arguments: @@ -1766,6 +1827,7 @@ function furthest_point(pt, points) = // Function: polygon_area() // Usage: // area = polygon_area(poly); +// Topics: Geometry, Polygons, Area // Description: // Given a 2D or 3D planar polygon, returns the area of that polygon. // If the polygon is self-crossing, the results are undefined. For non-planar 3D polygon the result is `undef`. @@ -1784,16 +1846,17 @@ function polygon_area(poly, signed=false) = let( n = plane_normal(plane), total = - sum([ for(i=[1:1:len(poly)-2]) - cross(poly[i]-poly[0], poly[i+1]-poly[0]) - ]) * n/2 + sum([ for(i=[1:1:len(poly)-2]) + cross(poly[i]-poly[0], poly[i+1]-poly[0]) + ]) * n/2 ) signed ? total : abs(total); // Function: polygon_shift() // Usage: -// polygon_shift(poly, i); +// newpoly = polygon_shift(poly, i); +// Topics: Geometry, Polygons // Description: // Given a polygon `poly`, rotates the point ordering so that the first point in the polygon path is the one at index `i`. // Arguments: @@ -1808,7 +1871,8 @@ function polygon_shift(poly, i) = // Function: polygon_shift_to_closest_point() // Usage: -// polygon_shift_to_closest_point(path, pt); +// newpoly = polygon_shift_to_closest_point(path, pt); +// Topics: Geometry, Polygons // Description: // Given a polygon `poly`, rotates the point ordering so that the first point in the path is the one closest to the given point `pt`. // Arguments: @@ -1827,6 +1891,7 @@ function polygon_shift_to_closest_point(poly, pt) = // Function: reindex_polygon() // Usage: // newpoly = reindex_polygon(reference, poly); +// Topics: Geometry, Polygons // Description: // Rotates and possibly reverses the point order of a 2d or 3d polygon path to optimize its pairwise point // association with a reference polygon. The two polygons must have the same number of vertices and be the same dimension. @@ -1877,6 +1942,7 @@ function reindex_polygon(reference, poly, return_error=false) = // Function: align_polygon() // Usage: // newpoly = align_polygon(reference, poly, angles, ); +// Topics: Geometry, Polygons // Description: // Tries the list or range of angles to find a rotation of the specified 2D polygon that best aligns // with the reference 2D polygon. For each angle, the polygon is reindexed, which is a costly operation @@ -1913,7 +1979,8 @@ function align_polygon(reference, poly, angles, cp) = // Function: centroid() // Usage: -// cp = centroid(poly); +// cpt = centroid(poly); +// Topics: Geometry, Polygons, Centroid // Description: // Given a simple 2D polygon, returns the 2D coordinates of the polygon's centroid. // Given a simple 3D planar polygon, returns the 3D coordinates of the polygon's centroid. @@ -1948,7 +2015,8 @@ function centroid(poly, eps=EPSILON) = // Function: point_in_polygon() // Usage: -// point_in_polygon(point, poly, ) +// test = point_in_polygon(point, poly, ) +// Topics: Geometry, Polygons // Description: // This function tests whether the given 2D point is inside, outside or on the boundary of // the specified 2D polygon using either the Nonzero Winding rule or the Even-Odd rule. @@ -2008,7 +2076,8 @@ function point_in_polygon(point, poly, nonzero=true, eps=EPSILON) = // Function: polygon_is_clockwise() // Usage: -// polygon_is_clockwise(poly); +// test = polygon_is_clockwise(poly); +// Topics: Geometry, Polygons, Clockwise // Description: // Return true if the given 2D simple polygon is in clockwise order, false otherwise. // Results for complex (self-intersecting) polygon are indeterminate. @@ -2021,7 +2090,8 @@ function polygon_is_clockwise(poly) = // Function: clockwise_polygon() // Usage: -// clockwise_polygon(poly); +// newpoly = clockwise_polygon(poly); +// Topics: Geometry, Polygons, Clockwise // Description: // Given a 2D polygon path, returns the clockwise winding version of that path. // Arguments: @@ -2033,7 +2103,8 @@ function clockwise_polygon(poly) = // Function: ccw_polygon() // Usage: -// ccw_polygon(poly); +// newpoly = ccw_polygon(poly); +// Topics: Geometry, Polygons, Clockwise // Description: // Given a 2D polygon poly, returns the counter-clockwise winding version of that poly. // Arguments: @@ -2045,7 +2116,8 @@ function ccw_polygon(poly) = // Function: reverse_polygon() // Usage: -// reverse_polygon(poly) +// newpoly = reverse_polygon(poly) +// Topics: Geometry, Polygons, Clockwise // Description: // Reverses a polygon's winding direction, while still using the same start point. // Arguments: @@ -2057,7 +2129,8 @@ function reverse_polygon(poly) = // Function: polygon_normal() // Usage: -// n = polygon_normal(poly); +// vec = polygon_normal(poly); +// Topics: Geometry, Polygons // Description: // Given a 3D planar polygon, returns a unit-length normal vector for the // clockwise orientation of the polygon. If the polygon points are collinear, returns `undef`. @@ -2165,6 +2238,7 @@ function _split_polygon_at_z(poly, z) = // Function: split_polygons_at_each_x() // Usage: // splitpolys = split_polygons_at_each_x(polys, xs); +// Topics: Geometry, Polygons, Intersections // Description: // Given a list of 3D polygons, splits all of them wherever they cross any X value given in `xs`. // Arguments: @@ -2185,6 +2259,7 @@ function split_polygons_at_each_x(polys, xs, _i=0) = // Function: split_polygons_at_each_y() // Usage: // splitpolys = split_polygons_at_each_y(polys, ys); +// Topics: Geometry, Polygons, Intersections // Description: // Given a list of 3D polygons, splits all of them wherever they cross any Y value given in `ys`. // Arguments: @@ -2205,6 +2280,7 @@ function split_polygons_at_each_y(polys, ys, _i=0) = // Function: split_polygons_at_each_z() // Usage: // splitpolys = split_polygons_at_each_z(polys, zs); +// Topics: Geometry, Polygons, Intersections // Description: // Given a list of 3D polygons, splits all of them wherever they cross any Z value given in `zs`. // Arguments: @@ -2228,7 +2304,8 @@ function split_polygons_at_each_z(polys, zs, _i=0) = // Function: is_convex_polygon() // Usage: -// is_convex_polygon(poly); +// test = is_convex_polygon(poly); +// Topics: Geometry, Convexity, Test // Description: // Returns true if the given 2D or 3D polygon is convex. // The result is meaningless if the polygon is not simple (self-intersecting) or non coplanar. @@ -2237,11 +2314,11 @@ function split_polygons_at_each_z(polys, zs, _i=0) = // poly = Polygon to check. // eps = Tolerance for the collinearity test. Default: EPSILON. // Example: -// is_convex_polygon(circle(d=50)); // Returns: true -// is_convex_polygon(rot([50,120,30], p=path3d(circle(1,$fn=50)))); // Returns: true +// test1 = is_convex_polygon(circle(d=50)); // Returns: true +// test2 = is_convex_polygon(rot([50,120,30], p=path3d(circle(1,$fn=50)))); // Returns: true // Example: // spiral = [for (i=[0:36]) let(a=-i*10) (10+i)*[cos(a),sin(a)]]; -// is_convex_polygon(spiral); // Returns: false +// test = is_convex_polygon(spiral); // Returns: false function is_convex_polygon(poly,eps=EPSILON) = assert(is_path(poly), "The input should be a 2D or 3D polygon." ) let( lp = len(poly), @@ -2260,9 +2337,10 @@ function is_convex_polygon(poly,eps=EPSILON) = // Function: convex_distance() // Usage: -// convex_distance(pts1, pts2,); +// dist = convex_distance(pts1, pts2,); +// Topics: Geometry, Convexity, Distance // See also: -// convex_collision +// convex_collision(), hull() // Description: // Returns the smallest distance between a point in convex hull of `points1` // and a point in the convex hull of `points2`. All the points in the lists @@ -2320,9 +2398,10 @@ function _GJK_distance(points1, points2, eps=EPSILON, lbd, d, simplex=[]) = // Function: convex_collision() // Usage: -// convex_collision(pts1, pts2,); +// test = convex_collision(pts1, pts2,); +// Topics: Geometry, Convexity, Collision, Intersection // See also: -// convex_distance +// convex_distance(), hull() // Description: // Returns `true` if the convex hull of `points1` intercepts the convex hull of `points2` // otherwise, `false`. @@ -2383,7 +2462,7 @@ function _closest_simplex(s,eps=EPSILON) = : _closest_s3(s,eps); -// find the closest to a 1-simplex +// find the point of a 1-simplex closest to the origin // Based on: http://uu.diva-portal.org/smash/get/diva2/FFULLTEXT01.pdf function _closest_s1(s,eps=EPSILON) = norm(s[1]-s[0])0 ? _closest_s1([s[0],s[2]],eps) : _closest_s1([s[1],s[2]],eps); -// find the closest to a 3-simplex +// find the point of a 3-simplex closest to the origin // it seems that degenerate 3-simplices are correctly manage without extra code function _closest_s3(s,eps=EPSILON) = assert( len(s[0])==3 && len(s)==4, "Internal error." )