PipelineParams

Import

from xeltofab import PipelineParams
# or
from xeltofab.state import PipelineParams

Overview

PipelineParams is a Pydantic BaseModel that holds all configurable parameters for the pipeline. It includes smart defaults that adapt based on the input field type.

Fields

Field	Type	Default	Constraints	Description
`threshold`	`float`	`0.5`	`>= 0.0`, `<= 1.0`	Field threshold for binarization
`smooth_sigma`	`float`	`1.0`	`>= 0.0`	Gaussian smoothing sigma for preprocessing
`morph_radius`	`int`	`1`	`>= 0`	Morphological cleanup radius
`taubin_iterations`	`int`	`20`	`>= 0`	Number of Taubin smoothing iterations
`taubin_lambda`	`float`	`0.5`	`> 0.0`, `<= 1.0`	Shrinkage factor for Taubin smoothing
`smoothing_method`	`Literal["taubin", "bilateral"]`	`"taubin"`	—	Mesh smoothing algorithm
`bilateral_iterations`	`int`	`10`	`>= 1`	Number of bilateral filtering iterations
`bilateral_sigma_s`	`float \| None`	`None`	`> 0.0`	Spatial weight reach (auto from edge length when `None`)
`bilateral_sigma_n`	`float`	`0.35`	`> 0.0`	Normal similarity threshold in radians
`field_type`	`Literal["density", "sdf"]`	`"density"`	—	Input field type
`extraction_method`	`"mc"` \| `"dc"` \| `"surfnets"` \| `"manifold"`	`"mc"`	—	Extraction algorithm: `mc` (Marching Cubes), `dc` (Dual Contouring), `surfnets` (Surface Nets), `manifold` (manifold3d)
`direct_extraction`	`bool`	`False`	—	Skip preprocessing and extract directly from the continuous field
`extraction_level`	`float \| None`	`None`	—	Explicit iso-level for extraction (MC, DC, SurfNets, or manifold)
`repair`	`bool`	`True`	—	Enable watertight mesh repair (3D only)
`remesh`	`bool`	`True`	—	Enable isotropic remeshing (3D only)
`target_edge_length`	`float \| None`	`None`	`> 0.0`	Target edge length for remeshing (auto from bounding box when `None`)
`remesh_iterations`	`int`	`10`	`>= 1`	Number of Botsch & Kobbelt remeshing iterations
`decimate`	`bool`	`True`	—	Enable QEM mesh decimation (3D only)
`target_faces`	`int \| None`	`None`	`> 0`	Absolute target face count (overrides `decimate_ratio`)
`decimate_ratio`	`float`	`0.5`	`> 0.0`, `<= 1.0`	Fraction of faces to keep
`decimate_aggressiveness`	`int`	`7`	`>= 1`, `<= 10`	QEM edge collapse error tolerance

Smart defaults for SDF fields

When field_type is set to "sdf", PipelineParams automatically adjusts defaults for values not explicitly set by the user:

direct_extraction becomes True (SDF fields are already continuous — no binarization needed)
smooth_sigma becomes 0.0 (Gaussian preprocessing is skipped)
extraction_method becomes "dc" (Dual Contouring leverages SDF gradients for sharp features)
smoothing_method becomes "bilateral" and taubin_iterations becomes 5 (reduced smoothing to preserve DC sharp features)

If you explicitly pass direct_extraction=False or smooth_sigma=2.0 with an SDF field, your values take precedence over the smart defaults.

Using with process_from_sdf()

When using process_from_sdf(), field_type="sdf" is set automatically — you don't need to specify it. Any additional PipelineParams fields can be passed as keyword arguments (e.g., process_from_sdf(my_sdf, bounds, smoothing_method="taubin")).

# Smart defaults apply automatically
sdf_params = PipelineParams(field_type="sdf")
assert sdf_params.direct_extraction is True
assert sdf_params.smooth_sigma == 0.0
assert sdf_params.extraction_method == "dc"
assert sdf_params.smoothing_method == "bilateral"
assert sdf_params.taubin_iterations == 5

# Explicit values override smart defaults
sdf_params = PipelineParams(field_type="sdf", smooth_sigma=0.5)
assert sdf_params.smooth_sigma == 0.5

effective_extraction_level

The effective_extraction_level property returns the iso-level used for mesh extraction:

If extraction_level is explicitly set, that value is returned.
Otherwise, 0.0 for SDF fields (zero level-set) or threshold for density fields.

params = PipelineParams(threshold=0.4)
assert params.effective_extraction_level == 0.4

params = PipelineParams(field_type="sdf")
assert params.effective_extraction_level == 0.0

params = PipelineParams(extraction_level=0.3)
assert params.effective_extraction_level == 0.3

Usage

from xeltofab import PipelineParams, load_field

# Default parameters
params = PipelineParams()

# Custom parameters
params = PipelineParams(
    threshold=0.4,
    smooth_sigma=1.5,
    taubin_iterations=30,
)

# SDF field with smart defaults
params = PipelineParams(field_type="sdf")

# Feature-preserving bilateral smoothing
params = PipelineParams(
    smoothing_method="bilateral",
    bilateral_iterations=10,
)

# Control decimation
params = PipelineParams(
    decimate_ratio=0.3,          # keep 30% of faces
    decimate_aggressiveness=5,   # conservative
)

# Absolute face count target
params = PipelineParams(target_faces=10000)

# Disable post-processing stages
params = PipelineParams(repair=False, remesh=False, decimate=False)

# Pass to load_field
state = load_field("field.npy", params=params)