Field Types

Overview

XelToFab supports two types of input scalar fields, configured via the field_type parameter:

Density fields

Density fields contain continuous values in [0, 1] where higher values indicate material presence. This is the standard output format from topology optimization solvers such as SIMP and BESO.

from xeltofab.state import PipelineParams

params = PipelineParams(field_type="density")  # this is the default

Default behavior for density fields

• Preprocessing is enabled -- The field is Gaussian-smoothed, thresholded to binary, and cleaned with morphological operations
• smooth_sigma = 1.0 -- Gaussian smoothing helps reduce noise in the scalar field before binarization
• direct_extraction = False -- Extraction operates on the preprocessed binary field
• Extraction level = threshold (default 0.5) -- The extraction isovalue

This pipeline works well for raw design optimization output where density values may be noisy or have intermediate values that need cleanup.

SDF fields

Signed distance fields encode the distance to the surface boundary. By convention, negative values are inside the object and positive values are outside (or vice versa depending on the model). The surface is at the zero level set.

from xeltofab.state import PipelineParams

params = PipelineParams(field_type="sdf")

Smart defaults for SDF fields

When field_type="sdf" is set, the pipeline automatically adjusts defaults (unless you explicitly override them):

• direct_extraction = True -- Preprocessing is skipped. SDF fields are typically clean continuous outputs that do not benefit from thresholding or morphological operations
• smooth_sigma = 0.0 -- Gaussian preprocessing is disabled. The field is already smooth
• Extraction level = 0.0 -- The zero level set, which is the surface boundary in an SDF
• extraction_method = "dc" -- Dual contouring leverages SDF gradients for sharp feature preservation
• smoothing_method = "bilateral", taubin_iterations = 5 -- Reduced smoothing for DC to preserve sharp features (vs taubin/20 for MC)

Overriding SDF defaults

The smart defaults only apply to values you have not explicitly set. You can override any of them:

# SDF field, but keep Gaussian smoothing at sigma=0.5
params = PipelineParams(field_type="sdf", smooth_sigma=0.5)

# SDF field with preprocessing enabled
params = PipelineParams(field_type="sdf", direct_extraction=False)

Extraction level

The extraction level is the isovalue passed to the extraction method (MC, DC, SurfNets, or manifold for 3D) or find_contours (2D). It determines which isosurface in the field becomes the mesh boundary.

The default depends on field type:

Override it explicitly for non-standard cases:

# Extract at a lower density threshold
params = PipelineParams(threshold=0.3)

# Extract SDF at a non-zero offset (expand/shrink the surface)
params = PipelineParams(field_type="sdf", extraction_level=0.1)

The effective level is always available via params.effective_extraction_level.

When to use each type

Use density (default) when:

• Your input comes from a design optimization solver (e.g., SIMP, BESO, evolutionary methods)
• Values represent material density or occupancy probability in [0, 1]
• The field may have noise, intermediate values, or disconnected artifacts that need cleanup

Use sdf when:

• Your input comes from a neural implicit model (DeepSDF, NITO, NTopo, neural radiance fields)
• Values represent signed distance to the surface
• The field is already smooth and continuous -- preprocessing would degrade quality
• You want the zero level set as the surface
• Your input is a callable function (neural SDF, analytical formula) — use process_from_sdf() with adaptive=True for large grids