Merge pull request #158 from ARISE-Initiative/v1.5-docs

V1.5 docs

docs/basicusage.md

@@ -0,0 +1,33 @@
+# Basic Usage
+
+## Running Standardized Environments
+**robosuite** offers a set of standardized manipulation tasks for benchmarking purposes. These pre-defined environments can be easily instantiated with the `make` function. The APIs we provide to interact with our environments are simple and similar to the ones used by [OpenAI Gym](https://github.com/openai/gym/). Below is a minimalistic example of how to interact with an environment.
+
+```python
+import numpy as np
+import robosuite as suite
+
+# create environment instance
+env = suite.make(
+    env_name="Lift", # try with other tasks like "Stack" and "Door"
+    robots="Panda",  # try with other robots like "Sawyer" and "Jaco"
+    has_renderer=True,
+    has_offscreen_renderer=False,
+    use_camera_obs=False,
+)
+
+# reset the environment
+env.reset()
+
+for i in range(1000):
+    action = np.random.randn(*env.action_spec[0].shape)
+    obs, reward, done, info = env.step(action)  # take action in the environment
+    env.render()  # render on display
+````
+
+This script above creates a simulated environment with the on-screen renderer, which is useful for visualization and qualitative evaluation. The `step()` function takes an `action` as input and returns a tuple of `(obs, reward, done, info)` where `obs` is an `OrderedDict` containing observations `[(name_string, np.array), ...]`, `reward` is the immediate reward obtained per step, `done` is a Boolean flag indicating if the episode has terminated and `info` is a dictionary which contains additional metadata.
+
+Many other parameters can be configured for each environment. They provide functionalities such as headless rendering, getting pixel observations, changing camera settings, using reward shaping, and adding extra low-level observations. Please refer to [Environment](modules/environments) modules and the [Environment class](simulation/environment) APIs for further details.
+
+Demo scripts that showcase various features of **robosuite** are available [here](demos). The purpose of each script and usage instructions can be found at the beginning of each file.
+

docs/changelog.md

@@ -0,0 +1,12 @@
+# Changelog
+
+
+
+## Version 1.5.0
+
+<div class="admonition warning">
+<p class="admonition-title">Breaking API changes</p>
+<div>
+    <ul>New controller design.</ul>
+</div>
+</div>

docs/conf.py

@@ -42,6 +42,11 @@
     "sphinx.ext.autodoc",
     "recommonmark",  # use Sphinx-1.4 or newer
     "nbsphinx",
+    "sphinx_togglebutton",
+]
+
+myst_enable_extensions = [
+    "dollarmath",
 ]
 
 mathjax_config = {

docs/demos.md

@@ -179,3 +179,50 @@ The `demo_renderers.py` script shows how to use different renderers with the sim
 $ python demo_renderers.py --renderer default
 ```
 The `--renderer` flag can be set to `mujoco` or `default(default)
+
+### Exporting to USD
+Exporting to USD allows users to render **robosuite** trajectories in external renderers such as NVIDIA Omniverse and Blender. In order to export to USD you must install the required dependencies for the exporter.
+```sh
+$ pip install usd-core pillow tqdm
+```
+Once the dependencies are installed, the USD exporter can be imported via `from robosuite.utils.usd import exporter`. The `USDExporter` class in the `exporter` module handles exporting all nessecary assets and USD files associated with a **robosuite** trajectory. 
+
+First, instantiate a **robosuite** environment. Each environment has an MjModel and MjData instance associated with it. These attributes can be retrieved using
+```python
+model = env.sim.model._model
+data = env.sim.data._data
+```
+Both `model` and `data` are used by the USD exporter. Once a robosuite environment is defined, create a `USDExporter` object with the following arguments.
+
+* `model` (required): an MjModel instance.
+* `max_geom`: Optional integer specifying the maximum number of geoms that
+can be rendered in the same scene. If None this will be chosen
+automatically based on the estimated maximum number of renderable
+geoms in the model.
+* `output_directory_name`: name of root directory to store outputted frames
+and assets generated by the USD renderer.
+and assets by the USD renderer.
+* `light_intensity`: default intensity of the lights in the external renderer.
+* `shareable`: use relative paths to assets instead of absolute paths to allow
+files to be shared across users.
+* `online`: set to true if using USD exporter for online rendering. This value
+is set to true when rendering with Isaac Sim. If online is set to true, shareable must be false.
+* `framerate`: framerate of the exported scene when rendered
+* `camera_names`: list of fixed cameras defined in the mujoco model to render.
+* `stage`: predefined stage to add objects in the scene to.
+* `verbose`: decides whether to print updates.
+
+`USDExporter` is adapted from [MuJoCo](https://github.com/google-deepmind/mujoco). In order to add a new frame in the outputted USD trajectory, call `update_scene` in the `exporter` module. 
+
+```python
+exp = exporter.USDExporter(model=model, output_directory_name="usd_demo")
+exp.update_scene(data)
+```
+
+This updates all geoms in the scene with their current poses from simulation. To save a USD trajectory, use the `save_scene` method.
+
+```python
+exp.save_scene(filetype="usd")
+```
+
+Users are able to save scenes as .usd, .usda, or .usdc files. For a more comprehensive example of the USD renderer, please refer to the [`demo_usd_export.py`]() script. This demonstration allows users to teleoperate a robot with a device (i.e. keyboard or spacemouse) and save the collected trajectory as a USD file. 

docs/index.rst

@@ -12,7 +12,7 @@ Welcome to robosuite's documentation!
 
    overview
    installation
-   quickstart
+   basicusage
    demos
 
 .. toctree::
@@ -21,7 +21,7 @@ Welcome to robosuite's documentation!
 
    modules/overview
    modules/robots
-   modules/controllers.ipynb
+   modules/controllers
    modules/objects
    modules/environments
    modules/sensors
@@ -30,6 +30,13 @@ Welcome to robosuite's documentation!
 
 .. toctree::
    :maxdepth: 1
+   :caption: Tutorials
+
+   tutorials/add_controller
+   tutorials/add_environment
+
+.. toctree::
+   :maxdepth: 3
    :caption: Simulation API
 
    simulation/robot
@@ -67,6 +74,7 @@ Welcome to robosuite's documentation!
    :caption: Miscellaneous
 
    references
+   changelog
    acknowledgement
 
 Indices and tables

docs/modeling/arena.rst

@@ -13,3 +13,55 @@ Base Arena
   .. automethod:: __init__
   .. automethod:: set_origin
   .. automethod:: set_camera
+
+Empty Arena
+-----------
+
+.. autoclass:: robosuite.models.arenas.empty_arena.EmptyArena
+
+  .. automethod:: __init__
+
+Bins Arena
+----------
+
+.. autoclass:: robosuite.models.arenas.bins_arena.BinsArena
+
+  .. automethod:: __init__
+  .. automethod:: configure_location
+
+Pegs Arena
+----------
+
+.. autoclass:: robosuite.models.arenas.pegs_arena.PegsArena
+
+  .. automethod:: __init__
+
+Table Arena
+-----------
+
+.. autoclass:: robosuite.models.arenas.table_arena.TableArena
+
+  .. automethod:: __init__
+  .. automethod:: configure_location
+  .. autoproperty:: table_top_abs
+
+Wipe Arena
+----------
+
+.. autoclass:: robosuite.models.arenas.wipe_arena.WipeArena
+
+  .. automethod:: __init__
+  .. automethod:: configure_location
+  .. automethod:: reset_arena
+  .. automethod:: sample_start_pos
+  .. automethod:: sample_path_pos
+
+MultiTable Arena
+----------------
+
+.. autoclass:: robosuite.models.arenas.multi_table_arena.MultiTableArena
+
+  .. automethod:: __init__
+  .. automethod:: _add_table
+  .. automethod:: configure_location
+  .. automethod:: _postprocess_arena

docs/modeling/robot_model.rst

@@ -12,6 +12,9 @@ file and also contains relevant hard-coded information from that XML. This repre
   .. automethod:: set_base_ori
   .. automethod:: set_joint_attribute
   .. automethod:: add_base
+  .. automethod:: add_mount
+  .. automethod:: add_mobile_base
+  .. automethod:: add_leg_base
   .. autoproperty:: dof
   .. autoproperty:: default_base
   .. autoproperty:: default_controller_config