From 402875861c3ace714121c601ab6f07d2ea15fcd7 Mon Sep 17 00:00:00 2001 From: Masoud Masoumi Date: Wed, 28 Oct 2026 13:29:49 -0400 Subject: [PATCH] Add FreeCAD executor CI: freecad-smoke job on a sha256-verified FreeCAD 1.1.4 AppImage (cached download, AppRun pip deps, freecadcmd smoke run with an ALL CHECKS PASSED / FAILED sentinel because freecadcmd exits 0 when a script raises); harden freecad_smoke_test.py (flushed per-check output, duplicate-invocation guard now exits non-zero, addon-import failures print their root cause); ROADMAP.md phases 1-4; pyproject/README/CHANGELOG/VERIFY dependency and doc sync --- .github/workflows/ci.yml | 71 ++++++++++ CHANGELOG.md | 36 +++++ README.md | 15 +- ROADMAP.md | 130 ++++++++++++++++++ freecad/meshtofeatures_wb/docs/VERIFY.md | 7 +- .../scripts/freecad_smoke_test.py | 45 ++++-- pyproject.toml | 10 +- 7 files changed, 296 insertions(+), 18 deletions(-) create mode 100644 ROADMAP.md diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 2b34621..c85dc05 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -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 diff --git a/CHANGELOG.md b/CHANGELOG.md index 768b5c2..644132b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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 diff --git a/README.md b/README.md index c923836..b1d793f 100644 --- a/README.md +++ b/README.md @@ -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 @@ -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 diff --git a/ROADMAP.md b/ROADMAP.md new file mode 100644 index 0000000..50223b3 --- /dev/null +++ b/ROADMAP.md @@ -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. diff --git a/freecad/meshtofeatures_wb/docs/VERIFY.md b/freecad/meshtofeatures_wb/docs/VERIFY.md index 907422f..a746d51 100644 --- a/freecad/meshtofeatures_wb/docs/VERIFY.md +++ b/freecad/meshtofeatures_wb/docs/VERIFY.md @@ -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 diff --git a/freecad/meshtofeatures_wb/scripts/freecad_smoke_test.py b/freecad/meshtofeatures_wb/scripts/freecad_smoke_test.py index b5366f0..a782f1a 100644 --- a/freecad/meshtofeatures_wb/scripts/freecad_smoke_test.py +++ b/freecad/meshtofeatures_wb/scripts/freecad_smoke_test.py @@ -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 @@ -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) @@ -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 @@ -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 @@ -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) diff --git a/pyproject.toml b/pyproject.toml index c0e2d61..84f099b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -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*"]