Added dashed_stroke(). path_cut() -> path_cut_points().

Author: Garth Minette

coords.scad

@@ -9,21 +9,27 @@
 // Section: Coordinate Manipulation
 
 // Function: point2d()
+// Usage:
+//   pt = point2d(p, <fill>);
+// Topics: Coordinates, Points
+// See Also: path2d(), point3d(), path3d()
 // Description:
-//   Returns a 2D vector/point from a 2D or 3D vector.
-//   If given a 3D point, removes the Z coordinate.
+//   Returns a 2D vector/point from a 2D or 3D vector.  If given a 3D point, removes the Z coordinate.
 // Arguments:
 //   p = The coordinates to force into a 2D vector/point.
 //   fill = Value to fill missing values in vector with.
 function point2d(p, fill=0) = [for (i=[0:1]) (p[i]==undef)? fill : p[i]];
 
 
 // Function: path2d()
+// Usage:
+//   pts = path2d(points);
+// Topics: Coordinates, Points, Paths
+// See Also: point2d(), point3d(), path3d()
 // 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
-//   every vector has the same length.  
+//   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
+//   every vector has the same length.
 // Arguments:
 //   points = A list of 2D or 3D points/vectors.
 function path2d(points) =
@@ -34,6 +40,10 @@ function path2d(points) =
 
 
 // Function: point3d()
+// Usage:
+//   pt = point3d(p, <fill>);
+// Topics: Coordinates, Points
+// See Also: path2d(), point2d(), path3d()
 // Description:
 //   Returns a 3D vector/point from a 2D or 3D vector.
 // Arguments:
@@ -43,6 +53,10 @@ function point3d(p, fill=0) = [for (i=[0:2]) (p[i]==undef)? fill : p[i]];
 
 
 // Function: path3d()
+// Usage:
+//   pts = path3d(points, <fill>);
+// Topics: Coordinates, Points, Paths
+// See Also: point2d(), path2d(), point3d()
 // Description:
 //   Returns a list of 3D vectors/points from a list of 2D or higher dimensional vectors/points
 //   by removing extra coordinates or adding the z coordinate.  
@@ -63,6 +77,10 @@ function path3d(points, fill=0) =
 
 
 // Function: point4d()
+// Usage:
+//   pt = point4d(p, <fill>);
+// Topics: Coordinates, Points
+// See Also: point2d(), path2d(), point3d(), path3d(), path4d()
 // Description:
 //   Returns a 4D vector/point from a 2D or 3D vector.
 // Arguments:
@@ -72,12 +90,15 @@ function point4d(p, fill=0) = [for (i=[0:3]) (p[i]==undef)? fill : p[i]];
 
 
 // Function: path4d()
+// Usage:
+//   pt = path4d(points, <fill>);
+// Topics: Coordinates, Points, Paths
+// See Also: point2d(), path2d(), point3d(), path3d(), point4d()
 // Description:
 //   Returns a list of 4D vectors/points from a list of 2D or 3D vectors/points.
 // Arguments:
 //   points = A list of 2D or 3D points/vectors.
 //   fill = Value to fill missing values in vectors with.
-
 function path4d(points, fill=0) = 
    assert(is_num(fill) || is_vector(fill))
    assert(is_path(points, dim=undef, fast=true), "Input to path4d is not a path")
@@ -102,8 +123,10 @@ function path4d(points, fill=0) =
 
 // Function: polar_to_xy()
 // Usage:
-//   polar_to_xy(r, theta);
-//   polar_to_xy([r, theta]);
+//   pt = polar_to_xy(r, theta);
+//   pt = polar_to_xy([r, theta]);
+// Topics: Coordinates, Points, Paths
+// 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.
 //   Returns [X,Y] cartesian coordinates.
@@ -114,6 +137,13 @@ function path4d(points, fill=0) =
 //   xy = polar_to_xy(20,45);    // Returns: ~[14.1421365, 14.1421365]
 //   xy = polar_to_xy(40,30);    // Returns: ~[34.6410162, 15]
 //   xy = polar_to_xy([40,30]);  // Returns: ~[34.6410162, 15]
+// Example(2D):
+//   r=40; ang=30; $fn=36;
+//   pt = polar_to_xy(r,ang);
+//   stroke(circle(r=r), closed=true, width=0.5);
+//   color("black") stroke([[r,0], [0,0], pt], width=0.5);
+//   color("black") stroke(arc(r=15, angle=ang), width=0.5);
+//   color("red") move(pt) circle(d=3);
 function polar_to_xy(r,theta=undef) = let(
         rad = theta==undef? r[0] : r,
         t = theta==undef? r[1] : theta
@@ -122,8 +152,10 @@ function polar_to_xy(r,theta=undef) = let(
 
 // Function: xy_to_polar()
 // Usage:
-//   xy_to_polar(x,y);
-//   xy_to_polar([X,Y]);
+//   r_theta = xy_to_polar(x,y);
+//   r_theta = xy_to_polar([X,Y]);
+// Topics: Coordinates, Points, Paths
+// 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.
 //   Returns [radius, theta] where theta is the angle counter-clockwise of X+.
@@ -133,6 +165,13 @@ function polar_to_xy(r,theta=undef) = let(
 // Examples:
 //   plr = xy_to_polar(20,30);
 //   plr = xy_to_polar([40,60]);
+// Example(2D):
+//   pt = [-20,30]; $fn = 36;
+//   rt = xy_to_polar(pt);
+//   r = rt[0]; ang = rt[1];
+//   stroke(circle(r=r), closed=true, width=0.5);
+//   zrot(ang) stroke([[0,0],[r,0]],width=0.5);
+//   color("red") move(pt) circle(d=3);
 function xy_to_polar(x,y=undef) = let(
         xx = y==undef? x[0] : x,
         yy = y==undef? x[1] : y
@@ -141,11 +180,13 @@ function xy_to_polar(x,y=undef) = let(
 
 // Function: project_plane()
 // Usage: With the plane defined by 3 Points
-//   xyz = project_plane(point, a, b, c);
+//   pt = project_plane(point, a, b, c);
 // Usage: With the plane defined by Pointlist
-//   xyz = project_plane(point, POINTLIST);
+//   pt = project_plane(point, POINTLIST);
 // Usage: With the plane defined by Plane Definition [A,B,C,D] Where Ax+By+Cz=D
-//   xyz = project_plane(point, PLANE);
+//   pt = project_plane(point, PLANE);
+// Topics: Coordinates, Points, Paths
+// See Also: lift_plane()
 // Description:
 //   Converts the given 3D points from global coordinates to the 2D planar coordinates of the closest
 //   points on the plane.  This coordinate system can be useful in taking a set of nearly coplanar
@@ -165,6 +206,20 @@ function xy_to_polar(x,y=undef) = let(
 //   a=[0,0,0];  b=[10,-10,0];  c=[10,0,10];
 //   xy = project_plane(pt, a, b, c);
 //   xy2 = project_plane(pt, [a,b,c]);
+// Example(3D):
+//   points = move([10,20,30], p=yrot(25, p=path3d(circle(d=100, $fn=36))));
+//   plane = plane_from_normal([1,0,1]);
+//   proj = project_plane(points,plane);
+//   n = plane_normal(plane);
+//   cp = centroid(proj);
+//   color("red") move_copies(points) sphere(d=2,$fn=12);
+//   color("blue") rot(from=UP,to=n,cp=cp) move_copies(proj) sphere(d=2,$fn=12);
+//   move(cp) {
+//       rot(from=UP,to=n) {
+//           anchor_arrow(30);
+//           %cube([120,150,0.1],center=true);
+//       }
+//   }
 function project_plane(point, a, b, c) =
     is_undef(b) && is_undef(c) && is_list(a)? let(
         mat = is_vector(a,4)? plane_transform(a) :
@@ -195,6 +250,8 @@ function project_plane(point, a, b, c) =
 //   xyz = lift_plane(point, POINTLIST);
 // Usage: With Plane Definition [A,B,C,D] Where Ax+By+Cz=D
 //   xyz = lift_plane(point, PLANE);
+// Topics: Coordinates, Points, Paths
+// See Also: project_plane()
 // Description:
 //   Converts the given 2D point from planar coordinates to the global 3D coordinates of the point on the plane.
 //   Can be called one of three ways:
@@ -232,8 +289,10 @@ function lift_plane(point, a, b, c) =
 
 // Function: cylindrical_to_xyz()
 // Usage:
-//   cylindrical_to_xyz(r, theta, z)
-//   cylindrical_to_xyz([r, theta, z])
+//   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()
 // Description:
 //   Convert cylindrical coordinates to 3D cartesian coordinates.  Returns [X,Y,Z] cartesian coordinates.
 // Arguments:
@@ -252,12 +311,13 @@ function cylindrical_to_xyz(r,theta=undef,z=undef) = let(
 
 // Function: xyz_to_cylindrical()
 // Usage:
-//   xyz_to_cylindrical(x,y,z)
-//   xyz_to_cylindrical([X,Y,Z])
+//   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()
 // 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.
+//   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.
 // Arguments:
 //   x = X coordinate.
 //   y = Y coordinate.
@@ -272,11 +332,12 @@ function xyz_to_cylindrical(x,y=undef,z=undef) = let(
 
 // Function: spherical_to_xyz()
 // Usage:
-//   spherical_to_xyz(r, theta, phi);
-//   spherical_to_xyz([r, theta, phi]);
+//   pt = spherical_to_xyz(r, theta, phi);
+//   pt = spherical_to_xyz([r, theta, phi]);
 // Description:
-//   Convert spherical coordinates to 3D cartesian coordinates.
-//   Returns [X,Y,Z] cartesian coordinates.
+//   Convert spherical coordinates to 3D cartesian coordinates.  Returns [X,Y,Z] cartesian coordinates.
+// Topics: Coordinates, Points, Paths
+// See Also: cylindrical_to_xyz(), xyz_to_spherical(), xyz_to_cylindrical()
 // Arguments:
 //   r = distance from origin.
 //   theta = angle in degrees, counter-clockwise of X+ on the XY plane.
@@ -293,12 +354,13 @@ function spherical_to_xyz(r,theta=undef,phi=undef) = let(
 
 // Function: xyz_to_spherical()
 // Usage:
-//   xyz_to_spherical(x,y,z)
-//   xyz_to_spherical([X,Y,Z])
+//   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()
 // 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.
+//   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.
 // Arguments:
 //   x = X coordinate.
 //   y = Y coordinate.
@@ -313,8 +375,10 @@ function xyz_to_spherical(x,y=undef,z=undef) = let(
 
 // Function: altaz_to_xyz()
 // Usage:
-//   altaz_to_xyz(alt, az, r);
-//   altaz_to_xyz([alt, az, r]);
+//   pt = altaz_to_xyz(alt, az, r);
+//   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()
 // Description:
 //   Convert altitude/azimuth/range coordinates to 3D cartesian coordinates.
 //   Returns [X,Y,Z] cartesian coordinates.
@@ -334,8 +398,10 @@ function altaz_to_xyz(alt,az=undef,r=undef) = let(
 
 // Function: xyz_to_altaz()
 // Usage:
-//   xyz_to_altaz(x,y,z);
-//   xyz_to_altaz([X,Y,Z]);
+//   alt_az_r = xyz_to_altaz(x,y,z);
+//   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()
 // Description:
 //   Convert 3D cartesian coordinates to altitude/azimuth/range coordinates.
 //   Returns [altitude,azimuth,range], where altitude is angle above the

geometry.scad

@@ -999,10 +999,11 @@ function plane_transform(plane) =
 
 // Function: projection_on_plane()
 // Usage:
-//   projection_on_plane(points);
+//   pts = projection_on_plane(plane, points);
 // 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.
+//   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.
+//   In other words, for every point given, returns the closest point to it on the plane.
 // Arguments:
 //   plane = The `[A,B,C,D]` plane definition where `Ax+By+Cz=D` is the formula of the plane.
 //   points = List of points to project
@@ -1061,24 +1062,6 @@ function distance_from_plane(plane, point) =
     point3d(plane)* point - plane[3];
 
 
-// Function: closest_point_on_plane()
-// Usage:
-//   pt = closest_point_on_plane(plane, point);
-// Description:
-//   Takes a point, and a plane [A,B,C,D] where the equation of that plane is `Ax+By+Cz=D`.
-//   Returns the coordinates of the closest point on that plane to the given `point`.
-// Arguments:
-//   plane = The [A,B,C,D] coefficients for the equation of the plane.
-//   point = The 3D point to find the closest point to.
-function closest_point_on_plane(plane, point) =
-    assert( _valid_plane(plane), "Invalid input plane." )
-    assert( is_vector(point,3), "Invalid point." )
-    let( plane = normalize_plane(plane),
-        n = point3d(plane),
-        d = n*point - plane[3] // distance from plane
-    )
-    point - n*d;
-
 
 // Returns [POINT, U] if line intersects plane at one point.
 // Returns [LINE, undef] if the line is on the plane.