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. It reads the geometry
a file states — placements, axes, radii, unit factors — and never computes
what the file does not: 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.6, 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 reads what a file states — units, geometry, placements, a solid's topology, a definition's solids and the faces PMI applies to — in millimetres and radians, and refuses what it cannot read with certainty. 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
Compute geometry. stepq reads what a file states — a point, an axis, a
radius, a placement, a unit factor — and applying a stated unit factor or
composing stated placements counts as reading. It never computes what the
file does not state: no intersections, no trimmed areas, no tessellation, no
mass properties, no bounding boxes, 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.
Learning STEP
stepq assumes you know what a product_definition is, why a shape
representation points at its product, and what a
next_assembly_usage_occurrence does. If you don't, or are rusty, read
the companion book Inside the STEP File,
an open-source reader's guide to ISO 10303. It walks through the format
one record at a time — the product chain, contexts and units,
assemblies, boundary representation, colours, properties and PMI — using
real files exported from Open CASCADE, and every entity name and
attribute claim in it is checked against the published EXPRESS schemas.
It is the conceptual foundation this project's documentation builds on:
the architecture notes and the
command reference use its vocabulary without
re-explaining it.
The book is available as a website and as a
PDF;
its source and the twelve example files behind its listings are in the
step-book repository. Those
files are small enough to explore with stepq info, tree and refs
as you read.
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.6", = 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.