Terrain#

class genesis_forge.managers.TerrainManager(env: GenesisEnv, terrain_attr: str = 'terrain')[source]#

Bases: BaseManager

Provides useful functions for the environment terrain. The manager maps out the sizes and heights of the terrain and subterrain. This allows your environment to calculate the robot’s height above rough terrain. You can also generate random positions on the terrain or subterrain to place your robots on reset.

Parameters:

env – The environment instance.
terrain_attr – The attribute name of the terrain in the environment.

Example:

class MyEnv(ManagedEnvironment):
    def __init__(self, *args, **kwargs):
        super().__init__(*args, **kwargs)

        self.scene = gs.Scene()

        # Add terrain
        self.terrain = self.scene.add_entity(
            morph=gs.morphs.Terrain(
                n_subterrains=(2, 2),
                subterrain_size=(25, 25),
                subterrain_types=[
                    ["flat_terrain", "random_uniform_terrain"],
                    ["discrete_obstacles_terrain", "pyramid_stairs_terrain"],
                ],
            ),
        )

    def config(self):
        self.terrain_manager = TerrainManager(
            self,
            terrain_attr="terrain",
        )

     def reset(self, envs_idx: list[int] = None) -> tuple[torch.Tensor, dict[str, Any]]:
        # Randomize positions on the terrain
        pos = self.terrain_manager.generate_random_env_pos(
            envs_idx=envs_idx,
            subterrain="flat_terrain",
            height_offset=0.15,
        )
        self.robot.set_pos(pos, envs_idx=envs_idx)

build()[source]#: Cache the terrain height field

generate_random_env_pos(envs_idx: list[int] | torch.Tensor | None = None, usable_ratio: float = 0.5, subterrain: str | None = None, height_offset: float = 0.0001) → torch.Tensor[source]#

Generate one X/Y/Z position on the terrain for each environment. The X & Y positions will be random points and the Z position will be at the approximate terrain height at that point.

Parameters:

envs_idx – The indices of the environments to generate positions for. If None, positions will be generated for all environments. Can be a list of ints or a torch.Tensor for better performance.
usable_ratio – How much of the terrain/subterrain area should be used for random positions. For example, 0.25 will only generate positions within the center 25% of the area of the terrain/subterrain. This helps avoid placing things right on th edge of the terrain/subterrain.
subterrain – The subterrain to generate positions for. If None, positions will be generated for the entire terrain.
height_offset – The offset to add to the terrain height.

Returns:

The position tensor of shape (1, 3)

generate_random_positions(num: int | None = None, usable_ratio: float = 0.5, subterrain: str | None = None, height_offset: float = 0.0001, output: torch.Tensor | None = None, out_idx: torch.Tensor | list[int] | None = None) → torch.Tensor[source]#

Distribute X/Y/Z positions across the terrain or subterrain. The X & Y positions will be random points and the Z position will be at the approximate terrain height at that point.

Parameters:

num – The number of positions to generate. Not necessary if output is provided
output – The position tensor to update in-place.
out_idx – The indices of the output position tensor to update. Can be a list of ints or a torch.Tensor for better performance.
usable_ratio – How much of the terrain/subterrain area should be used for random positions. For example, 0.25 will only generate positions within the center 25% of the area of the terrain/subterrain. This helps avoid placing things right on th edge of the terrain/subterrain.
subterrain – The subterrain to generate positions for. If None, positions will be generated for the entire terrain.
height_offset – The offset to add to the terrain height. Since the height is approximate, this can prevent items being placed below the terrain.

Returns:

The positions tensor of shape (num, 3)

get_bounds(subterrain: str | None = None) → tuple[float, float, float, float][source]#: Get the bounds of the terrain, or subterrain

get_terrain_height(x: torch.Tensor, y: torch.Tensor) → torch.Tensor[source]#

Get interpolated terrain height at world coordinates (x, y).

Parameters:

x – Tensor of shape (n_envs,)
y – Tensor of shape (n_envs,)

Returns:

Heights in the torch.Tensor of shape (n_envs,)

reset(envs_idx: list[int] | None = None)#: One or more environments have been reset

step()#: Called when the environment is stepped