docs(geom): add doc strings

thi-ng · Jun 24, 2022 · e368619 · e368619
1 parent cd8217c
commit e368619
Show file tree

Hide file tree

Showing 9 changed files with 180 additions and 35 deletions.
diff --git a/packages/geom/src/area.ts b/packages/geom/src/area.ts
@@ -10,41 +10,44 @@ import type { Arc } from "./api/arc.js";
 import type { Circle } from "./api/circle.js";
 import type { Ellipse } from "./api/ellipse.js";
 import type { Group } from "./api/group.js";
+import type { Path } from "./api/path.js";
 import type { Polygon } from "./api/polygon.js";
 import type { Rect } from "./api/rect.js";
 import type { Sphere } from "./api/sphere.js";
 import type { Triangle } from "./api/triangle.js";
+import { asPolygon } from "./as-polygon.js";
 import { __dispatch } from "./internal/dispatch.js";
 
 /**
- * Returns the possibly signed (unsigned by default) surface area of given
- * `shape`. For groups calls {@link area} for each child and returns sum of
- * unsigned areas.
+ * Computes the possibly signed (unsigned by default) surface area of given
+ * `shape`. For groups calls itself for each child and returns sum of unsigned
+ * areas.
  *
- * In general, for polygons and triangles, the sign of the result can be
- * used as indication of the shapes orientation (clockwise /
- * counterclockwise).
+ * @remarks
+ * In general, for polygons and triangles, the sign of the result can be used as
+ * indication of the shapes orientation (clockwise / counterclockwise).
  *
  * For curves, lines, point clouds and rays the function returns 0.
  *
- * Implemented for:
+ * Currently implemented for:
  *
- * - AABB
- * - Circle
- * - Cubic
- * - Ellipse
- * - Group
- * - Line
- * - Plane
- * - Points
- * - Polygon
- * - Polyline
- * - Quad
- * - Quadratic
- * - Ray
- * - Rect
- * - Sphere
- * - Triangle
+ * - {@link AABB}
+ * - {@link Circle}
+ * - {@link Cubic}
+ * - {@link Ellipse}
+ * - {@link Group}
+ * - {@link Line}
+ * - {@link Path} (closed only & via poly conversion)
+ * - {@link Plane}
+ * - {@link Points}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Ray}
+ * - {@link Rect}
+ * - {@link Sphere}
+ * - {@link Triangle}
  *
  * @param shape - shape to operate on
  * @param signed - true, if signed area
@@ -66,6 +69,8 @@ export const area: MultiFn1O<IShape, boolean, number> = defmulti(
         group: ({ children }: Group) =>
             children.reduce((sum, $) => sum + area($, false), 0),
 
+        path: ($: Path) => ($.closed ? area(asPolygon($)) : 0),
+
         plane: () => Infinity,
 
         poly: ($: Polygon, signed?) => {

diff --git a/packages/geom/src/as-cubic.ts b/packages/geom/src/as-cubic.ts
@@ -27,6 +27,26 @@ import { cubicFromArc, cubicFromLine, cubicFromQuadratic } from "./cubic.js";
 import { __copyAttribs } from "./internal/copy.js";
 import { __dispatch } from "./internal/dispatch.js";
 
+/**
+ * Converts given shape into an array of {@link Cubic} curves.
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - Arc
+ * - Circle
+ * - Cubic
+ * - Ellipse
+ * - Group
+ * - Line
+ * - Path
+ * - Polygon
+ * - Polyline
+ * - Quad
+ * - Quadratic
+ * - Rect
+ * - Triangle
+ */
 export const asCubic: MultiFn1O<IShape, Partial<CubicOpts>, Cubic[]> = defmulti(
     __dispatch,
     {
@@ -52,15 +72,15 @@ export const asCubic: MultiFn1O<IShape, Partial<CubicOpts>, Cubic[]> = defmulti(
         ],
 
         poly: ($: Polygon, opts: Partial<CubicOpts> = {}) =>
-            polyCubic(
+            __polyCubic(
                 $,
                 opts,
                 closedCubicFromBreakPoints,
                 closedCubicFromControlPoints
             ),
 
         polyline: ($: Polyline, opts: Partial<CubicOpts> = {}) =>
-            polyCubic(
+            __polyCubic(
                 $,
                 opts,
                 openCubicFromBreakPoints,
@@ -76,8 +96,11 @@ export const asCubic: MultiFn1O<IShape, Partial<CubicOpts>, Cubic[]> = defmulti(
     }
 );
 
+/**
+ * @internal
+ */
 // prettier-ignore
-const polyCubic = (
+const __polyCubic = (
     $: PCLike,
     opts: Partial<CubicOpts>,
     breakPoints: (pts: ReadonlyVec[], t?: number, uniform?: boolean) => Vec[][],

diff --git a/packages/geom/src/as-path.ts b/packages/geom/src/as-path.ts
@@ -3,5 +3,12 @@ import { asCubic } from "./as-cubic.js";
 import { __copyAttribs } from "./internal/copy.js";
 import { pathFromCubics } from "./path.js";
 
+/**
+ * Converts given shape into a {@link Path} (via {@link asCubic} and
+ * {@link pathFromCubics}).
+ *
+ * @param src
+ * @param attribs
+ */
 export const asPath = (src: IShape, attribs?: Attribs) =>
     pathFromCubics(asCubic(src), attribs || __copyAttribs(src));
diff --git a/packages/geom/src/as-polygon.ts b/packages/geom/src/as-polygon.ts
@@ -6,6 +6,23 @@ import { __copyAttribs } from "./internal/copy.js";
 import { __dispatch } from "./internal/dispatch.js";
 import { vertices } from "./vertices.js";
 
+/**
+ * Converts given shape into a {@link Polygon}, optionally using provided
+ * {@link @thi.ng/geom-api#SamplingOpts} or number of target vertices.
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - Circle
+ * - Ellipse
+ * - Line
+ * - Path
+ * - Poly
+ * - Polyline (will be closed)
+ * - Quad
+ * - Rect
+ * - Triangle
+ */
 export const asPolygon: MultiFn1O<
     IShape,
     number | Partial<SamplingOpts>,

diff --git a/packages/geom/src/as-polyline.ts b/packages/geom/src/as-polyline.ts
@@ -8,6 +8,26 @@ import { __copyAttribs } from "./internal/copy.js";
 import { __dispatch } from "./internal/dispatch.js";
 import { vertices } from "./vertices.js";
 
+/**
+ * Converts given shape into a {@link Polyline}, optionally using provided
+ * {@link @thi.ng/geom-api#SamplingOpts} or number of target vertices.
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - {@link Arc}
+ * - {@link Circle}
+ * - {@link Cubic}
+ * - {@link Ellipse}
+ * - {@link Line}
+ * - {@link Path}
+ * - {@link Poly}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Rect}
+ * - {@link Triangle}
+ */
 export const asPolyline: MultiFn1O<
     IShape,
     number | Partial<SamplingOpts>,

diff --git a/packages/geom/src/bounds.ts b/packages/geom/src/bounds.ts
@@ -31,6 +31,31 @@ import { __collBounds } from "./internal/bounds.js";
 import { __dispatch } from "./internal/dispatch.js";
 import { rectFromMinMaxWithMargin } from "./rect.js";
 
+/**
+ * Computes and returns bounding rect/box for the given shape, optionally with
+ * extra uniform margin/padding (default: 0). For groups, the compound bounds of
+ * all children will be returned.
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - {@link AABB}
+ * - {@link Arc}
+ * - {@link BPatch}
+ * - {@link Circle}
+ * - {@link Cubic}
+ * - {@link Ellipse}
+ * - {@link Group}
+ * - {@link Line}
+ * - {@link Path}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Points}
+ * - {@link Points3}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Text} - (no way to compute size, only position & any margin)
+ */
 export const bounds: MultiFn1O<IShape, number, AABBLike | undefined> = defmulti<
     any,
     number | undefined,
@@ -111,6 +136,6 @@ export const bounds: MultiFn1O<IShape, number, AABBLike | undefined> = defmulti<
                 : (<AABBLike>$.copy()).offset(margin),
 
         text: ($: Text, margin = 0) =>
-            new Rect(subN2([], $.pos, margin), [0, 0]), // TODO
+            new Rect(subN2([], $.pos, margin), margin * 2),
     }
 );
diff --git a/packages/geom/src/center.ts b/packages/geom/src/center.ts
@@ -13,6 +13,14 @@ import { __copyAttribs } from "./internal/copy.js";
 import { __dispatch } from "./internal/dispatch.js";
 import { translate } from "./translate.js";
 
+/**
+ * Returns copy of given shape centered around optionally provided point
+ * (default: worldspace origin)
+ *
+ * @remarks
+ * Implemented for all shape types supported by {@link centroid} and
+ * {@link translate}.
+ */
 export const center: MultiFn1O<IShape, ReadonlyVec, IShape | undefined> =
     defmulti<any, ReadonlyVec | undefined, IShape | undefined>(
         __dispatch,
@@ -22,6 +30,7 @@ export const center: MultiFn1O<IShape, ReadonlyVec, IShape | undefined> =
                 const c = centroid($);
                 return c ? translate($, submN(null, c, origin, -1)) : undefined;
             },
+
             arc: ($: Arc, origin = ZERO2) =>
                 new Arc(
                     set2([], origin),

diff --git a/packages/geom/src/centroid.ts b/packages/geom/src/centroid.ts
@@ -5,7 +5,7 @@ import { centerOfWeight2 } from "@thi.ng/geom-poly-utils/center-of-weight";
 import { centroid as _centroid } from "@thi.ng/geom-poly-utils/centroid";
 import type { Vec } from "@thi.ng/vectors";
 import { add } from "@thi.ng/vectors/add";
-import { divN } from "@thi.ng/vectors/divn";
+import { addmN } from "@thi.ng/vectors/addmn";
 import { maddN } from "@thi.ng/vectors/maddn";
 import { mixN } from "@thi.ng/vectors/mixn";
 import { mulN } from "@thi.ng/vectors/muln";
@@ -19,6 +19,30 @@ import type { Triangle } from "./api/triangle.js";
 import { bounds } from "./bounds.js";
 import { __dispatch } from "./internal/dispatch.js";
 
+/**
+ * Computes centroid of given shape, writes result in optionally provided output
+ * vector (or creates new one if omitted).
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - {@link AABB}
+ * - {@link Arc}
+ * - {@link BPatch}
+ * - {@link Circle}
+ * - {@link Cubic}
+ * - {@link Ellipse}
+ * - {@link Group}
+ * - {@link Line}
+ * - {@link Path}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Points}
+ * - {@link Points3}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Text} - (no way to compute size, only position & any margin)
+ */
 export const centroid: MultiFn1O<IShape, Vec, Vec | undefined> = defmulti<
     any,
     Vec | undefined,
@@ -28,6 +52,7 @@ export const centroid: MultiFn1O<IShape, Vec, Vec | undefined> = defmulti<
     {
         arc: "circle",
         aabb: "rect",
+        bpatch: "points",
         ellipse: "circle",
         line3: "line",
         points3: "points",
@@ -40,9 +65,9 @@ export const centroid: MultiFn1O<IShape, Vec, Vec | undefined> = defmulti<
     {
         circle: ($: Circle, out?) => set(out || [], $.pos),
 
-        group: ($: Group) => {
+        group: ($: Group, out?) => {
             const b = bounds($);
-            return b ? centroid(b) : undefined;
+            return b ? centroid(b, out) : undefined;
         },
 
         line: ({ points }: Line, out?) =>
@@ -57,10 +82,6 @@ export const centroid: MultiFn1O<IShape, Vec, Vec | undefined> = defmulti<
         rect: ($: AABBLike, out?) => maddN(out || [], $.size, 0.5, $.pos),
 
         tri: ({ points }: Triangle, out?) =>
-            divN(
-                null,
-                add(null, add(out || [], points[0], points[1]), points[2]),
-                3
-            ),
+            addmN(null, add(out || [], points[0], points[1]), points[2], 1 / 3),
     }
 );
diff --git a/packages/geom/src/classify-point.ts b/packages/geom/src/classify-point.ts
@@ -14,6 +14,24 @@ import type { Plane } from "./api/plane.js";
 import type { Triangle } from "./api/triangle.js";
 import { __dispatch } from "./internal/dispatch.js";
 
+/**
+ * Classifies point `p` with respect to given shape. Returns -1 if `p` is
+ * inside, 1 if outside  or 0 if `p` is on the shape boundary (using optional
+ * tolerance `eps`, default: 1e-6).
+ *
+ * @remarks
+ * Currently only implemented for:
+ *
+ * - {@link Circle}
+ * - {@link Plane}
+ * - {@link Sphere}
+ * - {@link Triangle}
+ *
+ * The package @thi.ng/geom-sdf provides a much more comprehensive feature set
+ * (incl. support for more shapes) to perform similar checks as this function.
+ *
+ * Also see {@link pointInside}.
+ */
 export const classifyPoint: MultiFn2O<IShape, ReadonlyVec, number, number> =
     defmulti<any, ReadonlyVec, number | undefined, number>(
         __dispatch,