@thi.ng/geom 6.1.9 → 7.0.1

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2024-04-23T07:02:18Z
+- **Last updated**: 2024-05-09T14:25:15Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,119 @@ 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.
 
+### [7.0.1](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom@7.0.1) (2024-05-09)
+
+#### 🩹 Bug fixes
+
+- update arc() arg defaults, add docs ([cc57a57](https://github.com/thi-ng/umbrella/commit/cc57a57))
+
+# [7.0.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom@7.0.0) (2024-05-08)
+
+#### 🛑 Breaking changes
+
+- update Path to support sub-paths (holes), update impls ([#464](https://github.com/thi-ng/umbrella/issues/464)) ([9329d27](https://github.com/thi-ng/umbrella/commit/9329d27))
+- BREAKING CHANGE: update path related ctors & functions
+  - add `subPaths` argument for Path ctor/factory fn
+  - rename `Path.add()` => `Path.addSegments()`
+  - add `Path.addSubPaths()`
+  - update `Path.toHiccup()` to include sub-paths
+  - update `pathFromSvg()` to always return a single path only
+    - sub-paths are included in main path now
+  - update impls for following ops to also process sub-paths:
+    - bounds()
+    - rotate()
+    - scale()
+    - simplify()
+    - translate()
+    - transform()
+    - transformVertices()
+- update asPolyline(), add support for multiple boundaries ([#464](https://github.com/thi-ng/umbrella/issues/464)) ([0616b96](https://github.com/thi-ng/umbrella/commit/0616b96))
+- BREAKING CHANGE: update asPolygon() to return array of polylines
+  - add/update impls for complexpoly & path to produce multiple results
+  - update other internal callsites
+  - update tests
+- update `Path` closing logic ([ce3a922](https://github.com/thi-ng/umbrella/commit/ce3a922))
+- BREAKING CHANGE: update `Path` closing logic, `Path.closed` now a readonly property
+  - add `Path.closed()` getter
+  - add `Path.close()` to add a `Z`-type segment, check if not closed already
+  - update `Path.addSegments()` to check each segment, throw error if path already closed
+  - refactor `PathBuilder.closePath()`
+- add asPolygon() support for complexpoly & path ([e3c9f20](https://github.com/thi-ng/umbrella/commit/e3c9f20))
+- BREAKING CHANGE: update asPolygon() to return array of polygons (rather than single only)
+  - add support for complexpoly & path (incl. sub-shapes, holes)
+  - refactor internal call sites
+- update asPath(), add AsPathOpts ([ef0ebdf](https://github.com/thi-ng/umbrella/commit/ef0ebdf))
+- BREAKING CHANGE: update asPath() args, add AsPathOpts as 2nd arg
+  - add option for using only linear path segments (no cubics)
+  - update impls for complexpoly & other polygon types
+- update Path & PathBuilder.close() ([b2134c2](https://github.com/thi-ng/umbrella/commit/b2134c2))
+- BREAKING CHANGE: rename `PathBuilder.closePath()` => `PathBuilder.close()`
+  - update `Path.close()` to return path itself
+- rewrite roundedRect() to allow individual corner radii ([a4817aa](https://github.com/thi-ng/umbrella/commit/a4817aa))
+- BREAKING CHANGE: update roundedRect() radius handling to allow individual corner radii
+  - update docs
+  - add tests
+
+#### 🚀 Features
+
+- initial import ComplexPolygon & impls ([#464](https://github.com/thi-ng/umbrella/issues/464)) ([ded007c](https://github.com/thi-ng/umbrella/commit/ded007c))
+  - add complexPolygon() factory fn
+  - add bounds() & centroid() impls
+- add ops for complex polygons ([#464](https://github.com/thi-ng/umbrella/issues/464)) ([35ce854](https://github.com/thi-ng/umbrella/commit/35ce854))
+  - add implementations for:
+    - arcLength()
+    - area()
+    - asPath()
+    - closestPoint()
+    - convexHull()
+    - edges()
+    - flip()
+    - pointInside()
+    - resample()
+    - rotate()
+    - scale()
+    - simplify()
+    - subdivCurve()
+    - transform()
+    - transformVertices()
+    - translate()
+    - vertices()
+  - add tests
+- add proximity() ([5d5951c](https://github.com/thi-ng/umbrella/commit/5d5951c))
+- update `vertices()` impl for `Path`, incl. sub-path vertices ([824067f](https://github.com/thi-ng/umbrella/commit/824067f))
+- update simplify() default threshold ([bdba298](https://github.com/thi-ng/umbrella/commit/bdba298))
+- add arcLength() for Path, refactor complexpoly impl ([d133bbe](https://github.com/thi-ng/umbrella/commit/d133bbe))
+- add/update asCubic() impls for complex poly & path ([7f9e927](https://github.com/thi-ng/umbrella/commit/7f9e927))
+- update pathFromCubics() to auto-create sub-paths if needed ([1170e45](https://github.com/thi-ng/umbrella/commit/1170e45))
+- add closestPoint() impl for Path ([f0cf2f1](https://github.com/thi-ng/umbrella/commit/f0cf2f1))
+- add pointInside() impl for Polyline ([d10bf43](https://github.com/thi-ng/umbrella/commit/d10bf43))
+- add centroid() & convexHull() impl for Path ([76aa229](https://github.com/thi-ng/umbrella/commit/76aa229))
+- add complexPolygonFromPath() ([cd526f1](https://github.com/thi-ng/umbrella/commit/cd526f1))
+- update PathBuilder.close(), fix attrib handling ([e68d0bc](https://github.com/thi-ng/umbrella/commit/e68d0bc))
+  - only insert closing line segment if needed
+  - copy attribs for each new path
+  - add docs
+- add opt attribs for `pathFromSvg()` ([2da31f6](https://github.com/thi-ng/umbrella/commit/2da31f6))
+  - update docs
+  - add/update tests
+- add scaleWithCenter() ([e328494](https://github.com/thi-ng/umbrella/commit/e328494))
+- add complexpoly & path support for `clipConvex()` ([7665dc1](https://github.com/thi-ng/umbrella/commit/7665dc1))
+
+#### 🩹 Bug fixes
+
+- update vertices() ([2afc05e](https://github.com/thi-ng/umbrella/commit/2afc05e))
+  - update impl for points, poly, polyline to return shallow copy of point array if no opts given
+
+#### ♻️ Refactoring
+
+- update withAttribs(), make new attribs optional ([688e1bf](https://github.com/thi-ng/umbrella/commit/688e1bf))
+- update geom examples (recent API changes) ([f0f5ea7](https://github.com/thi-ng/umbrella/commit/f0f5ea7))
+- update area() impl for Path ([0960817](https://github.com/thi-ng/umbrella/commit/0960817))
+- update/simplify asPath() impls ([cbc71bb](https://github.com/thi-ng/umbrella/commit/cbc71bb))
+- update centroid() for complexpoly ([58ac296](https://github.com/thi-ng/umbrella/commit/58ac296))
+  - re-use migrated fn from [@thi.ng/geom-poly-utils](https://github.com/thi-ng/umbrella/tree/main/packages/geom-poly-utils)
+- update path segment transformations ([88b2c40](https://github.com/thi-ng/umbrella/commit/88b2c40))
+
 ### [6.1.7](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom@6.1.7) (2024-04-20)
 
 #### ♻️ Refactoring

package/README.md

@@ -44,28 +44,29 @@ name](http://thi.ng/geom-clj). All polymorphic operations built on
 The following shape primitives are provided. For many there're multiple ways to
 create them, please check linked sources and/or docs.
 
-| Shape/Form                                                                                            | Description                  | Hiccup support  |
-|-------------------------------------------------------------------------------------------------------|------------------------------|-----------------|
-| [AABB](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/aabb.ts)                     | 3D Axis-aligned bounding box | ✅<sup>(2)</sup> |
-| [Arc](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/arc.ts)                       | 2D elliptic arc              | ✅               |
-| [Circle](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/circle.ts)                 | 2D circle                    | ✅               |
-| [Cubic](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/cubic.ts)                   | nD cubic bezier              | ✅<sup>(1)</sup> |
-| [Ellipse](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/ellipse.ts)               | 2D ellipse                   | ✅               |
-| [Group](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/group.ts)                   | group of 2D shapes           | ✅               |
-| [Line](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/line.ts)                     | 2D line segment              | ✅               |
-| [Path](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/path-builder.ts)             | 2D path                      | ✅               |
-| [Path (from SVG)](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/path-from-svg.ts) | 2D path from SVG `<path>`    | ✅               |
-| [Plane](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/plane.ts)                   | 3D plane                     | ✅<sup>(2)</sup> |
-| [Point cloud](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/points.ts)            | nD point cloud               | ✅<sup>(1)</sup> |
-| [Polygon](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/polygon.ts)               | 2D simple polygon (no holes) | ✅               |
-| [Polyline](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/polyline.ts)             | 2D polyline                  | ✅               |
-| [Quad](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/quad.ts)                     | 2D/3D quad (4-gon)           | ✅<sup>(1)</sup> |
-| [Quadratic](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/quadratic.ts)           | nD quadratic bezier          | ✅<sup>(1)</sup> |
-| [Ray](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/ray.ts)                       | nD ray                       | ✅<sup>(1)</sup> |
-| [Rectangle](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/rect.ts)                | 2D rectangle                 | ✅               |
-| [Sphere](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/sphere.ts)                 | 3D sphere                    | ✅<sup>(2)</sup> |
-| [Text](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/text.ts)                     | Basic stub for text labels   | ✅<sup>(3)</sup> |
-| [Triangle](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/triangle.ts)             | 2D triangle                  | ✅               |
+| Shape/Form                                                                                             | Description                           | Hiccup support  |
+|--------------------------------------------------------------------------------------------------------|---------------------------------------|-----------------|
+| [AABB](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/aabb.ts)                      | 3D Axis-aligned bounding box          | ✅<sup>(2)</sup> |
+| [Arc](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/arc.ts)                        | 2D elliptic arc                       | ✅               |
+| [Circle](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/circle.ts)                  | 2D circle                             | ✅               |
+| [ComplexPolygon](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/complex-polygon.ts) | 2D polygon w/ holes                   | ✅               |
+| [Cubic](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/cubic.ts)                    | nD cubic bezier                       | ✅<sup>(1)</sup> |
+| [Ellipse](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/ellipse.ts)                | 2D ellipse                            | ✅               |
+| [Group](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/group.ts)                    | group of 2D shapes                    | ✅               |
+| [Line](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/line.ts)                      | 2D line segment                       | ✅               |
+| [Path](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/path-builder.ts)              | 2D path (w/ optional holes/sub-paths) | ✅               |
+| [Path (from SVG)](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/path-from-svg.ts)  | 2D path from SVG                      | ✅               |
+| [Plane](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/plane.ts)                    | 3D plane                              | ✅<sup>(2)</sup> |
+| [Point cloud](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/points.ts)             | nD point cloud                        | ✅<sup>(1)</sup> |
+| [Polygon](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/polygon.ts)                | 2D simple polygon (no holes)          | ✅               |
+| [Polyline](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/polyline.ts)              | 2D polyline                           | ✅               |
+| [Quad](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/quad.ts)                      | 2D/3D quad (4-gon)                    | ✅<sup>(1)</sup> |
+| [Quadratic](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/quadratic.ts)            | nD quadratic bezier                   | ✅<sup>(1)</sup> |
+| [Ray](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/ray.ts)                        | nD ray                                | ✅<sup>(1)</sup> |
+| [Rectangle](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/rect.ts)                 | 2D rectangle                          | ✅               |
+| [Sphere](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/sphere.ts)                  | 3D sphere                             | ✅<sup>(2)</sup> |
+| [Text](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/text.ts)                      | Basic stub for text labels            | ✅<sup>(3)</sup> |
+| [Triangle](https://github.com/thi-ng/umbrella/blob/develop/packages/geom/src/triangle.ts)              | 2D triangle                           | ✅               |
 
 - <sup>(1)</sup> valid hiccup format, currently only useable/supported if 2D geometry
 - <sup>(2)</sup> valid hiccup format, currently unused/unsupported elsewhere
@@ -77,9 +78,10 @@ With very few exceptions these all are implementing the [`IToHiccup`
 interface](https://docs.thi.ng/umbrella/api/interfaces/IToHiccup.html) and so
 can be easily converted (via
 [hiccup](https://github.com/thi-ng/umbrella/tree/develop/packages/hiccup)) to a
-variety of other formats. By design, for better flexibility and performance
-reasons, the hiccup flavor used by this package is **not** compatible with that
-used by
+variety of other formats, incl. [conversion to SVG](#svg-support).
+
+By design, for better flexibility and performance reasons, the hiccup flavor
+used by this package is **not** compatible with that used by
 [thi.ng/hiccup-svg](https://github.com/thi-ng/umbrella/tree/develop/packages/hiccup-svg),
 though the latter provides a
 [`convertTree()`](https://docs.thi.ng/umbrella/hiccup-svg/functions/convertTree.html)
@@ -104,8 +106,8 @@ directly and/or perform automatic resampling/conversion if needed).
 | [`area()`](https://docs.thi.ng/umbrella/geom/functions/area.html)                           | signed/unsigned surface area                                 |
 | [`asCubic()`](https://docs.thi.ng/umbrella/geom/functions/asCubic.html)                     | convert shape boundary to cubic bezier segments              |
 | [`asPath()`](https://docs.thi.ng/umbrella/geom/functions/asPath.html)                       | convert shape to path                                        |
-| [`asPolygon()`](https://docs.thi.ng/umbrella/geom/functions/asPolygon.html)                 | convert shape to polygon                                     |
-| [`asPolyline()`](https://docs.thi.ng/umbrella/geom/functions/asPolyline.html)               | convert shape to polyline                                    |
+| [`asPolygon()`](https://docs.thi.ng/umbrella/geom/functions/asPolygon.html)                 | convert shape to polygon(s)                                  |
+| [`asPolyline()`](https://docs.thi.ng/umbrella/geom/functions/asPolyline.html)               | convert shape to polyline(s)                                 |
 | [`asSvg()`](https://docs.thi.ng/umbrella/geom/functions/asSvg.html)                         | serialize shape/group/hierarchy to SVG                       |
 | [`bounds()`](https://docs.thi.ng/umbrella/geom/functions/bounds.html)                       | compute bounding box                                         |
 | [`center()`](https://docs.thi.ng/umbrella/geom/functions/center.html)                       | center shape around origin or point                          |
@@ -122,6 +124,7 @@ directly and/or perform automatic resampling/conversion if needed).
 | [`offset()`](https://docs.thi.ng/umbrella/geom/functions/offset.html)                       | shape/path offsetting                                        |
 | [`pointAt()`](https://docs.thi.ng/umbrella/geom/functions/pointAt.html)                     | compute point on shape boundary at parametric position       |
 | [`pointInside()`](https://docs.thi.ng/umbrella/geom/functions/pointInside.html)             | check if point is inside shape                               |
+| [`proximity()`](https://docs.thi.ng/umbrella/geom/functions/proximity.html)                 | distance from point to shape boundary                        |
 | [`resample()`](https://docs.thi.ng/umbrella/geom/functions/resample.html)                   | resample/convert shape                                       |
 | [`rotate()`](https://docs.thi.ng/umbrella/geom/functions/rotate.html)                       | rotate shape                                                 |
 | [`scale()`](https://docs.thi.ng/umbrella/geom/functions/scale.html)                         | scale shape (uniformly/non-uniformly)                        |
@@ -210,7 +213,7 @@ For Node.js REPL:
 const geom = await import("@thi.ng/geom");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 13.25 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 14.61 KB
 
 ## Dependencies
 
@@ -253,15 +256,17 @@ directory are using this package:
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/boid-basics.png" width="240"/>           | Basic 2D boid simulation and spatial indexing neighbor lookups                   | [Demo](https://demo.thi.ng/umbrella/boid-basics/)           | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/boid-basics)           |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/canvas-recorder.png" width="240"/>       | Self-modifying, animated typographic grid with emergent complex patterns         | [Demo](https://demo.thi.ng/umbrella/canvas-recorder/)       | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/canvas-recorder)       |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/fiber-basics.png" width="240"/>          | Fiber-based cooperative multitasking basics                                      | [Demo](https://demo.thi.ng/umbrella/fiber-basics/)          | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/fiber-basics)          |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/geom-complex-poly.png" width="240"/>     | Shape conversions & operations using polygons with holes                         | [Demo](https://demo.thi.ng/umbrella/geom-complex-poly/)     | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/geom-complex-poly)     |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/geom-convex-hull.png" width="240"/>      | Convex hull & shape clipping of 2D polygons                                      | [Demo](https://demo.thi.ng/umbrella/geom-convex-hull/)      | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/geom-convex-hull)      |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom/geom-fuzz.png" width="240"/>                 | geom-fuzz basic shape & fill examples                                            | [Demo](https://demo.thi.ng/umbrella/geom-fuzz-basics/)      | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/geom-fuzz-basics)      |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/geom-sdf-logo.jpg" width="240"/>         | (Re)Constructing the thi.ng logo using a 2D signed-distance field                | [Demo](https://demo.thi.ng/umbrella/geom-sdf-logo/)         | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/geom-sdf-logo)         |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/geom-sdf-path.png" width="240"/>         | SVG path to SDF, applying deformation and converting back to SVG                 | [Demo](https://demo.thi.ng/umbrella/geom-sdf-path/)         | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/geom-sdf-path)         |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/geom-terrain-viz.jpg" width="240"/>      | 2.5D hidden line visualization of digital elevation files (DEM)                  | [Demo](https://demo.thi.ng/umbrella/geom-terrain-viz/)      | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/geom-terrain-viz)      |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom/tessel.png" width="240"/>                    | Animated, recursive polygon tessellations                                        | [Demo](https://demo.thi.ng/umbrella/geom-tessel/)           | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/geom-tessel)           |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/geom-voronoi-mst.jpg" width="240"/>      | Poisson-disk shape-aware sampling, Voronoi & Minimum Spanning Tree visualization | [Demo](https://demo.thi.ng/umbrella/geom-voronoi-mst/)      | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/geom-voronoi-mst)      |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/gesture-analysis.png" width="240"/>      | Mouse gesture / stroke analysis, simplification, corner detection                | [Demo](https://demo.thi.ng/umbrella/gesture-analysis/)      | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/gesture-analysis)      |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/hdom-canvas-particles.jpg" width="240"/> | 2D Bezier curve-guided particle system                                           | [Demo](https://demo.thi.ng/umbrella/hdom-canvas-particles/) | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/hdom-canvas-particles) |
-| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/hiccup-canvas-arcs.png" width="240"/>    | Animated arcs & drawing using hiccup-canvas                                      | [Demo](https://demo.thi.ng/umbrella/hiccup-canvas-arcs/)    | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/hiccup-canvas-arcs)    |
+| <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/hiccup-canvas-arcs.jpg" width="240"/>    | Animated arcs & drawing using hiccup-canvas                                      | [Demo](https://demo.thi.ng/umbrella/hiccup-canvas-arcs/)    | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/hiccup-canvas-arcs)    |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/imgui/imgui-all.png" width="240"/>                | Canvas based Immediate Mode GUI components                                       | [Demo](https://demo.thi.ng/umbrella/imgui/)                 | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/imgui)                 |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/geom/geom-isoline.png" width="240"/>              | Animated sine plasma effect visualized using contour lines                       | [Demo](https://demo.thi.ng/umbrella/iso-plasma/)            | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/iso-plasma)            |
 | <img src="https://raw.githubusercontent.com/thi-ng/umbrella/develop/assets/examples/kmeans-viz.jpg" width="240"/>            | k-means clustering visualization                                                 | [Demo](https://demo.thi.ng/umbrella/kmeans-viz/)            | [Source](https://github.com/thi-ng/umbrella/tree/develop/examples/kmeans-viz)            |

package/api/arc.js

@@ -64,7 +64,7 @@ class Arc {
     return [
       "path",
       this.attribs,
-      [["M", this.pointAt(0)], ...this.toHiccupPathSegments()]
+      [["M", this.pointAt(0)], this.toHiccupPathSegments()[0]]
     ];
   }
   toHiccupPathSegments() {

package/api/complex-polygon.d.ts

@@ -0,0 +1,14 @@
+import type { Attribs, IHiccupShape } from "@thi.ng/geom-api";
+import { Polygon } from "./polygon.js";
+export declare class ComplexPolygon implements IHiccupShape {
+    boundary: Polygon;
+    attribs?: Attribs | undefined;
+    children: Polygon[];
+    constructor(boundary?: Polygon, children?: Iterable<Polygon>, attribs?: Attribs | undefined);
+    get type(): string;
+    addChild(poly: Polygon): void;
+    copy(): ComplexPolygon;
+    withAttribs(attribs: Attribs): ComplexPolygon;
+    toHiccup(): (string | any[] | Attribs | undefined)[];
+}
+//# sourceMappingURL=complex-polygon.d.ts.map

package/api/complex-polygon.js

@@ -0,0 +1,44 @@
+import { ensureArray } from "@thi.ng/arrays/ensure-array";
+import { __copyAttribs } from "../internal/copy.js";
+import { Polygon } from "./polygon.js";
+class ComplexPolygon {
+  constructor(boundary = new Polygon(), children, attribs) {
+    this.boundary = boundary;
+    this.attribs = attribs;
+    this.children = children ? ensureArray(children) : [];
+  }
+  children;
+  get type() {
+    return "complexpoly";
+  }
+  addChild(poly) {
+    this.children.push(poly);
+  }
+  copy() {
+    return new ComplexPolygon(
+      this.boundary.copy(),
+      this.children.map((h) => h.copy()),
+      __copyAttribs(this)
+    );
+  }
+  withAttribs(attribs) {
+    return new ComplexPolygon(this.boundary, this.children, attribs);
+  }
+  toHiccup() {
+    const segments = [];
+    const $hiccupSegments = ({ points }) => {
+      if (!points.length) return;
+      segments.push(["M", points[0]]);
+      for (let i = 1, n = points.length; i < n; i++) {
+        segments.push(["L", points[i]]);
+      }
+      segments.push(["Z"]);
+    };
+    $hiccupSegments(this.boundary);
+    for (let c of this.children) $hiccupSegments(c);
+    return ["path", this.attribs, segments];
+  }
+}
+export {
+  ComplexPolygon
+};

package/api/path.d.ts

@@ -3,15 +3,23 @@ import type { Attribs, IHiccupShape, PathSegment } from "@thi.ng/geom-api";
 export declare class Path implements IClear, IHiccupShape {
     attribs?: Attribs | undefined;
     segments: PathSegment[];
-    closed: boolean;
-    constructor(segments?: Iterable<PathSegment>, attribs?: Attribs | undefined);
+    subPaths: PathSegment[][];
+    constructor(segments?: Iterable<PathSegment>, subPaths?: Iterable<PathSegment[]>, attribs?: Attribs | undefined);
     get type(): string;
+    /**
+     * Returns true, if the last main segment is a closing segment, e.g. if the
+     * path represents a closed shape.
+     */
+    get closed(): boolean;
     [Symbol.iterator](): Generator<PathSegment, void, undefined>;
     clear(): void;
+    close(): this;
     copy(): Path;
     withAttribs(attribs: Attribs): Path;
     equiv(o: any): boolean;
-    add(...segments: PathSegment[]): void;
+    isComplex(): number;
+    addSegments(...segments: PathSegment[]): this;
+    addSubPaths(...paths: PathSegment[][]): this;
     toHiccup(): (string | any[] | Attribs)[];
 }
 //# sourceMappingURL=path.d.ts.map

package/api/path.js

@@ -1,68 +1,84 @@
 import { ensureArray } from "@thi.ng/arrays/ensure-array";
+import { peek } from "@thi.ng/arrays/peek";
 import { equiv } from "@thi.ng/equiv";
 import { illegalState } from "@thi.ng/errors/illegal-state";
-import { copy } from "@thi.ng/vectors/copy";
-import { __copyAttribs } from "../internal/copy.js";
+import { __copyAttribs, __copySegment } from "../internal/copy.js";
+const CLOSE = Object.freeze({ type: "z" });
 class Path {
-  constructor(segments, attribs) {
+  constructor(segments, subPaths, attribs) {
     this.attribs = attribs;
     this.segments = segments ? ensureArray(segments) : [];
+    this.subPaths = subPaths ? ensureArray(subPaths) : [];
   }
   segments;
-  closed = false;
+  subPaths;
   get type() {
     return "path";
   }
+  /**
+   * Returns true, if the last main segment is a closing segment, e.g. if the
+   * path represents a closed shape.
+   */
+  get closed() {
+    return peek(this.segments)?.type === "z";
+  }
   *[Symbol.iterator]() {
     yield* this.segments;
   }
   clear() {
     this.segments.length = 0;
   }
+  close() {
+    if (!this.closed) this.segments.push(CLOSE);
+    return this;
+  }
   copy() {
     const p = new Path(
-      this.segments.map((s) => {
-        const d = { type: s.type };
-        s.point && (d.point = copy(s.point));
-        s.geo && (d.geo = s.geo.copy());
-        return d;
-      }),
+      this.segments.map(__copySegment),
+      this.subPaths.map((sub) => sub.map(__copySegment)),
       __copyAttribs(this)
     );
-    p.closed = this.closed;
     return p;
   }
   withAttribs(attribs) {
-    const res = new Path(this.segments, attribs);
-    res.closed = this.closed;
-    return res;
+    return new Path(this.segments, this.subPaths, attribs);
   }
   equiv(o) {
     return o instanceof Path && equiv(this.segments, o.segments);
   }
-  add(...segments) {
-    if (this.closed)
-      illegalState("path already closed");
-    this.segments.push(...segments);
+  isComplex() {
+    return this.subPaths.length;
+  }
+  addSegments(...segments) {
+    for (let s of segments) {
+      this.closed && illegalState("path already closed");
+      this.segments.push(s);
+    }
+    return this;
+  }
+  addSubPaths(...paths) {
+    this.subPaths.push(...paths);
+    return this;
   }
   toHiccup() {
-    let dest = [];
-    const segments = this.segments;
-    const n = segments.length;
-    if (n > 1) {
-      for (let i = 0; i < n; i++) {
+    const acc = [];
+    const $hiccupSegments = (segments) => {
+      for (let i = 0, n = segments.length; i < n; i++) {
         const s = segments[i];
         if (s.geo) {
-          dest = dest.concat(s.geo.toHiccupPathSegments());
+          acc.push(...s.geo.toHiccupPathSegments());
         } else if (s.point) {
-          dest.push(["M", s.point]);
+          acc.push(["M", s.point]);
+        } else {
+          acc.push([s.type]);
         }
       }
-      if (this.closed) {
-        dest.push(["Z"]);
-      }
+    };
+    if (this.segments.length > 1) {
+      $hiccupSegments(this.segments);
     }
-    return ["path", this.attribs || {}, dest];
+    for (let p of this.subPaths) $hiccupSegments(p);
+    return ["path", this.attribs || {}, acc];
   }
 }
 export {

package/apply-transforms.js

@@ -8,23 +8,18 @@ import { translate } from "./translate.js";
 const TX_ATTRIBS = ["transform", "translate", "rotate", "scale"];
 const __apply = ($) => {
   let attribs = $.attribs;
-  if (!attribs)
-    return $;
+  if (!attribs) return $;
   const { transform: tx, translate: t, rotate: r, scale: s } = attribs;
   if (tx)
     return transform(
       $.withAttribs(withoutKeysObj(attribs, TX_ATTRIBS)),
       tx
     );
-  if (!(t || r || s))
-    return $;
+  if (!(t || r || s)) return $;
   $ = $.withAttribs(withoutKeysObj(attribs, TX_ATTRIBS));
-  if (r)
-    $ = rotate($, r);
-  if (s)
-    $ = scale($, s);
-  if (t)
-    $ = translate($, t);
+  if (r) $ = rotate($, r);
+  if (s) $ = scale($, s);
+  if (t) $ = translate($, t);
   return $;
 };
 const applyTransforms = defmulti(

package/arc-length.d.ts

@@ -8,6 +8,7 @@ import type { IShape } from "@thi.ng/geom-api";
  * Implemented for:
  *
  * - {@link Circle}
+ * - {@link ComplexPolygon}
  * - {@link Ellipse}
  * - {@link Group} (total sum of child circumferences)
  * - {@link Line}

package/arc-length.js

@@ -2,6 +2,8 @@ import { defmulti } from "@thi.ng/defmulti/defmulti";
 import { perimeter } from "@thi.ng/geom-poly-utils/perimeter";
 import { PI, TAU } from "@thi.ng/math/api";
 import { dist } from "@thi.ng/vectors/dist";
+import { asPolygon } from "./as-polygon.js";
+import { asPolyline } from "./as-polyline.js";
 import { __dispatch } from "./internal/dispatch.js";
 const arcLength = defmulti(
   __dispatch,
@@ -11,6 +13,10 @@ const arcLength = defmulti(
   },
   {
     circle: ($) => TAU * $.r,
+    complexpoly: ($) => [$.boundary, ...$.children].reduce(
+      (acc, c) => acc + arcLength(c),
+      0
+    ),
     ellipse: ({ r: [a, b] }) => (
       // Ramanujan approximation
       // https://www.mathsisfun.com/geometry/ellipse-perimeter.html
@@ -18,6 +24,12 @@ const arcLength = defmulti(
     ),
     group: ({ children }) => children.reduce((sum, $) => sum + arcLength($), 0),
     line: ({ points }) => dist(points[0], points[1]),
+    path: ($) => {
+      return ($.closed ? asPolygon($) : asPolyline($)).reduce(
+        (acc, p) => acc + arcLength(p),
+        0
+      );
+    },
     poly: ({ points }) => perimeter(points, points.length, true),
     polyline: ({ points }) => perimeter(points, points.length),
     rect: ({ size: [w, h] }) => 2 * (w + h),

package/arc.d.ts

@@ -1,6 +1,56 @@
 import type { Attribs } from "@thi.ng/geom-api";
 import type { ReadonlyVec, Vec } from "@thi.ng/vectors";
 import { Arc } from "./api/arc.js";
-export declare const arc: (pos: Vec, r: number | Vec, axis: number, start: number, end: number, xl?: boolean, clockwise?: boolean) => Arc;
+/**
+ * Creates a new elliptic {@link Arc} from given `center`, `radii`, `axis`
+ * rotation, `start` and `end` angles (in radians).
+ *
+ * @remarks
+ * The `xl` (large arc) and `clockwise` params are defaulting to:
+ *
+ * - xl = true if |start-end| > PI
+ * - clockwise = true if end > start
+ *
+ * Reference:
+ * - https://svgwg.org/svg2-draft/paths.html#PathDataEllipticalArcCommands
+ * - https://svgwg.org/svg2-draft/images/paths/arcs02.svg
+ *
+ * Also see {@link arcFrom2Points}, {@link pathFromSvg} for an alternative construction.
+ *
+ * @param center
+ * @param radii
+ * @param axis
+ * @param start
+ * @param end
+ * @param xl
+ * @param clockwise
+ * @param attribs
+ */
+export declare const arc: (center: Vec, radii: number | Vec, axis: number, start: number, end: number, xl?: boolean, clockwise?: boolean, attribs?: Attribs) => Arc;
+/**
+ * Constructs a new {@link Arc} between the two given points `a` and `b` using
+ * `radii`, `axis` rotation (in radians) and `xl`, `clockwise` params to
+ * configure which of 4 possible arcs will be chosen.
+ *
+ * @remarks
+ * This function returns `undefined` if it's mathematically impossible to create
+ * an arc with the given parameters.
+ *
+ * Reference:
+ * - https://svgwg.org/svg2-draft/paths.html#PathDataEllipticalArcCommands
+ * - https://svgwg.org/svg2-draft/images/paths/arcs02.svg
+ * - https://svgwg.org/svg2-draft/implnote.html#ArcConversionEndpointToCenter
+ * - https://www.w3.org/TR/SVG11/implnote.html#ArcImplementationNotes
+ *
+ * Also see {@link arc}, {@link pathFromSvg} for an alternative construction.
+ *
+ * @param a
+ * @param b
+ * @param radii
+ * @param axis
+ * @param xl
+ * @param cw
+ * @param attribs
+ */
 export declare const arcFrom2Points: (a: ReadonlyVec, b: ReadonlyVec, radii: ReadonlyVec, axis?: number, xl?: boolean, cw?: boolean, attribs?: Attribs) => Arc | undefined;
 //# sourceMappingURL=arc.d.ts.map

package/arc.js

@@ -1,7 +1,18 @@
 import { isNumber } from "@thi.ng/checks/is-number";
 import { fromEndPoints } from "@thi.ng/geom-arc/from-endpoints";
 import { Arc } from "./api/arc.js";
-const arc = (pos, r, axis, start, end, xl = false, clockwise = false) => new Arc(pos, isNumber(r) ? [r, r] : r, axis, start, end, xl, clockwise);
+import { absDiff } from "@thi.ng/math/abs";
+import { PI } from "@thi.ng/math/api";
+const arc = (center, radii, axis, start, end, xl = absDiff(start, end) > PI, clockwise = end > start, attribs) => new Arc(
+  center,
+  isNumber(radii) ? [radii, radii] : radii,
+  axis,
+  start,
+  end,
+  xl,
+  clockwise,
+  attribs
+);
 const arcFrom2Points = (a, b, radii, axis = 0, xl = false, cw = false, attribs) => {
   const res = fromEndPoints(a, b, radii, axis, xl, cw);
   return res ? new Arc(

package/area.d.ts

@@ -15,6 +15,7 @@ import type { IShape } from "@thi.ng/geom-api";
  *
  * - {@link AABB}
  * - {@link Circle}
+ * - {@link ComplexPolygon}
  * - {@link Cubic}
  * - {@link Ellipse}
  * - {@link Group}