@thi.ng/geom-axidraw 0.3.12 → 0.5.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-03-14T13:27:19Z
+- **Last updated**: 2023-03-22T22:24:21Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,29 @@ 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.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom-axidraw@0.5.0) (2023-03-22)
+
+#### 🚀 Features
+
+- add support for new draw commands ([e5e994c](https://github.com/thi-ng/umbrella/commit/e5e994c))
+  - update asGeometry() to handle new move commands
+
+## [0.4.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom-axidraw@0.4.0) (2023-03-19)
+
+#### 🚀 Features
+
+- add InterleaveOpts for point clouds ([78012a0](https://github.com/thi-ng/umbrella/commit/78012a0))
+  - add InterleaveOpts & docs
+  - update AxiDrawAttribs
+  - update point cloud processing to support command sequence interleaving
+- add interleave opts support for shape groups ([57783ff](https://github.com/thi-ng/umbrella/commit/57783ff))
+  - update asAxiDraw() impl for shape groups
+
+#### ♻️ Refactoring
+
+- update draw command handling ([18cd5bc](https://github.com/thi-ng/umbrella/commit/18cd5bc))
+- update InterleaveOpts ([0866f9f](https://github.com/thi-ng/umbrella/commit/0866f9f))
+
 ## [0.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom-axidraw@0.3.0) (2023-01-10)
 
 #### 🚀 Features

package/README.md

@@ -18,6 +18,7 @@ This project is part of the
   - [Basic usage & examples](#basic-usage--examples)
     - [Interpolated polygons](#interpolated-polygons)
     - [Clipping](#clipping)
+  - [Supporting custom drawing tools](#supporting-custom-drawing-tools)
 - [Status](#status)
 - [Related packages](#related-packages)
 - [Installation](#installation)
@@ -43,10 +44,10 @@ package is responsible for the actual plotter output...
 | circle     | circle<sup>(1)</sup>                            |
 | cubic      | cubic bezier segment<sup>(1)</sup>              |
 | ellipse    | ellipse<sup>(1)</sup>                           |
-| group      | shape group (possibly nested)                   |
+| group      | shape group (possibly nested)<sup>(3)</sup>     |
 | line       | line segment<sup>(2)</sup>                      |
 | path       | single outline only, no holes                   |
-| points     | point cloud (stippling)                         |
+| points     | point cloud (stippling)<sup>(3)</sup>           |
 | polyline   | polyline (any number of vertices)<sup>(2)</sup> |
 | polygon    | simple polygon, no holes<sup>(2)</sup>          |
 | quad       | arbitrary 4-gon<sup>(2)</sup>                   |
@@ -56,6 +57,7 @@ package is responsible for the actual plotter output...
 
 - <sup>(1)</sup> always interpolated/sampled
 - <sup>(2)</sup> only interpolated if forced via attrib
+- <sup>(3)</sup> supports command sequence interleaving
 
 ### AxiDraw specific shape attributes
 
@@ -81,6 +83,8 @@ any package-specific attribs must be stored under the `__axi` key:
 - `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.
+- `interleave`: Currently only supported for point clouds. See [Supporting
+  custom drawing tools](#supporting-custom-drawing-tools).
 
 ```ts
 // a circle which will be plotted at only 10% of the normal speed
@@ -220,6 +224,55 @@ import { writeFileSync } from "fs";
 })();
 ```
 
+### Supporting custom drawing tools
+
+AxiDraw (and other pen plotters) are not restricted to just using pens, but can
+be used with all sorts of custom drawing tools, some of which (like paint
+brushes) require regular "refills" every N strokes/dots. For that reason, some
+shape types (currently **only** shape groups and point clouds) are supporting
+config & behavior options for interleaving their normal shape command sequence
+with additional tool-specific arbitrary utility command sequences (e.g. to
+regularly dip a brush into a paint pot/palette).
+
+```ts tangle:export/readme-interleave.ts
+import { AxiDraw, COMMENT, dip, MOVE } from "@thi.ng/axidraw";
+import { circle, points, vertices } from "@thi.ng/geom";
+import { asAxiDraw } from "@thi.ng/geom-axidraw";
+
+(async () => {
+    // create point cloud container
+    const pts = points(
+        // using 24 points on a circle w/ origin @ 150,150, radius=100
+        vertices(circle([150, 150], 100), 24),
+        { __axi: {
+            // use command interleaving
+            interleave: {
+                // every 5 points/dots
+                num: 5,
+                // insert these draw commands:
+                // (this function is being re-called every `num` points and
+                // can produce different commands to insert each time...)
+                commands: (n) => [
+                    // no-op command, but will be logged during plotting
+                    COMMENT(`--- refill brush (@ ${n} points) ---`),
+                    // move to XY pos (i.e. position of paint reservoir)
+                    MOVE([10,50]),
+                    // dip the brush 3x times down & up (each time wait 200ms whilst down)
+                    // (dip() creates a cmd sequence, so need to use the spread operator `...` here)
+                    ...dip(3, { downDelay: 200 }),
+                    // (...and then drawing continues w/ next 5 points)
+                ]
+            }
+        }
+    });
+
+    // actually connect & send to plotter
+    const axi = new AxiDraw();
+    await axi.connect();
+    await axi.draw(asAxiDraw(pts));
+})();
+```
+
 ## Status
 
 **ALPHA** - bleeding edge / work-in-progress
@@ -250,7 +303,7 @@ For Node.js REPL:
 const geomAxidraw = await import("@thi.ng/geom-axidraw");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 1.32 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 1.50 KB
 
 ## Dependencies
 

package/api.d.ts

@@ -1,4 +1,5 @@
 import type { Fn } from "@thi.ng/api";
+import type { DrawCommand } from "@thi.ng/axidraw";
 import type { IShape, SamplingOpts } from "@thi.ng/geom-api";
 import type { ReadonlyVec } from "@thi.ng/vectors";
 /**
@@ -58,6 +59,11 @@ export interface AxiDrawAttribs {
      * detail test runs.
      */
     skip: number;
+    /**
+     * Currently only supported for shape groups and point clouds. See
+     * {@link InterleaveOpts} for details.
+     */
+    interleave: InterleaveOpts;
 }
 export interface AsAxiDrawOpts {
     /**
@@ -76,6 +82,37 @@ export interface AsAxiDrawOpts {
      */
     clip: ReadonlyVec[];
 }
+/**
+ * Config & behavior options for interleaving the normal shape command sequence
+ * with tool-specific arbitrary utility command sequences (e.g. to regularly dip
+ * a brush into a paint pot/palette).
+ */
+export interface InterleaveOpts {
+    /**
+     * Number of elements after which to insert the interleave command sequence
+     */
+    num: number;
+    /**
+     * Single arg function which is called every `num` elements (with the count
+     * of elements already processed given as arg) and each time yielding a
+     * [`DrawCommand`](https://docs.thi.ng/umbrella/axidraw/types/DrawCommand.html)
+     * sequence, which will be inserted as-is into the generated main command
+     * sequence of the currently processed shape.
+     *
+     * @param num
+     */
+    commands: Fn<number, Iterable<DrawCommand>>;
+    /**
+     * If true (default), call the given `commands` fn at the beginning of the
+     * shape processing (with arg=0).
+     */
+    start?: boolean;
+    /**
+     * If true (default: false), call the given `commands` fn at the end of the
+     * shape processing (with arg=number of points/elements in the shape).
+     */
+    end?: boolean;
+}
 export type PointOrdering = Fn<ReadonlyVec[], Iterable<ReadonlyVec>>;
 export type ShapeOrdering = Fn<IShape[], Iterable<IShape>>;
 //# sourceMappingURL=api.d.ts.map

package/as-axidraw.d.ts

@@ -1,4 +1,4 @@
-import { DrawCommand } from "@thi.ng/axidraw/api";
+import type { DrawCommand } from "@thi.ng/axidraw/api";
 import type { MultiFn1O } from "@thi.ng/defmulti";
 import type { IShape } from "@thi.ng/geom-api";
 import type { AsAxiDrawOpts } from "./api.js";

package/as-axidraw.js

@@ -1,4 +1,4 @@
-import { UP } from "@thi.ng/axidraw/api";
+import { DOWN, MOVE, UP } from "@thi.ng/axidraw/commands";
 import { polyline } from "@thi.ng/axidraw/polyline";
 import { defmulti } from "@thi.ng/defmulti/defmulti";
 import { clipPolylinePoly } from "@thi.ng/geom-clip-line/clip-poly";
@@ -69,24 +69,42 @@ export const asAxiDraw = defmulti(__dispatch, {
     group: ($, opts) => __group($, opts),
 });
 function* __group($, opts) {
-    const { skip, sort } = __axiAttribs($.attribs);
-    const sopts = __sampleAttribs(opts?.samples, $.attribs);
+    const $sampleOpts = __sampleAttribs(opts?.samples, $.attribs);
+    const { skip, sort, interleave } = __axiAttribs($.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 = {
-            ...$.attribs,
-            ...shape.attribs,
-            __samples: __sampleAttribs(sopts, shape.attribs),
-        };
-        yield* asAxiDraw(shape, opts);
+    function* emitChunk(chunk) {
+        const iter = sort ? sort(chunk) : chunk;
+        for (let child of iter) {
+            const shape = applyTransforms(child);
+            shape.attribs = {
+                ...$.attribs,
+                ...shape.attribs,
+                __samples: __sampleAttribs($sampleOpts, shape.attribs),
+            };
+            yield* asAxiDraw(shape, opts);
+        }
+    }
+    if (interleave) {
+        const { num, commands } = interleave;
+        if (interleave.start !== false)
+            yield* commands(0);
+        for (let i = 0, n = children.length; i < n;) {
+            yield* emitChunk(children.slice(i, i + num));
+            i += num;
+            if (i < n)
+                yield* commands(i);
+        }
+        if (interleave.end)
+            yield* interleave.commands(children.length);
+    }
+    else {
+        yield* emitChunk(children);
     }
 }
 function* __points(pts, attribs, opts) {
     if (!pts.length)
         return;
-    const { clip, delayDown, delayUp, down, skip, speed, sort } = {
+    const { clip, delayDown, delayUp, down, skip, speed, sort, interleave } = {
         sort: pointsByNearestNeighbor(),
         ...__axiAttribs(attribs),
     };
@@ -99,18 +117,34 @@ function* __points(pts, attribs, opts) {
     if (skip) {
         pts = [...takeNth(skip + 1, pts)];
     }
-    yield UP;
-    if (down != undefined)
-        yield ["pen", down];
-    for (let p of sort ? sort(pts) : pts) {
-        yield* [
-            ["m", p, speed],
-            ["d", delayDown],
-            ["u", delayUp],
-        ];
+    function* emitChunk($pts) {
+        if (down != undefined)
+            yield ["pen", down];
+        for (let p of sort ? sort($pts) : $pts) {
+            yield MOVE(p, speed);
+            yield DOWN(delayDown);
+            yield UP(delayUp);
+        }
+        if (down != undefined)
+            yield ["pen"];
+    }
+    yield UP();
+    if (interleave) {
+        const { num, commands } = interleave;
+        if (interleave.start !== false)
+            yield* commands(0);
+        for (let i = 0, n = pts.length; i < n;) {
+            yield* emitChunk(pts.slice(i, i + num));
+            i += num;
+            if (i < n)
+                yield* commands(i);
+        }
+        if (interleave.end)
+            yield* interleave.commands(pts.length);
+    }
+    else {
+        yield* emitChunk(pts);
     }
-    if (down != undefined)
-        yield ["pen"];
 }
 function* __polyline(pts, attribs, opts) {
     if (!pts.length)

package/as-geometry.js

@@ -1,7 +1,8 @@
 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";
+import { add2 } from "@thi.ng/vectors/add";
+import { copy } from "@thi.ng/vectors/copy";
 const DEFAULT_ATTRIBS = {
     paths: { stroke: "#000" },
     rapids: { stroke: "#0ff" },
@@ -40,19 +41,24 @@ export const asGeometry = (src, opts = {}) => {
     let penDown = false;
     let pts = null;
     let currPos = [0, 0];
+    const $move = (newPos) => {
+        if (penDown || opts.rapids) {
+            if (!pts)
+                pts = [copy(currPos), newPos];
+            else
+                pts.push(newPos);
+        }
+        currPos = newPos;
+    };
     for (let cmd of src) {
         switch (cmd[0]) {
+            // absolute
+            case "M":
+                $move(copy(cmd[1]));
+                break;
+            // relative
             case "m":
-                {
-                    const newPos = copy(cmd[1]);
-                    if (penDown || opts.rapids) {
-                        if (!pts)
-                            pts = [copy(currPos), newPos];
-                        else
-                            pts.push(newPos);
-                    }
-                    currPos = newPos;
-                }
+                $move(add2([], currPos, cmd[1]));
                 break;
             case "u":
                 if (pts) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/geom-axidraw",
-  "version": "0.3.12",
+  "version": "0.5.0",
   "description": "Conversion and preparation of thi.ng/geom shapes & shape groups to/from AxiDraw pen plotter draw commands",
   "type": "module",
   "module": "./index.js",
@@ -36,16 +36,16 @@
   "dependencies": {
     "@thi.ng/api": "^8.7.4",
     "@thi.ng/arrays": "^2.5.8",
-    "@thi.ng/axidraw": "^0.5.8",
+    "@thi.ng/axidraw": "^1.1.0",
     "@thi.ng/compare": "^2.1.27",
     "@thi.ng/defmulti": "^2.1.33",
-    "@thi.ng/geom": "^4.2.11",
-    "@thi.ng/geom-accel": "^3.3.8",
-    "@thi.ng/geom-api": "^3.4.9",
-    "@thi.ng/geom-clip-line": "^2.3.9",
-    "@thi.ng/geom-isec": "^2.1.51",
-    "@thi.ng/transducers": "^8.3.38",
-    "@thi.ng/vectors": "^7.6.8"
+    "@thi.ng/geom": "^4.3.0",
+    "@thi.ng/geom-accel": "^3.3.9",
+    "@thi.ng/geom-api": "^3.4.10",
+    "@thi.ng/geom-clip-line": "^2.3.10",
+    "@thi.ng/geom-isec": "^2.1.52",
+    "@thi.ng/transducers": "^8.4.0",
+    "@thi.ng/vectors": "^7.6.9"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.34.4",
@@ -121,5 +121,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "cc46c097a3a173fb1ef41f57a858d03037063141\n"
+  "gitHead": "5b3d731c0e192c53f65efb4baed97be0e4029a33\n"
 }