@thi.ng/geom-axidraw 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Change Log
+
+- **Last updated**: 2022-12-10T14:04:38Z
+- **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
+
+All notable changes to this project will be documented in this file.
+See [Conventional Commits](https://conventionalcommits.org/) for commit guidelines.
+
+**Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
+and/or version bumps of transitive dependencies.
+
+## [0.1.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom-axidraw@0.1.0) (2022-12-10)
+
+#### 🚀 Features
+
+- import as new pkg ([87e4945](https://github.com/thi-ng/umbrella/commit/87e4945))
+- add shape/point ordering support ([58b3b5d](https://github.com/thi-ng/umbrella/commit/58b3b5d))
+  - add Point/ShapeOrdering types
+  - add pointsByProximity()/shapesByProximity() HOF ordering fns
+  - add AxiDrawAttribs.sort attrib
+  - add/update doc strings
+  - update deps
+- add/update AsAxiDrawOpts ([24f8abe](https://github.com/thi-ng/umbrella/commit/24f8abe))
+  - update points & polyline handling
+- add pointsByNearestNeighbor() ordering ([d1ebd21](https://github.com/thi-ng/umbrella/commit/d1ebd21))
+  - use pointsByNearestNeighbor() as default for point clouds
+    - new method is 25%-30% faster than pointsByProximity()
+  - update PointOrdering/ShapeOrdering return types
+  - update doc strings
+  - update deps
+
+#### ♻️ Refactoring
+
+- internal restructure, add docs ([443c12c](https://github.com/thi-ng/umbrella/commit/443c12c))

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "{}"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright {yyyy} {name of copyright owner}
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,257 @@
+<!-- This file is generated - DO NOT EDIT! -->
+
+# ![geom-axidraw](https://media.thi.ng/umbrella/banners-20220914/thing-geom-axidraw.svg?97576ad9)
+
+[![npm version](https://img.shields.io/npm/v/@thi.ng/geom-axidraw.svg)](https://www.npmjs.com/package/@thi.ng/geom-axidraw)
+![npm downloads](https://img.shields.io/npm/dm/@thi.ng/geom-axidraw.svg)
+[![Twitter Follow](https://img.shields.io/twitter/follow/thing_umbrella.svg?style=flat-square&label=twitter)](https://twitter.com/thing_umbrella)
+
+This project is part of the
+[@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo.
+
+- [About](#about)
+  - [Supported shape types](#supported-shape-types)
+  - [AxiDraw specific shape attributes](#axidraw-specific-shape-attributes)
+    - [Shape interpolation/resampling](#shape-interpolationresampling)
+  - [Draw order](#draw-order)
+  - [Basic usage & examples](#basic-usage--examples)
+    - [Interpolated polygons](#interpolated-polygons)
+  - [Clipping](#clipping)
+- [Status](#status)
+- [Related packages](#related-packages)
+- [Installation](#installation)
+- [Dependencies](#dependencies)
+- [API](#api)
+- [Authors](#authors)
+- [License](#license)
+
+## 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).
+
+This package only deals with the conversion aspects. The
+[@thi.ng/axidraw](https://github.com/thi-ng/umbrella/blob/develop/packages/axidraw)
+is responsible for the actual plotter output...
+
+### Supported shape types
+
+| Shape type | Remarks                                         |
+|------------|-------------------------------------------------|
+| arc        | elliptic arc<sup>(1)</sup>                      |
+| circle     | circle<sup>(1)</sup>                            |
+| cubic      | cubic bezier segment<sup>(1)</sup>              |
+| ellipse    | ellipse<sup>(1)</sup>                           |
+| group      | shape group (possibly nested)                   |
+| line       | line segment<sup>(2)</sup>                      |
+| path       | single outline only, no holes                   |
+| points     | point cloud (stippling)                         |
+| polyline   | polyline (any number of vertices)<sup>(2)</sup> |
+| polygon    | simple polygon, no holes<sup>(2)</sup>          |
+| quad       | arbitrary 4-gon<sup>(2)</sup>                   |
+| quadratic  | quadratic bezier segment<sup>(1)</sup>          |
+| rect       | axis aligned rectangle<sup>(2)</sup>            |
+| triangle   | triangle<sup>(2)</sup>                          |
+
+- <sup>(1)</sup> always interpolated/sampled
+- <sup>(2)</sup> only interpolated if forced via attrib
+
+### AxiDraw specific shape attributes
+
+All
+[thi.ng/geom](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/)
+shape types have support for arbitrary attributes. Different support packages
+can then utilize these attribs to customize usage or behaviors. In this case,
+any package-specific attribs must be stored under the `__axi` key:
+
+- `clip`: Optional clip polygon vertices (if given only the parts of strokes
+  inside that polygon will be plotted)
+- `delayDown`: Shape specific delay (in ms), i.e. initial hold time for the
+  stroke or when stippling...
+- `delayUp`: Delay for pen up command at the end this particular
+  shape/polyline/point.
+- `down`: Pen down position (in \%) for this particular shape/polyline. Will be
+  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.
+- `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.
+
+```ts
+// a circle which will be plotted at only 10% of the normal speed
+circle(100, { __axi: { speed: 0.1 } })
+```
+
+#### Shape interpolation/resampling
+
+Since many of the supported shapes are not inherently vertex-based, their
+boundaries/outlines need to be sampled when they are being converted to
+polylines. Therefore, in addition to the above attributes, the thi.ng/geom
+package itself also makes use of the `__samples` attribute to control the
+re-sampling of individual shapes. Please see the following links for more
+details and supported options:
+
+- [`SamplingOpts`](https://docs.thi.ng/umbrella/geom-api/interfaces/SamplingOpts.html)
+- [`vertices()`](https://docs.thi.ng/umbrella/geom/functions/vertices.html)
+
+### Draw order
+
+As mentioned above, the default draw order for shapes within a group is order of
+appearance. For point clouds, the {@link pointsByNearestNeighbor} ordering
+function is used by default, which attempts to minimize travel distance between
+points.
+
+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)
+- [`pointsByProximity()`](https://docs.thi.ng/umbrella/geom-axidraw/functions/pointsByProximity.html)
+- [`shapesByProximity()`](https://docs.thi.ng/umbrella/geom-axidraw/functions/shapesByProximity.html)
+
+### Basic usage & examples
+
+The main function of this package is the polymorphic function
+[`asAxiDraw()`](https://docs.thi.ng/umbrella/geom-axidraw/functions/asAxiDraw.html),
+which converts any of the supported shape types into an iterable of
+[thi.ng/axidraw](https://github.com/thi-ng/umbrella/blob/develop/packages/axidraw)
+drawing commands. This conversion happens **semi-lazily** (via generator
+functions) to minimize memory usage and spread out the computational load of the
+conversions.
+
+The below example can be directly launched via `node cubics.js` (obviously
+provided you have an AxiDraw connected and all listed packages installed):
+
+#### Interpolated polygons
+
+(Result: https://mastodon.thi.ng/@toxi/109473655772673067)
+
+```ts tangle:export/readme-cubics.ts
+import { AxiDraw } from "@thi.ng/axidraw";
+import { asCubic, group, pathFromCubics, star } from "@thi.ng/geom";
+import { asAxiDraw } from "@thi.ng/geom-axidraw";
+import { map, range } from "@thi.ng/transducers";
+
+(async () => {
+	// create group of bezier-interpolated star polygons,
+	// with each path using a slightly different configuration
+	const geo = group({ translate: [100, 100] }, [
+		...map(
+			(t) =>
+				pathFromCubics(
+					asCubic(star(90, 6, [t, 1]), {
+						breakPoints: true,
+						scale: 0.66,
+					})
+				),
+			range(0.3, 1.01, 0.05)
+		),
+	]);
+
+	// connect to plotter
+	const axi = new AxiDraw();
+	await axi.connect();
+	// convert geometry to drawing commands & send to plotter
+	await axi.draw(asAxiDraw(geo, { samples: 40 }));
+})();
+```
+
+### Clipping
+
+(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 { map, range } from "@thi.ng/transducers";
+
+(async () => {
+	const origin = [100, 100];
+	const radius = 50;
+	const boundary = starWithCentroid(origin, radius, 5, [1, 0.45], { __axi: { speed: 0.25 } });
+	// group of concentric circles using boundary as clip polygon
+	const geo = group({}, [
+		boundary,
+		group({ __samples: 40, __axi: { clip: vertices(boundary) } }, [
+			...map((r) => circle(origin, r), range(2, radius, 2)),
+		]),
+	]);
+	const axi = new AxiDraw();
+	await axi.connect();
+	await axi.draw(asAxiDraw(geo));
+})();
+```
+
+## Status
+
+**ALPHA** - bleeding edge / work-in-progress
+
+[Search or submit any issues for this package](https://github.com/thi-ng/umbrella/issues?q=%5Bgeom-axidraw%5D+in%3Atitle)
+
+## Related packages
+
+- [@thi.ng/axidraw](https://github.com/thi-ng/umbrella/tree/develop/packages/axidraw) - Minimal AxiDraw plotter/drawing machine controller for Node.js
+
+## Installation
+
+```bash
+yarn add @thi.ng/geom-axidraw
+```
+
+ES module import:
+
+```html
+<script type="module" src="https://cdn.skypack.dev/@thi.ng/geom-axidraw"></script>
+```
+
+[Skypack documentation](https://docs.skypack.dev/)
+
+For Node.js REPL:
+
+```text
+# with flag only for < v16
+node --experimental-repl-await
+
+> const geomAxidraw = await import("@thi.ng/geom-axidraw");
+```
+
+Package sizes (brotli'd, pre-treeshake): ESM: 856 bytes
+
+## Dependencies
+
+- [@thi.ng/api](https://github.com/thi-ng/umbrella/tree/develop/packages/api)
+- [@thi.ng/arrays](https://github.com/thi-ng/umbrella/tree/develop/packages/arrays)
+- [@thi.ng/axidraw](https://github.com/thi-ng/umbrella/tree/develop/packages/axidraw)
+- [@thi.ng/compare](https://github.com/thi-ng/umbrella/tree/develop/packages/compare)
+- [@thi.ng/defmulti](https://github.com/thi-ng/umbrella/tree/develop/packages/defmulti)
+- [@thi.ng/geom](https://github.com/thi-ng/umbrella/tree/develop/packages/geom)
+- [@thi.ng/geom-accel](https://github.com/thi-ng/umbrella/tree/develop/packages/geom-accel)
+- [@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/vectors](https://github.com/thi-ng/umbrella/tree/develop/packages/vectors)
+
+## API
+
+[Generated API docs](https://docs.thi.ng/umbrella/geom-axidraw/)
+
+TODO
+
+## Authors
+
+Karsten Schmidt
+
+If this project contributes to an academic publication, please cite it as:
+
+```bibtex
+@misc{thing-geom-axidraw,
+  title = "@thi.ng/geom-axidraw",
+  author = "Karsten Schmidt",
+  note = "https://thi.ng/geom-axidraw",
+  year = 2022
+}
+```
+
+## License
+
+&copy; 2022 Karsten Schmidt // Apache Software License 2.0

package/api.d.ts

@@ -0,0 +1,75 @@
+import type { Fn } from "@thi.ng/api";
+import type { IShape, SamplingOpts } from "@thi.ng/geom-api";
+import type { ReadonlyVec } from "@thi.ng/vectors";
+/**
+ * Package-specific shape attributes used to control conversion behavior. MUST
+ * be stored under the `__axi` attribute name.
+ *
+ * @remark
+ * Important: TODO keep this in sync with
+ * [PolylineOpts](https://docs.thi.ng/umbrella/axidraw/interfaces/PolylineOpts.html)
+ *
+ * @example
+ * ```ts
+ * // a circle which will be drawn at 25% speed
+ * circle(100, { __axi: { speed: 0.25 } });
+ * ```
+ */
+export interface AxiDrawAttribs {
+    /**
+     * Clip polygon vertices. See {@link AsAxiDrawOpts.clip}.
+     */
+    clip: ReadonlyVec[];
+    /**
+     * Optional speed factor (multiple of globally configured draw speed).
+     * Depending on pen used, slower speeds might result in thicker strokes.
+     */
+    speed: number;
+    /**
+     * Optional shape specific delay (in ms), i.e. initial hold time for the
+     * stroke or when stippling...
+     */
+    delayDown: number;
+    /**
+     * Delay for pen up command at the end this particular shape/polyline/point.
+     */
+    delayUp: number;
+    /**
+     * Pen down position (%) for this particular shape/polyline. Will be reset
+     * to globally configured default at the end of the shape.
+     */
+    down: number;
+    /**
+     * 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.
+     *
+     * @remarks
+     * Currently available implementations:
+     *
+     * - {@link pointsByNearestNeighbor} (for `points()`, default)
+     * - {@link pointsByProximity} (for `points()`)
+     * - {@link shapesByProximity} (for `group()`)
+     */
+    sort: PointOrdering | ShapeOrdering;
+}
+export interface AsAxiDrawOpts {
+    /**
+     * Global options for sampling non-polygonal shape. Shapes can also provide
+     * a `__samples` attribute to override these global options.
+     *
+     * @remarks
+     * References:
+     * - https://docs.thi.ng/umbrella/geom-api/interfaces/SamplingOpts.html
+     * - https://docs.thi.ng/umbrella/geom/functions/vertices.html
+     */
+    samples: number | Partial<SamplingOpts>;
+    /**
+     * Clip polygon vertices. Can also be provided per-shape as
+     * {@link AxiDrawAttribs.clip} (i.e. as part of a shape's `__axi` attrib).
+     */
+    clip: ReadonlyVec[];
+}
+export declare type PointOrdering = Fn<ReadonlyVec[], Iterable<ReadonlyVec>>;
+export declare type ShapeOrdering = Fn<IShape[], Iterable<IShape>>;
+//# sourceMappingURL=api.d.ts.map

package/api.js

@@ -0,0 +1 @@
+export {};

package/as-axidraw.d.ts

@@ -0,0 +1,45 @@
+import { 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";
+/**
+ * Lazily converts given shape (or group) into an iterable of thi.ng/axidraw
+ * drawing commands, using optionally provided config options.
+ *
+ * @remarks
+ * The provided conversion options can (and will) be overridden by a shape's
+ * `__axi` attribute. See {@link AxiDrawAttribs} for details.
+ *
+ * Currently supported shape types (at least all types which are supported by
+ * the
+ * [`asPolyline()`](https://docs.thi.ng/umbrella/geom/functions/asPolyline.html)
+ * function):
+ *
+ * - arc
+ * - circle
+ * - cubic
+ * - ellipse
+ * - group
+ * - line
+ * - path
+ * - points
+ * - polygon
+ * - polyline
+ * - quad
+ * - quadratic
+ * - rect
+ * - triangle
+ *
+ * @example
+ * ```ts
+ * [...asAxiDraw(circle(100), { samples: 100 })]
+ * [
+ *   [ 'm', [ 10, 0 ] ],
+ *   [ 'd' ],
+ *   [ 'm', [ 9.980267284282716, 0.6279051952931337 ], undefined ],
+ *   ...
+ * ]
+ * ```
+ */
+export declare const asAxiDraw: MultiFn1O<IShape, Partial<AsAxiDrawOpts>, Iterable<DrawCommand>>;
+//# sourceMappingURL=as-axidraw.d.ts.map

package/as-axidraw.js

@@ -0,0 +1,120 @@
+import { UP } from "@thi.ng/axidraw/api";
+import { polyline } from "@thi.ng/axidraw/polyline";
+import { defmulti } from "@thi.ng/defmulti/defmulti";
+import { clipPolylinePoly } from "@thi.ng/geom-clip-line/clip-poly";
+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 { pointsByNearestNeighbor } from "./sort.js";
+/**
+ * Lazily converts given shape (or group) into an iterable of thi.ng/axidraw
+ * drawing commands, using optionally provided config options.
+ *
+ * @remarks
+ * The provided conversion options can (and will) be overridden by a shape's
+ * `__axi` attribute. See {@link AxiDrawAttribs} for details.
+ *
+ * Currently supported shape types (at least all types which are supported by
+ * the
+ * [`asPolyline()`](https://docs.thi.ng/umbrella/geom/functions/asPolyline.html)
+ * function):
+ *
+ * - arc
+ * - circle
+ * - cubic
+ * - ellipse
+ * - group
+ * - line
+ * - path
+ * - points
+ * - polygon
+ * - polyline
+ * - quad
+ * - quadratic
+ * - rect
+ * - triangle
+ *
+ * @example
+ * ```ts
+ * [...asAxiDraw(circle(100), { samples: 100 })]
+ * [
+ *   [ 'm', [ 10, 0 ] ],
+ *   [ 'd' ],
+ *   [ 'm', [ 9.980267284282716, 0.6279051952931337 ], undefined ],
+ *   ...
+ * ]
+ * ```
+ */
+export const asAxiDraw = defmulti(__dispatch, {
+    arc: "circle",
+    cubic: "circle",
+    ellipse: "circle",
+    line: "polyline",
+    path: "circle",
+    poly: "polyline",
+    quad: "polyline",
+    quadratic: "circle",
+    rect: "polyline",
+    tri: "polyline",
+}, {
+    points: ($, opts) => __points(applyTransforms($).points, $.attribs, opts),
+    // used for all shapes which need to be sampled
+    circle: ($, opts) => __polyline(asPolyline(applyTransforms($), opts?.samples).points, $.attribs, opts),
+    // ignore sample opts for polyline & other polygonal shapes
+    // i.e. use points verbatim
+    polyline: ($, opts) => __polyline(asPolyline(applyTransforms($)).points, $.attribs, opts),
+    group: ($, opts) => __group($, opts),
+});
+function* __group($, opts) {
+    const { sort } = __axiAttribs($.attribs);
+    const children = sort ? sort($.children) : $.children;
+    for (let child of children) {
+        const shape = applyTransforms(child);
+        shape.attribs = {
+            ...shape.attribs,
+            ...$.attribs,
+        };
+        yield* asAxiDraw(shape, opts);
+    }
+}
+function* __points(pts, attribs, opts) {
+    if (!pts.length)
+        return;
+    const { clip, delayDown, delayUp, down, speed, sort } = {
+        sort: pointsByNearestNeighbor(),
+        ...__axiAttribs(attribs),
+    };
+    const clipPts = clip || opts?.clip;
+    if (clipPts) {
+        pts = pts.filter((p) => !!pointInPolygon2(p, clipPts));
+        if (!pts.length)
+            return;
+    }
+    yield UP;
+    if (down != undefined)
+        yield ["pen", down];
+    for (let p of sort ? sort(pts) : pts) {
+        yield* [
+            ["m", p, speed],
+            ["d", delayDown],
+            ["u", delayUp],
+        ];
+    }
+    if (down != undefined)
+        yield ["pen"];
+}
+function* __polyline(pts, attribs, opts) {
+    if (!pts.length)
+        return;
+    const { clip, down, delayDown, delayUp, speed } = __axiAttribs(attribs);
+    const clipPts = clip || opts?.clip;
+    const chunks = clipPts ? clipPolylinePoly(pts, clipPts) : [pts];
+    if (!chunks.length)
+        return;
+    for (let chunk of chunks) {
+        yield* polyline(chunk, { down, delayDown, delayUp, speed });
+    }
+}
+/** @internal */
+const __axiAttribs = (attribs) => attribs ? attribs.__axi || {} : {};

package/index.d.ts

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

package/index.js

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

package/package.json

@@ -0,0 +1,121 @@
+{
+  "name": "@thi.ng/geom-axidraw",
+  "version": "0.1.0",
+  "description": "Conversion and preparation of thi.ng/geom shapes & shape groups to AxiDraw pen plotter draw commands",
+  "type": "module",
+  "module": "./index.js",
+  "typings": "./index.d.ts",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/thi-ng/umbrella.git"
+  },
+  "homepage": "https://github.com/thi-ng/umbrella/tree/master/packages/geom-axidraw#readme",
+  "funding": [
+    {
+      "type": "github",
+      "url": "https://github.com/sponsors/postspectacular"
+    },
+    {
+      "type": "patreon",
+      "url": "https://patreon.com/thing_umbrella"
+    }
+  ],
+  "author": "Karsten Schmidt <k+npm@thi.ng>",
+  "license": "Apache-2.0",
+  "scripts": {
+    "build": "yarn clean && tsc --declaration",
+    "clean": "rimraf '*.js' '*.d.ts' '*.map' doc",
+    "doc": "typedoc --excludePrivate --excludeInternal --out doc src/index.ts",
+    "doc:ae": "mkdir -p .ae/doc .ae/temp && api-extractor run --local --verbose",
+    "doc:readme": "yarn doc:stats && tools:readme",
+    "doc:stats": "tools:module-stats",
+    "pub": "yarn npm publish --access public",
+    "test": "testament test"
+  },
+  "dependencies": {
+    "@thi.ng/api": "^8.5.1",
+    "@thi.ng/arrays": "^2.4.4",
+    "@thi.ng/axidraw": "^0.2.0",
+    "@thi.ng/compare": "^2.1.18",
+    "@thi.ng/defmulti": "^2.1.23",
+    "@thi.ng/geom": "^4.0.0",
+    "@thi.ng/geom-accel": "^3.2.28",
+    "@thi.ng/geom-api": "^3.3.20",
+    "@thi.ng/geom-clip-line": "^2.2.0",
+    "@thi.ng/geom-isec": "^2.1.37",
+    "@thi.ng/vectors": "^7.5.26"
+  },
+  "devDependencies": {
+    "@microsoft/api-extractor": "^7.33.5",
+    "@thi.ng/testament": "^0.3.6",
+    "rimraf": "^3.0.2",
+    "tools": "^0.0.1",
+    "typedoc": "^0.23.20",
+    "typescript": "^4.8.4"
+  },
+  "keywords": [
+    "2d",
+    "axidraw",
+    "arc",
+    "bezier",
+    "circle",
+    "cubic",
+    "curve",
+    "ellipse",
+    "clipping",
+    "conversion",
+    "geometry",
+    "group",
+    "iterator",
+    "penplotter",
+    "path",
+    "points",
+    "polygon",
+    "polyline",
+    "polymorphic",
+    "quadratic",
+    "sample",
+    "shape",
+    "sort",
+    "triangle",
+    "typescript"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "browser": {
+    "process": false,
+    "setTimeout": false
+  },
+  "engines": {
+    "node": ">=14"
+  },
+  "files": [
+    "./*.js",
+    "./*.d.ts"
+  ],
+  "exports": {
+    ".": {
+      "default": "./index.js"
+    },
+    "./api": {
+      "default": "./api.js"
+    },
+    "./as-axidraw": {
+      "default": "./as-axidraw.js"
+    },
+    "./sort": {
+      "default": "./sort.js"
+    }
+  },
+  "thi.ng": {
+    "parent": "@thi.ng/geom",
+    "related": [
+      "axidraw"
+    ],
+    "status": "alpha",
+    "year": 2022
+  },
+  "gitHead": "5178ea1d7f4b2de86cf5101bdd73f6567518c0bd\n"
+}

package/sort.d.ts

@@ -0,0 +1,31 @@
+import { ReadonlyVec } from "@thi.ng/vectors/api";
+import type { PointOrdering, ShapeOrdering } from "./api.js";
+/**
+ * Higher order point ordering fn. Lazily sorts points by nearest neighbor
+ * distance, starting selection of first point based on given `ref` point
+ * (default: [0, 0]).
+ *
+ * @remarks
+ * Internally uses a
+ * [`KdTreeSet`](https://docs.thi.ng/umbrella/geom-accel/classes/KdTreeSet.html)
+ * to index all points and then successively perform efficient nearest neighbor
+ * searches (always w.r.t the most recent result point).
+ *
+ * @param ref
+ */
+export declare const pointsByNearestNeighbor: (ref?: ReadonlyVec) => PointOrdering;
+/**
+ * Higher order point ordering fn. Sorts points by proximity to given `ref` point
+ * (default: [0, 0]).
+ *
+ * @param ref
+ */
+export declare const pointsByProximity: (ref?: ReadonlyVec) => PointOrdering;
+/**
+ * Higher order shape sorting fn. Sorts shapes by their centroid's proximity to
+ * given `ref` point (default: [0, 0]).
+ *
+ * @param ref
+ */
+export declare const shapesByProximity: (ref?: ReadonlyVec) => ShapeOrdering;
+//# sourceMappingURL=sort.d.ts.map

package/sort.js

@@ -0,0 +1,45 @@
+import { sortByCachedKey } from "@thi.ng/arrays/sort-cached";
+import { compareNumAsc } from "@thi.ng/compare/numeric";
+import { KdTreeSet } from "@thi.ng/geom-accel/kd-tree-set";
+import { centroid } from "@thi.ng/geom/centroid";
+import { ZERO2 } from "@thi.ng/vectors/api";
+import { distSq2 } from "@thi.ng/vectors/distsq";
+/**
+ * Higher order point ordering fn. Lazily sorts points by nearest neighbor
+ * distance, starting selection of first point based on given `ref` point
+ * (default: [0, 0]).
+ *
+ * @remarks
+ * Internally uses a
+ * [`KdTreeSet`](https://docs.thi.ng/umbrella/geom-accel/classes/KdTreeSet.html)
+ * to index all points and then successively perform efficient nearest neighbor
+ * searches (always w.r.t the most recent result point).
+ *
+ * @param ref
+ */
+export const pointsByNearestNeighbor = (ref = ZERO2) => function* (pts) {
+    const index = new KdTreeSet(2, pts);
+    while (index.size) {
+        ref = index.queryKeys(ref, 1e4, 1)[0];
+        index.remove(ref);
+        yield ref;
+    }
+};
+/**
+ * Higher order point ordering fn. Sorts points by proximity to given `ref` point
+ * (default: [0, 0]).
+ *
+ * @param ref
+ */
+export const pointsByProximity = (ref = ZERO2) => (pts) => {
+    return sortByCachedKey(pts.slice(), (p) => distSq2(p, ref), compareNumAsc);
+};
+/**
+ * Higher order shape sorting fn. Sorts shapes by their centroid's proximity to
+ * given `ref` point (default: [0, 0]).
+ *
+ * @param ref
+ */
+export const shapesByProximity = (ref = ZERO2) => (shapes) => {
+    return sortByCachedKey(shapes.slice(), (s) => distSq2(centroid(s) || ZERO2, ref), compareNumAsc);
+};