[docs] update installation docs, add contribution doc

Author: HanqingWangAI

source/en/user_guide/internmanip/quick_start/installation.md

@@ -244,6 +244,11 @@ chmod +x install.sh
 ```bash
 ./install.sh --all
 ```
+> 💡 Tips: 
+> Before installing genmanip, please ensure that Anaconda and Isaac Sim 4.5.0 are properly set up on your system. You can download the standalone version from [👉 Download Isaac Sim 4.5.0 (RC36)](https://download.isaacsim.omniverse.nvidia.com/isaac-sim-standalone%404.5.0-rc.36%2Brelease.19112.f59b3005.gl.linux-x86_64.release.zip)
+> 
+> After downloading, extract the archive to a suitable directory (e.g., ~/tools/isaac-sim-4.5.0). You should set the path to your local Isaac Sim installation during running `install.sh`.
+
 
 #### Available Installation Options:
 ```bash
@@ -291,6 +296,12 @@ source .venv/model/bin/activate
 deactivate
 ```
 
+> 🟡 Note: Unlike other environments that use venv, genmanip relies on Conda for environment management. You should always activate the environment using:
+> ```bash
+> conda activate genmanip
+> ```
+
+
 Optionally, users can customize the virtual environments directory path by passing the `--venv-dir {path}` option when executing `install.sh`.
 
 ```bash
@@ -361,6 +372,7 @@ When compiling C++ components (e.g., `building ManiSkill2_real2sim`), you might
     ```
 
 
+
 ## Verification (WIP)
 
 You can evaluate the pretrained **GR00t-N1** model on the `Simpler-Env` benchmark using a **client-server** architecture. This requires two separate terminal sessions:
@@ -419,3 +431,122 @@ If you prefer manual dataset preparation:
    - [CALVIN_ABC](https://huggingface.co/datasets/InternRobotics/InternData-Calvin_ABC)
    - [Google-Robot](https://huggingface.co/datasets/InternRobotics/InternData-fractal20220817_data)
    - [BridgeData-v2](https://huggingface.co/datasets/InternRobotics/InternData-BridgeV2)
+
+
+
+## ⚠️ Troubleshooting
+
+### 1. Conda Terms of Service Acceptance Error
+
+If you encounter the following error during the genmanip installation:
+```bash
+CondaToNonInteractiveError: Terms of Service have not been accepted for the following channels:
+    • https://repo.anaconda.com/pkgs/main
+    • https://repo.anaconda.com/pkgs/r
+```
+Manually accept the Terms of Service for each affected channel by running these commands:
+```bash
+conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/main
+conda tos accept --override-channels --channel https://repo.anaconda.com/pkgs/r
+```
+
+
+### 2. Tips for Slow or Unstable Networks
+
+If you encounter errors such as timeouts or incomplete downloads, especially in network-restricted or low-bandwidth environments, we recommend the following approaches.
+
+- Step 1: By default, `uv pip` uses relatively short HTTP timeouts. To extend the timeout, set the following environment variable before installation:
+    ```bash
+    export UV_HTTP_TIMEOUT=600  # Timeout in seconds (10 minutes)
+    ```
+
+- Step 2: Locate the package that failed to install. When running the `install.sh` script, if a package fails to install, identify the failing line in the output. This usually indicates which package wasn't downloaded properly.
+- Step 3: Dry-run to preview packages and versions. Use uv pip install --dry-run` to preview which packages (and exact versions) are going to be installed. For example:
+    ```bash
+    uv pip install "git+https://github.com/NVIDIA/Isaac-GR00T.git#egg=isaac-gr00t[base]" --dry-run
+    ```
+    This will list all packages along with their resolved versions, including those that might fail due to slow download.
+- Step 4: Activate your environment. Before manually installing the package, make sure you're in the correct virtual environment.
+    ```bash
+    source .venv/{your_env_name}/bin/activate
+    ```
+- Step 5: Manually install the problematic package. After identifying the package and version, install it manually:
+    ```bash
+    uv pip install torch==2.5.1  # Replace with your actual package and version
+    ```
+
+<!---
+- By default, `uv pip` uses relatively short HTTP timeouts. To extend the timeout, set the following environment variable before installation:
+    ```bash
+    export UV_HTTP_TIMEOUT=600  # Timeout in seconds (10 minutes)
+    ```
+- To ensure successful installation without network interruptions, you can download some large packages first and then install them locally:
+    ```bash
+    uv pip download -d ./wheelhouse "some-large-package"
+    uv pip install --no-index --find-links=./wheelhouse "some-large-package"
+    ```
+--->
+
+### 3. `import simpler_env` Fails Due to Missing Vulkan Library
+
+If you encounter the following error when trying to import simpler_env:
+```bash
+>>> import simpler_env
+Traceback (most recent call last):
+  ...
+ImportError: libvulkan.so.1: cannot open shared object file: No such file or directory
+```
+You can resolve this issue by installing the Vulkan runtime library via `apt`:
+```bash
+sudo apt update
+sudo apt install libvulkan1
+sudo ldconfig
+```
+
+### 4. GCC Fails to Compile Due to Missing Dependencies
+
+When compiling C++ components (e.g., `building ManiSkill2_real2sim`), you might encounter errors related to GCC or missing shared libraries. This guide walks you through how to resolve them without root/sudo permissions.
+
+- Step 1: Use a modern GCC (recommended ≥ 9.3.0). Older system compilers (e.g., GCC 5.x or 7.x) may not support required C++ standards. It's recommended to switch to GCC 9.3.0 or newer:
+    ```bash
+    export LD_LIBRARY_PATH=${PATH_TO}/gcc/gcc-9.3.0/lib64:${LD_LIBRARY_PATH:+:${LD_LIBRARY_PATH}}
+    export PATH=${PATH_TO}/gcc/gcc-9.3.0/bin:$PATH
+    ```
+    > ⚠️ Note: Simply using a newer compiler might not be enough — it may depend on shared libraries that are not available on your system.
+- Step 2: Manually install required libraries. If you encounter errors like: `error while loading shared libraries: libmpc.so.2 (libmpfr.so.1, libgmp.so.3)`. If you do have `sudo` privileges, the easiest way is to install the required libraries system-wide using your system package manager.
+    ```bash
+    sudo apt update
+    sudo apt install gcc-9 g++-9
+    ```
+    Or, you need to manually compile and install the following dependencies locally:
+    ```bash
+    INSTALL_DIR=$HOME/local
+    mkdir -p "$INSTALL_DIR"
+    cd "$INSTALL_DIR"
+
+    wget https://ftp.gnu.org/gnu/gmp/gmp-6.2.1.tar.xz
+    tar -xf gmp-6.2.1.tar.xz && cd gmp-6.2.1
+    ./configure --prefix="$INSTALL_DIR"
+    make -j$(nproc)
+    make install
+    cd "$INSTALL_DIR"
+
+    wget https://www.mpfr.org/mpfr-current/mpfr-4.2.1.tar.xz
+    tar -xf mpfr-4.2.1.tar.xz && cd mpfr-4.2.1
+    ./configure --prefix="$INSTALL_DIR" --with-gmp="$INSTALL_DIR"
+    make -j$(nproc)
+    make install
+    cd "$INSTALL_DIR"
+
+    echo "📦 Installing MPC..."
+    wget https://ftp.gnu.org/gnu/mpc/mpc-1.3.1.tar.gz
+    tar -xf mpc-1.3.1.tar.gz && cd mpc-1.3.1
+    ./configure --prefix="$INSTALL_DIR" --with-gmp="$INSTALL_DIR" --with-mpfr="$INSTALL_DIR"
+    make -j$(nproc)
+    make install
+    ```
+- Step 3 (Optional): Fix Missing `.so` Versions. Sometimes you have the correct library version (e.g., `libgmp.so.10`), but GCC expects an older symlink name (e.g., `libgmp.so.3`). You can fix missing library versions with symlinks.
+- Step 4: Export the Library Path. Make sure the compiler can find your locally installed shared libraries:
+    ```bash
+    export LD_LIBRARY_PATH=$HOME/local/lib:$LD_LIBRARY_PATH
+    ```

source/en/user_guide/internmanip/tutorials/environment.md

@@ -42,12 +42,18 @@ eval_cfg = EvalCfg(
             eval_tasks=["task1", "task2", ...],
             res_save_path="path/to/save/results",
             is_save_img=False,
-            camera_enable=CameraEnable(realsense=False, obs_camera=False, obs_camera_2=False),
-            depth_obs=False,
+            robot_type="franka",
             gripper_type="panda",
-            env_num=1,
+            franka_camera_enable=FrankaCameraEnable(
+                realsense=False, obs_camera=False, obs_camera_2=False
+            ),
+            aloha_split_camera_enable=AlohaSplitCameraEnable(
+                top_camera=True, left_camera=True, right_camera=True
+            ),
+            depth_obs=False,
             max_step=500,
             max_success_step=100,
+            env_num=1,
             physics_dt=1/30,
             rendering_dt=1/30,
             headless=True,
@@ -63,12 +69,14 @@ eval_cfg = EvalCfg(
 | Parameter | Type | Default | Description |
 |-----------|------|---------|-------------|
 | `dataset_path` | str | None | If None, it will be automatically downloaded from Hugging Face dataset [URL](https://huggingface.co/datasets/OpenRobotLab/InternBench-M1) on the first run. |
-| `eval_tasks` | list[str] | ALL_EVAL_TASKS | Subset of 18 predefined tasks (validate against `internmanip.configs.env.genmanip_env.ALL_EVAL_TASKS`) |
+| `eval_tasks` | list[str] | ALL_EVAL_TASKS | The relative path to the task folder under dataset_path |
 | `res_save_path` | str | None | Evaluation results storage directory (disabled if None).|
 | `is_save_img` | bool | False | Enable per-step multi-camera image capture (requires disk space) |
-| `camera_enable` | CameraEnable | `CameraEnable(realsense=False, `<br>`obs_camera=False, obs_camera_2=False)` | Camera activation config:<br>• `realsense`: Ego-view gripper cam<br>• `obs_camera`: Fixed rear-view cam<br>• `obs_camera_2`: Fixed front-view cam |
+| `robote_type` | enum | "franka" | robot selection (`"franka"` or `"aloha_split"`) |
+| `gripper_type` | enum | "panda" | End effector selection **when robote_type is `franka`** (`"panda"` or `"robotiq"`) |
+| `franka_camera_enable` | FrankaCameraEnable | `FrankaCameraEnable(realsense=False, `<br>`obs_camera=False, `<br>`obs_camera_2=False)` | Camera activation config:<br>• `realsense`: Ego-view gripper cam<br>• `obs_camera`: Fixed rear-view cam<br>• `obs_camera_2`: Fixed front-view cam <br> Note that this only works **when robote_type is `franka`** |
+| `aloha_split_camera_enable` | AlohaSplitCameraEnable | `AlohaSplitCameraEnable(top_camera=False, `<br>`left_camera=False, `<br>`right_camera=False)` | Camera activation config:<br>• `top_camera`: Ego-view top head cam<br>• `left_camera`: Ego-view left gripper cam<br>• `right_camera`: Ego-view right gripper cam <br> Note that this only works **when robote_type is `aloha_split`** |
 | `depth_obs` | bool | False | Generate depth maps for active cameras |
-| `gripper_type` | enum | "panda" | End effector selection (`"panda"` or `"robotiq"`) |
 | `max_step` | int | 500 | Episode termination step threshold |
 | `headless` | bool | True | Disable GUI |
 
@@ -85,17 +93,21 @@ eval_cfg = EvalCfg(
 > **Concurrency Note**: When `env_num > 1` or `ray_distribution.proc_num > 1`, environment outputs become multi-instance tensors. Agents must process batched observations and return batched actions.
 
 ## 3. I/O Specifications: Environment Outputs and Action Data Formats
+
+### 3.1 when robote_type is **franka**
+  
 **Observation Structure**
+  
 ```python
 observations: List[Dict] = [
     {
-        "franka_robot": {
-            "robot_pose": Tuple[array, array], # (position, oritention(quaternion))
+        "robot": {
+            "robot_pose": Tuple[array, array], # (position, oritention(quaternion: (w, x, y, z)))
             "joints_state": {
                 "positions": array,
                 "velocities": array
             },
-            "eef_pose": Tuple[array, array], # (position, oritention(quaternion))
+            "eef_pose": Tuple[array, array], # (position, oritention(quaternion: (w, x, y, z)))
             "sensors": {
                 "realsense": {
                     "rgb": array, # uint8 (480, 640, 3)
@@ -126,17 +138,17 @@ observations: List[Dict] = [
 ]
 ```
 
-**Action Space Specifications**
-Agents must output `List[Union[ActionFormat1, ActionFormat2, ..., ActionFormat5]]` of the same length as the input observations.
+**Action Space Specifications**  
+Agents must output `List[Union[List[float], dict]] = [action_1, action_2 , ...]` of the same length as the input observations.
 ```python
-actions: List[Union[ActionFormat1, ActionFormat2, ..., ActionFormat5]] = [
-    ActionFormat1,
-    ActionFormat2,
+actions: List[Union[List[float], dict]] = [
+    action_1,
+    action_2,
     ...
 ]
 ```
 
-Supported action formats:
+The `action_x` supports any of the following formats:
 
 **ActionFormat1**:
 ```python
@@ -146,31 +158,96 @@ List[float] # (9,) or (13,) -> panda or robotiq
 ```python
 {
     'arm_action': List[float], # (7,)
-    'gripper_action': List[float], # (2,) or (9,) -> panda or robotiq
+    'gripper_action': Union[List[float], int], # (2,) or (6,) -> panda or robotiq || -1 or 1 -> open or close
 }
 ```
 **ActionFormat3**:
 ```python
 {
-    'arm_action': List[float], # (7,)
-    'gripper_action': int, # -1 or 1 -> open or close
+    'eef_position': List[float], # (3,) -> (x, y, z)
+    'eef_orientation': List[float], # (4,) -> (quaternion: (w, x, y, z))
+    'gripper_action': Union[List[float], int], # (2,) or (6,) -> panda or robotiq || -1 or 1 -> open or close
 }
 ```
-**ActionFormat4**:
+  
+---  
+  
+### 3.2 when robote_type is **aloha_split**
+  
+**Observation Structure**
+  
+```python
+observations: List[Dict] = [
+    {
+        "robot": {
+            "robot_pose": Tuple[array, array], # (position, oritention(quaternion: (w, x, y, z)))
+            "joints_state": {
+                "positions": array,
+                "velocities": array
+            },
+            "left_eef_pose": Tuple[array, array], # (position, oritention(quaternion: (w, x, y, z))) -> left gripper eef pose
+            "right_eef_pose": Tuple[array, array], # (position, oritention(quaternion: (w, x, y, z))) -> right gripper eef pose
+            "sensors": {
+                "top_camera": {
+                    "rgb": array, # uint8 (480, 640, 3)
+                    "depth": array, # float32 (480, 640)
+                },
+                "left_camera": {
+                    "rgb": array,
+                    "depth": array,
+                },
+                "right_camera": {
+                    "rgb": array,
+                    "depth": array,
+                },
+            },
+            "instruction": str,
+            "metric": {
+                "task_name": str,
+                "episode_name": str,
+                "episode_sr": int,
+                "first_success_step": int,
+                "episode_step": int
+            },
+            "step": int,
+            "render": bool
+        }
+    },
+    ...
+]
+```
+
+**Action Space Specifications**  
+Agents must output `List[dict] = [action_1, action_2 , ...]` of the same length as the input observations.
+```python
+actions: List[dict] = [
+    action_1,
+    action_2,
+    ...
+]
+```
+
+The `action_x` supports any of the following formats:
+
+**ActionFormat1**:
 ```python
 {
-    'eef_position': List[float], # (3,) -> (x, y, z)
-    'eef_orientation': List[float], # (4,) -> (quaternion)
-    'gripper_action': List[float], # (2,) or (9,) -> panda or robotiq
+    'left_arm_action': List[float], # (6,)
+    'left_gripper_action': Union[List[float], int], # (2,) || -1 or 1 -> open or close
+    'right_arm_action': List[float], # (6,)
+    'right_gripper_action': Union[List[float], int], # (2,) || -1 or 1 -> open or close
 }
 ```
-**ActionFormat5**:
+**ActionFormat2**:
 ```python
 {
-    'eef_position': List[float], # (3,) -> (x, y, z)
-    'eef_orientation': List[float], # (4,) -> (quaternion)
-    'gripper_action': int, # -1 or 1 -> open or close
+    'left_eef_position': List[float], # (3,) -> (x, y, z)
+    'left_eef_orientation': List[float], # (4,) -> (quaternion: (w, x, y, z))
+    'left_gripper_action': Union[List[float], int], # (2,) || -1 or 1 -> open or close
+    'right_eef_position': List[float], # (3,) -> (x, y, z)
+    'right_eef_orientation': List[float], # (4,) -> (quaternion: (w, x, y, z))
+    'right_gripper_action': Union[List[float], int], # (2,)|| -1 or 1 -> open or close
 }
 ```
-
+  
 **None Handling Protocol**: If observation element is `None` or invalid value, corresponding action must be `[]`.