diff --git a/beziers.scad b/beziers.scad index 5589f2c..3a48b6f 100644 --- a/beziers.scad +++ b/beziers.scad @@ -28,11 +28,13 @@ // Section: Bezier Curves // Function: bezier_points() +// Synopsis: Computes one or more specified points along a bezier curve. +// Topics: Bezier Curves +// See Also: bezier_curve(), bezier_curvature(), bezier_tangent(), bezier_derivative(), bezier_points() // Usage: // pt = bezier_points(bezier, u); // ptlist = bezier_points(bezier, RANGE); // ptlist = bezier_points(bezier, LIST); -// Topics: Bezier Curves // Description: // Computes points on a bezier curve with control points specified by `bezier` at parameter values // specified by `u`, which can be a scalar or a list. The value `u=0` gives the first endpoint; `u=1` gives the final endpoint, @@ -176,10 +178,11 @@ function _bezier_matrix(N) = // Function: bezier_curve() +// Synopsis: Computes a number of uniformly distributed points along a bezier curve. +// Topics: Bezier Curves +// See Also: bezier_curve(), bezier_curvature(), bezier_tangent(), bezier_derivative(), bezier_points() // Usage: // path = bezier_curve(bezier, [splinesteps], [endpoint]); -// Topics: Bezier Curves -// See Also: bezier_curvature(), bezier_tangent(), bezier_derivative(), bezier_points() // Description: // Takes a list of bezier control points and generates splinesteps segments (splinesteps+1 points) // along the bezier curve they define. @@ -210,12 +213,13 @@ function bezier_curve(bezier,splinesteps=16,endpoint=true) = // Function: bezier_derivative() +// Synopsis: Evaluates the derivative of the bezier curve at the given point or points. +// Topics: Bezier Curves +// See Also: bezier_curvature(), bezier_tangent(), bezier_points() // Usage: // deriv = bezier_derivative(bezier, u, [order]); // derivs = bezier_derivative(bezier, LIST, [order]); // derivs = bezier_derivative(bezier, RANGE, [order]); -// Topics: Bezier Curves -// See Also: bezier_curvature(), bezier_tangent(), bezier_points() // Description: // Evaluates the derivative of the bezier curve at the given parameter value or values, `u`. The `order` gives the order of the derivative. // The degree of the bezier curve is one less than the number of points in `bezier`. @@ -234,12 +238,13 @@ function bezier_derivative(bezier, u, order=1) = // Function: bezier_tangent() +// Synopsis: Calculates unit tangent vectors along the bezier curve at one or more given positions. +// Topics: Bezier Curves +// See Also: bezier_curvature(), bezier_derivative(), bezier_points() // Usage: // tanvec = bezier_tangent(bezier, u); // tanvecs = bezier_tangent(bezier, LIST); // tanvecs = bezier_tangent(bezier, RANGE); -// Topics: Bezier Curves -// See Also: bezier_curvature(), bezier_derivative(), bezier_points() // Description: // Returns the unit tangent vector at the given parameter values on a bezier curve with control points `bezier`. // Arguments: @@ -254,12 +259,13 @@ function bezier_tangent(bezier, u) = // Function: bezier_curvature() +// Synopsis: Returns the curvature values at one or more given positions along a bezier curve. +// Topics: Bezier Curves +// See Also: bezier_tangent(), bezier_derivative(), bezier_points() // Usage: // crv = bezier_curvature(curve, u); // crvlist = bezier_curvature(curve, LIST); // crvlist = bezier_curvature(curve, RANGE); -// Topics: Bezier Curves -// See Also: bezier_tangent(), bezier_derivative(), bezier_points() // Description: // Returns the curvature value for the given parameters `u` on the bezier curve with control points `bezier`. // The curvature is the inverse of the radius of the tangent circle at the given point. @@ -284,10 +290,11 @@ function bezier_curvature(bezier, u) = // Function: bezier_closest_point() -// Usage: -// u = bezier_closest_point(bezier, pt, [max_err]); +// Synopsis: Finds the closest position on a bezier curve to a given point. // Topics: Bezier Curves // See Also: bezier_points() +// Usage: +// u = bezier_closest_point(bezier, pt, [max_err]); // Description: // Finds the closest part of the given bezier curve to point `pt`. // The degree of the curve, N, is one less than the number of points in `curve`. @@ -333,10 +340,11 @@ function bezier_closest_point(bezier, pt, max_err=0.01, u=0, end_u=1) = // Function: bezier_length() -// Usage: -// pathlen = bezier_length(bezier, [start_u], [end_u], [max_deflect]); +// Synopsis: Approximate the length of part of a bezier curve. // Topics: Bezier Curves // See Also: bezier_points() +// Usage: +// pathlen = bezier_length(bezier, [start_u], [end_u], [max_deflect]); // Description: // Approximates the length of the portion of the bezier curve between start_u and end_u. // Arguments: @@ -370,10 +378,11 @@ function bezier_length(bezier, start_u=0, end_u=1, max_deflect=0.01) = // Function: bezier_line_intersection() -// Usage: -// u = bezier_line_intersection(bezier, line); +// Synopsis: Calculates where a bezier curve intersects a line. // Topics: Bezier Curves, Geometry, Intersection // See Also: bezier_points(), bezier_length(), bezier_closest_point() +// Usage: +// u = bezier_line_intersection(bezier, line); // Description: // Finds the intersection points of the 2D Bezier curve with control points `bezier` and the given line, specified as a pair of points. // Returns the intersection as a list of `u` values for the Bezier. @@ -404,12 +413,13 @@ function bezier_line_intersection(bezier, line) = // Function: bezpath_points() +// Synopsis: Computes one or more specified points along a bezier path. +// Topics: Bezier Paths +// See Also: bezier_points(), bezier_curve() // Usage: // pt = bezpath_points(bezpath, curveind, u, [N]); // ptlist = bezpath_points(bezpath, curveind, LIST, [N]); // path = bezpath_points(bezpath, curveind, RANGE, [N]); -// Topics: Bezier Paths -// See Also: bezier_points(), bezier_curve() // Description: // Extracts from the Bezier path `bezpath` the control points for the Bezier curve whose index is `curveind` and // computes the point or points on the corresponding Bezier curve specified by `u`. If `curveind` is zero you @@ -424,12 +434,13 @@ function bezpath_points(bezpath, curveind, u, N=3) = // Function: bezpath_curve() +// Synopsis: Takes a bezier path and converts it into a path of points. +// Topics: Bezier Paths +// See Also: bezier_points(), bezier_curve(), bezpath_points() // Usage: // path = bezpath_curve(bezpath, [splinesteps], [N], [endpoint]) -// Topics: Bezier Paths -// See Also: bezier_points(), bezier_curve() // Description: -// Takes a bezier path and converts it into a path of points. +// Computes a number of uniformly distributed points along a bezier path. // Arguments: // bezpath = A bezier path to approximate. // splinesteps = Number of straight lines to split each bezier curve into. default=16 @@ -459,10 +470,11 @@ function bezpath_curve(bezpath, splinesteps=16, N=3, endpoint=true) = // Function: bezpath_closest_point() +// Synopsis: Finds the closest part of a bezier path to a give point. +// Topics: Bezier Paths +// See Also: bezpath_points(), bezpath_curve(), bezier_points(), bezier_curve(), bezier_closest_point() // Usage: // res = bezpath_closest_point(bezpath, pt, [N], [max_err]); -// Topics: Bezier Paths -// See Also: bezier_points(), bezier_curve(), bezier_closest_point() // Description: // Finds an approximation to the closest part of the given bezier path to point `pt`. // Returns [segnum, u] for the closest position on the bezier path to the given point `pt`. @@ -504,10 +516,11 @@ function bezpath_closest_point(bezpath, pt, N=3, max_err=0.01, seg=0, min_seg=un // Function: bezpath_length() -// Usage: -// plen = bezpath_length(path, [N], [max_deflect]); +// Synopsis: Approximate the length of a bezier path. // Topics: Bezier Paths // See Also: bezier_points(), bezier_curve(), bezier_length() +// Usage: +// plen = bezpath_length(path, [N], [max_deflect]); // Description: // Approximates the length of the bezier path. // Arguments: @@ -530,10 +543,11 @@ function bezpath_length(bezpath, N=3, max_deflect=0.001) = // Function: path_to_bezpath() -// Usage: -// bezpath = path_to_bezpath(path, [closed], [tangents], [uniform], [size=]|[relsize=]); +// Synopsis: Generates a bezier path that passes through all points in a given linear path. // Topics: Bezier Paths, Rounding // See Also: path_tangents() +// Usage: +// bezpath = path_to_bezpath(path, [closed], [tangents], [uniform], [size=]|[relsize=]); // Description: // Given a 2d or 3d input path and optional list of tangent vectors, computes a cubic (degree 3) bezier // path that passes through every point on the input path and matches the tangent vectors. If you do @@ -616,10 +630,11 @@ function path_to_bezpath(path, closed, tangents, uniform=false, size, relsize) = // Function: bezpath_close_to_axis() -// Usage: -// bezpath = bezpath_close_to_axis(bezpath, [axis], [N]); +// Synopsis: Closes a 2D bezier path to the specified axis. // Topics: Bezier Paths // See Also: bezpath_offset() +// Usage: +// bezpath = bezpath_close_to_axis(bezpath, [axis], [N]); // Description: // Takes a 2D bezier path and closes it to the specified axis. // Arguments: @@ -659,10 +674,11 @@ function bezpath_close_to_axis(bezpath, axis="X", N=3) = // Function: bezpath_offset() -// Usage: -// bezpath = bezpath_offset(offset, bezier, [N]); +// Synopsis: Forms a closed bezier path loop with a translated and reversed copy of itself. // Topics: Bezier Paths // See Also: bezpath_close_to_axis() +// Usage: +// bezpath = bezpath_offset(offset, bezier, [N]); // Description: // Takes a 2D bezier path and closes it with a matching reversed path that is offset by the given `offset` [X,Y] distance. // Arguments: @@ -697,6 +713,7 @@ function bezpath_offset(offset, bezier, N=3) = // Section: Cubic Bezier Path Construction // Function: bez_begin() +// Synopsis: Calculates starting bezier path control points. // Topics: Bezier Paths // See Also: bez_tang(), bez_joint(), bez_end() // Usage: @@ -767,6 +784,7 @@ function bez_begin(pt,a,r,p) = // Function: bez_tang() +// Synopsis: Calculates control points for a smooth bezier path joint. // Topics: Bezier Paths // See Also: bez_begin(), bez_joint(), bez_end() // Usage: @@ -802,6 +820,7 @@ function bez_tang(pt,a,r1,r2,p) = // Function: bez_joint() +// Synopsis: Calculates control points for a disjointed corner bezier path joint. // Topics: Bezier Paths // See Also: bez_begin(), bez_tang(), bez_end() // Usage: @@ -842,6 +861,7 @@ function bez_joint(pt,a1,a2,r1,r2,p1,p2) = // Function: bez_end() +// Synopsis: Calculates ending bezier path control points. // Topics: Bezier Paths // See Also: bez_tang(), bez_joint(), bez_end() // Usage: @@ -868,11 +888,12 @@ function bez_end(pt,a,r,p) = // Function: is_bezier_patch() +// Synopsis: Returns true if the given item is a bezier patch. +// Topics: Bezier Patches, Type Checking // Usage: // bool = is_bezier_patch(x); -// Topics: Bezier Patches, Type Checking // Description: -// Returns true if the given item is a bezier patch. +// Returns true if the given item is a bezier patch. (a 2D array of 3D points.) // Arguments: // x = The value to check the type of. function is_bezier_patch(x) = @@ -880,10 +901,11 @@ function is_bezier_patch(x) = // Function: bezier_patch_flat() -// Usage: -// patch = bezier_patch_flat(size, [N=], [spin=], [orient=], [trans=]); +// Synopsis: Creates a flat bezier patch. // Topics: Bezier Patches // See Also: bezier_patch_points() +// Usage: +// patch = bezier_patch_flat(size, [N=], [spin=], [orient=], [trans=]); // Description: // Returns a flat rectangular bezier patch of degree `N`, centered on the XY plane. // Arguments: @@ -913,10 +935,11 @@ function bezier_patch_flat(size, N=1, spin=0, orient=UP, trans=[0,0,0]) = // Function: bezier_patch_reverse() -// Usage: -// rpatch = bezier_patch_reverse(patch); +// Synopsis: Reverses the orientation of a bezier patch. // Topics: Bezier Patches // See Also: bezier_patch_points(), bezier_patch_flat() +// Usage: +// rpatch = bezier_patch_reverse(patch); // Description: // Reverses the patch, so that the faces generated from it are flipped back to front. // Arguments: @@ -926,12 +949,13 @@ function bezier_patch_reverse(patch) = // Function: bezier_patch_points() +// Synopsis: Computes one or more specified points across a bezier surface patch. +// Topics: Bezier Patches +// See Also: bezier_patch_normals(), bezier_points(), bezier_curve(), bezpath_curve() // Usage: // pt = bezier_patch_points(patch, u, v); // ptgrid = bezier_patch_points(patch, LIST, LIST); // ptgrid = bezier_patch_points(patch, RANGE, RANGE); -// Topics: Bezier Patches -// See Also: bezier_patch_normals(), bezier_points(), bezier_curve(), bezpath_curve() // Description: // Sample a bezier patch on a listed point set. The bezier patch must be a rectangular array of // points, and it will be sampled at all the (u,v) pairs that you specify. If you give u and v @@ -987,10 +1011,11 @@ function _bezier_rectangle(patch, splinesteps=16, style="default") = // Function: bezier_vnf() -// Usage: -// vnf = bezier_vnf(patches, [splinesteps], [style]); +// Synopsis: Generates a (probably non-manifold) VNF for one or more bezier surface patches. // Topics: Bezier Patches // See Also: bezier_patch_points(), bezier_patch_flat() +// Usage: +// vnf = bezier_vnf(patches, [splinesteps], [style]); // Description: // Convert a patch or list of patches into the corresponding Bezier surface, representing the // result as a [VNF structure](vnf.scad). The `splinesteps` argument specifies the sampling grid of @@ -1113,6 +1138,9 @@ function bezier_vnf(patches=[], splinesteps=16, style="default") = // Function: bezier_vnf_degenerate_patch() +// Synopsis: Generates a VNF for a degenerate bezier surface patch. +// Topics: Bezier Patches +// See Also: bezier_patch_points(), bezier_patch_flat(), bezier_vnf() // Usage: // vnf = bezier_vnf_degenerate_patch(patch, [splinesteps], [reverse]); // vnf_edges = bezier_vnf_degenerate_patch(patch, [splinesteps], [reverse], return_edges=true); @@ -1297,12 +1325,13 @@ function bezier_vnf_degenerate_patch(patch, splinesteps=16, reverse=false, retur // Function: bezier_patch_normals() +// Synopsis: Computes surface normals for one or more places on a bezier surface patch. +// Topics: Bezier Patches +// See Also: bezier_patch_points(), bezier_points(), bezier_curve(), bezpath_curve() // Usage: // n = bezier_patch_normals(patch, u, v); // ngrid = bezier_patch_normals(patch, LIST, LIST); // ngrid = bezier_patch_normals(patch, RANGE, RANGE); -// Topics: Bezier Patches -// See Also: bezier_patch_points(), bezier_points(), bezier_curve(), bezpath_curve() // Description: // Compute the unit normal vector to a bezier patch at the listed point set. The bezier patch must be a rectangular array of // points, and the normal will be computed at all the (u,v) pairs that you specify. If you give u and v @@ -1409,10 +1438,11 @@ function bezier_patch_normals(patch, u, v) = // Module: debug_bezier() -// Usage: -// debug_bezier(bez, [size], [N=]); +// Synopsis: Shows a bezier path and it's associated control points. // Topics: Bezier Paths, Debugging // See Also: bezpath_curve() +// Usage: +// debug_bezier(bez, [size], [N=]); // Description: // Renders 2D or 3D bezier paths and their associated control points. // Useful for debugging bezier paths. @@ -1462,10 +1492,11 @@ module debug_bezier(bezpath, width=1, N=3) { // Module: debug_bezier_patches() -// Usage: -// debug_bezier_patches(patches, [size=], [splinesteps=], [showcps=], [showdots=], [showpatch=], [convexity=], [style=]); +// Synopsis: Shows a bezier surface patch and its associated control points. // Topics: Bezier Patches, Debugging // See Also: bezier_patch_points(), bezier_patch_flat(), bezier_vnf() +// Usage: +// debug_bezier_patches(patches, [size=], [splinesteps=], [showcps=], [showdots=], [showpatch=], [convexity=], [style=]); // Description: // Shows the surface, and optionally, control points of a list of bezier patches. // Arguments: