update document

README.md

@@ -9,14 +9,16 @@ This repository contains a reference PyTorch implementation of the paper:
 [Yi Ma](http://people.eecs.berkeley.edu/~yima/),
 [Jitendra Malik](https://people.eecs.berkeley.edu/~malik/) <br>
 Conference on Robot Learning (CoRL), 2022 <br>
-[[Website](https://haozhi.io/hora)], [[Paper](https://arxiv.org/abs/2210.04887)]
+[[Website](https://haozhi.io/hora)],
+[[Paper](https://arxiv.org/abs/2210.04887)],
+[[Video](https://www.youtube.com/watch?v=yH0e0l-H7-8)]
 
 ## Disclaimer
 
 It is worth noticing that:
 1. Simulation: The method is developed and debugged using IsaacGym Preview 3.0 ([Download](https://drive.google.com/file/d/1oK-QMZ40PO60PFWWsTmtK5ToFDkbL6R0/)), IsaacGymEnvs ([e860979](https://github.com/NVIDIA-Omniverse/IsaacGymEnvs/tree/e86097999b88da28b5252be16f81c595bbb3fca5)). Versions newer than these should work, but have not been extensively tested yet.
-2. Hardware: The method is developed using an internal version of AllegroHand. We also provide a reference implementation and [video results](https://haozhi.io/hora/allegro_v4) using the public AllegroHand-v4.
-3. Results: The reward number in this repository are higher than what is reported in the paper. This is because we change the `reset` function order following [LeggedGym](https://github.com/leggedrobotics/legged_gym) instead of the one in [IsaacGymEnvs](https://github.com/NVIDIA-Omniverse/IsaacGymEnvs/blob/main/isaacgymenvs/tasks/base/vec_task.py).
+2. Hardware: The method is developed using an internal version of AllegroHand. We also provide a reference implementation (see the *Training the Policy* section for details) and [video results](https://haozhi.io/hora/allegro_v4) using the public AllegroHand-v4.
+3. Results: The reward number in this repository are higher than what is reported in the paper. This is because we change the `reset` function order following [LeggedGym](https://github.com/leggedrobotics/legged_gym) instead of the one in [IsaacGymEnvs](https://github.com/NVIDIA-Omniverse/IsaacGymEnvs/blob/e8f1c66b24/isaacgymenvs/tasks/base/vec_task.py).
 
 ## Installation
 
@@ -31,17 +33,20 @@ This repository contains the following functionalities:
 
 ### Prerequisite
 
-We consider in-hand object rotation starting from a stable initial grasp. Download the pre-computed grasping pose files (see [development instructions](docs/dev.md) for how to customize grasp generation).
+In this paper, we consider in-hand object rotation starting from a stable initial grasp. Download the pre-computed grasping pose files (see [development instructions](docs/dev.md) for how to customize grasp generation) for both the public allegro hand and our internal allegro hand.
 
 ```
 # file size 109M
 gdown 1xqmCDCiZjl2N7ndGsS_ZvnpViU7PH7a3 -O cache/data.zip
 unzip cache/data.zip -d cache/
 ```
 
-The data structure should look like:
+The data structure should look like the following:
 
 ```
+# s07 means the size of the object is 0.7 times canonical size.
+# 50k means there are 50k randomly sampled grasping pose for each scale.
+
 cache/
   internal_allegro_grasp_50k_s07.npy
   ...
@@ -74,15 +79,15 @@ outputs/
       stage2_tb/  # stage 2 tensorboard records
 ```
 
-Visualize it:
+Visualize it by running the following command. Note that stage 1 policy refers to the one trained with privileged object information while stage 2 policy refers to the one trained with proprioceptive history. The stage 2 policy is also what we deployed in the real-world.
 
 ```
 # s1 and s2 stands for stage 1 and 2, respectively
 scripts/vis_s1.sh hora
 scripts/vis_s2.sh hora
 ```
 
-Evaluate it:
+Evaluate this two policies by running:
 
 ```
 # change {GPU_ID} to a valid number

docs/deploy.md

@@ -1,30 +1,40 @@
 # Deployment Instructions
 
-In this document, we provide instructions of how to deploy the model on a real AllegroHand.
-
-(This document is still under active polishing and construction, ping me in discord if you need help or want to contribute).
+This document provides instructions on how to deploy a trained policy on the real AllegroHand.
 
 ## Install ROS
 
-There are varies ways of installing ROS. During the development of this project, we use the following command to install ROS:
+This section provides instruction for installing ROS. Note that there are varies ways of installing ROS. Since this project is developed using Ubuntu 22.04, which is not officially supported by ROS. During the development of this project, we install ros from [robostack](https://github.com/RoboStack/ros-noetic). It's ok to ignore this section if you already have a working ROS library setup.
+
+The following instructions are copied from [robostack](https://github.com/RoboStack/ros-noetic). We assume you have a miniconda or conda environment installed.
+
+First, install `mamba` in the `base` environment.
+
 ```
-conda install -c conda-forge -c robostack ros-noetic-desktop
+# if you don't have mamba yet, install it first in the base environment (not needed when using mambaforge):
+conda install mamba -c conda-forge
 ```
-This is because of the official ROS release does not support my operating system at that time.
 
-## Setup the Allegro ROS library
+Then, install `rosallegro` conda environment. Note that his `rosallegro` environment is different from what we used to train the policy. This is mainly to solve possible conflicts between ros and varies packages we used (e.g. `pytorch`).
 
-Follow the insturctions at [ros-allegro](https://github.com/HaozhiQi/ros-allegro/) repository to setup the ROS package and the PCAN driver.
+```
+mamba create -n rosallegro ros-noetic-desktop python=3.9 -c robostack -c robostack-experimental -c conda-forge --no-channel-priority --override-channels
+conda activate rosallegro
+```
+
+Finally, follow the instructions at [ros-allegro](https://github.com/HaozhiQi/ros-allegro/) repository to set up the ROS package and the PCAN driver.
 
 ## Usage
 
 First, you need to open a shell and launch the following script:
 ```
 # may need to change /dev/pcanusbfd32 to your customized values
-roslaunch allegro_hand allegro_hand.launch HAND:=right AUTO_CAN:=false CAN_DEVICE:=/dev/pcanusbfd32 KEYBOARD:=false
+roslaunch allegro_hand allegro_hand.launch HAND:=right AUTO_CAN:=false CAN_DEVICE:=/dev/pcanusbfd32 KEYBOARD:=false CONTROLLER:=pd
 ```
-Once it's launched, run the following command to control the robot hand.
+
+Once it's launched, run the following command in the `hora` conda environment to control the robot hand.
 ```
 # e.g. scripts/deploy.sh hora
+conda activate hora
 scripts/deploy.sh ${OUTPUT_NAME}
 ```

docs/dev.md

@@ -2,8 +2,6 @@
 
 In this documentation, we provide explanations to the code structure and starting point for your customized usage.
 
-(This document is still under active polishing and construction, ping me in discord if you need help or want to contribute).
-
 ## File Structure
 
 ```

docs/install.md

@@ -1,12 +1,8 @@
 # Installation Instruction
 
-In this document, we provide instructions of how to properly install this codebase. We highly recommend using a conda environment to simplify set up.
+This document provides instructions of how to properly install this codebase. We highly recommend using a conda environment to simplify set up.
 
-(This document is still under active polishing and construction, ping me in discord if you need help or want to contribute).
-
-## Setup Conda Environment
-
-You can skip this section if you are not using conda virtual environment.
+## Setup a Conda Environment
 
 ```
 conda create -y -n hora python=3.8
@@ -31,11 +27,13 @@ pip install -e .
 Note, there may be some errors about `ERROR: pip's dependency resolver does not currently take into account all the packages that are installed.` This is mainly caused by `dm-control` which can be ignored at this stage. As long as you can run some isaacgym examples, you are good to go:
 
 ```
+# this example can only be ran with a monitor 
 python examples/joint_monkey.py
 ```
 
 ## Hora Repository
 
+Then we install the main repository by:
 ```
 git clone https://github.com/HaozhiQi/hora
 cd hora