diff --git a/docs/source/contributing/robots.md b/docs/source/contributing/robots.md index 45e47be2f..f9aaffc7f 100644 --- a/docs/source/contributing/robots.md +++ b/docs/source/contributing/robots.md @@ -1,12 +1,12 @@ # Robots -To add a new robot, you can follow any of the existing robots built already as templates in ManiSkill. We also highly recommend that you read through [custom robot tutorial](../user_guide/tutorials/custom_robots.md) to learn how to make new robots and tune them. +To add a new robot, you can follow any of the existing robots built already as templates in ManiSkill. We also highly recommend that you read through the [custom robot tutorial](../user_guide/tutorials/custom_robots.md) to learn how to make new robots and tune them. ManiSkill is a supporter of open-source and we encourage you to make contributions to help grow our list of robots in simulation! ## Contributing the Robot to ManiSkill -We recommend first opening an issue on our GitHub about your interest in adding a new robot as to not conflict with others and to consolidate information. Once done our maintainers can give a go ahead. +We recommend first opening an issue on our GitHub about your interest in adding a new robot as to not conflict with others and to consolidate information. Once done, our maintainers can give a go ahead. In your pull request, we ask you to do the following: - The robot / agent class code should be placed in `mani_skill/agents//your_robot.py`. If you want to re-use an agent class (e.g. as done with the Allegro hand robot and the Panda robot) you can create a folder that groups all the different agent classes together. diff --git a/docs/source/contributing/tasks.md b/docs/source/contributing/tasks.md index 12b4f7883..685306b19 100644 --- a/docs/source/contributing/tasks.md +++ b/docs/source/contributing/tasks.md @@ -56,7 +56,7 @@ class YourEnv(BaseEnv): Whenever possible, task code should be written in batch mode (assuming all data in and out are batched by the number of parallel environments). This generally ensures that the task is then GPU simulatable, which is of great benefit to workflows that leverage sim data collection at scale. -GPU simulation also entails tuning the GPU simulation configurations. You can opt to do two ways, dynamic or fix GPU simulation configurations. +GPU simulation also entails tuning the GPU simulation configurations. You can opt to do two ways, dynamic or fixed GPU simulation configurations. A version of fixed configurations can be seen in `mani_skill/envs/tasks/push_cube.py` which defines the default diff --git a/docs/source/user_guide/additional_resources/performance_benchmarking.md b/docs/source/user_guide/additional_resources/performance_benchmarking.md index 5683a0573..06be9628b 100644 --- a/docs/source/user_guide/additional_resources/performance_benchmarking.md +++ b/docs/source/user_guide/additional_resources/performance_benchmarking.md @@ -2,7 +2,7 @@ This page documents code and results of benchmarking various robotics simulators on a number of dimensions. It is still a WIP as we write more fair benchmarking environments for other simulators. Given the number of factors that impact simulation speed and rendering (e.g number of objects, geometry complexity etc.) trends that appear in results in this page may not necessarily be the case on some environments. -Currently we just compare ManiSkill and [Isaac Lab](https://github.com/isaac-sim/IsaacLab) on one task, Cartpole Balancing (control). For details on benchmarking methodology see [this section](#benchmarking-detailsmethodology) +Currently we just compare ManiSkill to [Isaac Lab](https://github.com/isaac-sim/IsaacLab) on one task, Cartpole Balancing (control). For details on benchmarking methodology see [this section](#benchmarking-detailsmethodology) Raw benchmark results can be read from the .csv files in the [results folder on GitHub](https://github.com/haosulab/ManiSkill/blob/main/docs/source/user_guide/additional_resources/benchmarking_results). There are also plotted figures in that folder. Below we show a selection of some of the figures/results from testing on an RTX 4090. The figures are also sometimes annotated with the GPU memory usage in GB. @@ -85,7 +85,7 @@ There is currently one benchmarked task: Cartpole Balance (classic control). Det For simulators that use physx (like ManiSkill and Isaac Lab), for comparison we try to align as many simulation configuration parameters (like number of solver position iterations) as well as object types (e.g. collision meshes, size of objects etc.) as close as possible. -In the future we plan to benchmark other simulators using other physics engines (like Mujoco) although how to fairly do so is still WIP. +In the future we plan to benchmark other simulators using other physics engines (like Mujoco) although how to do so fairly is still WIP. Reward functions and evaluation functions are purposely left out and not benchmarked. diff --git a/docs/source/user_guide/concepts/controllers.md b/docs/source/user_guide/concepts/controllers.md index c0e61c635..ff66942ff 100644 --- a/docs/source/user_guide/concepts/controllers.md +++ b/docs/source/user_guide/concepts/controllers.md @@ -94,7 +94,7 @@ keyframe qpos of rest panda modified to kf.qpos[-4] += 0.5 robot pose modified to sapien.Pose([-0.302144, -3.72529e-09, -5.96046e-08], [0.984722, 9.31323e-10, -1.50322e-08, -0.174137]) --> -For rotation in this controller, the user specifies a delta X, Y, and Z axis rotation (in radians if not normalized) indicating how far to rotate in all those dimensions. They are processed as XYZ euler angles and converted to a quaternion internally. Inverse kinematics is then used to determine the required joint actions to achieve the desired rotation. +For rotation in this controller, the user specifies a delta X, Y, and Z axis rotation (in radians if not normalized) indicating how far to rotate in all those dimensions. They are processed as XYZ Euler angles and converted to a quaternion internally. Inverse kinematics is then used to determine the required joint actions to achieve the desired rotation. ManiSkill implements two types of rotation based control that are generally the most intuitive to understand and commonly used in real-world robots, which is rotation under one orientation aligned/positioned at another frame. In particular there are two rotation frames supported: root aligned body and body aligned body. A aligned B means rotation in the frame with the same orientation as frame A and same position as frame B. Both frames are shown below by setting the corresponding dimension in the action to > 0 and the rest to 0. @@ -126,7 +126,7 @@ To help detail how controllers work in detail, below we explain with formulae ho ### Terminology -- fixed joint: a joint that can not be controlled. The degree of freedom (DoF) is 0. +- fixed joint: a joint that cannot be controlled. The degree of freedom (DoF) is 0. - `qpos` ( $q$ ): controllable joint positions - `qvel` ( $\dot{q}$ ): controllable joint velocities - target joint position ( $\bar{q}$ ): target position of the motor which drives the joint diff --git a/docs/source/user_guide/concepts/gpu_simulation.md b/docs/source/user_guide/concepts/gpu_simulation.md index 117aac083..ce096e619 100644 --- a/docs/source/user_guide/concepts/gpu_simulation.md +++ b/docs/source/user_guide/concepts/gpu_simulation.md @@ -11,7 +11,7 @@ The idea of sub-scenes is that reading data of e.g. actor poses is automatically :::{figure} images/physx_scene_subscene_relationship.png ::: -SAPIEN permits sub-scenes to be located at any location you want, ManiSkill just picks the most square setup with a fixed spacing parameter. Notice that if objects in one sub-scene go beyond it's workspace, it can actually affect the other sub-scenes. This is a common bug users may face when simulating larger scenes of e.g. houses or out-door settings where the spacing parameter is set too low so objects from e.g. sub-scene-0 will contact with objects in sub-scene-1. +SAPIEN permits sub-scenes to be located at any location you want, ManiSkill just picks the most square setup with a fixed spacing parameter. Notice that if objects in one sub-scene go beyond its workspace, it can actually affect the other sub-scenes. This is a common bug users may face when simulating larger scenes of e.g. houses or out-door settings where the spacing parameter is set too low so objects from e.g. sub-scene-0 will contact with objects in sub-scene-1. ## GPU Simulation Lifecycle @@ -20,7 +20,7 @@ In ManiSkill, the gym API is adopted to create, reset, and step through environm The `env.reset` part consists of one time reconfiguration followed by initialization: -1. Reconfiguration: Loading objects (comrpised of actors/articulations/lights) into the scene (basically spawning them in with an initial pose and not doing anything else) +1. Reconfiguration: Loading objects (comprised of actors/articulations/lights) into the scene (basically spawning them in with an initial pose and not doing anything else) 2. A call to `physx_system.gpu_init()` to initialize all GPU memory buffers and setting up all the rendering groups for parallelized rendering 3. Initializing all actors and articulations (set poses, qpos values etc.). 4. Running `physx_system.gpu_apply_*` to then save all the initialized data in step 3 to the GPU buffers to prepare for simulation diff --git a/docs/source/user_guide/concepts/observation.md b/docs/source/user_guide/concepts/observation.md index 90b8bb77f..91836d4a9 100644 --- a/docs/source/user_guide/concepts/observation.md +++ b/docs/source/user_guide/concepts/observation.md @@ -34,7 +34,7 @@ In addition to `agent` and `extra`, `sensor_data` and `sensor_param` are introdu If the data comes from a camera sensor: - `Color`: [H, W, 4], `torch.uint8`. RGB+Alpha values.. - - `PositionSegmentation`: [H, W, 4], `torch.int16`. The first 3 dimensions stand for (x, y, z) coordinates in the OpenGL/Blender convension. The unit is millimeters. The last dimension represents segmentation ID, see the [Segmentation data section](#segmentation-data) for more details. + - `PositionSegmentation`: [H, W, 4], `torch.int16`. The first 3 dimensions stand for (x, y, z) coordinates in the OpenGL/Blender convention. The unit is millimeters. The last dimension represents segmentation ID, see the [Segmentation data section](#segmentation-data) for more details. - `sensor_param`: parameters of each sensor, which varies depending on type of sensor - `{sensor_uid}`: @@ -61,7 +61,7 @@ This observation mode has the same data format as the [sensor_data mode](#sensor Note that this data is not scaled/normalized to [0, 1] or [-1, 1] in order to conserve memory, so if you consider to train on RGB, depth, and/or segmentation data be sure to scale your data before training on it. -ManiSkill by default flexibly supports different combinations of RGB, depth, and segmentation data, namely `rgb`, `depth`, `segmentation`, `rgb+depth`, `rgb+depth+segmentation`, `rgb+segmentation`, and`depth+segmentation`. (`rgbd` is a short hand for `rgb+depth`). Whichever image modality that is not chosen will not be included in the observation and conserves some memory and GPU bandwith. +ManiSkill by default flexibly supports different combinations of RGB, depth, and segmentation data, namely `rgb`, `depth`, `segmentation`, `rgb+depth`, `rgb+depth+segmentation`, `rgb+segmentation`, and`depth+segmentation`. (`rgbd` is a short hand for `rgb+depth`). Whichever image modality that is not chosen will not be included in the observation and conserves some memory and GPU bandwidth. The RGB and depth data visualized can look like below: ```{image} images/replica_cad_rgbd.png diff --git a/docs/source/user_guide/concepts/simulation_101.md b/docs/source/user_guide/concepts/simulation_101.md index a7f8c5110..113c6bd65 100644 --- a/docs/source/user_guide/concepts/simulation_101.md +++ b/docs/source/user_guide/concepts/simulation_101.md @@ -24,7 +24,7 @@ Actors are generally "singular" objects that when physically acted upon with som In simulation actors are composed of two major elements, collision shapes and visual shapes. -**Colision Shapes:** +**Collision Shapes:** Collision shapes define how an object will behave in simulation. A single actor can also be composed of several convex collision shapes in simulation. diff --git a/docs/source/user_guide/data_collection/motionplanning.md b/docs/source/user_guide/data_collection/motionplanning.md index 8da72919b..a25773b1b 100644 --- a/docs/source/user_guide/data_collection/motionplanning.md +++ b/docs/source/user_guide/data_collection/motionplanning.md @@ -2,11 +2,11 @@ ManiSkill provides simple tools to use motion planning to generate robot trajectories, primarily via the open-source [mplib](https://github.com/haosulab/MPlib) library. If you install ManiSkill, mplib will come installed already so no extra installation is necessary. -For an in depth tutorial on how to use more advanced features of mplib check out their documentation here: https://motion-planning-lib.readthedocs.io/latest/. Otherwise this section will cover some example code you can use and modify to generate motion planned demonstrations. The example code here is written for the Panda arm but should be modifiable to work for other robots. +For an in-depth tutorial on how to use more advanced features of mplib check out their documentation here: https://motion-planning-lib.readthedocs.io/latest/. Otherwise this section will cover some example code you can use and modify to generate motion planned demonstrations. The example code here is written for the Panda arm but can be modified to work for other robots. ## Motion Planning with Panda Arm -We provide some built in motion planning solutions for some tasks using the Panda arm at https://github.com/haosulab/ManiSkill/tree/main/mani_skill/examples/motionplanning/panda. You can run a quick demo below, which will save trajectory data as .h5 files to `demos/motionplanning/` and optionally save videos and/or visualize with a GUI. +We provide some built-in motion planning solutions for some tasks using the Panda arm at https://github.com/haosulab/ManiSkill/tree/main/mani_skill/examples/motionplanning/panda. You can run a quick demo below, which will save trajectory data as .h5 files to `demos/motionplanning/` and optionally save videos and/or visualize with a GUI. ```bash python -m mani_skill.examples.motionplanning.panda.run -e "PickCube-v1" --save-video # runs headless and only saves video @@ -28,4 +28,4 @@ For example, the PickCube-v1 task is composed of 3. close the gripper 4. move the gripper to above the goal location so the tool center point (tcp) of the gripper is at the goal -Note that while motion planning can generate and solve a wide variety of tasks, it's main limitations is that it often requires an human/engineer to tune and write, as well as being unable to generate solutions for more dynamical tasks. \ No newline at end of file +Note that while motion planning can generate and solve a wide variety of tasks, its main limitation is that it often requires an human/engineer to tune and write, as well as being unable to generate solutions for more dynamical tasks. \ No newline at end of file diff --git a/docs/source/user_guide/datasets/demos.md b/docs/source/user_guide/datasets/demos.md index b6c1e4b38..e2d796bd5 100644 --- a/docs/source/user_guide/datasets/demos.md +++ b/docs/source/user_guide/datasets/demos.md @@ -1,6 +1,6 @@ # Demonstrations -We provide a command line tool to download demonstrations directly from our [Hugging Face 🤗 dataset](https://huggingface.co/datasets/haosulab/ManiSkill_Demonstrations) which are done by task ID. The tool will download the demonstration files to a folder and also a few demonstration videos visualizing what the demonstrations look like. See [Tasks](../../tasks/index.md) for a list of all supported tasks. +We provide a command line tool to download demonstrations directly from our [Hugging Face 🤗 dataset](https://huggingface.co/datasets/haosulab/ManiSkill_Demonstrations) which is done by task ID. The tool will download the demonstration files to a folder and also a few demonstration videos visualizing what the demonstrations look like. See [Tasks](../../tasks/index.md) for a list of all supported tasks. @@ -15,7 +15,7 @@ python -m mani_skill.utils.download_demo all ## Format -All demonstrations for an task are saved in the HDF5 format openable by [h5py](https://github.com/h5py/h5py). Each HDF5 dataset is named `trajectory.{obs_mode}.{control_mode}.{sim_backend}.h5`, and is associated with a JSON metadata file with the same base name. Unless otherwise specified, `trajectory.h5` is short for `trajectory.none.pd_joint_pos.cpu.h5`, which contains the original demonstrations generated by the `pd_joint_pos` controller with the `none` observation mode (empty observations) in the CPU based simulation. However, there may exist demonstrations generated by other controllers. **Thus, please check the associated JSON to ensure which controller is used.** +All demonstrations for a task are saved in the HDF5 format openable by [h5py](https://github.com/h5py/h5py). Each HDF5 dataset is named `trajectory.{obs_mode}.{control_mode}.{sim_backend}.h5`, and is associated with a JSON metadata file with the same base name. Unless otherwise specified, `trajectory.h5` is short for `trajectory.none.pd_joint_pos.cpu.h5`, which contains the original demonstrations generated by the `pd_joint_pos` controller with the `none` observation mode (empty observations) in the CPU based simulation. However, there may exist demonstrations generated by other controllers. **Thus, please check the associated JSON to ensure which controller is used.** -ManiSkill is a robotics simulator built on top of SAPIEN. It provides a standard Gym/Gymnasium interface for easy use with existing learning workflows like RL and imitation learning. Moreover ManiSkill supports simulation on both the GPU and CPU, as well as fast parallelized rendering. +ManiSkill is a robotics simulator built on top of SAPIEN. It provides a standard Gym/Gymnasium interface for easy use with existing learning workflows like RL and imitation learning. Moreover, ManiSkill supports simulation on both the GPU and CPU, as well as fast parallelized rendering. ## Interface -Here is a basic example of how to run a ManiSkill task following the interface of [Gymnasium](https://gymnasium.farama.org/) and execute a random policy with a few basic options +Here is a basic example of how to run a ManiSkill task following the interface of [Gymnasium](https://gymnasium.farama.org/) and executing a random policy with a few basic options ```python import gymnasium as gym @@ -31,7 +31,7 @@ while not done: env.close() ``` -Changing `num_envs` to a value > 1 will automatically turn on the GPU simulation mode. More quick details [covered below](#gpu-parallelizedvectorized-tasks). +Changing `num_envs` to a value greater than 1 will automatically turn on the GPU simulation mode. More quick details [covered below](#gpu-parallelizedvectorized-tasks). You can also run the same code from the command line to demo random actions and play with rendering options @@ -42,7 +42,7 @@ python -m mani_skill.examples.demo_random_action -e PickCube-v1 python -m mani_skill.examples.demo_random_action -e PickCube-v1 --render-mode="human" --shader="rt-fast" ``` -Running with `render_mode="human"` will open up a GUI shown below that you can use to interactively explore the scene, pause/play the script, teleport objects around, and more. +Running with `render_mode="human"` will open up a GUI, shown below, that you can use to interactively explore the scene, pause/play the script, teleport objects around, and more. ```{figure} images/demo_random_action_gui.png --- @@ -69,7 +69,7 @@ python -m mani_skill.examples.demo_random_action -e "ReplicaCAD_SceneManipulatio --> -You will also notice that all data returned is a batched torch tensor. To reduce extra code handling numpy vs torch, cpu vs gpu sim, everything in ManiSkill defaults to serving/using batched torch Tensors of all data. To change the environment to serve numpy, unbatched data simply do the following +You will also notice that all data returned is a batched torch tensor. To reduce extra code handling numpy vs torch, cpu vs gpu sim, everything in ManiSkill defaults to serving/using batched torch tensors of all data. To change the environment to serve numpy, unbatched data simply do the following ```python from mani_skill.utils.wrappers.gymnasium import CPUGymWrapper @@ -78,7 +78,7 @@ env = CPUGymWrapper(env) obs, _ = env.reset() # obs is numpy and unbatched ``` -To have the exact same API defined by [gym/gymnasium](https://gymnasium.farama.org/) for single/vectorized environments see the section on [reinforcement learning setups](../reinforcement_learning/setup.md). +To have the exact same API defined by [gym/gymnasium](https://gymnasium.farama.org/) for single/vectorized environments, see the section on [reinforcement learning setups](../reinforcement_learning/setup.md). For a compilation of demos you can run without having to write any extra code check out the [demos page](../demos/index) @@ -90,7 +90,7 @@ See {py:class}`mani_skill.envs.sapien_env` for the full list of environment inst ManiSkill is powered by SAPIEN which supports GPU parallelized physics simulation and GPU parallelized rendering. This enables achieving 200,000+ state-based simulation FPS and 30,000+ FPS with rendering on a single 4090 GPU on a e.g. manipulation tasks. The FPS can be higher or lower depending on what is simulated. For full benchmarking results see [this page](../additional_resources/performance_benchmarking) -In order to run massively parallelized tasks on a GPU, it is as simple as adding the `num_envs` argument to `gym.make` as so +In order to run massively parallelized tasks on a GPU, it is as simple as adding the `num_envs` argument to `gym.make` as follows: ```python import gymnasium as gym diff --git a/docs/source/user_guide/learning_from_demos/baselines.md b/docs/source/user_guide/learning_from_demos/baselines.md index fad37ceaa..5bed438d4 100644 --- a/docs/source/user_guide/learning_from_demos/baselines.md +++ b/docs/source/user_guide/learning_from_demos/baselines.md @@ -16,7 +16,7 @@ BC Baselines are characterized by supervised learning focused algorithms for lea **Online Learning from Demonstrations Baselines** -Online ;earning from demonstrations baselines are characterized by learning from demonstrations while also leveraging online environment interactions. +Online learning from demonstrations baselines are characterized by learning from demonstrations while also leveraging online environment interactions. | Baseline | Code | Results | Paper | | --------------------------------------------- | ------------------------------------------------------------------------------- | ------- | ---------------------------------------- | diff --git a/docs/source/user_guide/reinforcement_learning/baselines.md b/docs/source/user_guide/reinforcement_learning/baselines.md index 3daee1157..178264326 100644 --- a/docs/source/user_guide/reinforcement_learning/baselines.md +++ b/docs/source/user_guide/reinforcement_learning/baselines.md @@ -8,7 +8,7 @@ As part of these baselines we establish standardized [reinforcement learning ben ## Online Reinforcement Learning Baselines -List of already implemented and tested online reinforcement learning baselines. The results link take you to the respective wandb pages for the results. You can change filters/views in the wandb workspace to view results with other settings (e.g. state based or RGB based training). Note that there are also reinforcement learning (offline RL, online imitation learning) baselines that leverage demonstrations, see the [learning from demos page](../learning_from_demos/index.md) for more information. +List of already implemented and tested online reinforcement learning baselines. The results link takes you to the respective wandb pages for the results. You can change filters/views in the wandb workspace to view results with other settings (e.g. state based or RGB based training). Note that there are also reinforcement learning (offline RL, online imitation learning) baselines that leverage demonstrations, see the [learning from demos page](../learning_from_demos/index.md) for more information. | Baseline | Code | Results | Paper | | ------------------------------------------------------------------- | ------------------------------------------------------------------------------ | ------- | ---------------------------------------- | diff --git a/docs/source/user_guide/reinforcement_learning/setup.md b/docs/source/user_guide/reinforcement_learning/setup.md index e4afe30dc..963c5c533 100644 --- a/docs/source/user_guide/reinforcement_learning/setup.md +++ b/docs/source/user_guide/reinforcement_learning/setup.md @@ -60,7 +60,7 @@ obs, rew, terminated, truncated, info = env.step(env.action_space.sample()) You may also notice that there are two additional options when creating a vector env. The `auto_reset` argument controls whether to automatically reset a parallel environment when it is terminated or truncated. This is useful depending on algorithm. The `ignore_terminations` argument controls whether environments reset upon terminated being True. Like gymnasium vector environments, partial resets can occur where some parallel environments reset while others do not. -Note that for efficiency, everything returned by the environment will be a batched torch tensor on the GPU and not a batched numpy array on the CPU. This the only difference you may need to account for between ManiSkill vectorized environments and gymnasium vectorized environments. +Note that for efficiency, everything returned by the environment will be a batched torch tensor on the GPU and not a batched numpy array on the CPU. This is the only difference you may need to account for between ManiSkill vectorized environments and gymnasium vectorized environments. ## Evaluation diff --git a/docs/source/user_guide/tutorials/custom_robots.md b/docs/source/user_guide/tutorials/custom_robots.md index 61854507d..1f274657c 100644 --- a/docs/source/user_guide/tutorials/custom_robots.md +++ b/docs/source/user_guide/tutorials/custom_robots.md @@ -377,7 +377,7 @@ To achieve fewer contacts and leverage just basic primitives, the model of the A :::{figure} images/anymal-visual-collision.png ::: -Another way to acheive fewer contacts is to remove collision shapes/meshes that are more often not going to be close to another one. Normally the collision mesh of the quadruped above is "dense" with no gaps between parts. By leaving big enough gaps in between, the physics simulation never needs to bother checking collisions between parts that are normally close together. The minimum gap required is determined by the simulation configuration `contact_offset` which acts as a first-pass filter to determine whether a contact between two bodies (Actor/Links) in the simulation needs to be checked and resolved. +Another way to achieve fewer contacts is to remove collision shapes/meshes that are more often not going to be close to another one. Normally the collision mesh of the quadruped above is "dense" with no gaps between parts. By leaving big enough gaps in between, the physics simulation never needs to bother checking collisions between parts that are normally close together. The minimum gap required is determined by the simulation configuration `contact_offset` which acts as a first-pass filter to determine whether a contact between two bodies (Actor/Links) in the simulation needs to be checked and resolved. Moreover, when there are fewer contacts the GPU memory requirements are significantly lessened. @@ -468,7 +468,7 @@ First is the use of simplified collision meshes. The URDF used by ManiSkill is [ ::: -You can view collisons of any object/articulation in the simulation via the GUI viewer by clicking any link on the articulation and under the articulation tab click Show collision. For individual objects you can do the same under the Entity tab. +You can view collisions of any object/articulation in the simulation via the GUI viewer by clicking any link on the articulation and under the articulation tab click Show collision. For individual objects you can do the same under the Entity tab. ## FAQ / Troubleshooting @@ -483,7 +483,7 @@ In the viewer when visualizing the robot you created, click any link on the robo **The collision shape looks completely different from the visual (like a convex version of it)** -This can be caused by a few reasons. One may be that your defined base agent has its `load_multiple_collisions` property set to False. If the collision meshes you use have multiple convex shapes that can be loaded (preferrably a .ply or .glb format), then setting `load_multiple_collisions = True` in your custom robot class can work. +This can be caused by a few reasons. One may be that your defined base agent has its `load_multiple_collisions` property set to False. If the collision meshes you use have multiple convex shapes that can be loaded (preferably a .ply or .glb format), then setting `load_multiple_collisions = True` in your custom robot class can work. Another reason is if your collision mesh is in the .stl format. Our loader has some issues loading .stl files at times and we recommend converting them to `.glb` as that is the easiest for our system to load and interpret. diff --git a/docs/source/user_guide/tutorials/custom_tasks/advanced.md b/docs/source/user_guide/tutorials/custom_tasks/advanced.md index a1e972c94..166102178 100644 --- a/docs/source/user_guide/tutorials/custom_tasks/advanced.md +++ b/docs/source/user_guide/tutorials/custom_tasks/advanced.md @@ -6,7 +6,7 @@ This page covers nearly every feature useful for task building in ManiSkill. If ### Pair-wise Contact Forces -You may notice that in some tasks like [PickCube-v1](https://github.com/haosulab/ManiSkill/blob/main/mani_skill/envs/tasks/pikc_cube.py) we call a function `self.agent.is_grasping(...)`. In ManiSkill, we leverage the pairwise impulses/forces API of SAPIEN to compute the forces betewen two objects. In the case of robots with two-finger grippers we check if both fingers are contacting a queried object. This is particularly useful for building better reward functions for faster RL. +You may notice that in some tasks like [PickCube-v1](https://github.com/haosulab/ManiSkill/blob/main/mani_skill/envs/tasks/pikc_cube.py) we call a function `self.agent.is_grasping(...)`. In ManiSkill, we leverage the pairwise impulses/forces API of SAPIEN to compute the forces between two objects. In the case of robots with two-finger grippers we check if both fingers are contacting a queried object. This is particularly useful for building better reward functions for faster RL. The API for querying pair-wise contact forces is unified between the GPU and CPU and is accessible via the `self.scene` object in your environment, accessible as so given a pair of actors/links of type `Actor | Link` to query via the ManiSkillScene object. @@ -147,7 +147,7 @@ Now recorded trajectories of your task will include the height as part of the en ### Handling Heterogeneous Simulation States -Many tasks like OpenCabinetDrawer-v1 and PegInsertionSide-v1 support heterogeneous simulation where each environment has a different object/geometry/dof. For these tasks often times during scene loading you run a for loop to create each different object in each parallel environment. However in doing so you have to give them each a different name which causes inconsistenency in the environment state as now the number of environments changes the shape of the state dictionary. To handle this you need to remove the per-environment actor/articulation from the state dictionary registry and add in the merged version. See sections on how to use [scene masks](#scene-masks) and [merging](#merging) for information on how to build heterogeneous simulated environments. +Many tasks like OpenCabinetDrawer-v1 and PegInsertionSide-v1 support heterogeneous simulation where each environment has a different object/geometry/dof. For these tasks often times during scene loading you run a for loop to create each different object in each parallel environment. However in doing so you have to give them each a different name which causes inconsistency in the environment state as now the number of environments changes the shape of the state dictionary. To handle this you need to remove the per-environment actor/articulation from the state dictionary registry and add in the merged version. See sections on how to use [scene masks](#scene-masks) and [merging](#merging) for information on how to build heterogeneous simulated environments. ```python class MyCustomTask(BaseEnv): @@ -319,7 +319,7 @@ Note the default `sim_freq, control_freq` values are tuned for GPU simulation an The custom tasks tutorial demonstrated adding fixed cameras to the PushCube task. ManiSkill+SAPIEN also supports mounting cameras to Actors and Links, which can be useful to e.g. have a camera follow a object as it moves around. -For example if you had a task with a baseketball in it and it's actor object is stored at `self.basketball`, in the `_default_sensor_configs` or `_default_human_render_camera_configs` properties you can do +For example if you had a task with a basketball in it and its actor object is stored at `self.basketball`, in the `_default_sensor_configs` or `_default_human_render_camera_configs` properties you can do ```python from mani_skill.utils import sapien_utils @@ -328,7 +328,7 @@ class MyCustomTask(BaseEnv): # ... @property def _default_sensor_configs(self) - # look towards the center of the baskeball from a positon that is offset + # look towards the center of the basketball from a positon that is offset # (0.3, 0.3, 0.5) away from the basketball pose = sapien_utils.look_at(eye=[0.3, 0.3, 0.5], target=[0, 0, 0]) return [ @@ -353,7 +353,7 @@ class MyCustomTask(BaseEnv): self.cam_mount = self.scene.create_actor_builder().build_kinematic("camera_mount") ``` -`self.cam_mount` has it's own pose data and if changed the camera will move with it. +`self.cam_mount` has its own pose data and if changed the camera will move with it. diff --git a/docs/source/user_guide/tutorials/custom_tasks/intro.md b/docs/source/user_guide/tutorials/custom_tasks/intro.md index 47a0d8379..70c883d12 100644 --- a/docs/source/user_guide/tutorials/custom_tasks/intro.md +++ b/docs/source/user_guide/tutorials/custom_tasks/intro.md @@ -32,7 +32,7 @@ If you have any questions or issues, feel free to ask in our [discord](https://d ## Setting up the Task Class -All tasks are defined by their own class and must inherit `BaseEnv`, similar to the design of many other robot learning simulation frameworks. You must then also register the class with a decorator so that the environment can be easily created via the `gym.make(env_id=...)` command in the future. Environment registration is done via `@register_env(env_id, max_episode_steps=...)` where `max_episode_steps` indicates the timelimit of the task. +All tasks are defined by their own class and must inherit `BaseEnv`, similar to the design of many other robot learning simulation frameworks. You must then also register the class with a decorator so that the environment can be easily created via the `gym.make(env_id=...)` command in the future. Environment registration is done via `@register_env(env_id, max_episode_steps=...)` where `max_episode_steps` indicates the time limit of the task. ```python import sapien @@ -303,7 +303,7 @@ class PushCubeEnv(BaseEnv): `compute_normalized_dense_reward` is the default reward function used and returned from `env.step`. We recommend defining normalized reward function as these tend to be easier to learn from, especially in algorithms that learn Q functions in RL. The result of `compute_dense_reward` is returned when an environment created as `gym.make(env_id=..., reward_mode="dense")` -Dense reward functions are not required and can be skipped. If not implemented then those reward modes are not supported and will raise an error if you try to use dense reward modes. Sparse reward functions are available if the evaluation function returns a dictonary with the success/fail key. If the task is in a success state, +1 reward is given. If the task is in a fail state, -1 reward is given. Otherwise 0 is given. +Dense reward functions are not required and can be skipped. If not implemented then those reward modes are not supported and will raise an error if you try to use dense reward modes. Sparse reward functions are available if the evaluation function returns a dictionary with the success/fail key. If the task is in a success state, +1 reward is given. If the task is in a fail state, -1 reward is given. Otherwise 0 is given. ## (Optional) Setting up Cameras/Sensors for Observations and Recording diff --git a/docs/source/user_guide/tutorials/custom_tasks/loading_objects.md b/docs/source/user_guide/tutorials/custom_tasks/loading_objects.md index 119aa4ec5..1ff91e50f 100644 --- a/docs/source/user_guide/tutorials/custom_tasks/loading_objects.md +++ b/docs/source/user_guide/tutorials/custom_tasks/loading_objects.md @@ -19,7 +19,7 @@ def _load_scene(self, options): id=f"ycb:{model_id}", ) # choose a reasonable initial pose that doesn't intersect other objects - builder.inital_pose = sapien.Pose(p=[0, 0, 0.5]) + builder.initial_pose = sapien.Pose(p=[0, 0, 0.5]) builder.build(name="object") ``` @@ -115,7 +115,7 @@ def _load_scene(self, options): ### Articulation Limitations -For the physx simulation backend, any single articulation can have a maximum of 64 links. More complex articulated objects will either need to be simplified by merging links together. Most of the time this is readily possible by inspecting the URDF and fusing together links held together by fixed joints. The less fixed joints and linsk there are, the better the simulation will run in terms of accuracy and speed. +For the physx simulation backend, any single articulation can have a maximum of 64 links. More complex articulated objects will either need to be simplified by merging links together. Most of the time this is readily possible by inspecting the URDF and fusing together links held together by fixed joints. The less fixed joints and links there are, the better the simulation will run in terms of accuracy and speed. ## Using the MJCF Loader @@ -165,6 +165,6 @@ class PickSingleYCBEnv(BaseEnv): ) ``` -A `reconfiguration_freq` value of 1 means every during every reset we reconfigure. A `reconfiguration_freq` of `k` means every `k` resets we reconfigure. A `reconfiguration_freq` of 0 (the default) means we never reconfigure again. +A `reconfiguration_freq` value of 1 means during every reset we reconfigure. A `reconfiguration_freq` of `k` means every `k` resets we reconfigure. A `reconfiguration_freq` of 0 (the default) means we never reconfigure again. In general one use case of setting a positive `reconfiguration_freq` value is for when you want to simulate a task in parallel where each parallel environment is working with a different object/articulation and there are way more object variants than number of parallel environments. For machine learning / RL workflows, setting `reconfiguration_freq` to e.g. 10 ensures every 10 resets the objects being simulated on are randomized which can diversify the data collected for online training while keeping simulation fast by reconfiguring infrequently. diff --git a/docs/source/user_guide/tutorials/domain_randomization.md b/docs/source/user_guide/tutorials/domain_randomization.md index 8bdd735a9..e0187ebb9 100644 --- a/docs/source/user_guide/tutorials/domain_randomization.md +++ b/docs/source/user_guide/tutorials/domain_randomization.md @@ -1,6 +1,6 @@ # Domain Randomization -One of the benefits of simulation is the ability to chop and change a number of aspects that would otherwise be expensive or time-consuming to do in the real world. This documents demonstrates a number of simple tools for randomization. In the beta release we currently only have a tutorial on how to do camera randomization. +One of the benefits of simulation is the ability to chop and change a number of aspects that would otherwise be expensive or time-consuming to do in the real world. This document demonstrates a number of simple tools for randomization. In the beta release we currently only have a tutorial on how to do camera randomization. ## Camera Randomization diff --git a/docs/source/user_guide/wrappers/record.md b/docs/source/user_guide/wrappers/record.md index 984973a06..d611a5420 100644 --- a/docs/source/user_guide/wrappers/record.md +++ b/docs/source/user_guide/wrappers/record.md @@ -6,7 +6,7 @@ ManiSkill provides a few ways to record videos/trajectories of tasks on single a The recommended approach is to use our RecordEpisode wrapper, which supports both single and vectorized environments, and saves videos and/or trajectory data (in the [ManiSkill format](../datasets/demos.md)) to disk. It will save whatever render_mode is specified upon environment creation (can be "rgb_array", "sensors", or "all" which combines both). -This wrapper by default saves videos on environment reset for single environments +This wrapper by default saves videos on environment reset for single environments. ```python import mani_skill.envs import gymnasium as gym