SDF Shape Catalogue

Visual reference: Inigo Quilez — 3D Distance Functions

What is an SDF?

A signed distance function returns the distance from any point in space to the nearest surface of a shape — negative inside, zero on the surface, positive outside. That distance becomes the input to a force curve: closer to the surface means more force, farther away means none.

SDF shapes are used by the Navigation module (bubble shape).

A shape is described by a primitive and a parameters block:

{
  "shape": {
    "primitive": "sphere",
    "parameters": { "r": 0.05 }
  }
}

Basic shapes

Primitive	Parameters	Notes
sphere	r (radius)	Simplest shape
ellipsoid	a (semi-axis radii as vec3)	Approximate SDF; accurate for forces
box	b (half-extents as vec3)	Axis-aligned
rounded_box	b (half-extents), r (corner radius)	Total extent = b + r
box_frame	b (half-extents), e (edge thickness)	Wireframe outline of a box
plane	n (normal vec3), h (offset along n)	Infinite half-space; n must be normalised

Capsules and cylinders

Primitive	Parameters	Notes
capsule	a, b (endpoint positions as vec3), r (radius)	Hemispherical caps
capsule_vertical	h (half-height), r (radius)	Y-axis shorthand
capped_cylinder	a, b (axis endpoints as vec3), r (radius)	Flat end caps
capped_cylinder_vertical	h (half-height), r (radius)	Y-axis shorthand

Torus family

Primitive	Parameters	Notes
torus	r1 (major radius), r2 (tube radius)	Donut in the XZ plane
capped_torus	sc (cap direction as vec2), r1, r2	Arc; sc = (cos θ, sin θ)
link	le (half-length), r1 (ring radius), r2 (tube radius)	Chain-link shape

Cones

Primitive	Parameters	Notes
cone	c (angle as vec2 (sin α, cos α)), h (height)	Infinite cone clipped at tip
capped_cone	a, b (endpoints as vec3), r1 (base radius), r2 (top radius)	Frustum
rounded_cone	a, b (endpoints as vec3), r1, r2	Frustum with spherical caps
solid_angle	c (angle as vec2), r (radius)	Sphere sliced by a cone

Exotic shapes

Primitive	Parameters	Notes
vesica_revolved	a, b (axis as vec3), w (width)	Lens shape
rhombus	la, lb (half-diagonals), h (extrusion half-height), r (rounding)	Diamond cross-section
pyramid	h (height)	Square base
octahedron	r (inradius)	Regular octahedron
hexagonal_prism	r (circumradius), h (half-height)	Along Y
triangular_prism	w (half-width), h (half-height)	Along Z

Parameter types

Scalar parameters (r, h, e, etc.) are plain numbers. Vector parameters (a, b, n) are objects: { "x": 0.0, "y": 0.0, "z": 0.0 }. Vec2 parameters (c, sc) are objects: { "x": 0.707, "y": 0.707 }.

JSON examples

Sphere:

{ "primitive": "sphere", "parameters": { "r": 0.05 } }

Ellipsoid (wider X/Z):

{ "primitive": "ellipsoid", "parameters": { "a": { "x": 0.06, "y": 0.03, "z": 0.06 } } }

Box:

{ "primitive": "box", "parameters": { "b": { "x": 0.04, "y": 0.02, "z": 0.04 } } }

Rounded box:

{ "primitive": "rounded_box", "parameters": { "b": { "x": 0.30, "y": 0.02, "z": 0.30 }, "r": 0.01 } }

Capsule:

{
  "primitive": "capsule",
  "parameters": {
    "a": { "x": 0.0, "y": -0.03, "z": 0.0 },
    "b": { "x": 0.0, "y":  0.03, "z": 0.0 },
    "r": 0.04
  }
}

Plane (boundary along +X):

{ "primitive": "plane", "parameters": { "n": { "x": 1.0, "y": 0.0, "z": 0.0 }, "h": 0.0 } }

Torus:

{ "primitive": "torus", "parameters": { "r1": 0.08, "r2": 0.02 } }

Capped cone (frustum):

{
  "primitive": "capped_cone",
  "parameters": {
    "a": { "x": 0.0, "y": -0.05, "z": 0.0 },
    "b": { "x": 0.0, "y":  0.05, "z": 0.0 },
    "r1": 0.04, "r2": 0.01
  }
}

If an unsupported primitive is supplied, the service falls back to a distance-from-origin sphere-like evaluation.