- simplecad-cache/simplecad-export entry points are gone (hard cut): the same commands live under the unified dispatcher (simplecadapi.cli) as 'sca cache ...' and 'sca export ...', each group registered at parser level so per-group --help works - sca init now wires the shell by default (--no-shell skips): a ~/.sca/bin/sca shim (Windows sca.cmd) execs the installing venv's console script — the venv bin itself never goes on PATH — and the shim dir lands on PATH via a marked, removable block in ~/.zshenv (read by non-interactive shells, so agents see the command), ~/.bashrc, fish conf.d, or the Windows user PATH registry value with a change broadcast; rc files are created only for the login shell or when they already exist; re-running init refreshes the shim (target discovery is symlink-safe, no resolve() out of venv) - addon/cache/export cli modules expose configure(subparsers) + _execute(args); module run() keeps the CLI-shaped argv - docs: sca namespace across evergreen docs, shell-integration section, 'never writes shell profiles' contract line retired - tests: +17 (dispatcher groups, shell integration, entry-point absence); cache/export suites moved to group-token argv
5.6 KiB
Workflow: Export and Translation
Take a validated product package and produce the requested downstream deliverables.
Preferred command path
For normal delivery, use the package exporter CLI rather than writing a
one-off Python wrapper. It validates the .scadpkg, chooses the conventional
output names, prints one JSON report, and lets independent targets finish even
when an optional target is unavailable:
uv run sca export out/product.scadpkg --output-dir out/exports
Without --format, this writes AP242 STEP, binary STL, and OBJ. Add unusual
or backend-dependent outputs deliberately; --check performs all package,
output-path, and selected-target prerequisite checks without writing files:
uv run sca export out/product.scadpkg \
--format fcstd --format mjcf --output-dir out/exports --check
uv run sca export out/product.scadpkg \
--format fcstd --freecad-cmd /path/to/FreeCADCmd --output-dir out/exports
Use the lower-level Python APIs only when a workflow needs behavior the CLI does not expose, such as consuming a report in-process or a format-specific option not represented by a CLI flag.
Goal and scope
Use when geometry and product validation already passed and the remaining work is format conversion. If the model still needs work, route to the owning modeling workflow first — exports are deliverables, never validation.
Task decomposition
goal: requested export files from a validated .scadpkg
primary_domain: export-and-translation
required_domains:
- requirement-refinement # which formats and why
- export-and-translation
optional_domains:
- step-inspection # roundtrip validation of exports
artifacts:
- refreshed package (capture re-run if sources changed)
- sca export JSON report (or API reports for programmatic export)
validation_gates:
- package is current (sources unchanged since capture)
- each export report read and printed
- roundtrip validation when the consumer re-imports STEP
repair_routes:
- stale export -> re-capture, re-export
- coarse mesh -> tighten deflection parameters
- backend missing -> report; no silent format substitution
Steps
- Confirm the package is current: if any source changed since the last
capture, re-run the owning workflow's capture step. Exports are point-in-time deliverables. If this workflow edits any part source while making it current, the edit followsdiscipline/feature-tree-convention.mdblock structure. - Select targets by consumer contract
(
domains/export-and-translation.mdtable): editable FreeCAD document →.FCStd; neutral exchange → AP242.step; DCC/surface inspection →.obj; additive manufacturing →.stl; MuJoCo simulation → MJCF. - Preflight and export from the package path. Start with
uv run sca export <package>.scadpkg --output-dir <dir> --check. It checks the package and default STEP/STL/OBJ targets. Add each non-default target with--format; FCStd requires FreeCADCmd (or--freecad-cmd) and MJCF requires an assembly-rooted package. Re-run without--checkto write the files. Use--output FORMAT=PATHfor a non-conventional file name and--overwriteonly when replacement is intentional. - Read the JSON report: definition ids, occurrence/solid/triangle counts, material items, limitations, and per-target failures. Print the facts; never assume success from a missing exception. An unavailable optional target returns a nonzero status but does not erase successful independent exports.
- Validate roundtrip when it matters: consumers that re-import STEP →
validate_step_roundtrip_rdescriptoron the exported file. - Report: file paths, per-format report facts, parameters chosen (deflection values), and any backend that was unavailable.
API pages to read
capture (when re-capturing), this workflow's CLI command contract, the
exporter page(s) for every format requested when using APIs or interpreting
format-specific reports, the translator page(s) for every backend requested,
and validate_step_roundtrip_rdescriptor when roundtrip validation applies.
Validation gates
- Export report counts match the model's expectation (solids, occurrences, triangles).
- Tessellation accuracy chosen deliberately:
linear_deflectionin product units,angular_deflection_degreesfor curved surfaces; tighter for small curved parts, looser for large simple geometry when size matters. - MJCF: every intended joint present; loop-closing constraints emitted as equality/connect; public connectors only expose sites/endpoints.
.FCStd: translation consumed the intended package revision.sca export --checkpasses before delivery export; the final JSON report records every requested target as successful.
Failure routes
- FreeCAD/FreeCADCmd missing →
sca export --check --format fcstdreports the missing backend before writing. Export default STEP/STL/OBJ if requested, offer STEP as the neutral fallback, and say so explicitly. - STL/OBJ too coarse or too large → adjust deflection parameters, re-export; both formats share one tessellation pass.
- MJCF joints missing → the assembly lacked explicit constraints; return to
assembly-product-build.md, do not hand-edit MJCF.
Deliverables
Exported file paths, report facts per format, chosen parameters, unavailable backends, and checks not run.
Required reading before authoring or editing any part source in this
workflow: discipline/feature-tree-convention.md — the block-structured
sketch → basic body op → bool → modifier convention, its mandatory boundary
comments, and the sketch/geometry/primitive tier rules.