@thi.ng/geom-axidraw 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2022-12-29T20:56:59Z
+- **Last updated**: 2023-01-17T10:57:27Z
 - **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-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

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)
@@ -27,11 +28,12 @@ This project is part of the
 
 ## About
 
-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).
+Conversion and preparation of thi.ng/geom shapes & shape groups to/from 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...
+package is responsible for the actual plotter output...
 
 ### Supported shape types
 
@@ -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,21 @@ 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.
+
+![Example draw command visualization based on the code example in this readme](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom-axidraw/readme-commands.png)
+
 ### Basic usage & examples
 
 The main function of this package is the polymorphic function
@@ -160,10 +177,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 +197,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 +250,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 +264,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 +290,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/as-axidraw.js

@@ -6,6 +6,7 @@ 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";
 /**
@@ -69,13 +70,15 @@ export const asAxiDraw = defmulti(__dispatch, {
 });
 function* __group($, opts) {
     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);
     }

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,7 +1,7 @@
 {
   "name": "@thi.ng/geom-axidraw",
-  "version": "0.2.0",
-  "description": "Conversion and preparation of thi.ng/geom shapes & shape groups to AxiDraw pen plotter draw commands",
+  "version": "0.3.1",
+  "description": "Conversion and preparation of thi.ng/geom shapes & shape groups to/from AxiDraw pen plotter draw commands",
   "type": "module",
   "module": "./index.js",
   "typings": "./index.d.ts",
@@ -34,22 +34,22 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.6.2",
-    "@thi.ng/arrays": "^2.5.0",
-    "@thi.ng/axidraw": "^0.3.0",
-    "@thi.ng/compare": "^2.1.21",
-    "@thi.ng/defmulti": "^2.1.26",
-    "@thi.ng/geom": "^4.1.1",
-    "@thi.ng/geom-accel": "^3.2.32",
-    "@thi.ng/geom-api": "^3.3.24",
-    "@thi.ng/geom-clip-line": "^2.2.4",
-    "@thi.ng/geom-isec": "^2.1.41",
-    "@thi.ng/transducers": "^8.3.29",
-    "@thi.ng/vectors": "^7.5.30"
+    "@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",
@@ -106,6 +106,9 @@
     "./as-axidraw": {
       "default": "./as-axidraw.js"
     },
+    "./as-geometry": {
+      "default": "./as-geometry.js"
+    },
     "./sort": {
       "default": "./sort.js"
     }
@@ -118,5 +121,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "28bb74c67217a352d673b6efdab234921d4a370e\n"
+  "gitHead": "02425e5d92d381af664430d56609ee82948b4f59\n"
 }