Primitives, SDFs, and CSG

Overview

Every shape in Rasmah is built by starting from a small set of primitives — sphere, box, cylinder, and so on — and then combining them with constructive solid geometry (CSG) and transforms. This chapter introduces each primitive, shows how its signed distance field represents it exactly, and then shows how to cut, merge, move, scale, and rotate shapes.

The big idea is that a whole solid can be described by a single scalar function $s(\mathbf{x})$ (its SDF). A boolean operation between two shapes is then nothing more than a min or a max of their two fields. The catch is that a min/max is only piecewise smooth: it is continuous, but it has a kink — a sharp crease — exactly where the two surfaces cross, where $s_a = s_b$. So the combined field is differentiable almost everywhere, not everywhere. That is usually enough to keep the CAD → mesh → simulation chain differentiable in practice; where a rounded transition is wanted instead of a crease, the soft booleans smooth_union / smooth_intersection / smooth_difference replace the hard min/max with a smooth blend.

The primitives

Each primitive has an exact signed distance field and an analytic (closed form) volume, so the geometry never depends on how finely you sample it.

Sphere

Rasmah.sphere — Function

sphere(r)

Construct a solid sphere of radius r, centred at the origin.

A sphere is the set of points whose distance from its centre is at most r. As a signed distance field (SDF) it is the exact field

\[s(\mathbf{x}) = \|\mathbf{x}\| - r,\]

which is negative inside, zero on the surface, and positive outside. Because $|s(\mathbf{x})|$ is the shortest distance to the surface, the gradient $\nabla s = \mathbf{x}/\|\mathbf{x}\|$ has unit length almost everywhere — this is the defining property of an exact SDF, and it is what keeps the field well-behaved when it is fed to meshing, ray casting, or gradient.

Arguments

r::Real (or a unit-aware Quantity length): the sphere radius.

Returns

A Sphere feature node. Feed it to brep for the exact topology, to evaluate(…, MeshBackend(…)) for a mesh, or read its analytic volume / bounds.

Example

A bare number is interpreted in SI base units, and an explicit Quantity gives the same result. A quantity is written by appending the u"…" string macro to a number — 2u"m" is 2 metres, 10u"mm" is 10 millimetres, and so on; the notation is covered in the Units chapter:

julia> volume(sphere(2))
33.510321638291124 m^3

julia> volume(sphere(2u"m"))
33.510321638291124 m^3

julia> bounds(evaluate(sphere(2), SDFBackend())) == ([-2, -2, -2], [2, 2, 2])
true

julia> vtk(sphere(2.0))   # interactive VTK.js viewer (inline in Jupyter/Quarto)
VTKView(640×480, inline)

The analytic volume is $4\pi r^{3}/3$, so its derivative with respect to the radius is the surface area $4\pi r^{2}$. With a unitless radius the derivative keeps the output's volume units, while an explicit length gives area:

julia> derivative(r -> volume(sphere(r)), 2.0)
50.26548245743669 m^3

julia> derivative(r -> volume(sphere(r)), 2.0u"m")
50.26548245743669 m^2