unilab.base.np_env.NpEnv

class unilab.base.np_env.NpEnv[source]

Bases: ABEnv

Backend-agnostic numpy environment base class.

Parameters:

Methods

__init__(cfg, backend, num_envs)

apply_action(actions, state)

Subclasses implement the action-to-control conversion.

capture_play_video_frame()

Capture one detached RGB video frame through the env contract.

close()

Close the environment and release backend-owned scene assets.

export_training_state()

Export cumulative training progress, independently of episode/physics state.

get_physics_state_snapshot()

Return a detached physics snapshot for offline playback/video export.

get_playback_model([env_index])

Return the backend playback model for one env in a vectorized batch.

get_scene_visual_model_file()

Return the backend scene visual model file on the cold path, when available.

import_training_state(state)

Validate and restore cumulative progress before the next control step.

init_play_renderer([render_spacing, ...])

Initialize backend-native playback rendering when available.

init_state()

Initialize environment and return initial state

render([mode])

Render the current state to an RGB array through the play renderer.

render_play_frame()

Render one interactive playback frame through the env contract.

reset(env_indices)

resolve_play_render_plan(*, ...)

Resolve high-level playback mode through the concrete backend.

run_playback(*, initialize, step, num_steps)

Execute playback through the concrete backend.

run_playback_mode(*, play_render_mode, ...)

Resolve configured playback mode and execute it through the backend contract.

set_autoreset(enabled)

Toggle automatic reset of done envs at the end of step.

set_nan_guard(guard)

step(actions)

Step the environment with given actions, return new state

update_state(state)

Subclasses compute observation, reward, and termination state.

Attributes

action_space

Action space

cfg

The configuration of the environment

num_envs

return the size of the env if it is vectorized

obs_groups_spec

101}.

observation_space

Observation space

play_capabilities

Return env-facing play/render capabilities.

state

Current environment state (None before first reset)
__init__(cfg, backend, num_envs)[source]
Parameters:
property cfg: EnvCfg

The configuration of the environment

property num_envs: int

return the size of the env if it is vectorized

property state: NpEnvState | None

Current environment state (None before first reset)

property obs_groups_spec: dict[str, int]

101}.

Subclasses MUST override this property.

Type:

Return observation group dimensions, e.g. {“obs”

Type:

98, “critic”

property observation_space: Space

Observation space

init_state()[source]

Initialize environment and return initial state

Return type:

NpEnvState

step(actions)[source]

Step the environment with given actions, return new state

Parameters:

actions (ndarray)

Return type:

NpEnvState

reset(env_indices)[source]
Parameters:

env_indices (ndarray)

Return type:

Tuple[dict[str, ndarray], dict]

init_play_renderer(render_spacing=None, render_offset_mode=None, *, headless=False, capture=False, width=1280, height=720, camera_kwargs=None)[source]

Initialize backend-native playback rendering when available.

Parameters:
Return type:

None

resolve_play_render_plan(*, play_render_mode, play_steps, output_video)[source]

Resolve high-level playback mode through the concrete backend.

Parameters:
Return type:

BackendPlayRenderPlan

run_playback(*, initialize, step, num_steps, output_video=None, render_spacing=None, render_offset_mode=None, headless=None, record_video=None, frame_state_getter=None, camera_kwargs=None, debug_overlay_getter=None, on_frame=None)[source]

Execute playback through the concrete backend.

on_frame is declared on the env contract but the unisim SimBackend.run_playback boundary does not accept it yet; passing a callback fails closed until the upstream contract lands. Use unilab.visualization.playback_session.SnapshotPlaybackSession for deferred rendering with per-frame callbacks today.

Parameters:

  • initialize (Callable[[], Any])

  • step (Callable[[Any], Any])

  • num_steps (int | None)

  • output_video (str | PathLike[str] | None)

  • render_spacing (float | None)

  • render_offset_mode (str | None)

  • headless (bool | None)

  • record_video (bool | None)

  • frame_state_getter (Callable[[], np.ndarray] | None)

  • camera_kwargs (CameraCfg | Mapping[str, Any] | None)

  • debug_overlay_getter (DebugOverlayGetter | None)

  • on_frame (Callable[[int, np.ndarray], np.ndarray | None] | None)

Return type:

str | None

render_play_frame()[source]

Render one interactive playback frame through the env contract.

Return type:

None

render(mode='rgb_array')[source]

Render the current state to an RGB array through the play renderer.

Lazily initializes a headless capture renderer on first use and returns one detached (H, W, 3) uint8 frame per call. Backends without native video capture fail closed with a class-named error.

Parameters:

mode (str)

Return type:

ndarray

capture_play_video_frame()[source]

Capture one detached RGB video frame through the env contract.

Return type:

ndarray

get_physics_state_snapshot()[source]

Return a detached physics snapshot for offline playback/video export.

Return type:

ndarray

abstract apply_action(actions, state)[source]

Subclasses implement the action-to-control conversion.

Parameters:
Return type:

ndarray

abstract update_state(state)[source]

Subclasses compute observation, reward, and termination state.

Parameters:

state (NpEnvState)

Return type:

NpEnvState

property play_capabilities: EnvPlayCapabilities

Return env-facing play/render capabilities.

get_playback_model(env_index=None)[source]

Return the backend playback model for one env in a vectorized batch.

Parameters:

env_index (int | None) – Optional vectorized environment index.

Return type:

Any

Returns:

The backend-specific playback model.

get_scene_visual_model_file()[source]

Return the backend scene visual model file on the cold path, when available.

Return type:

str | None

set_nan_guard(guard)[source]
Parameters:

guard (NanGuard)

Return type:

None

set_autoreset(enabled)[source]

Toggle automatic reset of done envs at the end of step.

Defaults to True (standard RL autoreset). Interactive playback can disable it so a terminated robot stays put until a manual reset.

Parameters:

enabled (bool)

Return type:

None

export_training_state()[source]

Export cumulative training progress, independently of episode/physics state.

Task-specific curriculum state belongs to the task’s explicit provider; this payload deliberately does not inspect manager or environment internals.

Return type:

dict[str, Any]

import_training_state(state)[source]

Validate and restore cumulative progress before the next control step.

Parameters:

state (Mapping[str, Any])

Return type:

None

close()[source]

Close the environment and release backend-owned scene assets.

Return type:

None

abstract property action_space: Space

Action space

run_playback_mode(*, play_render_mode, play_steps, output_video, initialize, step, render_spacing=None, render_offset_mode=None, frame_state_getter=None, camera_kwargs=None, debug_overlay_getter=None, on_frame=None, on_plan=None)

Resolve configured playback mode and execute it through the backend contract.

Overlay gating follows the resolved plan mode: record playback requires play_capabilities.supports_debug_overlay (backends fail closed otherwise); interactive playback requires supports_interactive_debug_overlay — when the backend lacks it the getter is dropped with a warning so interactive playback still runs without overlays.

Parameters:
Return type:

str | None