nucleation 0.6.0 → 0.8.0

package/Sdf.d.ts

@@ -1,13 +1,24 @@
 // generated by diplomat-tool
-import type { NucleationError } from "./NucleationError"
-import type { Schematic } from "./Schematic"
+import type { Field3 } from "./Field3.mjs"
+import type { FieldProgram } from "./FieldProgram.mjs"
+import type { NucleationError } from "./NucleationError.mjs"
+import type { Schematic } from "./Schematic.mjs"
+import type { SdfAxis } from "./SdfAxis.mjs"
+import type { SdfBounds } from "./SdfBounds.mjs"
+import type { SdfCellMode } from "./SdfCellMode.mjs"
+import type { SdfNormal } from "./SdfNormal.mjs"
+import type { Shape } from "./Shape.mjs"
 import type { pointer, codepoint } from "./diplomat-runtime.d.ts";
 
 
 
 /**
- * Namespace for the SDF free functions of the old ABI (`schematic_from_sdf`,
- * `sdf_eval`).
+ * An immutable, composable signed-distance-field expression graph.
+ *
+ * Primitive constructors and every combinator return a new graph, so values
+ * can be shared safely between Flow nodes and across Kotlin/Java, JavaScript,
+ * and Python bindings. JSON is retained only for explicit import/export and
+ * the legacy sampling helpers.
  */
 export class Sdf {
     /** @internal */
@@ -16,24 +27,208 @@ export class Sdf {
     constructor();
 
 
+    static sphere(radius: number): Sdf;
+
+    /**
+     * Axis-aligned rounded box, centered at the origin.
+     */
+    static boxShape(halfX: number, halfY: number, halfZ: number, rounding: number): Sdf;
+
+    static ellipsoid(radiusX: number, radiusY: number, radiusZ: number): Sdf;
+
+    static torus(majorRadius: number, minorRadius: number): Sdf;
+
+    /**
+     * Torus ring cut down to an arc. `cap_angle_degrees` is the half-aperture
+     * in `(0, 180]`, measured from +X and mirrored across X; `180` is a full
+     * torus.
+     */
+    static cappedTorus(majorRadius: number, minorRadius: number, capAngleDegrees: number): Sdf;
+
+    /**
+     * Chain-link shape: a torus stretched along Z by `half_length` and
+     * capped by two half-tori. `half_length: 0` is a plain torus.
+     */
+    static link(majorRadius: number, minorRadius: number, halfLength: number): Sdf;
+
+    static capsule(ax: number, ay: number, az: number, bx: number, by: number, bz: number, radius: number): Sdf;
+
+    /**
+     * Convex hull of two spheres: a capsule with a linear taper between
+     * `r1` (at `a`) and `r2` (at `b`) instead of one constant radius.
+     */
+    static roundCone(ax: number, ay: number, az: number, bx: number, by: number, bz: number, r1: number, r2: number): Sdf;
+
+    /**
+     * Sphere of `radius` intersected with an infinite cone of
+     * half-aperture `angle_degrees` (in `(0, 180)`) from the +Y axis,
+     * apex at the origin.
+     */
+    static solidAngle(radius: number, angleDegrees: number): Sdf;
+
+    /**
+     * Sphere cut by the plane `y = height`, keeping the cap above it
+     * (a dome). `height` must be strictly between `-radius` and
+     * `radius`.
+     */
+    static cutSphere(radius: number, height: number): Sdf;
+
+    /**
+     * Open (hollow) shell of `cut_sphere`'s dome: just the spherical
+     * cap surface, offset by `thickness`, with no flat floor.
+     */
+    static cutHollowSphere(radius: number, height: number, thickness: number): Sdf;
+
+    static cappedCylinder(radius: number, halfHeight: number): Sdf;
+
+    /**
+     * Exact Y-axis cylinder with infinite extent. Sampling requires explicit bounds.
+     */
+    static infiniteCylinder(radius: number): Sdf;
+
+    static cappedCone(halfHeight: number, bottomRadius: number, topRadius: number): Sdf;
+
+    static plane(normalX: number, normalY: number, normalZ: number, offset: number): Sdf;
+
+    static octahedron(size: number): Sdf;
+
+    static hexPrism(radius: number, halfHeight: number): Sdf;
+
+    static superPrism(halfX: number, halfY: number, halfZ: number, exponent: number): Sdf;
+
+    /**
+     * Hollow wireframe box: only the 12 edge beams are solid.
+     */
+    static boxFrame(halfX: number, halfY: number, halfZ: number, thickness: number): Sdf;
+
+    /**
+     * Exact but unbounded Y-axis infinite cone: apex at the origin,
+     * single nappe opening along +Y, half-aperture `angle_degrees`
+     * strictly in `(0, 90)`.
+     */
+    static infiniteCone(angleDegrees: number): Sdf;
+
+    /**
+     * Square-base pyramid, vertically centered: base (half-extent
+     * `half_base`) at `y = -height/2`, apex at `y = height/2`. `height`
+     * must be at least the smallest positive normal `f32`.
+     */
+    static squarePyramid(halfBase: number, height: number): Sdf;
+
+    static cells(frequency: number, seed: number, jitter: number, mode: SdfCellMode, threshold: number): Sdf;
+
+    unionWith(other: Sdf): Sdf;
+
+    intersectionWith(other: Sdf): Sdf;
+
+    subtract(other: Sdf): Sdf;
+
+    smoothUnion(other: Sdf, radius: number): Sdf;
+
+    smoothSubtract(other: Sdf, radius: number): Sdf;
+
+    smoothIntersection(other: Sdf, radius: number): Sdf;
+
+    rounded(radius: number): Sdf;
+
+    shell(thickness: number): Sdf;
+
+    /**
+     * Symmetric difference (XOR): solid where exactly one of `self`/
+     * `other` is solid.
+     */
+    xorWith(other: Sdf): Sdf;
+
+    /**
+     * Stretches this graph with IQ's origin-centered `opElongate` fold.
+     * Exactness requires a suitable origin-centered, reflection-symmetric
+     * child; off-center/asymmetric children are mirrored and produce only
+     * an estimate. Half-lengths must be finite and non-negative, with at
+     * least one strictly positive.
+     */
+    elongate(halfX: number, halfY: number, halfZ: number): Sdf;
+
+    translate(x: number, y: number, z: number): Sdf;
+
+    rotate(xDegrees: number, yDegrees: number, zDegrees: number): Sdf;
+
+    scale(factor: number): Sdf;
+
+    mirror(axis: SdfAxis): Sdf;
+
+    /**
+     * Twists this graph about the Y axis by `amount` radians per unit
+     * Y (IQ's `opTwist`). *Distorted*: not guaranteed exact even when
+     * `self` is.
+     */
+    twist(amount: number): Sdf;
+
+    /**
+     * Cheaply bends this graph by `amount` radians per unit X (IQ's
+     * `opCheapBend`). *Distorted*: not guaranteed exact even when
+     * `self` is.
+     */
+    bend(amount: number): Sdf;
+
+    repeatInfinite(spacingX: number, spacingY: number, spacingZ: number): Sdf;
+
+    repeatCounted(spacingX: number, spacingY: number, spacingZ: number, countX: number, countY: number, countZ: number): Sdf;
+
+    /**
+     * Finite rigid instances of this graph at arbitrary XYZ offsets.
+     * `offsets` is flat `[x0, y0, z0, x1, y1, z1, ...]` and may contain
+     * at most 4096 points.
+     */
+    repeatPoints(offsets: Array<number>): Sdf;
+
+    displace(amplitude: number, frequency: number, seed: number, octaves: number): Sdf;
+
+    /**
+     * Offset this surface by a reusable scalar field. The resulting zero
+     * set is generally an approximate field, not an exact distance field.
+     */
+    offsetByField(field: Field3, amplitude: number): Sdf;
+
+    warp(amplitude: number, frequency: number, seed: number): Sdf;
+
+    evalAt(x: number, y: number, z: number): number;
+
+    normal(x: number, y: number, z: number, epsilon: number): SdfNormal;
+
+    /**
+     * Conservative finite bounds, or `NotFound` for an unbounded graph
+     * (a bare `plane` or `infinite_cylinder` has no finite extent).
+     */
+    bounds(): SdfBounds;
+
+    toShape(): Shape;
+
+    toShapeBounded(minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): Shape;
+
+    static fromJsonString(json: string): Sdf;
+
+    toJson(): string;
+
+    /**
+     * Wrap a validated {@link FieldProgram} as an `Sdf` graph (cloning it,
+     * with its own explicit bounds and distance-kind metadata), so it
+     * composes with every other combinator.
+     */
+    static fromProgram(program: FieldProgram): Sdf;
+
     /**
-     * Builds a schematic by sampling an SDF JSON tree with material rules JSON.
-     * Sample an SDF tree into a schematic using the tree's own AABB —
-     * the ergonomic path for bounded trees (all primitives except
-     * `plane`). Fails with `InvalidArgument` for unbounded trees; use
-     * `schematic_from_sdf` with explicit bounds for those.
+     * Legacy JSON-first terrain helper. Prefer typed constructors and
+     * `to_shape()` with `BuildingTool.fill()` for new code.
      */
     static schematicFromSdfAuto(sdfJson: string, rulesJson: string): Schematic;
 
     /**
-     * When `has_bounds` is false the tree's own AABB is used (fails with
-     * `InvalidArgument` for unbounded trees) and the `min_*`/`max_*` arguments
-     * are ignored.
+     * Legacy JSON-first terrain helper with optional explicit bounds.
      */
     static schematicFromSdf(sdfJson: string, rulesJson: string, hasBounds: boolean, minX: number, minY: number, minZ: number, maxX: number, maxY: number, maxZ: number): Schematic;
 
     /**
-     * Evaluates an SDF JSON tree at a point, returning the signed distance.
+     * Legacy JSON-first evaluator. Prefer `Sdf.from_json_string(...).eval_at(...)`.
      */
     static eval(sdfJson: string, x: number, y: number, z: number): number;
 }