Input Formats

Supported formats

Install all optional formats at once with:

uv sync --extra all-formats

Check which formats are available on your system:

uv run xtf formats

Format details

NumPy (.npy, .npz)

The simplest format. .npy files contain a single array. .npz files can contain multiple arrays.

from xeltofab.io import load_field

# .npy -- loads the single array directly
state = load_field("field.npy")

# .npz -- uses "density" key if present, otherwise the first key
state = load_field("field.npz")

# .npz -- specify which array to load
state = load_field("field.npz", field_name="xPhys")

CLI:

uv run xtf process field.npy -o output.stl
uv run xtf process field.npz -o output.stl --field-name xPhys

MATLAB (.mat)

Loads .mat files via scipy.io.loadmat. The loader auto-detects common design optimization variable names in priority order:

1. xPhys
2. densities
3. x
4. rho
5. dc
6. density

If none of these are found and the file contains a single variable, that variable is used. If multiple variables exist, you must specify which one to load.

# Auto-detect variable name
state = load_field("result.mat")

# Specify explicitly
state = load_field("result.mat", field_name="xPhys")

CLI:

uv run xtf process result.mat -o output.stl
uv run xtf process result.mat -o output.stl --field-name rho

Note on MATLAB v7.3+ files: Files saved in MATLAB's v7.3 format use HDF5 internally and cannot be read by scipy.io.loadmat. If you encounter this, either resave in MATLAB with save('file.mat', '-v7') or save as .h5 and load with the HDF5 loader.

CSV / Text (.csv, .txt)

Loads comma-delimited or whitespace-delimited data via numpy.loadtxt. The loader tries comma-delimited first, then whitespace-delimited, then with header skipping.

For 2D grids stored as a table (rows and columns), the shape is inferred automatically:

state = load_field("field.csv")

For flat data (one value per line or a single row) that represents a 2D or 3D grid, provide the shape parameter:

state = load_field("field.csv", shape=(50, 100))       # 2D
state = load_field("field.csv", shape=(10, 20, 30))    # 3D

CLI:

uv run xtf process field.csv -o output.stl --shape 50x100
uv run xtf process field.txt -o output.stl --shape 10x20x30

The flat data is reshaped to the specified dimensions. The total number of values must match the product of the shape dimensions.

VTK (.vtk, .vtr, .vti)

Loads VTK structured grid files via PyVista. Requires the optional vtk extra.

The loader auto-detects scalar fields by looking for cell data or point data arrays with names matching common design optimization patterns (density, rho, xphys, x), checking cell data first (since element-level fields are stored as cell data). If no match is found and only one data array exists, it is used automatically.

state = load_field("result.vtk")
state = load_field("result.vti", field_name="density")

CLI:

uv run xtf process result.vtk -o output.stl
uv run xtf process result.vti -o output.stl --field-name density

Grid dimensions are extracted from the VTK structured grid metadata. Cell data arrays are reshaped to cell counts (node count - 1 per axis), and point data arrays use node counts directly. VTK's internal Fortran-like ordering is transposed to C order automatically.

HDF5 (.h5, .hdf5)

Loads HDF5 files via h5py. Requires the optional hdf5 extra.

Auto-detection searches all datasets recursively, checking leaf names against the same known variable names as the MATLAB loader (xPhys, densities, x, rho, dc, density).

state = load_field("result.h5")
state = load_field("result.h5", field_name="simulations/density")

CLI:

uv run xtf process result.h5 -o output.stl
uv run xtf process result.h5 -o output.stl --field-name simulations/density

XDMF (.xdmf)

XDMF files are XML metadata files that reference HDF5 datasets. The loader parses the XDMF XML, finds Attribute elements with DataItem children in HDF format, and reads the referenced data from the companion .h5 file.

state = load_field("result.xdmf")
state = load_field("result.xdmf", field_name="density")

The companion HDF5 file must be in the same directory as the XDMF file.

Common options

All loaders accept these parameters via load_field():