Skip to content

Remove unregistered rtx_raytracing_fractionalCutoutOpacity carb setting - #12

Open
lanafi00 wants to merge 4 commits into
AccelerationConsortium:mainfrom
lanafi00:fix/carb-settings-cutout-opacity
Open

lanafi00 wants to merge 4 commits into
AccelerationConsortium:mainfrom
lanafi00:fix/carb-settings-cutout-opacity

Conversation

@lanafi00

@lanafi00 lanafi00 commented Sep 3, 2026

Copy link
Copy Markdown
Contributor

Description

Isaac Sim 5.1 no longer registers rtx_raytracing_fractionalCutoutOpacity in carb settings, so Isaac Lab's _apply_render_settings_from_cfg() was raising a ValueError because this key is not found.

I don't know how rtx_raytracing_fractionalCutoutOpacity was renamed or restructured so I dropped the stale key entirely.
This is a raytraced-cutout-opacity rendering toggle, not physics-affecting, so nothing behavioral is lost beyond that visual effect.

Type of change

  • Bug fix (non-breaking change which fixes an issue)

Checklist

  • I have run the pre-commit checks with <FULL_PATH_TO_ISAACLAB>/isaaclab.sh --format
  • I have made corresponding changes to the documentation
  • My changes generate no new warnings
  • I have added tests that prove my fix is effective or that my feature works
  • I have updated the changelog and the corresponding version in the extension's config/extension.toml file
  • I have added my name to the CONTRIBUTORS.md or my name already exists there

@lanafi00
lanafi00 requested a review from kouroshD as a code owner September 3, 2026 02:49
@SissiFeng

Copy link
Copy Markdown
Collaborator

Request changes: please rebase and reproduce this issue against current main before deciding to remove the setting.

Please complete the following:

  1. Run an environment-construction smoke test using the exact versions targeted by current main:

    • start Isaac Sim/Isaac Lab;
    • construct a Matterix environment with one environment instance;
    • call reset() and at least one step();
    • close the environment cleanly;
    • report any exception or new warning.
  2. Record the actual runtime versions of Isaac Lab, Isaac Sim, Python, CUDA, and the renderer. The existing queued CI job does not provide this evidence.

  3. Test the documented replacement setting:
    /rtx/pathtracing/fractionalCutoutOpacity

    Please determine whether the original translucency intent can be preserved using the current RenderCfg API, for example with enable_translucency=True plus the current carb setting path.

  4. Add a configuration/runtime test that verifies:

    • the obsolete path is not used;
    • the intended current setting is present;
    • the value read back from carb settings after environment construction is correct.
  5. Provide before/after renders using the same scene, camera, lighting, seed, and renderer. The scene should contain representative transparent or cutout materials such as glassware or liquid. Please attach both images and check for opacity, missing cutout detail, and translucency artifacts.

  6. Update the in-code comment to describe the current Isaac Lab 3.0 behavior rather than the obsolete 2.3 method and Isaac Sim 5.1 failure path.

If the exception cannot be reproduced on the current stack, this PR should be closed or re-scoped as cleanup. If fractional cutout opacity is still required, the PR should migrate to the supported setting instead of deleting the visual behavior without regression evidence.

Lila Anafi and others added 2 commits September 3, 2026 21:56
IsaacLab's _apply_render_settings_from_cfg() validates every
RenderCfg.carb_settings key against currently-registered carb settings
and raises ValueError if the key isn't found. Under Isaac Sim 5.1,
rtx_raytracing_fractionalCutoutOpacity is no longer registered (renamed
or restructured upstream since it was added in #23), so any env
construction was raising ValueError and failing outright.

Drop the stale key; rtx_translucency_enabled still applies. This is a
raytraced-cutout-opacity rendering toggle, not physics-affecting, so
nothing behavioral is lost beyond that visual effect.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Addresses reviewer request to reproduce against current main before
deciding to remove the setting.

Reproduced the original crash on isaaclab==2.3.0/isaacsim==5.1.0.0 (env
construction smoke test, exact ValueError text matched). On current main's
isaaclab==3.0.0b2.post1/isaacsim==6.0.1.0, the crash no longer reproduces:
SimulationContext's render-settings application was rewritten and no longer
validates carb_settings keys against the registry, so an unregistered key is
now a silent no-op instead of a ValueError. Re-scoping this from an
active-crash fix to cleanup accordingly.

Searched isaacsim 6.0.1.0's full /rtx settings tree (including its new
rtpt/path-tracing branch) - no fractional-cutout-opacity setting exists
there either, at the reviewer's suggested /rtx/pathtracing/... path or
anywhere else, matching what was already found under 5.1.0. Nothing to
migrate to.

- Update the in-code comment to describe current Isaac Lab 3.0 behavior
  (silent no-op) alongside the original isaaclab 2.3.0 failure mode, rather
  than only the obsolete crash path.
- Add source/matterix/test/test_carb_settings_translucency.py: rather than
  asserting on IsaacLab's own validation behavior (which has already changed
  shape once across versions this project has targeted, for reasons outside
  Matterix's control), this pins down what Matterix actually owns - the
  config never reintroduces the dead key, translucency stays configured, and
  the value it maps to is actually readable back from carb settings after a
  real environment construction.
- Captured before/after renders of the beaker-lift scene (same camera,
  lighting, seed, renderer) with the dead key present vs removed - identical
  MD5 hash, confirming zero visual effect on current main.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@lanafi00
lanafi00 force-pushed the fix/carb-settings-cutout-opacity branch from dfc0d94 to 7d93739 Compare September 4, 2026 03:20
Lila Anafi and others added 2 commits September 4, 2026 00:02
Retracts a wrong claim from the previous commit. Confirmed identically on
isaaclab==2.3.0/isaacsim==5.1.0.0 and isaaclab==3.0.0b2.post1/isaacsim==6.0.1.0:
rtx_raytracing_fractionalCutoutOpacity is not a retired feature. It's a
raytracing-namespaced carb setting that the raytracing/path-tracing extension
only registers once the renderer actually switches into that render mode. The
base env config applies carb_settings during SimulationContext.__init__(),
which always runs before any such mode switch, so the setting is genuinely
unregistered at that point in the pipeline - on both Isaac Sim versions
tested, not just one. Once a scene is actually rendered in PathTracing mode,
the setting appears with real values on both versions
(/rtx/raytracing/fractionalCutoutOpacity=False,
/rtx/pathtracing/fractionalCutoutOpacity=True by default).

So the original PR (#23) applied this setting at a lifecycle stage where it
could never take effect in the base (non-raytraced) render path, on any
version. That's still a real bug worth fixing by removing it from the base
config - but "the feature was retired upstream" was wrong; it should have
read "applied too early in the render pipeline to ever register."

- Rewrote the in-code comment on the base config to describe the actual
  mechanism (lifecycle timing) instead of the incorrect "retired" claim.
- Restored the original visual intent where it can actually take effect: the
  "pathtracing" render preset (used by prepare_for_video_rec() for video
  recording) now explicitly sets /rtx/pathtracing/fractionalCutoutOpacity,
  the one place in the codebase that configures raytracing-namespaced
  settings at the right time (right before path-traced rendering runs).
- Extended test_carb_settings_translucency.py to cover both: the base
  config still has no dead key and keeps translucency working, and the
  pathtracing preset's cutout-opacity setting is both configured correctly
  and reads back correctly after a real path-traced render. Verified live
  end to end (env construction, render, video encode) on
  isaaclab==3.0.0b2.post1/isaacsim==6.0.1.0.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The previous commit also added /rtx/pathtracing/fractionalCutoutOpacity to
the "pathtracing" video-recording preset, restoring the setting where it can
actually take effect. On reflection this was unnecessary: the setting already
defaults to True on both isaaclab==2.3.0/isaacsim==5.1.0.0 and
isaaclab==3.0.0b2.post1/isaacsim==6.0.1.0 once path tracing engages, so
nothing was visually broken there to begin with, and prepare_for_video_rec()
has exactly one caller in the codebase (a manual test script, not part of any
CI, training, or eval path). Keeping this PR scoped to what was actually
broken: the base config crash and its corrected explanation.

Reverts the pathtracing preset change and the corresponding test coverage
added for it; keeps the corrected root-cause comment on the base config and
the base-config-focused test (dead key absent, translucency configured and
reading back correctly). Re-verified passing on isaaclab==3.0.0b2.post1/
isaacsim==6.0.1.0.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@lanafi00

lanafi00 commented Sep 4, 2026

Copy link
Copy Markdown
Contributor Author

I could not reproduce this error on the current stack, so I am re-scoping as cleanup.

Reproduction, old stack: confirmed on isaaclab==2.3.0 / isaacsim==5.1.0.0. Constructing SimulationContext with rtx_raytracing_fractionalCutoutOpacity in carb_settings raises:
ValueError: '/rtx/raytracing/fractionalCutoutOpacity' in RenderCfg.general_parameters does not map to a carb setting.

Reproduction, current main: does not reproduce on isaaclab==3.0.0b2.post1 / isaacsim==6.0.1.0. SimulationContext's render-settings application was rewritten between these versions, and isaaclab==3.0.0b2.post1's version no longer checks for the existence of carb settings.

Correction on the replacement-setting question: Correcting my earlier PR, this setting is lazily registered, not retired. rtx_raytracing_fractionalCutoutOpacity is raytracing-namespaced, and only gets registered once the renderer actually switches into that render mode. SimulationContext.__init__(), which is where the base env's carb_settings get applied, always runs before any switch to raytracing render mode.

. Confirmed identically on both Isaac Sim versions: searching the /rtx tree right after launch found nothing on either 5.1.0 or 6.0.1.0, but once I forced actual PathTracing render mode and rendered a real frame, the setting appeared on both with real values (/rtx/raytracing/fractionalCutoutOpacity=False, /rtx/pathtracing/fractionalCutoutOpacity=True by default).

Translucency preservation: rtx_translucency_enabled is a separate setting, unaffected by any of this, and confirmed still applying correctly.

Config/runtime test (source/matterix/test/test_carb_settings_translucency.py): the base config never reintroduces the dead key, and rtx_translucency_enabled is present and reads back True after a real environment construction. Verified directly on isaaclab==3.0.0b2.post1/isaacsim==6.0.1.0.

Before/after renders: captured the beaker-lift scene (default render mode, not path tracing) with identical camera/lighting/seed, dead key present vs. removed. Byte-identical MD5.

In-code comment: rewritten to describe the actual mechanism rather than the incorrect "retired" claim.

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.

2 participants