@thi.ng/geom 3.3.1 → 3.4.2

package/api/triangle.d.ts

@@ -1,8 +1,9 @@
-import type { IHiccupShape } from "@thi.ng/geom-api";
+import type { Attribs, IHiccupShape } from "@thi.ng/geom-api";
 import { APC } from "./apc.js";
 export declare class Triangle extends APC implements IHiccupShape {
     get type(): string;
     copy(): Triangle;
-    toHiccup(): (string | import("@thi.ng/geom-api").Attribs | undefined)[];
+    withAttribs(attribs: Attribs): Triangle;
+    toHiccup(): (string | Attribs | undefined)[];
 }
 //# sourceMappingURL=triangle.d.ts.map

package/api/triangle.js

@@ -7,6 +7,9 @@ export class Triangle extends APC {
     copy() {
         return __copyShape(Triangle, this);
     }
+    withAttribs(attribs) {
+        return new Triangle(this.points, attribs);
+    }
     toHiccup() {
         return ["polygon", this.attribs, this.points];
     }

package/apply-transforms.d.ts

@@ -0,0 +1,33 @@
+import type { MultiFn1 } from "@thi.ng/defmulti";
+import type { IShape } from "@thi.ng/geom-api";
+/**
+ * Applies any spatial transformation attributes defined (if any) for the given
+ * shape. If no such attributes exist, the original shape is returned as is.
+ *
+ * @remarks
+ * The following attributes are considered:
+ *
+ * - transform: A 2x3 (for 2D) or 4x4 (for 3D) transformation matrix
+ * - translate: Translation/offset vector
+ * - scale: A scale factor (scalar or vector)
+ * - rotate: Rotation angle (in radians)
+ *
+ * If the `transform` attrib is given, the others will be ignored. If any of the
+ * other 3 attribs is provided, the order of application is: rotate, scale,
+ * translate. Any of these relevant attributes will be removed from the
+ * transformed shapes to ensure idempotent behavior.
+ *
+ * For (@link group} shapes, the children are processed in depth-first order
+ * with any transformations to the group itself applied last.
+ *
+ * Note: Where possible, this function delegates to {@link rotate},
+ * {@link scale}, {@link translate} to realize individual/partial transformation
+ * aspects to increase the likelihodd of retaining original shape types. E.g.
+ * uniformly scaling a circle with a scalar factor retains a circle, but scaling
+ * non-uniformly will convert it to an ellipse... Similarly, rotating a rect
+ * will convert it to a quad etc.
+ *
+ * @param shape
+ */
+export declare const applyTransforms: MultiFn1<IShape, IShape>;
+//# sourceMappingURL=apply-transforms.d.ts.map

package/apply-transforms.js

@@ -0,0 +1,59 @@
+import { withoutKeysObj } from "@thi.ng/associative/without-keys";
+import { DEFAULT, defmulti } from "@thi.ng/defmulti/defmulti";
+import { __dispatch } from "./internal/dispatch.js";
+import { rotate } from "./rotate.js";
+import { scale } from "./scale.js";
+import { transform } from "./transform.js";
+import { translate } from "./translate.js";
+/** @internal */
+const __apply = ($) => {
+    let attribs = $.attribs;
+    if (!attribs)
+        return $;
+    const { transform: tx, translate: t, rotate: r, scale: s } = attribs;
+    if (tx)
+        return transform($.withAttribs(withoutKeysObj(attribs, ["transform"])), tx);
+    if (!(t || r || s))
+        return $;
+    $ = $.withAttribs(withoutKeysObj(attribs, ["translate", "rotate", "scale"]));
+    if (r)
+        $ = rotate($, r);
+    if (s)
+        $ = scale($, s);
+    if (t)
+        $ = translate($, t);
+    return $;
+};
+/**
+ * Applies any spatial transformation attributes defined (if any) for the given
+ * shape. If no such attributes exist, the original shape is returned as is.
+ *
+ * @remarks
+ * The following attributes are considered:
+ *
+ * - transform: A 2x3 (for 2D) or 4x4 (for 3D) transformation matrix
+ * - translate: Translation/offset vector
+ * - scale: A scale factor (scalar or vector)
+ * - rotate: Rotation angle (in radians)
+ *
+ * If the `transform` attrib is given, the others will be ignored. If any of the
+ * other 3 attribs is provided, the order of application is: rotate, scale,
+ * translate. Any of these relevant attributes will be removed from the
+ * transformed shapes to ensure idempotent behavior.
+ *
+ * For (@link group} shapes, the children are processed in depth-first order
+ * with any transformations to the group itself applied last.
+ *
+ * Note: Where possible, this function delegates to {@link rotate},
+ * {@link scale}, {@link translate} to realize individual/partial transformation
+ * aspects to increase the likelihodd of retaining original shape types. E.g.
+ * uniformly scaling a circle with a scalar factor retains a circle, but scaling
+ * non-uniformly will convert it to an ellipse... Similarly, rotating a rect
+ * will convert it to a quad etc.
+ *
+ * @param shape
+ */
+export const applyTransforms = defmulti(__dispatch, {}, {
+    [DEFAULT]: __apply,
+    group: ($) => __apply($.copyTransformed((x) => applyTransforms(x))),
+});

package/arc-length.d.ts

@@ -7,16 +7,17 @@ import type { IShape } from "@thi.ng/geom-api";
  *
  * Implemented for:
  *
- * - Circle
- * - Ellipse
- * - Group
- * - Line
- * - Polygon
- * - Polyline
- * - Quad
- * - Rect
- * - Triangle
+ * - {@link Circle}
+ * - {@link Ellipse}
+ * - {@link Group} (total sum of child circumferences)
+ * - {@link Line}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Rect}
+ * - {@link Triangle}
  *
+ * @param shape
  */
 export declare const arcLength: MultiFn1<IShape, number>;
 //# sourceMappingURL=arc-length.d.ts.map

package/arc-length.js

@@ -10,16 +10,17 @@ import { __dispatch } from "./internal/dispatch.js";
  *
  * Implemented for:
  *
- * - Circle
- * - Ellipse
- * - Group
- * - Line
- * - Polygon
- * - Polyline
- * - Quad
- * - Rect
- * - Triangle
+ * - {@link Circle}
+ * - {@link Ellipse}
+ * - {@link Group} (total sum of child circumferences)
+ * - {@link Line}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Rect}
+ * - {@link Triangle}
  *
+ * @param shape
  */
 export const arcLength = defmulti(__dispatch, {
     quad: "poly",
@@ -34,7 +35,7 @@ export const arcLength = defmulti(__dispatch, {
     line: ({ points }) => dist(points[0], points[1]),
     poly: ({ points }) => perimeter(points, points.length, true),
     polyline: ({ points }) => perimeter(points, points.length),
-    rect: ({ size }) => 2 * (size[0] + size[1]),
+    rect: ({ size: [w, h] }) => 2 * (w + h),
     tri: ({ points }) => dist(points[0], points[1]) +
         dist(points[1], points[2]) +
         dist(points[2], points[0]),

package/area.d.ts

@@ -1,34 +1,35 @@
 import type { MultiFn1O } from "@thi.ng/defmulti";
 import type { IShape } from "@thi.ng/geom-api";
 /**
- * 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

package/area.js

@@ -2,36 +2,38 @@ import { DEFAULT, defmulti } from "@thi.ng/defmulti/defmulti";
 import { polyArea2 } from "@thi.ng/geom-poly-utils/area";
 import { PI } from "@thi.ng/math/api";
 import { signedArea2 } from "@thi.ng/vectors/signed-area";
+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
@@ -44,6 +46,7 @@ export const area = defmulti(__dispatch, { quad: "poly" }, {
     circle: ($) => PI * $.r ** 2,
     ellipse: ($) => PI * $.r[0] * $.r[1],
     group: ({ children }) => children.reduce((sum, $) => sum + area($, false), 0),
+    path: ($) => ($.closed ? area(asPolygon($)) : 0),
     plane: () => Infinity,
     poly: ($, signed) => {
         const area = polyArea2($.points);

package/as-cubic.d.ts

@@ -1,5 +1,41 @@
 import type { MultiFn1O } from "@thi.ng/defmulti";
 import type { CubicOpts, IShape } from "@thi.ng/geom-api";
 import { Cubic } from "./api/cubic.js";
+/**
+ * Converts given shape into an array of {@link Cubic} curves. For some shapes
+ * (see below) the conversion supports optionally provided {@link CubicOpts}.
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - {@link Arc}
+ * - {@link Circle}
+ * - {@link Cubic}
+ * - {@link Ellipse}
+ * - {@link Group}
+ * - {@link Line}
+ * - {@link Path}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Rect}
+ * - {@link Triangle}
+ *
+ * Shape types supporting custom conversion options (see
+ * [@thi.ng/geom-splines](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-splines#cubic-curve-conversion-from-polygons--polylines)
+ * for more details):
+ *
+ * - {@link Group} (only used for eligible children)
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Rect}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param opts
+ */
 export declare const asCubic: MultiFn1O<IShape, Partial<CubicOpts>, Cubic[]>;
 //# sourceMappingURL=as-cubic.d.ts.map

package/as-cubic.js

@@ -9,6 +9,42 @@ import { asPolygon } from "./as-polygon.js";
 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. For some shapes
+ * (see below) the conversion supports optionally provided {@link CubicOpts}.
+ *
+ * @remarks
+ * Currently implemented for:
+ *
+ * - {@link Arc}
+ * - {@link Circle}
+ * - {@link Cubic}
+ * - {@link Ellipse}
+ * - {@link Group}
+ * - {@link Line}
+ * - {@link Path}
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Rect}
+ * - {@link Triangle}
+ *
+ * Shape types supporting custom conversion options (see
+ * [@thi.ng/geom-splines](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-splines#cubic-curve-conversion-from-polygons--polylines)
+ * for more details):
+ *
+ * - {@link Group} (only used for eligible children)
+ * - {@link Polygon}
+ * - {@link Polyline}
+ * - {@link Quad}
+ * - {@link Quadratic}
+ * - {@link Rect}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param opts
+ */
 export const asCubic = defmulti(__dispatch, {
     ellipse: "circle",
     quad: "poly",
@@ -17,22 +53,27 @@ export const asCubic = defmulti(__dispatch, {
     arc: cubicFromArc,
     circle: ($) => asCubic(arc($.pos, $.r, 0, 0, TAU, true, true)),
     cubic: ($) => [$],
-    group: ($) => [...mapcat(asCubic, $.children)],
+    group: ($, opts) => [
+        ...mapcat((x) => asCubic(x, opts), $.children),
+    ],
     line: ({ attribs, points }) => [
         cubicFromLine(points[0], points[1], { ...attribs }),
     ],
     path: ($) => [
         ...mapcat((s) => (s.geo ? asCubic(s.geo) : null), $.segments),
     ],
-    poly: ($, opts = {}) => polyCubic($, opts, closedCubicFromBreakPoints, closedCubicFromControlPoints),
-    polyline: ($, opts = {}) => polyCubic($, opts, openCubicFromBreakPoints, openCubicFromControlPoints),
+    poly: ($, opts = {}) => __polyCubic($, opts, closedCubicFromBreakPoints, closedCubicFromControlPoints),
+    polyline: ($, opts = {}) => __polyCubic($, opts, openCubicFromBreakPoints, openCubicFromControlPoints),
     quadratic: ({ attribs, points }) => [
         cubicFromQuadratic(points[0], points[1], points[2], { ...attribs }),
     ],
     rect: ($, opts) => asCubic(asPolygon($), opts),
 });
+/**
+ * @internal
+ */
 // prettier-ignore
-const polyCubic = ($, opts, breakPoints, controlPoints) => {
+const __polyCubic = ($, opts, breakPoints, controlPoints) => {
     opts = { breakPoints: false, scale: 1 / 3, uniform: false, ...opts };
     return (opts.breakPoints
         ? breakPoints($.points, opts.scale, opts.uniform)

package/as-path.d.ts

@@ -1,3 +1,10 @@
 import type { Attribs, IShape } from "@thi.ng/geom-api";
+/**
+ * Converts given shape into a {@link Path} (via {@link asCubic} and
+ * {@link pathFromCubics}).
+ *
+ * @param src
+ * @param attribs
+ */
 export declare const asPath: (src: IShape, attribs?: Attribs) => import("./index.js").Path;
 //# sourceMappingURL=as-path.d.ts.map

package/as-path.js

@@ -1,4 +1,11 @@
 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, attribs) => pathFromCubics(asCubic(src), attribs || __copyAttribs(src));

package/as-polygon.d.ts

@@ -1,5 +1,25 @@
 import type { MultiFn1O } from "@thi.ng/defmulti";
 import type { IShape, SamplingOpts } from "@thi.ng/geom-api";
 import { Polygon } from "./api/polygon.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:
+ *
+ * - {@link Circle}
+ * - {@link Ellipse}
+ * - {@link Line}
+ * - {@link Path}
+ * - {@link Poly}
+ * - {@link Polyline} (will be closed)
+ * - {@link Quad}
+ * - {@link Rect}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param opts
+ */
 export declare const asPolygon: MultiFn1O<IShape, number | Partial<SamplingOpts>, Polygon>;
 //# sourceMappingURL=as-polygon.d.ts.map

package/as-polygon.js

@@ -3,6 +3,26 @@ import { Polygon } from "./api/polygon.js";
 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:
+ *
+ * - {@link Circle}
+ * - {@link Ellipse}
+ * - {@link Line}
+ * - {@link Path}
+ * - {@link Poly}
+ * - {@link Polyline} (will be closed)
+ * - {@link Quad}
+ * - {@link Rect}
+ * - {@link Triangle}
+ *
+ * @param shape
+ * @param opts
+ */
 export const asPolygon = defmulti(__dispatch, {
     circle: "points",
     ellipse: "points",

package/as-polyline.d.ts

@@ -1,5 +1,28 @@
 import type { MultiFn1O } from "@thi.ng/defmulti";
 import type { IShape, SamplingOpts } from "@thi.ng/geom-api";
 import { Polyline } from "./api/polyline.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}
+ *
+ * @param shape
+ * @param opts
+ */
 export declare const asPolyline: MultiFn1O<IShape, number | Partial<SamplingOpts>, Polyline>;
 //# sourceMappingURL=as-polyline.d.ts.map

package/as-polyline.js

@@ -4,6 +4,29 @@ import { Polyline } from "./api/polyline.js";
 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}
+ *
+ * @param shape
+ * @param opts
+ */
 export const asPolyline = defmulti(__dispatch, {
     arc: "points",
     circle: "poly",

package/bounds.d.ts

@@ -1,4 +1,32 @@
 import type { MultiFn1O } from "@thi.ng/defmulti";
 import type { AABBLike, IShape } from "@thi.ng/geom-api";
+/**
+ * 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)
+ *
+ * @param shape
+ * @param margin
+ */
 export declare const bounds: MultiFn1O<IShape, number, AABBLike | undefined>;
 //# sourceMappingURL=bounds.d.ts.map

package/bounds.js

@@ -19,6 +19,34 @@ import { Rect } from "./api/rect.js";
 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)
+ *
+ * @param shape
+ * @param margin
+ */
 export const bounds = defmulti(__dispatch, {
     aabb: "rect",
     bpatch: "points",
@@ -51,5 +79,5 @@ export const bounds = defmulti(__dispatch, {
     rect: ($, margin = 0) => margin === 0
         ? $.copy()
         : $.copy().offset(margin),
-    text: ($, margin = 0) => new Rect(subN2([], $.pos, margin), [0, 0]), // TODO
+    text: ($, margin = 0) => new Rect(subN2([], $.pos, margin), margin * 2),
 });

package/center.d.ts

@@ -1,5 +1,16 @@
 import type { MultiFn1O } from "@thi.ng/defmulti";
 import type { IShape } from "@thi.ng/geom-api";
 import { ReadonlyVec } from "@thi.ng/vectors/api";
+/**
+ * Returns copy of given shape centered around optionally provided point `p`
+ * (default: worldspace origin).
+ *
+ * @remarks
+ * Implemented for all shape types supported by {@link centroid} and
+ * {@link translate}.
+ *
+ * @param shape
+ * @param p
+ */
 export declare const center: MultiFn1O<IShape, ReadonlyVec, IShape | undefined>;
 //# sourceMappingURL=center.d.ts.map