观察包装器

class gymnasium.ObservationWrapper(env: Env[ObsType, ActType])

使用 :meth:observation 函数修改来自 :meth:Env.reset 和 :meth:Env.step 的观察结果。

如果你想在将观测值传递给学习代码之前只对其应用一个函数，你可以简单地继承 :class:ObservationWrapper 并重写方法 :meth:observation 来实现该转换。该方法中定义的转换必须反映在 :attr:env 观测空间中。否则，你需要通过在包装器的 :meth:__init__ 方法中设置 :attr:self.observation_space 来指定包装器的新观测空间。

参数:

env – 要包装的环境。

observation(observation: ObsType) → WrapperObsType

返回一个修改后的观察结果。

参数:

observation – The :attr:env 观察

返回:

修改后的观察

已实现的包装器

class gymnasium.wrappers.TransformObservation(env: Env[ObsType, ActType], func: Callable[[ObsType], Any], observation_space: Space[WrapperObsType] | None)

对从环境的 :meth:Env.reset 和 :meth:Env.step 接收到的 observation 应用一个函数，该函数将返回给用户。

函数 :attr:func 将应用于所有观测值。如果来自 :attr:func 的观测值超出了 env 的观测空间范围，请提供一个更新的 :attr:observation_space。

存在一个包装器的向量版本 :class:gymnasium.wrappers.vector.TransformObservation。

示例

>>> import gymnasium as gym
>>> from gymnasium.wrappers import TransformObservation
>>> import numpy as np
>>> np.random.seed(0)
>>> env = gym.make("CartPole-v1")
>>> env.reset(seed=42)
(array([ 0.0273956 , -0.00611216,  0.03585979,  0.0197368 ], dtype=float32), {})
>>> env = gym.make("CartPole-v1")
>>> env = TransformObservation(env, lambda obs: obs + 0.1 * np.random.random(obs.shape), env.observation_space)
>>> env.reset(seed=42)
(array([0.08227695, 0.06540678, 0.09613613, 0.07422512]), {})

变更日志：

• v0.15.4 - 最初添加

• v1.0.0 - 添加 observation_space 的要求

参数:

• env – 要包装的环境

• func – 一个将转换观察结果的函数。如果这个转换后的观察结果超出了 env.observation_space 的观察空间，则提供一个 observation_space。

• observation_space – 包装器的观察空间，如果为 None，则假定与 env.observation_space 相同。

class gymnasium.wrappers.DelayObservation(env: Env[ObsType, ActType], delay: int)

向从环境中返回的观察结果添加延迟。

在达到 :attr:delay 时间步数之前，返回的观察结果是一个与观察空间形状相同的零数组。

不存在包装器的矢量版本。

备注

这不支持随机延迟值，如果用户对此感兴趣，请提出问题或提交拉取请求以添加此功能。

示例

>>> import gymnasium as gym
>>> env = gym.make("CartPole-v1")
>>> env.reset(seed=123)
(array([ 0.01823519, -0.0446179 , -0.02796401, -0.03156282], dtype=float32), {})

>>> env = DelayObservation(env, delay=2)
>>> env.reset(seed=123)
(array([0., 0., 0., 0.], dtype=float32), {})
>>> env.step(env.action_space.sample())
(array([0., 0., 0., 0.], dtype=float32), 1.0, False, False, {})
>>> env.step(env.action_space.sample())
(array([ 0.01823519, -0.0446179 , -0.02796401, -0.03156282], dtype=float32), 1.0, False, False, {})

变更日志：

• v1.0.0 - 最初添加

参数:

• env – 要包装的环境

• delay – 观察结果延迟的时间步数

class gymnasium.wrappers.DtypeObservation(env: Env[ObsType, ActType], dtype: Any)

将观测数组的 dtype 修改为指定的 dtype。

备注

这仅与 :class:Box、:class:Discrete、:class:MultiDiscrete 和 :class:MultiBinary 观测空间兼容。

存在一个包装器的向量化版本 :class:gymnasium.wrappers.vector.DtypeObservation。

变更日志：

• v1.0.0 - 最初添加

参数:

• env – 要包装的环境

• dtype – 观察的新数据类型

class gymnasium.wrappers.FilterObservation(env: Env[ObsType, ActType], filter_keys: Sequence[str | int])

通过一组键或索引过滤字典或元组观察空间。

存在一个包装器的向量化版本 :class:gymnasium.wrappers.vector.FilterObservation。

示例

>>> import gymnasium as gym
>>> from gymnasium.wrappers import FilterObservation
>>> env = gym.make("CartPole-v1")
>>> env = gym.wrappers.TimeAwareObservation(env, flatten=False)
>>> env.observation_space
Dict('obs': Box([-4.8000002e+00 -3.4028235e+38 -4.1887903e-01 -3.4028235e+38], [4.8000002e+00 3.4028235e+38 4.1887903e-01 3.4028235e+38], (4,), float32), 'time': Box(0, 500, (1,), int32))
>>> env.reset(seed=42)
({'obs': array([ 0.0273956 , -0.00611216,  0.03585979,  0.0197368 ], dtype=float32), 'time': array([0], dtype=int32)}, {})
>>> env = FilterObservation(env, filter_keys=['time'])
>>> env.reset(seed=42)
({'time': array([0], dtype=int32)}, {})
>>> env.step(0)
({'time': array([1], dtype=int32)}, 1.0, False, False, {})

变更日志：

• v0.12.3 - 最初添加，最初称为 FilterObservationWrapper

• v1.0.0 - 重命名为 FilterObservation 并添加对包含整数 filter_keys 的元组观察空间的支持

参数:

• env – 要包装的环境

• filter_keys – 要 包含 的子空间集合，对于 Dict 使用字符串列表，对于 Tuple 空间使用整数。

class gymnasium.wrappers.FlattenObservation(env: Env[ObsType, ActType])

将环境的观察空间展平，并对 reset 和 step 函数中的每个观察结果进行展平处理。

存在一个包装器的向量化版本 :class:gymnasium.wrappers.vector.FlattenObservation。

示例

>>> import gymnasium as gym
>>> from gymnasium.wrappers import FlattenObservation
>>> env = gym.make("CarRacing-v2")
>>> env.observation_space.shape
(96, 96, 3)
>>> env = FlattenObservation(env)
>>> env.observation_space.shape
(27648,)
>>> obs, _ = env.reset()
>>> obs.shape
(27648,)

变更日志：

• v0.15.0 - 最初添加

参数:

env – 要包装的环境

class gymnasium.wrappers.FrameStackObservation(env: Env[ObsType, ActType], stack_size: int, *, padding_type: str | ObsType = 'reset')

以滚动方式堆叠过去 N 个时间步的观测值。

例如，如果堆栈的数量是4，那么返回的观察结果包含最近的4个观察结果。对于环境 ‘Pendulum-v1’，原始观察结果是一个形状为 [3] 的数组，因此如果我们堆叠4个观察结果，处理后的观察结果的形状为 [4, 3]。

用户可以选择用于填充观察的选项：

• “reset” (默认) - 重置值被重复

• “zero” - 观察空间的 “zero” 类似实例

• custom - 观察空间的一个实例

不存在包装器的矢量版本。

示例

>>> import gymnasium as gym
>>> from gymnasium.wrappers import FrameStackObservation
>>> env = gym.make("CarRacing-v2")
>>> env = FrameStackObservation(env, stack_size=4)
>>> env.observation_space
Box(0, 255, (4, 96, 96, 3), uint8)
>>> obs, _ = env.reset()
>>> obs.shape
(4, 96, 96, 3)

不同填充观察的示例：

>>> env = gym.make("CartPole-v1")
>>> env.reset(seed=123)
(array([ 0.01823519, -0.0446179 , -0.02796401, -0.03156282], dtype=float32), {})
>>> stacked_env = FrameStackObservation(env, 3)   # the default is padding_type="reset"
>>> stacked_env.reset(seed=123)
(array([[ 0.01823519, -0.0446179 , -0.02796401, -0.03156282],
       [ 0.01823519, -0.0446179 , -0.02796401, -0.03156282],
       [ 0.01823519, -0.0446179 , -0.02796401, -0.03156282]],
      dtype=float32), {})

>>> stacked_env = FrameStackObservation(env, 3, padding_type="zero")
>>> stacked_env.reset(seed=123)
(array([[ 0.        ,  0.        ,  0.        ,  0.        ],
       [ 0.        ,  0.        ,  0.        ,  0.        ],
       [ 0.01823519, -0.0446179 , -0.02796401, -0.03156282]],
      dtype=float32), {})
>>> stacked_env = FrameStackObservation(env, 3, padding_type=np.array([1, -1, 0, 2], dtype=np.float32))
>>> stacked_env.reset(seed=123)
(array([[ 1.        , -1.        ,  0.        ,  2.        ],
       [ 1.        , -1.        ,  0.        ,  2.        ],
       [ 0.01823519, -0.0446179 , -0.02796401, -0.03156282]],
      dtype=float32), {})

变更日志：

• v0.15.0 - 最初添加为 FrameStack ，支持 lz4

• v1.0.0 - 重命名为 FrameStackObservation 并移除 lz4 和 LazyFrame 支持

  同时添加 padding_type 参数

参数:

• env – 应用包装器的环境

• stack_size – 要堆叠的帧数。

• padding_type – 在堆叠观测值时使用的填充类型，选项：”reset”，”zero”，自定义观测值

class gymnasium.wrappers.GrayscaleObservation(env: Env[ObsType, ActType], keep_dim: bool = False)

将由 reset 和 step 计算的图像观察结果从 RGB 转换为灰度。

The :attr:keep_dim 将保持通道维度。

存在一个包装器的向量化版本 :class:gymnasium.wrappers.vector.GrayscaleObservation。

示例

>>> import gymnasium as gym
>>> from gymnasium.wrappers import GrayscaleObservation
>>> env = gym.make("CarRacing-v2")
>>> env.observation_space.shape
(96, 96, 3)
>>> grayscale_env = GrayscaleObservation(env)
>>> grayscale_env.observation_space.shape
(96, 96)
>>> grayscale_env = GrayscaleObservation(env, keep_dim=True)
>>> grayscale_env.observation_space.shape
(96, 96, 1)

变更日志：

• v0.15.0 - 最初添加，最初称为 GrayScaleObservation

• v1.0.0 - 重命名为 GrayscaleObservation

参数:

• env – 要包装的环境

• keep_dim – 如果在观察中保留通道，如果 True，则 obs.shape == 3，否则 obs.shape == 2

class gymnasium.wrappers.MaxAndSkipObservation(env: Env[ObsType, ActType], skip: int = 4)

跳过第 N 帧（观察）并返回最后两次观察之间的最大值。

不存在包装器的矢量版本。

备注

这个包装器基于 stable-baselines3 中的包装器。

示例

>>> import gymnasium as gym
>>> env = gym.make("CartPole-v1")
>>> obs0, *_ = env.reset(seed=123)
>>> obs1, *_ = env.step(1)
>>> obs2, *_ = env.step(1)
>>> obs3, *_ = env.step(1)
>>> obs4, *_ = env.step(1)
>>> skip_and_max_obs = np.max(np.stack([obs3, obs4], axis=0), axis=0)
>>> env = gym.make("CartPole-v1")
>>> wrapped_env = MaxAndSkipObservation(env)
>>> wrapped_obs0, *_ = wrapped_env.reset(seed=123)
>>> wrapped_obs1, *_ = wrapped_env.step(1)
>>> np.all(obs0 == wrapped_obs0)
True
>>> np.all(wrapped_obs1 == skip_and_max_obs)
True

变更日志：

• v1.0.0 - 最初添加

参数:

• env (Env) – 应用包装器的环境

• skip – 要跳过的帧数

class gymnasium.wrappers.NormalizeObservation(env: Env[ObsType, ActType], epsilon: float = 1e-8)

将观测值标准化，使其以均值为中心，并具有单位方差。

属性 :attr:update_running_mean 允许冻结/继续观察统计数据的运行平均值计算。如果为 True（默认），每次调用 step 或 reset 时，RunningMeanStd 都会更新。如果为 False，则使用计算的统计数据，但不再更新；这可能在评估期间使用。

存在一个包装器的向量化版本 :class:gymnasium.wrappers.vector.NormalizeObservation。

备注

归一化依赖于过去的轨迹和观察结果，如果包装器是新实例化的或策略最近被更改，归一化将不会正确进行。

示例

>>> import numpy as np
>>> import gymnasium as gym
>>> env = gym.make("CartPole-v1")
>>> obs, info = env.reset(seed=123)
>>> term, trunc = False, False
>>> while not (term or trunc):
...     obs, _, term, trunc, _ = env.step(1)
...
>>> obs
array([ 0.1511158 ,  1.7183299 , -0.25533703, -2.8914354 ], dtype=float32)
>>> env = gym.make("CartPole-v1")
>>> env = NormalizeObservation(env)
>>> obs, info = env.reset(seed=123)
>>> term, trunc = False, False
>>> while not (term or trunc):
...     obs, _, term, trunc, _ = env.step(1)
>>> obs
array([ 2.0059888,  1.5676788, -1.9944268, -1.6120394], dtype=float32)

变更日志：

• v0.21.0 - 最初添加

• v1.0.0 - 添加 update_running_mean 属性，以允许禁用更新运行均值/标准差，特别适用于评估时间。

  将所有观测值转换为 np.float32，并将观测空间设置为 -np.inf 和 np.inf 的范围，数据类型为 np.float32

参数:

• env (Env) – 应用包装器的环境

• epsilon – 在缩放观测值时使用的稳定性参数。

class gymnasium.wrappers.AddRenderObservation(env: Env[ObsType, ActType], render_only: bool = True, render_key: str = 'pixels', obs_key: str = 'state')

在环境的观察中包含渲染的观察结果。

备注

这之前被称为 PixelObservationWrapper。

不存在包装器的矢量版本。

示例 - 用渲染的图像替换观察结果：

>>> env = gym.make("CartPole-v1", render_mode="rgb_array")
>>> env = AddRenderObservation(env, render_only=True)
>>> env.observation_space
Box(0, 255, (400, 600, 3), uint8)
>>> obs, _ = env.reset(seed=123)
>>> image = env.render()
>>> np.all(obs == image)
True
>>> obs, *_ = env.step(env.action_space.sample())
>>> image = env.render()
>>> np.all(obs == image)
True

示例 - 将渲染的图像添加到原始观察中作为字典项：

>>> env = gym.make("CartPole-v1", render_mode="rgb_array")
>>> env = AddRenderObservation(env, render_only=False)
>>> env.observation_space
Dict('pixels': Box(0, 255, (400, 600, 3), uint8), 'state': Box([-4.8000002e+00 -3.4028235e+38 -4.1887903e-01 -3.4028235e+38], [4.8000002e+00 3.4028235e+38 4.1887903e-01 3.4028235e+38], (4,), float32))
>>> obs, info = env.reset(seed=123)
>>> obs.keys()
dict_keys(['state', 'pixels'])
>>> obs["state"]
array([ 0.01823519, -0.0446179 , -0.02796401, -0.03156282], dtype=float32)
>>> np.all(obs["pixels"] == env.render())
True
>>> obs, reward, terminates, truncates, info = env.step(env.action_space.sample())
>>> image = env.render()
>>> np.all(obs["pixels"] == image)
True

变更日志：

• v0.15.0 - 最初作为 PixelObservationWrapper 添加

• v1.0.0 - 重命名为 AddRenderObservation

参数:

• env – 要包装的环境。

• render_only (bool) – 如果 True（默认），被包装环境返回的原始观察将被丢弃，观察字典将仅包含像素。如果 False，观察字典将同时包含原始观察和像素观察。

• render_key – 可选的自定义字符串，指定像素键。默认为“pixels”

• obs_key – 可选的自定义字符串，指定obs键。默认为“state”

class gymnasium.wrappers.ResizeObservation(env: Env[ObsType, ActType], shape: tuple[int, int])

使用 OpenCV 将图像观察结果调整为指定形状。

存在一个包装器的向量版本 :class:gymnasium.wrappers.vector.ResizeObservation。

示例

>>> import gymnasium as gym
>>> from gymnasium.wrappers import ResizeObservation
>>> env = gym.make("CarRacing-v2")
>>> env.observation_space.shape
(96, 96, 3)
>>> resized_env = ResizeObservation(env, (32, 32))
>>> resized_env.observation_space.shape
(32, 32, 3)

变更日志：

• v0.12.6 - 最初添加

• v1.0.0 - 需要 shape 为两个整数的元组

参数:

• env – 要包装的环境

• shape – 调整大小后的观察形状

class gymnasium.wrappers.ReshapeObservation(env: Env[ObsType, ActType], shape: int | tuple[int, ...])

将基于数组的观测值重塑为指定形状。

存在一个包装器的向量化版本 :class:gymnasium.wrappers.vector.RescaleObservation。

示例

>>> import gymnasium as gym
>>> from gymnasium.wrappers import ReshapeObservation
>>> env = gym.make("CarRacing-v2")
>>> env.observation_space.shape
(96, 96, 3)
>>> reshape_env = ReshapeObservation(env, (24, 4, 96, 1, 3))
>>> reshape_env.observation_space.shape
(24, 4, 96, 1, 3)

变更日志：

• v1.0.0 - 最初添加

参数:

• env – 要包装的环境

• shape – 重塑的观察空间

class gymnasium.wrappers.RescaleObservation(env: Env[ObsType, ActType], min_obs: floating | integer | ndarray, max_obs: floating | integer | ndarray)

将环境的 Box 观测空间仿射（线性）重新缩放到 [min_obs, max_obs] 范围内。

存在一个包装器的向量化版本 :class:gymnasium.wrappers.vector.RescaleObservation。

示例

>>> import gymnasium as gym
>>> from gymnasium.wrappers import RescaleObservation
>>> env = gym.make("Pendulum-v1")
>>> env.observation_space
Box([-1. -1. -8.], [1. 1. 8.], (3,), float32)
>>> env = RescaleObservation(env, np.array([-2, -1, -10], dtype=np.float32), np.array([1, 0, 1], dtype=np.float32))
>>> env.observation_space
Box([ -2.  -1. -10.], [1. 0. 1.], (3,), float32)

变更日志：

• v1.0.0 - 最初添加

参数:

• env – 要包装的环境

• min_obs – 新的最小观测界限

• max_obs – 新的最大观测界限

class gymnasium.wrappers.TimeAwareObservation(env: Env[ObsType, ActType], flatten: bool = True, normalize_time: bool = False, *, dict_time_key: str = 'time')

在观察中增加一个情节内所采取的时间步数。

如果 :attr:normalize_time 为 True，则将时间表示为 [0,1] 之间的归一化值；如果为 False，则当前时间步长为整数。

对于具有 Dict 观测空间的环境，时间信息会自动添加到键 "time" 中（可以通过 :attr:dict_time_key 更改），而对于具有 Tuple 观测空间的环境，时间信息会作为元组的最后一个元素添加。否则，观测空间会被转换为一个具有两个键的 Dict 观测空间，"obs" 用于基础环境的观测，"time" 用于时间信息。

要扁平化观察结果，请使用 :attr:flatten 参数，该参数将使用 :func:gymnasium.spaces.utils.flatten 函数。

不存在包装器的矢量版本。

示例

>>> import gymnasium as gym
>>> from gymnasium.wrappers import TimeAwareObservation
>>> env = gym.make("CartPole-v1")
>>> env = TimeAwareObservation(env)
>>> env.observation_space
Box([-4.80000019e+00 -3.40282347e+38 -4.18879032e-01 -3.40282347e+38
  0.00000000e+00], [4.80000019e+00 3.40282347e+38 4.18879032e-01 3.40282347e+38
 5.00000000e+02], (5,), float64)
>>> env.reset(seed=42)[0]
array([ 0.0273956 , -0.00611216,  0.03585979,  0.0197368 ,  0.        ])
>>> _ = env.action_space.seed(42)
>>> env.step(env.action_space.sample())[0]
array([ 0.02727336, -0.20172954,  0.03625453,  0.32351476,  1.        ])

标准化时间观测空间示例：

>>> env = gym.make('CartPole-v1')
>>> env = TimeAwareObservation(env, normalize_time=True)
>>> env.observation_space
Box([-4.8000002e+00 -3.4028235e+38 -4.1887903e-01 -3.4028235e+38
  0.0000000e+00], [4.8000002e+00 3.4028235e+38 4.1887903e-01 3.4028235e+38 1.0000000e+00], (5,), float32)
>>> env.reset(seed=42)[0]
array([ 0.0273956 , -0.00611216,  0.03585979,  0.0197368 ,  0.        ],
      dtype=float32)
>>> _ = env.action_space.seed(42)
>>> env.step(env.action_space.sample())[0]
array([ 0.02727336, -0.20172954,  0.03625453,  0.32351476,  0.002     ],
      dtype=float32)

扁平化观察空间示例：

>>> env = gym.make("CartPole-v1")
>>> env = TimeAwareObservation(env, flatten=False)
>>> env.observation_space
Dict('obs': Box([-4.8000002e+00 -3.4028235e+38 -4.1887903e-01 -3.4028235e+38], [4.8000002e+00 3.4028235e+38 4.1887903e-01 3.4028235e+38], (4,), float32), 'time': Box(0, 500, (1,), int32))
>>> env.reset(seed=42)[0]
{'obs': array([ 0.0273956 , -0.00611216,  0.03585979,  0.0197368 ], dtype=float32), 'time': array([0], dtype=int32)}
>>> _ = env.action_space.seed(42)
>>> env.step(env.action_space.sample())[0]
{'obs': array([ 0.02727336, -0.20172954,  0.03625453,  0.32351476], dtype=float32), 'time': array([1], dtype=int32)}

变更日志：

• v0.18.0 - 最初添加

• v1.0.0 - 移除向量环境支持，添加 flatten 和 normalize_time 参数

参数:

• env – 应用包装器的环境

• flatten – 将观察结果展平为一个单维度的 Box

• normalize_time – 如果 True 返回时间在范围 [0,1] 内，否则返回截断前的剩余时间步。

• dict_time_key – 对于具有 Dict 观测空间的环境，时间空间的关键字。默认情况下，"time"。