OpenUSD contract

Version 0 (draft). This document says what every file written by a Primvaria generator has in common, so that an asset from one generator composes with an asset from any other and behaves the same in every engine.

Each rule is marked:

• in place: all four generators already do it, and their tests check it;
• v0: new with this version, to be implemented in the four generators and enforced by the shared conformance test (tests/test_contract.py);
• planned: named here so the direction is fixed, specified in a later version.

A change to the file format changes this document first, in a pull request to this repository. See MISSION.md.

1. Terms

2. Stage

3. Shared ground and physics scene

In place in all four generators, written and checked by ground.py (the same file in each repository).

An asset rests on z = 0. A standalone asset file (Quincaillerie's assets/*.usdc) carries no ground: its underside is at z = 0 of the asset.

4. Model hierarchy and asset identity

v0. Every asset root is a model, so that tools can find, list and instance assets without knowing the generator.

Asset roots by generator:

Every asset root also carries assetInfo:

5. Ground truth: the primvaria: namespace

v0. Every asset root carries these attributes, with the same names and types in every generator, and no other prim carries a primvaria:* attribute:

Generator-specific attributes keep their own namespace (granulaire:*, maillage:*, filaire:*, quincaillerie:*) and never repeat the attributes above or the drawn values of section 6: a generator's own preset, seed, version or variation metadata is not written.

primvaria:variation:* holds what was drawn for the asset (section 6).

primvaria:measured:<name> holds what was measured on the asset once generated, with the value types and the naming of the drawn values (snake_case, the unit as a suffix):

Semantic labels

Every asset root also says what it is with OpenUSD's own semantic labels, the multiple-apply schema UsdSemantics.LabelsAPI, which renderers turn into segmentation masks. They are not in the primvaria: namespace: any tool that knows OpenUSD reads them.

An asset that references another (a Granulaire grain and its prototype, a part placed in a Quincaillerie scene) takes its classes from it and states its own instance label. Labels are inherited down the hierarchy, so every mesh of an asset carries them.

6. Variation model

v0. The reference implementation is Quincaillerie's variation.py; the four generators follow the same rules.

Aspects. A generator varies its assets along a fixed list of aspects, each of which can be switched off:

Rules.

1. Reproducible. The same generator version, preset, seed and options give the same assets.
2. Independent aspects. Switching an aspect off leaves every value drawn for the other aspects unchanged, so two runs with the same seed differ by that aspect alone. A generator gets there with one random stream per aspect, or by always drawing and then overriding.
3. Nominal when off. An aspect that is switched off takes its nominal value (the middle of its range, the first of its list), and that value is still recorded.
4. Recorded. Every drawn value is written on the asset root and in the pack's table, under the same name.

Recording.

Names are lowercase snake_case with the unit as a suffix when the value has one (diameter_m, clearance_mm, cut_skew_deg, youngs_modulus_pa). The pack's table has the same values in columns named variation:<name>. In Granulaire the values are written on the prototype and inherited by the grains; a grain adds its own drawn moisture state.

Each generator tests rules 1 to 3; the conformance check requires primvaria:variation:aspects on every asset root and checks the names.

7. Variant sets

In place, with the names used today:

v0 rules for any new variant set:

• names are lowercase snake_case;
• a name means the same thing in every generator: finish is always a surface state, moisture always a water content;
• a default selection is always authored;
• a variant never changes the asset's identity (section 5), only its state.

Planned: state for Maillage (flat, draped, crumpled, folded).

8. MateFrame

In place in Filaire and Quincaillerie: anything that connects (plug and socket, screw and nut, cell and holder) carries an Xform named MateFrame, or MateFrame_<feature> when a part has several (MateFrame_thread, MateFrame_drive).

• Its origin is on the mating plane.
• +Z is the insertion or screwing direction.
• Two parts mate when their MateFrames coincide, within the clearance.

The attributes that describe the mate (role, gender, insertion depth, clearance, keying) are generator-specific today (filaire:role, filaire:insertionDepth, …). Planned: common primvaria:mate:* attributes.

9. Engines

Every file is plain OpenUSD: UsdGeom, UsdShade with UsdPreviewSurface, and the standard UsdPhysics schemas. It is what the OpenUSD validators, Blender and the MuJoCo checks read, and it is complete on its own.

What only one engine reads is not in the file. It is an engine layer beside it:

• named <file stem>_<engine>.usda (or .usdc when it holds large meshes);
• its only sublayer is the file, so opening the layer gives the file plus the engine's data, and the file alone never depends on it;
• it adds opinions to what the file defines. It defines prims of its own only where the engine needs geometry the file does not have (a simulation mesh, an engine material);
• an opinion on something that exists in one variant only is written inside that variant.

MaterialX is not an engine layer: Quincaillerie's material library offers it beside UsdPreviewSurface, in the same file.

v0 rules:

• a file holds no schema or attribute of an engine (Physx*, OmniPhysics*, physx*:, omniphysics:);
• a file is valid and passes its generator's checks without its layers;
• a generator says in its own namespace what an engine must know and cannot guess (for example quincaillerie:contactOffset, the distance from which a threaded part needs contacts), and the engine layer copies it.

Each generator checks the structure of its layers (python -m <generator>.physx, python -m <generator>.omniphysics). No layer has been simulated: both engines need Isaac Sim and an NVIDIA RTX GPU.

10. Pack files

v0. Every pack has the same two files, written by the same module (pack.py) in the four generators.

instances.csv has one row per asset, read back from the OpenUSD files, so the table and the files cannot disagree. An asset is listed from the file that defines it; a scene or a layer that only references it does not list it again. Columns, in this order:

Lists are separated by spaces, booleans are true and false, and a cell is empty where an asset has no such value.

manifest.json says what the pack is: contract, generator, version, pack (the preset or the set), seed, aspects, assets (the number of rows), classes (the semantic classes of its assets, sorted), table, files (the pack's OpenUSD files) and summary, the generator's own statistics.

A generator may write other files beside them (Granulaire's prototype_metrics.csv, textures, previews, engine exports).

11. Conformance

12. Versioning

The contract has one integer version, written in primvaria:contract. A file states the version it follows; a generator release states it in its changelog. Adding an attribute or a variant set is a minor change recorded here; renaming or removing one raises the version.