Parameters

PipelineParams reference

All pipeline behavior is configured through PipelineParams, a Pydantic model defined in xeltofab.state.

from xeltofab.state import PipelineParams

params = PipelineParams(
    threshold=0.5,
    smooth_sigma=1.0,
    morph_radius=1,
    taubin_iterations=20,
    taubin_lambda=0.5,
    smoothing_method="taubin",   # or "bilateral"
    field_type="density",
    direct_extraction=False,
    extraction_level=None,
    repair=True,
    remesh=True,
    decimate=True,
    decimate_ratio=0.5,
)

Full parameter table

Computed property

Smart defaults by field type

When field_type="sdf" is set, certain parameters are automatically adjusted unless you explicitly provide a value:

These overrides only apply when the parameter was not explicitly passed. If you set smooth_sigma=0.5 with field_type="sdf", your value is preserved.

Parameter tuning tips

Threshold

• Lower threshold (0.3-0.4): Includes more material, produces thicker features. Use when the solver was aggressive with material removal
• Higher threshold (0.6-0.7): Excludes more material, produces thinner features. Use when the solver left too much intermediate density
• The threshold only applies when direct_extraction=False

Gaussian sigma

• smooth_sigma=0.0: No Gaussian smoothing. Use for clean or already-smoothed fields
• smooth_sigma=0.5-1.0: Light smoothing. Good for most design optimization results
• smooth_sigma=2.0+: Heavy smoothing. Blurs fine features but removes more noise. Be cautious of thin features being smoothed away

Morphological radius

• morph_radius=0: Disabled. Use when the field is clean or when you need to preserve fine detail
• morph_radius=1: Default. Removes single-voxel noise and fills single-voxel holes
• morph_radius=2-3: More aggressive cleanup. Can merge nearby features or break thin connections

Taubin smoothing

• taubin_iterations=0: Disabled. Raw extraction output (staircase artifacts for MC, sharper for DC)
• taubin_iterations=10-20: Moderate smoothing. Good balance between quality and feature preservation
• taubin_iterations=50+: Heavy smoothing. Produces very smooth surfaces but may lose sharp features
• taubin_lambda: Controls smoothing strength per iteration. The default of 0.5 works well for most cases. Lower values (0.1-0.3) produce gentler smoothing

Bilateral smoothing

Use smoothing_method="bilateral" when the mesh has sharp features (corners, ridges, thin walls) that should be preserved during smoothing:

• bilateral_iterations=5-10: Default range. Fewer iterations than Taubin because bilateral filtering is more aggressive per iteration
• bilateral_iterations=1-3: Very light smoothing. Good for meshes that are already reasonably smooth
• bilateral_sigma_s: Controls how far the filter reaches. None (default) auto-computes from average edge length, which works well for most meshes. Set explicitly when you need finer control
• bilateral_sigma_n=0.35: Default. Edges with >~40° normal deviation are preserved. Lower values (0.1-0.2) preserve more features but smooth less. Higher values (0.5-1.0) smooth more aggressively across features
• When to use bilateral over Taubin: Bilateral filtering is best when the mesh has both smooth regions and sharp structural features. On uniformly smooth meshes (like spheres), Taubin produces comparable or better results with less volume drift

Decimation

QEM decimation reduces face count after remeshing. It runs by default with decimate_ratio=0.5 (50% reduction):

• decimate=False or --no-decimate: Skip decimation entirely. Use when you need maximum geometric fidelity or the mesh is already at an acceptable face count
• decimate_ratio=0.3: Keep only 30% of faces. Good for lightweight visualization meshes
• decimate_ratio=0.8: Keep 80% of faces. Minimal reduction, maximum quality
• target_faces=10000: Set an absolute face count limit. Useful when targeting a specific polygon budget for FEA or rendering
• decimate_aggressiveness=3-5: Conservative decimation, slower but preserves more detail
• decimate_aggressiveness=7-10: Aggressive decimation, faster with more approximation error

Direct extraction

Enable direct_extraction=True when:

• The input field is a clean SDF (automatically enabled for field_type="sdf")
• The solver has fully converged and density values are near 0 or 1
• You want to control the exact isovalue via extraction_level

CLI mapping

CLI flags map to PipelineParams fields:

The CLI preserves smart defaults: if you pass --field-type sdf without --sigma or --direct, the SDF defaults are applied automatically.

Parameters not exposed via CLI (morph_radius, taubin_iterations, taubin_lambda, extraction_level, target_edge_length, remesh_iterations, target_faces, decimate_ratio, decimate_aggressiveness) can be configured through the Python API.