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.

Dry-run JSON for convert includes operation_diagnostics, a list of planned operations with level set to exact, approximate, or metadata_only. When --pipeline is used it also includes pipeline_advisories, warning about ordering issues such as decimation before repair, tangents without UV0, AO baking without UV1, and LOD generation before LOD0 optimization. Conversion reports include a preflight step before expensive work starts, followed near the end by workflow_recipe, conversion_manifest, and workflow_summary steps. The preflight checklist flags missing patch cleanup, orientation preparation, UV/tangent ordering, AO bake UV1 prerequisites, and LOD0 optimization, plus glTF compression applicability notes. The workflow recipe records the selected profile's Unity-inspired target recipe and counts honored, disabled, metadata-only, and unsupported choices. The conversion manifest records the resolved profile, import, direct or pipeline operation settings, and export options; the workflow summary maps Unity-inspired preparation stages to run/skipped status and exact, approximate, or metadata-only levels.

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 report steps include import_decisions, which separates requested, effective, honored, approximated, unsupported, disabled, not_present, and backend_default states for Unity-style import toggles such as PMI, variants, existing meshes, construction cleanup, and coordinate normalization. PMI import uses a textual AP242 scan for common dimension, location, geometric tolerance and named geometric-tolerance subtypes, plus/minus tolerance, datum, datum-reference, feature-control-frame, and annotation text records and writes typed PmiAnnotation metadata plus a pmi_semantic_graph of STEP entity nodes and reference edges, including common target support records and inbound callout/annotation associativity, tolerance-zone, and annotation-presentation support records. metadata_and_visuals export writes deterministic glTF/USD PMI marker meshes with simple vector text glyphs linked to those records; full AP242 visual presentation reconstruction remains planned. Report steps also include detected STEP design variant configuration/effectivity metadata when design_variants is enabled; design_variant_selection can prune imported geometry by selected variant labels, STEP record ids, exact effectivity values, or values inside supported serial/date/time-interval effectivity ranges when those records resolve to labels that match imported node, part, or source-name metadata, including referenced TIME_INTERVAL_WITH_BOUNDS date bounds using CALENDAR_DATE, ORDINAL_DATE, or WEEK_OF_YEAR_AND_DAY_DATE records. Simple AP242 condition/expression records such as AND_EXPRESSION, OR_EXPRESSION, XOR_EXPRESSION, NOT_EXPRESSION, EQUALS_EXPRESSION, COMPARISON_EQUAL, COMPARISON_NOT_EQUAL, COMPARISON_GREATER, COMPARISON_GREATER_EQUAL, COMPARISON_LESS, COMPARISON_LESS_EQUAL, INTERVAL_EXPRESSION, LIKE_EXPRESSION, simple numeric arithmetic expressions such as PLUS_EXPRESSION, MINUS_EXPRESSION, MULT_EXPRESSION, DIV_EXPRESSION, SLASH_EXPRESSION, MOD_EXPRESSION, and POWER_EXPRESSION, RATIONAL_REPRESENTATION_ITEM, EXPRESSION_EXTENSION_NUMERIC, numeric functions such as ABS_FUNCTION, MINUS_FUNCTION, SQUARE_ROOT_FUNCTION, MAXIMUM_FUNCTION, MINIMUM_FUNCTION, SIN_FUNCTION, COS_FUNCTION, TAN_FUNCTION, ASIN_FUNCTION, ACOS_FUNCTION, unary or binary ATAN_FUNCTION, EXP_FUNCTION, LOG_FUNCTION, LOG2_FUNCTION, and LOG10_FUNCTION, simple string expressions such as CONCAT_EXPRESSION, SUBSTRING_EXPRESSION, INDEX_EXPRESSION, FORMAT_FUNCTION, and EXPRESSION_EXTENSION_STRING, and string-derived numeric functions such as LENGTH_FUNCTION, VALUE_FUNCTION, INT_VALUE_FUNCTION, ODD_FUNCTION, BOOLEAN_LITERAL, BOOLEAN_REPRESENTATION_ITEM, LOGICAL_LITERAL, LOGICAL_REPRESENTATION_ITEM, BOOLEAN_VARIABLE, and MATHS_BOOLEAN_VARIABLE are reported with condition operators, and boolean or logical literals include parsed true/false values. Numeric literals include parsed numeric values, including expression-extension numeric values; string literals include parsed text values, including expression-extension string values. Supported conditions gate their operand labels before those labels can drive geometry pruning; expression-only operand labels are not promoted as geometry targets; equality/not-equality records compare resolved numeric/string operand values and fall back to selected boolean operand states for non-value operands. Named maths numeric variables evaluate from selected label=value assignments for numeric comparisons, intervals, equality/not-equality, numeric function expressions including rational representation items, expression-extension numeric values, and elementary trig/log/exp functions, with two-operand ATAN_FUNCTION evaluated as atan2, and ODD_FUNCTION integer tests. String variables evaluate from selected label=value assignments for equality/not-equality, LIKE_EXPRESSION, CONCAT_EXPRESSION, SUBSTRING_EXPRESSION, INDEX_EXPRESSION, EXPRESSION_EXTENSION_STRING, LENGTH_FUNCTION, VALUE_FUNCTION, and INT_VALUE_FUNCTION matching, while numeric variables can feed conservative FORMAT_FUNCTION string matching, boolean variables act as named operands selected by label, STEP record id, or explicit label=true / label=false assignments, and conditional/effectivity-assignment wrappers, including CONDITIONAL_CONCEPT_FEATURE, CONDITIONAL_EFFECTIVITY, CONFIGURED_EFFECTIVITY_ASSIGNMENT, and APPLIED_EFFECTIVITY_ASSIGNMENT, also gate their configured target labels. APPLIED_INEFFECTIVITY_ASSIGNMENT records are reported and suppress assigned target labels when the selected effectivity matches. Applied assignment targets can resolve through referenced product-definition labels. Effectivity context-assignment wrappers add their context target labels only when the referenced effectivity assignment is satisfied. Product-definition and configuration effectivity records add their usage relationship labels only when the selected effectivity matches. Effectivity relationship records can bridge selected effectivity labels to related gated usage records. Report steps also include loaded_representations, a per-part BREP/construction-shape summary plus deleted construction-only nodes and source topology counts. Free construction edges split from mixed face+curve STEP shapes appear as separate construction-line parts or construction cleanup counts, depending on the construction-curve policy. 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 with the native source shape retained for tessellation and healing.

Convert flags

Units and behavior notes:

• Linear tolerances and sizes such as --sag, --min-edge-length, --max-edge-length, --max-polygon-length, --heal-tolerance, --max-sliver-area, --region-size, and --max-hole-diameter use the source asset's working units unless the option explicitly says otherwise.
• Import space normalization uses a root transform: source BREP coordinates stay in source units, while the asset declares the target units, up-axis, and handedness and records the transform in the import report.
• tessellate, heal_brep, and repair report steps include tolerance_policy, which records effective source/local units, declared target units, meter conversions, active tessellation deflection kind, converted absolute tessellation lengths where applicable, and whether related repair cleanup backends such as T-junction sewing, boundary-gap stitching, or non-manifold cracking are implemented.
• repair detects non-orientable shared-edge cycles before winding normalization and warns when Mobius-like topology cannot be fixed by ordinary face flipping.
• repair records face and normal orientation policy. 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 and report status instead of being hidden behind fix_winding.
• repair records before/after flipped closed-component counts. fix_winding flips coherent closed shells with inward signed volume when possible and warns if flipped components remain.
• repair records before/after T-junction counts and warns when T-junctions remain, because the current mesh repair path reports but does not sew them.
• repair records nearby unstitched boundary gap counts and warns when boundary gaps remain, because the current mesh repair path reports but does not stitch them.
• --delete-degenerate-polygons removes repeated-vertex, collapsed-edge, near-flat, and exact duplicate polygons by default, with separate report counts for each reason; use --keep-duplicate-polygons when duplicate triangles should only be reported.
• Angles such as --angle, --normal-tolerance, and --hard-edge-angle are degrees.
• Ratios such as --ratio, --lods, and decimation target ratios are fractions between 0 and 1; LOD ratios must be sorted from highest to lowest detail.
• Explicit decimation requests that keep less than 20% of source triangles emit an LOD0 distortion warning. Use those aggressive ratios primarily for distant LODs unless visual validation says otherwise.
• Explicit decimation report metadata includes target_strategy data that distinguishes explicit target-count, target-ratio, and quality/error approximation workflows, plus estimated RAM using the Unity rule of thumb of 5 GB per million source triangles, the iterative threshold, whether iterative decimation is recommended, actual simplification and iterative pass counts, whether the target was allocated globally across the selection or per part, and per-part target allocation summaries.
• When --decimate is enabled without --target-triangles or --ratio, the selected profile or --target-device-profile triangle budget seeds the explicit decimation target when available.
• Screen coverage values are fractions between 0 and 1; file-size budgets are megabytes; atlas and bake sizes are pixels.
• LOD report metadata separates source, added-LOD, and full-chain vertex/triangle counts plus estimated mesh payload bytes, making the memory and export-size tradeoff of extra LOD levels visible before runtime testing. Ratio LODs simplify progressively from the previous generated level while preserving each requested ratio against the source triangle count.
• LOD chain advisories warn when a chain has more than four generated levels, when LOD1 or LOD2 are too aggressive for close or mid views, and when the farthest LOD is still geometry-only and should eventually use one-mesh/one-material baking.
• LOD per-level policy metadata reports the simplification source, whether instances were reused, whether materials were merged, whether textures were baked, whether culling granularity changed, which advisory applies to each level, and the resolved export representation. --lod-engine-profile unity emits standard MSFT_lod variant nodes for glTFast-oriented import, while --lod-engine-profile unreal emits separate _LOD# scene nodes so import tooling that ignores MSFT_lod can still see the generated meshes.
• fascat validate output.glb --visual-preview preview.png --lod-preview-dir previews/ writes local software-rendered PNG review artifacts. --visual-preview renders the validated output mesh with material base colors and node transforms; --lod-preview-dir writes lod0.png, each available LOD level, and lod-switching.png with monotonic triangle-count metadata in JSON mode.
• fascat validate output.glb --runtime-browser-preview preview.png writes a browser/WebGL-rendered PNG for supported glTF/GLB mesh primitives, including node transforms, material base-color factors, quantized vertex attributes, Draco geometry decoded through glTF Transform, meshopt exports that keep fallback buffer data, meshopt bufferViews without fallback buffer data decoded through local meshoptimizer, KTX2/Basis textures decoded through the default Python alktx2 backend on supported Python 3.11+ Linux/Windows x86_64 installs or glTF Transform plus KTX-Software when available, optional KHR_texture_basisu textures with PNG fallbacks, and supported base-color image URI/data URI texture sampling. The browser preview preflights compressed runtime extensions: Draco or meshopt decode tooling failures return status="unsupported", while unavailable KTX2/Basis texture decode tooling can still render fallback texture sources as status="rendered_partial" with unsupported_extensions and preview_limitations; assets without fallbacks render geometry only. Sparse accessors and full engine material/lighting parity remain outside this preview path.
• fascat validate output.glb --runtime-browser runs a Chromium-compatible headless browser when available, loads the GLB/GLTF bytes, executes a bounded WebGL triangle workload derived from asset triangle count, and reports measured browser load time, FPS, frame count, memory bytes, and workload scale. If no browser is available, the runtime report is marked unavailable instead of estimated.
• fascat validate output.glb --runtime-engine unity or --runtime-engine unreal launches a local engine harness and records measured engine-process load/parse time, frame count, memory bytes, engine version, mesh count, and triangle count. When --runtime-engine-project is omitted, Fascat runs a packaged temporary Unity or Unreal harness template. Pass --runtime-engine-project Harness/ or --runtime-engine-project Harness.uproject to use a customized project, and use --runtime-engine-command or FASCAT_UNITY / UNITY_EDITOR / FASCAT_UNREAL / UNREAL_EDITOR when the engine executable is not on PATH; missing engines or explicit projects are reported as unavailable. --runtime-engine-preview preview.png reports render_status, render_time_ms, rendered_frames, render_backend, render_limitations, render_error, and preview_path; --runtime-engine-baseline baseline.png compares a rendered engine preview against a baseline with the --visual-diff-* thresholds and fails validation on drift. The packaged Unity template uses glTFast to instantiate the scene, render a fixed multi-frame camera loop with measured_fps, and write a camera-rendered PNG when graphics are available. The packaged Unreal commandlet now rasterizes supported GLB triangle geometry with material baseColorFactor into a deterministic PNG and fixed-frame software benchmark; unsupported assets fall back to render_status="rendered_partial" with explicit limitations. Full Unreal scene-rendered screenshots/FPS and checked-in engine-specific golden corpora remain open. fascat runtime-fixtures DIR writes bundled PBR material, texture-map, optional KTX2/Basis fallback, normal/lighting, Unity MSFT_lod, and Unreal separate-node LOD-profile GLB fixtures with software baseline PNGs, target-golden paths, and a manifest for browser, Unity, and Unreal preview comparisons; add --capture browser, --capture unity, or --capture unreal to write preview captures and runtime-parity-captures.json, --promote-goldens to copy rendered captures into goldens/<target>/, and --require-goldens to fail when requested target golden files are absent. --check-goldens writes runtime-parity-golden-coverage.json without rendering; combined with --require-goldens, it fails on missing, invalid, or wrong-size target PNGs.
• --decimate-criterion quality passes tolerance-derived target error bounds to the simplification backend and records bound/result metadata plus achieved triangle reduction.
• Explicit decimation reports protected hard-edge, hole-boundary, material-boundary, UV-seam, silhouette, and total feature-face counts so topology/material/UV preservation pressure is visible.
• --uv-importance ignore strips UV/tangent attributes before simplification; preserve-seams uses UVs for seam preservation and then strips them; preserve-islands keeps UVs through the output.
• --preserve-painted-areas and --preserve-ambient-occlusion add painted/protected face groups, metadata-marked face indices, and low-AO faces to the simplification constraints. Reports include painted-area, AO, and combined importance-face counts.
• --decimate-cleanup-attributes unused-uvs,tangents removes empty, constant, or zero-area UV channels and tangents before simplification. Reports record removed channels, removed tangent parts, preserved UV channels, and warn when preserved UV seams or islands can reduce simplification efficiency.
• Bake-domain UV channels generated with --uv1 unwrap or --uv1 lightmap are packed by xatlas with configured padding/resolution and report pack dimensions, utilization, and padding status.
• Box UV generation is reported as AABB projection. --uv-aabb-scope, --uv3d-size, and --uv-preserve-existing record local/shared bounds, real-world UV scale, destination channel, override policy, and unit metadata.
• --uv-sharp-to-seam and --uv-forbid-overlapping are recorded as Unity-style UV policy intent for unwrap/lightmap channels. The current xatlas backend does not expose those controls directly, so reports include per-channel requested/enforced fields and post-generation overlap validation.
• --remove-holes uses mesh boundary classification and filling when BREP hole removal is unavailable. --hole-types filters inferred through, blind, and surface boundary loops; closed BREP feature holes still require a BREP feature backend.
• --remove-occluded uses deterministic sampled visibility. Strategy changes the direction set, --hemi-evaluation restricts rays to upper-hemisphere and side views, and --occlusion-level controls whether fully hidden parts, material groups, or triangles are removed. Output metadata records sample coverage, direction coverage, and an occlusion confidence score.
• --draco runs the Draco encoder for glTF/GLB mesh payloads.
• --texture-fallback-format auto records PNG fallback for alpha-bearing texture sets and JPEG fallback for color-only texture sets when KTX2/Basis output is not requested. Explicit jpeg fallback reports a warning when referenced texture metadata indicates transparency would be discarded.

Inspect flags

Supported filter 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"]
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.

Validate flags

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/ \
  --runtime-browser \
  --report report.json

File arguments

Use - for standard streams:

cat input.step | fascat inspect -
cat input.step | fascat convert - - --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 -, USD bytes are reserved for stdout and 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.

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

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