@thi.ng/grid-iterators 3.1.1 → 4.0.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-03-27T19:05:49Z
+- **Last updated**: 2023-04-08T11:09:50Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,22 @@ 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.
 
+# [4.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/grid-iterators@4.0.0) (2023-04-08)
+
+#### 🛑 Breaking changes
+
+- add/rename types/opts ([bc3ea21](https://github.com/thi-ng/umbrella/commit/bc3ea21))
+- BREAKING CHANGE: rename various option types (add 2D/3D suffixes)
+
+#### 🚀 Features
+
+- add filter predicates ([81abf60](https://github.com/thi-ng/umbrella/commit/81abf60))
+  - add isDiagonal/Alt() filters
+
+#### 🩹 Bug fixes
+
+- fix imports ([353bc3d](https://github.com/thi-ng/umbrella/commit/353bc3d))
+
 ## [3.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/grid-iterators@3.1.0) (2023-03-25)
 
 #### 🚀 Features

package/README.md

@@ -240,7 +240,7 @@ For Node.js REPL:
 const gridIterators = await import("@thi.ng/grid-iterators");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.52 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.57 KB
 
 ## Dependencies
 
@@ -261,9 +261,10 @@ directory are using this package.
 
 A selection:
 
-| Screenshot                                                                                                            | Description                                         | Live demo                                            | Source                                                                            |
-|:----------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------|:-----------------------------------------------------|:----------------------------------------------------------------------------------|
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/grid-iterators.png" width="240"/> | Visualization of different grid iterator strategies | [Demo](https://demo.thi.ng/umbrella/grid-iterators/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/grid-iterators) |
+| Screenshot                                                                                                            | Description                                            | Live demo                                            | Source                                                                            |
+|:----------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------|:-----------------------------------------------------|:----------------------------------------------------------------------------------|
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/grid-iterators.png" width="240"/> | Visualization of different grid iterator strategies    | [Demo](https://demo.thi.ng/umbrella/grid-iterators/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/grid-iterators) |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/trace-bitmap.jpg" width="240"/>   | Multi-layer vectorization & dithering of bitmap images | [Demo](https://demo.thi.ng/umbrella/trace-bitmap/)   | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/trace-bitmap)   |
 
 ## API
 

package/api.d.ts

@@ -1,11 +1,19 @@
-import type { Fn, FnU2 } from "@thi.ng/api";
+import type { Fn, FnU2, FnU3 } from "@thi.ng/api";
+export type GridCoord2D = [number, number];
+export type GridCoord3D = [number, number, number];
 /**
  * Higher order point coordinate transformation function. First is called with
  * grid resolution (cols,rows), then returns a function which is applied to each
  * generated grid coordinate.
  */
-export type PointTransform = FnU2<number, FnU2<number, [number, number]>>;
-export interface GridIterOpts {
+export type PointTransform2D = FnU2<number, FnU2<number, GridCoord2D>>;
+/**
+ * Higher order point coordinate transformation function. First is called with
+ * grid resolution (cols,rows,slices), then returns a function which is applied
+ * to each generated grid coordinate.
+ */
+export type PointTransform3D = FnU3<number, FnU3<number, GridCoord3D>>;
+export interface GridIterOpts2D {
     /**
      * Number of grid columns
      */
@@ -20,8 +28,8 @@ export interface GridIterOpts {
      *
      * @defaultValue {@link ident}
      */
-    tx?: PointTransform;
+    tx?: PointTransform2D;
 }
-export type GridIterator2D = Fn<GridIterOpts, Iterable<[number, number]>>;
-export type GridIterator3D = Fn<GridIterOpts, Iterable<[number, number, number]>>;
+export type GridIterator2D = Fn<GridIterOpts2D, Iterable<GridCoord2D>>;
+export type GridIterator3D = Fn<GridIterOpts2D, Iterable<GridCoord3D>>;
 //# sourceMappingURL=api.d.ts.map

package/column-ends.d.ts

@@ -1,9 +1,9 @@
-import type { GridIterOpts } from "./api.js";
+import type { GridIterOpts2D } from "./api.js";
 /**
  * Filtered version of {@link columns2d}, only including end points of
  * each column.
  *
  * @param opts -
  */
-export declare function columnEnds2d(opts: GridIterOpts): Generator<[number, number], void, unknown>;
+export declare function columnEnds2d(opts: GridIterOpts2D): Generator<import("./api.js").GridCoord2D, void, unknown>;
 //# sourceMappingURL=column-ends.d.ts.map

package/columns.d.ts

@@ -1,8 +1,8 @@
-import type { GridIterOpts } from "./api.js";
+import type { GridIterOpts2D } from "./api.js";
 /**
  * Yields sequence of 2D grid coordinates in column-major order.
  *
  * @param opts -
  */
-export declare const columns2d: (opts: GridIterOpts) => IterableIterator<[number, number]>;
+export declare const columns2d: (opts: GridIterOpts2D) => IterableIterator<import("./api.js").GridCoord2D>;
 //# sourceMappingURL=columns.d.ts.map

package/diagonal-ends.d.ts

@@ -1,4 +1,4 @@
-import type { GridIterOpts } from "./api.js";
+import type { GridIterOpts2D } from "./api.js";
 /**
  * Filtered version of {@link diagonal2d}, only including end points of the
  * diagonals. Unless `all` option is enabled (default: false), the very first
@@ -9,7 +9,7 @@ import type { GridIterOpts } from "./api.js";
  *
  * @param opts -
  */
-export declare function diagonalEnds2d(opts: GridIterOpts & {
+export declare function diagonalEnds2d(opts: GridIterOpts2D & {
     all?: boolean;
-}): Generator<[number, number], void, unknown>;
+}): Generator<import("./api.js").GridCoord2D, void, unknown>;
 //# sourceMappingURL=diagonal-ends.d.ts.map

package/diagonal-slope.d.ts

@@ -1,5 +1,5 @@
-import type { GridIterOpts } from "./api.js";
-interface DiagonalSlopeOpts extends GridIterOpts {
+import type { GridIterOpts2D } from "./api.js";
+interface DiagonalSlopeOpts extends GridIterOpts2D {
     /**
      * Diagonal slope / step size
      */
@@ -30,7 +30,7 @@ interface DiagonalSlopeOpts extends GridIterOpts {
  *
  * @param opts -
  */
-export declare function diagonalSlopeY(opts: DiagonalSlopeOpts): Generator<[number, number], void, unknown>;
+export declare function diagonalSlopeY(opts: DiagonalSlopeOpts): Generator<import("./api.js").GridCoord2D, void, unknown>;
 /**
  * Similar to {@link diagonalSlopeY}. Yields sequence of 2D grid coordinates in
  * diagonal order with configurable slope, starting at [step-1,0]. Each
@@ -39,6 +39,6 @@ export declare function diagonalSlopeY(opts: DiagonalSlopeOpts): Generator<[numb
  *
  * @param opts -
  */
-export declare function diagonalSlopeX(opts: DiagonalSlopeOpts): Generator<[number, number], void, unknown>;
+export declare function diagonalSlopeX(opts: DiagonalSlopeOpts): Generator<import("./api.js").GridCoord2D, void, unknown>;
 export {};
 //# sourceMappingURL=diagonal-slope.d.ts.map

package/diagonal.d.ts

@@ -1,4 +1,4 @@
-import type { GridIterOpts } from "./api.js";
+import type { GridIterOpts2D } from "./api.js";
 /**
  * Yields sequence of 2D grid coordinates in diagonal order starting at [0,0]
  * and using given `cols` and `rows`. Each diagonal starts at y=0 and progresses
@@ -9,5 +9,5 @@ import type { GridIterOpts } from "./api.js";
  *
  * @param opts -
  */
-export declare function diagonal2d(opts: GridIterOpts): Generator<[number, number], void, unknown>;
+export declare function diagonal2d(opts: GridIterOpts2D): Generator<import("./api.js").GridCoord2D, void, unknown>;
 //# sourceMappingURL=diagonal.d.ts.map

package/filters.d.ts

@@ -0,0 +1,18 @@
+import type { GridCoord2D } from "./api.js";
+/**
+ * Returns true if x,y is on a right-to-left diagonal with spacing `n`.
+ *
+ * @param x
+ * @param y
+ * @param n
+ */
+export declare const isOnDiagonal: ([x, y]: GridCoord2D, n: number) => boolean;
+/**
+ * Returns true if x,y is on a left-to-right diagonal with spacing `n`.
+ *
+ * @param x
+ * @param y
+ * @param n
+ */
+export declare const isOnDiagonalAlt: ([x, y]: GridCoord2D, N: number) => boolean;
+//# sourceMappingURL=filters.d.ts.map

package/filters.js

@@ -0,0 +1,22 @@
+/**
+ * Returns true if x,y is on a right-to-left diagonal with spacing `n`.
+ *
+ * @param x
+ * @param y
+ * @param n
+ */
+export const isOnDiagonal = ([x, y], n) => {
+    const d = ((x + y) / n) | 0;
+    return y === d * n - x;
+};
+/**
+ * Returns true if x,y is on a left-to-right diagonal with spacing `n`.
+ *
+ * @param x
+ * @param y
+ * @param n
+ */
+export const isOnDiagonalAlt = ([x, y], N) => {
+    const d = ((x - y) / N) | 0;
+    return -y === d * N - x;
+};

package/hilbert.d.ts

@@ -1,4 +1,4 @@
-import type { GridIterOpts } from "./api.js";
+import type { GridIterOpts2D } from "./api.js";
 /**
  * Yields sequence of 2D grid coordinates along 2D Hilbert curve using given
  * `cols` and `rows` (each max. 32768 (2^15)).
@@ -8,5 +8,5 @@ import type { GridIterOpts } from "./api.js";
  *
  * @param opts -
  */
-export declare function hilbert2d(opts: GridIterOpts): Generator<[number, number], void, unknown>;
+export declare function hilbert2d(opts: GridIterOpts2D): Generator<import("./api.js").GridCoord2D, void, unknown>;
 //# sourceMappingURL=hilbert.d.ts.map

package/index.d.ts

@@ -7,6 +7,7 @@ export * from "./diagonal.js";
 export * from "./diagonal-ends.js";
 export * from "./diagonal-slope.js";
 export * from "./diamond-square.js";
+export * from "./filters.js";
 export * from "./flood-fill.js";
 export * from "./hilbert.js";
 export * from "./hvline.js";

package/index.js

@@ -7,6 +7,7 @@ export * from "./diagonal.js";
 export * from "./diagonal-ends.js";
 export * from "./diagonal-slope.js";
 export * from "./diamond-square.js";
+export * from "./filters.js";
 export * from "./flood-fill.js";
 export * from "./hilbert.js";
 export * from "./hvline.js";

package/interleave.d.ts

@@ -1,5 +1,5 @@
-import type { GridIterOpts } from "./api.js";
-interface InterleaveOpts extends GridIterOpts {
+import type { GridIterOpts2D } from "./api.js";
+interface InterleaveOpts2D extends GridIterOpts2D {
     /**
      * Row or column stride.
      *
@@ -22,7 +22,7 @@ interface InterleaveOpts extends GridIterOpts {
  *
  * @param opts -
  */
-export declare function interleaveColumns2d(opts: InterleaveOpts): Generator<[number, number], void, undefined>;
+export declare function interleaveColumns2d(opts: InterleaveOpts2D): Generator<import("./api.js").GridCoord2D, void, undefined>;
 /**
  * Similar to {@link interleaveColumns2d}, but yields 2D grid coordinates in
  * the order of interleaved rows with configurable `step` size (default:
@@ -37,6 +37,6 @@ export declare function interleaveColumns2d(opts: InterleaveOpts): Generator<[nu
  *
  * @param opts -
  */
-export declare function interleaveRows2d(opts: InterleaveOpts): Generator<[number, number], void, undefined>;
+export declare function interleaveRows2d(opts: InterleaveOpts2D): Generator<import("./api.js").GridCoord2D, void, undefined>;
 export {};
 //# sourceMappingURL=interleave.d.ts.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/grid-iterators",
-  "version": "3.1.1",
+  "version": "4.0.0",
   "description": "2D grid and shape iterators w/ multiple orderings",
   "type": "module",
   "module": "./index.js",
@@ -36,22 +36,22 @@
     "tool:assets": "tools:node-esm tools/build-assets.ts"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.7.5",
-    "@thi.ng/arrays": "^2.5.9",
-    "@thi.ng/binary": "^3.3.22",
-    "@thi.ng/bitfield": "^2.2.25",
-    "@thi.ng/errors": "^2.2.14",
-    "@thi.ng/morton": "^3.1.33",
-    "@thi.ng/random": "^3.3.28",
-    "@thi.ng/transducers": "^8.4.1"
+    "@thi.ng/api": "^8.7.6",
+    "@thi.ng/arrays": "^2.5.10",
+    "@thi.ng/binary": "^3.3.23",
+    "@thi.ng/bitfield": "^2.2.26",
+    "@thi.ng/errors": "^2.2.15",
+    "@thi.ng/morton": "^3.1.34",
+    "@thi.ng/random": "^3.3.29",
+    "@thi.ng/transducers": "^8.4.2"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.34.4",
-    "@thi.ng/testament": "^0.3.14",
+    "@thi.ng/testament": "^0.3.15",
     "rimraf": "^4.4.1",
     "tools": "^0.0.1",
     "typedoc": "^0.23.28",
-    "typescript": "^5.0.2"
+    "typescript": "^5.0.4"
   },
   "keywords": [
     "2d",
@@ -112,6 +112,9 @@
     "./diamond-square": {
       "default": "./diamond-square.js"
     },
+    "./filters": {
+      "default": "./filters.js"
+    },
     "./flood-fill": {
       "default": "./flood-fill.js"
     },
@@ -163,5 +166,5 @@
     ],
     "year": 2019
   },
-  "gitHead": "83b15b34326d480cbca0472b20390d4d3bbb792a\n"
+  "gitHead": "abcedd9e4e06a4b631f363610eec572f79b571c1\n"
 }

package/random.d.ts

@@ -1,6 +1,6 @@
 import type { IRandom } from "@thi.ng/random";
-import type { GridIterOpts } from "./api.js";
-interface Random2DOpts extends GridIterOpts {
+import type { GridIterOpts2D } from "./api.js";
+interface RandomOpts2D extends GridIterOpts2D {
     /**
      * PRNG instance to use
      *
@@ -17,6 +17,6 @@ interface Random2DOpts extends GridIterOpts {
  *
  * @param opts -
  */
-export declare function random2d(opts: Random2DOpts): Generator<[number, number], void, unknown>;
+export declare function random2d(opts: RandomOpts2D): Generator<import("./api.js").GridCoord2D, void, unknown>;
 export {};
 //# sourceMappingURL=random.d.ts.map

package/row-ends.d.ts

@@ -1,9 +1,9 @@
-import type { GridIterOpts } from "./api.js";
+import type { GridIterOpts2D } from "./api.js";
 /**
  * Filtered version of {@link rows2d}, only including end points of
  * each row.
  *
  * @param opts -
  */
-export declare function rowEnds2d(opts: GridIterOpts): Generator<[number, number], void, unknown>;
+export declare function rowEnds2d(opts: GridIterOpts2D): Generator<import("./api.js").GridCoord2D, void, unknown>;
 //# sourceMappingURL=row-ends.d.ts.map

package/rows.d.ts

@@ -1,9 +1,9 @@
-import type { GridIterOpts } from "./api.js";
+import type { GridIterOpts2D } from "./api.js";
 /**
  * Yields sequence of 2D grid coordinates in row-major order. Same as
  * [`range2d()`](https://docs.thi.ng/umbrella/transducers/functions/range2d.html).
  *
  * @param opts -
  */
-export declare const rows2d: (opts: GridIterOpts) => IterableIterator<[number, number]>;
+export declare const rows2d: (opts: GridIterOpts2D) => IterableIterator<import("./api.js").GridCoord2D>;
 //# sourceMappingURL=rows.d.ts.map

package/spiral.d.ts

@@ -1,4 +1,4 @@
-import type { GridIterOpts } from "./api.js";
+import type { GridIterOpts2D } from "./api.js";
 /**
  * Yields sequence of 2D grid coordinates in outward spiral order starting from
  * the center, given `cols` and `rows`.
@@ -8,5 +8,5 @@ import type { GridIterOpts } from "./api.js";
  *
  * @param opts -
  */
-export declare function spiral2d(opts: GridIterOpts): Generator<[number, number], void, unknown>;
+export declare function spiral2d(opts: GridIterOpts2D): Generator<import("./api.js").GridCoord2D, void, unknown>;
 //# sourceMappingURL=spiral.d.ts.map

package/transforms.d.ts

@@ -1,15 +1,15 @@
-import type { PointTransform } from "./api.js";
+import type { PointTransform2D } from "./api.js";
 /**
  * No-op / identity {@link PointTransform}.
  */
-export declare const ident: PointTransform;
-export declare const flipX: PointTransform;
-export declare const flipY: PointTransform;
-export declare const flipXY: PointTransform;
+export declare const ident: PointTransform2D;
+export declare const flipX: PointTransform2D;
+export declare const flipY: PointTransform2D;
+export declare const flipXY: PointTransform2D;
 /**
  * {@link PointTransform} to swaps X & Y coords.
  */
-export declare const swapXY: PointTransform;
+export declare const swapXY: PointTransform2D;
 /**
  * Higher order {@link PointTransform} to compose given transforms in
  * left-to-right order.
@@ -17,5 +17,5 @@ export declare const swapXY: PointTransform;
  * @param a
  * @param b
  */
-export declare const compTransforms: (a: PointTransform, b: PointTransform) => PointTransform;
+export declare const compTransforms: (a: PointTransform2D, b: PointTransform2D) => PointTransform2D;
 //# sourceMappingURL=transforms.d.ts.map

package/utils.d.ts

@@ -1,7 +1,7 @@
-import type { GridIterOpts } from "./api.js";
-export declare const __opts: (opts: GridIterOpts) => {
+import type { GridIterOpts2D } from "./api.js";
+export declare const __opts: (opts: GridIterOpts2D) => {
     cols: number;
     rows: number;
-    tx: import("@thi.ng/api").FnU2<number, [number, number]>;
+    tx: import("@thi.ng/api").FnU2<number, import("./api.js").GridCoord2D>;
 };
 //# sourceMappingURL=utils.d.ts.map

package/zcurve.d.ts

@@ -1,4 +1,4 @@
-import type { GridIterOpts } from "./api.js";
+import type { GridIterOpts2D } from "./api.js";
 /**
  * Yields 2D grid coordinates in Z-curve (Morton) order. A perfect
  * Z-curve is only generated if `cols` AND `rows` are equal and a power
@@ -7,5 +7,5 @@ import type { GridIterOpts } from "./api.js";
  *
  * @param opts -
  */
-export declare function zcurve2d(opts: GridIterOpts): Generator<[number, number], void, unknown>;
+export declare function zcurve2d(opts: GridIterOpts2D): Generator<import("./api.js").GridCoord2D, void, unknown>;
 //# sourceMappingURL=zcurve.d.ts.map

package/zigzag-columns.d.ts

@@ -1,4 +1,4 @@
-import type { GridIterOpts } from "./api.js";
+import type { GridIterOpts2D } from "./api.js";
 /**
  * Yields sequence of 2D grid coordinates in zigzag column order starting from
  * [0,0], given `cols` and `rows`.
@@ -8,5 +8,5 @@ import type { GridIterOpts } from "./api.js";
  *
  * @param opts -
  */
-export declare function zigzagColumns2d(opts: GridIterOpts): Generator<[number, number], void, unknown>;
+export declare function zigzagColumns2d(opts: GridIterOpts2D): Generator<import("./api.js").GridCoord2D, void, unknown>;
 //# sourceMappingURL=zigzag-columns.d.ts.map

package/zigzag-diagonal.d.ts

@@ -1,9 +1,9 @@
-import type { GridIterOpts } from "./api.js";
+import type { GridIterOpts2D } from "./api.js";
 /**
  * Similar to {@link diagonal2d}, but yields 2D grid coordinates in zigzag
  * diagonal order starting at [0,0] and using given `cols` and `rows`.
  *
  * @param opts -
  */
-export declare function zigzagDiagonal2d(opts: GridIterOpts): Generator<[number, number], void, unknown>;
+export declare function zigzagDiagonal2d(opts: GridIterOpts2D): Generator<import("./api.js").GridCoord2D, void, unknown>;
 //# sourceMappingURL=zigzag-diagonal.d.ts.map

package/zigzag-rows.d.ts

@@ -1,4 +1,4 @@
-import type { GridIterOpts } from "./api.js";
+import type { GridIterOpts2D } from "./api.js";
 /**
  * Yields sequence of 2D grid coordinates in zigzag row order starting from
  * [0,0], given `cols` and `rows`.
@@ -8,5 +8,5 @@ import type { GridIterOpts } from "./api.js";
  *
  * @param opts -
  */
-export declare function zigzagRows2d(opts: GridIterOpts): Generator<[number, number], void, unknown>;
+export declare function zigzagRows2d(opts: GridIterOpts2D): Generator<import("./api.js").GridCoord2D, void, unknown>;
 //# sourceMappingURL=zigzag-rows.d.ts.map