@thi.ng/axidraw 0.5.8 → 1.1.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,70 @@ 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
+
+- add/update command presets ([610f873](https://github.com/thi-ng/umbrella/commit/610f873))
+- BREAKING CHANGE: update DrawCommands and cmd presets
+  - update MoveXYCommand to use `"M"`
+  - add MoveRelCommand (using `"m"`)
+  - add/update AxiDraw.moveTo()/moveRelative()
+  - migrate command presets to commands.ts
+  - refactor parametric command type presets as functions:
+    -  PEN(), UP(), DOWN(), MOVE(), MOVE_REL(), WAIT(), COMMENT()
+  - add DIP() command sequence gen
+
+#### 🚀 Features
+
+- add command fns, add COMMENT cmd ([0d64b55](https://github.com/thi-ng/umbrella/commit/0d64b55))
+  - add MOVE(), WAIT(), COMMENT()
+  - add CommentCommand
+  - update AxiDraw.draw() to log comments
+- add disconnect() ([af93177](https://github.com/thi-ng/umbrella/commit/af93177))
+  - add disconnect() for ISerial & AxiDraw
+  - update MockSerial impl
+- update commands, docs & pkg exports ([1324cb8](https://github.com/thi-ng/umbrella/commit/1324cb8))
+- update dip(), update imports. restructure /src ([b108760](https://github.com/thi-ng/umbrella/commit/b108760))
+  - add DipOpts, extend dip() functionality
+  - move dip() to own file dip.ts
+  - move complete() to commands.ts
+  - move registrationMark() to own file registration.ts
+  - update all imports
+  - update pkg exports map
+
 ## [0.5.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/axidraw@0.5.0) (2023-02-05)
 
 #### 🚀 Features

package/README.md

@@ -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,9 +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)
+  - [Brush & paint palette](#brush--paint-palette)
 - [Authors](#authors)
 - [License](#license)
 
@@ -32,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
@@ -51,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
 
@@ -164,7 +186,7 @@ For Node.js REPL:
 const axidraw = await import("@thi.ng/axidraw");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.15 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.13 KB
 
 ## Dependencies
 
@@ -174,7 +196,9 @@ Package sizes (brotli'd, pre-treeshake): ESM: 2.15 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)
 
@@ -182,6 +206,46 @@ Package sizes (brotli'd, pre-treeshake): ESM: 2.15 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
@@ -257,14 +321,82 @@ 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:
 
-- https://mastodon.thi.ng/@toxi/109490174709589253
-- https://mastodon.thi.ng/@toxi/109473655772673067
-- https://mastodon.thi.ng/@toxi/109474947869078797
-- https://mastodon.thi.ng/@toxi/109483553358349473
-- https://mastodon.thi.ng/@toxi/109570540391689321
-- https://mastodon.thi.ng/@toxi/109586780630493994
+- [Project announcement](https://mastodon.thi.ng/@toxi/109490174709589253)
+- [Geometry conversion basics](https://mastodon.thi.ng/@toxi/109473655772673067)
+- [Shape group conversion and stippling](https://mastodon.thi.ng/@toxi/109474947869078797)
+- [Per-shape & on-the-fly polyline clipping](https://mastodon.thi.ng/@toxi/109483553358349473)
+- [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...
 
 ## Authors

package/api.d.ts

@@ -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"];
@@ -23,10 +24,25 @@ export type PenUpDownCommand = ["u" | "d", number?, number?];
  * Move to abs pos (in worldspace coords, default mm), optional speed factor
  * (default: 1)
  */
-export type MoveXYCommand = ["m", ReadonlyVec, number?];
+export type MoveXYCommand = ["M", ReadonlyVec, number?];
+/**
+ * Move to **relative** pos (based on curr plotter position, im worldspace
+ * units, default mm), optional speed factor (default: 1)
+ */
+export type MoveRelCommand = ["m", ReadonlyVec, number?];
 /** Explicit delay (in ms) */
 export type WaitCommand = ["w", number];
-export type DrawCommand = StartCommand | StopCommand | HomeCommand | ResetCommand | MotorCommand | PenConfigCommand | PenUpDownCommand | MoveXYCommand | WaitCommand;
+/** Ignored, but will be logged (if logging enabled) */
+export type CommentCommand = ["comment", string];
+/**
+ * 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}.
  */
@@ -58,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.
@@ -125,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.
      *
@@ -137,15 +191,6 @@ export interface AxiDrawOpts {
      */
     sigint: boolean;
 }
-export declare const START: StartCommand;
-export declare const STOP: StopCommand;
-export declare const HOME: HomeCommand;
-export declare const RESET: ResetCommand;
-export declare const PEN: PenConfigCommand;
-export declare const UP: PenUpDownCommand;
-export declare const DOWN: PenUpDownCommand;
-export declare const ON: MotorCommand;
-export declare const OFF: MotorCommand;
 /**
  * FSM state enum for (interactive) control for processing of drawing commands.
  * See {@link AxiDraw.draw} and {@link AxiDrawControl} for details.
@@ -245,6 +290,7 @@ export interface SerialConnection {
     ctor(path: string, baudRate: number): ISerial;
 }
 export interface ISerial {
+    close(): void;
     /**
      * Writes given string to the port.
      *

package/api.js

@@ -1,12 +1,3 @@
-export const START = ["start"];
-export const STOP = ["stop"];
-export const HOME = ["home"];
-export const RESET = ["reset"];
-export const PEN = ["pen"];
-export const UP = ["u"];
-export const DOWN = ["d"];
-export const ON = ["on"];
-export const OFF = ["off"];
 /**
  * FSM state enum for (interactive) control for processing of drawing commands.
  * See {@link AxiDraw.draw} and {@link AxiDrawControl} for details.

package/axidraw.d.ts

@@ -1,5 +1,5 @@
 import type { IReset } from "@thi.ng/api";
-import { ReadonlyVec, Vec } from "@thi.ng/vectors";
+import { ReadonlyVec, Vec, VecPair } from "@thi.ng/vectors/api";
 import { AxiDrawOpts, DrawCommand, ISerial, Metrics } from "./api.js";
 export declare const DEFAULT_OPTS: AxiDrawOpts;
 export declare class AxiDraw implements IReset {
@@ -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;
     /**
@@ -25,6 +29,7 @@ export declare class AxiDraw implements IReset {
      * @param path
      */
     connect(path?: string | RegExp): Promise<void>;
+    disconnect(): void;
     /**
      * Async function. Converts sequence of {@link DrawCommand}s into actual EBB
      * commands and sends them via configured serial port to the AxiDraw. If
@@ -68,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;
@@ -85,12 +92,21 @@ export declare class AxiDraw implements IReset {
      * @param tempo
      */
     moveTo(p: ReadonlyVec, tempo?: number): number[];
+    /**
+     * Similar to {@link AxiDraw.moveTo}, but using **relative** coordinates.
+     *
+     * @param delta
+     * @param tempo
+     */
+    moveRelative(delta: ReadonlyVec, tempo?: number): number[];
     /**
      * 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[];
     /**
      * Sends pen up/down config
      *