Metadata-Version: 2.4
Name: xeltofab
Version: 0.3.0
Summary: Design fields to fabrication-ready geometry
Project-URL: Homepage, https://xel-to-fab.vercel.app
Project-URL: Documentation, https://xel-to-fab.vercel.app
Project-URL: Repository, https://github.com/xarthurx/XelToFab
Project-URL: Issues, https://github.com/xarthurx/XelToFab/issues
Author-email: Zhao MA <zhma@ethz.ch>
License-Expression: MIT
License-File: LICENSE
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.13
Requires-Dist: click>=8.3.1
Requires-Dist: marimo>=0.20.4
Requires-Dist: matplotlib>=3.10.8
Requires-Dist: numpy
Requires-Dist: plotly>=6.6.0
Requires-Dist: pydantic>=2.12.5
Requires-Dist: pyfqmr>=0.5.0
Requires-Dist: scikit-image
Requires-Dist: scipy
Requires-Dist: trimesh
Provides-Extra: all
Requires-Dist: gpytoolbox>=0.3.0; extra == 'all'
Requires-Dist: h5py>=3.10; extra == 'all'
Requires-Dist: manifold3d>=3.0; extra == 'all'
Requires-Dist: pymeshlab>=2023.12; extra == 'all'
Requires-Dist: pyvista>=0.43; extra == 'all'
Provides-Extra: all-formats
Requires-Dist: h5py>=3.10; extra == 'all-formats'
Requires-Dist: pyvista>=0.43; extra == 'all-formats'
Provides-Extra: cuda
Requires-Dist: isoext>=0.5; extra == 'cuda'
Provides-Extra: hdf5
Requires-Dist: h5py>=3.10; extra == 'hdf5'
Provides-Extra: manifold
Requires-Dist: manifold3d>=3.0; extra == 'manifold'
Provides-Extra: mesh-quality
Requires-Dist: gpytoolbox>=0.3.0; extra == 'mesh-quality'
Requires-Dist: pymeshlab>=2023.12; extra == 'mesh-quality'
Provides-Extra: vtk
Requires-Dist: pyvista>=0.43; extra == 'vtk'
Description-Content-Type: text/markdown

<h1 align="center">XelToFab</h1>

<p align="center">
  <a href="https://pypi.org/project/xeltofab/"><img src="https://img.shields.io/pypi/v/xeltofab.svg" alt="PyPI"></a>
  <a href="https://www.python.org/downloads/"><img src="https://img.shields.io/badge/python-3.13%2B-blue.svg" alt="Python 3.13+"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-green.svg" alt="License: MIT"></a>
</p>

A design field post-processing pipeline that transforms continuous scalar fields from optimization solvers and neural networks into clean, fabrication-ready triangle meshes (3D) and contour representations (2D). The pipeline handles thresholding, smoothing, mesh extraction, quality improvement, visualization, and multi-format export.

## Installation

```bash
# From PyPI (stable)
pip install xeltofab

# With optional format support
pip install "xeltofab[vtk,hdf5]"

# From source (development)
git clone https://github.com/xarthurx/XelToFab.git
cd XelToFab
uv sync
```

## Quick Start

```bash
# Process a 3D density field into an STL mesh
xtf process density.npy -o output.stl

# Process with custom parameters and save a comparison plot
xtf process density.npy -o output.stl --threshold 0.4 --sigma 1.5 --viz

# Visualize a 2D density field
xtf viz density_2d.npy -o comparison.png
```

## Pipeline

```
Scalar Field → Preprocess → Extract → Smooth → Mesh/Contours
     (.npy)      threshold     marching    Taubin     (.stl/.obj)
                 + morphology  cubes/sq.   filter
```

1. **Preprocess** — Gaussian smoothing, Heaviside thresholding, morphological cleanup, small component removal
2. **Extract** — Marching cubes (3D) or marching squares (2D) via scikit-image
3. **Smooth** — Taubin smoothing via trimesh (3D meshes only)

## Python API

```python
import numpy as np
from xeltofab.state import PipelineState, PipelineParams
from xeltofab.pipeline import process
from xeltofab.io import save_mesh

# Create a scalar field (e.g., a sphere)
z, y, x = np.mgrid[-1:1:50j, -1:1:50j, -1:1:50j]
field = (x**2 + y**2 + z**2 < 0.5**2).astype(float)

# Run the pipeline
params = PipelineParams(threshold=0.5, smooth_sigma=1.0)
state = PipelineState(field=field, params=params)
result = process(state)

# Export
save_mesh(result, "sphere.stl")
```

### Using Example Data

Pre-computed topology optimization results are included in `data/examples/` (sourced from [IDEALLab EngiBench](https://huggingface.co/IDEALLab)):

```python
from xeltofab.io import load_field
from xeltofab.pipeline import process

state = load_field("data/examples/beams_2d_50x100_sample0.npy")
result = process(state)
```

## Supported Input Formats

| Format | Extensions | Install |
|--------|-----------|---------|
| NumPy | .npy, .npz | Built-in |
| MATLAB | .mat | Built-in (via scipy) |
| CSV/Text | .csv, .txt | Built-in |
| VTK | .vtk, .vtr, .vti | `pip install "xeltofab[vtk]"` |
| HDF5/XDMF | .h5, .hdf5, .xdmf | `pip install "xeltofab[hdf5]"` |
| All formats | — | `pip install "xeltofab[all-formats]"` |

List available formats: `xtf formats`

## Development

```bash
uv sync                          # Install deps
uv run pytest tests/ -v          # Run tests
uv run ruff check src/ tests/    # Lint
uv run ruff format src/ tests/   # Format
uv run marimo edit notebooks/demo.py  # Interactive demo
```

## Project Structure

```
src/xeltofab/
├── state.py        Pipeline state + parameter models
├── preprocess.py   Field preprocessing
├── extract.py      Mesh/contour extraction
├── smooth.py       Taubin smoothing
├── pipeline.py     Orchestrator
├── io.py           File I/O (multi-format load, mesh export)
├── loaders/        Format-specific loaders (numpy, matlab, csv, vtk, hdf5)
├── field_plots.py  Matplotlib visualization
└── cli.py          CLI (xtf)
```

See [docs/ARCHITECTURE.md](docs/ARCHITECTURE.md) for detailed architecture documentation.

## Documentation

Full documentation is available at [xel-to-fab.vercel.app](https://xel-to-fab.vercel.app).

## Requirements

- Python 3.13+
- [uv](https://docs.astral.sh/uv/) for development
