Contour Extract ​

Extract contour lines (iso-curves) from a ScalarField at a given threshold, using marching squares. Turns any scalar field into a shape at a level set.

Category: Shapes Menu path: Shapes > Contour Extract

Ports ​

PortTypeDirectionDescription
field_inscalarFieldinputScalar field to extract contours from
outshapeoutputExtracted contour(s) as a shape

Parameters ​

ParamTypeDefaultDescription
thresholdscalar0.5Level-set value. Contour traces where field == threshold. Keyframeable.
resolutionscalar128Grid samples along the longer axis. Higher = smoother, quadratically more work. Clamped [4, 512].
outputenumBezierBezier fits Catmull-Rom cubic beziers through the contour for smooth curves. Polyline emits straight-line segments (faceted, fastest).

Expose Channels ​

When enabled (E button on node header), adds input ports that override params via edge connections:

PortTypeOverrides
threshold_inscalarthreshold
resolution_inscalarresolution

Useful for chaining a Time or Math node into threshold_in to sweep through level sets (animated topo reveal), or feeding an adaptive scalar into resolution_in to dynamically trade quality for speed.

How It Works ​

Contour Extract samples the input ScalarField on a regular grid covering the composition bounds, then runs marching squares to trace the iso-curve at threshold:

  1. For each cell in the grid, the four corners are classified as "inside" (≥ threshold) or "outside" (< threshold) — 16 possible configurations.
  2. Each configuration emits 0, 1, or 2 line segments crossing the cell. Endpoints are linearly interpolated along cell edges where the threshold is crossed.
  3. Saddle configurations (two diagonally-opposite inside corners) are disambiguated by sampling the cell center.
  4. Adjacent cells share edges by construction, so segments chain into continuous polylines.
  5. Closed loops (interior contours) produce closed paths; chains reaching the grid boundary produce open paths.

With output = Bezier, the final polyline is re-fit to cubic beziers via Catmull-Rom interpolation, so smooth fields produce smooth output without needing a downstream ResampleShape.

Output caveats ​

  • No PointId stability. As the field animates, contours can merge, split, appear, or disappear. Output PointIds regenerate every frame.
  • Sampling bounds are the composition's base resolution, origin-centered. Fields whose interesting features fall outside the comp bounds will get clipped at the edges.
  • Fill rule is always NonZero on output. Multiple nested contours (a contour with holes) will render correctly when winding is preserved.

Usage Examples ​

Metaballs ​

Circle A ──► DistanceField ──► ScalarField.out ─┐
                                                 ├──► FieldMath (SmoothMin, t=0.3) ──► ContourExtract (threshold: 0.5) ──► DrawShape
Circle B ──► DistanceField ──► ScalarField.out ─┘

Two circles that attract and merge when they get close (SmoothMin blends their distance fields smoothly). Animate the circle positions for classic metaball motion.

Topo lines ​

Noise (scalarField) ──► ContourExtract (threshold: 0.3) ──► DrawShape
Noise (scalarField) ──► ContourExtract (threshold: 0.5) ──► DrawShape
Noise (scalarField) ──► ContourExtract (threshold: 0.7) ──► DrawShape

Three contour nodes at different thresholds on the same noise field → stack of topo lines like a contour map.

Blob text ​

Text("HI") ──► TextToShape ──► DistanceField ──► FieldMath (SmoothMin, k=10) ←── DistanceField ←── Text("HI")
                                                         │
                                                         └──► ContourExtract ──► DrawShape

Rough equivalent — fatten letterforms into blob silhouettes via SDF blending. Great for animated title reveals.

Voronoi region edges ​

Voronoi (scalarField, mode: F2-F1) ──► ContourExtract (threshold: 0.02) ──► DrawShape

Extract cell boundaries as vector paths — Voronoi diagrams rendered as strokable shapes instead of textures.

Noise-driven organic silhouette ​

Noise ──► Remap (curve: wave) ──► ContourExtract (threshold: 0.5) ──► DrawShape

Organic, noise-driven closed shapes for marker blobs, paint splats, or abstract motion-graphics fills.

Tips ​

  • Start at 128 resolution — good balance of smoothness and speed at 1080p. Crank to 256 or 512 for extreme closeup; drop to 64 for previewing complex field chains.
  • Animate threshold for "reveal from inside out" effects on SDFs. For DistanceField output, threshold 0 is at the shape boundary; lower values are outside, higher are inside.
  • Pair with OffsetPath downstream to grow/shrink the contour by a fixed amount after extraction.
  • Multi-threshold passes need separate nodes in v1 — connect one scalar field to N ContourExtract nodes, each with a different threshold. (A multi-output variant may come later.)
  • Topology changes are silent. If the field evolves through a merge or split, the output path count jumps — downstream PointId-keyed nodes will desync on that frame. This is unavoidable for contour extraction, same limitation as ShapeBoolean.
  • DistanceField — produces SDFs, the most common input for ContourExtract
  • Noise — scalar noise → topo lines
  • Voronoi — F2-F1 mode produces cell-boundary scalar fields
  • FieldMath — SmoothMin / SmoothMax / Add / Multiply to blend multiple fields before contouring
  • ShapeBoolean — alternative for hard-edged shape combining (no smoothness); contouring blended SDFs gives soft metaball-style merging
  • ResampleShape — resample the extracted contour for even vertex spacing

© 2026 Caddis