Terrain Generation#

class go2sim.GeometryType(str, Enum)#

Enumeration of supported geometric shapes for the terrain generator.

PLANE = "plane"#

SPHERE = "sphere"#

CAPSULE = "capsule"#

ELLIPSOID = "ellipsoid"#

CYLINDER = "cylinder"#

BOX = "box"#

class go2sim.TerrainGenerator#

A utility class to dynamically generate and modify MuJoCo XML scene files for the robot simulation environment. In addition to raw geometry, the generator supports textured geometries and ArUco markers backed by an internal ResourceManager that manages imported texture assets.

ROBOT: str = "go2"#: The identifier of the robot model.

BASE_DIR: pathlib.Path#: The root directory of the module.

PUBLIC_RESOURCES_DIR: pathlib.Path#: The directory containing user-facing resources (e.g. textures) that may be imported into a scene. Backs the public resources manager.

INTERNAL_RESOURCES_DIR: pathlib.Path#: The directory containing internal resources, including the base and generated scene XML files.

GENERATED_SCENE_PATH: pathlib.Path#: The file path where the generated scene is saved.

BASE_SCENE_PATH: pathlib.Path#: The file path to the baseline XML scene.

resources: ResourceManager#: A ResourceManager rooted at PUBLIC_RESOURCES_DIR, used to import and validate texture files referenced by add_textured_geometry().

__init__() → None#: Initializes the TerrainGenerator, setting up the public resources manager, parsing the generated and base XML scenes, and setting up the root XML element pointers.

add_geometry(position: List[float] = [1.0, 0.0, 0.0], euler: List[float] = [0.0, 0.0, 0.0], size: List[float] = [0.1, 0.1, 0.1], geo_type: GeometryType = GeometryType.BOX) → None#

Adds a generic, untextured geometry object to the MuJoCo worldbody.

Parameters:

position (List[float]) – The [x, y, z] coordinates of the geometry. Defaults to [1.0, 0.0, 0.0].
euler (List[float]) – The Euler angles [roll, pitch, yaw] for rotation. Defaults to [0.0, 0.0, 0.0].
size (List[float]) – The full size [x, y, z] of the geometry (halved internally for MuJoCo). Defaults to [0.1, 0.1, 0.1].
geo_type (GeometryType) – The type of geometry to add. Defaults to GeometryType.BOX.

add_textured_geometry(texture_path: str | pathlib.Path, position: List[float] = [0.0, 0.0, 0.0], euler: List[float] = [0.0, 0.0, 0.0], size: List[float] = [0.1, 0.1, 0.1], geo_type: GeometryType = GeometryType.BOX) → None#

Adds a geometry object textured with a previously-imported texture. The texture and its backing material are registered as scene assets on first use and reused on subsequent calls with the same texture path.

Parameters:

texture_path (str | pathlib.Path) – The path to the texture, relative to PUBLIC_RESOURCES_DIR. Must already exist via resources (e.g. imported with resources.import_texture).
position (List[float]) – The [x, y, z] coordinates of the geometry. Defaults to [0.0, 0.0, 0.0].
euler (List[float]) – The Euler angles [roll, pitch, yaw] for rotation. Defaults to [0.0, 0.0, 0.0].
size (List[float]) – The full size [x, y, z] of the geometry (halved internally for MuJoCo). Defaults to [0.1, 0.1, 0.1].
geo_type (GeometryType) – The type of geometry to add. Defaults to GeometryType.BOX.

Raises:

FileNotFoundError – If texture_path has not been imported into resources.

add_stairs(init_pos: List[float] = [1.0, 0.0, 0.0], yaw: float = 0.0, width: float = 0.2, height: float = 0.15, length: float = 1.5, stair_nums: int = 10) → None#

Generates a sequence of ascending stair geometries.

Parameters:

init_pos (List[float]) – The starting [x, y, z] position of the stair sequence. Defaults to [1.0, 0.0, 0.0].
yaw (float) – The yaw angle rotation of the stair sequence in radians. Defaults to 0.0.
width (float) – The tread depth (width along the walking path) of each stair. Defaults to 0.2.
height (float) – The vertical riser height of each stair. Defaults to 0.15.
length (float) – The span length of each stair perpendicular to the walking path. Defaults to 1.5.
stair_nums (int) – The total number of stairs to generate. Defaults to 10.

add_suspend_stairs(init_pos: List[float] = [1.0, 0.0, 0.0], yaw: float = 1.0, width: float = 0.2, height: float = 0.15, length: float = 1.5, gap: float = 0.1, stair_nums: int = 10) → None#

Generates a sequence of suspended (floating) stair geometries with vertical gaps.

Parameters:

init_pos (List[float]) – The starting [x, y, z] position of the stair sequence. Defaults to [1.0, 0.0, 0.0].
yaw (float) – The yaw angle rotation of the stair sequence in radians. Defaults to 1.0.
width (float) – The tread depth of each suspended stair. Defaults to 0.2.
height (float) – The overall vertical displacement between stairs. Defaults to 0.15.
length (float) – The span length of each stair. Defaults to 1.5.
gap (float) – The vertical gap distance removing volume from the riser area. Defaults to 0.1.
stair_nums (int) – The total number of suspended stairs to generate. Defaults to 10.

add_rough_ground(init_pos: List[float] = [1.0, 0.0, 0.0], euler: List[float] = [0.0, -0.0, 0.0], nums: List[int] = [10, 10], box_size: List[float] = [0.5, 0.5, 0.5], box_euler: List[float] = [0.0, 0.0, 0.0], separation: List[float] = [0.2, 0.2], box_size_rand: List[float] = [0.05, 0.05, 0.05], box_euler_rand: List[float] = [0.2, 0.2, 0.2], separation_rand: List[float] = [0.05, 0.05]) → None#

Generates a randomized rough terrain grid composed of multiple box geometries.

Parameters:

init_pos (List[float]) – The starting [x, y, z] baseline position. Defaults to [1.0, 0.0, 0.0].
euler (List[float]) – The base Euler angles [roll, pitch, yaw] for the entire grid. Defaults to [0.0, -0.0, 0.0].
nums (List[int]) – A list representing the [x_count, y_count] of boxes in the grid. Defaults to [10, 10].
box_size (List[float]) – The baseline [x, y, z] size for each terrain box. Defaults to [0.5, 0.5, 0.5].
box_euler (List[float]) – The baseline Euler orientation for each terrain box. Defaults to [0.0, 0.0, 0.0].
separation (List[float]) – The baseline [x, y] spacing between box centers. Defaults to [0.2, 0.2].
box_size_rand (List[float]) – The randomization limits for the size of each box. Defaults to [0.05, 0.05, 0.05].
box_euler_rand (List[float]) – The randomization limits for the orientation of each box. Defaults to [0.2, 0.2, 0.2].
separation_rand (List[float]) – The randomization limits for the spacing between boxes. Defaults to [0.05, 0.05].

add_aruco_marker(position: List[float] = [1.0, 0.0, 0.0], euler: List[float] = [0.0, 0.0, 0.0], size: List[float] = [0.1, 0.1, 0.1], marker_num: int = 0) → None#

Adds a textured ArUco marker box to the scene. The marker texture is resolved internally (markers/marker_7x7_{marker_num}.png) and its material asset is registered automatically.

Parameters:

position (List[float]) – The [x, y, z] coordinates of the marker. Defaults to [1.0, 0.0, 0.0].
euler (List[float]) – The Euler angles [roll, pitch, yaw] for rotation. Defaults to [0.0, 0.0, 0.0].
size (List[float]) – The full size [x, y, z] of the marker geometry. Defaults to [0.1, 0.1, 0.1].
marker_num (int) – The ArUco marker ID (must be between 0 and 20 inclusive). Defaults to 0.

Raises:

ValueError – If marker_num falls outside the 0-20 range.

save() → None#: Formats and saves the current state of the generated XML scene to the active path.

reset_to_base(reset_resources: bool = False) → None#

Overwrites the generated scene with the clean baseline scene and resets internal XML pointers.

Parameters:: reset_resources (bool) – If True, also deletes all imported resources under PUBLIC_RESOURCES_DIR via resources.remove_all(). Defaults to False.

load_scene_from_path(absolute_path: str | pathlib.Path) → None#

Loads an external MuJoCo XML scene, sets it as the active generation target, and updates internal pointers.

Parameters:: absolute_path (str | pathlib.Path) – The absolute path to the target XML file.
Raises:: FileNotFoundError – If the provided path does not exist.

export_scene_to_directory(absolute_path: str | pathlib.Path) → None#

Exports the current generated scene tree as ‘scene.xml’ to a specified directory.

Parameters:: absolute_path (str | pathlib.Path) – The path to the destination directory.
Raises:: FileNotFoundError – If the destination directory does not exist.

Resource Management#

exception go2sim.ResourceError#: Raised for resource-management errors that are not better represented by a built-in exception, such as unsupported file formats or attempts to resolve a path outside the managed resource root.

class go2sim.ResourceManager#

Manages a root directory of importable resource files (currently texture images) used by TerrainGenerator. Accessible on a generator instance via its TerrainGenerator.resources property. All relative paths passed to its methods are resolved against, and confined to, the manager’s root directory.

SUPPORTED_IMAGE_TYPES: set[str] = {".png"}#: The set of file extensions accepted by import_texture().

__init__(resources_root: pathlib.Path) → None#

Initializes the manager, creating resources_root on disk if it does not already exist.

Parameters:: resources_root (pathlib.Path) – The directory this manager is rooted at.

property root: pathlib.Path#: The resolved root directory managed by this instance.

import_texture(src: str | pathlib.Path, dest_folder: str = '') → pathlib.Path#

Copies a texture file from an arbitrary source path into the managed resource root, under an optional destination subfolder.

Parameters:

src (str | pathlib.Path) – The path to the source image file to import.
dest_folder (str) – The subfolder, relative to the resource root, to copy the file into. Defaults to the root itself.

Returns:

The path of the imported file, relative to the resource root.

Return type:

pathlib.Path

Raises:

FileNotFoundError – If src does not exist.
ResourceError – If src has an unsupported file extension (see SUPPORTED_IMAGE_TYPES).

add_folder(relative_path: str | pathlib.Path) → None#

Creates a folder (and any missing parent folders) under the resource root.

Parameters:: relative_path (str | pathlib.Path) – The folder path, relative to the resource root, to create.

remove_folder(relative_path: str | pathlib.Path, recursive: bool = True) → None#

Removes a folder under the resource root.

Parameters:

relative_path (str | pathlib.Path) – The folder path, relative to the resource root, to remove.
recursive (bool) – If True, removes the folder and all of its contents. If False, only removes the folder if it is empty. Defaults to True.

Raises:

FileNotFoundError – If the folder does not exist.
ResourceError – If the path is not a directory, or if recursive is False and the folder is not empty.

remove_file(relative_path: str | pathlib.Path) → None#

Removes a single file under the resource root.

Parameters:

relative_path (str | pathlib.Path) – The file path, relative to the resource root, to remove.

Raises:

FileNotFoundError – If the file does not exist.
ResourceError – If the path is not a file.

remove_all() → None#: Deletes the entire resource root directory and recreates it empty.

list_dirs(relative_path: str | pathlib.Path = '') → None#

Prints a tree view of the contents of a directory under the resource root (defaults to the root itself) to stdout. Directories are listed before files at each level, sorted alphabetically.

Parameters:

relative_path (str | pathlib.Path) – The directory to list, relative to the resource root. Defaults to the resource root.

Raises:

FileNotFoundError – If the directory does not exist.
NotADirectoryError – If the path is not a directory.

exists(relative_path: str | pathlib.Path = '') → bool#

Checks whether a given path exists under the resource root.

Parameters:: relative_path (str | pathlib.Path) – The path to check, relative to the resource root.
Returns:: True if the path exists and lies within the resource root, False otherwise (including if the path would resolve outside the root).
Return type:: bool

On this page