gnucleus-freecad-validator

Deterministic validation for FreeCAD CAD geometry, design specifications, and solved FreeCAD/CalculiX FEM analyses. Reproducible, no LLM, no GPU.

Prerequisites

• Python ≥ 3.11
• FreeCAD 1.1.0 recommended. FreeCAD 0.21.x remains supported for non-FEM validation, but FEM validation requires FreeCAD 1.1.0.

For a reproducible FreeCAD 1.1.0 installation, the official 1.1.0 release provides these platform-specific assets:

Pick the download that matches your CPU — the two macOS disk images are not interchangeable.

Prefer a known build over a rolling package manager when reproducibility matters. brew install --cask freecad tracks the newest release and can move off 1.1.0; on Ubuntu / Debian, both the distro package and the freecad-stable PPA can lag behind. FreeCAD 0.21.x from those sources remains supported for non-FEM validation. If you use a package manager, check freecad --version before relying on it.

Under conda / mamba, FreeCAD's binding lands in $CONDA_PREFIX/lib rather than site-packages, which the loader already looks for first.

Pin the build, not just the version

Scores are only comparable when they come from the same geometry kernel, and FreeCAD 1.1.0 does not imply one OCCT version — the kernel travels with the build:

Both report the same FreeCAD build string, 1.1.0 20260325, so the version alone does not tell you which kernel you are on.

Volume, surface-area, and surface-type measurements can shift across kernels, so generate references and score candidates with the same build — not merely the same FreeCAD version. Check yours with:

python -c "from freecad_validator._freecad_loader import import_freecad; import_freecad(); import Part; print(Part.OCC_VERSION)"

Locating the binding

The validator auto-detects FreeCAD's Python binding for these installs, so pip install gnucleus-freecad-validator and import-and-use just work — no PYTHONPATH wrangling:

Windows and the Linux AppImage are not auto-detected — they have no fixed install location — so set FREECAD_LIB for those (below). The package works fine with them; it just cannot guess where they are.

FREECAD_LIB accepts a single directory or an os.pathsep-separated list (: on Unix, ; on Windows — same convention as PATH and PYTHONPATH), so you can point at every directory FreeCAD needs in one variable. It is tried before the built-in candidates, and a value that doesn't resolve falls back to them rather than failing outright:

# conda / mamba — the binding sits directly under the env's lib/.
export FREECAD_LIB="$CONDA_PREFIX/lib"

# macOS (Homebrew cask) — single path; the .app bundle finds its own
# workbenches relative to the binary.
export FREECAD_LIB=/Applications/FreeCAD.app/Contents/Resources/lib

# Linux (apt / PPA install) — three paths: the binding under lib/,
# the package-root Mod (often a symlink to /usr/share/freecad/Mod),
# and the canonical workbench tree itself.
export FREECAD_LIB=/usr/lib/freecad/lib:/usr/lib/freecad/Mod:/usr/share/freecad/Mod

# Linux AppImage — extract it first; the bundle is not a normal install.
#   ./FreeCAD_1.1.0-Linux-x86_64-py311.AppImage --appimage-extract
export FREECAD_LIB=$PWD/squashfs-root/usr/lib:$PWD/squashfs-root/usr/Mod

On Windows, point it at the directory holding FreeCAD.pyd — the installer's bin directory — using ; as the separator:

$env:FREECAD_LIB = "C:\Program Files\FreeCAD 1.1\bin"

Verify the wiring. The recommended 1.1.0 install reports 1, 1, 0 in the first three fields; a supported 0.21.x install reports 0, 21 in the first two:

python -c "from freecad_validator._freecad_loader import import_freecad; print(import_freecad().Version())"

Install

pip install gnucleus-freecad-validator

Usage

CLI

freecad-validator validate my_model.FCStd ground_truth.FCStd spec.json

freecad-validator is the package's entry-point; --help shows the validate, batch, join, render, and fem-score subcommands.

Python

from freecad_validator import Validator

validator = Validator()
result = validator.validate(
    candidate_fcstd="path/to/my_model.FCStd",
    reference_fcstd="path/to/ground_truth.FCStd",
    spec_json="path/to/spec.json",
)
result.combined  # combined verdict, in [0, 1] (harmonic mean by default)
result.geometry_similarity  # geometry-only sub-score
result.cad_spec_consistency  # spec ↔ CAD sub-score

For repeated scoring, reuse one Validator across cases — its internal scorers amortize across calls.

FEM validation

[!IMPORTANT] FEM validation requires FreeCAD 1.1.0. FreeCAD 0.21.x is supported only for non-FEM validation.

The FEM API compares a candidate solved FCStd with an engineer-generated solved reference on a source STEP. It extracts the saved analysis, replays the candidate solve with CalculiX, verifies the stored displacement and stress fields, and returns a deterministic 0–100 report with validity gates and engineering diagnostics.

from freecad_validator.fem import FEMValidator

validator = FEMValidator(require_boolean=True)
report = validator.validate(
    step_path="source.step",
    reference_fcstd="reference.FCStd",
    candidate_fcstd="candidate.FCStd",
)
print(report.overall_score, report.grade, report.gates_triggered)

Trusted, already-extracted dictionaries can be scored without FreeCAD or CalculiX:

from freecad_validator.fem import score_trusted_payloads

report = score_trusted_payloads(target_geometry, reference_payload, candidate_payload)

This low-level function trusts adapter-produced replay-verification fields. Do not pass candidate-controlled JSON to it. Use FEMValidator.validate() for untrusted FCStd inputs so the validator performs extraction and solver replay.

The equivalent CLI is:

freecad-validator fem-score source.step reference.FCStd candidate.FCStd \
  --timeout 900 --json

Use --require-boolean only for tasks whose metadata explicitly requires a Boolean operation, and --require-preprocessing only when preprocessing is an explicit task requirement. Neither requirement is inferred from instruction text. Intermediate extraction JSON is temporary by default; pass --extract-dir to retain it.

[!WARNING] FEM validation executes FreeCAD and CalculiX subprocesses against the candidate document. Although the FCStd adapter rejects archive path traversal before opening the file, untrusted submissions should still be validated in a locked-down container with no network access and no sensitive host mounts.

Scoring

Two independent passes per case:

The two are combined into result.combined so a strong score on one axis cannot rescue a weak score on the other. The aggregation method is configurable via Validator(combine_method=...) or --combine-method on the CLI; both options return 0 when either g or s is 0.

where g = geometry_similarity and s = cad_spec_consistency. All three values are in [0, 1].

from freecad_validator import Validator

Validator(combine_method="min")  # use min() instead of harmonic mean

freecad-validator validate ... --combine-method min
freecad-validator batch    ... --combine-method min

Tolerances

Pass GeometryTolerances or SpecTolerances to Validator to make the scoring stricter or more lenient. Each axis on the geometry side has a matched threshold (score = 1.0 at or below) and a far threshold (score = 0.0 at or above), with a smooth ramp in between.

Geometry — defaults:

Spec consistency — defaults:

from freecad_validator import Validator, GeometryTolerances, SpecTolerances

validator = Validator(
    geom_tolerances=GeometryTolerances(volume_matched_rel_tol=5e-4),
    spec_tolerances=SpecTolerances(tol_scalar=0.05),
)

Every field is also a CLI flag in --kebab-case (e.g. --volume-matched-rel-tol, --tol-scalar) on freecad-validator validate and batch. See the GeometryTolerances and SpecTolerances classes for the full field list.

Inputs

The validator takes three paths — names and on-disk layout are up to the caller:

Optional spec field categories: ["gear", ...] opts into family-specific checks.

param_check.py auto-discovery

If param_check.py sits next to the candidate FCStd (Path(candidate_fcstd).parent / "param_check.py"), the validator loads it dynamically to refine spec-consistency findings. Anything else in the directory is ignored.

Trust boundary — this executes arbitrary Python. The file is imported and run in the validator's own process, with its privileges. Validating a case directory is therefore equivalent to running code from it. This is fine for cases you author, but if you score candidates produced by an untrusted party (a model under evaluation, a submitted archive), do not let that party write into the directory holding the candidate FCStd — a param_check.py dropped there runs unsandboxed. Isolate untrusted runs at the process or container level, or stage the candidate FCStd into a directory you control.

Batch CLI layout

freecad-validator batch --sample-data-dir <sample-data-dir> expects one folder per case under <sample-data-dir>/data/:

<sample-data-dir>/data/<case-name>/
├── candidate.FCStd
├── reference.FCStd
├── spec.json                 # any *.json — see below
└── param_check.py            # optional

<case-name> only labels rows in the output CSV. Spec lookup tries spec.json, then <case-name>.json, then any single *.json. Outputs default to <sample-data-dir>/validation_results.csv and validation_summary.json (override with --output-csv / --output-summary).

Adding a custom Category

Define derived_candidates(bank, spec) that returns {spec_key: (value, feature_ref)}. Reference it from a case's param_check.py. The built-in categories under src/freecad_validator/consistency/categories/ are worked examples — each module's docstring states the spec keys that trigger it.

License

Apache 2.0 — see LICENSE.

This project depends on FreeCAD, which is licensed under LGPL 2.1+. FreeCAD is not bundled with this package.

Full FCStd FEM validation requires CalculiX, which is licensed under GPL 2.0 or later and is not bundled with this package. Install a ccx executable for the validator runtime, or configure ccxBinaryPath in FreeCAD's FEM preferences. The runtime preflight verifies FreeCAD, OCCT, the embedded Python, and CalculiX before candidate scoring; these versions are recorded in ScoringReport.runtime_provenance.

• macOS: the official FreeCAD application includes ccx beside freecadcmd, which the validator detects automatically.
• Linux: install CalculiX with the system package manager and ensure ccx is executable on PATH.
• Windows: install a CalculiX executable and select it as ccxBinaryPath in FreeCAD's FEM preferences.