Quincaillerie

Every instance is different

quincaillerie generate screw M10 --with nut,washer --count 10 and the same for AA and 9 V cells: each part is a distinct file. Rust, grime, oil and scratches; scuffed and faded labels; a dished washer, oval and crushed nuts, crushed and bent screws (not all visible from here); and, invisible in a picture, a different thread fit, alloy density, friction and spring for each.

Each aspect has its own random stream: --no-vary wear keeps the same tolerances and defects with clean parts; the same seed gives the same parts. Everything drawn is in instances.csv and in each file as primvaria:variation:* attributes; the clean finishes stay available in the finish variant set of a worn part. --nominal gives the reference part.

The defects are physical. The same nut, the same light torque (a hand on a nut driver), simulated in MuJoCo from the files: it runs down the sound screw (left) and stops at the crushed thread of the other (right). quincaillerie sim-test --defects checks this for every crushed screw of a batch.

Only crushed threads jam a nut: one screw in three with a defect, so the jam rate is a third of --defect-rate (5 % at the default 15 %). Measured on 40 screws: Defect rate and jam rate.

The physics, in motion

All three are rendered in Blender (Cycles) from the generated OpenUSD files: scripts/physics_gifs.py.

What it does

• Fasteners, metric coarse thread, M3 to M12: hex head screws (ISO 4017, fully threaded, any length), hex nuts (ISO 4032), plain washers (ISO 7089). The visual mesh carries the ISO 68-1 thread profile; the collision is a core cylinder plus one convex piece per 10° of helix (≈ 800 per screw, 200 per nut) with 0.05 mm of radial clearance, so a nut really screws on. Six finishes as a variant set: clear and yellow zinc, black oxide, stainless A2, plain steel, brass.
• Cells and holders: AAA, AA, C, D, CR123A, 18650, 21700 in cradles with a coil spring; the 9 V block in a holder whose terminal slots are keyed; CR2032 and LR44 under a hinged leaf-spring clip. The spring stiffness and wire come from the contact force and preload (k = G d⁴ / 8 D³ n); the clip torsion from the force at its lever arm.
• Variation: --count N distinct instances of each part, with drawn tolerances, defects, wear and physics (see above), and their ground truth.
• Related elements on request (--with): a screw with its nut and washer, a cell with its holder, and a scene with every instance resting on a floor, plus the assemblies (made of instances without defects).
• OpenUSD: one file per part, one rigid body per moving part with one visual mesh (so every DCC imports one object per body), mass, centre of mass and principal inertia, convex collision shapes, physics materials, joints with drives, mate frames (thread axis, drive, terminals, cell seat). The files hold nothing specific to an engine: what only PhysX reads (Isaac Sim) is a layer over each file, <file>_physx.usda. A shared material library in UsdPreviewSurface and MaterialX.
• Checks (quincaillerie sim-test, quincaillerie blender-test): the same scenes, read back from the files, in MuJoCo and in Blender.
• A Blender add-on (quincaillerie blender-addon): rigid bodies and constraints set up on every USD import.
• --no-physics for visual-only assets.

Engines

Every file is OpenUSD with standard UsdPhysics schemas. Where each engine stands, as on the Primvaria engine matrix:

Installation

From PyPI:

pip install "quincaillerie[sim]"

From a clone, for development:

python -m venv .venv && source .venv/bin/activate
pip install -e ".[sim]"            # add ",dev" for tests and linting, ",materialx" for the .mtlx file

Requires Python 3.11+. Dependencies: NumPy, SciPy, Pillow and the OpenUSD bindings (usd-core 26.5+); MuJoCo for the checks. The Blender checks need Blender as a Python module (pip install bpy, Python 3.13) or a Blender executable.

Earlier usd-core wheels generate the same files, but their OpenUSD validators do not load (25.5 ships without the validator libraries, 25.8 and 25.11 without the UsdPreviewSurface definitions), and CI tests both 26.5 and the newest release.

Usage

quincaillerie list                                          # sizes, formats, finishes
quincaillerie generate screw M8 --length 30 --with nut,washer --count 100
quincaillerie generate cell 18650 --with holder --count 20 --defect-rate 0.3
quincaillerie generate screw M8 --count 50 --no-vary wear   # clean parts, varied fits and defects
quincaillerie generate nut M10 --nominal                    # the reference part
quincaillerie generate holder 9V --with cell --no-physics   # visuals only
quincaillerie generate all --nominal                        # the whole catalogue (41 assets)
quincaillerie sim-test output/ISO4017_M8x30 --defects       # MuJoCo checks (+ crushed threads jam)
quincaillerie blender-test output/catalog                   # the same in Blender
quincaillerie blender-addon                                 # quincaillerie_physics.zip

python -m quincaillerie ... works too. From Python:

from quincaillerie import generate, resolve

parts = resolve("screw", "M6", length=25, with_=["nut", "washer"])
generate(parts, "output", count=100, defect_rate=0.2)  # -> output/ISO4017_M6x25/
generate(parts, "output", vary=("tolerance", "physics"))  # clean, undamaged, varied fits

Four short scripts in examples/ show the rest, each explained by its own comments: a first pack and its ground truth, one aspect switched off, reading the files with OpenUSD alone, and a nut screwed on in MuJoCo.

Outputs (under output/<set>/)

Limits

The short version; the full list is in Limits and roadmap.

• Dimensions are nominal, from public tables; variation ranges are plausible orders of magnitude, not measured distributions.
• A thread is about 1000 convex pieces: exact enough to screw, heavy for large scenes. --collider simple is light, but then nothing screws or jams.
• Holders are generic designs, with no electrical contact model.
• Checked in MuJoCo and Blender; not tested in Isaac Sim yet.

Development

git clone https://github.com/drscaon/quincaillerie.git && cd quincaillerie
pip install -e ".[dev]"
pytest

Conventions and continuous integration: Development.

Documentation

License

MIT © 2026 Daniel Régis Sarmento Caon

The logo is drawn from DejaVu Sans Bold outlines (Bitstream Vera license), converted to paths, so it displays without the font installed.

---

Quincaillerie is part of Primvaria, physics-ready variability for Physical AI, in OpenUSD: pip install primvaria installs the whole suite (source).