Skip to content

crust-core: the image depends on the scene index alone (hydra-only-renders) - #431

Merged
doubleailes merged 3 commits into
mainfrom
hydra-only-renders
Oct 30, 2026
Merged

doubleailes merged 3 commits into
mainfrom
hydra-only-renders

Conversation

@doubleailes

Copy link
Copy Markdown
Owner

Why

Crust's delegate reads only Hydra schemas (tests/hydra_only.rs), but three answers it took from the host's stage through HostFacts still changed the image:

  • the authoring layer of an asset value;
  • the stage's metersPerUnit;
  • a material's .mtlx reference.

Under a host with no stage (NoHostFacts), a relative texture authored as a string, a metre-unit scene's lens and a .mtlx-referenced material rendered differently. A Hydra 2.0 delegate should render from its index alone.

What

  • The unit from the index. Moho is bumped to 4d63d41 (stage: the root carries the stage's authored unit (__usdMetersPerUnit) Moho#28, stage-meters-per-unit). Depth of field reads __usdMetersPerUnit/metersPerUnit from the index root. HostFacts::meters_per_unit is removed.
  • Asset paths from the index. An asset value arrives resolved on its authoring layer, as UsdImaging does it. HostFacts::authoring_layer_dir is removed, along with the layer-directory plumbing: MatSource's index, rebase and host fields; the MaterialX and precomp translators' LayerDir; and the products reader's host.
  • Behaviour change: a relative path authored as a string, which USD never anchors, resolves against the stage's directory and raises the new asset.string_path warning. This reverses 0bebb347. A temporary count under crust check found ALab 2.3.0 and the Moana island author no such path.
  • The one exception left: .mtlx references stay a host fact until mtlx-format-plugin composes them into the stage.
  • Diagnostics only: the other host facts inform warnings, crust check and provenance only.

OpenSpec: openspec/changes/hydra-only-renders/. It adds requirements to render-delegate ("The image depends on the scene index alone") and to usd-scene-import ("Relative asset paths resolve as the index gives them").

Tests

  • crust-render/tests/host_facts.rs (the guard): every samples/*.usda that references no .mtlx renders bit-identically at 16 spp with NoHostFacts and with StageHostFacts. materialx_basic is checked to differ, so the exception list cannot hide a regression.
  • crust-core/tests/lens_units_from_index.rs: a metre stage's lens is identical without host facts. On the old code it was 100× too wide without them.
  • crust-core/tests/asset_anchoring.rs: the string case is rewritten (resolves against the stage, warns), and an absolute-string case is added.

Measurements

  • Images: scripts/check_images.sh against goldens recorded before the change (16 spp, --indirect-clamp 0): all 45 samples identical. Kitchen_set is not on the machine I used.

  • Local gate (Windows): fmt and clippy are clean, with and without --features delegate. The workspace tests pass except three that fail identically on unmodified main and are Windows-specific:

    • asset_anchoring::relative_assets_…: Linux path expectations;
    • kept::a_tile_added_…: touching a directory is denied;
    • stamp::the_lens_the_layer_stack_…: 8.3 short-path spelling.

    Linux CI is the check for those, for the unchanged asset cases, and for the site build: Zola 0.21 is needed for the new texture file paths section and the asset.string_path warning row.

Downstream

Mantle bumps crust-render after this merges. It needs no code change, since it keeps passing StageHostFacts.

🤖 Generated with Claude Code

…nders)

What the delegate asks its host about the stage (HostFacts) now informs
warnings, crust check and provenance only, except a .mtlx reference until
mtlx-format-plugin composes it into the stage.

- Moho 4d63d41 (stage-meters-per-unit): depth of field reads the stage unit
  from the index root's __usdMetersPerUnit/metersPerUnit;
  HostFacts::meters_per_unit is removed.
- Asset paths are the index's asset values, which Moho resolves on their
  authoring layer. HostFacts::authoring_layer_dir and the layer-dir
  plumbing (MatSource, the MaterialX and precomp translators, the products
  reader) are removed. A relative path authored as a string, which USD
  never anchors, resolves against the stage's directory and raises the new
  asset.string_path warning (reverses 0bebb34; ALab 2.3.0 and the Moana
  island author none).
- crust-render/tests/host_facts.rs: every sample that references no .mtlx
  renders bit-identically at 16 spp with NoHostFacts and StageHostFacts; a
  .mtlx sample is checked to differ.
- tests/lens_units_from_index.rs; asset_anchoring.rs's string case
  rewritten, an absolute-string case added.

Images: all 45 samples identical to goldens recorded before the change
(scripts/check_images.sh, 16 spp, --indirect-clamp 0).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@qodo-code-review

Copy link
Copy Markdown
Contributor

PR Summary by Qodo

Render from scene-index assets and units without stage host facts

🐞 Bug fix ✨ Enhancement 🧪 Tests 📝 Documentation 🕐 40+ Minutes

Grey Divider

AI Description

• Read lens units and asset paths from the scene index instead of render-affecting host facts.
• Resolve relative string paths beside the stage with warnings; retain referenced MaterialX as an
 exception.
• Guard host-independent rendering with bitwise image comparisons and targeted lens and asset tests.
Diagram

graph TD
  I["Scene index"] --> A["Asset values"] --> D["Scene delegate"] --> R["Renderer"]
  I --> U["Root units"] --> D
  H["Host facts"] --> M["MTLX reference"] --> D
  H --> W["Diagnostics"]
Loading
High-Level Assessment

The following are alternative approaches to this PR:

1. Keep host-side layer lookup for strings
  • ➕ Preserves the previous behavior for string paths authored in sublayers.
  • ➖ Keeps pixels dependent on stage facts and preserves anchoring that USD does not provide for strings.
2. Reject relative string paths
  • ➕ Avoids an ambiguous fallback location.
  • ➖ Breaks existing root-relative content that can still be read and diagnosed.

Recommendation: Use the PR's index-first approach. Stage-directory fallback plus a warning preserves useful string-path behavior without a stage lookup; keeping referenced MaterialX as an explicit temporary exception avoids coupling this change to its format-plugin work.

Files changed (30) +697 / -225

Enhancement (1) +2 / -0
warnings.rsDefine the relative string-path warning +2/-0

Define the relative string-path warning

• Adds asset.string_path as an approximated warning emitted for each applicable read.

crates/crust-core/src/warnings.rs

Bug fix (2) +49 / -38
assets.rsResolve file paths without authoring-layer host lookups +30/-19

Resolve file paths without authoring-layer host lookups

• Uses the index value's resolved path first, then an absolute authored path or the stage directory. Relative string paths now raise an attribute-specific asset.string_path warning.

crates/crust-core/src/scene/hydra/assets.rs

camera.rsRead depth-of-field units from the index root +19/-19

Read depth-of-field units from the index root

• Reads __usdMetersPerUnit/metersPerUnit through the scene index instead of HostFacts, preserving the existing fallback and invalid-unit handling. Adjusts camera tests to use the indexed value.

crates/crust-core/src/scene/hydra/camera.rs

Refactor (11) +28 / -171
commit.rsBuild committed cameras without host unit facts +1/-1

Build committed cameras without host unit facts

• Passes the scene index, rather than host facts, into camera construction.

crates/crust-core/src/scene/hydra/commit.rs

host.rsRemove render-affecting unit and layer queries +0/-11

Remove render-affecting unit and layer queries

• Removes meters_per_unit and authoring_layer_dir from HostFacts and NoHostFacts. The MaterialX reference query remains.

crates/crust-core/src/scene/hydra/index/host.rs

lights.rsUse index asset values for light files +5/-4

Use index asset values for light files

• Stops requesting authoring-layer directories for IES profiles and rect and dome textures; supplies attribute paths for string-path warnings.

crates/crust-core/src/scene/hydra/lights.rs

materials.rsRemove material layer-directory plumbing +6/-51

Remove material layer-directory plumbing

• Drops MatSource's host, index, and rebase fields used for layer lookup. Ptex and MaterialX file resolution now use index values, with property paths available for diagnostics.

crates/crust-core/src/scene/hydra/materials.rs

mod.rsDecouple product import from host facts +1/-9

Decouple product import from host facts

• Passes only the stage path into render-product import and removes the shared authoring-layer directory helper.

crates/crust-core/src/scene/hydra/mod.rs

mtlx_network.rsTranslate inline MaterialX without layer callbacks +2/-18

Translate inline MaterialX without layer callbacks

• Removes LayerDir from network and value-graph translation. Filename assets use index values and property paths rather than host-derived layer directories.

crates/crust-core/src/scene/hydra/mtlx_network.rs

precomp.rsRemove host layer lookups from precomp +5/-8

Remove host layer lookups from precomp

• Eliminates LayerDir parameters throughout precomp graph and display reading. Kernel paths use index asset values, with the kernel attribute identified for warnings.

crates/crust-core/src/scene/hydra/precomp.rs

preview.rsResolve preview textures without host layers +1/-1

Resolve preview textures without host layers

• Replaces the layer-directory lookup for preview texture files with their attribute path for warning context.

crates/crust-core/src/scene/hydra/preview.rs

products.rsRead render products and precomp without host facts +7/-19

Read render products and precomp without host facts

• Changes product import to accept an optional stage path rather than a stage-path-and-host pair, removing the precomp layer callback. Updates its test caller.

crates/crust-core/src/scene/hydra/products.rs

update.rsRefresh cameras from the index +0/-1

Refresh cameras from the index

• Removes host facts from camera construction during settings refresh.

crates/crust-core/src/scene/hydra/update.rs

stage_facts.rsRemove obsolete stage-derived rendering facts +0/-48

Remove obsolete stage-derived rendering facts

• Deletes stage metadata and authoring-layer lookup implementations after their consumers move to index data.

crates/crust-core/src/scene/usd_import/stage_facts.rs

Tests (3) +273 / -7
asset_anchoring.rsTest stage-relative string paths and absolute paths +56/-7

Test stage-relative string paths and absolute paths

• Rewrites the relative-string test to expect stage-directory resolution and a warning. Adds an absolute-string case that expects the literal path without a warning.

crates/crust-core/tests/asset_anchoring.rs

lens_units_from_index.rsVerify metre-stage lenses without host facts +94/-0

Verify metre-stage lenses without host facts

• Commits a metre-unit camera with StageHostFacts and NoHostFacts, checking both its expected lens diameter and bitwise equality.

crates/crust-core/tests/lens_units_from_index.rs

host_facts.rsGuard image equality across host-fact implementations +123/-0

Guard image equality across host-fact implementations

• Renders non-MaterialX-reference samples at 16 spp with and without stage facts and compares image bits. Verifies a referenced MaterialX sample still differs, making the exception explicit.

crates/crust-render/tests/host_facts.rs

Documentation (10) +341 / -7
architecture.mdClarify the remaining render-affecting host exception +1/-1

Clarify the remaining render-affecting host exception

• Updates the HostFacts architecture contract to identify MaterialX references as the sole remaining image-affecting fact.

docs/architecture.md

design.mdRecord index-only rendering decisions and trade-offs +108/-0

Record index-only rendering decisions and trade-offs

• Explains stage-directory fallback for strings, index-root lens units, the image-comparison guard, and the temporary MaterialX exception. Records content measurements and migration risks.

openspec/changes/hydra-only-renders/design.md

proposal.mdPropose removing render dependence on stage facts +70/-0

Propose removing render dependence on stage facts

• States the motivation, behavior change, affected capabilities, and scope of the remaining MaterialX exception.

openspec/changes/hydra-only-renders/proposal.md

spec.mdSpecify scene-index-dependent rendered images +37/-0

Specify scene-index-dependent rendered images

• Requires host facts to affect diagnostics rather than pixels, except for referenced MaterialX. Defines image-equality, metre-lens, and exception scenarios.

openspec/changes/hydra-only-renders/specs/render-delegate/spec.md

spec.mdSpecify asset and string path resolution +29/-0

Specify asset and string path resolution

• Requires index-resolved asset paths, stage-relative fallback and warnings for relative strings, and unchanged handling of absolute strings.

openspec/changes/hydra-only-renders/specs/usd-scene-import/spec.md

tasks.mdTrack implementation and validation work +33/-0

Track implementation and validation work

• Records the Moho bump, asset and camera changes, render guard, documentation, and validation tasks, including remaining unchecked items.

openspec/changes/hydra-only-renders/tasks.md

design.mdDocument the delegate's image dependency boundary +25/-0

Document the delegate's image dependency boundary

• Explains why index assets and units determine rendering while most HostFacts supply diagnostics, and names the MaterialX exception and regression guard.

openspec/specs/render-delegate/design.md

design.mdUpdate import design for indexed units and assets +22/-6

Update import design for indexed units and assets

• Records index-root camera units, the narrower HostFacts contract, and the reversal of layer anchoring for relative string paths.

openspec/specs/usd-scene-import/design.md

warnings.mdDocument asset.string_path remediation +1/-0

Document asset.string_path remediation

• Adds the new warning and advises authoring asset-typed paths to obtain layer-relative resolution.

site/content/docs/reference/warnings.md

materials.mdExplain texture file path anchoring +15/-0

Explain texture file path anchoring

• Documents layer-relative asset paths, stage-relative string paths, absolute strings, and the warning, including other file-reading inputs.

site/content/docs/usd/materials.md

Other (3) +4 / -2
Cargo.tomlPin Moho with index-provided stage units +1/-1

Pin Moho with index-provided stage units

• Bumps Moho to the revision that exposes authored metersPerUnit on the scene-index root.

Cargo.toml

Cargo.lockLock the updated Moho revision +1/-1

Lock the updated Moho revision

• Updates the Moho Git source to match the workspace dependency pin.

Cargo.lock

.openspec.yamlConfigure the Hydra-only-renders OpenSpec change +2/-0

Configure the Hydra-only-renders OpenSpec change

• Adds the spec-driven change metadata and creation date.

openspec/changes/hydra-only-renders/.openspec.yaml

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@qodo-code-review

qodo-code-review Bot commented Oct 30, 2026 •

Copy link
Copy Markdown
Contributor

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

Grey Divider


Informational

1. New string-path warning prints a run of spaces ✓ Resolved
Description
The message literal passed to crate::warning!(AssetStringPath, …) in asset_value_path has about
fourteen spaces between "does not" and "anchor". It looks like a wrapped line lost its trailing \
continuation. Every asset.string_path warning in the CLI log, crust check and JSON reports
carries that gap, and tests that match the message text have to match it too.
Code

crates/crust-core/src/scene/hydra/assets.rs[199]

+            "{named} authors the relative path \"{authored}\" as a string, which USD does not              anchor on its layer; it resolves against the stage's directory, to {}",
Relevance

●●● Strong

Straightforward warning-text formatting fix; extra spaces visibly alter every emitted diagnostic.

ⓘ Recommendations generated based on similar findings in past PRs

Evidence
The literal at line 199 holds the spaces inline instead of using a \ continuation (other warnings
in the repo, e.g. the pixel-aspect ones, use \ and an indented next line). So the spaces become
part of the emitted string.

crates/crust-core/src/scene/hydra/assets.rs[196-201]

Agent prompt
The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The `asset.string_path` warning message has a block of literal spaces in the middle because a wrapped line lost its `\` continuation.

## Fix Focus Areas
- crates/crust-core/src/scene/hydra/assets.rs[196-201]

## Recommended Fix
Split the literal with a trailing backslash: `"{named} authors the relative path \"{authored}\" as a string, which USD does not \
anchor on its layer; it resolves against the stage's directory, to {}"`. Then check whether `tests/asset_anchoring.rs` asserts on the message text.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools


Grey Divider

Context sources
✅ Cross-repo context — repo relationships
  Explored: repo: doubleailes/Obsidian (sha: d6b1c128) — View relationship
  Explored: repo: doubleailes/Mantle (sha: 566eb0d1) — View relationship
Review mode: Auto: 🧠 Deep: Broad rendering behavior changes span many independent asset, camera, and host paths.

Grey Divider

Tip of the day
💡 Did you know, you can route each severity your way: inline, summary, both, or drop

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Grey Divider

Qodo Logo

… on #431)

A wrapped line of the warning's literal had lost its trailing \ continuation,
so every message carried about fourteen spaces between "does not" and
"anchor". asset_anchoring's string case now checks the message text. Also
ticks hydra-only-renders 2.4, 4.2 and 4.3, verified by #431's Linux CI.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@doubleailes
doubleailes merged commit cfddfac into main Oct 30, 2026
15 checks passed
@doubleailes
doubleailes deleted the hydra-only-renders branch October 30, 2026 08:48
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant