From 67121413708721108e46190c4e567c0417ea3a52 Mon Sep 17 00:00:00 2001 From: Revar Desmera Date: Sat, 27 May 2023 01:42:09 -0700 Subject: [PATCH] SynTags for attachments.scad to geometry.scad --- attachments.scad | 24 +++-- comparisons.scad | 6 +- constants.scad | 1 + coords.scad | 110 +++++++++++--------- cubetruss.scad | 17 ++- distributors.scad | 62 ++++++++--- drawing.scad | 13 ++- gears.scad | 7 ++ geometry.scad | 257 +++++++++++++++++++++++++++------------------- 9 files changed, 304 insertions(+), 193 deletions(-) diff --git a/attachments.scad b/attachments.scad index 3b7d4ec..c661c31 100644 --- a/attachments.scad +++ b/attachments.scad @@ -464,6 +464,7 @@ _ANCHOR_TYPES = ["intersect","hull"]; // Module: position() // Synopsis: Attaches children to a parent object at an anchor point. +// SynTags: Trans // Topics: Attachments // See Also: attachable(), attach(), orient() // Usage: @@ -500,6 +501,7 @@ module position(from) // Module: orient() // Synopsis: Orients children's tops in the directon of the specified anchor. +// SynTags: Trans // Topics: Attachments // See Also: attachable(), attach(), orient() // Usage: @@ -553,6 +555,7 @@ module orient(anchor, spin) { // Module: attach() // Synopsis: Attaches children to a parent object at an anchor point and orientation. +// SynTags: Trans // Topics: Attachments // See Also: attachable(), position(), face_profile(), edge_profile(), corner_profile() // Usage: @@ -1380,6 +1383,7 @@ module show_int(tags) // Module: face_mask() // Synopsis: Ataches a 3d mask shape to the given faces of the parent. +// SynTags: Trans // Topics: Attachments, Masking // See Also: attachable(), position(), attach(), edge_mask(), corner_mask(), face_profile(), edge_profile(), corner_profile() // Usage: @@ -1423,6 +1427,7 @@ module face_mask(faces=[LEFT,RIGHT,FRONT,BACK,BOT,TOP]) { // Module: edge_mask() // Synopsis: Attaches a 3D mask shape to the given edges of the parent. +// SynTags: Trans // Topics: Attachments, Masking // See Also: attachable(), position(), attach(), face_mask(), corner_mask(), face_profile(), edge_profile(), corner_profile() // Usage: @@ -1487,6 +1492,7 @@ module edge_mask(edges=EDGES_ALL, except=[]) { // Module: corner_mask() // Synopsis: Attaches a 3d mask shape to the given corners of the parent. +// SynTags: Trans // Topics: Attachments, Masking // See Also: attachable(), position(), attach(), face_mask(), edge_mask(), face_profile(), edge_profile(), corner_profile() // Usage: @@ -1537,6 +1543,7 @@ module corner_mask(corners=CORNERS_ALL, except=[]) { // Module: face_profile() // Synopsis: Extrudes a 2D edge profile into a mask for all edges and corners of the given faces on the parent. +// SynTags: Geom // Topics: Attachments, Masking // See Also: attachable(), position(), attach(), edge_profile(), corner_profile(), face_mask(), edge_mask(), corner_mask() // Usage: @@ -1576,6 +1583,7 @@ module face_profile(faces=[], r, d, excess=0.01, convexity=10) { // Module: edge_profile() // Synopsis: Extrudes a 2d edge profile into a mask on the given edges of the parent. +// SynTags: Geom // Topics: Attachments, Masking // See Also: attachable(), position(), attach(), face_profile(), corner_profile(), edge_mask(), face_mask(), corner_mask() // Usage: @@ -1640,6 +1648,7 @@ module edge_profile(edges=EDGES_ALL, except=[], excess=0.01, convexity=10) { // Module: corner_profile() // Synopsis: Rotationally extrudes a 2d edge profile into corner mask on the given corners of the parent. +// SynTags: Geom // Topics: Attachments, Masking // See Also: attachable(), position(), attach(), face_profile(), edge_profile(), corner_mask(), face_mask(), edge_mask() // Usage: @@ -2024,6 +2033,7 @@ module attachable( // Function: reorient() // Synopsis: Calculates the transformation matrix needed to reorient an object. +// SynTags: Trans, Path, VNF // Topics: Attachments // See Also: reorient(), attachable() // Usage: Square/Trapezoid Geometry @@ -2040,25 +2050,25 @@ module attachable( // pts = reorient(anchor, spin, [orient], two_d=true, region=, [extent=], p=, ...); // Usage: Cubical/Prismoidal Geometry // mat = reorient(anchor, spin, [orient], size=, [size2=], [shift=], ...); -// pts = reorient(anchor, spin, [orient], size=, [size2=], [shift=], p=, ...); +// vnf = reorient(anchor, spin, [orient], size=, [size2=], [shift=], p=, ...); // Usage: Cylindrical Geometry // mat = reorient(anchor, spin, [orient], r=|d=, l=, [axis=], ...); -// pts = reorient(anchor, spin, [orient], r=|d=, l=, [axis=], p=, ...); +// vnf = reorient(anchor, spin, [orient], r=|d=, l=, [axis=], p=, ...); // Usage: Conical Geometry // mat = reorient(anchor, spin, [orient], r1=|d1=, r2=|d2=, l=, [axis=], ...); -// pts = reorient(anchor, spin, [orient], r1=|d1=, r2=|d2=, l=, [axis=], p=, ...); +// vnf = reorient(anchor, spin, [orient], r1=|d1=, r2=|d2=, l=, [axis=], p=, ...); // Usage: Spheroid/Ovoid Geometry // mat = reorient(anchor, spin, [orient], r|d=, ...); -// pts = reorient(anchor, spin, [orient], r|d=, p=, ...); +// vnf = reorient(anchor, spin, [orient], r|d=, p=, ...); // Usage: Extruded Path/Polygon Geometry // mat = reorient(anchor, spin, [orient], path=, l=|h=, [extent=], ...); -// pts = reorient(anchor, spin, [orient], path=, l=|h=, [extent=], p=, ...); +// vnf = reorient(anchor, spin, [orient], path=, l=|h=, [extent=], p=, ...); // Usage: Extruded Region Geometry // mat = reorient(anchor, spin, [orient], region=, l=|h=, [extent=], ...); -// pts = reorient(anchor, spin, [orient], region=, l=|h=, [extent=], p=, ...); +// vnf = reorient(anchor, spin, [orient], region=, l=|h=, [extent=], p=, ...); // Usage: VNF Geometry // mat = reorient(anchor, spin, [orient], vnf, [extent], ...); -// pts = reorient(anchor, spin, [orient], vnf, [extent], p=, ...); +// vnf = reorient(anchor, spin, [orient], vnf, [extent], p=, ...); // // Description: // Given anchor, spin, orient, and general geometry info for a managed volume, this calculates diff --git a/comparisons.scad b/comparisons.scad index 1687f12..2d090da 100644 --- a/comparisons.scad +++ b/comparisons.scad @@ -241,7 +241,7 @@ function are_ends_equal(list, eps=EPSILON) = // Usage: // bool = is_increasing(list, [strict]); // Description: -// Returns true if the list is (non-strictly) increasing, or strictly increasing if strict is set to true. +// Returns true if the list is (non-strictly) increasing, or strictly increasing if `strict=true`. // The list can be a list of any items that OpenSCAD can compare, or it can be a string which will be // evaluated character by character. // Arguments: @@ -266,7 +266,7 @@ function is_increasing(list,strict=false) = // Usage: // bool = is_decreasing(list, [strict]); // Description: -// Returns true if the list is (non-strictly) decreasing, or strictly decreasing if strict is set to true. +// Returns true if the list is (non-strictly) decreasing, or strictly decreasing if `strict=true`. // The list can be a list of any items that OpenSCAD can compare, or it can be a string which will be // evaluated character by character. // Arguments: @@ -532,7 +532,7 @@ function close_path(list,eps=EPSILON) = list_wrap(list,eps); // Function: list_unwrap() -// Synopsis: Removes the last item of a list if it's first and last values are equal. +// Synopsis: Removes the last item of a list if its first and last values are equal. // Topics: List Handling, Paths // See Also: list_wrap(), deduplicate() // Usage: diff --git a/constants.scad b/constants.scad index a93f9c9..466dfcc 100644 --- a/constants.scad +++ b/constants.scad @@ -130,6 +130,7 @@ INCH = 25.4; // Constant: IDENT // Synopsis: A constant containing the 3D identity transformation matrix. +// SynTags: Mat // Topics: Constants, Affine, Matrices, Transforms // See Also: ident() // Description: Identity transformation matrix for three-dimensional transforms. Equal to `ident(4)`. diff --git a/coords.scad b/coords.scad index 272e102..46b7577 100644 --- a/coords.scad +++ b/coords.scad @@ -12,11 +12,11 @@ // Section: Coordinate Manipulation // Function: point2d() -// Usage: -// pt = point2d(p, [fill]); +// Synopsis: Convert a vector to 2D. // Topics: Coordinates, Points // See Also: path2d(), point3d(), path3d() -// Synopsis: Convert a vector to 2d. +// Usage: +// pt = point2d(p, [fill]); // Description: // Returns a 2D vector/point from a 2D or 3D vector. If given a 3D point, removes the Z coordinate. // Arguments: @@ -26,11 +26,12 @@ function point2d(p, fill=0) = assert(is_list(p)) [for (i=[0:1]) (p[i]==undef)? f // Function: path2d() -// Usage: -// pts = path2d(points); +// Synopsis: Convert a path to 2D. +// SynTags: Path // Topics: Coordinates, Points, Paths // See Also: point2d(), point3d(), path3d() -// Synopsis: Convert a path to 2d. +// Usage: +// pts = path2d(points); // 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 @@ -45,11 +46,11 @@ function path2d(points) = // Function: point3d() -// Usage: -// pt = point3d(p, [fill]); +// Synopsis: Convert a vector to 3D. // Topics: Coordinates, Points // See Also: path2d(), point2d(), path3d() -// Synopsis: Convert a vector to 3d. +// Usage: +// pt = point3d(p, [fill]); // Description: // Returns a 3D vector/point from a 2D or 3D vector. // Arguments: @@ -61,11 +62,12 @@ function point3d(p, fill=0) = // Function: path3d() +// Synopsis: Convert a path to 3D. +// SynTags: Path +// Topics: Coordinates, Points, Paths +// See Also: point2d(), path2d(), point3d() // Usage: // pts = path3d(points, [fill]); -// Topics: Coordinates, Points, Paths -// Synopsis: Convert a path to 3d. -// 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. @@ -86,11 +88,11 @@ function path3d(points, fill=0) = // Function: point4d() +// Synopsis: Convert a vector to 4d. +// Topics: Coordinates, Points +// See Also: point2d(), path2d(), point3d(), path3d(), path4d() // Usage: // pt = point4d(p, [fill]); -// Topics: Coordinates, Points -// Synopsis: Convert a vector to 4d. -// See Also: point2d(), path2d(), point3d(), path3d(), path4d() // Description: // Returns a 4D vector/point from a 2D or 3D vector. // Arguments: @@ -101,11 +103,12 @@ function point4d(p, fill=0) = assert(is_list(p)) // Function: path4d() -// Usage: -// pt = path4d(points, [fill]); +// Synopsis: Convert a path to 4d. +// SynTags: Path // Topics: Coordinates, Points, Paths // See Also: point2d(), path2d(), point3d(), path3d(), point4d() -// Synopsis: Convert a path to 4d. +// Usage: +// pt = path4d(points, [fill]); // Description: // Returns a list of 4D vectors/points from a list of 2D or 3D vectors/points. // Arguments: @@ -134,13 +137,14 @@ function path4d(points, fill=0) = // Section: Coordinate Systems // Function: polar_to_xy() +// Synopsis: Convert 2D polar coordinates to cartesian coordinates. +// SynTags: Path +// Topics: Coordinates, Points, Paths +// See Also: xy_to_polar(), xyz_to_cylindrical(), cylindrical_to_xyz(), xyz_to_spherical(), spherical_to_xyz() // Usage: // pt = polar_to_xy(r, theta); // pt = polar_to_xy([R, THETA]); // pts = polar_to_xy([[R,THETA], [R,THETA], ...]); -// Topics: Coordinates, Points, Paths -// Synopsis: Convert 2d polar coordinates to cartesian coordinates. -// See Also: xy_to_polar(), xyz_to_cylindrical(), cylindrical_to_xyz(), xyz_to_spherical(), spherical_to_xyz() // Description: // Called with two arguments, converts the `r` and `theta` 2D polar coordinate into an `[X,Y]` cartesian coordinate. // Called with one `[R,THETA]` vector argument, converts the 2D polar coordinate into an `[X,Y]` cartesian coordinate. @@ -172,13 +176,13 @@ function polar_to_xy(r,theta) = // Function: xy_to_polar() +// Synopsis: Convert 2D cartesian coordinates to polar coordinates (radius and angle) +// Topics: Coordinates, Points, Paths +// See Also: polar_to_xy(), xyz_to_cylindrical(), cylindrical_to_xyz(), xyz_to_spherical(), spherical_to_xyz() // Usage: // r_theta = xy_to_polar(x,y); // r_theta = xy_to_polar([X,Y]); // r_thetas = xy_to_polar([[X,Y], [X,Y], ...]); -// Topics: Coordinates, Points, Paths -// Synopsis: Convert 2d cartesian coordinates to polar coordinates (radius and angle) -// See Also: polar_to_xy(), xyz_to_cylindrical(), cylindrical_to_xyz(), xyz_to_spherical(), spherical_to_xyz() // Description: // Called with two arguments, converts the `x` and `y` 2D cartesian coordinate into a `[RADIUS,THETA]` polar coordinate. // Called with one `[X,Y]` vector argument, converts the 2D cartesian coordinate into a `[RADIUS,THETA]` polar coordinate. @@ -209,16 +213,19 @@ function xy_to_polar(x, y) = // Function: project_plane() +// Synopsis: Project a set of points onto a specified plane, returning 2D points. +// SynTags: Path +// Topics: Coordinates, Points, Paths +// See Also: lift_plane() // Usage: // xy = project_plane(plane, p); // Usage: To get a transform matrix // M = project_plane(plane) -// Synopsis: Project a set of points onto a specified plane, returning 2d points. // Description: -// Maps the provided 3d point(s) from 3D coordinates to a 2d coordinate system defined by `plane`. Points that are not +// Maps the provided 3D point(s) from 3D coordinates to a 2D coordinate system defined by `plane`. Points that are not // on the specified plane will be projected orthogonally onto the plane. This coordinate system is useful if you need -// to perform 2d operations on a coplanar set of data. After those operations are done you can return the data -// to 3d with `lift_plane()`. You could also use this to force approximately coplanar data to be exactly coplanar. +// to perform 2D operations on a coplanar set of data. After those operations are done you can return the data +// to 3D with `lift_plane()`. You could also use this to force approximately coplanar data to be exactly coplanar. // The parameter p can be a point, path, region, bezier patch or VNF. // The plane can be specified as // - A list of three points. The planar coordinate system will have [0,0] at plane[0], and plane[1] will lie on the Y+ axis. @@ -227,7 +234,6 @@ function xy_to_polar(x, y) = // . // If you omit the point specification then `project_plane()` returns a rotation matrix that maps the specified plane to the XY plane. // Note that if you apply this transformation to data lying on the plane it will produce 3D points with the Z coordinate of zero. -// Topics: Coordinates, Points, Paths // Arguments: // plane = plane specification or point list defining the plane // p = 3D point, path, region, VNF or bezier patch to project @@ -271,7 +277,7 @@ function project_plane(plane,p) = is_vnf(p) ? [project_plane(plane,p[0]), p[1]] : is_list(p) && is_list(p[0]) && is_vector(p[0][0],3) ? // bezier patch or region [for(plist=p) project_plane(plane,plist)] - : assert(is_vector(p,3) || is_path(p,3),str("Data must be a 3d point, path, region, vnf or bezier patch",p)) + : assert(is_vector(p,3) || is_path(p,3),str("Data must be a 3D point, path, region, vnf or bezier patch",p)) is_matrix(plane,3,3) ? assert(!is_collinear(plane),"Points defining the plane must not be collinear") let( @@ -285,13 +291,14 @@ function project_plane(plane,p) = // Function: lift_plane() +// Synopsis: Map a list of 2D points onto a plane in 3D. +// SynTags: Path +// Topics: Coordinates, Points, Paths +// See Also: project_plane() // Usage: // xyz = lift_plane(plane, p); // Usage: to get transform matrix // M = lift_plane(plane); -// Synopsis: Map a list of 2d points onto a plane in 3d. -// Topics: Coordinates, Points, Paths -// See Also: project_plane() // Description: // Converts the given 2D point on the plane to 3D coordinates of the specified plane. // The parameter p can be a point, path, region, bezier patch or VNF. @@ -327,7 +334,7 @@ function lift_plane(plane, p) = : is_vnf(p) ? [lift_plane(plane,p[0]), p[1]] : is_list(p) && is_list(p[0]) && is_vector(p[0][0],3) ? // bezier patch or region [for(plist=p) lift_plane(plane,plist)] - : assert(is_vector(p,2) || is_path(p,2),"Data must be a 2d point, path, region, vnf or bezier patch") + : assert(is_vector(p,2) || is_path(p,2),"Data must be a 2D point, path, region, vnf or bezier patch") is_matrix(plane,3,3) ? let( v = plane[2]-plane[0], @@ -338,13 +345,14 @@ function lift_plane(plane, p) = // Function: cylindrical_to_xyz() +// Synopsis: Convert cylindrical coordinates to cartesian coordinates. +// SynTags: Path +// Topics: Coordinates, Points, Paths +// See Also: xyz_to_cylindrical(), xy_to_polar(), polar_to_xy(), xyz_to_spherical(), spherical_to_xyz() // Usage: // pt = cylindrical_to_xyz(r, theta, z); // pt = cylindrical_to_xyz([RADIUS,THETA,Z]); // pts = cylindrical_to_xyz([[RADIUS,THETA,Z], [RADIUS,THETA,Z], ...]); -// Topics: Coordinates, Points, Paths -// See Also: xyz_to_cylindrical(), xy_to_polar(), polar_to_xy(), xyz_to_spherical(), spherical_to_xyz() -// Synopsis: Convert cylindrical coordinates to cartesian coordinates. // Description: // Called with three arguments, converts the `r`, `theta`, and 'z' 3D cylindrical coordinate into an `[X,Y,Z]` cartesian coordinate. // Called with one `[RADIUS,THETA,Z]` vector argument, converts the 3D cylindrical coordinate into an `[X,Y,Z]` cartesian coordinate. @@ -368,13 +376,13 @@ function cylindrical_to_xyz(r,theta,z) = // Function: xyz_to_cylindrical() +// Synopsis: Convert 3D cartesian coordinates to cylindrical coordinates. +// Topics: Coordinates, Points, Paths +// See Also: cylindrical_to_xyz(), xy_to_polar(), polar_to_xy(), xyz_to_spherical(), spherical_to_xyz() // Usage: // rtz = xyz_to_cylindrical(x,y,z); // rtz = xyz_to_cylindrical([X,Y,Z]); // rtzs = xyz_to_cylindrical([[X,Y,Z], [X,Y,Z], ...]); -// Topics: Coordinates, Points, Paths -// Synopsis: Convert 3d cartesian coordinates to cylindrical coordinates. -// See Also: cylindrical_to_xyz(), xy_to_polar(), polar_to_xy(), xyz_to_spherical(), spherical_to_xyz() // Description: // Called with three arguments, converts the `x`, `y`, and `z` 3D cartesian coordinate into a `[RADIUS,THETA,Z]` cylindrical coordinate. // Called with one `[X,Y,Z]` vector argument, converts the 3D cartesian coordinate into a `[RADIUS,THETA,Z]` cylindrical coordinate. @@ -399,6 +407,10 @@ function xyz_to_cylindrical(x,y,z) = // Function: spherical_to_xyz() +// Synopsis: Convert spherical coordinates to 3D cartesian coordinates. +// SynTags: Path +// Topics: Coordinates, Points, Paths +// See Also: cylindrical_to_xyz(), xyz_to_spherical(), xyz_to_cylindrical(), altaz_to_xyz(), xyz_to_altaz() // Usage: // pt = spherical_to_xyz(r, theta, phi); // pt = spherical_to_xyz([RADIUS,THETA,PHI]); @@ -408,9 +420,6 @@ function xyz_to_cylindrical(x,y,z) = // Called with one `[RADIUS,THETA,PHI]` vector argument, converts the 3D spherical coordinate into an `[X,Y,Z]` cartesian coordinate. // Called with a list of `[RADIUS,THETA,PHI]` vector arguments, converts each 3D spherical coordinate into `[X,Y,Z]` cartesian coordinates. // Theta is the angle counter-clockwise of X+ on the XY plane. Phi is the angle down from the Z+ pole. -// Synopsis: Convert spherical coordinates to 3d cartesian coordinates. -// Topics: Coordinates, Points, Paths -// See Also: cylindrical_to_xyz(), xyz_to_spherical(), xyz_to_cylindrical(), altaz_to_xyz(), xyz_to_altaz() // Arguments: // r = distance from origin. // theta = angle in degrees, counter-clockwise of X+ on the XY plane. @@ -435,7 +444,7 @@ function spherical_to_xyz(r,theta,phi) = // r_theta_phi = xyz_to_spherical([X,Y,Z]) // r_theta_phis = xyz_to_spherical([[X,Y,Z], [X,Y,Z], ...]) // Topics: Coordinates, Points, Paths -// Synopsis: Convert 3d cartesian coordinates to spherical coordinates. +// Synopsis: Convert 3D cartesian coordinates to spherical coordinates. // See Also: cylindrical_to_xyz(), spherical_to_xyz(), xyz_to_cylindrical(), altaz_to_xyz(), xyz_to_altaz() // Description: // Called with three arguments, converts the `x`, `y`, and `z` 3D cartesian coordinate into a `[RADIUS,THETA,PHI]` spherical coordinate. @@ -461,13 +470,14 @@ function xyz_to_spherical(x,y,z) = // Function: altaz_to_xyz() +// Synopsis: Convert altitude/azimuth/range to 3D cartesian coordinates. +// SynTags: Path +// Topics: Coordinates, Points, Paths +// See Also: cylindrical_to_xyz(), xyz_to_spherical(), spherical_to_xyz(), xyz_to_cylindrical(), xyz_to_altaz() // Usage: // pt = altaz_to_xyz(alt, az, r); // pt = altaz_to_xyz([ALT,AZ,R]); // pts = altaz_to_xyz([[ALT,AZ,R], [ALT,AZ,R], ...]); -// Topics: Coordinates, Points, Paths -// See Also: cylindrical_to_xyz(), xyz_to_spherical(), spherical_to_xyz(), xyz_to_cylindrical(), xyz_to_altaz() -// Synopsis: Convert altitude/azimuth/range to 3d cartesian coordinates. // Description: // Convert altitude/azimuth/range coordinates to 3D cartesian coordinates. // Called with three arguments, converts the `alt`, `az`, and 'r' 3D altitude-azimuth coordinate into an `[X,Y,Z]` cartesian coordinate. @@ -493,13 +503,13 @@ function altaz_to_xyz(alt,az,r) = // Function: xyz_to_altaz() +// Synopsis: Convert 3D cartesian coordinates to [altitude,azimuth,range]. +// Topics: Coordinates, Points, Paths +// See Also: cylindrical_to_xyz(), xyz_to_spherical(), spherical_to_xyz(), xyz_to_cylindrical(), altaz_to_xyz() // Usage: // alt_az_r = xyz_to_altaz(x,y,z); // alt_az_r = xyz_to_altaz([X,Y,Z]); // alt_az_rs = xyz_to_altaz([[X,Y,Z], [X,Y,Z], ...]); -// Topics: Coordinates, Points, Paths -// See Also: cylindrical_to_xyz(), xyz_to_spherical(), spherical_to_xyz(), xyz_to_cylindrical(), altaz_to_xyz() -// Synopsis: Convert 3d cartesian coordinates to [altitude,azimuth,range]. // Description: // Converts 3D cartesian coordinates to altitude/azimuth/range coordinates. // Called with three arguments, converts the `x`, `y`, and `z` 3D cartesian coordinate into an `[ALTITUDE,AZIMUTH,RANGE]` coordinate. diff --git a/cubetruss.scad b/cubetruss.scad index e0e16b9..822a41c 100644 --- a/cubetruss.scad +++ b/cubetruss.scad @@ -18,6 +18,7 @@ $cubetruss_clip_thickness = 1.6; // Module: cubetruss() // Synopsis: Creates a multi-cube straight cubetruss shape. +// SynTags: Geom // Topics: Trusses, CubeTruss, FDM Optimized, Parts // See Also: cubetruss_segment(), cubetruss_support(), cubetruss(), cubetruss_corner() // Usage: @@ -35,7 +36,6 @@ $cubetruss_clip_thickness = 1.6; // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#subsection-anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#subsection-spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#subsection-orient). Default: `UP` -// Topics: Attachable, Trusses // Examples: // cubetruss(extents=3); // cubetruss(extents=3, clips=FRONT); @@ -91,6 +91,7 @@ module cubetruss(extents=6, clips=[], bracing, size, strut, clipthick, anchor=CE // Module: cubetruss_corner() // Synopsis: Creates a multi-cube corner cubetruss shape. +// SynTags: Geom // Topics: Trusses, CubeTruss, FDM Optimized, Parts // See Also: cubetruss_segment(), cubetruss_support(), cubetruss(), cubetruss_corner() // Usage: @@ -108,7 +109,6 @@ module cubetruss(extents=6, clips=[], bracing, size, strut, clipthick, anchor=CE // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#subsection-anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#subsection-spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#subsection-orient). Default: `UP` -// Topics: Attachable, Trusses // Examples: // cubetruss_corner(extents=2); // cubetruss_corner(extents=2, h=2); @@ -167,6 +167,7 @@ module cubetruss_corner(h=1, extents=[1,1,0,0,1], bracing, size, strut, clipthic // Module: cubetruss_support() // Synopsis: Creates a cubetruss support structure shape. +// SynTags: Geom // Topics: Trusses, CubeTruss, FDM Optimized, Parts // See Also: cubetruss_segment(), cubetruss_support(), cubetruss(), cubetruss_corner() // Usage: @@ -181,7 +182,6 @@ module cubetruss_corner(h=1, extents=[1,1,0,0,1], bracing, size, strut, clipthic // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#subsection-anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#subsection-spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#subsection-orient). Default: `UP` -// Topics: Attachable, Trusses // Example(VPT=[0,0,0],VPD=150): // cubetruss_support(); // Example(VPT=[0,0,0],VPD=200): @@ -234,6 +234,7 @@ module cubetruss_support(size, strut, extents=1, anchor=CENTER, spin=0, orient=U // Module: cubetruss_foot() // Synopsis: Creates a foot that can connect two cubetrusses. +// SynTags: Geom // Topics: Trusses, CubeTruss, FDM Optimized, Parts // See Also: cubetruss_segment(), cubetruss_support(), cubetruss(), cubetruss_corner() // Usage: @@ -250,7 +251,6 @@ module cubetruss_support(size, strut, extents=1, anchor=CENTER, spin=0, orient=U // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#subsection-anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#subsection-spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#subsection-orient). Default: `UP` -// Topics: Attachable, Trusses // Examples: // cubetruss_foot(w=1); // cubetruss_foot(w=3); @@ -314,6 +314,7 @@ module cubetruss_foot(w=1, size, strut, clipthick, anchor=CENTER, spin=0, orient // Module: cubetruss_joiner() // Synopsis: Creates a joiner that can connect two cubetrusses end-to-end. +// SynTags: Geom // Topics: Trusses, CubeTruss, FDM Optimized, Parts // See Also: cubetruss_segment(), cubetruss_support(), cubetruss(), cubetruss_corner() // Usage: @@ -331,7 +332,6 @@ module cubetruss_foot(w=1, size, strut, clipthick, anchor=CENTER, spin=0, orient // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#subsection-anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#subsection-spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#subsection-orient). Default: `UP` -// Topics: Attachable, Trusses // Examples: // cubetruss_joiner(w=1, vert=false); // cubetruss_joiner(w=1, vert=true); @@ -385,6 +385,7 @@ module cubetruss_joiner(w=1, vert=true, size, strut, clipthick, anchor=CENTER, s // Module: cubetruss_uclip() // Synopsis: Creates a joiner that can connect two cubetrusses end-to-end. +// SynTags: Geom // Topics: Trusses, CubeTruss, FDM Optimized, Parts // See Also: cubetruss_segment(), cubetruss_support(), cubetruss(), cubetruss_corner() // Usage: @@ -401,7 +402,6 @@ module cubetruss_joiner(w=1, vert=true, size, strut, clipthick, anchor=CENTER, s // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#subsection-anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#subsection-spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#subsection-orient). Default: `UP` -// Topics: Attachable, Trusses // Examples: // cubetruss_uclip(dual=false); // cubetruss_uclip(dual=true); @@ -437,6 +437,7 @@ module cubetruss_uclip(dual=true, size, strut, clipthick, anchor=CENTER, spin=0, // Module: cubetruss_segment() // Synopsis: Creates a single cubetruss cube. +// SynTags: Geom // Topics: Trusses, CubeTruss, FDM Optimized, Parts // See Also: cubetruss_segment(), cubetruss_support(), cubetruss(), cubetruss_corner() // Usage: @@ -451,7 +452,6 @@ module cubetruss_uclip(dual=true, size, strut, clipthick, anchor=CENTER, spin=0, // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#subsection-anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#subsection-spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#subsection-orient). Default: `UP` -// Topics: Attachable, Trusses // Examples: // cubetruss_segment(bracing=false); // cubetruss_segment(bracing=true); @@ -509,6 +509,7 @@ module cubetruss_segment(size, strut, bracing, anchor=CENTER, spin=0, orient=UP) // Module: cubetruss_clip() // Synopsis: Creates a clip for the end of a cubetruss to snap-lock it to another cubetruss. +// SynTags: Geom // Topics: Trusses, CubeTruss, FDM Optimized, Parts // See Also: cubetruss_segment(), cubetruss_support(), cubetruss(), cubetruss_corner() // Usage: @@ -525,7 +526,6 @@ module cubetruss_segment(size, strut, bracing, anchor=CENTER, spin=0, orient=UP) // anchor = Translate so anchor point is at origin (0,0,0). See [anchor](attachments.scad#subsection-anchor). Default: `CENTER` // spin = Rotate this many degrees around the Z axis. See [spin](attachments.scad#subsection-spin). Default: `0` // orient = Vector to rotate top towards. See [orient](attachments.scad#subsection-orient). Default: `UP` -// Topics: Attachable, Trusses // Examples: // cubetruss_clip(extents=2); // cubetruss_clip(extents=1); @@ -588,7 +588,6 @@ module cubetruss_clip(extents=1, size, strut, clipthick, anchor=CENTER, spin=0, // gaps = The number of extra strut widths to add in, corresponding to each time a truss butts up against another. // size = The length of each side of the cubetruss cubes. Default: `$cubetruss_size` (usually 30) // strut = The width of the struts on the cubetruss cubes. Default: `$cubetruss_strut_size` (usually 3) -// Topics: Trusses function cubetruss_dist(cubes=0, gaps=0, size, strut) = let( size = is_undef(size)? $cubetruss_size : size, diff --git a/distributors.scad b/distributors.scad index 2aad458..d343c78 100644 --- a/distributors.scad +++ b/distributors.scad @@ -93,6 +93,7 @@ // Function&Module: move_copies() // Synopsis: Translates copies of all children. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Translation, Copiers // See Also: xcopies(), ycopies(), zcopies(), line_copies(), grid_copies(), rot_copies(), xrot_copies(), yrot_copies(), zrot_copies(), arc_copies(), sphere_copies() // @@ -145,6 +146,7 @@ function move_copies(a=[[0,0,0]],p=_NO_ARG) = // Function&Module: xcopies() // Synopsis: Places copies of children along the X axis. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Translation, Copiers // See Also: move_copies(), ycopies(), zcopies(), line_copies(), grid_copies(), rot_copies(), xrot_copies(), yrot_copies(), zrot_copies(), arc_copies(), sphere_copies() // @@ -230,6 +232,7 @@ function xcopies(spacing, n, l, sp, p=_NO_ARG) = // Function&Module: ycopies() // Synopsis: Places copies of children along the Y axis. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Translation, Copiers // See Also: move_copies(), xcopies(), zcopies(), line_copies(), grid_copies(), rot_copies(), xrot_copies(), yrot_copies(), zrot_copies(), arc_copies(), sphere_copies() // @@ -315,6 +318,7 @@ function ycopies(spacing, n, l, sp, p=_NO_ARG) = // Function&Module: zcopies() // Synopsis: Places copies of children along the Z axis. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Translation, Copiers // See Also: move_copies(), xcopies(), ycopies(), line_copies(), grid_copies(), rot_copies(), xrot_copies(), yrot_copies(), zrot_copies(), arc_copies(), sphere_copies() // @@ -415,6 +419,7 @@ function zcopies(spacing, n, l, sp, p=_NO_ARG) = // Function&Module: line_copies() // Synopsis: Places copies of children along an arbitrary line. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Translation, Copiers // See Also: move_copies(), xcopies(), ycopies(), zcopies(), rot_copies(), xrot_copies(), yrot_copies(), zrot_copies(), arc_copies(), sphere_copies() // @@ -548,6 +553,7 @@ function line_copies(spacing, n, l, p1, p2, p=_NO_ARG) = // Function&Module: grid_copies() // Synopsis: Places copies of children in an [X,Y] grid. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Translation, Copiers // See Also: move_copies(), xcopies(), ycopies(), zcopies(), line_copies(), rot_copies(), xrot_copies(), yrot_copies(), zrot_copies(), arc_copies(), sphere_copies() // @@ -771,6 +777,7 @@ function grid_copies(spacing, n, size, stagger=false, inside=undef, nonzero, p=_ // Function&Module: rot_copies() // Synopsis: Rotates copies of children. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Rotation, Copiers // See Also: rot_copies(), xrot_copies(), yrot_copies(), zrot_copies(), arc_copies(), sphere_copies(), move_copies(), xcopies(), ycopies(), zcopies(), line_copies(), grid_copies() // @@ -895,6 +902,7 @@ function rot_copies(rots=[], v, cp=[0,0,0], n, sa=0, offset=0, delta=[0,0,0], su // Function&Module: xrot_copies() // Synopsis: Rotates copies of children around the X axis. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Rotation, Copiers // See Also: rot_copies(), xrot_copies(), yrot_copies(), zrot_copies(), arc_copies(), sphere_copies(), move_copies(), xcopies(), ycopies(), zcopies(), line_copies(), grid_copies() // @@ -974,6 +982,7 @@ function xrot_copies(rots=[], cp=[0,0,0], n, sa=0, r, d, subrot=true, p=_NO_ARG) // Function&Module: yrot_copies() // Synopsis: Rotates copies of children around the Y axis. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Rotation, Copiers // See Also: rot_copies(), xrot_copies(), yrot_copies(), zrot_copies(), arc_copies(), sphere_copies(), move_copies(), xcopies(), ycopies(), zcopies(), line_copies(), grid_copies() // @@ -1053,6 +1062,7 @@ function yrot_copies(rots=[], cp=[0,0,0], n, sa=0, r, d, subrot=true, p=_NO_ARG) // Function&Module: zrot_copies() // Synopsis: Rotates copies of children around the Z axis. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Rotation, Copiers // See Also: rot_copies(), xrot_copies(), yrot_copies(), zrot_copies(), arc_copies(), sphere_copies(), move_copies(), xcopies(), ycopies(), zcopies(), line_copies(), grid_copies() // @@ -1132,6 +1142,7 @@ function zrot_copies(rots=[], cp=[0,0,0], n, sa=0, r, d, subrot=true, p=_NO_ARG) // Function&Module: arc_copies() // Synopsis: Distributes duplicates of children along an arc. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Rotation, Copiers // See Also: rot_copies(), xrot_copies(), yrot_copies(), zrot_copies(), sphere_copies(), move_copies(), xcopies(), ycopies(), zcopies(), line_copies(), grid_copies() // @@ -1256,6 +1267,7 @@ function arc_copies( // Function&Module: sphere_copies() // Synopsis: Distributes copies of children over the surface of a sphere. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Rotation, Copiers // See Also: rot_copies(), xrot_copies(), yrot_copies(), zrot_copies(), arc_copies(), move_copies(), xcopies(), ycopies(), zcopies(), line_copies(), grid_copies() // @@ -1363,6 +1375,7 @@ function sphere_copies(n=100, r=undef, d=undef, cone_ang=90, scale=[1,1,1], perp // Function&Module: path_copies() // Synopsis: Uniformly distributes copies of children along a path. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Copiers // See Also: line_copies(), move_copies(), xcopies(), ycopies(), zcopies(), grid_copies(), xflip_copy(), yflip_copy(), zflip_copy(), mirror_copy() // @@ -1576,6 +1589,7 @@ function path_copies(path, n, spacing, sp=undef, dist, rotate_children=true, dis // Function&Module: xflip_copy() // Synopsis: Makes a copy of children mirrored across the X axis. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Translation, Copiers // See Also: yflip_copy(), zflip_copy(), mirror_copy(), path_copies(), move_copies(), xcopies(), ycopies(), zcopies(), line_copies(), grid_copies() // @@ -1626,6 +1640,7 @@ function xflip_copy(offset=0, x=0, p=_NO_ARG) = // Function&Module: yflip_copy() // Synopsis: Makes a copy of children mirrored across the Y axis. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Translation, Copiers // See Also: xflip_copy(), zflip_copy(), mirror_copy(), path_copies(), move_copies(), xcopies(), ycopies(), zcopies(), line_copies(), grid_copies() // @@ -1676,6 +1691,7 @@ function yflip_copy(offset=0, y=0, p=_NO_ARG) = // Function&Module: zflip_copy() // Synopsis: Makes a copy of children mirrored across the Z axis. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Translation, Copiers // See Also: xflip_copy(), yflip_copy(), mirror_copy(), path_copies(), move_copies(), xcopies(), ycopies(), zcopies(), line_copies(), grid_copies() // @@ -1726,6 +1742,7 @@ function zflip_copy(offset=0, z=0, p=_NO_ARG) = // Function&Module: mirror_copy() // Synopsis: Makes a copy of children mirrored across a given plane. +// SynTags: MatList, Trans // Topics: Transformations, Distributors, Translation, Copiers // See Also: xflip_copy(), yflip_copy(), zflip_copy(), path_copies(), move_copies(), xcopies(), ycopies(), zcopies(), line_copies(), grid_copies() // @@ -1815,6 +1832,14 @@ function mirror_copy(v=[0,0,1], offset=0, cp, p=_NO_ARG) = // Section: Distributing children individually along a line /////////////////// // Module: xdistribute() +// Synopsis: Distributes each child, individually, out along the X axis. +// SynTags: Trans +// See Also: xdistribute(), ydistribute(), zdistribute(), distribute() +// +// Usage: +// xdistribute(spacing, [sizes]) CHILDREN; +// xdistribute(l=, [sizes=]) CHILDREN; +// // // Description: // Spreads out the children individually along the X axis. @@ -1822,10 +1847,6 @@ function mirror_copy(v=[0,0,1], offset=0, cp, p=_NO_ARG) = // This is useful for laying out groups of disparate objects // where you only really care about the spacing between them. // -// Usage: -// xdistribute(spacing, [sizes]) CHILDREN; -// xdistribute(l=, [sizes=]) CHILDREN; -// // Arguments: // spacing = spacing between each child. (Default: 10.0) // sizes = Array containing how much space each child will need. @@ -1861,6 +1882,13 @@ module xdistribute(spacing=10, sizes=undef, l=undef) // Module: ydistribute() +// Synopsis: Distributes each child, individually, out along the Y axis. +// SynTags: Trans +// See Also: xdistribute(), ydistribute(), zdistribute(), distribute() +// +// Usage: +// ydistribute(spacing, [sizes]) CHILDREN; +// ydistribute(l=, [sizes=]) CHILDREN; // // Description: // Spreads out the children individually along the Y axis. @@ -1868,10 +1896,6 @@ module xdistribute(spacing=10, sizes=undef, l=undef) // This is useful for laying out groups of disparate objects // where you only really care about the spacing between them. // -// Usage: -// ydistribute(spacing, [sizes]) CHILDREN; -// ydistribute(l=, [sizes=]) CHILDREN; -// // Arguments: // spacing = spacing between each child. (Default: 10.0) // sizes = Array containing how much space each child will need. @@ -1907,6 +1931,13 @@ module ydistribute(spacing=10, sizes=undef, l=undef) // Module: zdistribute() +// Synopsis: Distributes each child, individually, out along the Z axis. +// SynTags: Trans +// See Also: xdistribute(), ydistribute(), zdistribute(), distribute() +// +// Usage: +// zdistribute(spacing, [sizes]) CHILDREN; +// zdistribute(l=, [sizes=]) CHILDREN; // // Description: // Spreads out each individual child along the Z axis. @@ -1914,10 +1945,6 @@ module ydistribute(spacing=10, sizes=undef, l=undef) // This is useful for laying out groups of disparate objects // where you only really care about the spacing between them. // -// Usage: -// zdistribute(spacing, [sizes]) CHILDREN; -// zdistribute(l=, [sizes=]) CHILDREN; -// // Arguments: // spacing = spacing between each child. (Default: 10.0) // sizes = Array containing how much space each child will need. @@ -1954,6 +1981,13 @@ module zdistribute(spacing=10, sizes=undef, l=undef) // Module: distribute() +// Synopsis: Distributes each child, individually, out along an arbitrary line. +// SynTags: Trans +// See Also: xdistribute(), ydistribute(), zdistribute(), distribute() +// +// Usage: +// distribute(spacing, sizes, dir) CHILDREN; +// distribute(l=, [sizes=], [dir=]) CHILDREN; // // Description: // Spreads out the children individually along the direction `dir`. @@ -1961,10 +1995,6 @@ module zdistribute(spacing=10, sizes=undef, l=undef) // This is useful for laying out groups of disparate objects // where you only really care about the spacing between them. // -// Usage: -// distribute(spacing, sizes, dir) CHILDREN; -// distribute(l=, [sizes=], [dir=]) CHILDREN; -// // Arguments: // spacing = Spacing to add between each child. (Default: 10.0) // sizes = Array containing how much space each child will need. diff --git a/drawing.scad b/drawing.scad index 70f519d..14c5a06 100644 --- a/drawing.scad +++ b/drawing.scad @@ -18,6 +18,7 @@ // Module: stroke() // Synopsis: Draws a line along a path or region boundry. +// SynTags: Geom // Topics: Paths (2D), Paths (3D), Drawing Tools // See Also: offset_stroke(), path_sweep() // Usage: @@ -588,6 +589,7 @@ module stroke( // Function&Module: dashed_stroke() // Synopsis: Draws a dashed line along a path or region boundry. +// SynTags: Geom, PathList // Topics: Paths, Drawing Tools // See Also: stroke(), path_cut() // Usage: As a Module @@ -666,7 +668,9 @@ module dashed_stroke(path, dashpat=[3,3], width=1, closed=false, fit=true, round // Function&Module: arc() // Synopsis: Draws a 2D pie-slice or returns 2D or 3D path forming an arc. +// SynTags: Geom, Path // Topics: Paths (2D), Paths (3D), Shapes (2D), Path Generators +// See Also: pie_slice(), stroke() // // Usage: 2D arc from 0ยบ to `angle` degrees. // path=arc(n, r|d=, angle); @@ -860,7 +864,9 @@ module arc(n, r, angle, d, cp, points, corner, width, thickness, start, wedge=fa // Function: helix() // Synopsis: Creates a 2d spiral or 3d helical path. +// SynTags: Path // Topics: Path Generators, Paths, Drawing Tools +// See Also: pie_slice(), stroke(), thread_helix(), path_sweep() // // Usage: // path = helix(l|h, [turns=], [angle=], r=|r1=|r2=, d=|d1=|d2=); @@ -915,10 +921,11 @@ function _normal_segment(p1,p2) = // Function: turtle() // Synopsis: Uses [turtle graphics](https://en.wikipedia.org/wiki/Turtle_graphics) to generate a 2D path. +// SynTags: Path // Topics: Shapes (2D), Path Generators (2D), Mini-Language -// See Also: turtle3d() +// See Also: turtle3d(), stroke(), path_sweep() // Usage: -// turtle(commands, [state], [full_state=], [repeat=]) +// path = turtle(commands, [state], [full_state=], [repeat=]) // Description: // Use a sequence of [turtle graphics]{https://en.wikipedia.org/wiki/Turtle_graphics} commands to generate a path. The parameter `commands` is a list of // turtle commands and optional parameters for each command. The turtle state has a position, movement direction, @@ -1178,7 +1185,9 @@ function _turtle_command(command, parm, parm2, state, index) = // Module: debug_polygon() // Synopsis: Draws an annotated polygon. +// SynTags: Geom // Topics: Shapes (2D) +// See Also: debug_vnf(), debug_bezier() // // Usage: // debug_polygon(points, paths, [vertices=], [edges=], [convexity=], [size=]); diff --git a/gears.scad b/gears.scad index 6461cd6..ab8f687 100644 --- a/gears.scad +++ b/gears.scad @@ -27,6 +27,7 @@ // Function&Module: spur_gear() // Synopsis: Creates a spur gear shape. +// SynTags: Geom, VNF // Topics: Gears, Parts // See Also: rack(), spur_gear(), spur_gear2d(), bevel_gear() // Usage: As a Module @@ -193,6 +194,7 @@ module spur_gear( // Function&Module: spur_gear2d() // Synopsis: Creates a 2D spur gear shape. +// SynTags: Geom, Path // Topics: Gears, Parts // See Also: rack(), spur_gear(), spur_gear2d(), bevel_gear() // Usage: As Module @@ -294,6 +296,7 @@ module spur_gear2d( // Function&Module: rack() // Synopsis: Creates a gear rack shape. +// SynTags: Geom, VNF // Topics: Gears, Parts // See Also: rack2d(), spur_gear(), spur_gear2d(), bevel_gear() // Usage: As a Module @@ -443,6 +446,7 @@ function rack( // Function&Module: rack2d() // Synopsis: Creates a 2D gear rack shape. +// SynTags: Geom, Path // Topics: Gears, Parts // See Also: rack(), spur_gear(), spur_gear2d(), bevel_gear() // Usage: As a Module @@ -566,6 +570,7 @@ module rack2d( // Function&Module: bevel_gear() // Synopsis: Creates a possibly spiral beveled gear shape. +// SynTags: Geom, VNF // Topics: Gears, Parts // See Also: rack(), rack2d(), spur_gear(), spur_gear2d(), bevel_pitch_angle(), bevel_gear() // Usage: As a Module @@ -826,6 +831,7 @@ module bevel_gear( // Function&Module: worm() // Synopsis: Creates a worm shape that will mate with a worm gear. +// SynTags: Geom, VNF // Topics: Gears, Parts // See Also: worm(), worm_gear(), rack(), rack2d(), spur_gear(), spur_gear2d(), bevel_pitch_angle(), bevel_gear() // Usage: As a Module @@ -946,6 +952,7 @@ module worm( // Function&Module: worm_gear() // Synopsis: Creates a worm gear shape that will mate with a worm. +// SynTags: Geom, VNF // Topics: Gears, Parts // See Also: worm(), worm_gear(), rack(), rack2d(), spur_gear(), spur_gear2d(), bevel_pitch_angle(), bevel_gear() // Usage: As a Module diff --git a/geometry.scad b/geometry.scad index f976ac1..aa5c067 100644 --- a/geometry.scad +++ b/geometry.scad @@ -15,10 +15,11 @@ // Section: Lines, Rays, and Segments // Function: is_point_on_line() +// Synopsis: Determine if a point is on a line, ray or segment. +// Topics: Geometry, Points, Segments +// See Also: is_collinear(), is_point_on_line(), point_line_distance(), line_from_points() // Usage: // pt = is_point_on_line(point, line, [bounded], [eps]); -// Topics: Geometry, Points, Segments -// Synopsis: Determine if a point is on a line, ray or segment. // Description: // Determine if the point is on the line segment, ray or segment defined by the two between two points. // Returns true if yes, and false if not. If bounded is set to true it specifies a segment, with @@ -140,10 +141,11 @@ function _point_left_of_line2d(point, line, eps=EPSILON) = // Function: is_collinear() +// Synopsis: Determine if points are collinear. +// Topics: Geometry, Points, Collinearity +// See Also: is_collinear(), is_point_on_line(), point_line_distance(), line_from_points() // Usage: // bool = is_collinear(a, [b, c], [eps]); -// Synopsis: Determine if a points are collinear. -// 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: @@ -162,10 +164,11 @@ function is_collinear(a, b, c, eps=EPSILON) = // Function: point_line_distance() +// Synopsis: Find shortest distance from point to a line, segment or ray. +// Topics: Geometry, Points, Lines, Distance +// See Also: is_collinear(), is_point_on_line(), point_line_distance(), line_from_points() // Usage: // dist = point_line_distance(line, pt, [bounded]); -// Topics: Geometry, Points, Lines, Distance -// Synopsis: Find shortest distance from point to a line, segment or ray. // Description: // Finds the shortest distance from the point `pt` to the specified line, segment or ray. // The bounded parameter specifies the whether the endpoints give a ray or segment. @@ -187,11 +190,11 @@ function point_line_distance(pt, line, bounded=false) = // Function: segment_distance() -// Usage: -// dist = segment_distance(seg1, seg2, [eps]); +// Synopsis: Find smallest distance between two line semgnets. // Topics: Geometry, Segments, Distance // See Also: convex_collision(), convex_distance() -// Synopsis: Find smallest distance between two line semgnets. +// Usage: +// dist = segment_distance(seg1, seg2, [eps]); // Description: // Returns the smallest distance of the points on two given line segments. // Arguments: @@ -207,13 +210,14 @@ function segment_distance(seg1, seg2,eps=EPSILON) = // Function: line_normal() +// Synopsis: Return normal vector to given line. +// Topics: Geometry, Lines +// See Also: line_intersection(), line_from_points() // Usage: // 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. -// Synopsis: Return normal vector to given line. // Arguments: // p1 = First point on 2D line. // p2 = Second point on 2D line. @@ -255,9 +259,11 @@ function _general_line_intersection(s1,s2,eps=EPSILON) = // Function: line_intersection() +// Synopsis: Compute intersection of two lines, segments or rays. +// Topics: Geometry, Lines +// See Also: line_normal(), line_from_points() // Usage: // pt = line_intersection(line1, line2, [bounded1], [bounded2], [bounded=], [eps=]); -// Synopsis: Compute intersection of two lines, segments or rays. // Description: // Returns the intersection point of any two 2D lines, segments or rays. Returns undef // if they do not intersect. You specify a line by giving two distinct points on the @@ -316,10 +322,11 @@ function line_intersection(line1, line2, bounded1, bounded2, bounded, eps=EPSILO // Function: line_closest_point() +// Synopsis: Find point on given line, segment or ray that is closest to a given point. +// Topics: Geometry, Lines, Distance +// See Also: line_normal(), point_line_distance() // Usage: // pt = line_closest_point(line, pt, [bounded]); -// Topics: Geometry, Lines, Distance -// Synopsis: Find point on given line, segment or ray that is closest to a given point. // Description: // Returns the point on the given line, segment or ray that is closest to the given point `pt`. // The inputs `line` and `pt` args should be of the same dimension. The parameter bounded indicates @@ -401,10 +408,10 @@ function line_closest_point(line, pt, bounded=false) = // Function: line_from_points() -// Usage: -// line = line_from_points(points, [fast], [eps]); // Synopsis: Given a list of collinear points, return the line they define. // Topics: Geometry, Lines, Points +// Usage: +// line = line_from_points(points, [fast], [eps]); // Description: // Given a list of 2 or more collinear points, returns two points defining a line containing them. // If `fast` is false and the points are coincident or non-collinear, then `undef` is returned. @@ -428,10 +435,11 @@ function line_from_points(points, fast=false, eps=EPSILON) = // Function: is_coplanar() +// Synopsis: Check if 3d points are coplanar and not collinear. +// Topics: Geometry, Coplanarity +// See Also: plane3pt(), plane3pt_indexed(), plane_from_normal(), plane_from_points(), plane_from_polygon() // Usage: // bool = is_coplanar(points,[eps]); -// Topics: Geometry, Coplanarity -// Synopsis: Check if 3d points are coplanar and not collinear. // Description: // Returns true if the given 3D points are non-collinear and are on a plane. // Arguments: @@ -449,11 +457,12 @@ function is_coplanar(points, eps=EPSILON) = // Function: plane3pt() +// Synopsis: Return a plane from 3 points. +// Topics: Geometry, Planes +// See Also: plane3pt(), plane3pt_indexed(), plane_from_normal(), plane_from_points(), plane_from_polygon() // Usage: // plane = plane3pt(p1, p2, p3); // plane = plane3pt([p1, p2, p3]); -// Topics: Geometry, Planes -// Synopsis: Return a plane from 3 points. // 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. @@ -474,10 +483,11 @@ function plane3pt(p1, p2, p3) = // Function: plane3pt_indexed() +// Synopsis: Given list of 3d points and 3 indices, return the plane they define. +// Topics: Geometry, Planes +// See Also: plane3pt(), plane3pt_indexed(), plane_from_normal(), plane_from_points(), plane_from_polygon() // Usage: // plane = plane3pt_indexed(points, i1, i2, i3); -// Topics: Geometry, Planes -// Synopsis: Given list of 3d points and 3 indices, return the plane they define. // 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 @@ -503,10 +513,11 @@ function plane3pt_indexed(points, i1, i2, i3) = // Function: plane_from_normal() -// Usage: -// plane = plane_from_normal(normal, [pt]) // Synopsis: Return plane defined by normal vector and a point. // Topics: Geometry, Planes +// See Also: plane3pt(), plane3pt_indexed(), plane_from_normal(), plane_from_points(), plane_from_polygon() +// Usage: +// plane = plane_from_normal(normal, [pt]) // Description: // Returns a plane defined by a normal vector and a point. If you omit `pt` you will get a plane // passing through the origin. @@ -564,11 +575,11 @@ function _covariance_evec_eval(points) = // Function: plane_from_points() -// Usage: -// plane = plane_from_points(points, [fast], [eps]); // Synopsis: Return plane defined by a set of coplanar 3d points, with arbitrary normal direction. // Topics: Geometry, Planes, Points -// See Also: plane_from_polygon() +// See Also: plane3pt(), plane3pt_indexed(), plane_from_normal(), plane_from_points(), plane_from_polygon() +// Usage: +// plane = plane_from_points(points, [fast], [eps]); // 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. @@ -603,11 +614,11 @@ function plane_from_points(points, fast=false, eps=EPSILON) = // Function: plane_from_polygon() -// Usage: -// plane = plane_from_polygon(points, [fast], [eps]); // Synopsis: Given a 3d planar polygon, returns directed plane. // Topics: Geometry, Planes, Polygons -// See Also: plane_from_points() +// See Also: plane3pt(), plane3pt_indexed(), plane_from_normal(), plane_from_points(), plane_from_polygon() +// Usage: +// plane = plane_from_polygon(points, [fast], [eps]); // 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. @@ -640,10 +651,11 @@ function plane_from_polygon(poly, fast=false, eps=EPSILON) = // Function: plane_normal() +// Synopsis: Returns the normal vector to a plane. +// Topics: Geometry, Planes +// See Also: plane3pt(), plane3pt_indexed(), plane_from_normal(), plane_from_points(), plane_from_polygon(), plane_normal(), plane_offset() // Usage: // vec = plane_normal(plane); -// Topics: Geometry, Planes -// Synopsis: Returns the normal vector to a plane. // Description: // Returns the unit length normal vector for the given plane. // Arguments: @@ -654,10 +666,11 @@ function plane_normal(plane) = // Function: plane_offset() +// Synopsis: Returns the signed offset of the plane from the origin. +// Topics: Geometry, Planes +// See Also: plane3pt(), plane3pt_indexed(), plane_from_normal(), plane_from_points(), plane_from_polygon(), plane_normal(), plane_offset() // Usage: // d = plane_offset(plane); -// Topics: Geometry, Planes -// Synopsis: Returns the signed offset of the plane from the origin. // 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. @@ -686,21 +699,22 @@ function _general_plane_line_intersection(plane, line, eps=EPSILON) = /// Internal Function: normalize_plane() -// Usage: -// nplane = normalize_plane(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. +/// Description: +/// Returns a new representation [A,B,C,D] of `plane` where norm([A,B,C]) is equal to one. function _normalize_plane(plane) = assert( _valid_plane(plane), str("Invalid plane. ",plane ) ) plane/norm(point3d(plane)); // Function: plane_line_intersection() +// Synopsis: Returns the intersection of a plane and 3d line, segment or ray. +// Topics: Geometry, Planes, Lines, Intersection +// See Also: plane3pt(), plane_from_normal(), plane_from_points(), plane_from_polygon(), line_intersection() // Usage: // pt = plane_line_intersection(plane, line, [bounded], [eps]); -// Topics: Geometry, Planes, Lines, Intersection -// Synopsis: Returns the intersection of a plane and 3d line, segment or ray. // 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. @@ -727,11 +741,12 @@ function plane_line_intersection(plane, line, bounded=false, eps=EPSILON) = // Function: plane_intersection() +// Synopsis: Returns the intersection of two or three planes. +// Topics: Geometry, Planes, Intersection +// See Also: plane3pt(), plane_from_normal(), plane_from_points(), plane_from_polygon(), line_intersection() // Usage: // line = plane_intersection(plane1, plane2) // pt = plane_intersection(plane1, plane2, plane3) -// Topics: Geometry, Planes, Intersection -// Synopsis: Returns the intersection of two or three planes. // 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 @@ -763,10 +778,11 @@ function plane_intersection(plane1,plane2,plane3) = // Function: plane_line_angle() +// Synopsis: Returns the angle between a plane and a 3d line. +// Topics: Geometry, Planes, Lines, Angle +// See Also: plane3pt(), plane_from_normal(), plane_from_points(), plane_from_polygon(), plane_intersection(), line_intersection(), vector_angle() // Usage: // angle = plane_line_angle(plane,line); -// Topics: Geometry, Planes, Lines, Angle -// Synopsis: Returns the angle between a plane and a 3d line. // 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 above the plane, on @@ -784,10 +800,11 @@ function plane_line_angle(plane, line) = // Function: plane_closest_point() +// Synopsis: Returns the orthogonal projection of points onto a plane. +// Topics: Geometry, Planes, Projection +// See Also: plane3pt(), line_closest_point(), point_plane_distance() // Usage: // pts = plane_closest_point(plane, points); -// Topics: Geometry, Planes, Projection -// Synopsis: Returns the orthogonal projection of points onto a plane. // Description: // Given a plane definition `[A,B,C,D]`, where `Ax+By+Cz=D`, and a list of 2d or // 3d points, return the closest 3D orthogonal projection of the points on the plane. @@ -820,10 +837,11 @@ function plane_closest_point(plane, points) = // Function: point_plane_distance() +// Synopsis: Determine distance between a point and plane. +// Topics: Geometry, Planes, Distance +// See Also: plane3pt(), line_closest_point(), plane_closest_point() // Usage: // dist = point_plane_distance(plane, point) -// Topics: Geometry, Planes, Distance -// Synopsis: Determine distance between a point and plane. // 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. @@ -852,10 +870,11 @@ function _pointlist_greatest_distance(points,plane) = // Function: are_points_on_plane() +// Synopsis: Determine if all of the listed points are on a plane. +// Topics: Geometry, Planes, Points +// See Also: plane3pt(), line_closest_point(), plane_closest_point(), is_coplanar() // Usage: // bool = are_points_on_plane(points, plane, [eps]); -// Topics: Geometry, Planes, Points -// Synopsis: Determine if all of the listed points are on a plane. // Description: // Returns true if the given 3D points are on the given plane. // Arguments: @@ -889,10 +908,11 @@ function _is_point_above_plane(plane, point) = // Section: Circle Calculations // Function: circle_line_intersection() -// Usage: -// pts = circle_line_intersection(r|d=, cp, line, [bounded], [eps=]); // Synopsis: Find the intersection points between a 2d circle and a line, ray or segment. // Topics: Geometry, Circles, Lines, Intersection +// See Also: circle_line_intersection(), circle_circle_intersection(), circle_2tangents(), circle_3points(), circle_point_tangents(), circle_circle_tangents() +// Usage: +// pts = circle_line_intersection(r|d=, cp, line, [bounded], [eps=]); // Description: // Find intersection points between a 2D circle and a line, ray or segment specified by two points. // By default the line is unbounded. Returns the list of zero or more intersection points. @@ -963,10 +983,11 @@ function _circle_or_sphere_line_intersection(r, cp, line, bounded=false, d, eps= // Function: circle_circle_intersection() -// Usage: -// pts = circle_circle_intersection(r1|d1=, cp1, r2|d2=, cp2, [eps]); // Synopsis: Find the intersection points of two 2d circles. // Topics: Geometry, Circles +// See Also: circle_line_intersection(), circle_circle_intersection(), circle_2tangents(), circle_3points(), circle_point_tangents(), circle_circle_tangents() +// Usage: +// pts = circle_circle_intersection(r1|d1=, cp1, r2|d2=, cp2, [eps]); // Description: // Compute the intersection points of two circles. Returns a list of the intersection points, which // will contain two points in the general case, one point for tangent circles, or will be empty @@ -1030,11 +1051,12 @@ function circle_circle_intersection(r1, cp1, r2, cp2, eps=EPSILON, d1, d2) = // Function: circle_2tangents() +// Synopsis: Given two 2d or 3d rays, find a circle tangent to both. +// Topics: Geometry, Circles, Tangents +// See Also: circle_line_intersection(), circle_circle_intersection(), circle_2tangents(), circle_3points(), circle_point_tangents(), circle_circle_tangents() // Usage: // circ = circle_2tangents(r|d=, pt1, pt2, pt3, [tangents=]); // circ = circle_2tangents(r|d=, [PT1, PT2, PT3], [tangents=]); -// Topics: Geometry, Circles, Tangents -// Synopsis: Given two 2d or 3d rays, find a circle tangent to both. // Description: // Given a pair of 2d or 3d rays with a common origin, and a known circle radius/diameter, finds // the centerpoint for the circle of that size that touches both rays tangentally. @@ -1131,11 +1153,12 @@ function circle_2tangents(r, pt1, pt2, pt3, tangents=false, d) = // Function: circle_3points() +// Synopsis: Find a circle passing through three 2d or 3d points. +// Topics: Geometry, Circles +// See Also: circle_line_intersection(), circle_circle_intersection(), circle_2tangents(), circle_3points(), circle_point_tangents(), circle_circle_tangents() // Usage: // circ = circle_3points(pt1, pt2, pt3); // circ = circle_3points([PT1, PT2, PT3]); -// Topics: Geometry, Circles -// Synopsis: Find a circle passing through three 2d or 3d points. // Description: // Returns the [CENTERPOINT, RADIUS, NORMAL] of the circle that passes through three non-collinear // points where NORMAL is the normal vector of the plane that the circle is on (UP or DOWN if the points are 2D). @@ -1183,10 +1206,11 @@ function circle_3points(pt1, pt2, pt3) = // Function: circle_point_tangents() +// Synopsis: Given a circle and point, find tangents to circle passing through the point. +// Topics: Geometry, Circles, Tangents +// See Also: circle_line_intersection(), circle_circle_intersection(), circle_2tangents(), circle_3points(), circle_point_tangents(), circle_circle_tangents() // Usage: // tangents = circle_point_tangents(r|d=, cp, pt); -// Topics: Geometry, Circles, Tangents -// Synopsis: Given a circle and point, find tangents to circle passing through the point. // 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. @@ -1220,10 +1244,11 @@ function circle_point_tangents(r, cp, pt, d) = // Function: circle_circle_tangents() +// Synopsis: Find tangents to a pair of circles in 2d. +// Topics: Geometry, Circles, Tangents +// See Also: circle_line_intersection(), circle_circle_intersection(), circle_2tangents(), circle_3points(), circle_point_tangents(), circle_circle_tangents() // Usage: // segs = circle_circle_tangents(r1|d1=, cp1, r2|d2=, cp2); -// Topics: Geometry, Circles, Tangents -// Synopsis: Find tangents to a pair of circles in 2d. // Description: // Computes 2d lines tangents to a pair of circles in 2d. Returns a list of line endpoints [p1,p2] where // p1 is the tangent point on circle 1 and p2 is the tangent point on circle 2. @@ -1346,10 +1371,11 @@ function _noncollinear_triple(points,error=true,eps=EPSILON) = // Function: sphere_line_intersection() +// Synopsis: Find intersection between a sphere and line, ray or segment. +// Topics: Geometry, Spheres, Lines, Intersection +// See Also: circle_line_intersection(), circle_circle_intersection(), circle_2tangents(), circle_3points(), circle_point_tangents(), circle_circle_tangents() // Usage: // isect = sphere_line_intersection(r|d=, cp, line, [bounded], [eps=]); -// Topics: Geometry, Spheres, Lines, Intersection -// Synopsis: Find intersection between a sphere and line, ray or segment. // Description: // Find intersection points between a sphere and a line, ray or segment specified by two points. // By default the line is unbounded. @@ -1379,10 +1405,11 @@ function sphere_line_intersection(r, cp, line, bounded=false, d, eps=EPSILON) = // Section: Polygons // Function: polygon_area() +// Synopsis: Calculate area of a 2d or 3d polygon. +// Topics: Geometry, Polygons, Area +// See Also: polygon_area(), centroid(), polygon_normal(), point_in_polygon(), polygon_line_intersection() // Usage: // area = polygon_area(poly, [signed]); -// Topics: Geometry, Polygons, Area -// Synopsis: Calculate area of a 2d or 3d polygon. // Description: // Given a 2D or 3D simple planar polygon, returns the area of that polygon. // If the polygon is non-planar the result is `undef.` If the polygon is self-intersecting @@ -1414,10 +1441,11 @@ function polygon_area(poly, signed=false) = // Function: centroid() +// Synopsis: Compute centroid of a 2d or 3d polygon or a VNF. +// Topics: Geometry, Polygons, Centroid +// See Also: polygon_area(), centroid(), polygon_normal(), point_in_polygon(), polygon_line_intersection() // Usage: // c = centroid(object, [eps]); -// Topics: Geometry, Polygons, Centroid -// Synopsis: Compute centroid of a 2d or 3d polygon or a VNF. // 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. @@ -1500,10 +1528,11 @@ function _polygon_centroid(poly, eps=EPSILON) = // Function: polygon_normal() +// Synopsis: Return normal to a polygon. +// Topics: Geometry, Polygons +// See Also: polygon_area(), centroid(), polygon_normal(), point_in_polygon(), polygon_line_intersection() // Usage: // vec = polygon_normal(poly); -// Topics: Geometry, Polygons -// Synopsis: Return normal to a polygon. // Description: // Given a 3D simple planar polygon, returns a unit normal vector for the polygon. The vector // is oriented so that if the normal points towards the viewer, the polygon winds in the clockwise @@ -1529,10 +1558,11 @@ function polygon_normal(poly) = // Function: point_in_polygon() +// Synopsis: Checks if a 2d point is inside or on the boundary of a 2d polygon. +// Topics: Geometry, Polygons +// See Also: polygon_area(), centroid(), polygon_normal(), point_in_polygon(), polygon_line_intersection() // Usage: // bool = point_in_polygon(point, poly, [nonzero], [eps]) -// Topics: Geometry, Polygons -// Synopsis: Checks if a 2d point is inside or on the boundary of a 2d polygon. // Description: // This function tests whether the given 2D point is inside, outside or on the boundary of // the specified 2D polygon. @@ -1673,10 +1703,11 @@ function point_in_polygon(point, poly, nonzero=false, eps=EPSILON) = // Function: polygon_line_intersection() +// Synopsis: Find intersection between 2d or 3d polygon and a line, segment or ray. +// Topics: Geometry, Polygons, Lines, Intersection +// See Also: polygon_area(), centroid(), polygon_normal(), point_in_polygon(), polygon_line_intersection() // Usage: // pt = polygon_line_intersection(poly, line, [bounded], [nonzero], [eps]); -// Topics: Geometry, Polygons, Lines, Intersection -// Synopsis: Find intersection between 2d or 3d polygon and a line, segment or ray. // Description: // Takes a possibly bounded line, and a 2D or 3D planar polygon, and finds their intersection. Note the polygon is // treated as its boundary and interior, so the intersection may include both points and line segments. @@ -1860,9 +1891,11 @@ function _merge_segments(insegs,outsegs, eps, i=1) = // Function: polygon_triangulate() +// Synopsis: Divide a polygon into triangles. +// Topics: Geometry, Triangulation +// See Also: vnf_triangulate() // Usage: // triangles = polygon_triangulate(poly, [ind], [error], [eps]) -// Synopsis: Divide a polygon into triangles. // Description: // Given a simple polygon in 2D or 3D, triangulates it and returns a list // of triples indexing into the polygon vertices. When the optional argument `ind` is @@ -2049,11 +2082,11 @@ function _none_inside(idxs,poly,p0,p1,p2,eps,i=0) = // Function: is_polygon_clockwise() -// Usage: -// bool = is_polygon_clockwise(poly); +// Synopsis: Determine if a 2d polygon winds clockwise. // Topics: Geometry, Polygons, Clockwise // See Also: clockwise_polygon(), ccw_polygon(), reverse_polygon() -// Synopsis: Determine if a 2d polygon winds clockwise. +// Usage: +// bool = is_polygon_clockwise(poly); // Description: // Return true if the given 2D simple polygon is in clockwise order, false otherwise. // Results for complex (self-intersecting) polygon are indeterminate. @@ -2076,11 +2109,11 @@ function is_polygon_clockwise(poly) = // Function: clockwise_polygon() +// Synopsis: Return clockwise version of a polygon. +// Topics: Geometry, Polygons, Clockwise +// See Also: is_polygon_clockwise(), ccw_polygon(), reverse_polygon() // Usage: // newpoly = clockwise_polygon(poly); -// Topics: Geometry, Polygons, Clockwise -// Synopsis: Return clockwise version of a polygon. -// See Also: is_polygon_clockwise(), ccw_polygon(), reverse_polygon() // Description: // Given a 2D polygon path, returns the clockwise winding version of that path. // Arguments: @@ -2091,11 +2124,11 @@ function clockwise_polygon(poly) = // Function: ccw_polygon() +// Synopsis: Return counter-clockwise version of a polygon. +// Topics: Geometry, Polygons, Clockwise +// See Also: is_polygon_clockwise(), clockwise_polygon(), reverse_polygon() // Usage: // newpoly = ccw_polygon(poly); -// Synopsis: Return counter-clockwise version of a polygon. -// See Also: is_polygon_clockwise(), clockwise_polygon(), reverse_polygon() -// Topics: Geometry, Polygons, Clockwise // Description: // Given a 2D polygon poly, returns the counter-clockwise winding version of that poly. // Arguments: @@ -2106,11 +2139,11 @@ function ccw_polygon(poly) = // Function: reverse_polygon() -// Usage: -// newpoly = reverse_polygon(poly) // Synopsis: Reverse winding direction of polygon. // Topics: Geometry, Polygons, Clockwise // See Also: is_polygon_clockwise(), ccw_polygon(), clockwise_polygon() +// Usage: +// newpoly = reverse_polygon(poly) // Description: // Reverses a polygon's winding direction, while still using the same start point. // Arguments: @@ -2122,10 +2155,11 @@ function reverse_polygon(poly) = // Function: reindex_polygon() -// Usage: -// newpoly = reindex_polygon(reference, poly); // Synopsis: Adjust point indexing of polygon to minimize pointwise distance to a reference polygon. // Topics: Geometry, Polygons +// See Also: reindex_polygon(), align_polygon(), are_polygons_equal() +// Usage: +// newpoly = reindex_polygon(reference, poly); // 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. @@ -2177,10 +2211,11 @@ function reindex_polygon(reference, poly, return_error=false) = // Function: align_polygon() +// Synopsis: Find best alignment of a 2d polygon to a reference 2d polygon over a set of transformations. +// Topics: Geometry, Polygons +// See Also: reindex_polygon(), align_polygon(), are_polygons_equal() // Usage: // newpoly = align_polygon(reference, poly, [angles], [cp], [tran], [return_ind]); -// Topics: Geometry, Polygons -// Synopsis: Find best alignment of a 2d polygon to a reference 2d polygon over a set of transformations. // Description: // Find the best alignment of a specified 2D polygon with a reference 2D polygon over a set of // transformations. You can specify a list or range of angles and a centerpoint or you can @@ -2245,12 +2280,14 @@ function align_polygon(reference, poly, angles, cp, trans, return_ind=false) = // Function: are_polygons_equal() +// Synopsis: Check if two polygons (not necessarily in the same point order) are equal. +// Topics: Geometry, Polygons, Comparators +// See Also: reindex_polygon(), align_polygon(), are_polygons_equal() // Usage: // bool = are_polygons_equal(poly1, poly2, [eps]) // Description: // Returns true if poly1 and poly2 are the same polongs // within given epsilon tolerance. -// Synopsis: Check if two polygons (not necessarily in the same point order) are equal. // Arguments: // poly1 = first polygon // poly2 = second polygon @@ -2301,9 +2338,11 @@ function ___is_polygon_in_list(poly, polys, i) = // Function: hull() +// Synopsis: Convex hull of a list of 2d or 3d points. +// Topics: Geometry, Hulling +// See Also: hull(), hull_points(), hull2d_path(), hull3d_faces() // Usage: // face_list_or_index_list = hull(points); -// Synopsis: Convex hull of a list of 2d or 3d points. // Description: // Takes a list of 2D or 3D points (but not both in the same list) and returns either the list of // indexes into `points` that forms the 2D convex hull perimeter path, or the list of faces that @@ -2322,9 +2361,11 @@ function hull(points) = // Module: hull_points() +// Synopsis: Convex hull of a list of 2d or 3d points. +// Topics: Geometry, Hulling +// See Also: hull(), hull_points(), hull2d_path(), hull3d_faces() // Usage: // hull_points(points, [fast]); -// Synopsis: Convex hull of a list of 2d or 3d points. // Description: // If given a list of 2D points, creates a 2D convex hull polygon that encloses all those points. // If given a list of 3D points, creates a 3D polyhedron that encloses all the points. This should @@ -2380,13 +2421,15 @@ function _is_cw(a,b,c,all) = // Function: hull2d_path() +// Synopsis: Convex hull of a list of 2d points. +// Topics: Geometry, Hulling +// See Also: hull(), hull_points(), hull2d_path(), hull3d_faces() // Usage: // index_list = hull2d_path(points,all) // Description: // Takes a list of arbitrary 2D points, and finds the convex hull polygon to enclose them. // Returns a path as a list of indices into `points`. // When all==true, returns extra points that are on edges of the hull. -// Synopsis: Convex hull of a list of 2d points. // Arguments: // points = list of 2d points to get the hull of. // all = when true, includes all points on the edges of the convex hull. Default: false. @@ -2443,9 +2486,11 @@ function _hull_collinear(points) = // Function: hull3d_faces() +// Synopsis: Convex hull of a list of 3d points. +// Topics: Geometry, Hulling +// See Also: hull(), hull_points(), hull2d_path(), hull3d_faces() // Usage: // faces = hull3d_faces(points) -// Synopsis: Convex hull of a list of 3d points. // Description: // Takes a list of arbitrary 3D points, and finds the convex hull polyhedron to enclose // them. Returns a list of triangular faces, where each face is a list of indexes into the given `points` @@ -2555,10 +2600,11 @@ function _find_first_noncoplanar(plane, points, i=0) = // Function: is_polygon_convex() -// Usage: -// bool = is_polygon_convex(poly, [eps]); // Synopsis: Check if a polygon is convex. // Topics: Geometry, Convexity, Test +// See Also: clockwise_polygon(), ccw_polygon() +// Usage: +// bool = is_polygon_convex(poly, [eps]); // Description: // Returns true if the given 2D or 3D polygon is convex. // The result is meaningless if the polygon is not simple (self-crossing) or non coplanar. @@ -2601,12 +2647,11 @@ function is_polygon_convex(poly,eps=EPSILON) = // Function: convex_distance() -// Usage: -// dist = convex_distance(points1, points2,eps); // Synopsis: Compute distance between convex hull of two point lists. // Topics: Geometry, Convexity, Distance -// See also: -// convex_collision(), hull() +// See also: convex_collision(), hull() +// Usage: +// dist = convex_distance(points1, points2,eps); // 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 @@ -2661,12 +2706,12 @@ function _GJK_distance(points1, points2, eps=EPSILON, lbd, d, simplex=[]) = // Function: convex_collision() -// Usage: -// bool = convex_collision(points1, points2, [eps]); +// Synopsis: Check whether the convex hulls of two point lists intersect. // Topics: Geometry, Convexity, Collision, Intersection // See also: // convex_distance(), hull() -// Synopsis: Check whether the convex hulls of two point lists intersect. +// Usage: +// bool = convex_collision(points1, points2, [eps]); // Description: // Returns `true` if the convex hull of `points1` intersects the convex hull of `points2` // otherwise, `false`. @@ -2812,10 +2857,10 @@ function _support_diff(p1,p2,d) = // Section: Rotation Decoding // Function: rot_decode() -// Usage: -// info = rot_decode(rotation,[long]); // Returns: [angle,axis,cp,translation] // Synopsis: Extract axis and rotation angle from a rotation matrix. // Topics: Affine, Matrices, Transforms +// Usage: +// info = rot_decode(rotation,[long]); // Returns: [angle,axis,cp,translation] // Description: // Given an input 3D rigid transformation operator (one composed of just rotations and translations) represented // as a 4x4 matrix, compute the rotation and translation parameters of the operator. Returns a list of the