@thi.ng/geom 3.3.1 → 3.4.0

package/scatter.d.ts

@@ -1,4 +1,17 @@
 import type { IShape } from "@thi.ng/geom-api";
 import type { Vec } from "@thi.ng/vectors";
+/**
+ * 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 declare const scatter: (shape: IShape, num: number, rnd?: import("@thi.ng/random/system").SystemRandom, out?: Vec[]) => Vec[] | undefined;
 //# sourceMappingURL=scatter.d.ts.map

package/scatter.js

@@ -2,6 +2,19 @@ import { SYSTEM } from "@thi.ng/random/system";
 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, num, rnd = SYSTEM, out = []) => {
     const b = bounds(shape);
     if (!b)

package/simplify.d.ts

@@ -1,4 +1,22 @@
 import type { MultiFn2 } from "@thi.ng/defmulti";
 import type { IShape } from "@thi.ng/geom-api";
+/**
+ * Simplifies given 2D shape boundary using Douglas-Peucker algorithm
+ * (implemented by {@link @thi.ng/geom-resample#simplify}) and given `threshold`
+ * distance (default: 0, which removes only co-linear vertices).
+ *
+ * @remarks
+ * Currently only implemented for:
+ *
+ * - {@link Path}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ *
+ * Use {@link asPath}, {@link asPolygon} or {@link asPolyline} to convert other
+ * shape types first.
+ *
+ * @param shape
+ * @param threshold
+ */
 export declare const simplify: MultiFn2<IShape, number, IShape>;
 //# sourceMappingURL=simplify.d.ts.map

package/simplify.js

@@ -7,8 +7,26 @@ import { Polyline } from "./api/polyline.js";
 import { __copyAttribs } from "./internal/copy.js";
 import { __dispatch } from "./internal/dispatch.js";
 import { vertices } from "./vertices.js";
+/**
+ * Simplifies given 2D shape boundary using Douglas-Peucker algorithm
+ * (implemented by {@link @thi.ng/geom-resample#simplify}) and given `threshold`
+ * distance (default: 0, which removes only co-linear vertices).
+ *
+ * @remarks
+ * Currently only implemented for:
+ *
+ * - {@link Path}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ *
+ * Use {@link asPath}, {@link asPolygon} or {@link asPolyline} to convert other
+ * shape types first.
+ *
+ * @param shape
+ * @param threshold
+ */
 export const simplify = defmulti(__dispatch, {}, {
-    path: ($, eps = 0.1) => {
+    path: ($, eps = 0) => {
         const res = [];
         const orig = $.segments;
         const n = orig.length;
@@ -43,6 +61,6 @@ export const simplify = defmulti(__dispatch, {}, {
         }
         return new Path(res, __copyAttribs($));
     },
-    poly: ($, eps = 0.1) => new Polygon(_simplify($.points, eps, true), __copyAttribs($)),
-    polyline: ($, eps = 0.1) => new Polyline(_simplify($.points, eps), __copyAttribs($)),
+    poly: ($, eps = 0) => new Polygon(_simplify($.points, eps, true), __copyAttribs($)),
+    polyline: ($, eps = 0) => new Polyline(_simplify($.points, eps), __copyAttribs($)),
 });

package/split-at.d.ts

@@ -1,4 +1,19 @@
 import type { MultiFn2 } from "@thi.ng/defmulti";
 import type { IShape } from "@thi.ng/geom-api";
+/**
+ * Splits given shape in 2 parts at normalized parametric position `t`.
+ *
+ * @remarks
+ * Currently only implemented for:
+ *
+ * - {@link Arc}
+ * - {@link Cubic}
+ * - {@link Line}
+ * - {@link Polyline}
+ * - {@link Quadratic}
+ *
+ * @param shape
+ * @param t
+ */
 export declare const splitAt: MultiFn2<IShape, number, IShape[] | undefined>;
 //# sourceMappingURL=split-at.d.ts.map

package/split-at.js

@@ -13,6 +13,21 @@ import { __copyAttribs } from "./internal/copy.js";
 import { __dispatch } from "./internal/dispatch.js";
 import { __pointArraysAsShapes } from "./internal/points-as-shape.js";
 import { __splitLine } from "./internal/split.js";
+/**
+ * Splits given shape in 2 parts at normalized parametric position `t`.
+ *
+ * @remarks
+ * Currently only implemented for:
+ *
+ * - {@link Arc}
+ * - {@link Cubic}
+ * - {@link Line}
+ * - {@link Polyline}
+ * - {@link Quadratic}
+ *
+ * @param shape
+ * @param t
+ */
 export const splitAt = defmulti(__dispatch, {}, {
     arc: ($, t) => {
         const theta = fit01(t, $.start, $.end);

package/split-near.d.ts

@@ -4,14 +4,14 @@ import type { ReadonlyVec } from "@thi.ng/vectors";
 /**
  * Similar to {@link splitAt}, but instead of taking a normalized parametric
  * split position, splits the given curve at the closest point to `p`.
- * Returns tuple of split shapes of same type as `shape`.
  *
- * Implemented for:
+ * @remarks
+ * Currently only implemented for:
  *
- * - Cubic
- * - Line
- * - Polyline
- * - Quadratic
+ * - {@link Cubic}
+ * - {@link Line}
+ * - {@link Polyline}
+ * - {@link Quadratic}
  *
  * @param shape - shape to operate on
  * @param p - split point

package/split-near.js

@@ -15,14 +15,14 @@ import { __splitLine } from "./internal/split.js";
 /**
  * Similar to {@link splitAt}, but instead of taking a normalized parametric
  * split position, splits the given curve at the closest point to `p`.
- * Returns tuple of split shapes of same type as `shape`.
  *
- * Implemented for:
+ * @remarks
+ * Currently only implemented for:
  *
- * - Cubic
- * - Line
- * - Polyline
- * - Quadratic
+ * - {@link Cubic}
+ * - {@link Line}
+ * - {@link Polyline}
+ * - {@link Quadratic}
  *
  * @param shape - shape to operate on
  * @param p - split point

package/subdiv-curve.d.ts

@@ -1,4 +1,21 @@
 import type { MultiFn2O } from "@thi.ng/defmulti";
 import type { IShape, SubdivKernel } from "@thi.ng/geom-api";
+/**
+ * Recursively applies {@link @thi.ng/geom-api#SubdivKernel} to given
+ * shape/boundary. See {@link @thi.ng/geom-subdiv-curve#} package for further
+ * details.
+ *
+ * @remarks
+ * By default only applies a single iteration.
+ *
+ * Currently only implemented for:
+ *
+ * - {@link Polygon}
+ * - {@link Polyline}
+ *
+ * @param shape
+ * @param kernel
+ * @param iter
+ */
 export declare const subdivCurve: MultiFn2O<IShape, SubdivKernel, number, IShape>;
 //# sourceMappingURL=subdiv-curve.d.ts.map

package/subdiv-curve.js

@@ -4,6 +4,23 @@ import { Polygon } from "./api/polygon.js";
 import { Polyline } from "./api/polyline.js";
 import { __copyAttribs } from "./internal/copy.js";
 import { __dispatch } from "./internal/dispatch.js";
+/**
+ * Recursively applies {@link @thi.ng/geom-api#SubdivKernel} to given
+ * shape/boundary. See {@link @thi.ng/geom-subdiv-curve#} package for further
+ * details.
+ *
+ * @remarks
+ * By default only applies a single iteration.
+ *
+ * Currently only implemented for:
+ *
+ * - {@link Polygon}
+ * - {@link Polyline}
+ *
+ * @param shape
+ * @param kernel
+ * @param iter
+ */
 export const subdivCurve = defmulti(__dispatch, {}, {
     poly: ($, kernel, iter = 1) => new Polygon(subdivide($.points, kernel, iter), __copyAttribs($)),
     polyline: ($, kernel, iter = 1) => new Polyline(subdivide($.points, kernel, iter), __copyAttribs($)),

package/tangent-at.d.ts

@@ -1,5 +1,24 @@
 import type { MultiFn2 } from "@thi.ng/defmulti";
 import type { IShape } from "@thi.ng/geom-api";
 import type { Vec } from "@thi.ng/vectors";
+/**
+ * Computes tangent on shape/boundary at normalized parametric position `t`.
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - {@link Circle}
+ * - {@link Cubic}
+ * - {@link Line}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Rect}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param t
+ */
 export declare const tangentAt: MultiFn2<IShape, number, Vec | undefined>;
 //# sourceMappingURL=tangent-at.d.ts.map

package/tangent-at.js

@@ -7,6 +7,25 @@ import { HALF_PI, TAU } from "@thi.ng/math/api";
 import { direction } from "@thi.ng/vectors/direction";
 import { __dispatch } from "./internal/dispatch.js";
 import { vertices } from "./vertices.js";
+/**
+ * Computes tangent on shape/boundary at normalized parametric position `t`.
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - {@link Circle}
+ * - {@link Cubic}
+ * - {@link Line}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Rect}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param t
+ */
 export const tangentAt = defmulti(__dispatch, {
     quad: "poly",
     tri: "poly",

package/tessellate.d.ts

@@ -1,4 +1,15 @@
 import type { IShape, Tessellator } from "@thi.ng/geom-api";
 import type { Vec } from "@thi.ng/vectors";
-export declare const tessellate: import("@thi.ng/defmulti").MultiFn2<IShape, Tessellator[], Vec[][]>;
+/**
+ * Recursively tessellates shape using provided
+ * {@link @thi.ng/geom-api#Tessellator} functions. See
+ * {@link @thi.ng/geom-tessellate#} package for more details.
+ *
+ * @remarks
+ * Implemented for all shapes supported by {@link vertices}.
+ *
+ * @param shape
+ * @param tessellators
+ */
+export declare const tessellate: import("@thi.ng/defmulti").MultiFn2<IShape<IShape<any>>, Tessellator[], Vec[][]>;
 //# sourceMappingURL=tessellate.d.ts.map

package/tessellate.js

@@ -2,6 +2,17 @@ import { DEFAULT, defmulti } from "@thi.ng/defmulti/defmulti";
 import { tessellate as _tessellate } from "@thi.ng/geom-tessellate/tessellate";
 import { __dispatch } from "./internal/dispatch.js";
 import { vertices } from "./vertices.js";
+/**
+ * Recursively tessellates shape using provided
+ * {@link @thi.ng/geom-api#Tessellator} functions. See
+ * {@link @thi.ng/geom-tessellate#} package for more details.
+ *
+ * @remarks
+ * Implemented for all shapes supported by {@link vertices}.
+ *
+ * @param shape
+ * @param tessellators
+ */
 export const tessellate = defmulti(__dispatch, {}, {
     [DEFAULT]: ($, fns) => _tessellate(vertices($), fns),
 });

package/transform-vertices.d.ts

@@ -4,17 +4,42 @@ import type { IShape } from "@thi.ng/geom-api";
 import type { ReadonlyMat } from "@thi.ng/matrices";
 import type { ReadonlyVec } from "@thi.ng/vectors";
 /**
- * Transforms vertices of given shape with provided function, which is
- * being called for each vertex individually and should produce a
- * transformation matrix. Some shape types will be automatically
- * converted to other types prior to transformation because they cannot
- * be reliably represented in their original type anymore, this
- * includes:
+ * Similar to {@link transform}. Transforms vertices of given shape with
+ * provided function, which is being called for each vertex individually and
+ * should produce a transformation matrix.
  *
- * - Arc => Path (cubics)
- * - Circle => Path (cubics)
- * - Ellipse => Path (cubics)
- * - Rect => Polygon
+ * @remark
+ * Some shape types will be automatically converted to other types prior to
+ * transformation because they cannot be reliably represented in their original
+ * type anymore, this includes:
+ *
+ * - {@link Arc} => {@link Path} (cubics)
+ * - {@link Circle} => {@link Path} (cubics)
+ * - {@link Ellipse} => {@link Path} (cubics)
+ * - {@link Rect} => {@link Polygon}
+ *
+ * Currently implemented for:
+ *
+ * - {@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 Text}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param fn
  */
 export declare const transformVertices: MultiFn2<IShape, Fn<ReadonlyVec, ReadonlyMat>, IShape>;
 //# sourceMappingURL=transform-vertices.d.ts.map

package/transform-vertices.js

@@ -16,17 +16,42 @@ import { __copyAttribs } from "./internal/copy.js";
 import { __dispatch } from "./internal/dispatch.js";
 import { __transformedShapePoints as tx, __transformedShapePoints3 as tx3, } from "./internal/transform.js";
 /**
- * Transforms vertices of given shape with provided function, which is
- * being called for each vertex individually and should produce a
- * transformation matrix. Some shape types will be automatically
- * converted to other types prior to transformation because they cannot
- * be reliably represented in their original type anymore, this
- * includes:
+ * Similar to {@link transform}. Transforms vertices of given shape with
+ * provided function, which is being called for each vertex individually and
+ * should produce a transformation matrix.
  *
- * - Arc => Path (cubics)
- * - Circle => Path (cubics)
- * - Ellipse => Path (cubics)
- * - Rect => Polygon
+ * @remark
+ * Some shape types will be automatically converted to other types prior to
+ * transformation because they cannot be reliably represented in their original
+ * type anymore, this includes:
+ *
+ * - {@link Arc} => {@link Path} (cubics)
+ * - {@link Circle} => {@link Path} (cubics)
+ * - {@link Ellipse} => {@link Path} (cubics)
+ * - {@link Rect} => {@link Polygon}
+ *
+ * Currently implemented for:
+ *
+ * - {@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 Text}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param fn
  */
 export const transformVertices = defmulti(__dispatch, {
     circle: "rect",

package/transform.d.ts

@@ -2,15 +2,41 @@ import type { MultiFn2 } from "@thi.ng/defmulti";
 import type { IShape } from "@thi.ng/geom-api";
 import type { ReadonlyMat } from "@thi.ng/matrices";
 /**
- * Transforms given shape with provided matrix. Some shape types will be
- * automatically converted to other types prior to transformation because they
- * cannot be reliably represented in their original type anymore, this
- * includes:
+ * Transforms given shape with provided matrix.
  *
- * - Arc => Path (cubics)
- * - Circle => Path (cubics)
- * - Ellipse => Path (cubics)
- * - Rect => Polygon
+ * @remarks
+ * A 2x3 transform matrix is assumed for 2D shapes and 4x4 matrix for 3D shapes.
+ * Some shape types will be automatically converted to other types prior to
+ * transformation because they cannot be reliably represented in their original
+ * type anymore, this includes:
+ *
+ * - {@link Arc} => {@link Path} (cubics)
+ * - {@link Circle} => {@link Path} (cubics)
+ * - {@link Ellipse} => {@link Path} (cubics)
+ * - {@link Rect} => {@link Quad}
+ *
+ * Currently implemented for:
+ *
+ * - {@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 Text}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param mat
  */
 export declare const transform: MultiFn2<IShape, ReadonlyMat, IShape>;
 //# sourceMappingURL=transform.d.ts.map

package/transform.js

@@ -12,20 +12,46 @@ import { Quadratic } from "./api/quadratic.js";
 import { Text } from "./api/text.js";
 import { Triangle } from "./api/triangle.js";
 import { asPath } from "./as-path.js";
-import { asPolygon } from "./as-polygon.js";
 import { __copyAttribs } from "./internal/copy.js";
 import { __dispatch } from "./internal/dispatch.js";
 import { __transformedShape as tx, __transformedShape3 as tx3, } from "./internal/transform.js";
+import { vertices } from "./vertices.js";
 /**
- * Transforms given shape with provided matrix. Some shape types will be
- * automatically converted to other types prior to transformation because they
- * cannot be reliably represented in their original type anymore, this
- * includes:
+ * Transforms given shape with provided matrix.
  *
- * - Arc => Path (cubics)
- * - Circle => Path (cubics)
- * - Ellipse => Path (cubics)
- * - Rect => Polygon
+ * @remarks
+ * A 2x3 transform matrix is assumed for 2D shapes and 4x4 matrix for 3D shapes.
+ * Some shape types will be automatically converted to other types prior to
+ * transformation because they cannot be reliably represented in their original
+ * type anymore, this includes:
+ *
+ * - {@link Arc} => {@link Path} (cubics)
+ * - {@link Circle} => {@link Path} (cubics)
+ * - {@link Ellipse} => {@link Path} (cubics)
+ * - {@link Rect} => {@link Quad}
+ *
+ * Currently implemented for:
+ *
+ * - {@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 Text}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param mat
  */
 export const transform = defmulti(__dispatch, {
     circle: "arc",
@@ -52,7 +78,7 @@ export const transform = defmulti(__dispatch, {
     polyline: tx(Polyline),
     quad: tx(Quad),
     quadratic: tx(Quadratic),
-    rect: ($, mat) => transform(asPolygon($), mat),
+    rect: ($, mat) => transform(new Quad(vertices($), __copyAttribs($)), mat),
     text: ($, mat) => new Text(mulV([], mat, $.pos), $.body, __copyAttribs($)),
     tri: tx(Triangle),
 });

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)),