@thi.ng/geom-sdf 0.2.95 → 0.3.0

package/CHANGELOG.md

@@ -1,6 +1,6 @@
 # Change Log
 
-- **Last updated**: 2023-12-28T23:24:38Z
+- **Last updated**: 2024-01-23T15:58:27Z
 - **Generator**: [thi.ng/monopub](https://thi.ng/monopub)
 
 All notable changes to this project will be documented in this file.
@@ -9,6 +9,17 @@ 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.3.0](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom-sdf@0.3.0) (2024-01-23)
+
+#### 🚀 Features
+
+- update SDFAttribs/SDFModifiers ([e1e51ff](https://github.com/thi-ng/umbrella/commit/e1e51ff))
+  - extract/update SDFModifiers
+  - add min/max/clamp() mods
+  - add withSDFModifiers()
+  - update withSDFAttribs()
+  - add/update docstrings
+
 ### [0.2.81](https://github.com/thi-ng/umbrella/tree/@thi.ng/geom-sdf@0.2.81) (2023-11-09)
 
 #### ♻️ Refactoring

package/README.md

@@ -7,8 +7,9 @@
 ![npm downloads](https://img.shields.io/npm/dm/@thi.ng/geom-sdf.svg)
 [![Mastodon Follow](https://img.shields.io/mastodon/follow/109331703950160316?domain=https%3A%2F%2Fmastodon.thi.ng&style=social)](https://mastodon.thi.ng/@toxi)
 
-This project is part of the
-[@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo and anti-framework.
+This is a standalone project, maintained as part of the
+[@thi.ng/umbrella](https://github.com/thi-ng/umbrella/) monorepo and
+anti-framework.
 
 - [About](#about)
   - [SDF creation](#sdf-creation)
@@ -135,7 +136,7 @@ For Node.js REPL:
 const geomSdf = await import("@thi.ng/geom-sdf");
 ```
 
-Package sizes (brotli'd, pre-treeshake): ESM: 3.55 KB
+Package sizes (brotli'd, pre-treeshake): ESM: 3.65 KB
 
 ## Dependencies
 
@@ -250,4 +251,4 @@ If this project contributes to an academic publication, please cite it as:
 
 ## License
 
-© 2022 - 2023 Karsten Schmidt // Apache License 2.0
+© 2022 - 2024 Karsten Schmidt // Apache License 2.0

package/api.d.ts

@@ -9,23 +9,74 @@ export type SDFn = (p: ReadonlyVec, minD?: number) => number;
 export type SDFCombineOp = "union" | "isec" | "diff";
 export type FieldCoeff<T = number> = Fn<ReadonlyVec, T>;
 /**
- * Options object to customize geometry -> SDF conversions. Given as value to
- * the special `__sdf` shape attribute.
- *
- * @example
- * ```ts
- * const sdf = asSDF(circle(100, { __sdf: { abs: true } }));
- * ```
+ * Modifier options for {@link withSDFModifiers} and basis for
+ * {@link SDFAttribs}.
  */
-export interface SDFAttribs {
+export interface SDFModifiers {
     /**
      * If true, only the absolute (unsigned) distance will be used. For closed
      * shapes the default is false, for lines/curves the default is true (since
      * there's no real interior).
      *
+     * @remarks
+     * See {@link withSDFModifiers} for order of application.
+     *
      * @defaultValue false
      */
     abs: boolean;
+    /**
+     * If true (default: false), the sign of the resulting distance will be
+     * flipped. Useful for boolean operations.
+     *
+     * @remarks
+     * See {@link withSDFModifiers} for order of application.
+     *
+     * @defaultValue false
+     */
+    flip: boolean;
+    /**
+     * Subtracts given value from actual distance, thereby creating an
+     * offsetting effect. If given as function, it will be called with the
+     * current SDF query point and the return value will be used as param.
+     *
+     * @remarks
+     * See {@link withSDFModifiers} for order of application.
+     *
+     * @defaultValue 0
+     */
+    offset: number | FieldCoeff;
+    /**
+     * If given, the actual distance will be clamped to this value as lower
+     * bound.
+     *
+     * @remarks
+     * See {@link withSDFModifiers} for order of application.
+     *
+     * @defaultValue -Infinity
+     */
+    min: number;
+    /**
+     * If given, the actual distance will be clamped to this value as upper
+     * bound.
+     *
+     * @remarks
+     * See {@link withSDFModifiers} for order of application.
+     *
+     * @defaultValue Infinity
+     */
+    max: number;
+}
+/**
+ * Options object to customize geometry -> SDF conversions. Given as value to
+ * the special `__sdf` shape attribute. Also see {@link asSDF},
+ * {@link withSDFAttribs}.
+ *
+ * @example
+ * ```ts
+ * const sdf = asSDF(circle(100, { __sdf: { abs: true } }));
+ * ```
+ */
+export interface SDFAttribs extends SDFModifiers {
     /**
      * Advanced usage only. If true (default: false), the SDF will be wrapped
      * with a bounding box pre-check.
@@ -43,21 +94,6 @@ export interface SDFAttribs {
      * @defaultValue "union"
      */
     combine: SDFCombineOp;
-    /**
-     * If true (default: false), the sign of the resulting distance will be
-     * flipped. Useful for boolean operations.
-     *
-     * @defaultValue false
-     */
-    flip: boolean;
-    /**
-     * Subtracts given value from actual distance, thereby creating an
-     * offsetting effect. If given as function, it will be called with the
-     * current SDF query point and the return value will be used as param.
-     *
-     * @defaultValue 0
-     */
-    offset: number | FieldCoeff;
     /**
      * Coefficient for smooth union, intersection, difference ops (only
      * supported for `group()` shapes). If given as function, it will be called

package/ops.d.ts

@@ -1,7 +1,66 @@
 import type { Fn3, FnN2 } from "@thi.ng/api";
-import type { FieldCoeff, SDFn } from "./api.js";
+import type { FieldCoeff, SDFModifiers, SDFn } from "./api.js";
+/** @internal */
+export declare const DEFAULT_MODS: SDFModifiers;
+/**
+ * Applies any SDF modifiers specified via {@link SDFModifiers} to the given
+ * distance function. Returns a possibly updated distance function.
+ *
+ * @remarks
+ * Order of application is: abs, offset, flip, min, max
+ *
+ * @param fn
+ * @param mods
+ */
+export declare const withSDFModifiers: (fn: SDFn, mods: Partial<SDFModifiers>) => SDFn;
+/**
+ * SDF modifier. Augments given `fn` such that it always produces an unsigned
+ * (absolute) distance.
+ *
+ * @param sdf
+ */
 export declare const abs: (sdf: SDFn) => SDFn;
+/**
+ * SDF modifier. Augments given `fn` such that the returned distance is <= given
+ * `maxD`.
+ *
+ * @param sdf
+ * @param maxD
+ */
+export declare const min: (sdf: SDFn, maxD: number) => SDFn;
+/**
+ * SDF modifier. Augments given `fn` such that the returned distance is >= given
+ * `minD`.
+ *
+ * @param sdf
+ * @param minD
+ */
+export declare const max: (sdf: SDFn, minD: number) => SDFn;
+/**
+ * SDF modifier. Augments given `fn` such that the returned distance is clamped
+ * to given `[minD, maxD]` interval.
+ *
+ * @param sdf
+ * @param minD
+ * @param maxD
+ */
+export declare const clamp: (sdf: SDFn, minD: number, maxD: number) => SDFn;
+/**
+ * SDF modifier. Augments given `fn` such that the sign of the returned distance
+ * is flipped (i.e. inside vs. outside).
+ *
+ * @param sdf
+ */
 export declare const flip: (sdf: SDFn) => SDFn;
+/**
+ * SDF modifier. Augments given `fn` such that the returned distance will have
+ * given offset `r` (radius) subtracted. If `r` is a function it will be
+ * evaluated for each point the original SDF function is evaluated too and its
+ * return value will be subtracted, allowing for varying offsets.
+ *
+ * @param sdf
+ * @param r
+ */
 export declare const offset: (sdf: SDFn, r: number | FieldCoeff) => SDFn;
 export declare const defOp: (op: FnN2) => (children: SDFn[]) => SDFn;
 export declare const union: (children: SDFn[]) => SDFn;

package/ops.js

@@ -1,10 +1,45 @@
 import { isFunction } from "@thi.ng/checks/is-function";
 import { assert } from "@thi.ng/errors/assert";
-import { clamp01, mix, mod, SQRT2_2 } from "@thi.ng/math";
+import { SQRT2_2 } from "@thi.ng/math/api";
+import { clamp as $clamp, clamp01 } from "@thi.ng/math/interval";
+import { mix } from "@thi.ng/math/mix";
+import { mod } from "@thi.ng/math/prec";
+const { abs: $abs, min: $min, max: $max } = Math;
 const __asField = (k) => isFunction(k) ? k : () => k;
 const __ensureChildren = (children, min2 = 1) => assert(children.length >= 1, `require at least ${min2} SDF(s)`);
-const { min, max } = Math;
-const abs = (sdf) => (p, minD) => Math.abs(sdf(p, minD));
+const DEFAULT_MODS = {
+  abs: false,
+  flip: false,
+  min: -Infinity,
+  max: Infinity,
+  offset: 0
+};
+const withSDFModifiers = (fn, mods) => {
+  const {
+    abs: $abs2,
+    flip: $flip,
+    offset: $offset,
+    min: $min2,
+    max: $max2
+  } = { ...DEFAULT_MODS, ...mods };
+  if ($abs2)
+    fn = abs(fn);
+  if (isFunction($offset) || $offset > 0)
+    fn = offset(fn, $offset);
+  if ($flip)
+    fn = flip(fn);
+  if ($min2 >= -Infinity) {
+    if ($max2 < Infinity)
+      return clamp(fn, $min2, $max2);
+    fn = max(fn, $min2);
+  } else if ($max2 < Infinity)
+    fn = min(fn, $max2);
+  return fn;
+};
+const abs = (sdf) => (p, minD) => $abs(sdf(p, minD));
+const min = (sdf, maxD) => (p, minD) => $min(sdf(p, minD), maxD);
+const max = (sdf, minD) => (p, currMin) => $max(sdf(p, currMin), minD);
+const clamp = (sdf, minD, maxD) => (p, $minD) => $clamp(sdf(p, $minD), minD, maxD);
 const flip = (sdf) => (p, minD) => -sdf(p, minD);
 const offset = (sdf, r) => isFunction(r) ? (p, minD) => sdf(p, minD) - r(p) : (p, minD) => sdf(p, minD) - r;
 const defOp = (op) => (children) => {
@@ -23,9 +58,9 @@ const defOp = (op) => (children) => {
     return res;
   };
 };
-const union = defOp(min);
-const isec = defOp(max);
-const diff = defOp((a, b) => max(a, -b));
+const union = defOp($min);
+const isec = defOp($max);
+const diff = defOp((a, b) => $max(a, -b));
 const defParamOp = (op) => (k, children) => {
   __ensureChildren(children);
   const kfield = __asField(k);
@@ -57,27 +92,27 @@ const smoothDiff = defParamOp((a, b, k) => {
   return mix(a, -b, h) + k * h * (1 - h);
 });
 const chamferUnion = defParamOp(
-  (a, b, k) => min(min(a, b), (a - k + b) * SQRT2_2)
+  (a, b, k) => $min(a, b, (a - k + b) * SQRT2_2)
 );
 const chamferIsec = defParamOp(
-  (a, b, k) => max(max(a, b), (a + k + b) * SQRT2_2)
+  (a, b, k) => $max(a, b, (a + k + b) * SQRT2_2)
 );
 const chamferDiff = defParamOp(
-  (a, b, k) => max(max(a, -b), (a + k - b) * SQRT2_2)
+  (a, b, k) => $max(a, -b, (a + k - b) * SQRT2_2)
 );
 const roundUnion = defParamOp(
-  (a, b, k) => max(k, min(a, b)) - Math.hypot(max(k - a, 0), max(k - b, 0))
+  (a, b, k) => $max(k, $min(a, b)) - Math.hypot($max(k - a, 0), $max(k - b, 0))
 );
 const roundIsec = defParamOp(
-  (a, b, k) => min(-k, max(a, b)) + Math.hypot(max(k + a, 0), max(k + b, 0))
+  (a, b, k) => $min(-k, $max(a, b)) + Math.hypot($max(k + a, 0), $max(k + b, 0))
 );
 const roundDiff = defParamOp(
-  (a, b, k) => min(-k, max(a, -b)) + Math.hypot(max(k + a, 0), max(k - b, 0))
+  (a, b, k) => $min(-k, $max(a, -b)) + Math.hypot($max(k + a, 0), $max(k - b, 0))
 );
 const __steps = (a, b, [r, n]) => {
   const s = r / n;
   const u = b - r;
-  return min(min(a, b), 0.5 * (u + a + Math.abs(mod(u - a + s, 2 * s) - s)));
+  return $min(a, b, 0.5 * (u + a + Math.abs(mod(u - a + s, 2 * s) - s)));
 };
 const stepUnion = defParamOp(__steps);
 const stepIsec = defParamOp(
@@ -87,15 +122,19 @@ const stepDiff = defParamOp(
   (a, b, k) => -__steps(-a, b, k)
 );
 export {
+  DEFAULT_MODS,
   abs,
   chamferDiff,
   chamferIsec,
   chamferUnion,
+  clamp,
   defOp,
   defParamOp,
   diff,
   flip,
   isec,
+  max,
+  min,
   offset,
   roundDiff,
   roundIsec,
@@ -106,5 +145,6 @@ export {
   stepDiff,
   stepIsec,
   stepUnion,
-  union
+  union,
+  withSDFModifiers
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thi.ng/geom-sdf",
-  "version": "0.2.95",
+  "version": "0.3.0",
   "description": "2D Signed Distance Field creation from @thi.ng/geom shapes, conversions, sampling, combinators",
   "type": "module",
   "module": "./index.js",
@@ -35,18 +35,18 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@thi.ng/api": "^8.9.15",
-    "@thi.ng/checks": "^3.4.15",
-    "@thi.ng/defmulti": "^3.0.13",
-    "@thi.ng/errors": "^2.4.9",
-    "@thi.ng/geom": "^6.0.16",
-    "@thi.ng/geom-api": "^3.4.55",
-    "@thi.ng/geom-isoline": "^2.1.93",
-    "@thi.ng/geom-poly-utils": "^2.3.81",
-    "@thi.ng/geom-resample": "^2.3.19",
-    "@thi.ng/math": "^5.7.10",
-    "@thi.ng/transducers": "^8.8.19",
-    "@thi.ng/vectors": "^7.8.14"
+    "@thi.ng/api": "^8.9.17",
+    "@thi.ng/checks": "^3.4.17",
+    "@thi.ng/defmulti": "^3.0.15",
+    "@thi.ng/errors": "^2.4.11",
+    "@thi.ng/geom": "^6.0.18",
+    "@thi.ng/geom-api": "^3.4.57",
+    "@thi.ng/geom-isoline": "^2.1.95",
+    "@thi.ng/geom-poly-utils": "^2.3.83",
+    "@thi.ng/geom-resample": "^2.3.21",
+    "@thi.ng/math": "^5.7.12",
+    "@thi.ng/transducers": "^8.8.21",
+    "@thi.ng/vectors": "^7.9.0"
   },
   "devDependencies": {
     "@microsoft/api-extractor": "^7.39.0",
@@ -127,5 +127,5 @@
     "status": "alpha",
     "year": 2022
   },
-  "gitHead": "775c664723cd87d6ac5909cedf91195317add287\n"
+  "gitHead": "417b5a7ea7bd54a3b4f086fe0fc2ce8e8933c9b2\n"
 }

package/shapes.d.ts

@@ -3,11 +3,7 @@ import type { SDFAttribs, SDFn } from "./api.js";
 /** @internal */
 export declare const DEFAULT_ATTRIBS: SDFAttribs;
 /**
- * Applies any SDF modifiers specified via {@link SDFAttribs} to the given
- * distance function. Returns a possibly updated distance function.
- *
- * @remarks
- * Order of application is: abs, offset, flip
+ * Syntax sugar for {@link withSDFModifiers}.
  *
  * @param fn
  * @param attribs

package/shapes.js

@@ -1,4 +1,3 @@
-import { isFunction } from "@thi.ng/checks/is-function";
 import { distSq2 } from "@thi.ng/vectors";
 import { sub2 } from "@thi.ng/vectors/sub";
 import { withBoundingCircle } from "./bounds.js";
@@ -12,29 +11,16 @@ import {
   distQuadratic2,
   distSegment2
 } from "./dist.js";
-import { abs as $abs, flip as $flip, offset as $offset } from "./ops.js";
+import { DEFAULT_MODS, withSDFModifiers } from "./ops.js";
 const DEFAULT_ATTRIBS = {
-  abs: false,
+  ...DEFAULT_MODS,
   bounds: false,
   chamfer: 0,
   combine: "union",
-  flip: false,
-  offset: 0,
   round: 0,
   smooth: 0
 };
-const withSDFAttribs = (fn, attribs) => {
-  if (attribs) {
-    const { abs, flip, offset } = { ...DEFAULT_ATTRIBS, ...attribs };
-    if (abs)
-      fn = $abs(fn);
-    if (isFunction(offset) || offset > 0)
-      fn = $offset(fn, offset);
-    if (flip)
-      fn = $flip(fn);
-  }
-  return fn;
-};
+const withSDFAttribs = (fn, attribs) => attribs ? withSDFModifiers(fn, attribs) : fn;
 const arc2 = (center, apert, ra, rb, attribs = {}) => {
   const sdf = withSDFAttribs(
     (p) => distArc2(sub2([], p, center), apert, ra, rb),