@thi.ng/geom-tessellate 2.1.131 → 3.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-04-23T07:02:18Z
+- **Last updated**: 2024-06-21T19:34:38Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,52 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+# [3.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom-tessellate@3.0.0) (2024-06-21)
+
+#### 🛑 Breaking changes
+
+- update/rewrite tessellate() & all tessellator impls ([97f1f66](https://github.com/thi-ng/umbrella/commit/97f1f66))
+- BREAKING CHANGE: update tessellate() & all tessellator implementations
+  - `Tessellator`s now collect/append results to a `Tessellation` object, consisting of
+    a single point array and an array of face vertex IDs
+  - add `tessellatedPoints()` and `indexedPoints()` to produce face/point arrays from a result `Tessellation`
+  - remove again `edgeSplitWithThreshold()` & `triFanSplitWithThreshold()`,
+    to be replaced with a more general alternative approach
+- migrate types from [@thi.ng/geom-api](https://github.com/thi-ng/umbrella/tree/main/packages/geom-api) ([72cff99](https://github.com/thi-ng/umbrella/commit/72cff99))
+- BREAKING CHANGE: migrate/internalize types from [@thi.ng/geom-api](https://github.com/thi-ng/umbrella/tree/main/packages/geom-api)
+  - add/migrate Tessellator, Tessellation
+  - update imports
+  - update deps
+- add/update tessellation types & handling ([c0fb454](https://github.com/thi-ng/umbrella/commit/c0fb454))
+- BREAKING CHANGE: add `ITessellation` interface & impls, update tessellators & `tessellate()`
+  - rename/expand `Tessellation` => `ITessellation`
+  - add `BasicTessellation` class
+  - add `MeshTessellation` class
+  - update `Tessellator` signature/return type, now returning list of new faces only
+  - update all existing tessellators
+  - add `tessellateWith()`
+  - rename `tessellateQueue()` => `tessellateFaces()`
+  - update `tessellate()`, now only syntax sugar for `tessellateWith()`
+- update `Tessellator` signature ([c2ec98b](https://github.com/thi-ng/umbrella/commit/c2ec98b))
+- BREAKING CHANGE: update `Tessellator` signature, add array arg for collecting tessellated faces
+  - update `tessellateFaces()` to avoid concatenating
+  - update all tessellators
+
+#### 🚀 Features
+
+- add edgeSplitWithThreshold() tessellator ([91480c7](https://github.com/thi-ng/umbrella/commit/91480c7))
+  - add docstrings
+- add triFanSplit/triFanSplitWithThreshold() tessellators ([417123c](https://github.com/thi-ng/umbrella/commit/417123c))
+  - add doc strings
+- initial integration of earCutComplex ([307cb3d](https://github.com/thi-ng/umbrella/commit/307cb3d))
+- add triFanBoundary() tessellator ([a8fc397](https://github.com/thi-ng/umbrella/commit/a8fc397))
+
+#### ♻️ Refactoring
+
+- update/simplify earCutComplex() internals, add docs ([0b479eb](https://github.com/thi-ng/umbrella/commit/0b479eb))
+- enforce uniform naming convention of internal functions ([56992b2](https://github.com/thi-ng/umbrella/commit/56992b2))
+- minor updates earCutComplex() ([a2d5ec4](https://github.com/thi-ng/umbrella/commit/a2d5ec4))
+
 ### [2.1.87](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom-tessellate@2.1.87) (2023-11-09)
 
 #### ♻️ Refactoring

package/README.md

@@ -7,7 +7,7 @@
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
 > [!NOTE]
-> This is one of 192 standalone projects, maintained as part
+> This is one of 193 standalone projects, maintained as part
 > of the [@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo
 > and anti-framework.
 >
@@ -15,11 +15,22 @@
 > GitHub](https://github.com/sponsors/postspectacular). Thank you! ❤️
 
 - [About](#about)
+  - [Tessellators](#tessellators)
+    - [Ear cut](#ear-cut)
+    - [Edge split](#edge-split)
+    - [Inset](#inset)
+    - [Quad fan](#quad-fan)
+    - [Rim triangles](#rim-triangles)
+    - [Tri fan (with boundary point)](#tri-fan-with-boundary-point)
+    - [Tri fan (with centroid)](#tri-fan-with-centroid)
+    - [Tri fan (with edge splitting)](#tri-fan-with-edge-splitting)
+  - [The `ITessellation` interface & implementation](#the-itessellation-interface--implementation)
 - [Status](#status)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [Usage examples](#usage-examples)
 - [API](#api)
+  - [Basic usage](#basic-usage)
 - [Authors](#authors)
 - [License](#license)
 
@@ -27,16 +38,88 @@
 
 2D/3D convex polygon tessellators. This is a support package for [@thi.ng/geom](https://github.com/thi-ng/umbrella/tree/develop/packages/geom).
 
-- [earcut](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-tessellate/src/earcut.ts)
+### Tessellators
+
+The following tessellator algorithms are provided, but the package is designed
+to be fully extensible. See code examples further below.
+
+The following diagrams each show the effect of a single tessellator applied to a
+triangle, square, hexagon and octagon.
+
+#### Ear cut
+
+![diagram of tessellated polygons](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-tessellate/ear-cut.png)
+
+- [earCut](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-tessellate/src/earcut.ts)
+
+##### Complex polygons
+
+- [earCutComplex](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-tessellate/src/earcut-complex.ts)
+
+Higher order tessellator for concave polygons and/or polygons with holes...
+
+TODO add comments, credits & example
+
+#### Edge split
+
+![diagram of tessellated polygons](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-tessellate/edge-split.png)
+
 - [edgeSplit](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-tessellate/src/edge-split.ts)
+
+#### Inset
+
+![diagram of tessellated polygons](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-tessellate/inset.png)
+
 - [inset](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-tessellate/src/inset.ts)
+
+Higher order tessellator with configurable inset distance (normalized) toward
+centroid and option to keep center polygon (empty by default).
+
+#### Quad fan
+
+![diagram of tessellated polygons](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-tessellate/quad-fan.png)
+
 - [quadFan](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-tessellate/src/quad-fan.ts)
+
+#### Rim triangles
+
+![diagram of tessellated polygons](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-tessellate/rim-tris.png)
+
 - [rimTris](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-tessellate/src/rim-tris.ts)
+
+#### Tri fan (with boundary point)
+
+![diagram of tessellated polygons](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-tessellate/tri-fan-boundary.png)
+
+- [triFanBoundary](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-tessellate/src/tri-fan-boundary.ts)
+
+#### Tri fan (with centroid)
+
+![diagram of tessellated polygons](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-tessellate/tri-fan.png)
+
 - [triFan](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-tessellate/src/tri-fan.ts)
 
-**Note**: Though not officially supported, all functions *might* also
-work (in principle) with concave polygons, though correct results are
-highly dependent on the concavities present. YMMV!
+#### Tri fan (with edge splitting)
+
+![diagram of tessellated polygons](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-tessellate/tri-fan-split.png)
+
+- [triFanSplit](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-tessellate/src/tri-fan-split.ts)
+
+### The `ITessellation` interface & implementation
+
+The tessellators provided all operate in conjunction with a
+[`ITessellation`](https://docs.thi.ng/umbrella/geom-tessellate/interfaces/ITessellation.html)
+implementation which is used to collect (or index) points/vertices and generated
+faces (not necessarily triangles).
+
+Currently, there're two implementations available:
+
+- [`BasicTessellation`](https://docs.thi.ng/umbrella/geom-tessellate/classes/BasicTessellation.html)
+  is used as the default and merely collects points & faces into arrays
+- [`MeshTessellation`](https://docs.thi.ng/umbrella/geom-tessellate/classes/MeshTessellation.html)
+  uses a kD-tree to deduplicate/weld and re-use points (with configurable
+  tolerance) and is recommended for use cases when the result tessellation
+  should be converted or used for graph-like analysis or other post-processing.
 
 ## Status
 
@@ -70,14 +153,17 @@ For Node.js REPL:
 const gt = await import("@thi.ng/geom-tessellate");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1018 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 3.32 KB
 
 ## Dependencies
 
+- [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
 - [@thi.ng/checks](https://github.com/thi-ng/umbrella/tree/develop/packages/checks)
-- [@thi.ng/geom-api](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-api)
+- [@thi.ng/geom-accel](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-accel)
 - [@thi.ng/geom-isec](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-isec)
 - [@thi.ng/geom-poly-utils](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-poly-utils)
+- [@thi.ng/math](https://github.com/thi-ng/umbrella/tree/develop/packages/math)
+- [@thi.ng/morton](https://github.com/thi-ng/umbrella/tree/develop/packages/morton)
 - [@thi.ng/transducers](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers)
 - [@thi.ng/vectors](https://github.com/thi-ng/umbrella/tree/develop/packages/vectors)
 
@@ -89,6 +175,7 @@ directory are using this package:
 
 | Screenshot                                                                                                            | Description                                                                    | Live demo                                            | Source                                                                            |
 |:----------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------------------------------|:-----------------------------------------------------|:----------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/geom-hexgrid.png" width="240"/>   | Hex grid generation & tessellations                                            | [Demo](https://demo.thi.ng/umbrella/geom-hexgrid/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/geom-hexgrid)   |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom/tessel.png" width="240"/>             | Animated, recursive polygon tessellations                                      | [Demo](https://demo.thi.ng/umbrella/geom-tessel/)    | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/geom-tessel)    |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/pointfree-geom.jpg" width="240"/> | Live coding playground for 2D geometry generation using @thi.ng/pointfree-lang | [Demo](https://demo.thi.ng/umbrella/pointfree-geom/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/pointfree-geom) |
 
@@ -96,7 +183,74 @@ directory are using this package:
 
 [Generated API docs](https://docs.thi.ng/umbrella/geom-tessellate/)
 
-TODO
+**This is a low(er)-level support package for [thi.ng/geom](https://thi.ng/geom)
+and most users are encouraged to use the polymorphic [`tessellate()`
+function](https://docs.thi.ng/umbrella/geom/functions/tessellate.html)
+provided by that package.**
+
+In addition to the actual tessellator algorithms described above, this package
+also provides its own set of `tessellate()` functions to simplify
+recursive/iterative application of multiple tessellation passes:
+
+- [`tessellate()`](https://docs.thi.ng/umbrella/geom-tessellate/functions/tessellate.html)
+- [`tessellateWith()`](https://docs.thi.ng/umbrella/geom-tessellate/functions/tessellateWith.html)
+- [`tessellateFaces()`](https://docs.thi.ng/umbrella/geom-tessellate/functions/tessellateFaces.html)
+
+### Basic usage
+
+```ts tangle:export/readme.ts
+import * as gt from "@thi.ng/geom-tessellate";
+
+// points of a square polygon
+const points = [[0,0], [100,0], [100,100], [0, 100]];
+
+// tessellate square into a triangle fan
+console.log(gt.tessellate(points, gt.triFan));
+// BasicTessellation {
+//   points: [[ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ], [ 50, 50 ]],
+//   faces: [[ 4, 0, 1 ], [ 4, 1, 2 ], [ 4, 2, 3 ], [ 4, 3, 0 ]],
+//   ...
+// }
+
+// tessellate square first into a triangle fan, then each triangle into a quad fan
+console.log(gt.tessellate(points, [gt.triFan, gt.quadFan]));
+// BasicTessellation {
+//   points: [
+//     [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ],
+//     [ 50, 50 ], [ 50, 16.666 ], [ 75, 25 ], [ 25, 25 ],
+//     [ 50, 0 ], [ 83.333, 50 ], [ 75, 75 ], [ 75, 25 ],
+//     [ 100, 50 ], [ 50, 83.333 ], [ 25, 75 ], [ 75, 75 ],
+//     [ 50, 100 ], [ 16.666, 50 ], [ 25, 25 ], [ 25, 75 ], [ 0, 50 ]
+//   ],
+//   faces: [
+//     [ 5, 6, 4, 7 ], [ 5, 7, 0, 8 ], [ 5, 8, 1, 6 ], [ 9, 10, 4, 11 ],
+//     [ 9, 11, 1, 12 ], [ 9, 12, 2, 10 ], [ 13, 14, 4, 15 ], [ 13, 15, 2, 16 ],
+//     [ 13, 16, 3, 14 ], [ 17, 18, 4, 19 ], [ 17, 19, 3, 20 ], [ 17, 20, 0, 18 ]
+//   ],
+//   ...
+// }
+
+// apply quadfan twice and use a custom tessellation instance
+// (here to dedupe generated edge midpoints)
+console.log(gt.tessellateWith(new gt.MeshTessellation(2), points, gt.quadFan, 2));
+// MeshTessellation {
+//   points: [
+//     [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ],
+//     [ 50, 50 ], [ 0, 50 ], [ 50, 0 ], [ 100, 50 ],
+//     [ 50, 100 ], [ 25, 25 ], [ 50, 25 ], [ 25, 50 ],
+//     [ 0, 25 ], [ 25, 0 ], [ 75, 25 ], [ 75, 50 ],
+//     [ 75, 0 ], [ 100, 25 ], [ 75, 75 ], [ 50, 75 ],
+//     [ 100, 75 ], [ 75, 100 ], [ 25, 75 ], [25, 100], [ 0, 75 ]
+//   ],
+//   faces: [
+//     [ 9, 10, 4, 11 ], [ 9, 11, 5, 12 ], [ 9, 12, 0, 13 ], [ 9, 13, 6, 10 ],
+//     [ 14, 15, 4, 10 ], [ 14, 10, 6, 16 ], [ 14, 16, 1, 17 ], [ 14, 17, 7, 15 ],
+//     [ 18, 19, 4, 15 ], [ 18, 15, 7, 20 ], [ 18, 20, 2, 21 ], [ 18, 21, 8, 19 ],
+//     [ 22, 11, 4, 19 ], [ 22, 19, 8, 23 ], [ 22, 23, 3, 24 ], [ 22, 24, 5, 11 ]
+//   ],
+//   ...
+// }
+```
 
 ## Authors
 

package/api.d.ts

@@ -0,0 +1,81 @@
+import type { IEmpty } from "@thi.ng/api";
+import type { ReadonlyVec } from "@thi.ng/vectors";
+/**
+ * Tessellation algorithm implementation. Takes a {@link ITessellation}, an
+ * array of `faces` and an array of point/vertex IDs of the face/polygon to
+ * tessellate. Any new points created by the impl are to be added to the `tess`
+ * via {@link ITessellation.addPoint}. Any generated faces are to be appended to
+ * the given `faces` array (which also must be returned).
+ *
+ * @param tess
+ * @param faces
+ * @param face
+ */
+export type Tessellator = (tess: ITessellation, faces: number[][], face: number[]) => number[][];
+export interface ITessellation extends IEmpty<ITessellation> {
+    /**
+     * Points referenced by {@link ITessellation.faces}.
+     *
+     * @remarks
+     * If a {@link Tessellator} is creating new points as part of its
+     * processing, these are appended to this array (but **not directly!**).
+     * Tessellators MUST use {@link ITessellation.addPoint} or
+     * {@link ITessellation.addPoints}).
+     */
+    points: ReadonlyVec[];
+    /**
+     * Array of tessellated faces, each itself an array point IDs/indices,
+     * referencing {@link ITessellation.points}.
+     */
+    faces: number[][];
+    /**
+     * Adds given point to tessellation and returns its ID/index.
+     *
+     * @remarks
+     * It's implementation specific if the point will actually be added or if a
+     * matching pre-existing point ID will be reused (e.g. see
+     * {@link MeshTessellation}).
+     *
+     * @param point
+     */
+    addPoint(point: ReadonlyVec): number;
+    /**
+     * Batch version of {@link ITessellation.addPoint}, returning an array of
+     * point IDs.
+     *
+     * @param points
+     */
+    addPoints(points: ReadonlyVec[]): number[];
+    /**
+     * Add given faces to {@link ITessellation.faces}.
+     *
+     * @remarks
+     * Note: Because {@link Tessellator}s might be applied recursively, they
+     * **do not** directly add faces to a given {@link ITessellation}, but onl
+     * return generated faces as separate array. Currently, this function is
+     * only called by {@link tessellateFaces} (and implicitly by
+     * {@link tessellate}, {@link tessellateWith}).
+     *
+     * @param faces
+     */
+    addFaces(faces: number[][]): this;
+    /**
+     * Takes an array of point IDs and returns their actual points.
+     *
+     * @remarks
+     * No bounds checking performed. IDs are assumed to be valid.
+     *
+     * @param indices
+     */
+    pointsForIDs(indices: number[]): ReadonlyVec[];
+    /**
+     * Similar to {@link ITessellation.pointsForIDs}, but takes an array of
+     * faces (by default all current faces in the tessellation) and returns an
+     * array of faces where wach face is an array of points (rather than point
+     * IDs).
+     *
+     * @param faces
+     */
+    pointsForFaces(faces?: number[][]): ReadonlyVec[][];
+}
+//# sourceMappingURL=api.d.ts.map

package/earcut-complex.d.ts

@@ -0,0 +1,74 @@
+import type { ReadonlyVec } from "@thi.ng/vectors";
+import type { Tessellator } from "./api.js";
+/**
+ * Higher-order tessellator, implementing an ear slicing triangulation
+ * algorithm, optionally optimized by Morton/Z-curve hashing/sorting and able to
+ * handle complex polygons with holes, twists, degeneracies and
+ * self-intersections.
+ *
+ * @remarks
+ * This is an adapted version of https://github.com/mapbox/earcut with the
+ * following changes to the original implementation:
+ *
+ * - Input points given as array of points (not flattened, only 2D supported)
+ * - Appends results to given tessellation instance as per contract of all
+ *   tessellators in this package
+ * - Configurable Z-curve hashing threshold (default: 80)
+ * - If Z-curve hashing is used, points are pre-scaled once internally for
+ *   various simplifications and to avoid passing extraneous args around
+ * - Use unsigned 16 bits (per coord) hashing (instead of 15 bits)
+ * - Re-use existing thi.ng/umbrella fns for some processing steps
+ * - Add small tolerance for colinear check
+ * - Rename `Node` => `Vertex`
+ * - Minor other refactoring (use of destructuring, add types, renames etc.)
+ *
+ * Original implementation Copyright (c) 2016, Mapbox, ISC License. Original
+ * author: Volodymyr Agafonkin
+ *
+ * References:
+ *
+ * - https://www.cosy.sbg.ac.at/~held/projects/triang/triang.html
+ * - https://www.geometrictools.com/Documentation/TriangulationByEarClipping.pdf
+ * - https://docs.thi.ng/umbrella/morton/
+ *
+ * @param holeIDs
+ * @param hashThreshold
+ */
+export declare const earCutComplex: (holeIDs?: number[], hashThreshold?: number) => Tessellator;
+/**
+ * Takes an array of `boundary` points and another array of `holes` containing
+ * point arrays of individual holes. Concatenates all points (both boundary &
+ * holes) and returns a tuple of `[points, holeIDs]`, suitable for
+ * {@link earCutComplex}.
+ *
+ * @example
+ * ```ts tangle:../export/earcut-complex.ts
+ * import {
+ *   earCutComplex, earCutComplexPrepare, tessellate
+ * } from "@thi.ng/geom-tessellate";
+ *
+ * const boundary = [[0,0], [100,0], [100,100], [0,100]];
+ * const hole = [[20,20],[50,80],[80,20]];
+ *
+ * const [points, holeIDs] = earCutComplexPrepare(boundary, [hole]);
+ *
+ * const tess = tessellate(points, earCutComplex(holeIDs));
+ *
+ * console.log(tess);
+ * // {
+ * //   points: [
+ * //     [ 0, 0 ], [ 100, 0 ], [ 100, 100 ], [ 0, 100 ],
+ * //     [ 20, 20 ], [ 50, 80 ], [ 80, 20 ]
+ * //   ],
+ * //   indices: [
+ * //     [ 0, 4, 5 ], [ 6, 4, 0 ], [ 3, 0, 5 ], [ 6, 0, 1 ],
+ * //     [ 2, 3, 5 ], [ 5, 6, 1 ], [ 1, 2, 5 ]
+ * //   ],
+ * // }
+ * ```
+ *
+ * @param boundary
+ * @param holes
+ */
+export declare const earCutComplexPrepare: (boundary: ReadonlyVec[], holes: ReadonlyVec[][]) => [ReadonlyVec[], number[]];
+//# sourceMappingURL=earcut-complex.d.ts.map