@thi.ng/viz 0.7.18 → 0.8.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2025-07-10T14:20:23Z
+- **Last updated**: 2025-07-17T15:09:00Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -11,6 +11,12 @@ See [Conventional Commits](https://conventionalcommits.org/) for commit guidelin
 **Note:** Unlisted _patch_ versions only involve non-code or otherwise excluded changes
 and/or version bumps of transitive dependencies.
 
+## [0.8.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/viz@0.8.0) (2025-07-17)
+
+#### 🚀 Features
+
+- add vectorField() plot fn & helpers ([3d2263c](https://github.com/thi-ng/umbrella/commit/3d2263c))
+
 ## [0.7.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/viz@0.7.0) (2025-02-24)
 
 #### 🚀 Features

package/README.md

@@ -97,7 +97,7 @@ For Node.js REPL:
 const viz = await import("@thi.ng/viz");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 2.63 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 2.99 KB
 
 ## Dependencies
 
@@ -108,6 +108,7 @@ Package sizes (brotli'd, pre-treeshake): ESM: 2.63 KB
 - [@thi.ng/object-utils](https://github.com/thi-ng/umbrella/tree/develop/packages/object-utils)
 - [@thi.ng/strings](https://github.com/thi-ng/umbrella/tree/develop/packages/strings)
 - [@thi.ng/transducers](https://github.com/thi-ng/umbrella/tree/develop/packages/transducers)
+- [@thi.ng/vectors](https://github.com/thi-ng/umbrella/tree/develop/packages/vectors)
 
 Note: @thi.ng/api is in _most_ cases a type-only import (not used at runtime)
 

package/index.d.ts

@@ -11,4 +11,5 @@ export * from "./plot/line.js";
 export * from "./plot/scatter.js";
 export * from "./plot/stacked-intervals.js";
 export * from "./plot/utils.js";
+export * from "./plot/vector-field.js";
 //# sourceMappingURL=index.d.ts.map

package/index.js

@@ -11,3 +11,4 @@ export * from "./plot/line.js";
 export * from "./plot/scatter.js";
 export * from "./plot/stacked-intervals.js";
 export * from "./plot/utils.js";
+export * from "./plot/vector-field.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/viz",
-  "version": "0.7.18",
+  "version": "0.8.0",
   "description": "Declarative, functional & multi-format data visualization toolkit based around @thi.ng/hiccup",
   "type": "module",
   "module": "./index.js",
@@ -46,12 +46,13 @@
   },
   "dependencies": {
     "@thi.ng/api": "^8.11.30",
-    "@thi.ng/arrays": "^2.13.2",
+    "@thi.ng/arrays": "^2.13.3",
     "@thi.ng/checks": "^3.7.10",
     "@thi.ng/math": "^5.11.30",
     "@thi.ng/object-utils": "^1.2.2",
     "@thi.ng/strings": "^3.9.16",
-    "@thi.ng/transducers": "^9.6.0"
+    "@thi.ng/transducers": "^9.6.1",
+    "@thi.ng/vectors": "^8.3.3"
   },
   "devDependencies": {
     "@thi.ng/date": "^2.7.56",
@@ -136,6 +137,9 @@
     "./plot/utils": {
       "default": "./plot/utils.js"
     },
+    "./plot/vector-field": {
+      "default": "./plot/vector-field.js"
+    },
     "./plot": {
       "default": "./plot.js"
     }
@@ -149,5 +153,5 @@
     "status": "alpha",
     "year": 2014
   },
-  "gitHead": "a81765bd79046980463c56a8bd187f9aaa88dd65\n"
+  "gitHead": "4e98c38a817045d0e9a5b8bb6da23c00a721c3e0\n"
 }

package/plot/vector-field.d.ts

@@ -0,0 +1,57 @@
+import { type ReadonlyVec } from "@thi.ng/vectors";
+import type { PlotFn } from "../api.js";
+export interface VectorFieldOpts {
+    /**
+     * Group attributes.
+     */
+    attribs?: any;
+    /**
+     * Offset vector (in domain/grid coords), used to compute projected screen
+     * coords.
+     *
+     * @defaultValue [0.5, 0.5]
+     */
+    offset: ReadonlyVec;
+    /**
+     * Vector scale factor (applied to original field vectors)
+     *
+     * @defaultValue 1
+     */
+    scale: number;
+    /**
+     * Shape definition for visualizing individual vectors. Uses
+     * {@link vectorShapeLine} by default.
+     */
+    shape: VectorFieldShape;
+}
+export interface VectorFieldShape {
+    /**
+     * Optional marker for easy vector arrow visualization & reuse by shape function.
+     */
+    marker?: any[];
+    /**
+     * Shape function to represent a vector in the diagram as thi.ng/hiccup
+     * compatible shape/element.
+     *
+     * @param a - vector start point (in screen coords)
+     * @param b - vector end point (in screen coords)
+     * @param v - original vector
+     */
+    fn: (a: ReadonlyVec, b: ReadonlyVec, v: ReadonlyVec) => any;
+}
+/**
+ * Vectorfield plot function.
+ *
+ * @remarks
+ * IMPORTANT: Domain ranges for this plot function MUST be zero-based and
+ * integer-sized, corresponding to the shape of the supplied field data. The
+ * field vectors should be normalized, but don't have to be...
+ *
+ * @param data
+ * @param opts
+ */
+export declare const vectorField: (data: ReadonlyVec[][], opts?: Partial<VectorFieldOpts>) => PlotFn;
+export declare const vectorShapeLine: (size?: number) => VectorFieldShape;
+export declare const vectorShapeLineHSL: (size?: number) => VectorFieldShape;
+export declare const vectorShapeDial: VectorFieldShape;
+//# sourceMappingURL=vector-field.d.ts.map

package/plot/vector-field.js

@@ -0,0 +1,71 @@
+import { mapcatIndexed } from "@thi.ng/transducers";
+import { dist2, heading } from "@thi.ng/vectors";
+import { __valueMapper } from "./utils.js";
+const vectorField = (data, opts = {}) => (spec) => {
+  const scale = opts.scale ?? 1;
+  const [ox, oy] = opts.offset ?? [0.5, 0.5];
+  const { marker, fn } = opts.shape ?? vectorShapeLine();
+  const mapper = __valueMapper(spec.xaxis, spec.yaxis, spec.project);
+  return [
+    "g",
+    opts.attribs || {},
+    marker,
+    ...mapcatIndexed(
+      (y, row) => row.map(
+        (v, x) => fn(
+          mapper([x + ox, y + oy]),
+          mapper([
+            x + ox + v[0] * scale,
+            y + oy + v[1] * scale
+          ]),
+          v
+        )
+      ),
+      data
+    )
+  ];
+};
+const vectorShapeLine = (size = 5) => ({
+  marker: [
+    "marker",
+    {
+      id: "arrow",
+      viewBox: "0 0 10 10",
+      refX: 9,
+      refY: 5,
+      markerWidth: size,
+      markerHeight: size,
+      orient: "auto-start-reverse"
+    },
+    [
+      "path",
+      {
+        stroke: "none",
+        fill: "context-fill",
+        d: "M0,0L10,5L0,10z"
+      }
+    ]
+  ],
+  fn: (a, b) => ["line", { "marker-end": "url(#arrow)" }, a, b]
+});
+const vectorShapeLineHSL = (size = 5) => ({
+  ...vectorShapeLine(size),
+  fn: (a, b, v) => {
+    const col = `hsl(${heading(v).toFixed(2)}rad,100%,50%)`;
+    return [
+      "line",
+      { "marker-end": "url(#arrow)", fill: col, stroke: col },
+      a,
+      b
+    ];
+  }
+});
+const vectorShapeDial = {
+  fn: (a, b) => ["g", {}, ["circle", {}, a, dist2(a, b)], ["line", {}, a, b]]
+};
+export {
+  vectorField,
+  vectorShapeDial,
+  vectorShapeLine,
+  vectorShapeLineHSL
+};