Implementation:Farama Foundation Gymnasium Vector Observation Wrappers

Knowledge Sources	Farama_Foundation_Gymnasium Gymnasium Docs
Domains	Reinforcement_Learning, Wrappers
Last Updated	2026-02-15 03:00 GMT

Overview

A collection of vectorized observation wrappers that transform observations for VectorEnv environments, including TransformObservation, VectorizeTransformObservation, and specialized wrappers for filtering, flattening, grayscaling, resizing, reshaping, rescaling, and dtype conversion.

Description

This module provides vectorized versions of observation transformation wrappers:

• TransformObservation -- Applies a user-provided function to the entire vector of observations at once. Accepts optional observation_space and single_observation_space parameters for specifying the transformed spaces. Best used when vector-level parallel processing is possible.

• VectorizeTransformObservation -- Wraps a single-agent observation wrapper to work with vector environments by iterating over individual observations and applying the wrapper's transform. Uses a fake _SingleEnv internally. Handles final_obs in same-step autoreset mode. Serves as the base class for the specialized wrappers below.

• FilterObservation -- Filters Dict or Tuple observation spaces to include only specified keys or indices.

• FlattenObservation -- Flattens observations using spaces.utils.flatten.

• GrayscaleObservation -- Converts RGB image observations to grayscale, with optional dimension retention.

• ResizeObservation -- Resizes image observations to a target shape using OpenCV.

• ReshapeObservation -- Reshapes array-based observations to a new shape.

• RescaleObservation -- Linearly rescales observations to a new [min_obs, max_obs] range.

• DtypeObservation -- Converts observation dtype (e.g., float32 to float64).

All specialized wrappers are thin subclasses of VectorizeTransformObservation that delegate to the corresponding single-agent wrappers from gymnasium.wrappers.transform_observation.

Usage

Use these wrappers to preprocess observations in vectorized environments. The specialized wrappers (Filter, Flatten, Grayscale, etc.) are preferred for common operations. Use TransformObservation for custom vector-level transforms or VectorizeTransformObservation for applying custom single-agent wrappers.

Code Reference

Source Location

• Repository: Farama_Foundation_Gymnasium
• File: gymnasium/wrappers/vector/vectorize_observation.py

Signature

class TransformObservation(VectorObservationWrapper):
    def __init__(self, env: VectorEnv, func: Callable[[ObsType], Any],
                 observation_space: Space | None = None, single_observation_space: Space | None = None): ...

class VectorizeTransformObservation(VectorObservationWrapper):
    def __init__(self, env: VectorEnv, wrapper: type[transform_observation.TransformObservation], **kwargs: Any): ...

class FilterObservation(VectorizeTransformObservation):
    def __init__(self, env: VectorEnv, filter_keys: Sequence[str | int]): ...

class FlattenObservation(VectorizeTransformObservation):
    def __init__(self, env: VectorEnv): ...

class GrayscaleObservation(VectorizeTransformObservation):
    def __init__(self, env: VectorEnv, keep_dim: bool = False): ...

class ResizeObservation(VectorizeTransformObservation):
    def __init__(self, env: VectorEnv, shape: tuple[int, ...]): ...

class ReshapeObservation(VectorizeTransformObservation):
    def __init__(self, env: VectorEnv, shape: int | tuple[int, ...]): ...

class RescaleObservation(VectorizeTransformObservation):
    def __init__(self, env: VectorEnv, min_obs: np.floating | np.integer | np.ndarray,
                 max_obs: np.floating | np.integer | np.ndarray): ...

class DtypeObservation(VectorizeTransformObservation):
    def __init__(self, env: VectorEnv, dtype: Any): ...

Import

from gymnasium.wrappers.vector import (
    TransformObservation, VectorizeTransformObservation,
    FilterObservation, FlattenObservation, GrayscaleObservation,
    ResizeObservation, ReshapeObservation, RescaleObservation, DtypeObservation,
)

I/O Contract

Inputs

Name	Type	Required	Description
env	VectorEnv	Yes	The vector environment to wrap
func	Callable	Yes (TransformObservation)	Function to transform the vector observation
observation_space	Space or None	No	The new observation space for the vectorized environment
single_observation_space	Space or None	No	The observation space for a single sub-environment
filter_keys	Sequence[str or int]	Yes (FilterObservation)	Keys/indices to keep in Dict/Tuple spaces
keep_dim	bool	No (GrayscaleObservation)	Keep the channel dimension (default False)
shape	tuple[int, ...]	Yes (Resize/Reshape)	Target shape for resizing or reshaping
min_obs, max_obs	float, int, or ndarray	Yes (RescaleObservation)	New observation bounds
dtype	Any	Yes (DtypeObservation)	The new dtype for observations

Outputs

Name	Type	Description
observations	ObsType	Transformed vector observations

Usage Examples

import numpy as np
import gymnasium as gym
from gymnasium.wrappers.vector import FlattenObservation, GrayscaleObservation, DtypeObservation

# Flatten observations
envs = gym.make_vec("CarRacing-v3", num_envs=3, vectorization_mode="sync")
envs = FlattenObservation(envs)
obs, info = envs.reset(seed=123)
obs.shape  # (3, 27648)
envs.close()

# Convert to grayscale
envs = gym.make_vec("CarRacing-v3", num_envs=3, vectorization_mode="sync")
envs = GrayscaleObservation(envs)
obs, info = envs.reset(seed=123)
obs.shape  # (3, 96, 96)
envs.close()

# Change dtype
envs = gym.make_vec("CartPole-v1", num_envs=3, vectorization_mode="sync")
envs = DtypeObservation(envs, dtype=np.float64)
obs, info = envs.reset(seed=123)
obs.dtype  # dtype('float64')
envs.close()

Related Pages

• Environment:Farama_Foundation_Gymnasium_Python_3_10_Runtime