xtf process
Process a scalar field into a mesh from the command line
Usage
xtf process [OPTIONS] INPUT_PATHProcess a scalar field into a mesh. The input field is loaded, run through the full pipeline (preprocessing, extraction, smoothing, repair, remeshing, decimation), and the resulting mesh is saved to the output path.
Arguments
| Argument | Description |
|---|---|
INPUT_PATH | Path to the input scalar field file (must exist) |
Options
| Option | Type | Default | Description |
|---|---|---|---|
-o, --output | PATH | (required) | Output mesh file path (format determined by extension: .stl, .obj, .ply) |
--threshold | FLOAT | 0.5 | Field threshold [0-1] for binarization |
--sigma | FLOAT | 1.0 | Gaussian smoothing sigma for preprocessing |
-f, --field-name | TEXT | None | Field/variable name to extract from input file (for .npz, .mat, .h5, etc.) |
--shape | TEXT | None | Grid shape for flat data, e.g. 100x200 or 10x20x30 |
--field-type | density|sdf | density | Input field type. Setting sdf enables smart defaults (direct extraction, no Gaussian smoothing). |
--direct | flag | False | Direct extraction from continuous field (skip preprocessing) |
--no-repair | flag | False | Disable watertight mesh repair |
--no-remesh | flag | False | Disable isotropic remeshing |
--no-decimate | flag | False | Disable QEM mesh decimation |
--smoothing | taubin|bilateral | taubin | Mesh smoothing algorithm. Use bilateral for feature-preserving smoothing |
--extraction-method | mc|dc|surfnets|manifold | mc | Extraction algorithm. With --field-type sdf, smart default switches to dc unless explicitly overridden |
--viz | flag | False | Save a comparison visualization (PNG) alongside the mesh |
Smart defaults with --field-type sdf
When --field-type sdf is used, the following defaults change automatically unless explicitly overridden:
--directis enabled (preprocessing is skipped)--sigmais set to0.0(no Gaussian smoothing)--extraction-methodis set todc(dual contouring for sharp features)--smoothingis set tobilateralwith 5 iterations (reduced to preserve DC sharp features)
You can still override these by explicitly passing --sigma 1.0 or omitting --direct.
Examples
Basic 3D processing
xtf process scalar_field.npy -o output.stlCustom threshold and smoothing
xtf process field.npy -o mesh.obj --threshold 0.4 --sigma 1.5MATLAB file with named variable
xtf process design_result.mat -o mesh.stl -f xPhysCSV with shape specification
xtf process flat_data.csv -o mesh.stl --shape 10x20x30SDF field (smart defaults)
xtf process sdf_field.npy -o mesh.stl --field-type sdfDirect extraction from continuous field
xtf process field.npy -o mesh.stl --directWith visualization output
xtf process field.npy -o mesh.stl --viz
# Saves mesh.stl and mesh.pngWhen --viz is used, a comparison PNG image is saved alongside the mesh at the same path with a .png extension.
Feature-preserving smoothing
xtf process field.npy -o mesh.stl --smoothing bilateralBilateral filtering preserves sharp structural features (corners, ridges) while smoothing flat surfaces. Useful when the design has distinct sharp edges that should not be blurred.
Skip decimation (preserve full polygon count)
xtf process field.npy -o mesh.stl --no-decimateDual contouring on SDF field
xtf process neural_sdf.npy -o mesh.stl --field-type sdfAuto-selects DC extraction with bilateral smoothing (5 iterations) for sharp feature preservation.
Explicit manifold extraction
xtf process sdf_field.npy -o mesh.stl --extraction-method manifold --field-type sdfWatertight output by design — repair stage is automatically skipped.
Skip all post-processing (raw extraction output)
xtf process field.npy -o mesh.stl --no-repair --no-remesh --no-decimateUseful for debugging or when you need the raw extraction output without any mesh optimization.