Metadata-Version: 2.4
Name: fumesh
Version: 0.1.1
Summary: FuMesh: cross-platform 3D mesh editing made simple
License: GPL-3.0-only
Classifier: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: Microsoft :: Windows
Classifier: Operating System :: MacOS
Classifier: Operating System :: POSIX :: Linux
Classifier: Topic :: Multimedia :: Graphics :: 3D Modeling
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PySide6<7,>=6.6
Requires-Dist: pyvista<1,>=0.44
Requires-Dist: pyvistaqt<1,>=0.11
Requires-Dist: trimesh<5,>=4.0
Requires-Dist: numpy<3,>=1.26
Requires-Dist: scipy<2,>=1.11
Requires-Dist: pyacvd<1,>=0.4
Requires-Dist: manifold3d<4,>=3
Requires-Dist: packaging>=23
Provides-Extra: geometry
Requires-Dist: open3d<1,>=0.18; extra == "geometry"
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: ruff<1,>=0.7; extra == "dev"
Requires-Dist: lib3mf<3,>=2.3; extra == "dev"
Provides-Extra: package
Requires-Dist: pyinstaller<7,>=6.10; extra == "package"
Dynamic: license-file

# FuMesh

**3D Mesh Editing Made Simple**

FuMesh is a lightweight, cross-platform mesh editor for **Windows, macOS and Linux**. It focuses on repairing 3D scans and preparing printable models without the complexity of a full CAD/DCC suite: hole filling, clean-up, sculpting, Booleans with smooth seams, aligning overlapping scans, printability checks, 3MF and projects with autosave.

![FuMesh](docs/images/smooth-union.png)

**[User guide](docs/USER_GUIDE.md)** · [Benchmarks](docs/BENCHMARKS.md) · [Third-party licenses](docs/THIRD_PARTY_LICENSES.md) · [Building packages](docs/RELEASING.md)

> **Status: pre-release (0.1).** All planned tools for the first release are in place, with tested packages for Windows x64, macOS arm64 and Linux x86-64. Windows releases intentionally ship unsigned; see [release checks and signing policy](docs/RELEASING.md).

## Product pillars

- **Cut & Trim:** interactive plane cuts, lasso/brush selection, split, delete, cap, keep both halves.
- **Repair:** automatic hole detection, planar and curvature-aware hole filling, duplicate/normal/non-manifold cleanup, remove islands.
- **Sculpt:** smooth, flatten, move, inflate/deflate brushes with local masks and detail preservation.
- **Combine:** union, difference, intersection, local seam detection, auto-fit and adaptive seam blending.
- **Optimize:** mesh reduction, smoothing, remeshing, cleanup, preview and error reporting.
- **3D Printing:** watertightness checks, unit handling, STL/OBJ/PLY/3MF workflows and export validation.

## Roadmap

| Phase | Deliverable |
| --- | --- |
| **M0 – Foundation** | Runnable desktop shell, viewport, camera, selection, import, undo/redo infrastructure |
| **M1 – Basic Editing** | Plane cut/cap, region selection, split, transforms |
| **M2 – Mesh Repair** | Hole discovery, planar/curved fill, mesh cleanup |
| **M3 – Optimization & Sculpt** | Decimation, smoothing, remeshing and brushes |
| **M4 – Boolean & Join** | Robust booleans, local seam-aware blending, experimental auto-fit |
| **M5 – Release** | Print validation, 3MF, project persistence, tests, platform packaging |

Track work via the [six phase epics](docs/ROADMAP.md#phase-trackers-on-github) and 35 linked implementation issues.

See [Product specification](docs/PRODUCT_SPEC.md), [Architecture](docs/ARCHITECTURE.md), [Roadmap](docs/ROADMAP.md), [Geometry notes](docs/GEOMETRY.md), and [Contributing](CONTRIBUTING.md). GitHub Issues use the **[M0]–[M5]** prefixes so they can be tracked even before GitHub milestone objects are added.

## Suggested stack

Python 3.11+ · PySide6 (Qt 6) · PyVista/VTK and pyvistaqt · Trimesh · Manifold3D · Open3D where needed. Computationally heavy geometry is run in native libraries and moved off the GUI thread. All third-party licenses and distribution obligations must be reviewed before release.

## Quick start (development)

```bash
git clone https://github.com/Stigern/FuMesh.git
cd FuMesh
python -m venv .venv
# Linux/macOS: source .venv/bin/activate
# Windows: .venv\Scripts\activate
python -m pip install -e ".[dev]"
fumesh
```

### Linux system packages

Desktop Ubuntu/Debian installs usually have these already, but minimal or server installs do not, and the app then aborts with `Could not load the Qt platform plugin "xcb"`. Install Python's venv module and the X11/OpenGL libraries Qt 6 and VTK need (tested on Ubuntu 26.04; replace `3.14` with your Python version):

```bash
sudo apt install python3.14-venv libxcb-cursor0 libxkbcommon-x11-0 libxcb-icccm4 libxcb-keysyms1 libxcb-xkb1 libxcb-image0 libxcb-render-util0 libxcb-shape0 libxcb-randr0 libxcb-xinerama0 libegl1 libgl1
```

On a machine without a display (e.g. for GUI smoke tests), also install `xvfb` and start the app with `xvfb-run -a fumesh`. The unit tests need no display: run them with `QT_QPA_PLATFORM=offscreen pytest`.

You can also run `python -m fumesh`. The initial shell supports a 3D viewport, open mesh, reset camera and wireframe toggle. Complex repair/sculpt/boolean features are tracked as upcoming work. No internet connection or online AI service is required for editing.

## File formats and appearance data

| Format | Units stored | Placement | Vertex colours | UVs | Normals |
|---|---|---|---|---|---|
| STL | no (asked on import/export) | baked into vertices | no | no | facet only |
| OBJ | no (asked) | baked | yes (`v x y z r g b`) | yes | yes (recomputed) |
| PLY | no (asked) | baked | yes | yes | yes (recomputed) |
| 3MF | yes | build transform per object | yes | no | no |
| `.fumesh` project | yes | yes | yes | yes | yes, plus any other per-vertex data |

Normals are derived from the geometry, so exports write freshly computed ones. Edits keep
per-vertex data where they can (interpolated on new vertices); Booleans and joins rebuild the
surface and drop it. FuMesh asks before such an edit is applied and before exporting to a format
that cannot hold the data, so colours and UVs are never lost silently (Undo restores them).

## Projects and autosave

**File → Save project** (Ctrl/⌘+S) writes a `.fumesh` project: a ZIP with a versioned
`manifest.json` (object names, units, placement, visibility, lock, active object, triangle
selection and view settings) and every mesh as compressed VTK XML, which keeps colours,
normals and UVs. Saving is atomic (a temporary file renamed over the old one), and each mesh is
checked against its SHA-256 checksum when the project is opened. Older project versions are
upgraded automatically; projects from a newer FuMesh are refused with a clear message. The
undo history is not saved.

While you work, FuMesh autosaves every minute to its data folder (override with
`FUMESH_AUTOSAVE_DIR`). After a crash, the next start offers the autosaved work in a recovery
dialog.

## Scope principles

1. Preview potentially destructive operations and use explicit **Apply/Cancel**.
2. Keep the original mesh safely undoable and track topology changes.
3. Use separate preview-quality and final-quality meshes for large scans.
4. Be explicit when an algorithm cannot reliably repair an invalid/open mesh.
5. Prefer local processing; support large meshes with cancelable background work.
6. Support metric units and a consistent axis convention throughout the pipeline.

## License

FuMesh is free software under the **GNU General Public License v3.0 only** (`GPL-3.0-only`);
see [LICENSE](LICENSE). Every dependency's license has been checked for compatibility; see
[docs/THIRD_PARTY_LICENSES.md](docs/THIRD_PARTY_LICENSES.md). A test keeps it that way when
dependencies change.
