simready-forge 0.1.0__tar.gz → 0.2.0__tar.gz

simready_forge-0.2.0/CHANGELOG.md

@@ -0,0 +1,274 @@
+# Changelog
+
+What changed for people who use simready-forge, newest first. A change users notice adds its line under Unreleased in
+the same PR; the release PR renames Unreleased to `## X.Y.Z (YYYY-MM-DD)`, which the gate's version check reads. The
+format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+
+## 0.2.0 (2026-11-05)
+
+### Added
+
+- **A mode option may hold nothing,** for an asset a scene takes away by its own variant: `placed: [on, off]` with
+  every body `only={"placed": "on"}`. `placed=off` holds no body, mesh, joint or articulation root; `validate`
+  records NVIDIA's RB.001 and VG.MESH.001 as expected there and passes it on everything else; the review, the switch
+  pass and the scene prop take it as any option. A default option that holds nothing is refused.
+- **An option that holds nothing beside other mode sets:** `placed: [on, off]` beside `lid` and `condition`, a body
+  or part naming one more set (`only={"placed": "on", "lid": "on"}`). The asset is written whole inside `placed=on`,
+  and `validate`, the review and the switch pass take `placed=off` once, so the valve crate is checked in every
+  combination.
+- **The report's variants table, switch line and FET_007 line come from the files:** `review.json`'s
+  `variants_table` and `switches.line` and `validate.json`'s `fet_007_line`, which `make`'s report copies whole, as it
+  copies the cost line.
+- **The report's materials table and Library line come from the files too:** `structure.json`'s `materials_table`
+  and, with a library, `library_line`, copied whole by `make`'s report.
+- **`review.showcase()` takes `titles` and `words`** for a script's own captions: an asset's title, and a slice's
+  second line. A tall frame's caption and framing fit its width.
+
+- **Variants in the kit:** one asset switches between looks (colours, tints, finishes), modes (parts and bodies only
+  some options have, a door that starts open) and detail levels (high and low poly, a generated mesh at two
+  densities), as USD variant sets on its default prim. NVIDIA's validator, `inspect`, `poses` and the Isaac Sim
+  review check every option, and each option gets its own URDF and GLB (a start pose its GLB alone: URDF has
+  none). An asset without variants is unchanged.
+- **`simready-forge trellis image --faces N`** writes each candidate at another face count too, the same shape with
+  its own texture atlas.
+- **Variants in `/simready-forge:make`:** name them in the request ("in green, red or blue", "with the door open or
+  closed", "a high and a low poly version") and they go into the one asset; the critics judge every option, and the
+  report shows them side by side. `/simready-forge:review` checks every option of an asset with variant sets.
+- **`simready-forge showcase`** renders a turntable of one or more assets in Isaac Sim, each variant option in turn
+  seen from the front, as a WebP and, with `ffmpeg`, an MP4.
+- **`simready-forge trellis setup`** installs the local mesh generator on Windows or Linux with an NVIDIA GPU:
+  ComfyUI v0.43.2 with its own Python and PyTorch for CUDA 13.0, and the eight model files the kit's graphs load
+  (29.6 GB, resumable), each pinned to its Hugging Face commit and checked by its SHA-256. It says what it will
+  download, where, and under which licences before it starts. A ComfyUI you already have only gets the models;
+  `--start` starts it, and **`trellis stop`** ends it. **`trellis check`** says what a server lacks, the folder it
+  reads models from, and what to do. **`trellis setup --models DIR FILE ...`** adds just the named model files to the
+  folder a ComfyUI you run reads them from (Comfy Desktop's shared folder too), checked the same way.
+- **`/simready-forge:make` offers that setup** when a request would take a generated mesh (a photo, or an organic
+  shape such as a shoe) and TRELLIS.2 isn't ready: set it up or start it now, set it up for next time, build in CAD,
+  or don't ask again (`trellis_offer=never`). A ComfyUI you already run here that lacks only models is offered just
+  those files, in the folder it reads them from. On a Mac, or with no NVIDIA GPU, it builds in CAD and names the way
+  that still works: a ComfyUI on a machine that has one, set by `comfyui_url` or `COMFYUI_URL`.
+- **Labels per option:** `asset.label("caps", "off", on=["end_a", "end_b"])` gives a synthetic image of that
+  option its finding, `caps_off`: a semantic label that exists only while the option is selected, on the parts or
+  bodies that show it, and on the asset's root as `finding_asset`, which is all an instanced copy's image shows,
+  wherever the labelled part is there. The kit names every finding `<set>_<option>` (`rust_light`,
+  `cap_on_ground_on`), so findings from many assets read alike in one dataset; `finding=` is refused, and another
+  instance is a keyword of its own (`wear="worn"`). So `finding` masks the labelled part alone (the rust, the open end) and
+  `finding_asset` the whole copy. `on=asset` labels a state no one part shows, on the root alone; a part the option
+  removes is refused, with what to label instead.
+- **The selection check:** `validate` compares every selection it checks with what the build script declared in
+  `structure.json` (each part there or not, its triangles, its labels, its material and look, the colliders the same
+  in every detail option), so a part that never goes, a level that never applies, a label that never shows or a
+  material never bound fails at once, with no renderer. An asset the kit didn't build is checked without the
+  script's half, and its report says so.
+- **Live switches:** `simready-forge review --switches` switches every option while Isaac Sim runs and records how
+  many frames each switch takes to reach the renderer; a layout fault fails it, an Isaac Sim fault is recorded with
+  the workaround under which every switch showed. `make` runs it once on the final asset in every mode, `review`
+  after its review.
+- **`simready-forge bench`** measures what each detail level costs a field of instanced copies of an asset, fresh
+  and switched live: load time, GPU memory, frame time, how fast a switch shows.
+- **Scene props:** `scene` added to the formats (`formats=usd,urdf,glb,scene` in `/simready-forge:make`, or
+  `formats=usd,scene` for the USD and the scene prop alone; `save(formats=(..., "scene"))` in the kit) also writes
+  `<name>_exports/scene/<name>.usdc`: the validated and reviewed asset without its rigid bodies, mass,
+  articulation root or joints in any option, its geometry, materials, variant sets, colliders and pose options
+  kept, for a scene that places it thousands of times. `validate` on the asset checks it against the asset spec by
+  spec and writes `<name>.proof.json` beside it, which a scene's publish step reads (`docs/USAGE.md`). `inspect`
+  lists colliders that sit in no rigid body.
+- **Material libraries in the kit:** `lib = asset.library("materials.usda")` and `asset.add(body, "tube", shape,
+  lib["steel_galvanised"])` bind a shared library's material by name. The package references each one it binds, in a
+  copy of those materials under `<name>/usd/materials/`, and writes none of their values; mass comes from the
+  library's density, and the GLB carries its colour, its numbers and an opacity map. An asset without a library is
+  unchanged.
+- **Looks that rebind:** `asset.look(steel, "rust", "light", rebind=lib["steel_rust_light"])` binds a part to
+  another library material in one option, in every detail level and mode option, and two sets may rebind one part
+  (the one declared first wins where it rebinds it). `validate` checks the binding each selection shows, and that
+  every library material is still in the package's copy. `review --switches` checks each rebind reaches the
+  material binding Isaac Sim's Fabric holds, and records one that never does as an Isaac Sim fault.
+- **Generated meshes under a library:** `asset.scan_material(scan, "paint", like="steel_paint_yellow")` keeps a
+  TRELLIS.2 mesh's baked atlas and takes its friction, density, sensor tokens and label from the library material,
+  through a reference to it; each detail level's atlas lands on it. A scan region bound to a library material gets
+  UVs in metres, and `structure.json` names the asset's own materials and the parts that bind them.
+- **Scene props with a library:** with `asset.library(path, live="../../../materials/materials.usda")`, the scene
+  prop references the scene's own library at that path and carries none; without `live` it carries the package's
+  copy. Its proof names each material and the sha256 of the library the build read. `review` of it, its switch pass
+  and `bench` render it with the package's copy where the kit wrote it, and as it is where a scene placed it, the
+  scene's library giving its materials.
+- **Looks on a generated mesh:** `asset.overlay("skin", "state", "rust_light", lib["steel_rust_light"], where=rust,
+  at=0.58)` lays a library material over part of a mesh where a field says, as a shell defined only in that option
+  at every detail level, with the finding label on the shell itself; `asset.look(paint, "state", "wet",
+  blend=lib["wet_film"], amount=0.55)` blends a `like=` atlas towards a library material all over. The atlas stays
+  under both. The field is read on a grid of the shell's own, a plane every half the part's middle extent (coarser at
+  each lower detail level), so a straight CAD tube, whose cut has points at its ends alone, shows a patch along it
+  with no rings in its own mesh: a 12 m DN100 pipe ringed for its rust had 55,684 triangles at full, and built plain
+  it has 3,268.
+- **Material libraries in `/simready-forge:make`:** `library=<materials.usda>` in the request binds the asset's
+  materials from that library by name, the spec taking their values from it; rust, wet and grade states rebind to
+  another library material, or on a generated mesh lay one over it or blend towards it. With `scene` in the formats,
+  `library_live=<path>` makes the scene prop reference the scene's own library at that path. `make` checks the
+  library once and reuses its record until the library or the kit changes; a library that fails the check stops it
+  before the spec, with the check's message, and on an older kit it says so and builds with the asset's own
+  materials. The report gives each material's source, and `/simready-forge:review` checks an asset with a library
+  with its copy, and a scene prop delivered live where the scene placed it with the scene's library.
+- **`simready-forge library <materials.usda>`** checks a material library against the kit's rules (`docs/USAGE.md`,
+  Material libraries) and validates a swatch of its materials with NVIDIA's validator; `--out DIR` keeps the record
+  as `materials.json`, reused while the library and the kit stay the same. `inspect` gives a texture read through a
+  `UsdTransform2d` its `st_scale`.
+- **`simready-forge library --from <materials.yaml>`** writes a material library from a YAML list (each material's
+  colour, roughness, metallic, physics values and sensor tokens), with texture sets from ambientCG or Poly Haven
+  found in a folder you name (`--textures DIR`; the kit downloads nothing), each colour and roughness map scaled so
+  its mean is the YAML's value, each tiled at its own size in metres, or without textures (`--flat`). It checks the
+  library before it replaces the last good one, and refuses a YAML or a missing set naming every problem at once.
+  `make library=<materials.yaml>` writes it before the build and binds from it, with `library_textures=<dir>` for
+  the sets.
+- **Families:** one build script whose sizes are named parameters writes a package per size (`family()`,
+  `sizes.json`, `family.json`), each validated in every selection and bound to a material library by name;
+  `validate <family folder>` checks every size and the family, `cost --family` gives a line per size, and `make`
+  builds a family when a request names several sizes, reviewing the smallest and the largest. The worked example is
+  a pipe in three sizes: `simready-forge example --show pipe`.
+- **Sub-assets:** `asset.sub_asset(path, name, at=, turn=, only=)` puts another SimReady package inside an asset (a
+  drive in a tray, two trays in a cage), copied byte for byte into `usd/assets/<package>/` and referenced once by a
+  class prim each instance inherits, so no option switch opens a file. `asset.fixed()` mounts it where it is, or a
+  revolute or prismatic joint moves it; its mass counts, its detail set follows the asset's, its meshes reach the
+  URDF and the GLB, and `validate` passes it in every selection and says which copies are older than their source.
+  `/simready-forge:make uses=<path>` (or a request naming an existing asset) builds with that package instead of
+  modelling it again.
+- **`simready-forge batch <catalogue.yaml>`** makes every entry of a catalogue with no one at the keyboard: one
+  headless `make` each, in a folder of its own, up to `--jobs` at once, with no entry started once the bill reaches
+  `--cap`. A rerun skips each entry made and validated and makes again, from an empty folder, one that failed or was
+  cut short. Each entry is checked from its files and audited by a session that only reads; the batch writes one
+  report, one contact sheet (every package, every option, its triangles) and one bill. The catalogue is the kit's own
+  schema (`docs/USAGE.md`, Making a batch from a catalogue), and `/simready-forge:make` checks one and gives the
+  command. `--audit <name>` audits an entry again on its `report.md` as corrected since, keeping the earlier audit
+  and its cost in the bill.
+
+### Changed
+
+- **`validate` compares each mesh's material by its path under the root,** so a sub-asset's `steel` is never taken
+  for the asset's own. An asset without sub-assets gets the same result.
+- **`review.json`, `poses.json` and the probe key a joint or a body by its path under the root, less a `Joints`
+  scope:** two trays' latches are `tray_1/latch_hinge` and `tray_2/latch_hinge`, no longer one `latch_hinge`. Every
+  asset the kit builds keeps today's keys for its own joints and bodies. An asset the kit didn't build, with its
+  joints elsewhere, changes: an NVIDIA robot's `/robot/joints/elbow` is now `joints/elbow`, the key `poses --set`
+  takes.
+- **The probe judges an asset with fixed joints as one asset** (its version 12): a mounted part is no longer a loose
+  body, so its tilt is the main body's and lift no longer lists it as left behind. `poses` carries a fixed joint's
+  child with its parent and counts the pair as jointed, and the review sizes a slide's drive to what is fixed on it.
+
+- **Several Isaac Sim runs at once:** reviews, switch passes, probes and showcases on one machine no longer wait for
+  each other. Each Isaac Sim process waits until there is free RAM and GPU memory for it (6 GB and 4 GB), starts one
+  at a time, and runs again, up to 3 tries, when it crashes while others run. `SIMREADY_FORGE_GPU_RESERVE_GB` keeps
+  GPU memory free for another program's Kit. The bench still runs alone. Give each run its own `--out`: two into one
+  folder at once no longer take turns.
+- **An Isaac Sim process whose log shows a `[Fatal]` line is ended at once,** as a crash, instead of holding its
+  memory until its timeout: Kit can outlive an "Out of resource descriptors" for minutes.
+- **`validate` fails a state made by hiding:** a mesh shown in one selection and hidden in another, or a prim active
+  in one and inactive in another, fails the new `composition: hidden` row; a mesh hidden in every selection, such as
+  an invisible guide collider, still passes. No asset the kit writes meets it; a hand-edited or foreign asset that
+  makes a state by hiding now fails.
+- **`inspect.json`'s texture records gain `bias`** where a texture node authors one, beside the `scale` they already
+  gave: a scan's normal map now shows its `bias` too.
+- **A generated mesh's normals and UVs are written once per point,** not once per triangle corner: a TRELLIS.2 mesh
+  is already split at its UV seams, so every corner of a point had the same values. A 150,000-triangle scan's `.usda`
+  goes from 37.1 MB to 15.7 MB and its `.usdc` from 11.0 MB to 4.3 MB; the README's running shoe from 43.0 MB to
+  20.0 MB (`.usdc` 12.8 MB to 5.6 MB). Its GLB shares those vertices too. A CAD part stays per corner, and so do a
+  scan without UVs (it takes box-projected UVs) and a scan part whose `scan.uv` a script edits so one point's corners
+  differ. An asset built before keeps per-corner
+  values until its build script runs again.
+
+### Fixed
+
+- **A `box` collider fits a part turned in its body:** it was the box of the part's bounds square to its body's axes,
+  so a 30 mm leg splayed 15° collided as a slab 300 mm wide, and a stand's legs drawn inward met under its head at 3°
+  of 8. A part whose tightest box is under 90 % of that box now collides as its own hull, which stands on a foot
+  cut level; boards, slabs and posts square to their body keep their box.
+- **`make` checks its report's sources before the session ends:** the report is written to
+  `<name>_reports/report.md`, one short refuter returns each figure with no source, a wrong value or the wrong
+  source, and the coordinator fixes them before giving it. A target only the spec gives, stated as measured, is one
+  of them.
+- **`make`'s report states the joints as `review.json` gives them:** passed on each side driven, and which are short
+  or over, in place of a "within 15 % of target" no file holds, which every report in batch 2 copied and its audits
+  failed.
+- **The batch's findings check takes `critic-fidelity (final)#1`** as citing `critic-fidelity#1`, the spelling a
+  `final.md` used.
+- **`make`'s builder and coordinator run scripts from files,** never a heredoc piped into an interpreter, which hung a
+  Windows session until its 30-minute timeout.
+
+- **The Isaac Sim review lifts an asset on a part that stands on the floor:** a table's screw foot, a jack or a
+  splaying leg had a drive sized to its own part, so it couldn't push the asset up: a levelling foot read 0 for -32 mm
+  and failed. Such a joint's drive now carries the rest of the asset too, damped for its own part and capped near what
+  it lifts, and the review doesn't hold that asset off the floor, so it lifts it as it moves. `review.json` gives the
+  mass it lifts (`lifts_kg`), whether the asset was held up (`held_up`), and in `held` the tilt of each body standing
+  on the floor, held or not.
+- **The Isaac Sim review drives an asset's joints without throwing it, and holds each at its target:** a hinge's
+  drive was sized by the 3-D distance to its load, which gave an office chair's vertical seat swivel 546 N·m where
+  gravity puts none on it, and every target was set in one step, which threw the chair over. A hinge's drive is now
+  sized to the most torque gravity can put on its axis, so a level hinge whose load rests over it (a pallet jack's
+  upright tiller, a 1 m arm) holds its target when swung out. Each target moves over 2 s (3 s across the whole range),
+  and the asset is held 1 cm off the floor while its joints move, then set down: a loaded castor turned in place
+  scrubs, sticks and slips. A free hinge (`limits=None`) turns a quarter turn one way only, since it has no other side
+  to clear, and one that ends a turn round from its target reads as there; `poses` turns it the same way.
+  `review.json` gives each held body's tilt once each pass sets it down (`held`).
+- **The Isaac Sim review reads a hinge resting past 180 degrees in its own range:** a container's door folded back to
+  -265 read as +95, so its reach looked 360 degrees short and the option failed. Its first reading is now the turn its
+  limits hold.
+
+- **A tinted look switched live comes back:** after a live switch from a `tint=` option to the default, Isaac Sim's
+  RTX kept the tint on the base colour texture (a green shoe switched back from red rendered dark brown). Every option
+  of a set that tints now writes the texture's scale, the identity where it doesn't tint; rebuild an asset to get it.
+- **`simready-forge bench` measures its field as a scene holds it:** its own count of Fabric's triangles read every
+  copy's faces, which makes RTX hold identical copies apart, so every state after a field's fresh load without
+  instancing was one the bench had changed (the shoe's 30 MB of geometry became 4.1 GB). It now counts those meshes
+  without reading them, and `bench.json` gives `gpu_geometry_mb`, Kit's figure for what the field's geometry costs.
+- **The `comfyui_url` setting is read:** every `trellis` command, and `make`'s mesh jobs, use the server it names
+  unless `--server` or `COMFYUI_URL` says otherwise. Until now only `COMFYUI_URL` reached the client.
+- **`make` asks how to run (round 1)** whenever none of those choices is remembered. Until now any remembered
+  setting, such as `comfyui_url`, skipped it.
+- **A mesh job on a ComfyUI on another machine** no longer waits for an Isaac Sim review on this one, or holds one up:
+  only a ComfyUI here shares this machine's GPU.
+- **`simready-forge qcode` waits out a busy Wikidata:** on HTTP 429 or 503 it waits as Wikidata's `Retry-After` asks,
+  else 10, 20, 40, then 80 s, and asks again, five tries in all, then exits with what Wikidata said. Until now a 429,
+  which many sessions on one address meet, ended in a traceback.
+
+- **`simready-forge probe`** no longer passes on an earlier run's `probe.json` when this run wrote none: after Isaac
+  Sim crashed or was killed it took that file for this run's, and exited 0 on it even when it had recorded the crash.
+  A timeout is now reported too, instead of ending in a traceback.
+- **A `make` with no one to answer runs to its report:** with `claude -p` and the setting `docs/USAGE.md` gives
+  (`CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1`, and longer command timeouts), every agent `make` starts and every
+  command runs in the foreground, and a fix round starts a fresh builder instead of resuming one in the background.
+  Until now such a run could end half-way, with its fixes unmade, and still exit 0.
+- **Sonnet 5.5's cache reads are priced at $0.10 a million,** Anthropic's list price, not $0.20: a `cost.json` now
+  matches Claude Code's own figures for a Sonnet builder, and reads lower than one written before for the same work.
+- **`make`'s report says what its cost leaves out:** `cost.json` runs from the session's first command, now the
+  clock, to its writing, so the report's own turns are in Claude Code's total but not in it. `simready-forge cost`
+  prints that as one line, also `cost.json`'s `line`, and the report copies it.
+- **`make` keeps every critic finding in its round:** each critic's and the refuter's answer is saved as it came,
+  `round-<n>.md` has a row for each finding with its triage, and a build after the stop takes only what its rule
+  gives it. Until now a finding could drop out of a round's summary and never be fixed.
+- **`make`'s report names the source of each number and fault:** each kind of figure has one file it comes from, a
+  figure the spec decided is called decided, not measured, a count is the file's own, and a Kit fault of the switch
+  pass is stated for the switches it names, not for every switch.
+
+## 0.1.0 (2026-10-29)
+
+The first version.
+
+### Added
+
+- **`/simready-forge:make`** turns a prompt or a photo into an NVIDIA SimReady asset: OpenUSD on the Robotics-Prop
+  4.0.0 profile with real dimensions, materials, physics materials, rigid bodies, colliders, mass and the joints the
+  real object has, checked by NVIDIA's validator, its joints measured in Isaac Sim, exported as URDF and GLB, with a
+  report of what it cost. Three modes: Quick (the builder alone), Standard (the default: the builder, then critics
+  until clean, 4 rounds at most) and Max (two or three builders and a blind judge, then critics and a refuter).
+- **`/simready-forge:settings`** shows and changes the choices it remembers, such as the builder's and the critics'
+  models and effort, for a session, a project or always.
+- **`/simready-forge:review`** validates and reviews an asset you already have, with critics.
+- **The agents** `builder` (writes and runs the build script), `critic` (fresh eyes on the renders, the spec and the
+  measurements), `refuter` (checks the builder's report against the files) and `judge` (picks between candidates
+  blind, in Max mode).
+- **The physics probe** (`simready-forge probe`): tilt, a hand's push on each part, lift and shake, 10 s at rest and
+  a box dropped on top, each measured against what the asset's own values predict.
+- **`simready-forge poses`** checks the review's joint poses without Isaac Sim (overlaps, the ground, near misses,
+  openings that must stay empty), and **`simready-forge inspect`** reads a USD back for a refuter.
+- **The `simready-forge` package and command line:** `validate`, `review`, `probe`, `poses`, `inspect`, `trellis`,
+  `views`, `qcode`, `prefs`, `cost` and `example`, and the kit's `Asset` for build scripts written by hand. Each asset is written as
+  `<name>/usd/<name>.usda`, with `<name>_exports/` and `<name>_reports/` beside it.

{simready_forge-0.1.0 → simready_forge-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: simready-forge
-Version: 0.1.0
+Version: 0.2.0
 Summary: Turn a prompt or a photo into an NVIDIA SimReady asset: OpenUSD with materials, physics and joints
 Project-URL: Homepage, https://github.com/serionist/simready-forge
 Project-URL: Repository, https://github.com/serionist/simready-forge
@@ -25,6 +25,7 @@ Requires-Dist: matplotlib==3.11.2
 Requires-Dist: numpy==2.5.4
 Requires-Dist: physx-usd-schemas==25.11.2.72696984
 Requires-Dist: pillow==13.0.0
+Requires-Dist: pyyaml==6.0.3
 Requires-Dist: scipy==1.18.1
 Requires-Dist: simready-foundation-tier-core==2026.8.0
 Requires-Dist: simready-validate==2026.8.0
@@ -67,6 +68,22 @@ A Claude Code plugin and a Python kit. One prompt or photo in; out comes:
 - **OpenUSD** (NVIDIA SimReady, Robotics-Prop 4.0.0) with real dimensions, materials and physics
 - **Every joint the real object has**, driven and measured in Isaac Sim
 - **URDF and GLB** exports, a report, and the build script to tweak and rerun
+- **A scene prop** (0.2.0 and later; add `scene` to the formats: `formats=usd,urdf,glb,scene`, or `formats=usd,scene`
+  for the USD and the scene prop alone): the same asset without bodies, mass or joints, in `.usdc`, for a scene that
+  places it thousands of times, checked against the build that was validated and reviewed
+- **Library materials** (0.2.0 and later; `library=<materials.usda>`, or the YAML list a scene tunes them in,
+  `library=<materials.yaml>`, written into a library with its texture sets from a folder you name): the materials a
+  scene tunes once, bound by name and copied into the package, or referenced live by the scene prop
+  (`library_live=<path>`); a rust or wet state is another library material, and a generated mesh keeps its baked
+  texture under it
+- **Families** (0.2.0 and later): several sizes of one object ("DN100, 300 and 600 pipes") from one script, a package
+  per size, each validated and bound to a material library by name; the smallest and the largest reviewed, the cost
+  counted once
+- **Sub-assets** (0.2.0 and later; `uses=<path>`, or a request naming an asset you made): another package inside
+  this one, a drive in its tray, two trays in a cage, copied into the package and fixed or jointed where it goes,
+  modelled once
+- **A batch from a catalogue** (0.2.0 and later; `simready-forge batch <catalogue.yaml>`): every entry made
+  unattended, one headless `make` each, resumable, with one report, one contact sheet and one bill
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/serionist/simready-forge/main/docs/assets/joints.webp" alt="A desk lamp, a camera, a nightstand and a barricade, at rest and with every joint driven" width="80%">
@@ -125,6 +142,31 @@ Eight cases (five prompts, three photos), judged the same way:
 - Quick + Sonnet passes every physics check; the extra rounds buy fidelity.
 - Probe misses are the same in every mode: no joint friction in the kit yet.
 
+## Variants (0.2.0 and later)
+
+Name the options in the request, and one asset holds them all, each validated and reviewed:
+
+```text
+/simready-forge:make an HDD tray, with or without its drive, in a high and a low poly version
+/simready-forge:make a bedside cabinet, its door open or closed, with brass or steel knobs
+/simready-forge:make running shoes in green, red or blue, with a high and a low poly version
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/serionist/simready-forge/main/docs/assets/variants.webp" alt="An HDD tray with and without its drive and at a lower detail, a bedside cabinet with its door closed and open and its knobs in brass and steel, then a running shoe generated with TRELLIS.2 in green, red and blue and at a lower detail, each option seen across its front in Isaac Sim" width="80%">
+  <br><sub>Those three prompts' assets, each option seen across its front in turn: <code>simready-forge showcase</code>. The shoe's mesh came from TRELLIS.2, set up with <code>simready-forge trellis setup</code>.</sub>
+</p>
+
+| Kind | Asked as | Changes |
+|---|---|---|
+| look | "in green, red or blue", "brass or steel knobs" | colours, textures, finishes |
+| mode | "with or without its drive", "its door open or closed" | which parts exist, where a jointed part starts |
+| detail | "a high and a low poly version" | how finely the meshes are cut |
+
+They are USD variant sets in one file: switch them in Isaac Sim, usdview or any USD tool. Every option is checked
+switched live in Isaac Sim, and an option that shows a finding ("rust", "a cap missing") can carry its label for
+synthetic images.
+
 ## Install
 
 ```text
@@ -136,7 +178,7 @@ Eight cases (five prompts, three photos), judged the same way:
 |---|---|
 | [uv](https://docs.astral.sh/uv/) | everything |
 | Isaac Sim 5.x / 6.x + NVIDIA RTX GPU | the review and the probe (else a software preview) |
-| ComfyUI + TRELLIS.2 | generated meshes (optional) |
+| ComfyUI + TRELLIS.2 | generated meshes (optional): from 0.2.0, `make` offers to install or start it when a request needs a mesh, and `trellis setup --start` does it by hand; a ComfyUI you already run is offered just the model files it lacks; one on another machine works too, set by the `comfyui_url` setting or `COMFYUI_URL`, which is how a Mac gets meshes |
 
 Working on the kit itself? Set `SIMREADY_FORGE_DEV` to your clone.
 

{simready_forge-0.1.0 → simready_forge-0.2.0}/README.md

@@ -31,6 +31,22 @@ A Claude Code plugin and a Python kit. One prompt or photo in; out comes:
 - **OpenUSD** (NVIDIA SimReady, Robotics-Prop 4.0.0) with real dimensions, materials and physics
 - **Every joint the real object has**, driven and measured in Isaac Sim
 - **URDF and GLB** exports, a report, and the build script to tweak and rerun
+- **A scene prop** (0.2.0 and later; add `scene` to the formats: `formats=usd,urdf,glb,scene`, or `formats=usd,scene`
+  for the USD and the scene prop alone): the same asset without bodies, mass or joints, in `.usdc`, for a scene that
+  places it thousands of times, checked against the build that was validated and reviewed
+- **Library materials** (0.2.0 and later; `library=<materials.usda>`, or the YAML list a scene tunes them in,
+  `library=<materials.yaml>`, written into a library with its texture sets from a folder you name): the materials a
+  scene tunes once, bound by name and copied into the package, or referenced live by the scene prop
+  (`library_live=<path>`); a rust or wet state is another library material, and a generated mesh keeps its baked
+  texture under it
+- **Families** (0.2.0 and later): several sizes of one object ("DN100, 300 and 600 pipes") from one script, a package
+  per size, each validated and bound to a material library by name; the smallest and the largest reviewed, the cost
+  counted once
+- **Sub-assets** (0.2.0 and later; `uses=<path>`, or a request naming an asset you made): another package inside
+  this one, a drive in its tray, two trays in a cage, copied into the package and fixed or jointed where it goes,
+  modelled once
+- **A batch from a catalogue** (0.2.0 and later; `simready-forge batch <catalogue.yaml>`): every entry made
+  unattended, one headless `make` each, resumable, with one report, one contact sheet and one bill
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/serionist/simready-forge/main/docs/assets/joints.webp" alt="A desk lamp, a camera, a nightstand and a barricade, at rest and with every joint driven" width="80%">
@@ -89,6 +105,31 @@ Eight cases (five prompts, three photos), judged the same way:
 - Quick + Sonnet passes every physics check; the extra rounds buy fidelity.
 - Probe misses are the same in every mode: no joint friction in the kit yet.
 
+## Variants (0.2.0 and later)
+
+Name the options in the request, and one asset holds them all, each validated and reviewed:
+
+```text
+/simready-forge:make an HDD tray, with or without its drive, in a high and a low poly version
+/simready-forge:make a bedside cabinet, its door open or closed, with brass or steel knobs
+/simready-forge:make running shoes in green, red or blue, with a high and a low poly version
+```
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/serionist/simready-forge/main/docs/assets/variants.webp" alt="An HDD tray with and without its drive and at a lower detail, a bedside cabinet with its door closed and open and its knobs in brass and steel, then a running shoe generated with TRELLIS.2 in green, red and blue and at a lower detail, each option seen across its front in Isaac Sim" width="80%">
+  <br><sub>Those three prompts' assets, each option seen across its front in turn: <code>simready-forge showcase</code>. The shoe's mesh came from TRELLIS.2, set up with <code>simready-forge trellis setup</code>.</sub>
+</p>
+
+| Kind | Asked as | Changes |
+|---|---|---|
+| look | "in green, red or blue", "brass or steel knobs" | colours, textures, finishes |
+| mode | "with or without its drive", "its door open or closed" | which parts exist, where a jointed part starts |
+| detail | "a high and a low poly version" | how finely the meshes are cut |
+
+They are USD variant sets in one file: switch them in Isaac Sim, usdview or any USD tool. Every option is checked
+switched live in Isaac Sim, and an option that shows a finding ("rust", "a cap missing") can carry its label for
+synthetic images.
+
 ## Install
 
 ```text
@@ -100,7 +141,7 @@ Eight cases (five prompts, three photos), judged the same way:
 |---|---|
 | [uv](https://docs.astral.sh/uv/) | everything |
 | Isaac Sim 5.x / 6.x + NVIDIA RTX GPU | the review and the probe (else a software preview) |
-| ComfyUI + TRELLIS.2 | generated meshes (optional) |
+| ComfyUI + TRELLIS.2 | generated meshes (optional): from 0.2.0, `make` offers to install or start it when a request needs a mesh, and `trellis setup --start` does it by hand; a ComfyUI you already run is offered just the model files it lacks; one on another machine works too, set by the `comfyui_url` setting or `COMFYUI_URL`, which is how a Mac gets meshes |
 
 Working on the kit itself? Set `SIMREADY_FORGE_DEV` to your clone.