Consolidate Cartpole task IDs via preset CLI

Collapse 35 per-variant Cartpole gym task IDs into 4 consolidated tasks
that select the variant via the typed preset CLI from isaac-sim#5587:

- Isaac-Cartpole-Camera-Direct-v0 (subsumes 7 Direct-backend perception IDs)
- Isaac-Cartpole-Camera-v0 (subsumes 4 manager-based perception IDs)
- Isaac-Cartpole-Showcase-Direct-v0 (subsumes 15 proprioceptive showcase IDs)
- Isaac-Cartpole-Camera-Showcase-Direct-v0 (subsumes 9 camera showcase IDs)

Variant selection moves from the gym ID to ``presets=<name>`` (plus
``physics=`` / ``renderer=`` on the Direct-backend camera task, and
``--agent=`` where the per-shape skrl / rl_games yaml differs from the
default). Each retired ID stays registered for one release with an
env_cfg_entry_point that emits a DeprecationWarning naming the new task
and the equivalent CLI tokens, then returns the corresponding cfg.

The shim machinery is factored into a new helper:

  isaaclab_tasks.utils.deprecated_task_alias(
      old_task_id, new_command, consolidated_cfg_path, cfg_factory=None
  )

which wraps the warning emission plus lazy cfg resolution behind the
``"module:Name"`` entry-point string convention gym uses elsewhere.

The consolidated PresetCfg classes live alongside their per-variant
siblings in the existing *_env_cfg.py files; no new wrapper modules.
PresetCfg's docstring now documents the underscore-prefix convention for
class-local helpers (the resolver already skips them).

Full per-ID migration table is in the PR description.

Author: hujc7

source/isaaclab_tasks/changelog.d/jichuanh-cartpole-presets.minor.rst

@@ -0,0 +1,27 @@
+Added
+^^^^^
+
+* Added four consolidated Cartpole perception tasks that subsume 35
+  per-variant task IDs via the typed preset CLI (#5587):
+  ``Isaac-Cartpole-Camera-Direct-v0``, ``Isaac-Cartpole-Camera-v0``,
+  ``Isaac-Cartpole-Showcase-Direct-v0``, and
+  ``Isaac-Cartpole-Camera-Showcase-Direct-v0``. Variant (data type,
+  observation pipeline, gym-space shape) selected at runtime via
+  ``presets=<name>``; agent yaml selected via
+  ``--agent=<entry_point_name>`` for the manager perception feature
+  policies and all non-default showcase shapes.
+* Added :func:`isaaclab_tasks.utils.deprecated_task_alias` -- factory
+  that wraps a retired gym task ID with a :class:`DeprecationWarning`
+  naming the consolidated task plus its equivalent CLI tokens, and
+  lazily resolves the cfg variant at ``gym.make`` time.
+
+Deprecated
+^^^^^^^^^^
+
+* Deprecated 35 per-variant Cartpole task IDs (7 Direct-backend camera,
+  4 manager-based camera, 15 proprioceptive showcase, 9 camera-based
+  showcase) in favor of the four consolidated tasks above. Each retired
+  ID still loads and emits a :class:`DeprecationWarning` naming the
+  consolidated task and the equivalent ``presets=<name>`` (plus
+  ``--agent=<entry_point_name>`` where required) invocation. Full
+  migration table is in the PR description.

source/isaaclab_tasks/isaaclab_tasks/direct/cartpole/__init__.py

@@ -9,6 +9,8 @@
 
 import gymnasium as gym
 
+from isaaclab_tasks.utils import deprecated_task_alias
+
 from . import agents
 
 ##
@@ -29,78 +31,150 @@
 )
 
 gym.register(
-    id="Isaac-Cartpole-RGB-Camera-Direct-v0",
+    id="Isaac-Cartpole-Camera-Direct-v0",
     entry_point=f"{__name__}.cartpole_camera_env:CartpoleCameraEnv",
     disable_env_checker=True,
     kwargs={
-        "env_cfg_entry_point": f"{__name__}.cartpole_camera_env_cfg:CartpoleRGBCameraEnvCfg",
+        "env_cfg_entry_point": f"{__name__}.cartpole_camera_env_cfg:CartpoleCameraPresetsEnvCfg",
         "rl_games_cfg_entry_point": f"{agents.__name__}:rl_games_camera_ppo_cfg.yaml",
         "skrl_cfg_entry_point": f"{agents.__name__}:skrl_camera_ppo_cfg.yaml",
     },
 )
 
+
+# Retired per-data-type camera task IDs. Each is registered as a deprecation
+# shim that emits a DeprecationWarning naming the consolidated task with the
+# equivalent presets=<name>, then loads the corresponding variant of
+# CartpoleCameraPresetsEnvCfg. The nested tiled_camera attribute must be
+# pinned alongside the root preset -- see _resolve_camera_variant.
+_CAMERA_CFG_PATH = f"{__name__}.cartpole_camera_env_cfg:CartpoleCameraPresetsEnvCfg"
+_CAMERA_KWARGS = {
+    "rl_games_cfg_entry_point": f"{agents.__name__}:rl_games_camera_ppo_cfg.yaml",
+    "skrl_cfg_entry_point": f"{agents.__name__}:skrl_camera_ppo_cfg.yaml",
+}
+
+
+def _resolve_camera_variant(preset_name: str):
+    """Lazy 2-axis resolver: pin both the root cfg variant and the nested
+    ``tiled_camera`` preset. Without this the nested PresetCfg's default
+    (rgb) wins and a deprecated albedo task would load albedo's
+    ``observation_space`` with rgb ``data_types``.
+
+    Returns a zero-arg callable so the import of
+    :class:`CartpoleCameraPresetsEnvCfg` is deferred to ``gym.make()``.
+    """
+
+    def call():
+        from .cartpole_camera_env_cfg import CartpoleCameraPresetsEnvCfg
+
+        cfg = CartpoleCameraPresetsEnvCfg()
+        result = getattr(cfg, preset_name)
+        result.tiled_camera = getattr(result.tiled_camera, preset_name)
+        return result
+
+    return call
+
+
 gym.register(
-    id="Isaac-Cartpole-Albedo-Camera-Direct-v0",
+    id="Isaac-Cartpole-Camera-Presets-Direct-v0",
     entry_point=f"{__name__}.cartpole_camera_env:CartpoleCameraEnv",
     disable_env_checker=True,
     kwargs={
-        "env_cfg_entry_point": f"{__name__}.cartpole_camera_env_cfg:CartpoleAlbedoCameraEnvCfg",
-        "rl_games_cfg_entry_point": f"{agents.__name__}:rl_games_camera_ppo_cfg.yaml",
-        "skrl_cfg_entry_point": f"{agents.__name__}:skrl_camera_ppo_cfg.yaml",
+        "env_cfg_entry_point": deprecated_task_alias(
+            "Isaac-Cartpole-Camera-Presets-Direct-v0",
+            "--task=Isaac-Cartpole-Camera-Direct-v0",
+            _CAMERA_CFG_PATH,
+        ),
+        **_CAMERA_KWARGS,
     },
 )
 
 gym.register(
-    id="Isaac-Cartpole-SimpleShading-Constant-Camera-Direct-v0",
+    id="Isaac-Cartpole-RGB-Camera-Direct-v0",
     entry_point=f"{__name__}.cartpole_camera_env:CartpoleCameraEnv",
     disable_env_checker=True,
     kwargs={
-        "env_cfg_entry_point": f"{__name__}.cartpole_camera_env_cfg:CartpoleSimpleShadingConstantCameraEnvCfg",
-        "rl_games_cfg_entry_point": f"{agents.__name__}:rl_games_camera_ppo_cfg.yaml",
-        "skrl_cfg_entry_point": f"{agents.__name__}:skrl_camera_ppo_cfg.yaml",
+        "env_cfg_entry_point": deprecated_task_alias(
+            "Isaac-Cartpole-RGB-Camera-Direct-v0",
+            "--task=Isaac-Cartpole-Camera-Direct-v0 presets=rgb",
+            _CAMERA_CFG_PATH,
+            cfg_factory=_resolve_camera_variant("rgb"),
+        ),
+        **_CAMERA_KWARGS,
     },
 )
 
 gym.register(
-    id="Isaac-Cartpole-SimpleShading-Diffuse-Camera-Direct-v0",
+    id="Isaac-Cartpole-Albedo-Camera-Direct-v0",
     entry_point=f"{__name__}.cartpole_camera_env:CartpoleCameraEnv",
     disable_env_checker=True,
     kwargs={
-        "env_cfg_entry_point": f"{__name__}.cartpole_camera_env_cfg:CartpoleSimpleShadingDiffuseCameraEnvCfg",
-        "rl_games_cfg_entry_point": f"{agents.__name__}:rl_games_camera_ppo_cfg.yaml",
-        "skrl_cfg_entry_point": f"{agents.__name__}:skrl_camera_ppo_cfg.yaml",
+        "env_cfg_entry_point": deprecated_task_alias(
+            "Isaac-Cartpole-Albedo-Camera-Direct-v0",
+            "--task=Isaac-Cartpole-Camera-Direct-v0 presets=albedo",
+            _CAMERA_CFG_PATH,
+            cfg_factory=_resolve_camera_variant("albedo"),
+        ),
+        **_CAMERA_KWARGS,
     },
 )
 
 gym.register(
-    id="Isaac-Cartpole-SimpleShading-Full-Camera-Direct-v0",
+    id="Isaac-Cartpole-SimpleShading-Constant-Camera-Direct-v0",
     entry_point=f"{__name__}.cartpole_camera_env:CartpoleCameraEnv",
     disable_env_checker=True,
     kwargs={
-        "env_cfg_entry_point": f"{__name__}.cartpole_camera_env_cfg:CartpoleSimpleShadingFullCameraEnvCfg",
-        "rl_games_cfg_entry_point": f"{agents.__name__}:rl_games_camera_ppo_cfg.yaml",
-        "skrl_cfg_entry_point": f"{agents.__name__}:skrl_camera_ppo_cfg.yaml",
+        "env_cfg_entry_point": deprecated_task_alias(
+            "Isaac-Cartpole-SimpleShading-Constant-Camera-Direct-v0",
+            "--task=Isaac-Cartpole-Camera-Direct-v0 presets=simple_shading_constant_diffuse",
+            _CAMERA_CFG_PATH,
+            cfg_factory=_resolve_camera_variant("simple_shading_constant_diffuse"),
+        ),
+        **_CAMERA_KWARGS,
     },
 )
 
 gym.register(
-    id="Isaac-Cartpole-Depth-Camera-Direct-v0",
+    id="Isaac-Cartpole-SimpleShading-Diffuse-Camera-Direct-v0",
     entry_point=f"{__name__}.cartpole_camera_env:CartpoleCameraEnv",
     disable_env_checker=True,
     kwargs={
-        "env_cfg_entry_point": f"{__name__}.cartpole_camera_env_cfg:CartpoleDepthCameraEnvCfg",
-        "rl_games_cfg_entry_point": f"{agents.__name__}:rl_games_camera_ppo_cfg.yaml",
-        "skrl_cfg_entry_point": f"{agents.__name__}:skrl_camera_ppo_cfg.yaml",
+        "env_cfg_entry_point": deprecated_task_alias(
+            "Isaac-Cartpole-SimpleShading-Diffuse-Camera-Direct-v0",
+            "--task=Isaac-Cartpole-Camera-Direct-v0 presets=simple_shading_diffuse_mdl",
+            _CAMERA_CFG_PATH,
+            cfg_factory=_resolve_camera_variant("simple_shading_diffuse_mdl"),
+        ),
+        **_CAMERA_KWARGS,
     },
 )
 
 gym.register(
-    id="Isaac-Cartpole-Camera-Presets-Direct-v0",
+    id="Isaac-Cartpole-SimpleShading-Full-Camera-Direct-v0",
     entry_point=f"{__name__}.cartpole_camera_env:CartpoleCameraEnv",
     disable_env_checker=True,
     kwargs={
-        "env_cfg_entry_point": f"{__name__}.cartpole_camera_presets_env_cfg:CartpoleCameraPresetsEnvCfg",
-        "rl_games_cfg_entry_point": f"{agents.__name__}:rl_games_camera_ppo_cfg.yaml",
-        "skrl_cfg_entry_point": f"{agents.__name__}:skrl_camera_ppo_cfg.yaml",
+        "env_cfg_entry_point": deprecated_task_alias(
+            "Isaac-Cartpole-SimpleShading-Full-Camera-Direct-v0",
+            "--task=Isaac-Cartpole-Camera-Direct-v0 presets=simple_shading_full_mdl",
+            _CAMERA_CFG_PATH,
+            cfg_factory=_resolve_camera_variant("simple_shading_full_mdl"),
+        ),
+        **_CAMERA_KWARGS,
+    },
+)
+
+gym.register(
+    id="Isaac-Cartpole-Depth-Camera-Direct-v0",
+    entry_point=f"{__name__}.cartpole_camera_env:CartpoleCameraEnv",
+    disable_env_checker=True,
+    kwargs={
+        "env_cfg_entry_point": deprecated_task_alias(
+            "Isaac-Cartpole-Depth-Camera-Direct-v0",
+            "--task=Isaac-Cartpole-Camera-Direct-v0 presets=depth",
+            _CAMERA_CFG_PATH,
+            cfg_factory=_resolve_camera_variant("depth"),
+        ),
+        **_CAMERA_KWARGS,
     },
 )

source/isaaclab_tasks/isaaclab_tasks/direct/cartpole/cartpole_camera_env_cfg.py

@@ -13,6 +13,7 @@
 from isaaclab.sim import SimulationCfg
 from isaaclab.utils import configclass
 
+from isaaclab_tasks.utils import PresetCfg
 from isaaclab_tasks.utils.presets import MultiBackendRendererCfg
 
 from isaaclab_assets.robots.cartpole import CARTPOLE_CFG
@@ -158,3 +159,99 @@ class CartpoleSimpleShadingFullCameraEnvCfg(CartpoleRGBCameraEnvCfg):
 
     # spaces
     observation_space = [tiled_camera.height, tiled_camera.width, 3]
+
+
+##
+# Consolidated PresetCfg
+##
+
+
+@configclass
+class MultiDataTypeCartpoleTiledCameraCfg(PresetCfg):
+    @configclass
+    class CartpoleTiledCameraCfg(CameraCfg):
+        prim_path: str = "/World/envs/env_.*/Camera"
+        offset: CameraCfg.OffsetCfg = CameraCfg.OffsetCfg(
+            pos=(-5.0, 0.0, 2.0), rot=(0.0, 0.0, 0.0, 1.0), convention="world"
+        )
+        data_types: list[str] = []
+        spawn: sim_utils.PinholeCameraCfg = sim_utils.PinholeCameraCfg(
+            focal_length=24.0, focus_distance=400.0, horizontal_aperture=20.955, clipping_range=(0.1, 20.0)
+        )
+        width: int = 100
+        height: int = 100
+        renderer_cfg: MultiBackendRendererCfg = MultiBackendRendererCfg()
+
+    # Class-local helper (``_`` prefix -> PresetCfg resolver skips it, not a variant).
+    # 180-degree offset matches the historical Albedo / SimpleShading per-variant
+    # camera orientations (the dropped *-Camera-Direct-v0 task IDs).
+    _ROTATED_OFFSET = CameraCfg.OffsetCfg(pos=(-5.0, 0.0, 2.0), rot=(1.0, 0.0, 0.0, 0.0), convention="world")
+
+    rgb = CartpoleTiledCameraCfg(data_types=["rgb"])
+    depth = CartpoleTiledCameraCfg(data_types=["depth"])
+    semantic_segmentation = CartpoleTiledCameraCfg(data_types=["semantic_segmentation"])
+    albedo = CartpoleTiledCameraCfg(data_types=["albedo"], offset=_ROTATED_OFFSET)
+    # simple_shading_* -- cheap renderer-side approximations used for the dropped
+    # Isaac-Cartpole-SimpleShading-{Constant,Diffuse,Full}-Camera-Direct-v0 tasks.
+    # Trade visual fidelity (constant < diffuse_mdl < full_mdl) for throughput.
+    simple_shading_constant_diffuse = CartpoleTiledCameraCfg(
+        data_types=["simple_shading_constant_diffuse"], offset=_ROTATED_OFFSET
+    )
+    simple_shading_diffuse_mdl = CartpoleTiledCameraCfg(
+        data_types=["simple_shading_diffuse_mdl"], offset=_ROTATED_OFFSET
+    )
+    simple_shading_full_mdl = CartpoleTiledCameraCfg(data_types=["simple_shading_full_mdl"], offset=_ROTATED_OFFSET)
+    default = rgb
+
+
+@configclass
+class CartpoleCameraPresetsEnvCfg(PresetCfg):
+    @configclass
+    class BaseCartpoleCameraEnvCfg(DirectRLEnvCfg):
+        # env
+        decimation = 2
+        episode_length_s = 5.0
+        action_scale = 100.0  # [N]
+
+        # simulation
+        sim: SimulationCfg = SimulationCfg(dt=1 / 120, render_interval=decimation)
+
+        # robot
+        robot_cfg: ArticulationCfg = CARTPOLE_CFG.replace(prim_path="/World/envs/env_.*/Robot")
+        cart_dof_name = "slider_to_cart"
+        pole_dof_name = "cart_to_pole"
+
+        # camera
+        tiled_camera: MultiDataTypeCartpoleTiledCameraCfg = MultiDataTypeCartpoleTiledCameraCfg()
+        write_image_to_file = False
+
+        # spaces
+        action_space = 1
+        state_space = 0
+        observation_space = [100, 100, 3]
+
+        # change viewer settings
+        viewer = ViewerCfg(eye=(20.0, 20.0, 20.0))
+
+        # scene
+        scene: InteractiveSceneCfg = InteractiveSceneCfg(num_envs=512, env_spacing=20.0, replicate_physics=True)
+
+        # reset
+        max_cart_pos = 3.0  # the cart is reset if it exceeds that position [m]
+        initial_pole_angle_range = [-0.125, 0.125]  # the range in which the pole angle is sampled from on reset [rad]
+
+        # reward scales
+        rew_scale_alive = 1.0
+        rew_scale_terminated = -2.0
+        rew_scale_pole_pos = -1.0
+        rew_scale_cart_vel = -0.01
+        rew_scale_pole_vel = -0.005
+
+    rgb = BaseCartpoleCameraEnvCfg()
+    depth = BaseCartpoleCameraEnvCfg(observation_space=[100, 100, 1])
+    albedo = BaseCartpoleCameraEnvCfg(observation_space=[100, 100, 3])
+    semantic_segmentation = BaseCartpoleCameraEnvCfg(observation_space=[100, 100, 4])
+    simple_shading_constant_diffuse = BaseCartpoleCameraEnvCfg(observation_space=[100, 100, 3])
+    simple_shading_diffuse_mdl = BaseCartpoleCameraEnvCfg(observation_space=[100, 100, 3])
+    simple_shading_full_mdl = BaseCartpoleCameraEnvCfg(observation_space=[100, 100, 3])
+    default = rgb