stepq
Query, inspect, split and reshape STEP (ISO 10303-21) files — a Rust library and a command-line tool.
stepq works on the entity graph of a STEP file, not on its geometry.
It never tessellates, never computes a volume, never "heals" anything.
That constraint is the point: every entity that describes your geometry
comes out exactly as it went in, byte for byte, with its original names,
colours, layers, properties and PMI attached.
Status: 0.4, early. The Part 21 parser, reference graph, writer and EXPRESS schema reader are in place, and
stepq info,tree,bom,split(with--bodiesand--master),assemble,lint,refs,query,props,diff,stripandpmiwork. The library API and the CLI output will still change before 1.0; see ROADMAP.md.
What it does
$ stepq info assembly.stp # header, schema, units, entity histogram
$ stepq tree assembly.stp --usages # assembly hierarchy and placements
$ stepq bom assembly.stp # multi-level bill of materials as a tree
$ stepq bom assembly.stp --format csv # the same as an indented CSV
$ stepq split assembly.stp --out parts/ # one file per sub-assembly and part (--bodies: per solid)
$ stepq split assembly.stp --master --out parts/ # assemblies refer to component files (CAx-IF)
$ stepq assemble parts/assembly.stp -o whole.stp # merge a master and its files into one
$ stepq lint assembly.stp --schema schemas/ # structural problems; exit 1 on errors
$ stepq refs assembly.stp 1234 --depth 2 # what #1234 refers to, and what refers to it
$ stepq query assembly.stp --type product # instances by entity type or text
$ stepq props assembly.stp --kind user # user-defined attributes, validation properties, IDs
$ stepq diff old.stp new.stp # what changed: products, quantities, properties
$ stepq strip assembly.stp --anonymize -o shareable.stp # remove names before sharing a file
$ stepq pmi part.stp --format json # semantic GD&T: tolerances, datums, dimensions
Every command reads - as standard input and prints a table, JSON
(--format json) or CSV (--format csv).
Commands: docs/COMMANDS.md documents every command and option, with real example output and the library function behind each.
$ stepq bom assembly.stp
ASSEMBLY
├── PLATE
├── L-BRACKET ASSEMBLY ×2
│ ├── L-BRACKET (2 total)
│ └── NUT-BOLT ASSEMBLY ×3 (6 total)
│ ├── BOLT (6 total)
│ └── NUT (6 total)
└── ROD-ASSEMBLY
├── ROD
└── NUT ×2
3 sub-assemblies, 5 distinct parts, 18 parts in total
The headline feature is split: explode an assembly into self-contained
STEP files for every sub-assembly and part, preserving nested structure,
instance placement, colours and names — without a CAD seat and without
regenerating a single surface. As far as we can tell nothing open-source
does this today; the usual answer is "open it in SolidWorks and Save As".
Its inverse, assemble, merges a master file and the component files it
refers to back into one file. See ROADMAP.md for what comes
next.
What it will not do
Anything geometric. No tessellation, no mass properties, no bounding boxes,
no unit conversion, no shape healing, no format conversion. If you need
those, you need a geometry kernel; Open CASCADE
is the open-source one. stepq is designed to sit next to a kernel, not
replace it.
Install
Prebuilt binaries for macOS, Linux and Windows are attached to every
GitHub release. The
installers put stepq in ~/.cargo/bin without needing Rust.
macOS and Linux:
$ curl --proto '=https' --tlsv1.2 -LsSf https://github.com/jchultarsky/stepq/releases/latest/download/stepq-installer.sh | sh
Homebrew (macOS and Linux, from 0.3.0):
$ brew install jchultarsky/tap/stepq
Windows (PowerShell):
> powershell -ExecutionPolicy Bypass -c "irm https://github.com/jchultarsky/stepq/releases/latest/download/stepq-installer.ps1 | iex"
The installers also install stepq-update, which upgrades to the latest
release. With a Rust toolchain (1.85 or newer) instead:
$ cargo install stepq # or: cargo binstall stepq
As a library, without the CLI dependencies:
[]
= { = "0.4", = false }
Supported input
ISO 10303-21 editions 1 and 2 (implementation_level '2;1'), which is what
every mainstream CAD system writes. Application protocols AP203, AP214 and
AP242 (all editions). Part 21 edition 3 files are read too: multiple data
sections, anchors and external references (a name another file defines is
not a dangling reference), all kept when a file is rewritten. Scope
structures (&SCOPE) are rejected.
Design
Read docs/ARCHITECTURE.md before contributing. The short version:
- Back-references first. In STEP, a product's shape, colours, PMI and
placement all point at the product. A forward closure from a
product_definitionreaches six entities and no geometry. - Untyped entities, schema-checked. AP242 has ~2,400 entity types; real files use ~230. We keep instances as name + attribute tokens and validate attribute counts against the EXPRESS schema rather than generating a struct per type.
- Verbatim output. Unchanged entities are written back from their
original text. Only
#ids are renumbered. - Silent failure is the enemy. A dropped reverse reference produces a
file every tool reads happily with zero solids and no warning. The test
oracle is therefore geometric: every output is read back through Open
CASCADE and checked against volume and solid-count invariants of the
input (
tools/verify-occt.py). CI uses it on the core sample files to check that rewriting through stepq changes no geometry, and thatsplitoutputs reproduce the input (tools/verify-split.py).
Contributing
Issues and pull requests are welcome. Read CONTRIBUTING.md for how the project is organised, how to get the test fixtures, and what CI checks. Everyone taking part is expected to follow the Code of Conduct.
Found a crash or hang on a crafted file? Please report it privately — see SECURITY.md.
License
stepq is released under the MIT License.
Unless you explicitly state otherwise, any contribution you intentionally submit for inclusion in this project is licensed under the MIT License, without any additional terms or conditions.