@thi.ng/geom 3.3.1 → 3.4.2

package/translate.d.ts

@@ -1,5 +1,34 @@
 import type { MultiFn2 } from "@thi.ng/defmulti";
 import type { IShape } from "@thi.ng/geom-api";
 import type { ReadonlyVec } from "@thi.ng/vectors";
+/**
+ * Translates given shape by given `offset` vector.
+ *
+ * @remarks
+ * 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 offset
+ */
 export declare const translate: MultiFn2<IShape, ReadonlyVec, IShape>;
 //# sourceMappingURL=translate.d.ts.map

package/translate.js

@@ -20,6 +20,35 @@ import { Triangle } from "./api/triangle.js";
 import { __copyAttribs } from "./internal/copy.js";
 import { __dispatch } from "./internal/dispatch.js";
 import { __translatedShape as tx } from "./internal/translate.js";
+/**
+ * Translates given shape by given `offset` vector.
+ *
+ * @remarks
+ * 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 offset
+ */
 export const translate = defmulti(__dispatch, {}, {
     aabb: ($, delta) => new AABB(add3([], $.pos, delta), set3([], $.size), __copyAttribs($)),
     arc: ($, delta) => {

package/union.d.ts

@@ -1,4 +1,14 @@
 import type { MultiFn2 } from "@thi.ng/defmulti";
 import type { IShape } from "@thi.ng/geom-api";
+/**
+ * Computes shape "union" of given 2 shapes.
+ *
+ * @remarks
+ * Currently only implemented for {@link AABB} and {@link Rect} to compute union
+ * bounding boxes.
+ *
+ * @param a
+ * @param b
+ */
 export declare const union: MultiFn2<IShape, IShape, IShape[]>;
 //# sourceMappingURL=union.d.ts.map

package/union.js

@@ -3,6 +3,16 @@ import { AABB } from "./api/aabb.js";
 import { Rect } from "./api/rect.js";
 import { __unionBounds } from "./internal/bounds.js";
 import { __dispatch } from "./internal/dispatch.js";
+/**
+ * Computes shape "union" of given 2 shapes.
+ *
+ * @remarks
+ * Currently only implemented for {@link AABB} and {@link Rect} to compute union
+ * bounding boxes.
+ *
+ * @param a
+ * @param b
+ */
 export const union = defmulti(__dispatch, {}, {
     aabb: (a, b) => [
         new AABB(...__unionBounds(a.pos, a.size, b.pos, b.size)),

package/unmap-point.d.ts

@@ -2,16 +2,19 @@ import type { MultiFn2O } from "@thi.ng/defmulti";
 import type { IShape } from "@thi.ng/geom-api";
 import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
 /**
- * Projects given point `uv` (normalized coords) into the target space
- * defined by `shape` and writes result to `out` (or returns new
- * vector). See {@link mapPoint} for reverse operation. Both functions
- * together can be used to warp points from one shape into another.
+ * Projects given point `uv` (normalized coords) into the target space defined
+ * by `shape` and writes result to `out` (or returns new vector).
+ *
+ * @remarks
+ * See {@link mapPoint} for reverse operation. Both functions together can be
+ * used to warp points from one shape into another.
  *
  * Currently only implemented for these shape types:
  *
- * - AABB
- * - Quad
- * - Rect
+ * - {@link AABB}
+ * - {@link Quad}
+ * - {@link Quad3}
+ * - {@link Rect}
  *
  * @param shape - shape to operate on
  * @param uv - point to map in UV space

package/unmap-point.js

@@ -3,16 +3,19 @@ import { madd } from "@thi.ng/vectors/madd";
 import { mixBilinear } from "@thi.ng/vectors/mix-bilinear";
 import { __dispatch } from "./internal/dispatch.js";
 /**
- * Projects given point `uv` (normalized coords) into the target space
- * defined by `shape` and writes result to `out` (or returns new
- * vector). See {@link mapPoint} for reverse operation. Both functions
- * together can be used to warp points from one shape into another.
+ * Projects given point `uv` (normalized coords) into the target space defined
+ * by `shape` and writes result to `out` (or returns new vector).
+ *
+ * @remarks
+ * See {@link mapPoint} for reverse operation. Both functions together can be
+ * used to warp points from one shape into another.
  *
  * Currently only implemented for these shape types:
  *
- * - AABB
- * - Quad
- * - Rect
+ * - {@link AABB}
+ * - {@link Quad}
+ * - {@link Quad3}
+ * - {@link Rect}
  *
  * @param shape - shape to operate on
  * @param uv - point to map in UV space

package/vertices.d.ts

@@ -2,10 +2,37 @@ import type { MultiFn1O } from "@thi.ng/defmulti";
 import type { IShape } from "@thi.ng/geom-api";
 import { SamplingOpts } from "@thi.ng/geom-api/sample";
 import type { Vec } from "@thi.ng/vectors";
+/**
+ * Extracts/samples vertices from given shape's boundary and returns them as
+ * array. Some shapes also support {@link @thi.ng/geom-api#SamplingOpts}.
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - {@link AABB}
+ * - {@link Arc}
+ * - {@link BPatch}
+ * - {@link Circle}
+ * - {@link Cubic}
+ * - {@link Ellipse}
+ * - {@link Group}
+ * - {@link Line}
+ * - {@link Path}
+ * - {@link Points}
+ * - {@link Points3}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Rect}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param opts
+ */
 export declare const vertices: MultiFn1O<IShape, number | Partial<SamplingOpts>, Vec[]>;
 /**
- * Takes array of vectors or an `IShape`. If the latter, calls {@link vertices}
- * and return result, else returns original array.
+ * Takes an array of vertices or an `IShape`. If the latter, calls
+ * {@link vertices} with default options and returns result, else returns
+ * original array.
  *
  * @param shape -
  */

package/vertices.js

@@ -14,6 +14,32 @@ import { madd2 } from "@thi.ng/vectors/madd";
 import { set2 } from "@thi.ng/vectors/set";
 import { Polygon } from "./api/polygon.js";
 import { __dispatch } from "./internal/dispatch.js";
+/**
+ * Extracts/samples vertices from given shape's boundary and returns them as
+ * array. Some shapes also support {@link @thi.ng/geom-api#SamplingOpts}.
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - {@link AABB}
+ * - {@link Arc}
+ * - {@link BPatch}
+ * - {@link Circle}
+ * - {@link Cubic}
+ * - {@link Ellipse}
+ * - {@link Group}
+ * - {@link Line}
+ * - {@link Path}
+ * - {@link Points}
+ * - {@link Points3}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Rect}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param opts
+ */
 export const vertices = defmulti(__dispatch, {
     line: "polyline",
     bpatch: "points",
@@ -47,7 +73,7 @@ export const vertices = defmulti(__dispatch, {
     circle: ($, opts = DEFAULT_SAMPLES) => {
         const pos = $.pos;
         const r = $.r;
-        let [num, last] = circleOpts(opts, r);
+        let [num, last] = __circleOpts(opts, r);
         const delta = TAU / num;
         last && num++;
         const buf = new Array(num);
@@ -61,7 +87,7 @@ export const vertices = defmulti(__dispatch, {
         const buf = [];
         const pos = $.pos;
         const r = $.r;
-        let [num, last] = circleOpts(opts, Math.max($.r[0], $.r[1]));
+        let [num, last] = __circleOpts(opts, Math.max($.r[0], $.r[1]));
         const delta = TAU / num;
         last && num++;
         for (let i = 0; i < num; i++) {
@@ -96,13 +122,15 @@ export const vertices = defmulti(__dispatch, {
     },
 });
 /**
- * Takes array of vectors or an `IShape`. If the latter, calls {@link vertices}
- * and return result, else returns original array.
+ * Takes an array of vertices or an `IShape`. If the latter, calls
+ * {@link vertices} with default options and returns result, else returns
+ * original array.
  *
  * @param shape -
  */
 export const ensureVertices = (shape) => isArray(shape) ? shape : vertices(shape);
-const circleOpts = (opts, r) => isNumber(opts)
+/** @internal */
+const __circleOpts = (opts, r) => isNumber(opts)
     ? [opts, false]
     : [
         opts.theta

package/volume.d.ts

@@ -3,10 +3,13 @@ import type { IShape } from "@thi.ng/geom-api";
 /**
  * Returns the volume of given 3D shape. Returns 0 for all others.
  *
+ * @remarks
  * Currently only implemented for:
  *
- * - AABB
- * - Sphere
+ * - {@link AABB}
+ * - {@link Sphere}
+ *
+ * @param shape
  */
 export declare const volume: MultiFn1<IShape, number>;
 //# sourceMappingURL=volume.d.ts.map

package/volume.js

@@ -4,10 +4,13 @@ import { __dispatch } from "./internal/dispatch.js";
 /**
  * Returns the volume of given 3D shape. Returns 0 for all others.
  *
+ * @remarks
  * Currently only implemented for:
  *
- * - AABB
- * - Sphere
+ * - {@link AABB}
+ * - {@link Sphere}
+ *
+ * @param shape
  */
 export const volume = defmulti(__dispatch, {}, {
     [DEFAULT]: () => 0,

package/warp-points.d.ts

@@ -2,6 +2,20 @@ import type { IShape } from "@thi.ng/geom-api";
 import type { ReadonlyVec, Vec } from "@thi.ng/vectors/api";
 import type { BPatch } from "./api/bpatch.js";
 import type { Rect } from "./api/rect.js";
-export declare const warpPoints: (pts: ReadonlyVec[], dest: IShape, src: IShape) => Vec[];
+/**
+ * Transfers/remaps points (in world space) given in relation to `src` shape to
+ * be relative to the space of `dest` shape. Writes results to `out` (or creates
+ * new array).
+ *
+ * @remarks
+ * The type of `src` must be supported by {@link mapPoint}. The type of `dest`
+ * must be supported by {@link unmapPoint}.
+ *
+ * @param pts
+ * @param dest
+ * @param src
+ * @param out
+ */
+export declare const warpPoints: (pts: ReadonlyVec[], dest: IShape, src: IShape, out?: Vec[]) => Vec[];
 export declare const warpPointsBPatch: (pts: ReadonlyVec[], dest: BPatch, src?: Rect, out?: Vec[]) => Vec[];
 //# sourceMappingURL=warp-points.d.ts.map

package/warp-points.js

@@ -2,12 +2,25 @@ import { bounds2 } from "@thi.ng/geom-poly-utils/bounds";
 import { mapPoint } from "./map-point.js";
 import { rectFromMinMax } from "./rect.js";
 import { unmapPoint } from "./unmap-point.js";
-export const warpPoints = (pts, dest, src) => {
-    const res = [];
+/**
+ * Transfers/remaps points (in world space) given in relation to `src` shape to
+ * be relative to the space of `dest` shape. Writes results to `out` (or creates
+ * new array).
+ *
+ * @remarks
+ * The type of `src` must be supported by {@link mapPoint}. The type of `dest`
+ * must be supported by {@link unmapPoint}.
+ *
+ * @param pts
+ * @param dest
+ * @param src
+ * @param out
+ */
+export const warpPoints = (pts, dest, src, out = []) => {
     for (let n = pts.length, i = 0; i < n; i++) {
-        res.push(unmapPoint(dest, mapPoint(src, pts[i])));
+        out.push(unmapPoint(dest, mapPoint(src, pts[i])));
     }
-    return res;
+    return out;
 };
 export const warpPointsBPatch = (pts, dest, src, out = []) => {
     src = src || rectFromMinMax(...bounds2(pts));

package/with-attribs.d.ts

@@ -1,3 +1,12 @@
 import type { Attribs, IShape } from "@thi.ng/geom-api";
-export declare const withAttribs: <T extends IShape>(shape: T, attribs: Attribs, replace?: boolean) => T;
+/**
+ * Returns a shallow copy of given shape with new `attribs` assigned (using
+ * {@link @thi.ng/geom-api#IAttributed.withAttribs}). If `replace` is false, the
+ * new attribs will be merged with the existing ones (if any).
+ *
+ * @param shape
+ * @param attribs
+ * @param replace
+ */
+export declare const withAttribs: <T extends IShape<IShape<any>>>(shape: T, attribs: Attribs, replace?: boolean) => IShape<any>;
 //# sourceMappingURL=with-attribs.d.ts.map

package/with-attribs.js

@@ -1,4 +1,10 @@
-export const withAttribs = (shape, attribs, replace = true) => {
-    shape.attribs = replace ? attribs : { ...shape.attribs, ...attribs };
-    return shape;
-};
+/**
+ * Returns a shallow copy of given shape with new `attribs` assigned (using
+ * {@link @thi.ng/geom-api#IAttributed.withAttribs}). If `replace` is false, the
+ * new attribs will be merged with the existing ones (if any).
+ *
+ * @param shape
+ * @param attribs
+ * @param replace
+ */
+export const withAttribs = (shape, attribs, replace = true) => shape.withAttribs(replace ? attribs : { ...shape.attribs, ...attribs });