{"id":13840758,"url":"https://github.com/openai/mujoco-worldgen","last_synced_at":"2025-04-04T17:09:38.892Z","repository":{"id":50666031,"uuid":"203660786","full_name":"openai/mujoco-worldgen","owner":"openai","description":"Automatic object XML generation for Mujoco","archived":false,"fork":false,"pushed_at":"2024-07-26T16:20:06.000Z","size":90,"stargazers_count":541,"open_issues_count":12,"forks_count":111,"subscribers_count":143,"default_branch":"master","last_synced_at":"2025-03-28T16:09:17.445Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/openai.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-08-21T20:38:14.000Z","updated_at":"2025-03-26T11:29:26.000Z","dependencies_parsed_at":"2024-04-12T17:38:42.543Z","dependency_job_id":"987ffa4c-0fca-4b0c-82b5-35b398cffb19","html_url":"https://github.com/openai/mujoco-worldgen","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openai%2Fmujoco-worldgen","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openai%2Fmujoco-worldgen/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openai%2Fmujoco-worldgen/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/openai%2Fmujoco-worldgen/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/openai","download_url":"https://codeload.github.com/openai/mujoco-worldgen/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217221,"owners_count":20903009,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T17:00:55.148Z","updated_at":"2025-04-04T17:09:38.862Z","avatar_url":"https://github.com/openai.png","language":"Python","funding_links":[],"categories":["[MuJoCo](https://mujoco.org)"],"sub_categories":[],"readme":"**Status:** Archive (code is provided as-is, no updates expected)\n\n# Worldgen: Randomized MuJoCo environments\n\nWorldgen allows users to generate complex, heavily randomized environments environments. Examples of such environments can be found in the `examples` folder.\n\nActions in `action_space` are all actuators of objects added during world building. Not all objects will have actuators, but some do (e.g. `ObjFromXML('particle')` and `ObjFromXML('particle_hinge')`). You can examine the meaning of a given action by looking at the xml file of the object in `assets/xmls/.../main.xml`\n\nObservation spaces are inferred based on the outputs of the `get_obs` function in an `Env` object (`Env` class is defined in `mujoco_worldgen/env.py`.\n\n## Installation\n\nThis repository requires the MuJoCo physics engine (the repository has been tested with MuJoCo 1.50). To install MuJoCo, follow the instructions in the [mujoco-py](https://github.com/openai/mujoco-py/tree/1.50.1.0) repository.\n\n```\n    pip install -r requirements.txt\n    pip install -e .\n```\n\nThis repository has been used on Mac OS X and Ubuntu 16.04 with Python 3.6\n\n## Walkthrough\n\n### Initial steps\n\nLet’s analyze an example of one such generation.  First we create the `WorldParams`:\n\n```\n    world_params = WorldParams(size=(5, 5, 3.5))\n```\n\nThis defines the global properties of our generated world.\nMetric units used in worldgen are meters, kilograms, and angles are given in radians: `[-pi, pi]`. \nThe following are all optional paramaters with defaults:\n\n-  `size`: The size of the space available for placing objects. (Default: `(10., 10., 2.5)`)\n-  `num_substeps`: The number of physics substeps to perform within every call to `step()`. (Default: `1`)\n-  `randomize_light`: Whether to randomize the lighting conditions. (Default: `False`)\n-  `randomize_material`: Whether to randomize the materials that are applied to objects. (Default: `False`)\n-  `placement_margin`: The minimum distance between placed objects. (Default: `0.0`)\n-  `show_outer_bounds`: Whether to visualize the outer bounds. (Default: `False`)\n\nThen, we create a builder. The `WorldBuilder` constructor takes a `WorldParams` object and `seed`, which is used for randomization:\n\n```\n\tbuilder = WorldBuilder(world_params, seed)\n```\n\n### Placing objects\n\nHere's an example of adding geometries to our world:\n\n```\n    # Create a floor\n    floor = Floor()\n\n    # Load geometries from XML, and add to floor\n    robot = ObjFromXML(\"particle\")\n    floor.append(robot)\n    sphere = ObjFromXML(\"sphere\")\n    floor.append(sphere)\n\n    # Create a primitive geometry, and add to floor\n    box = Geom('box')\n    floor.append(box)\n\n    # Add the root floor to the builder\n    builder.append(floor)\n```\n\nThe `append()` function allows to specify a placement indicator (Usually “top” or “inside”).\nPlacements are spaces we’re able to place objects. \nPlacements are always world-aligned rectangular prisms, which objects can be oriented within.  All objects within a placement align along the bottom (and are positioned with X,Y coordinates).\nIf there are multiple placements for a given name (e.g. “inside\\_0”, “inside\\_1”, …) then we choose one at random.\nThe default placement name is “top”. \n\nTo customize the placement position:\n\n```\n    obj.append(child_obj, placement_name=\"top\", placement_xy=None)\n```\n\n`placement_xy` is None if you want the world generation algorithm to randomly place it.\nOtherwise it is an X, Y pair where both are within `[0.0, 1.0]`.\nThe object will be placed within the bounds, scaled by its size.\n*Note:* this is because the size of the placement (e.g. table) might not\nbe known until generation time. To add some more objects:\n\n```\n    obj.append(child_obj, 'top', (0.5, 1))  # placed in the center of the back\n    obj.append(child_obj, 'top', (0.5, 0.5))  # placed in the center\n    obj.append(child_obj, 'top', (0, 0))  # placed in the lower left corner\n```\n\n### Geoms\n\nThere are several kinds of primitive geoms: “box”, “sphere”, “cylinder”.\nWe can specify the size of a geom by providing a second parameter: `Geom(\"box\", (0.1, 0.2, 0.3))` which would result in box of size 10cm x 20cm x 30cm.\nFor a cube: `Geom(\"box\", 0.25)` results in “box” of size 25cm x 25cm x 25cm.\nMoreover, we can provide a range to sample a random size box: `Geom(\"box\", (0.1, 0.2, 0.3), (1.1, 1.2, 1.3))`.\nSize of this box would be random between 10cm x 20cm x 30cm and 1.1m x 1.2m x 1.3m.\n\n### Sites\nYou can create sites - static markers on an object - by calling `obj.mark()`. The current position of all created sites is stored in the `sim` object of the worldgen environment. For more information on sites, check out the `mark` function in the `Obj` class defined in `mujoco_worldgen/objs/obj.py`\n\nExample usage:\n```\n# Create a floor and a box\nfloor = Floor()\nbox = Geom('box')\n\n# Mark sites on floor and box\nfloor.mark(mark_name='floor_site', relative_xyz=(0.2, 0.2, 0))\nbox.mark(mark_name='box_site', relative_xyz=(0, 0, 0.5))\n\n# Add box to floor, add the floor to the builder, and create a sim with the builder\nfloor.append(box)\nbuilder.append(floor)\nsim = builder.get_sim()\n\n# Get the current position of the floor site and the box site\nfloor_site_pos = sim.data.site_xpos[sim.model.site_name2id('floor_site')]\nbox_site_pos = sim.data.site_xpos[sim.model.site_name2id('box_site')]\n```\n\n### Environments\n\nYou can create new environments with Worldgen by subclassing the `Env` class and defining the following methods:\n\n- `_get_sim`\n- `_get_obs`\n- `_get_reward` : You can also use a reward wrapper instead of defining this.\n\nYou can see two examples in the `examples` folder - the `simple_particle` environment and the `particle_gather` environment.\nYou can test out environments using the `/bin/examine` script, providing either a python script defining the `make_env` or a jsonnet file.\n\n```\n    ./bin/examine.py examples/simple_particle.py\n```\n\n```\n    ./bin/examine.py examples/example_env_examine.jsonnet\n```\n\n## Acknowledgements\n\nCredits to Alex Ray for writing the original version of Worldgen that OpenAI was using internally - the majority of the code in this repository has been copied over from the original Worldgen with minor changes.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenai%2Fmujoco-worldgen","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fopenai%2Fmujoco-worldgen","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fopenai%2Fmujoco-worldgen/lists"}