Mathias Bernhard

Axolotl for plugin developers

This is for Grasshopper plugins that build on Axolotl, either by providing their own distance objects (implementing IHasDistance) or by evaluating Axolotl objects in their own components.

The evaluation engine was reworked for Axolotl 2.0. It is parallel and batched. It skips regions far from the surface and simplifies the object tree per region. It also computes exact gradients and can mesh with sharp features. All of this is opt-in through optional interfaces: existing plugins keep working without changes, but only objects that implement the new interfaces benefit fully.

1. What stays compatible

Breaking changes in helper APIs

Code that calls these directly has to be updated and recompiled:

Removed / changed Use instead
MarchingCube2 (class) MarchingCube.Polygonize
MarchingCube.MarchingCubesParallelMesh(...) MarchingCube.MarchingCubesMesh(...) (now parallel) or MarchingCube.Polygonize
Octree(float x, float y, float z, float size) Octree(double x, double y, double z, double size)
Octree.root, Octree.OctNode, Octree.MakeCube removed; use Octree.DivideForMesh / DivideRaw
GradientVector.GetGradient(..., unit: false) returned 4·eps·gradient returns the actual gradient

2. Thread safety (please check)

GetDistance is now called from many threads at the same time, by every mesher, Dense Grid, Evaluate Points and Slice. Before, the default mesher ran on a single thread.

3. Providing distance objects: the optional interfaces

All interfaces are in namespace Axolotl. Implement as many as make sense; each one is independent. Without them your object is a black box: in any tree it is part of, there is no narrow band, no pruning of or below your object, finite-difference normals and one virtual call per point.

Interface Effort Benefit
ILipschitzBound one line narrow band (regions far from the surface are skipped)
IHasBounds a few lines large unions skip your object far away (bounding volume hierarchy)
IHasChildren one line (combinators / modifiers) subtrees used several times are evaluated once
IIntervalBound a method tighter narrow band, also for non-distance fields; pruning
IHasGradient a method exact normals (Dual Contouring Adaptive keeps sharp edges)
IHasDistanceBatch a method less call overhead, room for SIMD

Contracts

Axolotl relies on these guarantees for correctness, not just speed. A wrong bound can make meshes miss geometry, so only claim what holds everywhere.

Example: a primitive

using System;
using Rhino.Geometry;
using Axolotl;

public class MyBall : IHasDistanceBatch, ILipschitzBound, IHasBounds, IIntervalBound, IHasGradient
{
    readonly double cx, cy, cz, r;   // immutable: the object is shared between threads

    public MyBall(Point3d center, double radius) { cx = center.X; cy = center.Y; cz = center.Z; r = radius; }

    public double GetDistance(double x, double y, double z)
    {
        double dx = x - cx, dy = y - cy, dz = z - cz;
        return Math.Sqrt(dx * dx + dy * dy + dz * dz) - r;
    }

    public void GetDistances(double[] x, double[] y, double[] z, double[] result, int count)
    {
        for (int i = 0; i < count; i++) result[i] = GetDistance(x[i], y[i], z[i]);
    }

    public double Lipschitz { get { return 1; } }   // exact distance field

    public bool TryGetBounds(out BoundingBox bounds)
    {
        bounds = new BoundingBox(cx - r, cy - r, cz - r, cx + r, cy + r, cz + r);
        return r >= 0;
    }

    public ValueRange Bound(Region region, bool prune, out IHasDistance pruned)
    {
        pruned = this;   // a primitive cannot be simplified
        double near = Distance.BoxDistance(region.ToBoundingBox(), cx, cy, cz);
        double fx = Math.Max(Math.Abs(region.X.Lo - cx), Math.Abs(region.X.Hi - cx));
        double fy = Math.Max(Math.Abs(region.Y.Lo - cy), Math.Abs(region.Y.Hi - cy));
        double fz = Math.Max(Math.Abs(region.Z.Lo - cz), Math.Abs(region.Z.Hi - cz));
        return new ValueRange(near - r, Math.Sqrt(fx * fx + fy * fy + fz * fz) - r);
    }

    public double GetGradient(double x, double y, double z, double eps, out double gx, out double gy, out double gz)
    {
        double dx = x - cx, dy = y - cy, dz = z - cz;
        double l = Math.Sqrt(dx * dx + dy * dy + dz * dz);
        if (l > 0) { gx = dx / l; gy = dy / l; gz = dz / l; } else { gx = gy = gz = 0; }
        return l - r;
    }
}

Note: If you create your own distance object class (like MyBall above) in a C# component inside Grasshopper, you want to add the line #r "Axolotl.gha" to the top of your region Usings and explicitly call the first argument in ValueRange with the namespace Axolotl.Region to disambiguate from System.Drawing.Region.

For a primitive, ILipschitzBound alone already enables the narrow band (Axolotl derives d(centre) ± L · radius for every region). IIntervalBound is optional; implement it when it can be tighter, or for fields without a Lipschitz bound.

Example: a combinator (with pruning)

public class MyMin : IHasDistanceBatch, ILipschitzBound, IHasChildren, IIntervalBound, IHasGradient
{
    readonly IHasDistance a, b;
    public MyMin(IHasDistance a, IHasDistance b) { this.a = a; this.b = b; }

    public double GetDistance(double x, double y, double z) { return Math.Min(a.GetDistance(x, y, z), b.GetDistance(x, y, z)); }

    public void GetDistances(double[] x, double[] y, double[] z, double[] result, int count)
    {
        double[] tmp = Scratch.Rent(count);
        Distance.Evaluate(a, x, y, z, result, count);
        Distance.Evaluate(b, x, y, z, tmp, count);
        for (int i = 0; i < count; i++) result[i] = Math.Min(result[i], tmp[i]);
        Scratch.Return(tmp);
    }

    public double Lipschitz { get { return Distance.MaxLipschitz(a, b); } }
    public IHasDistance[] Children { get { return new[] { a, b }; } }

    public ValueRange Bound(Region region, bool prune, out IHasDistance pruned)
    {
        IHasDistance pa, pb;
        ValueRange ra = Distance.Bound(a, region, prune, out pa);
        ValueRange rb = Distance.Bound(b, region, prune, out pb);
        if (ra.Lo >= rb.Hi) { pruned = pb; return rb; }   // b is the minimum everywhere in the region
        if (rb.Lo >= ra.Hi) { pruned = pa; return ra; }   // a is the minimum everywhere in the region
        bool changed = !ReferenceEquals(pa, a) || !ReferenceEquals(pb, b);
        pruned = prune && changed ? new MyMin(pa, pb) : (IHasDistance)this;
        return ValueRange.Min(ra, rb);
    }

    public double GetGradient(double x, double y, double z, double eps, out double gx, out double gy, out double gz)
    {
        IHasDistance winner = a.GetDistance(x, y, z) <= b.GetDistance(x, y, z) ? a : b;
        return Distance.Gradient(winner, x, y, z, eps, out gx, out gy, out gz);
    }
}

Note: if you create this new combination type in a C# component inside Grasshopper, you can cast the inputs (other Axolotl distance objects) to create the new object like so:

private void RunScript(object x, object y, ref object a)
{
    a = new MyMin((IHasDistance)x, (IHasDistance)y);
}

Wrapping Axolotl objects

If your object wraps another distance object (an offset, a custom deformation, a transform), forward the capabilities. Otherwise everything inside the wrapper loses them. Use the helpers, which work for operands with and without the interfaces:

public double Lipschitz { get { return Distance.Lipschitz(inner); } }   // adjust if you stretch space

public ValueRange Bound(Region region, bool prune, out IHasDistance pruned)
{
    IHasDistance p;
    ValueRange r = Distance.Bound(inner, region, prune, out p);  // map the region first if you transform space
    pruned = prune && !ReferenceEquals(p, inner) ? new MyOffset(p, offset) : (IHasDistance)this;
    return r - offset;
}

For space transformations, map the region into the frame of the wrapped object (region.Transform(affine) for affine maps; Affine is a fast copy of a Rhino Transform), and multiply the gradient by the transposed linear part (affine.ApplyTranspose).

Useful types

4. Evaluating Axolotl objects in your own components

Calling GetDistance point by point keeps working, but bypasses the engine. Use these instead:

Task API
values on a grid (parallel, batched, pruned, optional narrow band) GridSampler.Sample(d, GridSpec.FromBounds(box, nx, ny, nz), new SampleOptions { NarrowBand = true, Iso = iso }, out stats)
values near the surface only (memory grows with the surface, for very fine grids) GridSampler.SampleSparse(d, grid, new SampleOptions { NarrowBand = true, Iso = iso }, maxPoints, out stats) returns a SparseGrid
values at arbitrary points (parallel, batched) GridSampler.SamplePoints(d, points, null)
a batch of points Distance.Evaluate(d, xs, ys, zs, result, count)
value and gradient Distance.Gradient(d, x, y, z, eps, out gx, out gy, out gz)
range over a box, simplified tree for that box Distance.Bound(d, region, true, out pruned)
marching cubes on sampled values (welded, parallel) MarchingCube.Polygonize(values, grid, iso, refine, parallel, cancel)
sharp-feature / adaptive meshing AdaptiveDualContouring.Build(sparseGrid, d, tolerance, manifold, parallel, cancel, out vertices, out faces) then MeshAssembly.Build(vertices, faces, refine) (an overload takes dense values, grid, iso)
smooth dual contouring / surface nets DualMesher.Build(values, grid, iso, d, iterations, clampToCell, manifold, refine, parallel, cancel)

manifold = true gives a cell crossed by several separate pieces of the surface one vertex per piece (CellTopology), so thin walls and near-touching parts give no non-manifold edges. The overloads without the parameter keep the earlier one-vertex-per-cell behaviour.

Note: with NarrowBand = true, values far from the isosurface are bounds, not exact distances (they only have the correct sign). Use NarrowBand = false (default) when you need the exact values everywhere, for example for your own post-processing.

Sampled grids can be passed between components as GooDistanceGrid (a DistanceGrid: GridSpec + double[]). The Dense Grid, Blur and Isosurface Distance Field components read and write it.

GridSpec grid = GridSpec.FromBounds(box, n, n, n);
SampleStats stats;
double[] values = GridSampler.Sample(d, grid, new SampleOptions { NarrowBand = true, Iso = 0 }, out stats);
Mesh mesh = MarchingCube.Polygonize(values, grid, 0, true, true, CancellationToken.None);

5. Grasshopper side: parameters, inputs, geometry, scripting

Task API
typed inputs / outputs (hidden from the toolbar, shown in tooltips and to RhinoAI) Param_DistanceObject, Param_CoordinateMap, Param_DistanceGrid, e.g. pManager.AddParameter(new Param_DistanceObject(), "Distance Object", "D", "...", GH_ParamAccess.item)
an input that takes a number or a field FieldInput.Configure(pManager[pManager.AddGenericParameter(...)], defaultValue), then FieldInput.Get(this, DA, i, out value, out field) (field is null for a plain number)
any Rhino / Grasshopper geometry as a distance object var c = new GeometryConverter(WrapMode.Auto, tolerance, sign); c.Add(item); ...; IHasDistance d = c.Result(); (null if nothing converted; c.Log says what each item became)
a 2D profile swept along a rail new SweepProfile(rail, profile, endProfile, plane, twist)
operator expressions from C# or Python Sdf: (Sdf.Sphere(10) & Sdf.Box(15, 15, 15, 1)) - c, .K(r) smooths the boolean before it; Sdf.FromGeometry(...), Sdf.Sweep(...), .F is the IHasDistance
text expressions SdfExpression looks up function and method names on Sdf by reflection, so a public static or instance method added to Sdf is available in the Expression component without further code

Any Axolotl input also accepts an Sdf or a plain IHasDistance from a script component (GooHasDistance.CastFrom).

Menu choices are saved in .gh files as indices. Lists such as TPMS.Names, Mapped.Corrections or TransferFunction.Names may only be appended to; inserting or reordering changes what old files produce.

6. Versioning

Implementing the new interfaces or calling the APIs above means compiling against Axolotl 2.0, so your plugin then requires that version (or later). Objects that only implement IHasDistance keep working with old and new versions.