xeltofab 0.2.2__tar.gz

xeltofab-0.2.2/.claude/settings.local.json

@@ -0,0 +1,18 @@
+{
+  "permissions": {
+    "allow": [
+      "mcp__plugin_claude-mem_mcp-search__search",
+      "Bash(du:*)",
+      "Bash(sqlite3:*)",
+      "Bash(rm:*)",
+      "Bash(kill 7397:*)",
+      "mcp__plugin_claude-mem_mcp-search__smart_outline",
+      "Bash(ls:*)",
+      "Bash(wc:*)",
+      "Bash(grep -c \"^def test_\" /home/xarthurx/repo/xelToFab/tests/*.py /home/xarthurx/repo/xelToFab/tests/test_loaders/*.py)",
+      "Bash(uv run:*)",
+      "Bash(grep:*)",
+      "Bash(git:*)"
+    ]
+  }
+}

xeltofab-0.2.2/.github/workflows/deploy-website.yml

@@ -0,0 +1,31 @@
+name: Deploy Website to Vercel
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'website/**'
+
+env:
+  VERCEL_ORG_ID: ${{ secrets.VERCEL_ORG_ID }}
+  VERCEL_PROJECT_ID: ${{ secrets.VERCEL_PROJECT_ID }}
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: oven-sh/setup-bun@v2
+
+      - name: Install Vercel CLI
+        run: bun add -g vercel
+
+      - name: Pull Vercel project settings
+        run: vercel pull --yes --environment=production --token=${{ secrets.VERCEL_TOKEN }}
+
+      - name: Build
+        run: vercel build --prod --token=${{ secrets.VERCEL_TOKEN }}
+
+      - name: Deploy to Vercel
+        run: vercel deploy --prebuilt --prod --token=${{ secrets.VERCEL_TOKEN }}

xeltofab-0.2.2/.gitignore

@@ -0,0 +1,218 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[codz]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+!website/lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py.cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# UV
+#   Similar to Pipfile.lock, it is generally recommended to include uv.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#uv.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+#poetry.toml
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#   pdm recommends including project-wide configuration in pdm.toml, but excluding .pdm-python.
+#   https://pdm-project.org/en/latest/usage/project/#working-with-version-control
+#pdm.lock
+#pdm.toml
+.pdm-python
+.pdm-build/
+
+# pixi
+#   Similar to Pipfile.lock, it is generally recommended to include pixi.lock in version control.
+#pixi.lock
+#   Pixi creates a virtual environment in the .pixi directory, just like venv module creates one
+#   in the .venv directory. It is recommended not to include this directory in version control.
+.pixi
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.envrc
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# PyCharm
+#  JetBrains specific template is maintained in a separate JetBrains.gitignore that can
+#  be found at https://github.com/github/gitignore/blob/main/Global/JetBrains.gitignore
+#  and can be added to the global gitignore or merged into this file.  For a more nuclear
+#  option (not recommended) you can uncomment the following to ignore the entire idea folder.
+#.idea/
+
+# Abstra
+# Abstra is an AI-powered process automation framework.
+# Ignore directories containing user credentials, local state, and settings.
+# Learn more at https://abstra.io/docs
+.abstra/
+
+# Visual Studio Code
+#  Visual Studio Code specific template is maintained in a separate VisualStudioCode.gitignore 
+#  that can be found at https://github.com/github/gitignore/blob/main/Global/VisualStudioCode.gitignore
+#  and can be added to the global gitignore or merged into this file. However, if you prefer, 
+#  you could uncomment the following to ignore the entire vscode folder
+# .vscode/
+
+# Ruff stuff:
+.ruff_cache/
+
+# PyPI configuration file
+.pypirc
+
+# Cursor
+#  Cursor is an AI-powered code editor. `.cursorignore` specifies files/directories to
+#  exclude from AI features like autocomplete and code analysis. Recommended for sensitive data
+#  refer to https://docs.cursor.com/context/ignore-files
+.cursorignore
+.cursorindexingignore
+
+# Marimo
+marimo/_static/
+marimo/_lsp/
+__marimo__/
+
+# Worktrees
+.worktrees/
+
+# Docs website
+website/.next/
+website/node_modules/
+website/.source/
+.vercel
+.env*.local

xeltofab-0.2.2/.python-version

@@ -0,0 +1 @@
+3.13

xeltofab-0.2.2/AGENTS.md

@@ -0,0 +1,3 @@
+# AGENTS
+
+See [CLAUDE.md](./CLAUDE.md).

xeltofab-0.2.2/CLAUDE.md

@@ -0,0 +1,94 @@
+# CLAUDE.md
+
+## Project Overview
+
+**XelToFab** — Design field post-processing pipeline: scalar fields → meshes → fabrication-ready geometry. Python 3.13+, `uv` project management. Package: `xeltofab` (`src/xeltofab/`).
+
+Research notes: `~/winHome/repo/xKnowledgeSync/99_academic.work/MAX_Mark/proj_XelToFab/`
+Background material: `~/winHome/repo/xKnowledgeSync/99_academic.work/MAX_Mark/` (brainstorms, strategy, glossary)
+Key reference: [`{Review} The Topology Optimization Post-Processing Pipeline.md`](file:///home/xarthurx/winHome/repo/xKnowledgeSync/99_academic.work/MAX_Mark/proj_XelToFab/%7BReview%7D%20The%20Topology%20Optimization%20Post-Processing%20Pipeline.md) — full literature review covering all 4 pipeline stages, toolchain, and feasibility analysis.
+Collaboration: M4X–IDEAL Lab with Prof. Mark Fuge.
+
+## Pipeline Architecture
+
+1. **Preprocessing** — Threshold (Heaviside), smooth (Gaussian), clean (morphology + connected components)
+2. **Mesh Extraction** — Marching cubes/squares (scikit-image); differentiable via FlexiCubes/Kaolin
+3. **Mesh Post-processing** — Taubin smoothing, QEM decimation, isotropic remeshing, repair
+4. **Mesh-to-CAD** — Patch decomposition, NURBS fitting, B-Rep assembly (research frontier)
+
+## Project-Specific Commands
+
+| Task | Command |
+|------|---------|
+| Install dependencies | `uv sync` |
+| Run tests | `uv run pytest tests/ -v` |
+| Lint | `ruff check` |
+| Format | `ruff format` |
+| Type check | `ty check` |
+| CLI help | `uv run xtf --help` |
+| Dev docs site | `cd website && bun run dev` |
+| Build docs site | `cd website && bun run build` |
+
+## Core Dependencies
+
+| Stage | Libraries |
+|-------|-----------|
+| Preprocessing | `scipy.ndimage`, `scikit-image` |
+| Mesh extraction | `scikit-image` (marching cubes), `pyvista`/VTK |
+| Smoothing / decimation | `pyvista`, `pymeshlab`, `open3d` |
+| Mesh I/O / repair | `trimesh` |
+| Quality metrics | `pyvista` (`mesh.quality()`) |
+| NURBS / CAD export | `pythonocc-core`, `cadquery` |
+| Format conversion | `meshio` |
+| I/O formats | `scipy.io` (.mat), `pyvista` (.vtk), `h5py` (.h5/.xdmf) |
+
+## Conventions
+
+- Input: numpy arrays — density fields in [0, 1] or SDF fields (unbounded)
+- Mesh quality targets (FEA): aspect ratio < 5, min angle > 20°, scaled Jacobian > 0.5
+- Always validate volume preservation after smoothing
+- Re-verify connectivity after decimation (thin TO features can collapse)
+- B-spline fitting: keep < 100 points per parametric direction to avoid oscillation
+
+## Documentation Layout
+
+| File | Location | Purpose |
+|------|----------|---------|
+| `CLAUDE.md` | repo root | Agent instructions (this file) |
+| `README.md` | repo root | Project overview, quick start, API examples |
+| `ARCHITECTURE.md` | `docs/` | Module map, data flow, dependency table |
+| `TODO.md` | `docs/` | Feature backlog (tiered) |
+| `PROGRESS.md` | `docs/` | Incident log & project memory |
+
+## Confidential Plans
+
+Design docs and implementation plans are stored externally (not synced with this repo):
+`~/repo/repo_plans/xelToFab/`
+
+## docs/TODO.md — Feature Backlog
+
+`docs/TODO.md` tracks deferred features and future work tiers. Update it when scoping new work or deferring functionality. Current tiers: quality-enhanced post-processing, Polyscope visualization, mesh-to-CAD, neural-enhanced pipeline.
+
+## docs/PROGRESS.md — Incident Log & Project Memory
+
+`docs/PROGRESS.md` is a living record of problems, solutions, and hard-won knowledge. Update it **immediately** when:
+- A bug is found and fixed
+- A failed approach is abandoned
+- A non-obvious design decision is made
+- A configuration or environment issue is resolved
+- A test failure reveals a misunderstanding
+
+Each entry **must** include:
+1. **Problem** — What went wrong or what changed
+2. **Root cause** — Why it happened
+3. **Resolution** — How it was fixed (include the **Git commit ID**, e.g. `fix: 8e2ab7e`)
+4. **Prevention** — How to avoid this class of problem in the future
+
+**Critical rule: Do NOT repeat the same type of mistake.** Before starting any work, review `docs/PROGRESS.md` for past issues in the same area. If a similar problem has already been documented, follow the prevention guidance — repeating a documented mistake is unacceptable.
+
+## Keeping Documentation in Sync
+
+Before finishing a session:
+1. Check changes made and update any stale docs
+2. Update `docs/PROGRESS.md` with any issues encountered
+3. Re-read this file for any instructions updated during the session

xeltofab-0.2.2/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Zhao.MA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xeltofab-0.2.2/PKG-INFO

@@ -0,0 +1,164 @@
+Metadata-Version: 2.4
+Name: xeltofab
+Version: 0.2.2
+Summary: Design fields to fabrication-ready geometry
+Project-URL: Homepage, https://xel-to-fab.github.io
+Project-URL: Documentation, https://xel-to-fab.github.io
+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://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.
+
+## Quick Start
+
+```bash
+# Install
+uv sync
+
+# Process a 3D density field into an STL mesh
+uv run xtf process density.npy -o output.stl
+
+# Process with custom parameters and save a comparison plot
+uv run xtf process density.npy -o output.stl --threshold 0.4 --sigma 1.5 --viz
+
+# Visualize a 2D density field
+uv run 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 | `uv sync --extra vtk` |
+| HDF5/XDMF | .h5, .hdf5, .xdmf | `uv sync --extra hdf5` |
+| All formats | — | `uv sync --extra all-formats` |
+
+List available formats: `uv run 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.
+
+## Requirements
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/) for project management

xeltofab-0.2.2/README.md

@@ -0,0 +1,114 @@
+<h1 align="center">XelToFab</h1>
+
+<p align="center">
+  <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.
+
+## Quick Start
+
+```bash
+# Install
+uv sync
+
+# Process a 3D density field into an STL mesh
+uv run xtf process density.npy -o output.stl
+
+# Process with custom parameters and save a comparison plot
+uv run xtf process density.npy -o output.stl --threshold 0.4 --sigma 1.5 --viz
+
+# Visualize a 2D density field
+uv run 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 | `uv sync --extra vtk` |
+| HDF5/XDMF | .h5, .hdf5, .xdmf | `uv sync --extra hdf5` |
+| All formats | — | `uv sync --extra all-formats` |
+
+List available formats: `uv run 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.
+
+## Requirements
+
+- Python 3.13+
+- [uv](https://docs.astral.sh/uv/) for project management