docs(geom): add docs for most remaining ops

thi-ng · Jun 28, 2022 · b1de347 · b1de347
1 parent 768dddd
commit b1de347
Show file tree

Hide file tree

Showing 24 changed files with 442 additions and 52 deletions.
diff --git a/packages/geom/src/api/bpatch.ts b/packages/geom/src/api/bpatch.ts
@@ -1,6 +1,6 @@
 import { assert } from "@thi.ng/errors/assert";
 import type { Attribs, IHiccupShape } from "@thi.ng/geom-api";
-import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
+import type { ReadonlyVec, Vec, VecPair } from "@thi.ng/vectors";
 import { mixCubic } from "@thi.ng/vectors/mix-cubic";
 import { __copyShape } from "../internal/copy.js";
 import { APC } from "./apc.js";
@@ -76,7 +76,7 @@ export class BPatch extends APC implements IHiccupShape {
             [12, 13],
             [13, 14],
             [14, 15],
-        ].map(([a, b]) => [p[a], p[b]]);
+        ].map(([a, b]) => <VecPair>[p[a], p[b]]);
     }
 
     unmapPoint(uv: ReadonlyVec, out?: Vec) {

diff --git a/packages/geom/src/fit-into-bounds.ts b/packages/geom/src/fit-into-bounds.ts
@@ -9,15 +9,16 @@ import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
 import { neg } from "@thi.ng/vectors/neg";
 import type { AABB } from "./api/aabb.js";
 import { Rect } from "./api/rect.js";
-import { __collBounds } from "./internal/bounds.js";
 import { bounds } from "./bounds.js";
 import { center } from "./center.js";
 import { centroid } from "./centroid.js";
+import { __collBounds } from "./internal/bounds.js";
 import { mapPoint } from "./map-point.js";
 import { transform } from "./transform.js";
 import { unmapPoint } from "./unmap-point.js";
 
-const translateScale = (
+/** @internal */
+const __translateScale = (
     tmat: MatOpV,
     smat: MatOpNV,
     shape: IShape,
@@ -30,12 +31,19 @@ const translateScale = (
         concat([], tmat([], postTrans), smat([], scale), tmat([], preTrans))
     );
 
+/**
+ * Uniformly rescales & repositions given 2D `shape` such that it fits into
+ * destination bounds. Returns transformed copy of `shape`.
+ *
+ * @param shape
+ * @param dest
+ */
 export const fitIntoBounds2 = (shape: IShape, dest: Rect) => {
     const src = <Rect>bounds(shape);
     if (!src) return;
     const c = centroid(src);
     if (!c) return;
-    return translateScale(
+    return __translateScale(
         translation23,
         scale23,
         shape,
@@ -48,12 +56,18 @@ export const fitIntoBounds2 = (shape: IShape, dest: Rect) => {
     );
 };
 
+/**
+ * 3D version of {@link fitIntoBounds2}.
+ *
+ * @param shape
+ * @param dest
+ */
 export const fitIntoBounds3 = (shape: IShape, dest: AABB) => {
     const src = <AABB>bounds(shape);
     if (!src) return;
     const c = centroid(src);
     if (!c) return;
-    return translateScale(
+    return __translateScale(
         translation44,
         scale44,
         shape,
@@ -67,6 +81,12 @@ export const fitIntoBounds3 = (shape: IShape, dest: AABB) => {
     );
 };
 
+/**
+ * Version of {@link fitIntoBounds2} for multiple source shapes.
+ *
+ * @param shapes
+ * @param dest
+ */
 export const fitAllIntoBounds2 = (shapes: IShape[], dest: Rect) => {
     const sbraw = __collBounds(shapes, bounds);
     if (!sbraw) return;
@@ -85,7 +105,7 @@ export const fitAllIntoBounds2 = (shapes: IShape[], dest: Rect) => {
         if (sc) {
             unmapPoint(b, mapPoint(src, sc), c2);
             res.push(
-                translateScale(
+                __translateScale(
                     translation23,
                     scale23,
                     s,

diff --git a/packages/geom/src/flip.ts b/packages/geom/src/flip.ts
@@ -8,6 +8,29 @@ import type { Path } from "./api/path.js";
 import type { Ray } from "./api/ray.js";
 import { __dispatch } from "./internal/dispatch.js";
 
+/**
+ * Reverses vertex ordering or general direction (e.g. for {@link Ray}) of given
+ * shape.
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - {@link Arc}
+ * - {@link Cubic}
+ * - {@link Group} (only eligible shapes)
+ * - {@link Line}
+ * - {@link Path}
+ * - {@link Points}
+ * - {@link Points3}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Ray}
+ * - {@link Triangle}
+ *
+ * @param shape
+ */
 export const flip: MultiFn1<IShape, IShape> = defmulti<any, IShape>(
     __dispatch,
     {

diff --git a/packages/geom/src/map-point.ts b/packages/geom/src/map-point.ts
@@ -7,6 +7,21 @@ import { sub } from "@thi.ng/vectors/sub";
 import type { Rect } from "./api/rect.js";
 import { __dispatch } from "./internal/dispatch.js";
 
+/**
+ * Maps point `p` from world space to the local space of given shape.
+ *
+ * @remarks
+ * This is the reverse operation of {@link unmapPoint}.
+ *
+ * Currently only implemented for:
+ *
+ * - {@link AABB}
+ * - {@link Rect}
+ *
+ * @param shape
+ * @param p
+ * @param out
+ */
 export const mapPoint: MultiFn2O<IShape, ReadonlyVec, Vec, Vec> = defmulti<
     any,
     ReadonlyVec,

diff --git a/packages/geom/src/offset.ts b/packages/geom/src/offset.ts
@@ -2,21 +2,37 @@ import type { MultiFn2 } from "@thi.ng/defmulti";
 import { defmulti } from "@thi.ng/defmulti/defmulti";
 import type { IShape } from "@thi.ng/geom-api";
 import { add2 } from "@thi.ng/vectors/add";
-import { addN2 } from "@thi.ng/vectors/addn";
-import { ZERO2 } from "@thi.ng/vectors/api";
-import { max2 } from "@thi.ng/vectors/max";
 import { normalCW } from "@thi.ng/vectors/normal";
 import { set2 } from "@thi.ng/vectors/set";
 import { sub2 } from "@thi.ng/vectors/sub";
+import { aabbFromCentroidWithMargin } from "./aabb.js";
+import type { AABB } from "./api/aabb.js";
 import { Circle } from "./api/circle.js";
 import type { Line } from "./api/line.js";
 import { Quad } from "./api/quad.js";
 import type { Rect } from "./api/rect.js";
 import { centroid } from "./centroid.js";
 import { __copyAttribs } from "./internal/copy.js";
 import { __dispatch } from "./internal/dispatch.js";
-import { rectFromCentroid } from "./rect.js";
+import { rectFromCentroidWithMargin } from "./rect.js";
 
+/**
+ * Computes an offset shape (as in "path offsetting") of given shape and offset
+ * distance `dist`.
+ *
+ * @remarks
+ * Also see {@link @thi.ng/geom-sdf#} package for more flexible & advanced usage.
+ *
+ * Currently only implemented for:
+ *
+ * - {@link AABB}
+ * - {@link Circle}
+ * - {@link Line}
+ * - {@link Rect}
+ *
+ * @param shape
+ * @param dist
+ */
 export const offset: MultiFn2<IShape, number, IShape> = defmulti<
     any,
     number,
@@ -25,6 +41,14 @@ export const offset: MultiFn2<IShape, number, IShape> = defmulti<
     __dispatch,
     {},
     {
+        aabb: ($: AABB, n) =>
+            aabbFromCentroidWithMargin(
+                centroid($)!,
+                $.size,
+                n,
+                __copyAttribs($)
+            ),
+
         circle: ($: Circle, n) =>
             new Circle(set2([], $.pos), Math.max($.r + n, 0)),
 
@@ -42,9 +66,10 @@ export const offset: MultiFn2<IShape, number, IShape> = defmulti<
         },
 
         rect: ($: Rect, n) =>
-            rectFromCentroid(
+            rectFromCentroidWithMargin(
                 centroid($)!,
-                max2(null, addN2([], $.size, n), ZERO2),
+                $.size,
+                n,
                 __copyAttribs($)
             ),
     }

diff --git a/packages/geom/src/point-at.ts b/packages/geom/src/point-at.ts
@@ -24,6 +24,31 @@ import type { Rect } from "./api/rect.js";
 import { __dispatch } from "./internal/dispatch.js";
 import { vertices } from "./vertices.js";
 
+/**
+ * Samples and returns point on the boundary of given 2D shape at normalized
+ * parametric distance `t`. If the shape is closed, t=0 and t=1 yield the same
+ * result.
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - {@link Arc}
+ * - {@link Circle}
+ * - {@link Cubic}
+ * - {@link Ellipse}
+ * - {@link Line}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Ray}
+ * - {@link Ray3}
+ * - {@link Rect}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param t
+ */
 export const pointAt: MultiFn2<IShape, number, Vec | undefined> = defmulti<
     any,
     number,

diff --git a/packages/geom/src/point-inside.ts b/packages/geom/src/point-inside.ts
@@ -20,6 +20,25 @@ import type { Rect } from "./api/rect.js";
 import type { Triangle } from "./api/triangle.js";
 import { __dispatch } from "./internal/dispatch.js";
 
+/**
+ * Returns true if point `p` is inside the given shape.
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - AABB
+ * - Circle
+ * - Points (i.e. if `p` is one of the points in the cloud)
+ * - Points3 (same as w/ Points)
+ * - Polygon
+ * - Quad
+ * - Rect
+ * - Sphere
+ * - Triangle
+ *
+ * @param shape
+ * @param p
+ */
 export const pointInside: MultiFn2<IShape, ReadonlyVec, boolean> = defmulti<
     any,
     ReadonlyVec,

diff --git a/packages/geom/src/resample.ts b/packages/geom/src/resample.ts
@@ -8,6 +8,25 @@ import { asPolygon } from "./as-polygon.js";
 import { __copyAttribs } from "./internal/copy.js";
 import { __dispatch } from "./internal/dispatch.js";
 
+/**
+ * Resamples given 2D shape with given options and returns result as polygon (if
+ * closed) or polyline (if open).
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - {@link Circle}
+ * - {@link Ellipse}
+ * - {@link Line}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Rect}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param opts
+ */
 export const resample: MultiFn2<
     IShape,
     number | Partial<SamplingOpts>,

diff --git a/packages/geom/src/rotate.ts b/packages/geom/src/rotate.ts
@@ -24,6 +24,32 @@ import { __copyAttribs } from "./internal/copy.js";
 import { __dispatch } from "./internal/dispatch.js";
 import { __rotatedShape as tx } from "./internal/rotate.js";
 
+/**
+ * Rotates given 2D shape by `theta` (in radians).
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - {@link Arc}
+ * - {@link Circle}
+ * - {@link Cubic}
+ * - {@link Ellipse}
+ * - {@link Group}
+ * - {@link Line}
+ * - {@link Path}
+ * - {@link Points}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Ray}
+ * - {@link Rect}
+ * - {@link Text}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param theta
+ */
 export const rotate: MultiFn2<IShape, number, IShape> = defmulti<
     any,
     number,

diff --git a/packages/geom/src/scale.ts b/packages/geom/src/scale.ts
@@ -30,6 +30,38 @@ import { __copyAttribs } from "./internal/copy.js";
 import { __dispatch } from "./internal/dispatch.js";
 import { __scaledShape as tx } from "./internal/scale.js";
 
+/**
+ * Scales given shape uniformly or non-uniformly by given `factor`.
+ *
+ * @remarks
+ * Scaling non-uniformly might result in different result types, e.g.
+ * {@link Circle} => {@link Ellipse}.
+ *
+ * Currently implemented for:
+ *
+ * - {@link AABB}
+ * - {@link Arc}
+ * - {@link Circle}
+ * - {@link Cubic}
+ * - {@link Ellipse}
+ * - {@link Group}
+ * - {@link Line}
+ * - {@link Path}
+ * - {@link Points}
+ * - {@link Points3}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Ray}
+ * - {@link Rect}
+ * - {@link Sphere}
+ * - {@link Text}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param factor
+ */
 export const scale: MultiFn2<IShape, number | ReadonlyVec, IShape> = defmulti<
     any,
     number | ReadonlyVec,

diff --git a/packages/geom/src/scatter.ts b/packages/geom/src/scatter.ts
@@ -5,6 +5,19 @@ import { randMinMax } from "@thi.ng/vectors/random";
 import { bounds } from "./bounds.js";
 import { pointInside } from "./point-inside.js";
 
+/**
+ * Produces `num` random points for which {@link pointInside} succeeeds for the
+ * given `shape`. Writes results into `out` array (or creates a new one).
+ *
+ * @remarks
+ * Samples are only created with the shapes bounding box and are chosen using
+ * optionall yprovided `rnd` {@link @thi.ng/random#IRandom} instance.
+ *
+ * @param shape
+ * @param num
+ * @param rnd
+ * @param out
+ */
 export const scatter = (
     shape: IShape,
     num: number,