Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
71 changes: 71 additions & 0 deletions .github/workflows/ci.yml
Original file line number Diff line number Diff line change
Expand Up @@ -28,3 +28,74 @@ jobs:

- name: Run tests
run: python -m pytest -q --durations=20

# The geometry core is covered by the headless suite above, but the thin
# FreeCAD adapter (the PartDesign executor) can only be exercised inside
# FreeCAD itself. Issues #3-#8 were all field-discovered executor
# regressions the core suite cannot see; this job runs the full
# reconstruct -> snap -> plan -> build smoke test in a real FreeCAD build
# on every push/PR, so an executor regression fails CI instead of the field.
freecad-smoke:
runs-on: ubuntu-latest
strategy:
fail-fast: false
matrix:
# The freecadmin target is 1.1.0; pin the newest 1.1.x stable.
freecad: ["1.1.4"]
timeout-minutes: 20
steps:
- uses: actions/checkout@v4

- name: Cache FreeCAD AppImage
id: cache-freecad
uses: actions/cache@v4
with:
# Cache the ~800 MB AppImage only, not the 3 GB extracted tree.
path: |
~/freecad/*.AppImage
~/freecad/*.AppImage-SHA256.txt
key: freecad-${{ matrix.freecad }}-x86_64-py311

- name: Download FreeCAD AppImage
if: steps.cache-freecad.outputs.cache-hit != 'true'
run: |
mkdir -p ~/freecad
cd ~/freecad
gh release download "${{ matrix.freecad }}" \
--repo FreeCAD/FreeCAD \
--pattern "FreeCAD_${{ matrix.freecad }}-Linux-x86_64-py311.AppImage" \
--pattern "FreeCAD_${{ matrix.freecad }}-Linux-x86_64-py311.AppImage-SHA256.txt" \
--dir .
sha256sum -c "FreeCAD_${{ matrix.freecad }}-Linux-x86_64-py311.AppImage-SHA256.txt"
env:
GH_TOKEN: ${{ github.token }}

- name: Extract FreeCAD
run: |
cd ~/freecad
chmod +x "FreeCAD_${{ matrix.freecad }}-Linux-x86_64-py311.AppImage"
"./FreeCAD_${{ matrix.freecad }}-Linux-x86_64-py311.AppImage" --appimage-extract

- name: Install core Python deps into FreeCAD's interpreter
run: |
# AppRun launches the bundled interpreter with PYTHONHOME and the
# SSL certs set. numpy/scipy/shapely ship with the AppImage; the
# rest are added. manifold3d enables the deviation-correction case.
~/freecad/squashfs-root/AppRun python -m pip install --no-input \
numpy scipy trimesh shapely rtree manifold3d

- name: Run headless smoke test
run: |
set -o pipefail
~/freecad/squashfs-root/AppRun freecadcmd \
freecad/meshtofeatures_wb/scripts/freecad_smoke_test.py \
| tee smoke.log
# freecadcmd exits 0 even when the script raises an exception
# (it prints "Exception while processing file" and swallows the
# failure). The script only prints the ALL CHECKS PASSED /
# FAILED sentinel when it ran to the end, so its absence means a
# crash mid-run -- fail the job in that case too.
if ! grep -qE "ALL CHECKS PASSED|^FAILED: " smoke.log; then
echo "::error::smoke script did not run to completion (crashed?)"
exit 1
fi
36 changes: 36 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,41 @@
# Changelog

## Unreleased

### Added

- **FreeCAD executor CI.** A second CI job (`freecad-smoke`) runs the
full headless smoke test (`scripts/freecad_smoke_test.py`: 17 parts
through reconstruct -> snap -> plan -> feature detection -> PartDesign
build, including the manifold3d deviation-correction case) inside a
sha256-verified FreeCAD 1.1.x AppImage on every push and PR. The
PartDesign executor — the layer behind field regressions #3-#8 — is
now regression-gated in CI instead of by the manual VERIFY.md
checklist.
- **ROADMAP.md.** Phased plan after v0.17.7: executor CI (this),
feature depth (convex cones, spheres, tori), per-feature deviation
report, and dimensioned/constrained sketches, plus deferred items
with reasons.

### Changed

- `freecad_smoke_test.py` flushes its `check()` output per check:
`freecadcmd` drops unflushed Python stdout when the script ends via
`sys.exit()`, which would otherwise hide every `[PASS]`/`[FAIL]` line
in the CI log (locally visible, silently absent on redirect).
- `freecad_smoke_test.py` failure visibility: its duplicate-invocation
guard now exits non-zero (it previously exited 0). `freecadcmd` only
re-executes a script when the first (import-based) execution raised,
so reaching the guard means the first run failed -- which it could
formerly be swallowed into a green exit code. Addon-import failures
also print their root-cause traceback and a repository-location hint
instead of being hidden behind freecadcmd's silent fallback.
- `pyproject.toml` dependency metadata now matches the workbench's
runtime dependency gate: `shapely` and `rtree` are runtime
dependencies (they were dev-only extras while the workbench gate and
README already required them at runtime); `dev` extras now hold only
the test-only packages (`pytest`, `manifold3d`, `mapbox-earcut`).

## 0.17.7 — 2026-10-26

The last four releases (0.17.3 -- 0.17.6) were all field-discovered
Expand Down
15 changes: 12 additions & 3 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -158,11 +158,14 @@ modules for the whole session).
freecad/meshtofeatures_wb/ the FreeCAD workbench: commands, task
panel, and the PartDesign executor
core/ geometry core (FreeCAD-free: numpy/scipy/
trimesh/shapely) — fitting, segmentation,
snapping, feature detection, build planning
trimesh/shapely) — fitting, segmentation,
snapping, feature detection, build planning
scripts/ headless diagnostics (probe + smoke test)
tests/ pytest suite (450+ tests, runs without FreeCAD)
tests/ pytest suite (500+ tests, runs without FreeCAD)
docs/ design notes + verification guide

ROADMAP.md phased plan after v0.17.7 (executor CI,
feature depth, deviation report, sketching)
```

The core is deliberately FreeCAD-free so the entire planning pipeline is
Expand All @@ -179,6 +182,12 @@ pip install numpy scipy trimesh shapely manifold3d mapbox-earcut rtree pytest
python -m pytest freecad/meshtofeatures_wb/tests/ -q
```

CI (`.github/workflows/ci.yml`) runs two jobs on every push and PR: the
headless suite above on a Python 3.10/3.11/3.12 matrix, and the
in-FreeCAD executor smoke test (`scripts/freecad_smoke_test.py`, run with
`freecadcmd` inside a FreeCAD 1.1.x AppImage) — the part of the pipeline
only a real FreeCAD build can exercise.

## Contributing & bug reports

Issues and PRs are welcome. For reconstruction bugs, please attach the
Expand Down
130 changes: 130 additions & 0 deletions ROADMAP.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
# Roadmap

Working plan for MeshToFeatures after v0.17.7. Each phase is developed on
its own branch (see the branch name in each phase's header) and released
when its exit criteria are met. The order is deliberate: the process
guarantee first, then feature depth, then trust, then editability.

## Phase 1 — FreeCAD executor CI (`infra/freecad-executor-ci`)

The last five field fixes (issues #3–#8) were all executor regressions the
headless core suite cannot see. The core is in CI; the PartDesign executor
(`build.py`, ~1000 lines) is verified only by a manual smoke test. This
phase puts the executor in CI.

Scope:

- A second CI job (`freecad-smoke`) runs the existing
`scripts/freecad_smoke_test.py` (17 parts, full pipeline through
`build_body`, including the manifold3d deviation-correction case) inside
a real headless FreeCAD 1.1.x build (AppImage, sha256-verified) on every
push and PR.
- The smoke test's `check()` output is flushed per check: `freecadcmd`
drops unflushed Python stdout on `sys.exit()`, which would otherwise
hide all `[PASS]`/`[FAIL]` lines in CI logs.
- Dependency metadata brought in line with the runtime dependency gate
(`commands._missing_dependencies`): `shapely` (and `rtree`) are runtime
requirements, not dev-only; README / requirements.txt / pyproject.toml
stay mutually consistent.

Exit criteria:

- `freecad-smoke` job green on the FreeCAD 1.1.x stable AppImage with all
smoke checks visible in the log.
- A deliberate executor regression (e.g. a wrong volume tolerance) fails
the job — verified once during development.
- Headless suite still green; dependency docs accurate.

Status: **in progress**.

## Phase 2 — Feature depth: convex cones, spheres, tori

The README's core limitation is that the core *fits* spheres, tori, and
convex cones but the planner/executor do not *rebuild* them. Each item
reuses the existing pattern (feature rule in `features.py` → plan op in
`history.py` → placed primitive or dressup in `build.py` → corpus + smoke
case), gated by the mesh-veto doctrine and the unplanned doctrine.

Order (smallest documented gap first):

1. **Convex cones** (tapered bosses, draft-angled studs) as
`PartDesign::AdditiveCone` — the `SubtractiveCone` path (ConeOp)
already exists end to end; the convex rule, plan op, and executor
branch are the delta.
2. **Spheres** (spherical bosses and concave seats) — PartDesign has no
sphere primitive; the executor builds a placed `Part::Sphere` revolve
(circle sketch) fused/cut through the body, or declines loudly.
3. **Tori** (round blends on edges the fillet rule cannot claim) — the
largest of the three; revolve-based, and only where a full-revolution
torus fit is unambiguous.

Exit criteria: corpus parts carrying each new feature class with analytic
ground truth; smoke case per executor path; no unplanned/silent drops of
newly recognized features.

Status: not started.

## Phase 3 — Per-feature deviation report

The pipeline already computes the trust metrics internally (two-way p99
surface distance in the adversarial verification, the volume gate in
`_shape_from_mesh`, per-feature checks in `probe_bore_placement.py`) but
never shows them to the user. This phase surfaces them: a Report-view
table per rebuild listing, for every planned feature, its status
(rebuilt / deferred / skipped / undressable) and its measured deviation
from the source mesh, plus the overall volume ratio. The hybrid-modelling
story (edit the tree, *measure* the corrected feature) needs this to be
usable rather than asserted.

Exit criteria: the report renders for a corpus part and for the corner
bracket; numbers agree with the probe script's output; no new pipeline
math — plumbing only.

Status: not started.

## Phase 4 — Dimensioned, constrained sketches

`loop_to_sketch` currently emits geometry only. PartDesign::Hole carries
full parameters (resize-a-hole works), but pocket/pad/step *profiles* are
unconstrained: dragging an entity has no dimensions to preserve, which
undermines the "editable body" promise. This phase makes rebuilt profile
sketches fully constrained with named, snap-informed dimensions.

Exit criteria: corpus parts' rebuilt sketches report fully-constrained
status; a scripted dimension edit (e.g. deepen a pocket) survives the
solve; under/over-constrained sketches are reported, never silently
emitted.

Status: not started.

## Quick wins (any time, small branches)

- **One-click STEP export** of the rebuilt body (the common "I need the
STEP" end of the workflow).
- **Adoption content**: a short demo video, a before/after gallery, and a
FreeCAD forum thread. The addon pulls ~500 installs/month from the
official index; discoverability is the current constraint.

## Deferred (with reasons)

- **Noisy 3D-scan meshes.** Explicitly out of scope for the prismatic
target; the conditioning and snapping tolerances assume
CAD-exported tessellations. Revisit only after the prismatic core is
rock-solid and real scan feedback exists.
- **Multi-axis / revolve / swept parts.** An architectural leap beyond
the single-frame prismatic model; the terrace/step machinery is
frame-axis-specific.
- **Interactive recognition override.** Valuable for robustness, but a
large UX investment; the automatic-pipeline-plus-report identity is the
differentiator from the manual/assisted tools (e.g. Detessellate).

## Process

- One branch per phase/slice; branch names prefixed `infra/`, `feature/`,
or `fix/` per the existing convention.
- Every new executor path lands with a smoke-test case in the same change
(Phase 1 makes that check run automatically).
- Every new feature class lands with a corpus part and analytic ground
truth in the same change.
- `pyproject.toml`, `requirements.txt`, `package.xml`, `README.md`, and
this file are checked for staleness in every phase's final pass.
7 changes: 5 additions & 2 deletions freecad/meshtofeatures_wb/docs/VERIFY.md
Original file line number Diff line number Diff line change
@@ -1,8 +1,11 @@
# Verifying the FreeCAD adapter on your machine

The geometry core and the emission planner are fully covered by the pytest
suite (runs anywhere). The thin FreeCAD layer must be verified inside
FreeCAD itself -- follow this checklist once per FreeCAD version.
suite (runs anywhere). CI additionally runs the headless smoke test of
section 3 inside a FreeCAD 1.1.x AppImage on every push and PR, so the
AppImage baseline is regression-gated automatically. Follow this
checklist for YOUR FreeCAD build (another version, a Flatpak/snap/AppImage
install, or a new feature branch) -- once per FreeCAD version.

## 1. Install Python dependencies into FreeCAD's interpreter

Expand Down
45 changes: 34 additions & 11 deletions freecad/meshtofeatures_wb/scripts/freecad_smoke_test.py
Original file line number Diff line number Diff line change
Expand Up @@ -14,9 +14,16 @@
import os as _os
import sys as _sys
if _os.environ.get("_MTF_SMOKE_DONE") == "1":
_sys.stdout.write("[smoke] duplicate CLI invocation detected; skipping second run\n")
_sys.stdout.flush()
_os._exit(0) # some FreeCAD builds execute CLI scripts twice
# freecadcmd processes a .py argument as a MODULE IMPORT (loadModule)
# and, only if that import raises, falls back to runFile() -- a second
# execution of this file. Reaching the guard therefore means the first
# execution raised; exit NON-zero so the failure cannot be swallowed
# into a green run. The last [PASS] line above marks where it stopped.
_sys.stderr.write("[smoke] second invocation reached: the first run "
"failed -- the last [PASS] line above marks where "
"it stopped\n")
_sys.stderr.flush()
_os._exit(1)
_os.environ["_MTF_SMOKE_DONE"] = "1"

import math
Expand All @@ -40,7 +47,9 @@

def check(name, cond, info=""):
status = "PASS" if cond else "FAIL"
print(f"[{status}] {name}" + (f" ({info})" if info else ""))
# flush=True: freecadcmd drops unflushed Python stdout when the script
# ends via sys.exit(), so each check must reach the CI log immediately
print(f"[{status}] {name}" + (f" ({info})" if info else ""), flush=True)
if not cond:
fails.append(name)

Expand All @@ -54,7 +63,8 @@ def check(name, cond, info=""):
except ImportError as exc:
check("python dependencies importable", False, str(exc))
print("Install into FreeCAD's Python, e.g.: "
f"'{sys.executable}' -m pip install numpy scipy trimesh")
f"'{sys.executable}' -m pip install numpy scipy trimesh",
flush=True)
sys.exit(1)

# regression check for the freecad namespace-shadowing bug: FreeCAD's own
Expand All @@ -66,10 +76,21 @@ def check(name, cond, info=""):
except ImportError as exc:
check("freecad namespace merges (module_io importable)", False, str(exc))

from freecad.meshtofeatures_wb.core.pipeline import reconstruct # noqa: E402
from freecad.meshtofeatures_wb.core.snapping import snap_report # noqa: E402
from freecad.meshtofeatures_wb.core.emission import plan_patches # noqa: E402
from freecad.meshtofeatures_wb import emit # noqa: E402
try:
from freecad.meshtofeatures_wb.core.pipeline import reconstruct # noqa: E402
from freecad.meshtofeatures_wb.core.snapping import snap_report # noqa: E402
from freecad.meshtofeatures_wb.core.emission import plan_patches # noqa: E402
from freecad.meshtofeatures_wb import emit # noqa: E402
except Exception: # noqa: BLE001
# freecadcmd's import-failure fallback re-runs this file, where the
# guard above would exit non-zero with no root cause; print it here.
import traceback
traceback.print_exc()
print("[FAIL] addon import failed -- the smoke script must run from "
"its repository location (it resolves the addon root from its "
"own path: four levels above freecad/meshtofeatures_wb/scripts/)",
flush=True)
sys.exit(1)

# --- build & tessellate a known solid --------------------------------------
solid = Part.makeCylinder(10.0, 30.0) # r=10, h=30, axis +Z at origin
Expand Down Expand Up @@ -583,7 +604,9 @@ def check(name, cond, info=""):

out = os.path.join(tempfile.gettempdir(), "meshtofeatures_smoke.FCStd")
doc.saveAs(out)
print(f"\nDocument saved to: {out} (open it in FreeCAD to inspect)")
print(f"\nDocument saved to: {out} (open it in FreeCAD to inspect)",
flush=True)

print("\n" + ("ALL CHECKS PASSED" if not fails else f"FAILED: {fails}"))
print("\n" + ("ALL CHECKS PASSED" if not fails else f"FAILED: {fails}"),
flush=True)
sys.exit(0 if not fails else 1)
10 changes: 8 additions & 2 deletions pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -8,10 +8,16 @@ version = "0.17.7"
description = "Reverse-engineer analytic surfaces from triangle meshes (geometry core of a FreeCAD reverse-engineering addon)"
license = "LGPL-2.1-or-later"
requires-python = ">=3.10"
dependencies = ["numpy>=1.24", "scipy>=1.10", "trimesh>=4.0"]
dependencies = [
"numpy>=1.24",
"scipy>=1.10",
"trimesh>=4.0",
"shapely>=2.0",
"rtree>=1.0", # spatial index some trimesh versions require at runtime
]

[project.optional-dependencies]
dev = ["pytest>=7.0", "manifold3d>=2.0", "shapely>=2.0", "mapbox-earcut>=1.0", "rtree>=1.0"]
dev = ["pytest>=7.0", "manifold3d>=2.0", "mapbox-earcut>=1.0"]

[tool.setuptools.packages.find]
include = ["freecad*"]
Expand Down
Loading