@thi.ng/geom-trace-bitmap 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-03-27T19:05:48Z
+- **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,17 @@ 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.
 
+## [0.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom-trace-bitmap@0.3.0) (2023-04-08)
+
+#### 🚀 Features
+
+- add TraceOpts.max ([3b39d61](https://github.com/thi-ng/umbrella/commit/3b39d61))
+- update TraceOpts.select() ([01b9e49](https://github.com/thi-ng/umbrella/commit/01b9e49))
+  - add point coords as 2nd select() arg
+- update extractSegmentX/Y() ([274f71d](https://github.com/thi-ng/umbrella/commit/274f71d))
+  - update result to include unmatched points
+  - update tests
+
 ## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom-trace-bitmap@0.2.0) (2023-03-25)
 
 #### 🚀 Features

package/README.md

@@ -14,6 +14,7 @@ This project is part of the
 - [Related packages](#related-packages)
 - [Installation](#installation)
 - [Dependencies](#dependencies)
+- [Usage examples](#usage-examples)
 - [API](#api)
   - [Basic usage](#basic-usage)
 - [Authors](#authors)
@@ -65,7 +66,7 @@ For Node.js REPL:
 const geomTraceBitmap = await import("@thi.ng/geom-trace-bitmap");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 940 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 988 bytes
 
 ## Dependencies
 
@@ -76,6 +77,18 @@ Package sizes (brotli'd, pre-treeshake): ESM: 940 bytes
 - [@thi.ng/pixel](https://github.com/thi-ng/umbrella/tree/develop/packages/pixel)
 - [@thi.ng/vectors](https://github.com/thi-ng/umbrella/tree/develop/packages/vectors)
 
+## Usage examples
+
+Several demos in this repo's
+[/examples](https://github.com/thi-ng/umbrella/tree/develop/examples)
+directory are using this package.
+
+A selection:
+
+| Screenshot                                                                                                          | Description                                            | Live demo                                          | Source                                                                          |
+|:--------------------------------------------------------------------------------------------------------------------|:-------------------------------------------------------|:---------------------------------------------------|:--------------------------------------------------------------------------------|
+| <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
 
 [Generated API docs](https://docs.thi.ng/umbrella/geom-trace-bitmap/)

package/api.d.ts

@@ -1,5 +1,5 @@
-import type { FnU2, Predicate } from "@thi.ng/api";
-import type { GridIterator2D, PointTransform } from "@thi.ng/grid-iterators";
+import type { Fn2, FnU2, Predicate } from "@thi.ng/api";
+import type { GridCoord2D, GridIterator2D, PointTransform2D } from "@thi.ng/grid-iterators";
 import type { ReadonlyMat } from "@thi.ng/matrices";
 import type { IntBuffer } from "@thi.ng/pixel";
 export interface TraceOpts {
@@ -12,16 +12,26 @@ export interface TraceOpts {
      */
     img: IntBuffer;
     /**
-     * Predicate function to determine if a pixel value is considered part of a
-     * line.
+     * Predicate function to determine if a pixel position (or pixel value) is
+     * considered selectable (part of a line or point cloud). The function is
+     * being called with the pixel value and its coordinates.
+     *
+     * @param val
+     * @param p
      */
-    select: Predicate<number>;
+    select: Fn2<number, GridCoord2D, boolean>;
     /**
-     * Minimum length of line segments (in pixels).
+     * Minimum length of line segments (in consecutive pixels).
      *
      * @defaultValue 2
      */
     min?: number;
+    /**
+     * Maximum length of line segments (in consecutive pixels).
+     *
+     * @defaultValue Infinity
+     */
+    max?: number;
     /**
      * Clear value to replace extracted pixels with.
      *
@@ -80,7 +90,7 @@ export interface TraceDirImpl {
      * Optional point transform passed to {@link TraceDirImpl.order} (e.g. to
      * flip iteration order and therefore line direction)
      */
-    tx?: PointTransform;
+    tx?: PointTransform2D;
 }
 export type BorderFn = FnU2<number, Predicate<[number, number]>>;
 //# sourceMappingURL=api.d.ts.map

package/extract.d.ts

@@ -1,7 +1,9 @@
-import type { ReadonlyVec, VecPair } from "@thi.ng/vectors";
+import type { ReadonlyVec, Vec, VecPair } from "@thi.ng/vectors";
 /**
  * Extracts horizontal line segments (along X-axis) from given point cloud
- * (assuming all points are aligned to a grid, e.g. pixel coords).
+ * (assuming all points are aligned to a grid, e.g. pixel coords). Returns
+ * object of `{segments, points}`, where `segments` contains all extracted
+ * segments and `points` all remaining/unmatched points.
  *
  * @remarks
  * The given point array will be sorted (in-place!). Line segments will be as
@@ -14,7 +16,10 @@ import type { ReadonlyVec, VecPair } from "@thi.ng/vectors";
  * @param pts
  * @param maxDist
  */
-export declare const extractSegmentsX: (pts: ReadonlyVec[], maxD?: number) => VecPair[];
+export declare const extractSegmentsX: (pts: ReadonlyVec[], maxD?: number) => {
+    segments: VecPair[];
+    points: Vec[];
+};
 /**
  * Similar to {@link extractSegmentsX}, but for extracting vertical line
  * segments (along Y-axis).
@@ -22,5 +27,8 @@ export declare const extractSegmentsX: (pts: ReadonlyVec[], maxD?: number) => Ve
  * @param pts
  * @param maxDist
  */
-export declare const extractSegmentsY: (pts: ReadonlyVec[], maxDist?: number) => VecPair[];
+export declare const extractSegmentsY: (pts: ReadonlyVec[], maxDist?: number) => {
+    segments: VecPair[];
+    points: Vec[];
+};
 //# sourceMappingURL=extract.d.ts.map

package/extract.js

@@ -1,7 +1,9 @@
 import { comparator2 } from "@thi.ng/vectors/compare";
 /**
  * Extracts horizontal line segments (along X-axis) from given point cloud
- * (assuming all points are aligned to a grid, e.g. pixel coords).
+ * (assuming all points are aligned to a grid, e.g. pixel coords). Returns
+ * object of `{segments, points}`, where `segments` contains all extracted
+ * segments and `points` all remaining/unmatched points.
  *
  * @remarks
  * The given point array will be sorted (in-place!). Line segments will be as
@@ -33,9 +35,12 @@ export const extractSegmentsY = (pts, maxDist = 5) => __extract(pts, maxDist, 0)
  * @internal
  */
 const __extract = (pts, maxD, order) => {
+    if (pts.length < 2)
+        return { segments: [], points: pts };
     const $ = order ? (p) => [p[1], p[0]] : (p) => p;
     pts = pts.sort(comparator2(order, order ^ 1));
     const segments = [];
+    const points = [];
     let [outer, inner] = $(pts[0]);
     let last = 0;
     for (let i = 1, n = pts.length - 1; i <= n; i++) {
@@ -45,6 +50,9 @@ const __extract = (pts, maxD, order) => {
                 if (i - last > 1) {
                     segments.push([pts[last], pts[i - 1]]);
                 }
+                else {
+                    points.push(pts[last]);
+                }
                 last = i;
             }
             inner = p[1];
@@ -53,9 +61,12 @@ const __extract = (pts, maxD, order) => {
             if (i - last > 1) {
                 segments.push([pts[last], pts[i - 1]]);
             }
+            else {
+                points.push(pts[last]);
+            }
             last = i;
             [outer, inner] = p;
         }
     }
-    return segments;
+    return { segments, points };
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/geom-trace-bitmap",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "Bitmap image to hairline vector and point cloud conversions",
   "type": "module",
   "module": "./index.js",
@@ -34,20 +34,20 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.7.5",
-    "@thi.ng/errors": "^2.2.14",
-    "@thi.ng/grid-iterators": "^3.1.1",
-    "@thi.ng/matrices": "^2.1.51",
-    "@thi.ng/pixel": "^4.1.11",
-    "@thi.ng/vectors": "^7.6.10"
+    "@thi.ng/api": "^8.8.0",
+    "@thi.ng/errors": "^2.2.15",
+    "@thi.ng/grid-iterators": "^4.0.1",
+    "@thi.ng/matrices": "^2.1.53",
+    "@thi.ng/pixel": "^4.2.1",
+    "@thi.ng/vectors": "^7.6.12"
   },
   "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": [
     "bitmap",
@@ -100,5 +100,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "83b15b34326d480cbca0472b20390d4d3bbb792a\n"
+  "gitHead": "3a56bc490f1e68754762a503d06327b5b34ff7eb\n"
 }

package/trace.d.ts

@@ -1,5 +1,5 @@
 import type { Fn, Predicate } from "@thi.ng/api";
-import type { GridIterOpts, PointTransform } from "@thi.ng/grid-iterators";
+import type { GridIterOpts2D, PointTransform2D } from "@thi.ng/grid-iterators";
 import type { Vec, VecPair } from "@thi.ng/vectors";
 import type { TraceBitmapOpts, TraceOpts } from "./api.js";
 /**
@@ -30,7 +30,7 @@ export declare const traceBitmap: (opts: TraceBitmapOpts) => {
  * @param tx
  * @param acc
  */
-export declare const traceLines: (opts: TraceOpts, order: Fn<GridIterOpts, Iterable<[number, number]>>, border: Predicate<[number, number]>, tx: PointTransform, acc?: VecPair[]) => VecPair[];
+export declare const traceLines: (opts: TraceOpts, order: Fn<GridIterOpts2D, Iterable<[number, number]>>, border: Predicate<[number, number]>, tx: PointTransform2D, acc?: VecPair[]) => VecPair[];
 /**
  * Extracts single pixels and stores their coordinates in `acc`.
  *

package/trace.js

@@ -69,10 +69,11 @@ export const traceBitmap = (opts) => {
  * @param acc
  */
 export const traceLines = (opts, order, border, tx, acc = []) => {
-    let { img, select, clear, last, min } = {
+    let { img, select, clear, last, min, max } = {
         clear: 0,
         last: true,
         min: 2,
+        max: Infinity,
         ...opts,
     };
     min--;
@@ -84,11 +85,11 @@ export const traceLines = (opts, order, border, tx, acc = []) => {
             img.setAtUnsafe(q[0], q[1], clear);
     };
     for (let p of order({ cols: img.width, rows: img.height, tx })) {
-        const c = select(img.getAtUnsafe(p[0], p[1]));
+        const c = select(img.getAtUnsafe(p[0], p[1]), p);
         const isBorder = border(p);
         const n = curr.length;
         if (c) {
-            if (isBorder) {
+            if (isBorder || n >= max) {
                 if (n > 0) {
                     if (prevBorder) {
                         if (n > min)
@@ -133,7 +134,7 @@ export const tracePoints = ({ img, select, clear }, acc = []) => {
     if (clear === undefined)
         clear = 0;
     for (let i = 0, n = img.data.length, w = img.width; i < n; i++) {
-        if (select(img.data[i])) {
+        if (select(img.data[i], [i % w, (i / w) | 0])) {
             acc.push([i % w, (i / w) | 0]);
             img.data[i] = clear;
         }