npm - @thi.ng/axidraw - Versions diffs - 1.0.0 → 1.1.1 - Mend

@thi.ng/axidraw 1.0.0 → 1.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (14) hide show

package/CHANGELOG.md CHANGED Viewed

@@ -1,6 +1,6 @@
 # Change Log
-- **Last updated**: 2023-03-19T14:07:45Z
+- **Last updated**: 2023-03-27T19:05:48Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,38 @@ 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.
+## [1.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/axidraw@1.1.0) (2023-03-22)
+#### 🚀 Features
+- add save/restore commands ([317f8e0](https://github.com/thi-ng/umbrella/commit/317f8e0))
+  - add/update command types
+  - add SAVE/RESTORE to store/restore pen levels
+  - update AxiDraw.draw() to restore state after one-off pen config
+- update DipOpts & dip() ([52d8924](https://github.com/thi-ng/umbrella/commit/52d8924))
+  - rename `down` => `downDelay`, `up` => `upDelay`
+  - add `down`/`up` level opts
+  - update dip() impl to store/restore pen state if using custom
+    up/down levels for dipping
+- add palette command seq gens ([0e453c1](https://github.com/thi-ng/umbrella/commit/0e453c1))
+  - add linearPalette() & radialPalette() and config options
+  - update pkg export maps
+- add global clipping bounds option ([a99a58e](https://github.com/thi-ng/umbrella/commit/a99a58e))
+  - add AxiDrawOpts.clip
+- add support for paper sizes, home offset ([c44510f](https://github.com/thi-ng/umbrella/commit/c44510f))
+  - update AxiDrawOpts.bounds to accept paper sizes ([@thi.ng/units](https://github.com/thi-ng/umbrella/tree/main/packages/units) quantities)
+  - add AxiDrawOpts.home
+  - update AxiDraw ctor & move/sendMove methods
+  - add AxiDraw.setHome()
+  - update pkg deps
+#### ♻️ Refactoring
+- remove obsolete clamping ([50978ba](https://github.com/thi-ng/umbrella/commit/50978ba))
+  - update linearPalette()
+- update bounds handling/clamping ([7850ed6](https://github.com/thi-ng/umbrella/commit/7850ed6))
+  - precalc scale factor & bounds in ctor
 # [1.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/axidraw@1.0.0) (2023-03-19)
 #### 🛑 Breaking changes

package/README.md CHANGED Viewed

@@ -11,7 +11,7 @@ This project is part of the
 - [About](#about)
   - [Declarative vs. imperative](#declarative-vs-imperative)
-  - [Units, limits & clipping](#units-limits--clipping)
+  - [Units, limits & clamping](#units-limits--clamping)
   - [Path planning](#path-planning)
   - [thi.ng/geom support](#thinggeom-support)
   - [SVG support](#svg-support)
@@ -22,11 +22,12 @@ This project is part of the
 - [Installation](#installation)
 - [Dependencies](#dependencies)
 - [API](#api)
+- [Available draw commands](#available-draw-commands)
+  - [Command sequence generators](#command-sequence-generators)
   - [Example usage](#example-usage)
     - [Basics](#basics)
   - [geom-axidraw example](#geom-axidraw-example)
-  - [Available draw commands](#available-draw-commands)
-    - [Command sequence generators](#command-sequence-generators)
+  - [Brush & paint palette](#brush--paint-palette)
 - [Authors](#authors)
 - [License](#license)
@@ -34,6 +35,10 @@ This project is part of the
 Minimal AxiDraw plotter/drawing machine controller for Node.js.
+![AXI-SCAPE #000](https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/axidraw/axiscape-1280.jpg)
+<small>AXI-SCAPE \#000, 12-layer watercolor painting/plot of cellular automata, © 2023 Karsten Schmidt</small>
 This package provides a super-lightweight alternative to control an [AxiDraw
 plotter](https://axidraw.com/) directly from Node.js, using a small custom set
 of medium/high-level drawing commands. Structurally, these custom commands are
@@ -53,15 +58,30 @@ following the pattern of other packages in the
 until the very last moment before being sent to the machine for physical
 output...
-### Units, limits & clipping
+### Units, limits & clamping
-This package performs **no bounds checking nor clipping** and expects all given
-coordinates to be valid and within machine limits. Coordinates can be given in
-any unit, but if not using millimeters (default), a conversion factor to inches
-(`unitsPerInch`) **MUST** be provided as part of the [options
+By default, bounds checking and coordinate clamping are applied (against a user
+defined bounding rect or paper size), however this can be disabled (in which
+case all given coordinates are expected to be valid and within machine limits).
+Coordinates can be given in any unit, but if not using millimeters (default), a
+conversion factor to inches (`unitsPerInch`) **MUST** be provided as part of the
+[options
 object](https://docs.thi.ng/umbrella/axidraw/interfaces/AxiDrawOpts.html) given
-to the `AxiDraw` constructor. Clipping can be handled by the geom or
-geom-axidraw packages (see below)...
+to the `AxiDraw` constructor. Actual geometry clipping can be handled by the
+[geom or geom-axidraw](#thinggeom-support) packages...
+The bounding rect can be either defined by a tuple of `[[minX,minY],
+[maxX,maxY]]` (in worldspace units) or as paper size defined as a
+[`quantity()`](https://docs.thi.ng/umbrella/units/functions/quantity-1.html). The
+default value is DIN A3 landscape.
+If given as paper size (e.g. via
+[thi.ng/units](https://github.com/thi-ng/umbrella/blob/develop/packages/units/)
+presets), the actual units used to define these dimensions are irrelevant and
+will be automatically converted.
+[List of paper
+sizes/presets](https://github.com/thi-ng/umbrella/blob/develop/packages/units/README.md#constants)
 ### Path planning
@@ -166,7 +186,7 @@ For Node.js REPL:
 const axidraw = await import("@thi.ng/axidraw");
 ```
-Package sizes (brotli'd, pre-treeshake): ESM: 2.46 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.13 KB
 ## Dependencies
@@ -176,7 +196,9 @@ Package sizes (brotli'd, pre-treeshake): ESM: 2.46 KB
 - [@thi.ng/date](https://github.com/thi-ng/umbrella/tree/develop/packages/date)
 - [@thi.ng/errors](https://github.com/thi-ng/umbrella/tree/develop/packages/errors)
 - [@thi.ng/logger](https://github.com/thi-ng/umbrella/tree/develop/packages/logger)
+- [@thi.ng/math](https://github.com/thi-ng/umbrella/tree/develop/packages/math)
 - [@thi.ng/transducers](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers)
+- [@thi.ng/units](https://github.com/thi-ng/umbrella/tree/develop/packages/units)
 - [@thi.ng/vectors](https://github.com/thi-ng/umbrella/tree/develop/packages/vectors)
 - [serialport](git://github.com/serialport/node-serialport.git)
@@ -184,6 +206,46 @@ Package sizes (brotli'd, pre-treeshake): ESM: 2.46 KB
 [Generated API docs](https://docs.thi.ng/umbrella/axidraw/)
+## Available draw commands
+All
+[`DrawCommand`s](https://docs.thi.ng/umbrella/axidraw/types/DrawCommand.html)
+are expressed as S-expression-like, [thi.ng/hiccup]()-style elements, aka JS
+arrays/tuples of `[command, ...args]`. The following commands are supported. All
+also as predefined constants or factory functions for the parametric ones:
+| Command                                           | Preset/factory                                                                                                                      | Description                                        |
+|---------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------|
+| `["comment", msg]`                                | [`COMMENT`](https://docs.thi.ng/umbrella/axidraw/functions/COMMENT.html)                                                            | Ignored, but logged during plotting                |
+| `["d", delay?, level?]` / `["u", delay?, level?]` | [`DOWN`](https://docs.thi.ng/umbrella/axidraw/functions/DOWN.html) / [`UP`](https://docs.thi.ng/umbrella/axidraw/functions/UP.html) | Move pen up/down w/ optional delay & level (0-100) |
+| `["home"]`                                        | `HOME`                                                                                                                              | Move to home position (origin)                     |
+| `["m", [x,y], speed?]`                            | [`MOVE_REL`](https://docs.thi.ng/umbrella/axidraw/functions/MOVE_REL.html)                                                          | Move to relative position w/ optional speed factor |
+| `["M", [x,y], speed?]`                            | [`MOVE`](https://docs.thi.ng/umbrella/axidraw/functions/MOVE.html)                                                                  | Move to absolute position w/ optional speed factor |
+| `["on"]` / `["off"]`                              | `ON` / `OFF`                                                                                                                        | Turn motors on/off                                 |
+| `["pen", down, up]`                               | [`PEN`](https://docs.thi.ng/umbrella/axidraw/functions/PEN.html)                                                                    | Pen config (up/down levels)                        |
+| `["reset"]`                                       | `RESET`                                                                                                                             | Execute user defined reset sequence<sup>(1)</sup>  |
+| `["restore"]`                                     | `RESTORE`                                                                                                                           | Restore saved pen up/down levels                   |
+| `["save"]`                                        | `SAVE`                                                                                                                              | Save current pen up/down levels                    |
+| `["start"]`                                       | `START`                                                                                                                             | Execute user defined start sequence<sup>(1)</sup>  |
+| `["stop"]`                                        | `STOP`                                                                                                                              | Execute user defined stop sequence<sup>(1)</sup>   |
+| `["w", delay]`                                    | [`WAIT`](https://docs.thi.ng/umbrella/axidraw/functions/WAIT.html)                                                                  | Wait N milliseconds                                |
+- <sup>(1)</sup> See
+  [AxiDrawOpts](https://docs.thi.ng/umbrella/axidraw/interfaces/AxiDrawOpts.html)
+  for details.
+### Command sequence generators
+Additionally, the following command sequence generators are provided (see their
+docs for details and code examples):
+- [`complete()`](https://docs.thi.ng/umbrella/axidraw/functions/complete.html)
+- [`dip()`](https://docs.thi.ng/umbrella/axidraw/functions/dip.html)
+- [`linearPalette()`](https://docs.thi.ng/umbrella/axidraw/functions/linearPalette.html)
+- [`polyline()`](https://docs.thi.ng/umbrella/axidraw/functions/polyline.html)
+- [`radialPalette()`](https://docs.thi.ng/umbrella/axidraw/functions/radialPalette.html)
+- [`registrationMark()`](https://docs.thi.ng/umbrella/axidraw/functions/registrationMark.html)
 ### Example usage
 #### Basics
@@ -259,6 +321,72 @@ import { map, range } from "@thi.ng/transducers";
 })();
 ```
+### Brush & paint palette
+This example illustrates how the [`linearPalette()`]() command sequence
+generator can be used to paint random dots with a brush which gets re-dipped in
+different paints every 10 dots...
+Also see
+[`InterleaveOpts`](https://docs.thi.ng/umbrella/geom-axidraw/interfaces/InterleaveOpts.html)
+for more details...
+```ts
+import { points } from "@thi.ng/geom";
+import { asAxiDraw } from "@thi.ng/geom-axidraw";
+import { repeatedly } from "@thi.ng/transducers";
+import { randMinMax2 } from "@thi.ng/vectors";
+// configure palette
+// "linear" here means the palette slots are arranged in a line
+// (there's also a radialPalette() function for circular/elliptical palette layouts)
+const palette = linearPalette({
+    // first palette slot is near the world origin (slight offset)
+    pos: [2, 0],
+    // 2mm jitter radius (to not always move to exact same position)
+    jitter: 2,
+    // palette has 5 paint slots
+    num: 5,
+    // each slot 40mm separation along Y-axis
+    // (needs to be measured/determined manually)
+    step: [0, 40],
+    // dip brush 3x each time
+    repeat: 3,
+});
+// define point cloud of 100 random points
+// using a random palette slot each time (for each refill)
+// assign axidraw-specific attribs to refill brush every 10 dots
+const cloud = points(
+    // pick random points
+    [...repeatedly(() => randMinMax2([], [10, 10], [190, 190]), 100)],
+    // shape attributes
+    {
+        __axi: {
+            interleave: {
+                // every 10 elements/dots...
+                num: 10,
+                // execute these commands...
+                commands: () => [
+                    // first brush cleaning in water
+                    // (we decide to use the last palette slot for that)
+                    ...palette(4),
+                    // now "refill" brush at a random other slot
+                    ...palette(Math.floor(Math.random() * 4))
+                ]
+            }
+        }
+    }
+);
+// AxiDraw setup
+const axi = new AxiDraw();
+...
+// convert geometry into axidraw commands and send to plotter
+axi.draw(asAxiDraw(cloud));
+```
 Other selected toots/tweets:
 - [Project announcement](https://mastodon.thi.ng/@toxi/109490174709589253)
@@ -268,39 +396,9 @@ Other selected toots/tweets:
 - [Bitmap-to-vector conversions & shape sorting](https://mastodon.thi.ng/@toxi/109570540391689321)
 - [Multi-color plotting](https://mastodon.thi.ng/@toxi/109586780630493994)
 - [Using water color & paintbrush](https://mastodon.thi.ng/@toxi/110044424626641749)
+- [Water color brush tests](https://mastodon.thi.ng/@toxi/110051629944117139)
 - more to come...
-### Available draw commands
-All
-[`DrawCommand`s](https://docs.thi.ng/umbrella/axidraw/types/DrawCommand.html)
-are expressed as S-expression-like, [thi.ng/hiccup]()-style elements, aka JS
-arrays/tuples of `[command, ...args]`. The following commands are supported. All
-also as predefined constants or factory functions for the parametric ones:
-| Command                           | Preset/factory                                                                                                                      |
-|-----------------------------------|-------------------------------------------------------------------------------------------------------------------------------------|
-| `["comment", msg]`                | [`COMMENT`](https://docs.thi.ng/umbrella/axidraw/functions/COMMENT.html)                                                            |
-| `["d", delay?]` / `["u", delay?]` | [`DOWN`](https://docs.thi.ng/umbrella/axidraw/functions/DOWN.html) / [`UP`](https://docs.thi.ng/umbrella/axidraw/functions/UP.html) |
-| `["home"]`                        | `HOME`                                                                                                                              |
-| `["m", [x,y], speed?]`            | [`MOVE_REL`](https://docs.thi.ng/umbrella/axidraw/functions/MOVE_REL.html)                                                          |
-| `["M", [x,y], speed?]`            | [`MOVE`](https://docs.thi.ng/umbrella/axidraw/functions/MOVE.html)                                                                  |
-| `["on"]` / `["off"]`              | `ON` / `OFF`                                                                                                                        |
-| `["pen", down, up]`               | [`PEN`](https://docs.thi.ng/umbrella/axidraw/functions/PEN.html)                                                                    |
-| `["reset"]`                       | `RESET`                                                                                                                             |
-| `["start"]`                       | `START`                                                                                                                             |
-| `["stop"]`                        | `STOP`                                                                                                                              |
-| `["w", delay]`                    | [`WAIT`](https://docs.thi.ng/umbrella/axidraw/functions/WAIT.html)                                                                  |
-#### Command sequence generators
-Additionally, the following command sequence generators are provided (see their docs for code examples):
-- [`complete`](https://docs.thi.ng/umbrella/axidraw/functions/complete.html)
-- [`dip`](https://docs.thi.ng/umbrella/axidraw/functions/dip.html)
-- [`polyline`](https://docs.thi.ng/umbrella/axidraw/functions/polyline.html)
-- [`registrationMark`](https://docs.thi.ng/umbrella/axidraw/functions/registrationMark.html)
 ## Authors
 - [Karsten Schmidt](https://thi.ng)

package/api.d.ts CHANGED Viewed

@@ -1,5 +1,6 @@
 import type { IDeref } from "@thi.ng/api";
 import type { ILogger } from "@thi.ng/logger";
+import type { Quantity } from "@thi.ng/units";
 import type { ReadonlyVec } from "@thi.ng/vectors";
 /** Start command sequence (configurable via {@link AxiDrawOpts}) */
 export type StartCommand = ["start"];
@@ -33,7 +34,15 @@ export type MoveRelCommand = ["m", ReadonlyVec, number?];
 export type WaitCommand = ["w", number];
 /** Ignored, but will be logged (if logging enabled) */
 export type CommentCommand = ["comment", string];
-export type DrawCommand = StartCommand | StopCommand | HomeCommand | ResetCommand | MotorCommand | PenConfigCommand | PenUpDownCommand | MoveXYCommand | MoveRelCommand | WaitCommand | CommentCommand;
+/**
+ * Stores current pen configuration on stack.
+ */
+export type SaveCommand = ["save"];
+/**
+ * Restores current pen configuration from stack.
+ */
+export type RestoreCommand = ["restore"];
+export type DrawCommand = CommentCommand | HomeCommand | MotorCommand | MoveRelCommand | MoveXYCommand | PenConfigCommand | PenUpDownCommand | ResetCommand | RestoreCommand | SaveCommand | StartCommand | StopCommand | WaitCommand;
 /**
  * Global plotter drawing configuration. Also see {@link DEFAULT_OPTS}.
  */
@@ -65,6 +74,28 @@ export interface AxiDrawOpts {
      * all or if the control is in the {@link AxiDrawState.CONTINUE} state.
      */
     control?: IDeref<AxiDrawState>;
+    /**
+     * All XY coords will be clamped to given bounding rect, either defined by
+     * `[[minX,minY], [maxX,maxY]]` (in worldspace units) or as paper size
+     * defined as a
+     * [`quantity`](https://docs.thi.ng/umbrella/units/functions/quantity-1.html).
+     * The default value is DIN A3 landscape.
+     *
+     * @remarks
+     * Set to `undefined` to disable bounds/clipping. If given a paper size (via
+     * thi.ng/units `quantity()`), the units used to define these dimensions are
+     * irrelevant (and independent of {@link AxiDrawOpts.unitsPerInch}!) and
+     * will be automatically converted. Also, the resulting bounds will always
+     * be based on [0, 0].
+     *
+     * List of paper sizes/presets:
+     * https://github.com/thi-ng/umbrella/blob/develop/packages/units/README.md#constants
+     *
+     * Also see {@link AxiDrawOpts.unitsPerInch}
+     *
+     * @defaultValue `DIN_A3_LANDSCAPE`
+     */
+    bounds?: [ReadonlyVec, ReadonlyVec] | Quantity<number[]>;
     /**
      * Conversion factor from geometry worldspace units to inches.
      * Default units are millimeters.
@@ -132,6 +163,22 @@ export interface AxiDrawOpts {
      * @defaultValue `[UP, HOME, OFF]`
      */
     stop: DrawCommand[];
+    /**
+     * Position (in world space units) which is considered the origin and which
+     * will be added to all coordinates as offset (e.g. for plotting with a
+     * physically offset easel).
+     *
+     * @remarks
+     * Note: The configured {@link AxiDrawOpts.bounds} are independent from this
+     * setting and are intended to enforce the plotter's physical movement
+     * limits. E.g. shifting the home/offset position by +100mm along X (and
+     * assuming only positive coordinates will be used for the drawing), simply
+     * means the available horizontal drawing space will be reduced by the same
+     * amount...
+     *
+     * @defaultValue [0, 0]
+     */
+    home: ReadonlyVec;
     /**
      * Refresh interval for checking the control FSM in paused state.
      *

package/axidraw.d.ts CHANGED Viewed

@@ -1,6 +1,6 @@
 import type { IReset } from "@thi.ng/api";
-import { ReadonlyVec, Vec } from "@thi.ng/vectors/api";
-import { AxiDrawOpts, DrawCommand, ISerial, Metrics } from "./api.js";
+import { type ReadonlyVec, type Vec, type VecPair } from "@thi.ng/vectors/api";
+import { type AxiDrawOpts, type DrawCommand, type ISerial, type Metrics } from "./api.js";
 export declare const DEFAULT_OPTS: AxiDrawOpts;
 export declare class AxiDraw implements IReset {
     serial: ISerial;
@@ -8,8 +8,12 @@ export declare class AxiDraw implements IReset {
     isConnected: boolean;
     isPenDown: boolean;
     penLimits: [number, number];
+    penState: [number, number][];
     pos: Vec;
     targetPos: Vec;
+    homePos: ReadonlyVec;
+    scale: number;
+    bounds?: VecPair;
     constructor(opts?: Partial<AxiDrawOpts>);
     reset(): this;
     /**
@@ -69,6 +73,8 @@ export declare class AxiDraw implements IReset {
     draw1(cmd: DrawCommand): Promise<Metrics>;
     motorsOn(): void;
     motorsOff(): void;
+    save(): void;
+    restore(): void;
     penConfig(down?: number, up?: number): void;
     penUp(delay?: number, level?: number): number;
     penDown(delay?: number, level?: number): number;
@@ -97,6 +103,7 @@ export declare class AxiDraw implements IReset {
      * Syntax sugar for {@link AxiDraw.moveTo}([0, 0]).
      */
     home(): number[];
+    setHome(pos: ReadonlyVec): void;
     protected onSignal(): Promise<void>;
     protected send(msg: string): void;
     protected sendMove(tempo?: number): number[];

package/axidraw.js CHANGED Viewed

@@ -5,8 +5,12 @@ import { assert } from "@thi.ng/errors/assert";
 import { ioerror } from "@thi.ng/errors/io";
 import { unsupported } from "@thi.ng/errors/unsupported";
 import { ConsoleLogger } from "@thi.ng/logger/console";
+import { DIN_A3_LANDSCAPE } from "@thi.ng/units/constants/paper-sizes";
+import { convert, div, Quantity } from "@thi.ng/units/unit";
+import { inch } from "@thi.ng/units/units/length";
 import { abs2 } from "@thi.ng/vectors/abs";
-import { ZERO2 } from "@thi.ng/vectors/api";
+import { ZERO2, } from "@thi.ng/vectors/api";
+import { clamp2 } from "@thi.ng/vectors/clamp";
 import { maddN2 } from "@thi.ng/vectors/maddn";
 import { mag } from "@thi.ng/vectors/mag";
 import { mulN2 } from "@thi.ng/vectors/muln";
@@ -22,6 +26,8 @@ export const DEFAULT_OPTS = {
     logger: new ConsoleLogger("axidraw"),
     control: new AxiDrawControl(),
     refresh: 1000,
+    bounds: DIN_A3_LANDSCAPE,
+    home: [0, 0],
     unitsPerInch: 25.4,
     stepsPerInch: 2032,
     speedDown: 4000,
@@ -39,10 +45,26 @@ export class AxiDraw {
     constructor(opts = {}) {
         this.isConnected = false;
         this.isPenDown = false;
+        this.penState = [];
         this.pos = [0, 0];
         this.targetPos = [0, 0];
         this.opts = { ...DEFAULT_OPTS, ...opts };
         this.penLimits = [this.opts.down, this.opts.up];
+        this.scale = this.opts.stepsPerInch / this.opts.unitsPerInch;
+        this.setHome(this.opts.home);
+        if (this.opts.bounds) {
+            this.bounds =
+                this.opts.bounds instanceof Quantity
+                    ? [
+                        [0, 0],
+                        convert(this.opts.bounds, div(inch, this.opts.stepsPerInch)),
+                    ]
+                    : [
+                        mulN2([], this.opts.bounds[0], this.scale),
+                        mulN2([], this.opts.bounds[1], this.scale),
+                    ];
+        }
+        this.save();
     }
     reset() {
         zero(this.pos);
@@ -185,6 +207,12 @@ export class AxiDraw {
                     wait = this.penDown(a, b);
                     penCommands++;
                     break;
+                case "save":
+                    this.save();
+                    break;
+                case "restore":
+                    this.restore();
+                    break;
                 case "w":
                     wait = a;
                     break;
@@ -207,6 +235,13 @@ export class AxiDraw {
                 logger.debug(`waiting ${wait}ms...`);
                 await delayed(0, wait);
             }
+            // restore one-off pen config to current state
+            if (cmd === "d" && b !== undefined) {
+                this.sendPenConfig(5, this.penLimits[0]);
+            }
+            else if (cmd === "u" && b !== undefined) {
+                this.sendPenConfig(4, this.penLimits[1]);
+            }
         }
         const duration = Date.now() - t0;
         if (showMetrics) {
@@ -239,6 +274,20 @@ export class AxiDraw {
     motorsOff() {
         this.send("EM,0,0\r");
     }
+    save() {
+        this.opts.logger.debug("saving pen state:", this.penLimits);
+        this.penState.push(this.penLimits.slice());
+    }
+    restore() {
+        if (this.penState.length < 2) {
+            this.opts.logger.warn("stack underflow, can't restore pen state");
+            return;
+        }
+        const [down, up] = (this.penLimits = this.penState.pop());
+        this.sendPenConfig(5, down);
+        this.sendPenConfig(4, up);
+        this.opts.logger.debug("restored pen state:", this.penLimits);
+    }
     penConfig(down, up) {
         down = down !== undefined ? down : this.opts.down;
         this.sendPenConfig(5, down);
@@ -278,9 +327,9 @@ export class AxiDraw {
      * @param tempo
      */
     moveTo(p, tempo) {
-        const { targetPos, opts } = this;
-        // apply scale factor: worldspace units -> motor steps
-        mulN2(targetPos, p, opts.stepsPerInch / opts.unitsPerInch);
+        const { homePos, scale, targetPos } = this;
+        // apply scale factor: worldspace units -> motor steps, add home offset
+        maddN2(targetPos, p, scale, homePos);
         return this.sendMove(tempo);
     }
     /**
@@ -290,9 +339,9 @@ export class AxiDraw {
      * @param tempo
      */
     moveRelative(delta, tempo) {
-        const { pos, targetPos, opts } = this;
+        const { pos, scale, targetPos } = this;
         // apply scale factor: worldspace units -> motor steps
-        maddN2(targetPos, delta, opts.stepsPerInch / opts.unitsPerInch, pos);
+        maddN2(targetPos, delta, scale, pos);
         return this.sendMove(tempo);
     }
     /**
@@ -301,6 +350,10 @@ export class AxiDraw {
     home() {
         return this.moveTo(ZERO2);
     }
+    setHome(pos) {
+        this.homePos = mulN2([], pos, this.scale);
+        this.opts.logger.debug("setting home position:", pos);
+    }
     async onSignal() {
         this.opts.logger.warn(`SIGNINT received, stop drawing...`);
         this.penUp(0);
@@ -313,14 +366,16 @@ export class AxiDraw {
         this.serial.write(msg);
     }
     sendMove(tempo = 1) {
-        const { pos, targetPos, opts, isPenDown } = this;
+        const { bounds, pos, scale, targetPos, opts, isPenDown } = this;
+        if (bounds)
+            clamp2(null, targetPos, ...bounds);
         const delta = sub2([], targetPos, pos);
         set2(pos, targetPos);
         const maxAxis = Math.max(...abs2([], delta));
         const duration = (1000 * maxAxis) /
             ((isPenDown ? opts.speedDown : opts.speedUp) * tempo);
         this.send(`XM,${duration | 0},${delta[0] | 0},${delta[1] | 0}\r`);
-        return [duration, (mag(delta) * opts.unitsPerInch) / opts.stepsPerInch];
+        return [duration, mag(delta) / scale];
     }
     /**
      * Sends pen up/down config

package/commands.d.ts CHANGED Viewed

@@ -1,9 +1,13 @@
 import type { ReadonlyVec } from "@thi.ng/vectors";
-import type { CommentCommand, DrawCommand, HomeCommand, MotorCommand, MoveRelCommand, MoveXYCommand, PenConfigCommand, PenUpDownCommand, ResetCommand, StartCommand, StopCommand, WaitCommand } from "./api.js";
+import type { CommentCommand, DrawCommand, HomeCommand, MotorCommand, MoveRelCommand, MoveXYCommand, PenConfigCommand, PenUpDownCommand, ResetCommand, RestoreCommand, SaveCommand, StartCommand, StopCommand, WaitCommand } from "./api.js";
 export declare const START: StartCommand;
 export declare const STOP: StopCommand;
 export declare const HOME: HomeCommand;
 export declare const RESET: ResetCommand;
+export declare const ON: MotorCommand;
+export declare const OFF: MotorCommand;
+export declare const SAVE: SaveCommand;
+export declare const RESTORE: RestoreCommand;
 /**
  * Creates a {@link PenConfigCommand} using provided down/up positions.
  *
@@ -12,19 +16,21 @@ export declare const RESET: ResetCommand;
  */
 export declare const PEN: (posDown?: number, posUp?: number) => PenConfigCommand;
 /**
- * Creates a {@link PenUpDownCommand} to move the pen up.
+ * Creates a {@link PenUpDownCommand} to move the pen up. Both args are optional
+ * and if omitted globally configured values are used.
  *
  * @param delay
+ * @param level
  */
-export declare const UP: (delay?: number) => PenUpDownCommand;
+export declare const UP: (delay?: number, level?: number) => PenUpDownCommand;
 /**
- * Creates a {@link PenUpDownCommand} to move the pen down.
+ * Creates a {@link PenUpDownCommand} to move the pen down. Both args are
+ * optional and if omitted globally configured values are used.
  *
  * @param delay
+ * @param level
  */
-export declare const DOWN: (delay?: number) => PenUpDownCommand;
-export declare const ON: MotorCommand;
-export declare const OFF: MotorCommand;
+export declare const DOWN: (delay?: number, level?: number) => PenUpDownCommand;
 /**
  * Creates a {@link MoveXYCommand} command (absolute coordinates).
  *

package/commands.js CHANGED Viewed

@@ -2,6 +2,10 @@ export const START = ["start"];
 export const STOP = ["stop"];
 export const HOME = ["home"];
 export const RESET = ["reset"];
+export const ON = ["on"];
+export const OFF = ["off"];
+export const SAVE = ["save"];
+export const RESTORE = ["restore"];
 /**
  * Creates a {@link PenConfigCommand} using provided down/up positions.
  *
@@ -14,19 +18,29 @@ export const PEN = (posDown, posUp) => [
     posUp,
 ];
 /**
- * Creates a {@link PenUpDownCommand} to move the pen up.
+ * Creates a {@link PenUpDownCommand} to move the pen up. Both args are optional
+ * and if omitted globally configured values are used.
  *
  * @param delay
+ * @param level
  */
-export const UP = (delay) => ["u", delay];
+export const UP = (delay, level) => [
+    "u",
+    delay,
+    level,
+];
 /**
- * Creates a {@link PenUpDownCommand} to move the pen down.
+ * Creates a {@link PenUpDownCommand} to move the pen down. Both args are
+ * optional and if omitted globally configured values are used.
  *
  * @param delay
+ * @param level
  */
-export const DOWN = (delay) => ["d", delay];
-export const ON = ["on"];
-export const OFF = ["off"];
+export const DOWN = (delay, level) => [
+    "d",
+    delay,
+    level,
+];
 /**
  * Creates a {@link MoveXYCommand} command (absolute coordinates).
  *

package/dip.d.ts CHANGED Viewed

@@ -2,18 +2,28 @@ import type { Fn0 } from "@thi.ng/api";
 import type { DrawCommand } from "./api.js";
 export interface DipOpts {
     /**
-     * Delay for emitted {@link DOWN} commands. If omitted, uses globally
-     * configured default.
+     * Pen level (0-99) for emitted {@link UP} commands. If omitted, uses
+     * currently configured default.
      */
     up: number;
     /**
-     * Delay for emitted {@link UP} commands. If omitted, uses globally
+     * Delay for emitted {@link DOWN} commands. If omitted, uses currently
      * configured default.
      */
+    upDelay: number;
+    /**
+     * Pen level (0-99) for emitted {@link DOWN} commands. If omitted, uses
+     * currently configured default.
+     */
     down: number;
+    /**
+     * Delay for emitted {@link UP} commands. If omitted, uses currently
+     * configured default.
+     */
+    downDelay: number;
     /**
      * No-arg function to inject custom commands between each down - up command.
-     * See example in {@link DIP} docs.
+     * See example in {@link dip} docs.
      */
     commands: Fn0<Iterable<DrawCommand>>;
 }
@@ -56,5 +66,5 @@ export interface DipOpts {
  * @param n
  * @param opts
  */
-export declare const dip: (n: number, opts?: Partial<DipOpts>) => IterableIterator<DrawCommand>;
+export declare const dip: (n: number, opts?: Partial<DipOpts>) => Iterable<DrawCommand>;
 //# sourceMappingURL=dip.d.ts.map

package/dip.js CHANGED Viewed

@@ -1,6 +1,6 @@
 import { flatten1 } from "@thi.ng/transducers/flatten1";
 import { repeatedly } from "@thi.ng/transducers/repeatedly";
-import { DOWN, UP } from "./commands.js";
+import { DOWN, RESTORE, SAVE, UP } from "./commands.js";
 /**
  * Yields a **sequence** of `n` repetitions of {@link DOWN}, {@link UP}
  * commands, optionally interspersed with other user provided
@@ -40,6 +40,13 @@ import { DOWN, UP } from "./commands.js";
  * @param n
  * @param opts
  */
-export const dip = (n, opts = {}) => flatten1(repeatedly(opts.commands
-    ? () => [DOWN(opts.down), ...opts.commands(), UP(opts.up)]
-    : () => [DOWN(opts.down), UP(opts.up)], n));
+export const dip = (n, opts = {}) => {
+    const down = DOWN(opts.downDelay, opts.down);
+    const up = UP(opts.upDelay, opts.up);
+    const main = flatten1(repeatedly(opts.commands
+        ? () => [down, ...opts.commands(), up]
+        : () => [down, up], n));
+    return opts.down !== undefined || opts.up !== undefined
+        ? [SAVE, ...main, RESTORE]
+        : main;
+};

package/index.d.ts CHANGED Viewed

@@ -3,6 +3,7 @@ export * from "./axidraw.js";
 export * from "./commands.js";
 export * from "./control.js";
 export * from "./dip.js";
+export * from "./palettes.js";
 export * from "./polyline.js";
 export * from "./registration.js";
 export * from "./serial.js";

package/index.js CHANGED Viewed

@@ -3,6 +3,7 @@ export * from "./axidraw.js";
 export * from "./commands.js";
 export * from "./control.js";
 export * from "./dip.js";
+export * from "./palettes.js";
 export * from "./polyline.js";
 export * from "./registration.js";
 export * from "./serial.js";

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/axidraw",
-  "version": "1.0.0",
+  "version": "1.1.1",
   "description": "Minimal AxiDraw plotter/drawing machine controller for Node.js",
   "type": "module",
   "module": "./index.js",
@@ -34,23 +34,25 @@
     "test": "testament test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.7.4",
-    "@thi.ng/checks": "^3.3.10",
-    "@thi.ng/compose": "^2.1.29",
-    "@thi.ng/date": "^2.4.8",
-    "@thi.ng/errors": "^2.2.13",
-    "@thi.ng/logger": "^1.4.11",
-    "@thi.ng/transducers": "^8.4.0",
-    "@thi.ng/vectors": "^7.6.9",
+    "@thi.ng/api": "^8.7.5",
+    "@thi.ng/checks": "^3.3.11",
+    "@thi.ng/compose": "^2.1.30",
+    "@thi.ng/date": "^2.4.10",
+    "@thi.ng/errors": "^2.2.14",
+    "@thi.ng/logger": "^1.4.12",
+    "@thi.ng/math": "^5.4.6",
+    "@thi.ng/transducers": "^8.4.1",
+    "@thi.ng/units": "^0.4.1",
+    "@thi.ng/vectors": "^7.6.10",
     "serialport": "^10.5.0"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.34.4",
-    "@thi.ng/testament": "^0.3.13",
-    "rimraf": "^4.4.0",
+    "@thi.ng/testament": "^0.3.14",
+    "rimraf": "^4.4.1",
     "tools": "^0.0.1",
-    "typedoc": "^0.23.26",
-    "typescript": "^4.9.5"
+    "typedoc": "^0.23.28",
+    "typescript": "^5.0.2"
   },
   "keywords": [
     "2d",
@@ -96,6 +98,9 @@
     "./dip": {
       "default": "./dip.js"
     },
+    "./palettes": {
+      "default": "./palettes.js"
+    },
     "./polyline": {
       "default": "./polyline.js"
     },
@@ -110,5 +115,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "1359645f3af8a7d0d43fe7944ea5cd865832f8ee\n"
+  "gitHead": "83b15b34326d480cbca0472b20390d4d3bbb792a\n"
 }

package/palettes.d.ts ADDED Viewed

@@ -0,0 +1,145 @@
+import type { ReadonlyVec } from "@thi.ng/vectors/api";
+import { type DipOpts } from "./dip.js";
+export interface BasePaletteOpts extends Partial<DipOpts> {
+    /**
+     * Jitter radius for base position.
+     *
+     * @defaultValue 0
+     */
+    jitter?: number;
+    /**
+     * Number of palette slots.
+     */
+    num: number;
+    /**
+     * Number of brush dips to execute.
+     *
+     * @defaultValue 1
+     */
+    repeat?: number;
+}
+export interface LinearPaletteOpts extends BasePaletteOpts {
+    /**
+     * Palette's base position (in world space units). See {@link AxiDrawOpts.unitsPerInch}.
+     *
+     * @defaultValue [0, 0]
+     */
+    pos?: ReadonlyVec;
+    /**
+     * Step direction vector between palette slots.
+     */
+    step: ReadonlyVec;
+}
+export interface RadialPaletteOpts extends BasePaletteOpts {
+    /**
+     * Palette's center position (in world space units). See {@link AxiDrawOpts.unitsPerInch}.
+     */
+    pos: ReadonlyVec;
+    /**
+     * Palette radius (measured to the center of each palette slot). If
+     * circular, given as number. If elliptical, given as vector.
+     */
+    radius: number | ReadonlyVec;
+    /**
+     * Start angle (in radians).
+     *
+     * @defaultValue 0
+     */
+    startTheta?: number;
+    /**
+     * End angle (in radians). This is 2π for a full-circle palette.
+     */
+    endTheta?: number;
+}
+/**
+ * Higher order {@link DrawCommand} sequence generator for working with paint
+ * brushes. Takes an config object describing a linear paint palette layout and
+ * behavior options for dipping the brush. Returns a function which takes a
+ * palette slot index as argument and returns a command sequence moving the
+ * plotter to the palette slot and dipping the brush to refill.
+ *
+ * @remarks
+ * Can be used with
+ * [InterleaveOpts](https://docs.thi.ng/umbrella/geom-axidraw/interfaces/InterleaveOpts.html)
+ * of https://thi.ng/geom-axidraw.
+ *
+ * Also see:
+ * - {@link LinearPaletteOpts} for options
+ * - {@link radialPalette} for circular/elliptical palette layouts
+ * - {@link dip} (used internally for dipping sequence)
+ *
+ * @example
+ * ```ts
+ * import { points } from "@thi.ng/geom";
+ * import { asAxiDraw } from "@thi.ng/geom-axidraw";
+ * import { repeatedly } from "@thi.ng/transducers";
+ * import { randMinMax2 } from "@thi.ng/vectors";
+ *
+ * // configure palette
+ * const palette = linearPalette({
+ *   // first palette slot is near the world origin (slight offset)
+ *   pos: [2, 0],
+ *   // palette has 5 paint slots
+ *   num: 5,
+ *   // each slot 40mm separation along Y-axis
+ *   // (needs to be measured/determined manually)
+ *   step: [0, 40],
+ *   // 2mm jitter radius (to not always move to exact same position)
+ *   jitter: 2,
+ *   // dip brush 3x each time
+ *   repeat: 3,
+ * });
+ *
+ * // investigate command sequence for requesting slot #1
+ * palette(1)
+ * // [
+ * //   [ "M", [ 0.8949, 41.6697 ], 1 ],
+ * //   [ "d", undefined, undefined ],
+ * //   [ "u", undefined, undefined ],
+ * //   [ "d", undefined, undefined ],
+ * //   [ "u", undefined, undefined ],
+ * //   [ "d", undefined, undefined ],
+ * //   [ "u", undefined, undefined ]
+ * // ]
+ *
+ * // define point cloud of 100 random points
+ * // using a random palette slot each time (for each refill)
+ * // assign axidraw-specific attribs to refill brush every 10 dots
+ * const cloud = points(
+ *   [...repeatedly(() => randMinMax2([], [10, 10], [190, 190]), 100)],
+ *   {
+ *     __axi: {
+ *       interleave: {
+ *         num: 10,
+ *         commands: () => palette((Math.random() * 5) | 0)
+ *       }
+ *     }
+ *   }
+ * );
+ *
+ * // AxiDraw setup
+ * const axi = new AxiDraw();
+ * ...
+ *
+ * // convert geometry into axidraw commands and send to plotter
+ * axi.draw(asAxiDraw(cloud));
+ * ```
+ *
+ * @param opts
+ */
+export declare const linearPalette: (opts: LinearPaletteOpts) => (id: number) => import("./api.js").DrawCommand[];
+/**
+ * Higher order {@link DrawCommand} sequence generator for working with paint
+ * brushes. Similar to {@link linearPalette}, but for circular or elliptic
+ * palette layouts.
+ *
+ * @remarks
+ * Also see:
+ * - {@link RadialPaletteOpts} for options
+ * - {@link linearPalette} for more details & code example
+ * - {@link dip} (used internally for dipping sequence)
+ *
+ * @param opts
+ */
+export declare const radialPalette: (opts: RadialPaletteOpts) => (id: number) => import("./api.js").DrawCommand[];
+//# sourceMappingURL=palettes.d.ts.map

package/palettes.js ADDED Viewed

@@ -0,0 +1,145 @@
+import { isNumber } from "@thi.ng/checks/is-number";
+import { illegalArgs } from "@thi.ng/errors/illegal-arguments";
+import { cossin } from "@thi.ng/math/angle";
+import { mix } from "@thi.ng/math/mix";
+import { jitter } from "@thi.ng/vectors/jitter";
+import { madd2 } from "@thi.ng/vectors/madd";
+import { maddN2 } from "@thi.ng/vectors/maddn";
+import { MOVE } from "./commands.js";
+import { dip } from "./dip.js";
+/**
+ * Higher order {@link DrawCommand} sequence generator for working with paint
+ * brushes. Takes an config object describing a linear paint palette layout and
+ * behavior options for dipping the brush. Returns a function which takes a
+ * palette slot index as argument and returns a command sequence moving the
+ * plotter to the palette slot and dipping the brush to refill.
+ *
+ * @remarks
+ * Can be used with
+ * [InterleaveOpts](https://docs.thi.ng/umbrella/geom-axidraw/interfaces/InterleaveOpts.html)
+ * of https://thi.ng/geom-axidraw.
+ *
+ * Also see:
+ * - {@link LinearPaletteOpts} for options
+ * - {@link radialPalette} for circular/elliptical palette layouts
+ * - {@link dip} (used internally for dipping sequence)
+ *
+ * @example
+ * ```ts
+ * import { points } from "@thi.ng/geom";
+ * import { asAxiDraw } from "@thi.ng/geom-axidraw";
+ * import { repeatedly } from "@thi.ng/transducers";
+ * import { randMinMax2 } from "@thi.ng/vectors";
+ *
+ * // configure palette
+ * const palette = linearPalette({
+ *   // first palette slot is near the world origin (slight offset)
+ *   pos: [2, 0],
+ *   // palette has 5 paint slots
+ *   num: 5,
+ *   // each slot 40mm separation along Y-axis
+ *   // (needs to be measured/determined manually)
+ *   step: [0, 40],
+ *   // 2mm jitter radius (to not always move to exact same position)
+ *   jitter: 2,
+ *   // dip brush 3x each time
+ *   repeat: 3,
+ * });
+ *
+ * // investigate command sequence for requesting slot #1
+ * palette(1)
+ * // [
+ * //   [ "M", [ 0.8949, 41.6697 ], 1 ],
+ * //   [ "d", undefined, undefined ],
+ * //   [ "u", undefined, undefined ],
+ * //   [ "d", undefined, undefined ],
+ * //   [ "u", undefined, undefined ],
+ * //   [ "d", undefined, undefined ],
+ * //   [ "u", undefined, undefined ]
+ * // ]
+ *
+ * // define point cloud of 100 random points
+ * // using a random palette slot each time (for each refill)
+ * // assign axidraw-specific attribs to refill brush every 10 dots
+ * const cloud = points(
+ *   [...repeatedly(() => randMinMax2([], [10, 10], [190, 190]), 100)],
+ *   {
+ *     __axi: {
+ *       interleave: {
+ *         num: 10,
+ *         commands: () => palette((Math.random() * 5) | 0)
+ *       }
+ *     }
+ *   }
+ * );
+ *
+ * // AxiDraw setup
+ * const axi = new AxiDraw();
+ * ...
+ *
+ * // convert geometry into axidraw commands and send to plotter
+ * axi.draw(asAxiDraw(cloud));
+ * ```
+ *
+ * @param opts
+ */
+export const linearPalette = (opts) => {
+    const $opts = {
+        pos: [0, 0],
+        repeat: 1,
+        jitter: 0,
+        ...opts,
+    };
+    const dipOpts = __dipOpts($opts);
+    return (id) => {
+        if (id < 0 || id >= $opts.num) {
+            illegalArgs(`invalid palette index: ${id}`);
+        }
+        return [
+            MOVE(jitter(null, maddN2([], $opts.step, id, $opts.pos), $opts.jitter)),
+            ...dip($opts.repeat, dipOpts),
+        ];
+    };
+};
+/**
+ * Higher order {@link DrawCommand} sequence generator for working with paint
+ * brushes. Similar to {@link linearPalette}, but for circular or elliptic
+ * palette layouts.
+ *
+ * @remarks
+ * Also see:
+ * - {@link RadialPaletteOpts} for options
+ * - {@link linearPalette} for more details & code example
+ * - {@link dip} (used internally for dipping sequence)
+ *
+ * @param opts
+ */
+export const radialPalette = (opts) => {
+    const $opts = {
+        repeat: 1,
+        jitter: 0,
+        startTheta: 0,
+        endTheta: Math.PI * 2,
+        ...opts,
+    };
+    const radius = isNumber($opts.radius)
+        ? [$opts.radius, $opts.radius]
+        : $opts.radius;
+    const dipOpts = __dipOpts($opts);
+    return (id) => {
+        if (id < 0 || id >= $opts.num) {
+            illegalArgs(`invalid palette index: ${id}`);
+        }
+        return [
+            MOVE(jitter(null, madd2(null, cossin(mix($opts.startTheta, $opts.endTheta, id / $opts.num)), radius, $opts.pos), $opts.jitter)),
+            ...dip($opts.repeat, dipOpts),
+        ];
+    };
+};
+const __dipOpts = (opts) => ({
+    down: opts.down,
+    downDelay: opts.downDelay,
+    up: opts.up,
+    upDelay: opts.upDelay,
+    commands: opts.commands,
+});