### Run MetaDrive Examples from Command Line

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/get_start.rst

Execute various MetaDrive examples directly from your terminal. These examples demonstrate immediate use after installation, procedural map generation, map visualization, and performance profiling. Ensure no sub-folder named 'metadrive' exists in the current directory before running.

```bash
# Make sure current folder does not have a sub-folder named metadrive
python -m metadrive.examples.drive_in_single_agent_env
```

```bash
python -m metadrive.examples.procedural_generation
```

```bash
python -m metadrive.examples.draw_maps
```

```bash
python -m metadrive.examples.profile_metadrive
```

```bash
# Make sure current folder does not have a sub-folder named metadrive

# ===== Generalization Environments =====
python -m metadrive.examples.drive_in_single_agent_env

# ===== Real-world Environments =====
python -m metadrive.examples.drive_in_real_env

# ===== Safe RL Environments =====
python -m metadrive.examples.drive_in_safe_metadrive_env

# ===== Multi-agent Environments =====
# Options for --env: roundabout, intersection, tollgate, bottleneck, parkinglot, pgma
python -m metadrive.examples.drive_in_multi_agent_env --env pgma
```

--------------------------------

### Instantiate and Use MetaDrive Environment with Gymnasium

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/get_start.rst

A minimal Python example demonstrating how to instantiate a MetaDrive environment using the gymnasium API. It shows environment reset, stepping through the environment with random actions, and closing the environment. This is compatible with most decision-making algorithms that support OpenAI gym.

```python
from metadrive.envs.metadrive_env import MetaDriveEnv
import gymnasium as gym

env = MetaDriveEnv(config={"use_render": True})
obs, info = env.reset()
for i in range(1000):
    obs, reward, terminated, truncated, info = env.step(env.action_space.sample())
    if terminated or truncated:
        env.reset()
env.close()
```

--------------------------------

### Install MetaDrive from Source

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/install.rst

Installs MetaDrive by cloning the repository and using pip. It recommends cloning the repository to get the latest version directly.

```bash
git clone https://github.com/metadriverse/metadrive.git
cd metadrive
pip install -e .
```

--------------------------------

### Wrap MetaDrive Environment for openai.gym Compatibility

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/get_start.rst

This Python script demonstrates how to wrap a MetaDrive environment to ensure compatibility with older training frameworks that rely on the openai.gym interface. It utilizes the `createGymWrapper` utility provided by MetaDrive. Note that the return values for `step` differ slightly from gymnasium (no `truncate`).

```python
from metadrive.envs.metadrive_env import MetaDriveEnv
import gymnasium as gym
from metadrive.envs.gym_wrapper import createGymWrapper # import the wrapper

env = createGymWrapper(MetaDriveEnv)(config={"use_render": True}) # wrap the environment
obs = env.reset()
for i in range(1000):
    obs, reward, done, info = env.step(env.action_space.sample()) # the return value contains no truncate
    if done:
        env.reset()
env.close()
```

--------------------------------

### Python: Minimal Vehicle Control Example in MetaDrive

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/action.ipynb

This Python snippet demonstrates a minimal example of controlling a vehicle in the MetaDrive environment. It initializes an environment, spawns a new vehicle, and applies a continuous action to it over several steps, rendering the scene at each step. Dependencies include `metadrive.envs.metadrive_env.MetaDriveEnv`, `metadrive.component.vehicle.vehicle_type.DefaultVehicle`, and `metadrive.utils.doc_utils.generate_gif`.

```python
from metadrive.envs.metadrive_env import MetaDriveEnv
from metadrive.component.vehicle.vehicle_type import DefaultVehicle
from metadrive.utils.doc_utils import generate_gif

env=MetaDriveEnv(dict(map="S", traffic_density=0))
frames = []
try:
    env.reset()
    cfg=env.config["vehicle_config"]
    cfg["navigation"]=None # it doesn't need navigation system
    v = env.engine.spawn_object(DefaultVehicle, 
                                vehicle_config=cfg, 
                                position=[30,0], 
                                heading=0)
    for _ in range(100):
        v.before_step([0, 0.5])
        env.step([0,0])
        frame=env.render(mode="topdown", 
                         window=False,
                         screen_size=(800, 200),
                         camera_position=(60, 7))
        frames.append(frame)
except Exception as e:
    print(e)
    env.close()

# To generate a GIF from the frames:
# generate_gif(frames, "output.gif")

```

--------------------------------

### Run Manual Control Example from Command Line

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/action.ipynb

This bash command executes a MetaDrive example script that allows manual control of the agent in a single-agent environment. Pressing the 'T' key during runtime switches the driving mode to manual control, enabling interaction via the configured controller (e.g., keyboard).

```bash
# pressing T to switch the driving mode to manual control 
python -m metadrive.examples.drive_in_single_agent_env
```

--------------------------------

### Install Test Extras for panda3d-simplepbr

Source: https://github.com/metadriverse/metadrive/blob/main/metadrive/third_party/simplepbr/readme.md

Installs the panda3d-simplepbr package in editable mode along with its test dependencies. This setup is required for running the project's test suite.

```bash
pip install -e .[test]
```

--------------------------------

### Install PyTorch for CUDA

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/install.rst

Installs a specific version of PyTorch with CUDA support, required for advanced offscreen rendering.

```bash
conda install pytorch==1.12.1 torchvision==0.13.1 torchaudio==0.12.1 cudatoolkit=11.6 -c pytorch -c conda-forge
```

--------------------------------

### Run Generalization Environment Example (Bash)

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/rl_environments.ipynb

This command demonstrates how to run the Generalization environment from the command line using a specific observation type. It's a quick way to test the environment's basic functionality.

```bash
# args
# --observation: lidar, rgb_camera
python -m metadrive.examples.drive_in_single_agent_env --observation lidar
```

--------------------------------

### Install Latest Development Build

Source: https://github.com/metadriverse/metadrive/blob/main/metadrive/third_party/simplepbr/readme.md

Installs the latest development version of panda3d-simplepbr directly from its GitHub repository using pip. This is useful for testing the newest features or bug fixes.

```bash
pip install git+https://github.com/Moguri/panda3d-simplepbr.git
```

--------------------------------

### Example: Using ExtraEnvInputPolicy with Discrete Extra Input

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/action.ipynb

This Python example demonstrates how to configure and use ExtraEnvInputPolicy with a discrete space for extra input. It sets the extra input space to a Discrete(10), initializes MetaDriveEnv with this policy and action checking enabled, and then simulates steps, providing a dictionary containing both the 'action' and 'extra' input. It verifies that the extra input is correctly passed to the simulator.

```python
from metadrive.envs.metadrive_env import MetaDriveEnv
from metadrive.policy.env_input_policy import ExtraEnvInputPolicy
import gymnasium as gym
import random

ExtraEnvInputPolicy.set_extra_input_space(gym.spaces.Discrete(10))

env=MetaDriveEnv(dict(map="S",
                      agent_policy=ExtraEnvInputPolicy,
                      action_check=True,
                      log_level=50))
try:
    # run several episodes
    env.reset()
    for step in range(10):
        # simulation
        extra = random.randint(0, 9)
        action={"action": [0., 0.], "extra": extra}
        _,_,_,_,info = env.step(action)
        extra_ = env.engine.get_policy(env.agent.id).extra_input
        assert extra == extra_
        print("Extra info this step is: {}".format(extra))
finally:
    env.close()
```

--------------------------------

### Install Sphinx and Dependencies for Metadrive Docs

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/README.md

Installs the required Python packages for building the Metadrive documentation locally. This includes Sphinx, the Read the Docs theme, myst-nb for Jupyter Notebook integration, and sphinx-copybutton for code copying functionality.

```bash
pip install sphinx sphinx_rtd_theme myst-nb
pip install sphinx-copybutton
```

--------------------------------

### Integrate MetaDrive with Stable-Baselines3 for Training

Source: https://context7.com/metadriverse/metadrive/llms.txt

Demonstrates how to create a vectorized MetaDrive environment and train a PPO agent using Stable-Baselines3. Configures environment parameters like map, traffic density, and horizon. Includes setup for DummyVecEnv and VecMonitor.

```python
from stable_baselines3 import PPO
from stable_baselines3.common.vec_env import DummyVecEnv, VecMonitor
from metadrive.envs.metadrive_env import MetaDriveEnv

def make_env():
    return MetaDriveEnv(config={
        "use_render": False,
        "map": 4,
        "traffic_density": 0.1,
        "num_scenarios": 100,
        "horizon": 1000,
        "crash_vehicle_done": True,
    })

# Create vectorized environment
env = DummyVecEnv([make_env])
env = VecMonitor(env)

# Train PPO agent
model = PPO(
    "MlpPolicy",
    env,
    learning_rate=3e-4,
    n_steps=2048,
    batch_size=64,
    n_epochs=10,
    gamma=0.99,
    verbose=1,
)

# model.learn(total_timesteps=100000)
# model.save("metadrive_ppo")

```

--------------------------------

### Example of Engine Manager's before_step Method in Python

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/system_design.ipynb

This Python code illustrates the structure of the engine.before_step() method, showing how it iterates through registered managers and calls their respective before_step() methods. This pattern is consistent across engine.step() and engine.after_step().

```python
def before_step(self):
    for mgr in managers.values():
        # or mgr.step() / mgr.after_step() for engine.step() / engine.after_step(), respectively
        mgr.before_step()
```

--------------------------------

### Initialize MetaDrive Environment with Configuration

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/config_system.ipynb

Demonstrates how to initialize a MetaDrive environment with custom configuration settings, such as the number of scenarios and a starting seed. This is the primary method for customizing environment generation.

```python
from metadrive import MetaDriveEnv
config = dict(num_scenarios=200, start_seed=0)
env = MetaDriveEnv(config)
```

--------------------------------

### Import necessary libraries for MetaDrive multigoal intersection

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/multigoal_intersection.ipynb

Imports required libraries including numpy, create_gym_wrapper, MultiGoalIntersectionEnv, and mediapy for environment setup and visualization.

```python
import numpy as np
from metadrive.envs.gym_wrapper import create_gym_wrapper
from metadrive.envs.multigoal_intersection import MultiGoalIntersectionEnv
import mediapy as media

render = False
num_scenarios = 1000
start_seed = 100
```

--------------------------------

### Cross-reference Section in .rst from .ipynb

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/README.md

Shows how to link to a section titled 'Install MetaDrive' in an '.rst' file ('install.rst') from within a Jupyter Notebook or HTML context. This method uses an anchor tag with the HTML filename and section ID.

```html
<a href="install.html#install-metadrive">Install MetaDrive</a>
```

--------------------------------

### Metadrive Environment Initialization and Rendering Example

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/new_env.ipynb

This Python script demonstrates how to initialize and use the Metadrive environment. It sets up the environment with specific parameters, resets it multiple times to load different scenarios, renders the environment from a top-down perspective, and saves the resulting frames as a single image file named 'demo.png'.

```python
import logging
import cv2
from metadrive.envs.base_env import BaseEnv
from metadrive.manager.map_manager import MyMapManager
from metadrive.component.observation import DummyObservation
from metadrive.scenario.scenario_manager import ScenarioManager
from metadrive.component.pg_map.map_blocks import FirstPGBlock
from IPython.display import Image

# ... (previous class definition for MyEnv)

if __name__=="__main__":
    frames = []
    
    env=MyEnv(dict(use_render=False, 
                   manual_control=True, 
                   num_scenarios=4,
                   log_level=logging.CRITICAL))
    for i in range(4):
        
        o, info = env.reset(seed=i)
        print("Load map with shape: {}".format(info["current_map"]))
        frame=env.render(mode="topdown", 
                         window=False, 
                         scaling=3,
                         camera_position=(50, 0),
                         screen_size=(400, 400))
        frames.append(frame)
    cv2.imwrite("demo.png",  cv2.cvtColor(cv2.hconcat(frames), cv2.COLOR_RGB2BGR))
    env.close()

Image(open("demo.png", 'rb').read())
```

--------------------------------

### Configure and create the MultiGoalIntersectionEnv

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/multigoal_intersection.ipynb

Sets up the environment configuration, including rendering, manual control, horizon, traffic density, and multigoal intersection settings. It then creates a gym-wrapped environment instance.

```python
env_config = dict(
    use_render=render,
    manual_control=False,
    horizon=500,  # to speed up training

    traffic_density=0.06,
    
    use_multigoal_intersection=True,  # Set to False if want to use the same observation but with original PG scenarios.
    out_of_route_done=False,

    num_scenarios=num_scenarios,
    start_seed=start_seed,
    accident_prob=0.8,
    crash_vehicle_done=False,
    crash_object_done=False,
)

wrapped = create_gym_wrapper(MultiGoalIntersectionEnv)

env = wrapped(env_config)
```

--------------------------------

### Get Object Summary

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/scenario_description.ipynb

Retrieves a summary of a specific object within a scenario, using the Self-Driving Car (SDC) as an example. The summary includes the object's type, ID, track length, moving distance, and valid length. This requires the object's dictionary and its unique ID.

```python
# Get the summary of an object. Here we use the SDC.
sd_utils.ScenarioDescription.get_object_summary(
    object_dict=scenario.get_sdc_track(), 
    object_id=scenario['metadata']['sdc_id']
)
```

--------------------------------

### Run Custom Environment with Configured Timesteps (Python)

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/system_design.ipynb

This snippet demonstrates how to instantiate and run the `ExampleEnv` with custom `generate_timestep` and `recycle_timestep` values. It simulates environment steps, renders the top-down view, and records a GIF. The code includes error handling to ensure the environment is properly closed. Dependencies include `metadrive.envs.MetaDriveEnv` and `IPython.display` for output manipulation.

```python
# ===== Set parameters for ExampleManager ===== 
env = ExampleEnv(dict(generate_timestep=80,
                      recycle_timestep=200, 
                      map="S"))
try:
    env.reset()
    for _ in range(220):
        env.step([0, 0]) # ego car is static
        env.render(mode="topdown", 
                   window=False,
                   screen_size=(200, 250),
                   camera_position=(0, 20),
                   screen_record=True,
                   text={"Has vehicle": env.engine.managers["traffic_manager"].generated_v is not None,
                         "Timestep": env.episode_step})
    env.top_down_renderer.generate_gif()
finally:
    env.close()
    clear_output()
Image(open("demo.gif", 'rb').read())
```

--------------------------------

### Install CuPy and Cuda-Python

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/install.rst

Installs CuPy and Cuda-Python, which are necessary dependencies for utilizing CUDA acceleration with MetaDrive.

```bash
pip install cupy-cuda11x
conda install -c nvidia cuda-python
```

--------------------------------

### Initialize BaseEnv and Render Environment in Metadrive

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/new_env.ipynb

This snippet demonstrates how to initialize a basic Metadrive environment with a vehicle. It covers environment creation, stepping through actions, and rendering the environment using a top-down view, with options for screen recording or GIF generation. It also shows how to display the generated GIF.

```python
from metadrive.envs import BaseEnv
from metadrive.obs.observation_base import DummyObservation
import logging

class MyEnv(BaseEnv):

    def reward_function(self, agent):
        return 0, {}

    def cost_function(self, agent):
        return 0, {}

    def done_function(self, agent):
        return False, {}
    
    def get_single_observation(self):
        return DummyObservation()
        

if __name__=="__main__":
    # create env
    env=MyEnv(dict(use_render=False, # if you have a screen and OpenGL suppor, you can set use_render=True to use 3D rendering  
                   manual_control=True, # we usually manually control the car to test environment
                   log_level=logging.CRITICAL)) # suppress logging message
    env.reset()
    for i in range(20):
        
        # step
        obs, reward, termination, truncate, info = env.step(env.action_space.sample())
        
        # you can set window=True and remove generate_gif() if you have a screen.
        # Or just use 3D rendering and remove all stuff related to env.render()  
        frame=env.render(mode="topdown", 
                         window=False, # turn me on, if you have screen
                         screen_record=True, # turn me off, if a window can be poped up
                         screen_size=(200, 200))
    env.top_down_renderer.generate_gif()
    env.close()

from IPython.display import Image
Image(open("demo.gif", 'rb').read())
```

--------------------------------

### Install ROS2 Bridge for MetaDrive

Source: https://github.com/metadriverse/metadrive/blob/main/bridges/ros_bridge/README.md

Installs the necessary dependencies and builds the ROS2 bridge for MetaDrive. This includes setting up the ROS2 environment, installing pyzmq, and running colcon build. Ensure you have ROS2 Humble installed.

```bash
cd bridges/ros_bridge

source /opt/ros/${ROS_DISTRO}/setup.bash
sudo rosdep init 
pip install pyzmq  
rosdep update
rosdep install --from-paths src --ignore-src -y

colcon build
source install/setup.bash
```

--------------------------------

### Verify MetaDrive Installation

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/install.rst

Runs a script to check if MetaDrive is installed correctly and to assess its performance. It provides information about the default observation types.

```python
python -m metadrive.examples.profile_metadrive
```

--------------------------------

### Metadrive Environment Simulation with Custom Policy (Python)

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/system_design.ipynb

This snippet demonstrates running a Metadrive environment with the custom MovingExampleEnv. It simulates a scenario for 200 steps, renders the top-down view, and generates a GIF of the simulation.

```python
env = MovingExampleEnv(dict(map="O"))
try:
    env.reset()
    for _ in range(200):
        env.step([0, 0]) # ego car is static
        env.render(mode="topdown", 
                   window=False,
                   screen_size=(400, 400),
                   camera_position=(100, 7),
                   scaling=2,
                   screen_record=True,
                   text={"Has vehicle": bool(len(env.engine.traffic_manager.spawned_objects)),
                         "Timestep": env.episode_step})
    assert env
    env.top_down_renderer.generate_gif()
finally:
    env.close()
    clear_output()
Image(open("demo.gif", 'rb').read())
```

--------------------------------

### Setup and Use Main Camera for Image Observation in MetaDrive

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/obs.ipynb

This snippet demonstrates using the default main camera for image observations in MetaDrive. It configures the environment to use 'main_camera' as the image source and sets the window size for rendering. The code simulates agent steps, collects image frames from the main camera, and generates a GIF. Dependencies include MetaDrive, OpenCV, and IPython display.

```python
cfg=dict(image_observation=True, 
         vehicle_config=dict(image_source="main_camera"),
         norm_pixel=False,
         agent_policy=IDMPolicy, # drive with IDM policy
         show_terrain = not os.getenv('TEST_DOC'), # test
         window_size=(84, 60) if os.getenv('TEST_DOC') else (200, 100))

env=MetaDriveEnv(cfg)
frames = []
try:
    env.reset()
    for _ in range(1 if os.getenv('TEST_DOC') else 10000):
        # simulation
        o, r, d, _, _ = env.step([0,1])
        # rendering, the last one is the current frame
        ret=o["image"][..., -1]
        frames.append(ret[..., ::-1])
        if d:
            break
    generate_gif(frames if os.getenv('TEST_DOC') else frames[-300: -50])
finally:
    env.close()
```

--------------------------------

### Safe RL Environment (SafeMetaDriveEnv) - Python

Source: https://context7.com/metadriverse/metadrive/llms.txt

Illustrates the use of SafeMetaDriveEnv, an extension for safe RL research. This environment includes additional obstacles, tracks cumulative costs, and features relaxed termination conditions, allowing agents to learn from safety violations without immediate episode termination. The example shows setup and a basic simulation loop tracking reward and cost.

```python
from metadrive.envs.safe_metadrive_env import SafeMetaDriveEnv

# SafeMetaDriveEnv adds obstacles and tracks cumulative costs
env = SafeMetaDriveEnv(config={
    "use_render": False,
    "num_scenarios": 100,
    "accident_prob": 0.8,          # Probability of obstacles on each road block
    "traffic_density": 0.05,
    "crash_vehicle_done": False,   # Don't terminate on vehicle collision
    "crash_object_done": False,    # Don't terminate on object collision
    "horizon": 1000,

    # Cost configuration
    "crash_vehicle_cost": 1.0,
    "crash_object_cost": 1.0,
    "out_of_road_cost": 1.0,
})

obs, info = env.reset()
episode_cost = 0
episode_reward = 0

for step in range(1000):
    action = env.action_space.sample()
    obs, reward, terminated, truncated, info = env.step(action)

    episode_reward += reward
    episode_cost += info["cost"]

    if terminated or truncated:
        print(f"Episode completed:")
        print(f"  Total reward: {episode_reward:.2f}")
        print(f"  Total cost: {info['total_cost']:.2f}")
        print(f"  Route completion: {info.get('route_completion', 0):.2%}")
        break

env.close()
```

--------------------------------

### Install ROS2 Bridge

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/ros.rst

Steps to install the ROS2 bridge for MetaDrive. This involves setting up the ROS2 environment, installing dependencies like pyzmq, and building the bridge using colcon.

```bash
cd bridges/ros_bridge
source /opt/ros/${ROS_DISTRO}/setup.bash
sudo rosdep init
pip install pyzmq
rosdep update
rosdep install --from-paths src --ignore-src -y
colcon build
source install/setup.bash
```

--------------------------------

### Launch and Record with Top-down Renderer - Python

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/top_down_render.ipynb

Demonstrates launching the top-down renderer, stepping through an environment, recording frames, generating a GIF, and observing the renderer's state before and after environment reset. This snippet requires Metadrive and IPython.display.

```python
from metadrive.envs import MetaDriveEnv
from IPython.display import Image
from metadrive.utils.doc_utils import print_source, get_source
import cv2

env = MetaDriveEnv(dict(log_level=50))
env.reset()
for i in range(100):
    env.step([0,0])
    if i>=50:
        env.render(mode="topdown",
                   window=False,
                   screen_size=(400, 200),
                   screen_record=True,
                   text={"Step": i})
env.top_down_renderer.generate_gif()
print("Before reset the renderer is", env.top_down_renderer)
env.reset()
print("After reset the renderer is", env.top_down_renderer)

env.close()

Image(open("demo.gif", 'rb').read())
```

--------------------------------

### Install MetaDrive with CUDA Support

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/install.rst

Installs MetaDrive with support for advanced offscreen rendering using CUDA, enabling faster image-based data sampling. Requires CUDA Toolkit 12.0+, Torch, CuPy, and Cuda-Python.

```bash
pip install -e .[cuda]
# or
pip install -e metadrive-simulator[cuda]
```

--------------------------------

### Install panda3d-simplepbr Package

Source: https://github.com/metadriverse/metadrive/blob/main/metadrive/third_party/simplepbr/readme.md

Installs the panda3d-simplepbr package using pip. This is the standard method for adding the library to your Python environment.

```bash
pip install panda3d-simplepbr
```

--------------------------------

### Python: Run Simulation with Custom Manager and Render Top-Down View

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/system_design.ipynb

This Python code initializes a MetaDrive environment with a 'S' map and runs a simulation for 120 steps. It uses the custom ExampleManager to control vehicle generation and recycling. The simulation is rendered in a top-down view, with status information displayed, and finally saved as a GIF.

```python
env = ExampleEnv(dict(map="S"))
try:
    env.reset()
    for _ in range(120):
        env.step([0, 0]) # ego car is static
        env.render(mode="topdown", 
                   window=False,
                   screen_size=(200, 250),
                   camera_position=(20, 20),
                   screen_record=True,
                   text={"Has vehicle": env.engine.managers["exp_mgr"].generated_v is not None,
                         "Timestep": env.episode_step})
    env.top_down_renderer.generate_gif()
finally:
    env.close()
    clear_output()
Image(open("demo.gif", 'rb').read())

```

--------------------------------

### Verify MetaDrive Installation

Source: https://context7.com/metadriverse/metadrive/llms.txt

Verifies the MetaDrive installation by running a profiling script. This command should be executed from a directory that does not contain a 'metadrive' subfolder.

```python
# Run from a folder that doesn't have a 'metadrive' subfolder
python -m metadrive.examples.profile_metadrive
```

--------------------------------

### Install stable-baselines3 for MetaDrive

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/training.ipynb

Installs the stable-baselines3 library and its extra dependencies required for training RL agents with MetaDrive. This is a prerequisite for using stable-baselines3.

```python
%pip install stable-baselines3[extra]
```

--------------------------------

### Control Vehicle and Generate GIF in MetaDrive

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/action.ipynb

This Python example demonstrates controlling a vehicle in the MetaDrive environment using continuous actions. It initializes the `MetaDriveEnv`, resets the environment, and then steps through 300 frames, applying a continuous action `[0.5, 1]` (steering and throttle) in each step. The rendered frames are collected and used to generate a 'demo.gif' file.

```python
from metadrive.envs.metadrive_env import MetaDriveEnv
from metadrive.utils.doc_utils import generate_gif

env=MetaDriveEnv(dict(map="S",
                      log_level=50,
                      traffic_density=0))
try:
    frames = []
    # run several episodes
    env.reset()
    for step in range(300):
        # simulation
        _,_,_,_,info = env.step([0.5, 1])
        frame = env.render(mode="topdown", 
                          window=False,
                          screen_size=(800, 200),
                          camera_position=(60, 15))
        frames.append(frame)
    generate_gif(frames)
finally:
    env.close()
```

--------------------------------

### Verify Headless Installation

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/install.rst

Confirms that MetaDrive supports headless rendering by generating and comparing images from the agent observation and the internal rendering buffer. Supports checking different cameras and CUDA pipelines.

```python
python -m metadrive.examples.verify_headless_installation
python -m metadrive.examples.verify_headless_installation --camera [rgb/depth]
python -m metadrive.examples.verify_headless_installation --cuda
```

--------------------------------

### Setup and Use RGB Camera for Image Observation in MetaDrive

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/obs.ipynb

This snippet demonstrates how to set up an RGB camera for vision-based observations in MetaDrive. It involves configuring the environment to enable image observation, specifying the RGB camera as the image source, and defining sensor parameters. The code then simulates agent steps, collects image frames, and generates a GIF. Dependencies include MetaDrive, OpenCV, and IPython display.

```python
from metadrive.envs.metadrive_env import MetaDriveEnv
from metadrive.component.sensors.rgb_camera import RGBCamera
import cv2
from metadrive.policy.idm_policy import IDMPolicy
from IPython.display import Image
from metadrive.utils.doc_utils import generate_gif
import numpy as np
import os
sensor_size = (84, 60) if os.getenv('TEST_DOC') else (200, 100)

cfg=dict(image_observation=True, 
         vehicle_config=dict(image_source="rgb_camera"),
         sensors={"rgb_camera": (RGBCamera, *sensor_size)},
         stack_size=3,
         agent_policy=IDMPolicy # drive with IDM policy
        )

env=MetaDriveEnv(cfg)
frames = []
try:
    env.reset()
    for _ in range(1 if os.getenv('TEST_DOC') else 10000):
        # simulation
        o, r, d, _, _ = env.step([0,1])
        # rendering, the last one is the current frame
        ret=o["image"][..., -1]*255 # [0., 1.] to [0, 255]
        ret=ret.astype(np.uint8)
        frames.append(ret[..., ::-1])
        if d:
            break
    generate_gif(frames if os.getenv('TEST_DOC') else frames[-300:-50])
finally:
    env.close()
```

--------------------------------

### Verify MetaDrive Installation

Source: https://github.com/metadriverse/metadrive/blob/main/README.md

Runs a testing script to verify the successful installation of MetaDrive. It's recommended to run this in a directory without a sub-folder named 'metadrive'.

```bash
# Go to a folder where no sub-folder calls metadrive
python -m metadrive.examples.profile_metadrive
```

--------------------------------

### Configure and Run Metadrive with Custom Observation

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/obs.ipynb

This Python code demonstrates how to configure and run a Metadrive simulation using the custom `MyObservation` class. It sets up the environment with specified sensors (RGB, depth, semantic cameras) and the IDM policy. The simulation then steps through a series of frames, collecting and visualizing the combined image observations.

```python
from metadrive.utils.doc_utils import generate_gif
from IPython.display import Image

frames = []
cfg=dict(agent_policy=IDMPolicy, # drive with IDM policy
         agent_observation=MyObservation,
         image_observation=True,
         sensors={"rgb": (RGBCamera, *sensor_size),
                  "depth": (DepthCamera, *sensor_size),
                  "semantic": (SemanticCamera, *sensor_size)},
         log_level=50) # turn off log

env=MetaDriveEnv(cfg)
try:
    env.reset()
    print("Observation shape: \n", env.observation_space)
    for step in range(1 if os.getenv('TEST_DOC') else 1000):
        o, r, d, _, _ = env.step([0,1]) # simulation
        
        # visualize image observation
        o_1 = o["depth"][..., -1]
        o_1 = np.concatenate([o_1, o_1, o_1], axis=-1) # align channel
        o_2 = o["rgb"][..., -1]
        o_3 = o["semantic"][..., -1]
        ret = cv2.hconcat([o_1, o_2, o_3])*255
        ret=ret.astype(np.uint8)
        frames.append(ret[..., ::-1])
        if d:
            break
    generate_gif(frames if os.getenv('TEST_DOC') else frames[-300:-50]) # only show 250 frames
finally:
    env.close()

```

--------------------------------

### Verify CUDA Image Observation

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/install.rst

Verifies the installation of MetaDrive with CUDA support by running a script that benchmarks image collection pipelines. Allows testing with and without CUDA, and selecting different camera types.

```python
python verify_image_observation.py --cuda
python verify_image_observation.py --cuda --render
python verify_image_observation.py --cuda --camera [rgb/depth/semantic/main]
```

--------------------------------

### Spawn Object using spawn_object API in Python

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/system_design.ipynb

Demonstrates how to create an object instance using the `manager.spawn_object` API. This method is preferred over direct instantiation for performance optimizations and logging. It accepts keyword arguments for parameters and ensures reproducibility by setting random seeds.

```python
obj = self.spawn_object(object_class, parameter_1=p_1, parameter_2=p2)
# Equivalent to:
obj = object_class(parameter_1=p_1, parameter_2=p2)
```

--------------------------------

### Run simulation steps and collect frames

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/multigoal_intersection.ipynb

Resets the environment, takes steps using a predefined action, renders the scene, and collects frames. The loop continues until the episode is done, after which the environment is closed.

```python
frames = []

try:
    env.reset()
    while True:
        action = [0, 1]
        o, r, d, i = env.step(action)
        frame = env.render(mode="topdown")
        frames.append(frame)
        if d:
            break
finally:
    env.close()
```

--------------------------------

### Python: Implement Custom Vehicle Spawning and Recycling with ExampleManager

Source: https://github.com/metadriverse/metadrive/blob/main/documentation/source/system_design.ipynb

This Python code defines an ExampleManager that inherits from BaseManager. It overrides the before_step() and after_step() methods to spawn a vehicle at timestep 40 and recycle it at timestep 100, while also applying a left-turning action. This manager is then registered with the MetaDrive environment.

```python
from metadrive.envs import MetaDriveEnv
from metadrive.manager import BaseManager
from metadrive.component.vehicle.vehicle_type import DefaultVehicle
from IPython.display import clear_output, Image

class ExampleManager(BaseManager):
    def __init__(self):
        super(ExampleManager, self).__init__()
        self.generated_v = None
        self.generate_ts = 40
        self.recycle_ts = 100
        
    def before_step(self):
        if self.generated_v:
            self.generated_v.before_step([0.5, 0.4]) # set action
        

    def after_step(self, *args, **kwargs):
        if self.episode_step == self.generate_ts:
            self.generated_v = self.spawn_object(DefaultVehicle, 
                                  vehicle_config=dict(), 
                                  position=(10, 0), 
                                  heading=0)
        elif self.episode_step == self.recycle_ts:
            self.clear_objects([self.generated_v.id])
            self.generated_v = None
        elif self.generated_v:
            self.generated_v.after_step()

class ExampleEnv(MetaDriveEnv):

    def setup_engine(self):
        super(ExampleEnv, self).setup_engine()
        self.engine.register_manager("exp_mgr", ExampleManager())

```

--------------------------------

### Load and Replay Real-World Driving Scenarios with ScenarioEnv

Source: https://context7.com/metadriverse/metadrive/llms.txt

Demonstrates how to load and replay real-world driving scenarios from datasets like nuScenes using the ScenarioEnv. It configures environment parameters such as data directory, number of scenarios, and traffic reactivity. The example shows how to reset the environment, take steps with agent actions, and retrieve scenario-specific rewards and termination information.

```python
from metadrive.envs.scenario_env import ScenarioEnv
from metadrive.engine.asset_loader import AssetLoader

# Load scenarios from bundled nuScenes data
env = ScenarioEnv(config={
    "use_render": False,
    "data_directory": AssetLoader.file_path("nuscenes", unix_style=False),
    "num_scenarios": 3,
    "start_scenario_index": 0,
    "sequential_seed": True,        # Load scenarios in order
    "reactive_traffic": False,      # Set True for IDM-controlled traffic
    "no_traffic": False,
    "no_light": False,
    "horizon": 1000,

    # Scenario-specific rewards
    "success_reward": 5.0,
    "out_of_road_penalty": 5.0,
    "crash_vehicle_penalty": 1.0,
    "driving_reward": 1.0,
    "heading_penalty": 1.0,
    "lateral_penalty": 0.5,
    "max_lateral_dist": 4,          # Max lateral deviation before out-of-road
})

for scenario_idx in range(3):
    obs, info = env.reset(seed=scenario_idx)
    print(f"\nScenario {scenario_idx}:")

    for step in range(500):
        action = [0.5, 0.0]  # Gentle acceleration, no steering
        obs, reward, terminated, truncated, info = env.step(action)

        if terminated or truncated:
            print(f"  Steps: {step}")
            print(f"  Route completion: {info.get('route_completion', 0):.2%}")
            print(f"  Success: {info.get('arrive_dest', False)}")
            break

env.close()
```

--------------------------------

### Build Wheels for panda3d-simplepbr

Source: https://github.com/metadriverse/metadrive/blob/main/metadrive/third_party/simplepbr/readme.md

Builds distributable wheel packages for the panda3d-simplepbr project. This involves installing the 'build' package and then running the build script.

```bash
pip install --upgrade build

python -m build

```