Global flags

Global flags can be placed before or after the subcommand. These are equivalent:

fascat --json inspect input.step
fascat inspect input.step --json

-h / --help and -V / --version are invocation-wide controls. They work before or after subcommands and ignore other arguments.

--verbose expands diagnostic output on stderr. Conversion report warnings are normally capped after 10 messages; with --verbose, Fascat prints the full warning list. --quiet suppresses non-essential diagnostics even when --verbose is also set.

--no-input is reserved for non-interactive automation. Fascat does not prompt today, and future prompts must first check that stdin is a TTY and that --no-input is not set.

A convert --dry-run emits JSON with operation_diagnostics — planned operations each tagged exact, approximate, or metadata_only. With --pipeline it also adds pipeline_advisories warning about ordering issues (decimation before repair, tangents without UV0, AO baking without UV1, LOD generation before LOD0 optimization). In non-JSON mode, add --verbose to print those planned operation diagnostics to stderr; --quiet suppresses them.

Exit codes

Errors are written to stderr in human mode. With --json, command errors are emitted as a single JSON object on stdout with the same command context plus an error string, while diagnostics remain on stderr.

JSON output schemas

All --json payloads are one JSON object on stdout. Optional sections are omitted when the matching flag or workflow is not used.

version

inspect

convert

validate

Conversion reports wrap the run in four steps: preflight (before expensive work — flags missing patch cleanup, orientation prep, UV/tangent ordering, AO-bake UV1 prerequisites, LOD0 optimization, and glTF compression notes), then near the end workflow_recipe (the profile's target recipe with honored/disabled/metadata-only/unsupported counts), conversion_manifest (resolved profile, import, operation, and export settings), and workflow_summary (preparation stages mapped to run/skipped status).

Commands

Format support matrix

This matrix is scoped to Fascat's current importer/exporter surface. It is meant to make Unity Asset Transformer-style format parity explicit, not to imply that all listed formats are implemented.

STEP import reports record two diagnostic steps:

• import_decisions — each import toggle (PMI, variants, existing meshes, construction cleanup, coordinate normalization) as requested vs. effective, with a status of honored, approximated, unsupported, disabled, not_present, or backend_default.
• loaded_representations — a per-part summary of BREP/construction-shape inputs, deleted construction-only nodes, and source topology counts. Free construction edges split from mixed face+curve shapes appear as separate construction-line parts or cleanup counts, per the construction-curve policy.

PMI (--pmi) runs a textual AP242 scan, writes typed PmiAnnotation metadata, and reports a pmi_semantic_graph. Design variants (--design-variants) scan configuration, effectivity, and condition records; --design-variant then prunes geometry by variant label, record id, effectivity value/range, or label=value assignment. The full list of supported STEP entity families and selection-resolution rules is documented once on the Python API page — the CLI flags drive exactly the same importer. metadata_and_visuals export adds deterministic glTF/USD marker meshes with simple vector text glyphs.

Full AP242 conditional/effectivity geometry evaluation and graphical PMI

presentation reconstruction remain planned backend work.

IGES import uses the same OCP/XDE shape-tree traversal for hierarchy, transforms, colors, and materials. BREP import creates one root occurrence and one part, keeping the native source shape for tessellation and healing.

JT import is a pure-Python reader (no OCP dependency) for JT 8.x, 9.x, and 10.x files. It decodes pre-tessellated LOD meshes (plain tri-strips in JT 8, topologically compressed tri-strip sets in JT 9/10), assembly hierarchy, instances, transforms, materials, and properties; parts are mesh-only (source_shape is None) and reuse the imported tessellation. Only the finest LOD is imported by default (--lod-selection all also fills Part.lod_meshes). Units come from the JT_PROP_MEASUREMENT_UNITS property (millimetres assumed when absent); JT declares no up axis, so the NX/Teamcenter Z-up right-handed convention is assumed — override with the standard --source-*/--target-* flags. Embedded precise B-rep (Parasolid XT), PMI, textures, JT 7 and older input, JT via stdin, and external (shattered) partition references are not supported; unsupported versions and B-rep-only files fail with explicit errors, and external references import as placeholder nodes with warnings.

Convert flags

Units

• Linear tolerances and sizes (--sag, --min-edge-length, --max-edge-length, --max-polygon-length, --heal-tolerance, --max-sliver-area, --region-size, --max-hole-diameter) use the source asset's working units unless stated otherwise.
• Angles (--angle, --normal-tolerance, --hard-edge-angle) are degrees.
• Ratios (--ratio, --lods, decimation ratios) and screen-coverage values are fractions between 0 and 1; LOD ratios must be sorted highest-to-lowest detail. File-size budgets are megabytes; atlas/bake sizes are pixels.
• Import space normalization uses a root transform: source coordinates stay in source units while the asset declares the target units, up-axis, and handedness, and the import report records the transform.
• tessellate, heal_brep, and repair report a tolerance_policy with effective source/target units, meter conversions, the active deflection kind, converted absolute lengths, and which cleanup backends are implemented.
• --sag and --sag-ratio are mutually exclusive in the effective tessellation options: passing --sag switches from the realtime profiles' relative sag_ratio=0.0002 default to an absolute tolerance.
• Migration note: current staging defaults use --normal-weighting area and --hard-edge-angle 45 instead of the older angle weighting and 30 degree threshold, so re-converted assets can shade or split vertices differently unless the older values are passed explicitly.

Repair

• face_orientation="exterior" is the implemented closed-component winding path; source-trusted, preserve, viewer-standpoint, open-shell, and unstitched-group policies are explicit in metadata rather than hidden behind fix_winding.
• fix_winding flips coherent closed shells with inward signed volume and records before/after flipped-component counts; it detects non-orientable shared-edge cycles first and warns on Möbius-like topology it cannot fix.
• T-junctions and boundary gaps are reported by default and fixed only with the opt-in fix_t_junctions / stitch_boundary_gaps flags; stitched vertices keep the surviving representative vertex's normals, tangents, and UVs, and UV-conflicting merges are counted in metadata.
• --delete-degenerate-polygons removes repeated-vertex, collapsed-edge, near-flat, and exact-duplicate polygons (separate report counts per reason); use --keep-duplicate-polygons to only report duplicates.

Decimation

• Keeping under 20% of source triangles emits an LOD0 distortion warning — prefer aggressive ratios for distant LODs.
• --decimate without --target-triangles/--ratio seeds its target from the profile or --target-device-profile triangle budget.
• --decimate-criterion quality passes tolerance-derived error bounds to the backend and records bound/result metadata.
• Reports include target_strategy (target count / ratio / quality), estimated RAM (Unity's ~5 GB per million source triangles), iterative pass counts, and per-part target allocation; plus protected hard-edge, hole-boundary, material-boundary, UV-seam, and silhouette face counts.
• --uv-importance: ignore strips UV/tangents first, preserve-seams uses then strips them, preserve-islands keeps them. --preserve-painted-areas and --preserve-ambient-occlusion add painted/protected and low-AO faces as constraints; --ambient-occlusion-strategy controls the AO direction set. --decimate-cleanup-attributes unused-uvs,tangents removes unused UV channels/tangents first.

Materials

• --merge-equivalent-materials compares PBR material factors with fixed six-decimal rounding for base color, metallic, roughness, and opacity, so importer floating-point noise does not prevent deduplication.

UVs

• --uv1 unwrap/lightmap bake channels are packed by xatlas with configured padding/resolution and report pack dimensions, utilization, and padding status. Bake-domain packing warns and clamps requested padding below 2 px to 2 px.
• box UV generation is reported as AABB projection; --uv-aabb-scope, --uv3d-size, and --uv-preserve-existing record local/shared bounds, scale, destination, override policy, and units.
• --uv-sharp-to-seam and --uv-forbid-overlapping are recorded as intent (the xatlas backend doesn't expose them directly) and validated after generation.

Material Baking

• --bake-materials collapses source material factors into the baked output with a simple arithmetic mean for base color, metallic, roughness, and opacity; atlas images carry the per-face raster detail.

LODs

• LOD reports separate source, newly added, retained imported, and full-chain vertex/triangle counts and payload bytes, so the memory/size cost and origin of extra levels are visible. Ratio LODs simplify progressively from the previous level while preserving each ratio against the source count.
• Chain advisories warn on more than four levels, over-aggressive LOD1/LOD2, and geometry-only far LODs that should bake to one mesh/material. Per-level metadata records simplification source, instance reuse, material merge, texture bake, culling-granularity changes, and resolved export representation.
• --lod-engine-profile unity emits MSFT_lod variant nodes; unreal emits separate _LOD# scene nodes for tools that ignore MSFT_lod.

Holes, occlusion, and compression

• --remove-holes uses mesh boundary classification and filling when BREP hole removal is unavailable; --hole-types filters inferred through/blind/surface loops.
• --remove-occluded uses deterministic sampled visibility — --occlusion-strategy sets the direction set, --hemi-evaluation restricts to upper-hemisphere/side views, and --occlusion-level picks parts/submeshes/triangles. Metadata records sample/direction coverage and a confidence score.
• --draco runs the Draco encoder for glTF/GLB. --texture-fallback-format auto keeps alpha-bearing sets PNG and color-only sets JPEG when KTX2/Basis isn't requested; explicit jpeg warns when it would discard transparency.

Validation previews

fascat validate can write review artifacts (full detail on the Python API page):

• --visual-preview / --lod-preview-dir — software-rendered PNGs of the output mesh and per-LOD contact sheet.
• --turntable-dir — software-rendered turntable PNGs from --turntable-views azimuths at each --turntable-elevations elevation, plus a turntable.png contact sheet grid. --turntable-baseline-dir diffs each view against a same-named baseline PNG using the --visual-diff-* thresholds and fails validation when any view drifts. Framing auto-fits each view, so diffs catch silhouette and shading changes rather than absolute size changes.
• --runtime-browser / --runtime-browser-preview — headless Chromium WebGL load/FPS measurement and screenshots for supported glTF/GLB primitives.

Inspect flags

Supported filter expressions use case-sensitive shell-style fnmatchcase patterns for string fields (*, ?, and character classes), not regular expressions:

Repeated --filter flags are combined with logical AND. Use --exclude-filter for negative selectors.

Pipeline files

Use --pipeline when different assembly branches need different ordered steps.

[import]
metadata = "full"
pmi = true
design_variants = false
design_variant_selection = []
existing_meshes = true
multi_file = false
material_library_paths = ["vendor-materials.json"]
material_library_color_space = "auto"
delete_free_vertices = false
delete_lines = false
construction_curve_policy = "preserve_metadata"
construction_curve_tube_radius = 0.01
target_units = "metre"
target_up_axis = "Y"
target_handedness = "right"

[export]
metadata = "summary"
pmi = "metadata"

[[filters]]
name = "fasteners"
path = "*/Fasteners/*"
names = ["Bolt*", "Nut*", "Washer*"]

[[filters]]
name = "large_castings"
path = "*/Housing/*"
min_diagonal = 50.0

[[steps]]
op = "tessellate"
where = "large_castings"
sag = 0.03
sag-ratio = 0.005
max-polygon-length = 5.0
free-edge-report = true
reuse-existing-meshes = false
angle = 10.0

[[steps]]
op = "tessellate"
where_not = "large_castings"
sag = 0.2
angle = 20.0

[[steps]]
op = "merge_vertices"
tolerance = 0.001
preserve_uvs = true
preserve_material_boundaries = true
quality_report = true

[[steps]]
op = "delete_degenerate_polygons"
area_epsilon = 1e-12

[[steps]]
op = "merge"
where = "fasteners"
mode = "by_material"
metadata = "combine"

fascat convert motor.step motor.glb --pipeline realtime.toml

Pipeline files are validated before conversion starts. Unknown top-level, filter, import/export, or operation keys are rejected, and option constraints such as invalid numeric ranges, missing external_path, conflicting where / where_not, or unsupported operation names fail during parse. CLI errors include line N when the source file location can be identified.

Unity-inspired capability matrix

This matrix maps Unity Asset Transformer-style CAD-to-runtime capabilities to the current Fascat behavior. Use dry-run operation_diagnostics, report workflow_summary, and report step warnings to distinguish exact work from fallbacks.

The Report step column names where to look for the detail; the linked sections above and on the Python API page document each field.

Validate flags

When any gate threshold flag, --strict-geometry, or --profile is set, validate evaluates the requested gates, prints one PASS|FAIL|SKIP <gate> <actual> <op> <limit> line per gate plus an OVERALL line on stdout, and exits 1 when any gate fails. Gates whose input is unavailable or inapplicable are reported as SKIP and never fail validation. Structural validity, visual diff, turntable diff, and LOD monotonicity are reported through the same gate mechanism.

Gated example:

fascat --json validate motor.glb \
  --strict-geometry \
  --profile realtime-web \
  --max-file-size-mb 25 \
  --turntable-dir views/ \
  --turntable-baseline-dir reference-views/

Example:

fascat validate motor.glb \
  --filter 'path=*/Fasteners/*' \
  --geometry-quality \
  --non-manifold-edges \
  --open-boundaries \
  --self-intersections \
  --sliver-triangles \
  --tiny-parts \
  --draw-call-estimate \
  --visual-risk \
  --visual-preview preview.png \
  --visual-baseline baseline.png \
  --lod-preview-dir preview-lods/ \
  --turntable-dir preview-views/ \
  --runtime-browser \
  --report report.json

File arguments

Use - for standard streams:

cat input.step | fascat inspect -
cat input.step | fascat convert - - --stdout-format glb --profile realtime-web
cat output.usdc | fascat validate -

When the convert output argument is omitted for a file input, Fascat writes beside the input with a .usdc suffix. Stdin input requires an explicit output path or -.

When output is -, --stdout-format selects the emitted format and defaults to usda. Progress/errors stay on stderr.

Supported input suffixes are .step, .stp, .igs, .iges, and .brep. Supported output suffixes are .usd, .usda, .usdc, .usdz, .gltf, .glb, .obj, .stl, and .fbx.

--debug is only valid with .usd or .usda output. Binary .usdc, .gltf, and .glb output is rejected when debug mode is enabled.

convert validates the generated asset before reporting success. If validation fails, the command exits non-zero.

convert prints up to 10 report warnings (budget violations, tessellation and UV advisories, export policy notes) on stderr after a successful run; --quiet suppresses them and --json keeps them in the JSON payload instead. Pass --report report.json for the full list.

All exporters write transactionally: content is produced at a hidden temp file in the destination directory, validated there, and atomically renamed into place only on success. A failed or interrupted export never leaves a partial or corrupt file at the output path (sidecar files from a previous differently-named export are not garbage-collected).

Benchmarking

Use the benchmark harness before performance-sensitive changes:

make benchmark
# or
uv run python scripts/benchmark.py tests/fixtures/vertical-screw.step --output-dir dist/benchmarks --output-suffix .glb

The harness writes JSON with total wall time, process peak RSS where the platform exposes it, per-report-step durations, output paths, and final mesh statistics. Pass --repeat N for repeated runs and --validate-output when the validation round trip should be included in the measured path.

Output streams

When --json is active, expected runtime errors are reported as JSON payloads on stdout and still exit non-zero.

Environment variables

Color is also disabled when --no-color is passed, TERM=dumb, or the relevant stream is not a TTY.

Exit codes

Fascat keeps exit codes stable for scripts: 0 means the command completed, 1 means the command was valid but failed at runtime or validation, and 2 means the invocation or option values were invalid before the requested work could run.

Shell completions

Typer provides built-in shell completion support:

# Install completion for your shell (auto-detects)
fascat --install-completion

# Show the completion script without installing
fascat --show-completion