Improve Partial Visuallization (isaac-sim#5347)

# Description

<!--
Thank you for your interest in sending a pull request. Please make sure
to check the contribution guidelines.

Link:
https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html

💡 Please try to keep PRs small and focused. Large PRs are harder to
review and merge.
-->

Improve Partial Visualization feature where a subset of envs are shown
in the launched visualizers to speed up performance, making use of new
updates to Newton.

Newton visualizers align on using the set_visible_worlds API to select
envs to show.

Kit visualizer just sets non selected envs invisible.

Updated docs and added tests.

<!-- As a practice, it is recommended to open an issue to have
discussions on the proposed pull request.
This makes it easier for the community to keep track of what is being
developed or added, and if a given feature
is demanded by more than one party. -->

## Type of change

<!-- As you go through the list, delete the ones that are not
applicable. -->

- New feature (non-breaking change which adds functionality)
- Documentation update

## Screenshots

Please attach before and after screenshots of the change if applicable.

<!--
Example:

| Before | After |
| ------ | ----- |
| _gif/png before_ | _gif/png after_ |

To upload images to a PR -- simply drag and drop an image while in edit
mode and it should upload the image directly. You can then paste that
source into the above before/after sections.
-->

## Checklist

- [ ] I have read and understood the [contribution
guidelines](https://isaac-sim.github.io/IsaacLab/main/source/refs/contributing.html)
- [ ] I have run the [`pre-commit` checks](https://pre-commit.com/) with
`./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

<!--
As you go through the checklist above, you can mark something as done by
putting an x character in it

For example,
- [x] I have done this task
- [ ] I have not done this task
-->

---------

Signed-off-by: matthewtrepte <mtrepte@nvidia.com>

Author: matthewtrepte

docs/source/features/visualization.rst

@@ -139,6 +139,21 @@ The effective visualizer mode is resolved from both CLI and ``SimulationCfg.visu
 For the migration-focused summary and deprecation context, see
 :doc:`/source/migration/migrating_to_isaaclab_3-0`.
 
+Partial Visualization
+~~~~~~~~~~~~~~~~~~~~~
+
+Visualizers can be configured to visualize just a subset of environments.
+This is called partial visualization.
+
+There are 3 fields exposed in the ``VisualizerCfg`` for selecting environments for partial visualization:
+
+- ``max_visible_envs`` caps how many envs are shown.
+- ``visible_env_indices`` explicitly selects the envs to visualize.
+- ``randomly_sample_visible_envs`` (default ``True``): when ``visible_env_indices`` is unset and ``max_visible_envs`` is set,
+  enables randomly sampling the selected envs. If disabled, the first ``max_visible_envs`` envs are selected.
+
+Also, there is a CLI arg ``--max_visible_envs`` that overrides ``VisualizerCfg.max_visible_envs`` for the run.
+
 .. _visualization-common-modes:
 
 .. list-table:: Common modes
@@ -345,7 +360,7 @@ server, allowing you to view and interact with the scene from any browser.
         open_browser=True,
         label="Isaac Lab Simulation",
         share=False,
-        max_worlds=64,
+        max_visible_envs=16,
     )
 
 **Configuration options:**
@@ -356,7 +371,6 @@ server, allowing you to view and interact with the scene from any browser.
 - ``share`` (bool, default ``False``): Request a public share URL from Viser for remote viewing.
 - ``record_to_viser`` (str or None, default ``None``): Path to save a ``.viser`` recording file.
 - ``verbose`` (bool, default ``True``): Print viewer server startup information.
-- ``max_worlds`` (int or None, default ``None``): Maximum number of environments rendered.
 
 .. note::
 
@@ -366,7 +380,7 @@ server, allowing you to view and interact with the scene from any browser.
 Performance Note
 ----------------
 
-To reduce overhead when visualizing large-scale environments, consider:
+When visualizing large-scale environments, consider:
 
 - Using Newton instead of Omniverse or Rerun
 - Reducing window sizes

docs/source/overview/core-concepts/scene_data_providers.rst

@@ -27,9 +27,9 @@ The system has three layers:
 
 1. **BaseSceneDataProvider** — abstract interface defining the contract:
 
-   - ``update(env_ids)`` — refresh cached scene data
+   - ``update()`` — refresh cached scene data (full Newton model/state sync when applicable)
    - ``get_newton_model()`` — return Newton model handle (if available)
-   - ``get_newton_state(env_ids)`` — return Newton state handle (if available)
+   - ``get_newton_state()`` — return Newton state handle (if available)
    - ``get_usd_stage()`` — return USD stage handle (if available)
    - ``get_transforms()`` — return body transforms
    - ``get_velocities()`` — return body velocities

source/isaaclab/isaaclab/app/app_launcher.py

@@ -49,57 +49,6 @@ def __call__(self, parser, namespace, values, option_string=None):
         setattr(namespace, f"{self.dest}_explicit", True)
 
 
-def _parse_visualizer_csv(value: str) -> list[str]:
-    """Parse visualizer list from a single comma-delimited CLI token."""
-    valid = {"kit", "newton", "rerun", "viser", "none"}
-    token = (value or "").strip()
-    if not token:
-        raise argparse.ArgumentTypeError(
-            "Invalid --visualizer value: empty string. Use a comma-separated list, e.g. --viz kit,newton."
-        )
-    if " " in token:
-        raise argparse.ArgumentTypeError(
-            "Invalid --visualizer value: spaces are not allowed. "
-            "Use a comma-separated list without spaces, e.g. --viz kit,newton,rerun,viser."
-        )
-
-    names = [item.strip().lower() for item in token.split(",")]
-    if any(not name for name in names):
-        raise argparse.ArgumentTypeError(
-            "Invalid --visualizer value: empty visualizer entry detected. "
-            "Use a comma-separated list without empty items."
-        )
-    invalid = [name for name in names if name not in valid]
-    if invalid:
-        raise argparse.ArgumentTypeError(
-            f"Invalid --visualizer value(s): {', '.join(invalid)}. Valid options: {', '.join(sorted(valid))}."
-        )
-    # De-duplicate while preserving order.
-    return list(dict.fromkeys(names))
-
-
-def _normalize_visualizer_intent(intent: Any) -> tuple[bool, bool]:
-    """Normalize and validate upstream config visualizer intent payload.
-
-    The expected schema is:
-    ``{"has_any_visualizers": bool, "has_kit_visualizer": bool}``.
-    """
-    if intent is None:
-        return False, False
-    if not isinstance(intent, dict):
-        raise ValueError("Invalid value for `visualizer_intent`: expected dict or None.")
-
-    has_any = intent.get("has_any_visualizers", False)
-    has_kit = intent.get("has_kit_visualizer", False)
-    if not isinstance(has_any, bool) or not isinstance(has_kit, bool):
-        raise ValueError(
-            "Invalid `visualizer_intent` values: expected booleans for `has_any_visualizers` and `has_kit_visualizer`."
-        )
-    if has_kit and not has_any:
-        raise ValueError("Invalid `visualizer_intent`: `has_kit_visualizer=True` requires `has_any_visualizers=True`.")
-    return has_any, has_kit
-
-
 class ExplicitTrueAction(argparse.Action):
     """Custom action to track explicit use of boolean flags."""
 
@@ -133,6 +82,96 @@ class AppLauncher:
 
     """
 
+    @staticmethod
+    def sync_visualizer_cli_settings_to_carb(launcher_args: dict) -> None:
+        """Write visualizer CLI selection and ``--max_visible_envs`` to carb settings.
+
+        Callers may set ``visualizer_explicit`` / ``visualizer_disable_all`` when those values
+        were resolved elsewhere (e.g. :class:`AppLauncher` strips flags from *launcher_args*).
+        Otherwise ``disable_all`` is inferred from ``"none"`` in ``visualizer``.
+
+        Also used when Kit is skipped (see :mod:`isaaclab_tasks.utils.sim_launcher`).
+        """
+        visualizers = launcher_args.get("visualizer")
+
+        if "max_visible_envs" in launcher_args:
+            v = launcher_args["max_visible_envs"]
+            if v is not None and int(v) < 0:
+                raise ValueError(f"Invalid value for --max_visible_envs: {v}. Expected non-negative int.")
+
+        cli_explicit = bool(launcher_args.get("visualizer_explicit", False))
+        if "visualizer_disable_all" in launcher_args:
+            cli_disable_all = bool(launcher_args["visualizer_disable_all"])
+        else:
+            cli_disable_all = bool(cli_explicit) and visualizers is not None and "none" in visualizers
+
+        with contextlib.suppress(Exception):
+            visualizer_str = " ".join(visualizers) if visualizers else ""
+            settings = get_settings_manager()
+            settings.set_string("/isaaclab/visualizer/types", visualizer_str)
+            settings.set_bool("/isaaclab/visualizer/explicit", cli_explicit)
+            settings.set_bool("/isaaclab/visualizer/disable_all", cli_disable_all)
+
+            # Sentinel: ``-1`` means ``--max_visible_envs`` was not passed (see ``SimulationContext``).
+            if "max_visible_envs" in launcher_args:
+                settings.set_int("/isaaclab/visualizer/max_visible_envs", int(launcher_args["max_visible_envs"]))
+            else:
+                settings.set_int("/isaaclab/visualizer/max_visible_envs", -1)
+
+    @staticmethod
+    def _parse_visualizer_csv(value: str) -> list[str]:
+        """Parse visualizer list from a single comma-delimited CLI token."""
+        valid = {"kit", "newton", "rerun", "viser", "none"}
+        token = (value or "").strip()
+        if not token:
+            raise argparse.ArgumentTypeError(
+                "Invalid --visualizer value: empty string. Use a comma-separated list, e.g. --viz kit,newton."
+            )
+        if " " in token:
+            raise argparse.ArgumentTypeError(
+                "Invalid --visualizer value: spaces are not allowed. "
+                "Use a comma-separated list without spaces, e.g. --viz kit,newton,rerun,viser."
+            )
+
+        names = [item.strip().lower() for item in token.split(",")]
+        if any(not name for name in names):
+            raise argparse.ArgumentTypeError(
+                "Invalid --visualizer value: empty visualizer entry detected. "
+                "Use a comma-separated list without empty items."
+            )
+        invalid = [name for name in names if name not in valid]
+        if invalid:
+            raise argparse.ArgumentTypeError(
+                f"Invalid --visualizer value(s): {', '.join(invalid)}. Valid options: {', '.join(sorted(valid))}."
+            )
+        # De-duplicate while preserving order.
+        return list(dict.fromkeys(names))
+
+    @staticmethod
+    def _normalize_visualizer_intent(intent: Any) -> tuple[bool, bool]:
+        """Normalize and validate upstream config visualizer intent payload.
+
+        The expected schema is:
+        ``{"has_any_visualizers": bool, "has_kit_visualizer": bool}``.
+        """
+        if intent is None:
+            return False, False
+        if not isinstance(intent, dict):
+            raise ValueError("Invalid value for `visualizer_intent`: expected dict or None.")
+
+        has_any = intent.get("has_any_visualizers", False)
+        has_kit = intent.get("has_kit_visualizer", False)
+        if not isinstance(has_any, bool) or not isinstance(has_kit, bool):
+            raise ValueError(
+                "Invalid `visualizer_intent` values: expected booleans for `has_any_visualizers` and "
+                "`has_kit_visualizer`."
+            )
+        if has_kit and not has_any:
+            raise ValueError(
+                "Invalid `visualizer_intent`: `has_kit_visualizer=True` requires `has_any_visualizers=True`."
+            )
+        return has_any, has_kit
+
     def __init__(self, launcher_args: argparse.Namespace | dict | None = None, **kwargs):
         """Create a `SimulationApp`_ instance based on the input settings.
 
@@ -188,7 +227,6 @@ def __init__(self, launcher_args: argparse.Namespace | dict | None = None, **kwa
         self._livestream: Literal[0, 1, 2]  # 0: Disabled, 1: WebRTC public, 2: WebRTC private
         self._offscreen_render: bool  # 0: Disabled, 1: Enabled
         self._sim_experience_file: str  # Experience file to load
-        self._visualizer_max_worlds: int | None  # Optional max worlds override for Newton-based visualizers
         self._video_enabled: bool  # Whether --video recording is enabled
 
         # Exposed to train scripts
@@ -330,10 +368,9 @@ def add_app_launcher_args(parser: argparse.ArgumentParser) -> None:
           - Multiple visualizers can be specified as a comma-delimited list:
             ``--viz rerun,newton,viser``.
 
-        * ``visualizer_max_worlds`` (int | None): Optional global override for the maximum number of worlds
-          rendered in Newton-based visualizers (newton, rerun, viser). If omitted, each visualizer uses its
-          config default.
-
+        * ``max_visible_envs`` (int | None): Optional global override for partial visualization by capping
+          how many environments are shown in the visualizers.
+          More partial visualization configuration fields are available in the ``VisualizerCfg`` class.
 
         .. _`WebRTC`: https://docs.isaacsim.omniverse.nvidia.com/latest/installation/manual_livestream_clients.html#isaac-sim-short-webrtc-streaming-client
 
@@ -414,7 +451,7 @@ def add_app_launcher_args(parser: argparse.ArgumentParser) -> None:
         arg_group.add_argument(
             "--visualizer",
             "--viz",
-            type=_parse_visualizer_csv,
+            type=AppLauncher._parse_visualizer_csv,
             action=ExplicitAction,
             default=None,
             help="Visualizer backends to enable as CSV (e.g., kit,newton,rerun,viser).",
@@ -485,13 +522,10 @@ def add_app_launcher_args(parser: argparse.ArgumentParser) -> None:
             ),
         )
         arg_group.add_argument(
-            "--visualizer_max_worlds",
+            "--max_visible_envs",
             type=int,
-            default=AppLauncher._APPLAUNCHER_CFG_INFO["visualizer_max_worlds"][1],
-            help=(
-                "Optional global max worlds override for Newton-based visualizers (newton/rerun/viser). "
-                "If omitted, visualizer config defaults are used."
-            ),
+            default=argparse.SUPPRESS,
+            help=("When set, caps the nums of envs shown in the launched visualizers."),
         )
         # special flag for backwards compatibility
 
@@ -513,7 +547,7 @@ def add_app_launcher_args(parser: argparse.ArgumentParser) -> None:
         "device": ([str], "cuda:0"),
         "experience": ([str], ""),
         "rendering_mode": ([str], "balanced"),
-        "visualizer_max_worlds": ([int, type(None)], None),
+        "max_visible_envs": ([int, type(None)], None),
     }
     """A dictionary of arguments added manually by the :meth:`AppLauncher.add_app_launcher_args` method.
 
@@ -783,7 +817,9 @@ def _resolve_headless_settings(self, launcher_args: dict, livestream_arg: int, l
     def _resolve_visualizer_settings(self, launcher_args: dict) -> None:
         """Resolve visualizer CLI semantics and normalize selection."""
         raw_visualizers = launcher_args.get("visualizer")
-        cfg_has_any, cfg_has_kit = _normalize_visualizer_intent(launcher_args.pop("visualizer_intent", None))
+        cfg_has_any, cfg_has_kit = AppLauncher._normalize_visualizer_intent(
+            launcher_args.pop("visualizer_intent", None)
+        )
         self._cfg_has_any_visualizers = cfg_has_any
         self._cfg_has_kit_visualizer = cfg_has_kit
         visualizer_explicit = bool(launcher_args.pop("visualizer_explicit", False))
@@ -793,7 +829,7 @@ def _resolve_visualizer_settings(self, launcher_args: dict) -> None:
         visualizer_types: list[str] = []
         if raw_visualizers is not None:
             if isinstance(raw_visualizers, str):
-                visualizer_types = _parse_visualizer_csv(raw_visualizers)
+                visualizer_types = AppLauncher._parse_visualizer_csv(raw_visualizers)
             else:
                 visualizer_types = [str(v).strip().lower() for v in raw_visualizers if str(v).strip()]
 
@@ -1152,28 +1188,14 @@ def _set_animation_recording_settings(self, launcher_args: dict) -> None:
         settings.set_float("/isaaclab/anim_recording/stop_time", stop_time)
 
     def _set_visualizer_settings(self, launcher_args: dict) -> None:
-        """Store visualizer selection and max-worlds override in settings."""
-        visualizers = launcher_args.get("visualizer")
-        visualizer_max_worlds = launcher_args.get("visualizer_max_worlds")
-
-        if visualizer_max_worlds is not None and visualizer_max_worlds < 0:
-            raise ValueError(
-                f"Invalid value for --visualizer_max_worlds: {visualizer_max_worlds}. Expected non-negative int."
-            )
-
-        with contextlib.suppress(Exception):
-            visualizer_str = " ".join(visualizers) if visualizers else ""
-            settings = get_settings_manager()
-            cli_visualizer_explicit = getattr(self, "_cli_visualizer_explicit", False)
-            cli_visualizer_disable_all = getattr(self, "_cli_visualizer_disable_all", False)
-            settings.set_string("/isaaclab/visualizer/types", visualizer_str)
-            settings.set_bool("/isaaclab/visualizer/explicit", cli_visualizer_explicit)
-            settings.set_bool("/isaaclab/visualizer/disable_all", cli_visualizer_disable_all)
-            # Store as int setting where -1 means "use per-visualizer defaults".
-            if visualizer_max_worlds is None:
-                settings.set_int("/isaaclab/visualizer/max_worlds", -1)
-            else:
-                settings.set_int("/isaaclab/visualizer/max_worlds", int(visualizer_max_worlds))
+        """Persist visualizer CLI flags and ``max_visible_envs`` override for :class:`SimulationContext`."""
+        AppLauncher.sync_visualizer_cli_settings_to_carb(
+            {
+                **launcher_args,
+                "visualizer_explicit": getattr(self, "_cli_visualizer_explicit", False),
+                "visualizer_disable_all": getattr(self, "_cli_visualizer_disable_all", False),
+            }
+        )
 
     def _interrupt_signal_handle_callback(self, signal, frame):
         """Handle the interrupt signal from the keyboard."""

source/isaaclab/isaaclab/envs/common.py

@@ -35,11 +35,8 @@ class ViewerCfg:
     """Configuration of the scene viewport camera.
 
     Note:
-        Overriding non-default fields is deprecated. In a future release, Isaac Sim viewport camera
-        configuration will be expressed only through ``KitVisualizerCfg`` under
-        ``SimulationCfg.visualizer_cfgs``; use ``NewtonVisualizerCfg`` for the Newton viewer.
-        Those visualizer configs replace the viewport camera pose, resolution, prim path, and
-        frame-origin behavior that this class used to configure.
+        ViewerCfg is deprecated. In a future release, this config will be streamlined with
+        the KitVisualizerCfg.
     """
 
     eye: tuple[float, float, float] = (7.5, 7.5, 7.5)
@@ -107,12 +104,8 @@ def __post_init__(self) -> None:
                 differing.append(f.name)
         if differing:
             warnings.warn(
-                "ViewerCfg is deprecated when overriding default viewport camera fields "
-                f"({', '.join(sorted(differing))}). In a future release, Isaac Sim viewport camera "
-                "settings will be configured only through ``SimulationCfg.visualizer_cfgs`` using "
-                "``KitVisualizerCfg`` (viewport camera pose, resolution, prim path, and "
-                "frame-origin options). For the Newton viewer, use ``NewtonVisualizerCfg``. "
-                "Migrate overrides out of ``ViewerCfg`` accordingly.",
+                "ViewerCfg is deprecated. In a future release, this config will be streamlined with "
+                "the KitVisualizerCfg.",
                 DeprecationWarning,
                 stacklevel=2,
             )

source/isaaclab/isaaclab/physics/base_scene_data_provider.py

@@ -15,8 +15,8 @@ class BaseSceneDataProvider(ABC):
     """Backend-agnostic scene data provider interface."""
 
     @abstractmethod
-    def update(self, env_ids: list[int] | None = None) -> None:
-        """Refresh any cached scene data."""
+    def update(self) -> None:
+        """Refresh any cached scene data (full model/state)."""
         raise NotImplementedError
 
     @abstractmethod
@@ -25,8 +25,8 @@ def get_newton_model(self) -> Any | None:
         raise NotImplementedError
 
     @abstractmethod
-    def get_newton_state(self, env_ids: list[int] | None = None) -> Any | None:
-        """Return Newton state handle when available."""
+    def get_newton_state(self) -> Any | None:
+        """Return Newton state handle when available (full state)."""
         raise NotImplementedError
 
     @abstractmethod