@field/cascade 0.5.2 → 0.6.0

package/dist/runtime/builtins/math/definitions.js

@@ -0,0 +1,285 @@
+function asComponents(value, label) {
+    if (typeof value === "number")
+        return [value];
+    if (Array.isArray(value) && value.every((part) => typeof part === "number"))
+        return value;
+    if (value === undefined || value === null)
+        return [0];
+    throw new Error(`${label} needs a number or a vector of numbers, and got ${describe(value)}`);
+}
+function describe(value) {
+    if (Array.isArray(value))
+        return `an array of ${value.length}`;
+    return `a ${typeof value}`;
+}
+/**
+ * Apply an operation component-wise, broadcasting a scalar against a vector.
+ *
+ * Mismatched vector widths throw rather than padding: `vec2 + vec3` is a wiring
+ * mistake, and quietly treating the missing component as zero would produce a
+ * plausible wrong answer — the failure that is hardest to see in a picture.
+ */
+function combine(left, right, operate) {
+    const a = asComponents(left, "the first input");
+    const b = asComponents(right, "the second input");
+    if (a.length !== b.length && a.length !== 1 && b.length !== 1)
+        throw new Error(`cannot combine a vector of ${a.length} with a vector of ${b.length}`);
+    const width = Math.max(a.length, b.length);
+    const out = [];
+    for (let index = 0; index < width; index += 1)
+        out.push(operate(a[a.length === 1 ? 0 : index], b[b.length === 1 ? 0 : index]));
+    return width === 1 ? out[0] : out;
+}
+function map(value, operate) {
+    const components = asComponents(value, "the input");
+    const out = components.map(operate);
+    return out.length === 1 ? out[0] : out;
+}
+/**
+ * Division and modulo by zero give **zero**, not `Infinity` or `NaN`.
+ *
+ * Both choices hide something, so this is the lesser one. A non-finite number
+ * flows downstream into a position and the geometry silently vanishes — a
+ * blank frame with no error anywhere, which is the hardest thing to diagnose
+ * here. And a zero divisor is almost always a parameter nobody set yet rather
+ * than an intent, so zero is also the likelier thing to have meant.
+ */
+function divide(a, b) {
+    return b === 0 ? 0 : a / b;
+}
+const BINARY = {
+    add: (a, b) => a + b,
+    subtract: (a, b) => a - b,
+    multiply: (a, b) => a * b,
+    divide,
+    power: (a, b) => a ** b,
+    modulo: (a, b) => (b === 0 ? 0 : a % b),
+    min: (a, b) => Math.min(a, b),
+    max: (a, b) => Math.max(a, b),
+    atan2: (a, b) => Math.atan2(a, b),
+};
+const DEG = Math.PI / 180;
+const UNARY = {
+    abs: Math.abs,
+    negate: (a) => -a,
+    floor: Math.floor,
+    ceil: Math.ceil,
+    round: Math.round,
+    sqrt: (a) => (a < 0 ? 0 : Math.sqrt(a)),
+    sign: Math.sign,
+    // Trigonometry in RADIANS, matching the expression engine, where bare `sin`
+    // is radians too. `radians` and `degrees` are here for the conversion, and
+    // the divergence from `Transform`'s degrees is recorded in AGENTS.md.
+    sin: Math.sin,
+    cos: Math.cos,
+    tan: Math.tan,
+    asin: (a) => Math.asin(Math.max(-1, Math.min(1, a))),
+    acos: (a) => Math.acos(Math.max(-1, Math.min(1, a))),
+    exp: Math.exp,
+    log: (a) => (a <= 0 ? 0 : Math.log(a)),
+    radians: (a) => a * DEG,
+    degrees: (a) => a / DEG,
+    /** The fractional part, always positive — `fract(-0.25)` is `0.75`, which is
+     *  what a repeating pattern wants and what GLSL's `fract` does. */
+    fract: (a) => a - Math.floor(a),
+};
+const COMPARE = {
+    greater: (a, b) => a > b,
+    "greater-or-equal": (a, b) => a >= b,
+    less: (a, b) => a < b,
+    "less-or-equal": (a, b) => a <= b,
+    equal: (a, b) => a === b,
+    "not-equal": (a, b) => a !== b,
+};
+function options(table) {
+    return Object.keys(table).map((value) => ({ value, label: label(value) }));
+}
+function label(value) {
+    return value
+        .split("-")
+        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(" ");
+}
+export const binaryDefinition = {
+    apiVersion: 1,
+    label: "Binary Math",
+    description: "Two values, one operation. Component-wise, and a scalar broadcasts against a vector.",
+    icon: "Plus",
+    runsOn: "portable",
+    inputs: {
+        a: { kind: "data", type: "any", default: 0, description: "First value." },
+        b: { kind: "data", type: "any", default: 0, description: "Second value." },
+    },
+    outputs: { value: { kind: "data", type: "any" } },
+    props: {
+        operation: {
+            type: "string",
+            default: "add",
+            control: "select",
+            options: options(BINARY),
+            label: "Operation",
+        },
+    },
+};
+export function executeBinary(context) {
+    const operate = BINARY[context.props.operation];
+    if (!operate)
+        throw new Error(`cascade.math.Binary has no operation "${context.props.operation}"`);
+    context.outputs.value.set(combine(context.inputs.a, context.inputs.b, operate));
+}
+export const unaryDefinition = {
+    apiVersion: 1,
+    label: "Unary Math",
+    description: "One value, one operation. Trigonometry is in radians.",
+    icon: "FunctionSquare",
+    runsOn: "portable",
+    inputs: {
+        value: { kind: "data", type: "any", default: 0 },
+    },
+    outputs: { value: { kind: "data", type: "any" } },
+    props: {
+        operation: {
+            type: "string",
+            default: "abs",
+            control: "select",
+            options: options(UNARY),
+            label: "Operation",
+        },
+    },
+};
+export function executeUnary(context) {
+    const operate = UNARY[context.props.operation];
+    if (!operate)
+        throw new Error(`cascade.math.Unary has no operation "${context.props.operation}"`);
+    context.outputs.value.set(map(context.inputs.value, operate));
+}
+export const clampDefinition = {
+    apiVersion: 1,
+    label: "Clamp",
+    description: "Hold a value between two bounds.",
+    icon: "Brackets",
+    runsOn: "portable",
+    inputs: {
+        value: { kind: "data", type: "any", default: 0 },
+        min: { kind: "data", type: "any", default: 0 },
+        max: { kind: "data", type: "any", default: 1 },
+    },
+    outputs: { value: { kind: "data", type: "any" } },
+    props: {},
+};
+export function executeClamp(context) {
+    const lower = combine(context.inputs.value, context.inputs.min, Math.max);
+    context.outputs.value.set(combine(lower, context.inputs.max, Math.min));
+}
+export const mixDefinition = {
+    apiVersion: 1,
+    label: "Mix",
+    description: "Blend between two values. Houdini's lerp.",
+    icon: "Blend",
+    runsOn: "portable",
+    inputs: {
+        a: { kind: "data", type: "any", default: 0, description: "The value at 0." },
+        b: { kind: "data", type: "any", default: 1, description: "The value at 1." },
+        bias: {
+            kind: "data",
+            type: "float",
+            default: 0.5,
+            min: 0,
+            max: 1,
+            step: 0.01,
+            description: "Not clamped: past 0..1 this extrapolates, which is useful.",
+        },
+    },
+    outputs: { value: { kind: "data", type: "any" } },
+    props: {},
+};
+export function executeMix(context) {
+    const bias = context.inputs.bias ?? 0.5;
+    // a + (b - a) * bias, component-wise. Written this way rather than as
+    // `a*(1-t) + b*t` because it is exact at t = 0 and t = 1 in floating point,
+    // which matters when a mix drives something that must land exactly on an end.
+    const delta = combine(context.inputs.b, context.inputs.a, (b, a) => b - a);
+    context.outputs.value.set(combine(context.inputs.a, delta, (a, d) => a + d * bias));
+}
+export const compareDefinition = {
+    apiVersion: 1,
+    label: "Compare",
+    description: "Test two values. Outputs a bool, for a Switch.",
+    icon: "Equal",
+    runsOn: "portable",
+    inputs: {
+        a: { kind: "data", type: "float", default: 0 },
+        b: { kind: "data", type: "float", default: 0 },
+    },
+    outputs: { result: { kind: "data", type: "bool" } },
+    props: {
+        operation: {
+            type: "string",
+            default: "greater",
+            control: "select",
+            options: options(COMPARE),
+            label: "Test",
+        },
+        /**
+         * Scalars only, unlike the rest of this namespace.
+         *
+         * "Is this vector greater than that one" has no single right answer — all
+         * components, any component, or the length — and a node that picked one
+         * silently would be wrong for the other two readings. A comparison feeding
+         * a `Switch` wants one boolean, so the input is a `float` and the question
+         * does not arise.
+         */
+        tolerance: {
+            type: "float",
+            default: 0,
+            min: 0,
+            label: "Tolerance",
+            description: "Slack for Equal and Not Equal. Floating point rarely lands on exactly equal.",
+        },
+    },
+};
+export function executeCompare(context) {
+    const operation = context.props.operation;
+    const test = COMPARE[operation];
+    if (!test)
+        throw new Error(`cascade.math.Compare has no test "${context.props.operation}"`);
+    const a = context.inputs.a ?? 0;
+    const b = context.inputs.b ?? 0;
+    const tolerance = context.props.tolerance;
+    if (tolerance > 0 && (operation === "equal" || operation === "not-equal")) {
+        const near = Math.abs(a - b) <= tolerance;
+        context.outputs.result.set(operation === "equal" ? near : !near);
+        return;
+    }
+    context.outputs.result.set(test(a, b));
+}
+function registration(name, definition, execute) {
+    return {
+        kind: "definition-v1",
+        moduleId: `cascade.math.${name}`,
+        definition,
+        loadExecute: async () => execute,
+    };
+}
+export const binaryRegistration = registration("Binary", binaryDefinition, executeBinary);
+export const unaryRegistration = registration("Unary", unaryDefinition, executeUnary);
+export const clampRegistration = registration("Clamp", clampDefinition, executeClamp);
+export const mixRegistration = registration("Mix", mixDefinition, executeMix);
+export const compareRegistration = registration("Compare", compareDefinition, executeCompare);
+export const mathNodeRegistrations = Object.freeze([
+    binaryRegistration,
+    unaryRegistration,
+    clampRegistration,
+    mixRegistration,
+    compareRegistration,
+]);
+/** `[moduleId, definition]` pairs, the shape a host's palette builder wants. */
+export const mathNodeDefinitions = Object.freeze([
+    ["cascade.math.Binary", binaryDefinition],
+    ["cascade.math.Unary", unaryDefinition],
+    ["cascade.math.Clamp", clampDefinition],
+    ["cascade.math.Mix", mixDefinition],
+    ["cascade.math.Compare", compareDefinition],
+]);
+export { BINARY, UNARY, COMPARE };
+//# sourceMappingURL=definitions.js.map

package/dist/runtime/builtins/math/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./definitions.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/runtime/builtins/math/index.js

@@ -0,0 +1,2 @@
+export * from "./definitions.js";
+//# sourceMappingURL=index.js.map

package/doc/NODE_REFERENCE.md

@@ -498,6 +498,121 @@ Runs on `portable`.
 | --- | --- | --- | --- |
 | `geometry` | `geometry` |  |  |
 
+### `cascade.math.Binary`
+
+Binary Math — Two values, one operation. Component-wise, and a scalar broadcasts against a vector.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `a` | `any` | `0` |  |
+| `b` | `any` | `0` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `operation` | `string` | `"add"` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` |  |  |
+
+### `cascade.math.Clamp`
+
+Clamp — Hold a value between two bounds.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` | `0` |  |
+| `min` | `any` | `0` |  |
+| `max` | `any` | `1` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` |  |  |
+
+### `cascade.math.Compare`
+
+Compare — Test two values. Outputs a bool, for a Switch.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `a` | `float` | `0` |  |
+| `b` | `float` | `0` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `operation` | `string` | `"greater"` |  |
+| `tolerance` | `float` | `0` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `result` | `bool` |  |  |
+
+### `cascade.math.Mix`
+
+Mix — Blend between two values. Houdini's lerp.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `a` | `any` | `0` |  |
+| `b` | `any` | `1` |  |
+| `bias` | `float` | `0.5` | 0…1 |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` |  |  |
+
+### `cascade.math.Unary`
+
+Unary Math — One value, one operation. Trigonometry is in radians.
+
+Runs on `portable`.
+
+**Inputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` | `0` |  |
+
+**Props**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `operation` | `string` | `"abs"` |  |
+
+**Outputs**
+
+| name | type | default | range |
+| --- | --- | --- | --- |
+| `value` | `any` |  |  |
+
 ### `cascade.pop.FieldForce`
 
 POP Field Force — Pull particles along a field's gradient and around its contours. The calligraphy force.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@field/cascade",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Visual programming for generative art",
   "license": "MIT",
   "author": "FIELD.IO <marcus@field.io>",

package/dist/assets/definitions-BgCvRHyR.js

@@ -1 +0,0 @@
-import{D as e,c as t,l as n,p as r,u as i}from"./index-CeqTfMbr.js";e([r,t,n,i]);

package/dist/assets/geo-CIxgs0oE.js

@@ -1 +0,0 @@
-import{D as e,E as t,s as n,v as r}from"./index-CeqTfMbr.js";e(n,{assets:t});export{r as geoLibrary};

package/dist/assets/pop-BJGN5Ac4.js

@@ -1 +0,0 @@
-import{D as e,_ as t,g as n}from"./index-CeqTfMbr.js";e(t,{});export{n as popLibrary};