@thi.ng/geom 7.0.1 → 8.0.0

package/api.d.ts

@@ -0,0 +1,193 @@
+import type { Fn, ICopy, IToHiccup } from "@thi.ng/api";
+import * as isec from "@thi.ng/geom-isec/api";
+import * as sample from "@thi.ng/geom-resample/api";
+import type * as sdc from "@thi.ng/geom-subdiv-curve";
+import type * as tess from "@thi.ng/geom-tessellate";
+import type { ReadonlyMat } from "@thi.ng/matrices";
+import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
+export type IntersectionResult = isec.IntersectionResult;
+export declare const IntersectionType: typeof isec.IntersectionType;
+export declare const NONE: isec.IntersectionResult;
+/**
+ * Sets number of default samples for all operations involving shape sampling
+ * (e.g. {@link vertices}, {@link asPolygon}, {@link asPolyline}).
+ *
+ * @param num
+ */
+export declare const setDefaultSamples: (n: number) => number;
+export type SamplingOpts = sample.SamplingOpts;
+export type SubdivKernel = sdc.SubdivKernel;
+export type Tessellator = tess.Tessellator;
+export type ITessellation = tess.ITessellation;
+export interface Attribs {
+    /**
+     * Shape resampling options/resolution.
+     */
+    __samples?: Partial<SamplingOpts> | number;
+    /**
+     * Control attribute to define the number of fractional digits for numeric
+     * values in the serialized SVG string.
+     *
+     * @defaultValue 3
+     */
+    __prec?: number;
+    /**
+     * 2D rotation angle (in radians)
+     */
+    rotate?: number;
+    /**
+     * 3D X rotation angle (in radians)
+     */
+    rotateX?: number;
+    /**
+     * 3D Y rotation angle (in radians)
+     */
+    rotateY?: number;
+    /**
+     * 3D Z rotation angle (in radians)
+     */
+    rotateZ?: number;
+    /**
+     * Uniform or non-uniform scale factor.
+     */
+    scale?: number | ReadonlyVec;
+    /**
+     * Translation offset.
+     */
+    translate?: ReadonlyVec;
+    /**
+     * Transformation matrix (2x3 for 2D, 4x4 for 3D).
+     */
+    transform?: ReadonlyVec;
+    /**
+     * Fill color
+     */
+    fill?: any;
+    /**
+     * Stroke color
+     */
+    stroke?: any;
+    /**
+     * Stroke weight
+     */
+    weight?: number;
+    [id: string]: any;
+}
+export interface GroupAttribs extends Attribs {
+    /**
+     * Currently only used by thi.ng/hiccup-canvas. Canvas background color,
+     * should only should be used for a root group.
+     */
+    __background?: any;
+    /**
+     * Only used by thi.ng/hiccup-canvas. Force clearing of the canvas before
+     * drawing. Takes priority over {@link GroupAttribs.__background} and should
+     * only should be used for a root group.
+     *
+     * @defaultValue false
+     */
+    __clear?: boolean;
+    /**
+     * Only used for SVG serialization. Inkscape payer name
+     */
+    __inkscapeLayer?: string;
+}
+export interface IAttributed<T> {
+    attribs?: Attribs;
+    withAttribs(attribs: Attribs): T;
+}
+export interface ICopyTransformed<A, B = A> {
+    copyTransformed(fn: Fn<A, B>): this;
+}
+export interface IShape<T extends IShape = IShape<any>> extends IAttributed<T>, ICopy<T> {
+    readonly type: number | string;
+    readonly dim: number;
+}
+export type IShape2<T extends IShape2 = IShape2<any>> = IShape<T> & {
+    readonly dim: 2;
+};
+export type IShape3<T extends IShape3 = IShape3<any>> = IShape<T> & {
+    readonly dim: 3;
+};
+export interface AABBLike extends IShape<AABBLike> {
+    pos: Vec;
+    size: Vec;
+    min(): Vec;
+    max(): Vec;
+    offset(x: number): this;
+}
+export interface SphereLike extends IShape<SphereLike> {
+    pos: Vec;
+    r: number;
+}
+export interface PCLike extends IShape<PCLike> {
+    points: Vec[];
+}
+export interface PCLikeConstructor<T extends PCLike = PCLike> {
+    new (pts: Vec[], attribs?: Attribs): T;
+}
+export interface IHiccupShape extends IShape, IToHiccup {
+}
+export type IHiccupShape2<T extends IHiccupShape2 = IHiccupShape2<any>> = IHiccupShape & IShape2<T>;
+export type IHiccupShape3<T extends IHiccupShape3 = IHiccupShape3<any>> = IHiccupShape & IShape3<T>;
+export type SegmentType2 = "m" | "l" | "p" | "a" | "c" | "q" | "z";
+/**
+ * Currently no 3D arc segments supported
+ */
+export type SegmentType3 = Exclude<SegmentType2, "a">;
+export type PathSegment = PathSegment2 | PathSegment3;
+export interface PathSegment2 {
+    type: SegmentType2;
+    point?: Vec;
+    geo?: IShape2 & IHiccupPathSegment;
+}
+export interface PathSegment3 {
+    type: SegmentType3;
+    point?: Vec;
+    geo?: IShape3 & IHiccupPathSegment;
+}
+export interface IHiccupPathSegment {
+    toHiccupPathSegments(): HiccupPathSegment[];
+}
+export type HiccupPathSegment = [string, ...any[]];
+export interface IPath<S extends PathSegment> extends IShape {
+    segments: S[];
+    subPaths: S[][];
+    readonly closed: boolean;
+    close(): this;
+    addSegments(...segments: S[]): this;
+    addSubPaths(...paths: S[][]): this;
+    isComplex(): boolean;
+}
+export interface PathConstructor<P extends IPath<S>, S extends PathSegment> {
+    new (segments: S[], subPaths: S[][], attribs?: Attribs): P;
+}
+export interface CubicOpts {
+    /**
+     * Controls behavior of curve conversion/interpolation:
+     *
+     * - `default`: Original vertices are used control points (see
+     *   [`closedCubicFromControlPoints()`](https://docs.thi.ng/umbrella/geom-splines/functions/closedCubicFromControlPoints.html))
+     * - `break`: Original vertices are used as curve points, tangents are
+     *   computed automatically (see
+     *   [`closedCubicFromBreakPoints()`](https://docs.thi.ng/umbrella/geom-splines/functions/closedCubicFromBreakPoints.html))
+     * - `hobby`: Use John Hobby's interpolation algorithm (see
+     *   [`cubicHobby2()`](https://docs.thi.ng/umbrella/geom-splines/functions/cubicHobby2.html))
+     */
+    mode: "default" | "break" | "hobby";
+    /**
+     * True, to enable uniform tangent scaling. If false (default), each
+     * tangent will be also scaled by the length of its related parent
+     * edge in the source shape.
+     *
+     * @remarks
+     * Unused for `hobby` mode.
+     */
+    uniform: boolean;
+    /**
+     * Tangent scale factor. Actual length in uniform scaling mode.
+     */
+    scale: number;
+}
+export type TransformVertexFn = Fn<ReadonlyVec, ReadonlyMat>;
+//# sourceMappingURL=api.d.ts.map

package/api.js

@@ -0,0 +1,10 @@
+import * as isec from "@thi.ng/geom-isec/api";
+import * as sample from "@thi.ng/geom-resample/api";
+const IntersectionType = isec.IntersectionType;
+const NONE = isec.NONE;
+const setDefaultSamples = sample.setDefaultSamples;
+export {
+  IntersectionType,
+  NONE,
+  setDefaultSamples
+};

package/apply-transforms.d.ts

@@ -1,5 +1,20 @@
 import type { MultiFn1 } from "@thi.ng/defmulti";
-import type { IShape } from "@thi.ng/geom-api";
+import type { IShape, IShape2, IShape3 } from "./api.js";
+import type { Arc } from "./api/arc.js";
+import type { Circle } from "./api/circle.js";
+import type { Ellipse } from "./api/ellipse.js";
+import type { Rect } from "./api/rect.js";
+/**
+ * Function overrides for {@link applyTransforms}.
+ */
+export type ApplyTransformsFn = {
+    (shape: Arc): IShape2;
+    (shape: Circle): IShape2;
+    (shape: Ellipse): IShape2;
+    (shape: Rect): IShape2;
+    <T extends IShape2>(shape: T): T;
+    <T extends IShape3>(shape: T): T;
+} & MultiFn1<IShape, IShape>;
 /**
  * Applies any spatial transformation attributes defined (if any) for the given
  * shape. If no such attributes exist, the original shape is returned as is.
@@ -7,10 +22,11 @@ import type { IShape } from "@thi.ng/geom-api";
  * @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)
+ * - `transform`: A 2x3 (for 2D) or 4x4 (for 3D) transformation matrix
+ * - `translate`: Translation/offset vector
+ * - `scale`: A scale factor (scalar for uniform or vector for non-uniform)
+ * - `rotate`: Rotation angle (in radians, 2D only)
+ * - `rotate[XYZ]`: Rotation angle (in radians, 3D only)
  *
  * 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,
@@ -18,16 +34,22 @@ import type { IShape } from "@thi.ng/geom-api";
  * 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.
+ * with any transformations to the group itself applied post-order.
  *
- * 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
+ * Note: Where possible, this function delegates to {@link rotate} (for 2D),
+ * {@link rotateX}, {@link rotateY}, {@link rotateZ} (all for 3D), {@link scale}
+ * and {@link translate} to realize individual/partial transformation aspects to
+ * increase the likelihood 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.
  *
+ * For those shape types for which a shape conversion _might_ be involved, the
+ * function only returns a generic `IShape2` or `IShape3` type. To find out if a
+ * shape conversion will apply, please consult the docs for the above linked
+ * transformation functions.
+ *
  * @param shape
  */
-export declare const applyTransforms: MultiFn1<IShape, IShape>;
+export declare const applyTransforms: ApplyTransformsFn;
 //# sourceMappingURL=apply-transforms.d.ts.map

package/apply-transforms.js

@@ -1,15 +1,32 @@
 import { withoutKeysObj } from "@thi.ng/associative/without-keys";
 import { DEFAULT, defmulti } from "@thi.ng/defmulti/defmulti";
 import { __dispatch } from "./internal/dispatch.js";
+import { rotateX, rotateY, rotateZ } from "./rotate-around-axis.js";
 import { rotate } from "./rotate.js";
 import { scale } from "./scale.js";
 import { transform } from "./transform.js";
 import { translate } from "./translate.js";
-const TX_ATTRIBS = ["transform", "translate", "rotate", "scale"];
+const TX_ATTRIBS = [
+  "rotate",
+  "rotateX",
+  "rotateY",
+  "rotateZ",
+  "scale",
+  "transform",
+  "translate"
+];
 const __apply = ($) => {
   let attribs = $.attribs;
   if (!attribs) return $;
-  const { transform: tx, translate: t, rotate: r, scale: s } = attribs;
+  const {
+    transform: tx,
+    translate: t,
+    rotate: r,
+    scale: s,
+    rotateX: rx,
+    rotateY: ry,
+    rotateZ: rz
+  } = attribs;
   if (tx)
     return transform(
       $.withAttribs(withoutKeysObj(attribs, TX_ATTRIBS)),
@@ -17,14 +34,17 @@ const __apply = ($) => {
     );
   if (!(t || r || s)) return $;
   $ = $.withAttribs(withoutKeysObj(attribs, TX_ATTRIBS));
-  if (r) $ = rotate($, r);
+  if (r != null && $.dim === 2) $ = rotate($, r);
+  if (rx != null && $.dim === 3) $ = rotateX($, rx);
+  if (ry != null && $.dim === 3) $ = rotateY($, ry);
+  if (rz != null && $.dim === 3) $ = rotateZ($, rz);
   if (s) $ = scale($, s);
   if (t) $ = translate($, t);
   return $;
 };
 const applyTransforms = defmulti(
   __dispatch,
-  {},
+  { group3: "group" },
   {
     [DEFAULT]: __apply,
     group: ($) => __apply($.copyTransformed((x) => applyTransforms(x)))

package/arc-length.d.ts

@@ -1,22 +1,36 @@
 import type { MultiFn1 } from "@thi.ng/defmulti";
-import type { IShape } from "@thi.ng/geom-api";
+import type { IShape } from "./api.js";
 /**
- * Returns the arc length / perimeter / circumference of the given
- * shape. For groups calls {@link arcLength} for each child and returns the
- * sum of results.
+ * Returns the arc length / perimeter / circumference of the given shape. For
+ * groups calls {@link arcLength} for each child and returns the sum of results.
  *
  * Implemented for:
  *
+ * - {@link Arc}
  * - {@link Circle}
  * - {@link ComplexPolygon}
+ * - {@link Cubic}
+ * - {@link Cubic3}
  * - {@link Ellipse}
  * - {@link Group} (total sum of child circumferences)
+ * - {@link Group3} (total sum of child circumferences)
  * - {@link Line}
+ * - {@link Line3}
+ * - {@link Path}
+ * - {@link Path3}
  * - {@link Polygon}
+ * - {@link Polygon3}
  * - {@link Polyline}
+ * - {@link Polyline3}
  * - {@link Quad}
+ * - {@link Quad3}
+ * - {@link Quadratic}
+ * - {@link Quadratic3}
  * - {@link Rect}
  * - {@link Triangle}
+ * - {@link Triangle3}
+ *
+ * For all other types the function returns 0.
  *
  * @param shape
  */

package/arc-length.js

@@ -1,4 +1,4 @@
-import { defmulti } from "@thi.ng/defmulti/defmulti";
+import { DEFAULT, defmulti } from "@thi.ng/defmulti/defmulti";
 import { perimeter } from "@thi.ng/geom-poly-utils/perimeter";
 import { PI, TAU } from "@thi.ng/math/api";
 import { dist } from "@thi.ng/vectors/dist";
@@ -8,10 +8,25 @@ import { __dispatch } from "./internal/dispatch.js";
 const arcLength = defmulti(
   __dispatch,
   {
+    arc: "$aspolyline",
+    cubic: "$aspolyline",
+    cubic3: "$aspolyline",
+    group3: "group",
+    line3: "line",
+    path3: "path",
+    poly3: "poly",
+    polyline3: "polyline",
     quad: "poly",
-    tri: "poly"
+    quad3: "poly",
+    quadratic: "$aspolyline",
+    quadratic3: "$aspolyline",
+    tri: "poly",
+    tri3: "tri"
   },
   {
+    [DEFAULT]: () => 0,
+    $aspoly: ($) => asPolygon($).reduce((acc, p) => acc + arcLength(p), 0),
+    $aspolyline: ($) => asPolyline($).reduce((acc, p) => acc + arcLength(p), 0),
     circle: ($) => TAU * $.r,
     complexpoly: ($) => [$.boundary, ...$.children].reduce(
       (acc, c) => acc + arcLength(c),
@@ -31,7 +46,7 @@ const arcLength = defmulti(
       );
     },
     poly: ({ points }) => perimeter(points, points.length, true),
-    polyline: ({ points }) => perimeter(points, points.length),
+    polyline: ({ points }) => perimeter(points),
     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/arc.d.ts

@@ -1,4 +1,4 @@
-import type { Attribs } from "@thi.ng/geom-api";
+import type { Attribs } from "./api.js";
 import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
 import { Arc } from "./api/arc.js";
 /**

package/area.d.ts

@@ -1,5 +1,5 @@
 import type { MultiFn1O } from "@thi.ng/defmulti";
-import type { IShape } from "@thi.ng/geom-api";
+import type { IShape } from "./api.js";
 /**
  * Computes the possibly signed (unsigned by default) surface area of given
  * `shape`. For groups calls itself for each child and returns sum of unsigned
@@ -9,29 +9,25 @@ import type { IShape } from "@thi.ng/geom-api";
  * 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.
- *
  * Currently implemented for:
  *
  * - {@link AABB}
+ * - {@link Arc} (sector area)
  * - {@link Circle}
  * - {@link ComplexPolygon}
- * - {@link Cubic}
  * - {@link Ellipse}
  * - {@link Group}
- * - {@link Line}
+ * - {@link Group3}
  * - {@link Path} (closed only & via poly conversion)
- * - {@link Plane}
- * - {@link Points}
+ * - {@link Plane} (infinity)
  * - {@link Polygon}
- * - {@link Polyline}
  * - {@link Quad}
- * - {@link Quadratic}
- * - {@link Ray}
  * - {@link Rect}
  * - {@link Sphere}
  * - {@link Triangle}
  *
+ * For all other shape types the function returns 0.
+ *
  * @param shape - shape to operate on
  * @param signed - true, if signed area
  */

package/area.js

@@ -6,8 +6,9 @@ import { asPolygon } from "./as-polygon.js";
 import { __dispatch } from "./internal/dispatch.js";
 const area = defmulti(
   __dispatch,
-  { quad: "poly" },
+  { group3: "group", quad: "poly" },
   {
+    [DEFAULT]: () => 0,
     aabb: ({ size: [w, h, d] }) => 2 * (w * h + w * d + h * d),
     arc: (
       // http://cut-the-knot.org/Generalization/Cavalieri2.shtml
@@ -30,8 +31,7 @@ const area = defmulti(
     tri: ($, signed) => {
       const area2 = 0.5 * signedArea2(...$.points);
       return signed ? area2 : Math.abs(area2);
-    },
-    [DEFAULT]: () => 0
+    }
   }
 );
 export {

package/as-cubic.d.ts

@@ -1,43 +1,69 @@
 import type { MultiFn1O } from "@thi.ng/defmulti";
-import type { CubicOpts, IShape } from "@thi.ng/geom-api";
+import type { CubicOpts, IShape, IShape2, IShape3 } from "./api.js";
 import { Cubic } from "./api/cubic.js";
+import { Cubic3 } from "./api/cubic3.js";
+export interface AsCubicOpts extends CubicOpts {
+    attribs: boolean;
+}
 /**
- * Converts given shape into an array of {@link Cubic} curves. For some shapes
- * (see below) the conversion supports optionally provided {@link CubicOpts}.
+ * Function overrides for {@link asCubic}.
+ */
+export type AsCubicFn = {
+    <T extends IShape2>(shape: T, opts?: Partial<AsCubicOpts>): Cubic[];
+    <T extends IShape3>(shape: T, opts?: Partial<AsCubicOpts>): Cubic3[];
+} & MultiFn1O<IShape, Partial<AsCubicOpts>, (Cubic | Cubic3)[]>;
+/**
+ * Converts given shape boundary into an array of {@link Cubic} or
+ * {@link Cubic3} curves. For some shapes (see below) the conversion supports
+ * optionally provided {@link CubicOpts}.
  *
  * @remarks
  * Currently implemented for:
  *
  * - {@link Arc}
+ * - {@link BPatch}
  * - {@link Circle}
  * - {@link ComplexPolygon}
  * - {@link Cubic}
+ * - {@link Cubic3}
  * - {@link Ellipse}
  * - {@link Group}
+ * - {@link Group3}
  * - {@link Line}
+ * - {@link Line3}
  * - {@link Path}
+ * - {@link Path3}
  * - {@link Polygon}
+ * - {@link Polygon3}
  * - {@link Polyline}
+ * - {@link Polyline3}
  * - {@link Quad}
+ * - {@link Quad3}
  * - {@link Quadratic}
+ * - {@link Quadratic3}
  * - {@link Rect}
  * - {@link Triangle}
+ * - {@link Triangle3}
  *
  * 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 Group3} (only used for eligible children)
  * - {@link ComplexPolygon}
  * - {@link Polygon}
+ * - {@link Polygon3}
  * - {@link Polyline}
+ * - {@link Polyline3}
  * - {@link Quad}
- * - {@link Quadratic}
+ * - {@link Quad3}
  * - {@link Rect}
  * - {@link Triangle}
+ * - {@link Triangle3}
  *
  * @param shape
  * @param opts
  */
-export declare const asCubic: MultiFn1O<IShape, Partial<CubicOpts>, Cubic[]>;
+export declare const asCubic: AsCubicFn;
 //# sourceMappingURL=as-cubic.d.ts.map