@thi.ng/geom-axidraw 0.1.3 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-12-22T21:47:07Z
+- **Last updated**: 2023-01-10T15:20:18Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,32 @@ 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-axidraw@0.3.0) (2023-01-10)
+
+#### 🚀 Features
+
+- add asGeometry() command visualization ([78199ba](https://github.com/thi-ng/umbrella/commit/78199ba))
+
+#### 🩹 Bug fixes
+
+- update group attrib handling ([7f5d9a3](https://github.com/thi-ng/umbrella/commit/7f5d9a3))
+  - ensure `__samples` attrib is being properly merged
+
+## [0.2.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom-axidraw@0.2.0) (2022-12-29)
+
+#### 🚀 Features
+
+- add shapesByNearestNeighbor() ([0059766](https://github.com/thi-ng/umbrella/commit/0059766))
+- add skip attrib ([4675151](https://github.com/thi-ng/umbrella/commit/4675151))
+  - update group & points conversion fns
+  - update deps
+
+#### ♻️ Refactoring
+
+- update pointsByNearestNeighbor() ([8a171e0](https://github.com/thi-ng/umbrella/commit/8a171e0))
+  - lift `accel` spatial index impl as arg
+  - update doc strings
+
 ## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom-axidraw@0.1.0) (2022-12-10)
 
 #### 🚀 Features

package/README.md

@@ -14,6 +14,7 @@ This project is part of the
   - [AxiDraw specific shape attributes](#axidraw-specific-shape-attributes)
     - [Shape interpolation/resampling](#shape-interpolationresampling)
   - [Draw order](#draw-order)
+  - [Command visualization](#command-visualization)
   - [Basic usage & examples](#basic-usage--examples)
     - [Interpolated polygons](#interpolated-polygons)
     - [Clipping](#clipping)
@@ -29,7 +30,8 @@ This project is part of the
 
 Conversion and preparation of thi.ng/geom shapes & shape groups to AxiDraw pen plotter draw commands. This is a support package for [@thi.ng/geom](https://github.com/thi-ng/umbrella/tree/develop/packages/geom).
 
-This package only deals with the conversion aspects. The
+This package only deals with the (bi-directional) conversion aspects between
+geometry and plotter commands. The
 [@thi.ng/axidraw](https://github.com/thi-ng/umbrella/blob/develop/packages/axidraw)
 is responsible for the actual plotter output...
 
@@ -73,6 +75,9 @@ any package-specific attribs must be stored under the `__axi` key:
   reset to globally configured default at the end of the shape.
 - `speed`: Speed factor (multiple of globally configured draw speed). Depending
   on pen used, slower speeds might result in thicker strokes.
+- `skip`: Only used for groups or point clouds. If given, only every (n+1)th
+  child shape or point is being processed and the others ignored. Useful for low
+  detail test runs.
 - `sort`: Ordering function (in lieu of full path planning/optimization, which
   is planned for a later stage). For shapes other than `points()`, order of
   appearance is used by default.
@@ -105,9 +110,19 @@ Currently, the following ordering functions are available, but custom
 implementations can be provided too...
 
 - [`pointsByNearestNeighbor()`](https://docs.thi.ng/umbrella/geom-axidraw/functions/pointsByNearestNeighbor.html)
+- [`shapesByNearestNeighbor()`](https://docs.thi.ng/umbrella/geom-axidraw/functions/shapesByNearestNeighbor.html)
 - [`pointsByProximity()`](https://docs.thi.ng/umbrella/geom-axidraw/functions/pointsByProximity.html)
 - [`shapesByProximity()`](https://docs.thi.ng/umbrella/geom-axidraw/functions/shapesByProximity.html)
 
+### Command visualization
+
+For debug, optimization & visualization purposes it's useful to convert a
+sequence of plotter commands back into 2D geometry. This can be done via the
+supplied
+[`asGeometry()`](https://docs.thi.ng/umbrella/geom-axidraw/functions/asGeometry.html)
+function, which also takes several options to customize the resulting output.
+One of the [examples](#clipping) below is demonstrating basic usage.
+
 ### Basic usage & examples
 
 The main function of this package is the polymorphic function
@@ -160,10 +175,18 @@ import { map, range } from "@thi.ng/transducers";
 (Result: https://mastodon.thi.ng/@toxi/109483553358349473)
 
 ```ts tangle:export/readme-clipping.ts
-import { AxiDraw, complete } from "@thi.ng/axidraw";
-import { circle, group, starWithCentroid, vertices } from "@thi.ng/geom";
-import { asAxiDraw } from "@thi.ng/geom-axidraw";
+import { AxiDraw } from "@thi.ng/axidraw";
+import {
+    asSvg,
+    circle,
+    group,
+    starWithCentroid,
+    svgDoc,
+    vertices,
+} from "@thi.ng/geom";
+import { asAxiDraw, asGeometry } from "@thi.ng/geom-axidraw";
 import { map, range } from "@thi.ng/transducers";
+import { writeFileSync } from "fs";
 
 (async () => {
     const origin = [100, 100];
@@ -172,13 +195,26 @@ import { map, range } from "@thi.ng/transducers";
     // group of concentric circles using boundary as clip polygon
     const geo = group({}, [
         boundary,
-        group({ __samples: 40, __axi: { clip: vertices(boundary) } }, [
+        group({ __samples: 60, __axi: { clip: vertices(boundary) } }, [
             ...map((r) => circle(origin, r), range(2, radius, 2)),
         ]),
     ]);
+
+    // convert into AxiDraw command sequence
+    const commands = [...asAxiDraw(geo)];
+
+    // now visualize command sequence (convert back to geometry, incl. pen movements)
+    const { paths, rapids, ups, downs } = asGeometry(commands);
+    // write visualization as SVG
+    writeFileSync(
+        "export/clipping-commands.svg",
+        asSvg(svgDoc({ width: 600, weight: 0.2 }, paths, rapids, ups, downs))
+    );
+
+    // actually connect & send to plotter
     const axi = new AxiDraw();
     await axi.connect();
-    await axi.draw(asAxiDraw(geo));
+    await axi.draw(commands);
 })();
 ```
 
@@ -212,7 +248,7 @@ For Node.js REPL:
 const geomAxidraw = await import("@thi.ng/geom-axidraw");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 856 bytes
+Package sizes (brotli'd, pre-treeshake): ESM: 1.31 KB
 
 ## Dependencies
 
@@ -226,6 +262,7 @@ Package sizes (brotli'd, pre-treeshake): ESM: 856 bytes
 - [@thi.ng/geom-api](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-api)
 - [@thi.ng/geom-clip-line](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-clip-line)
 - [@thi.ng/geom-isec](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-isec)
+- [@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)
 
 ## API
@@ -251,4 +288,4 @@ If this project contributes to an academic publication, please cite it as:
 
 ## License
 
-© 2022 Karsten Schmidt // Apache License 2.0
+© 2022 - 2023 Karsten Schmidt // Apache License 2.0

package/api.d.ts

@@ -52,6 +52,12 @@ export interface AxiDrawAttribs {
      * - {@link shapesByProximity} (for `group()`)
      */
     sort: PointOrdering | ShapeOrdering;
+    /**
+     * Only used for groups or point clouds. If given, only every (n+1)th child
+     * shape or point is being processed and the others ignored. Useful for low
+     * detail test runs.
+     */
+    skip: number;
 }
 export interface AsAxiDrawOpts {
     /**

package/as-axidraw.js

@@ -6,6 +6,8 @@ import { pointInPolygon2 } from "@thi.ng/geom-isec/point";
 import { applyTransforms } from "@thi.ng/geom/apply-transforms";
 import { asPolyline } from "@thi.ng/geom/as-polyline";
 import { __dispatch } from "@thi.ng/geom/internal/dispatch";
+import { __sampleAttribs } from "@thi.ng/geom/internal/vertices";
+import { takeNth } from "@thi.ng/transducers/take-nth";
 import { pointsByNearestNeighbor } from "./sort.js";
 /**
  * Lazily converts given shape (or group) into an iterable of thi.ng/axidraw
@@ -67,13 +69,16 @@ export const asAxiDraw = defmulti(__dispatch, {
     group: ($, opts) => __group($, opts),
 });
 function* __group($, opts) {
-    const { sort } = __axiAttribs($.attribs);
-    const children = sort ? sort($.children) : $.children;
-    for (let child of children) {
+    const { skip, sort } = __axiAttribs($.attribs);
+    const sopts = __sampleAttribs(opts?.samples, $.attribs);
+    const children = skip ? [...takeNth(skip + 1, $.children)] : $.children;
+    const childrenIter = sort ? sort(children) : children;
+    for (let child of childrenIter) {
         const shape = applyTransforms(child);
         shape.attribs = {
-            ...shape.attribs,
             ...$.attribs,
+            ...shape.attribs,
+            __samples: __sampleAttribs(sopts, shape.attribs),
         };
         yield* asAxiDraw(shape, opts);
     }
@@ -81,7 +86,7 @@ function* __group($, opts) {
 function* __points(pts, attribs, opts) {
     if (!pts.length)
         return;
-    const { clip, delayDown, delayUp, down, speed, sort } = {
+    const { clip, delayDown, delayUp, down, skip, speed, sort } = {
         sort: pointsByNearestNeighbor(),
         ...__axiAttribs(attribs),
     };
@@ -91,6 +96,9 @@ function* __points(pts, attribs, opts) {
         if (!pts.length)
             return;
     }
+    if (skip) {
+        pts = [...takeNth(skip + 1, pts)];
+    }
     yield UP;
     if (down != undefined)
         yield ["pen", down];

package/as-geometry.d.ts

@@ -0,0 +1,47 @@
+import type { DrawCommand } from "@thi.ng/axidraw";
+import type { Attribs } from "@thi.ng/geom-api";
+export interface AsGeometryOpts {
+    /**
+     * If true (default), records all movements whilst pen is up (otherwise only
+     * whilst pen is down)
+     */
+    rapids: boolean;
+    /**
+     * If true (default), records all pen up/down positions.
+     */
+    pen: boolean;
+    /**
+     * Attributes for result groups/pointclouds.
+     */
+    attribs: Partial<{
+        paths: Attribs;
+        rapids: Attribs;
+        ups: Attribs;
+        downs: Attribs;
+    }>;
+}
+/**
+ * Converts a sequence of
+ * [DrawCommands](https://docs.thi.ng/umbrella/axidraw/types/DrawCommand.html)
+ * into thi.ng/geom geometry. Returns an object of shapes. The conversion can be
+ * controlled via given options.
+ *
+ * @remarks
+ * The returned object contains groups & shapes which are being color coded by
+ * default:
+ *
+ * - `paths`: a group of polylines for which pen is down (#000)
+ * - `rapids`: a group of polylines for which pen is up (#0ff)
+ * - `ups`: a point cloud of positions where pen is being lifted (#0f0)
+ * - `downs`: a point cloud of positions where pen is being placed down (#f00)
+ *
+ * @param src
+ * @param opts
+ */
+export declare const asGeometry: (src: Iterable<DrawCommand>, opts?: Partial<AsGeometryOpts>) => {
+    paths: import("@thi.ng/geom").Group;
+    rapids: import("@thi.ng/geom").Group;
+    ups: import("@thi.ng/geom").Points;
+    downs: import("@thi.ng/geom").Points;
+};
+//# sourceMappingURL=as-geometry.d.ts.map

package/as-geometry.js

@@ -0,0 +1,106 @@
+import { group } from "@thi.ng/geom/group";
+import { points } from "@thi.ng/geom/points";
+import { polyline } from "@thi.ng/geom/polyline";
+import { copy } from "@thi.ng/vectors";
+const DEFAULT_ATTRIBS = {
+    paths: { stroke: "#000" },
+    rapids: { stroke: "#0ff" },
+    ups: { fill: "#0f0", stroke: "none" },
+    downs: { fill: "#f00", stroke: "none" },
+};
+/**
+ * Converts a sequence of
+ * [DrawCommands](https://docs.thi.ng/umbrella/axidraw/types/DrawCommand.html)
+ * into thi.ng/geom geometry. Returns an object of shapes. The conversion can be
+ * controlled via given options.
+ *
+ * @remarks
+ * The returned object contains groups & shapes which are being color coded by
+ * default:
+ *
+ * - `paths`: a group of polylines for which pen is down (#000)
+ * - `rapids`: a group of polylines for which pen is up (#0ff)
+ * - `ups`: a point cloud of positions where pen is being lifted (#0f0)
+ * - `downs`: a point cloud of positions where pen is being placed down (#f00)
+ *
+ * @param src
+ * @param opts
+ */
+export const asGeometry = (src, opts = {}) => {
+    opts = {
+        rapids: true,
+        pen: true,
+        ...opts,
+        attribs: { ...DEFAULT_ATTRIBS, ...opts.attribs },
+    };
+    const rapids = [];
+    const paths = [];
+    const downs = [];
+    const ups = [];
+    let penDown = false;
+    let pts = null;
+    let currPos = [0, 0];
+    for (let cmd of src) {
+        switch (cmd[0]) {
+            case "m":
+                {
+                    const newPos = copy(cmd[1]);
+                    if (penDown || opts.rapids) {
+                        if (!pts)
+                            pts = [copy(currPos), newPos];
+                        else
+                            pts.push(newPos);
+                    }
+                    currPos = newPos;
+                }
+                break;
+            case "u":
+                if (pts) {
+                    if (penDown)
+                        paths.push(pts);
+                    else if (opts.rapids)
+                        rapids.push(pts);
+                    pts = null;
+                }
+                if (opts.pen)
+                    ups.push(copy(currPos));
+                penDown = false;
+                break;
+            case "d":
+                if (pts) {
+                    if (!penDown) {
+                        if (opts.rapids)
+                            rapids.push(pts);
+                    }
+                    else
+                        paths.push(pts);
+                    pts = null;
+                }
+                if (opts.pen)
+                    downs.push(copy(currPos));
+                penDown = true;
+                break;
+            case "home":
+                currPos = [0, 0];
+                if (!pts)
+                    pts = [currPos];
+                else
+                    pts.push(currPos);
+                break;
+            default:
+                console.log("skipping command", cmd);
+        }
+    }
+    if (pts) {
+        if (penDown)
+            paths.push(pts);
+        else
+            rapids.push(pts);
+    }
+    return {
+        paths: group(opts.attribs.paths, paths.map((pts) => polyline(pts))),
+        rapids: group(opts.attribs.rapids, rapids.map((pts) => polyline(pts))),
+        ups: points(ups, opts.attribs.ups),
+        downs: points(downs, opts.attribs.downs),
+    };
+};

package/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./api.js";
 export * from "./as-axidraw.js";
+export * from "./as-geometry.js";
 export * from "./sort.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -1,3 +1,4 @@
 export * from "./api.js";
 export * from "./as-axidraw.js";
+export * from "./as-geometry.js";
 export * from "./sort.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/geom-axidraw",
-  "version": "0.1.3",
+  "version": "0.3.0",
   "description": "Conversion and preparation of thi.ng/geom shapes & shape groups to AxiDraw pen plotter draw commands",
   "type": "module",
   "module": "./index.js",
@@ -34,21 +34,22 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.6.2",
-    "@thi.ng/arrays": "^2.4.7",
-    "@thi.ng/axidraw": "^0.2.3",
-    "@thi.ng/compare": "^2.1.21",
-    "@thi.ng/defmulti": "^2.1.26",
-    "@thi.ng/geom": "^4.1.0",
-    "@thi.ng/geom-accel": "^3.2.31",
-    "@thi.ng/geom-api": "^3.3.23",
-    "@thi.ng/geom-clip-line": "^2.2.3",
-    "@thi.ng/geom-isec": "^2.1.40",
-    "@thi.ng/vectors": "^7.5.29"
+    "@thi.ng/api": "^8.6.3",
+    "@thi.ng/arrays": "^2.5.1",
+    "@thi.ng/axidraw": "^0.4.0",
+    "@thi.ng/compare": "^2.1.22",
+    "@thi.ng/defmulti": "^2.1.27",
+    "@thi.ng/geom": "^4.2.0",
+    "@thi.ng/geom-accel": "^3.2.33",
+    "@thi.ng/geom-api": "^3.4.0",
+    "@thi.ng/geom-clip-line": "^2.3.0",
+    "@thi.ng/geom-isec": "^2.1.42",
+    "@thi.ng/transducers": "^8.3.30",
+    "@thi.ng/vectors": "^7.5.31"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.33.7",
-    "@thi.ng/testament": "^0.3.8",
+    "@thi.ng/testament": "^0.3.9",
     "rimraf": "^3.0.2",
     "tools": "^0.0.1",
     "typedoc": "^0.23.22",
@@ -105,6 +106,9 @@
     "./as-axidraw": {
       "default": "./as-axidraw.js"
     },
+    "./as-geometry": {
+      "default": "./as-geometry.js"
+    },
     "./sort": {
       "default": "./sort.js"
     }
@@ -117,5 +121,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "bc6f7f5e2765bb96fe64db804eaf4b2443b47fc6\n"
+  "gitHead": "3f0b3e2a7c82aefc7e46fb4338369836b5e1b8cf\n"
 }

package/sort.d.ts

@@ -1,19 +1,22 @@
+import type { IRegionQuery, IShape, ISpatialMap, ISpatialSet } from "@thi.ng/geom-api";
 import { ReadonlyVec } from "@thi.ng/vectors/api";
 import type { PointOrdering, ShapeOrdering } from "./api.js";
 /**
- * Higher order point ordering fn. Lazily sorts points by nearest neighbor
+ * Higher order point ordering fn. Adds points to given spatial
+ * index/acceleration structure and then lazily sorts them by nearest neighbor
  * distance, starting selection of first point based on given `ref` point
  * (default: [0, 0]).
  *
  * @remarks
- * Internally uses a
+ * By default is using a
  * [`KdTreeSet`](https://docs.thi.ng/umbrella/geom-accel/classes/KdTreeSet.html)
  * to index all points and then successively perform efficient nearest neighbor
  * searches (always w.r.t the most recent result point).
  *
+ * @param accel
  * @param ref
  */
-export declare const pointsByNearestNeighbor: (ref?: ReadonlyVec) => PointOrdering;
+export declare const pointsByNearestNeighbor: (accel?: ISpatialSet<ReadonlyVec> & IRegionQuery<ReadonlyVec, ReadonlyVec, number>, ref?: ReadonlyVec) => PointOrdering;
 /**
  * Higher order point ordering fn. Sorts points by proximity to given `ref` point
  * (default: [0, 0]).
@@ -28,4 +31,19 @@ export declare const pointsByProximity: (ref?: ReadonlyVec) => PointOrdering;
  * @param ref
  */
 export declare const shapesByProximity: (ref?: ReadonlyVec) => ShapeOrdering;
+/**
+ * Similar to {@link pointsByNearestNeighbor}, however for shapes and requiring
+ * an
+ * [`ISpatialMap`](https://docs.thi.ng/umbrella/geom-api/interfaces/ISpatialMap.html)
+ * implementation and is using shape centroid (auto-computed) to perform
+ * indexing and nearest neighbor queries.
+ *
+ * @remarks
+ * Currently recommended to use
+ * [`NdQuadtreeMap`](https://docs.thi.ng/umbrella/geom-accel/classes/NdQuadtreeMap.html).
+ *
+ * @param accel
+ * @param ref
+ */
+export declare const shapesByNearestNeighbor: (accel: ISpatialMap<ReadonlyVec, IShape> & IRegionQuery<ReadonlyVec, IShape, number>, ref?: ReadonlyVec) => ShapeOrdering;
 //# sourceMappingURL=sort.d.ts.map

package/sort.js

@@ -5,23 +5,26 @@ import { centroid } from "@thi.ng/geom/centroid";
 import { ZERO2 } from "@thi.ng/vectors/api";
 import { distSq2 } from "@thi.ng/vectors/distsq";
 /**
- * Higher order point ordering fn. Lazily sorts points by nearest neighbor
+ * Higher order point ordering fn. Adds points to given spatial
+ * index/acceleration structure and then lazily sorts them by nearest neighbor
  * distance, starting selection of first point based on given `ref` point
  * (default: [0, 0]).
  *
  * @remarks
- * Internally uses a
+ * By default is using a
  * [`KdTreeSet`](https://docs.thi.ng/umbrella/geom-accel/classes/KdTreeSet.html)
  * to index all points and then successively perform efficient nearest neighbor
  * searches (always w.r.t the most recent result point).
  *
+ * @param accel
  * @param ref
  */
-export const pointsByNearestNeighbor = (ref = ZERO2) => function* (pts) {
-    const index = new KdTreeSet(2, pts);
-    while (index.size) {
-        ref = index.queryKeys(ref, 1e4, 1)[0];
-        index.remove(ref);
+export const pointsByNearestNeighbor = (accel = new KdTreeSet(2), ref = ZERO2) => function* (pts) {
+    accel.into(pts);
+    // const index = new KdTreeSet(2, pts);
+    while (accel.size) {
+        ref = accel.queryKeys(ref, 1e4, 1)[0];
+        accel.remove(ref);
         yield ref;
     }
 };
@@ -43,3 +46,26 @@ export const pointsByProximity = (ref = ZERO2) => (pts) => {
 export const shapesByProximity = (ref = ZERO2) => (shapes) => {
     return sortByCachedKey(shapes.slice(), (s) => distSq2(centroid(s) || ZERO2, ref), compareNumAsc);
 };
+/**
+ * Similar to {@link pointsByNearestNeighbor}, however for shapes and requiring
+ * an
+ * [`ISpatialMap`](https://docs.thi.ng/umbrella/geom-api/interfaces/ISpatialMap.html)
+ * implementation and is using shape centroid (auto-computed) to perform
+ * indexing and nearest neighbor queries.
+ *
+ * @remarks
+ * Currently recommended to use
+ * [`NdQuadtreeMap`](https://docs.thi.ng/umbrella/geom-accel/classes/NdQuadtreeMap.html).
+ *
+ * @param accel
+ * @param ref
+ */
+export const shapesByNearestNeighbor = (accel, ref = ZERO2) => function* (shapes) {
+    accel.into(shapes.map((s) => [centroid(s) || [0, 0], s]));
+    while (accel.size) {
+        const pair = accel.query(ref, 1e4, 1)[0];
+        ref = pair[0];
+        accel.remove(ref);
+        yield pair[1];
+    }
+};