cadmpeg

cadmpeg inspects native CAD containers, decodes supported model data into CADIR, validates and compares CADIR models, and exports CADIR or STEP Part 21 (AP203, AP214, or AP242). It also writes supported .FCStd, .f3d, .sldprt, and .3dm models.

Native codecs transfer different subsets of geometry, topology, design intent, presentation, and metadata. Check format support before relying on a conversion path.

Install

Install with Homebrew:

brew install cadmpeg/tap/cadmpeg

Or use the installer for macOS and Linux:

curl --proto '=https' --tlsv1.2 -LsSf \
  https://github.com/cadmpeg/cadmpeg/releases/latest/download/cadmpeg-installer.sh | sh

Or install from crates.io:

cargo install cadmpeg

Convert a model

convert decodes the input, validates the resulting CADIR, then exports it:

cadmpeg convert bracket.f3d -o bracket.step
cadmpeg convert bracket.f3d -o bracket.ap242.step --step-target ap242e3
cadmpeg convert bracket.f3d -o bracket.step --reject-step-losses

--step-target selects the STEP application protocol and edition (ap203e1, ap203e2, ap214 default, ap242e1, ap242e2, ap242e3). --reject-step-losses refuses STEP output before writing when any STEP loss note would be reported.

The output extension selects step, fcstd, f3d, sldprt, rhino, or cadir. Pass --format when writing to standard output or when the filename does not identify the format:

cadmpeg convert bracket.f3d --format step > bracket.step

Conversion stops before export if validation finds errors. It also refuses geometry output when decoding transfers no geometry. --allow-invalid and --allow-empty write the current result anyway. They leave model data unchanged.

Inspect, decode, and validate

Inspect a native container without decoding its model:

cadmpeg inspect bracket.f3d
cadmpeg inspect bracket.f3d --json

Decode a native file to canonical CADIR JSON:

cadmpeg decode bracket.f3d -o bracket.cadir.json

Without --output, artifact-producing commands write only the artifact to standard output. Diagnostics and loss summaries go to standard error, so redirection remains safe.

Validate either CADIR or a supported native file:

cadmpeg validate bracket.cadir.json
cadmpeg validate bracket.f3d --json

Use export to skip CADIR validation:

cadmpeg export bracket.cadir.json -o bracket.step

--container-only stops native decoding before geometry. It is useful for container diagnostics and normally requires --allow-empty when followed by a geometry export.

Read raw bytes

cadmpeg inspect also carries byte tools that work on any file, decoded or not. Every offset and length argument accepts 0x hexadecimal or decimal, and _ between digits.

cadmpeg inspect hex part.prt --offset 0x40 --len 0x80   # dump with an ASCII gutter
cadmpeg inspect read part.prt --type u32 --offset 0x40  # one scalar, decimal and hex
cadmpeg inspect read part.prt --type f64 --offset 0x100 --count 8 --stride 24
cadmpeg inspect find part.prt --hex '4d5a??00'          # `??` is a byte wildcard
cadmpeg inspect find part.prt --utf16le Extrude
cadmpeg inspect strings part.prt --min 6 --encoding both
cadmpeg inspect struct part.prt --offset 0x100 --count 4 \
  --layout 'u32le:id,pad4,f64le:x,f64le:y,f64le:z'
cadmpeg inspect container part.f3d                      # ZIP entries with byte offsets
cadmpeg inspect diff probe-a.prt probe-b.prt            # positional byte diff

--le and --be select the byte order for read; little-endian is the default. read --count N walks a record array, stepping --stride bytes and defaulting to the scalar width.

Common alternative spellings are accepted: --length for --len, --min-len and --min-length for --min, --start for --offset, and -n for --count. cadmpeg inspect bytes <tool> runs the same tool as cadmpeg inspect <tool>. find needs its pattern on --hex, --ascii, or --utf16le, because a bare word does not say how to encode it; the tool stops at --max hits and says so, and --max 0 reports every hit.

--layout is a comma-separated record spec with no implicit alignment:

Every field except padN accepts an optional :name; unnamed fields are called f<index>. struct --count N decodes N consecutive records and reports an error rather than a partial record when the run passes end of file.

inspect container lists ZIP entries with their local-header and payload offsets, so a hex dump of an entry follows directly. Names are single-quoted because Fusion .f3d entry names hold [ and ], which a shell reads as a glob. Other container families are listed by cadmpeg inspect FILE through their codec.

inspect diff compares byte n of one file with byte n of the other. It reports the first differing offset, the differing byte count, and the differing spans. --gap merges two spans separated by that many equal bytes or fewer. cadmpeg diff compares decoded models.

A file whose name is also a subcommand name, such as hex, is read as the subcommand. Write ./hex for such a file.

Compare models

diff compares two decoded models structurally:

cadmpeg diff before.cadir.json after.cadir.json
cadmpeg diff before.f3d after.f3d --json

It reports unit, tolerance, arena membership, and modified entity fields. Exit status 1 indicates a difference.

Inputs and outputs

The built-in codecs recognize .f3d, .FCStd, .sldprt, .3dm, .CATPart, IGES, STEP, and the NX and Creo .prt layouts by content. Commands that load models also accept CADIR JSON. Use --input-format to bypass detection for an ambiguous or extensionless input.

Output formats are:

• cadir for canonical CADIR JSON; json is an alias.
• step for ISO 10303-21 Part 21; --step-target selects AP203 edition 1 or 2, AP214, or AP242 edition 1, 2, or 3.
• fcstd, f3d, rhino, and sldprt for the native writers' supported subsets.

Native writers use retained source data where the format requires it, and reject unsupported edits. The format support page defines each reader and writer's current semantic coverage.

File output is atomic. cadmpeg refuses to replace its input or an existing output unless --force is present. An explicit --format takes precedence over a conflicting output extension and emits a warning.

Losses and machine-readable reports

Native decoding prints whether geometry transferred and lists known losses. STEP export reports omitted, reduced, or normalized content. To save a versioned JSON record of a decode, export, or convert operation, pass --report:

cadmpeg convert bracket.f3d -o bracket.step \
  --report bracket.conversion.json

The command report contains decode, validation, and export sections when those stages ran. inspect --json, validate --json, and diff --json write versioned JSON directly to standard output.

inspect, validate, and diff produce no artifact beside the report, so they also accept -o and --output for the report path. Every command refuses to replace an existing report or artifact unless --force is present. Validation findings live under .validation_report.findings; the printed error count and exit status 1 count the same error and blocking findings.

Exit status

• 0: the requested operation completed; validation passed and diffs were empty when those checks ran.
• 1: semantic result, such as validation errors, a non-empty diff, or refusal to export invalid or empty geometry.
• 2: operational error, including invalid arguments, unrecognized input, decode or encode failure, and file-system errors.

Run cadmpeg help <command> for the complete options of a command.

More documentation

• Format support
• Architecture
• Contributing
• Clean-room and legal policy
• Repository

Requires Rust 1.88 or later. Licensed under Apache-2.0.