Context
實際在 tiryoh/ros2-desktop-vnc:humble Docker container 中安裝並跑起 Meta Quest → Panda IK → MuJoCo viewer 整條 pipeline，過程中踩到多個命名和 API 坑。
Key Insights
- PyPI 套件名稱陷阱（robotics 生態常見）：
pip install pink裝到程式碼格式化工具（0.8.1），正確的是pip install pin-pink；pip install pinocchio也是錯的，正確是pip install pin。import pink/import pinocchio雖然一樣，但裝錯套件完全不同。 - colcon build 找不到 README.md：colcon 在
build/<pkg>/目錄執行setup.py，open("README.md")找不到 source 目錄的檔案。修法：sed改成open(os.path.join(os.path.dirname(__file__), "README.md"))。 - example_agilex 不是 ROS2 package：沒有
package.xml，colcon 直接忽略。解法是把pink_ik_solver.py和vectorised_posture_task.py複製到 teleop script 旁邊，同目錄直接 import。 - robot_descriptions fr3_description 沒有 URDF_PATH：FR3 在 robot_descriptions 只有 MJCF，改用
panda_description.URDF_PATH（Panda 和 FR3 kinematic chain 幾乎相同，驗證 teleop 夠用）。MuJoCo XML 也要對應改成franka_panda/scene.xml，end-effector frame 改成panda_hand。 - MetaQuestReader API：
get_buttons()不存在，正確是last_buttons（屬性，非方法），讀取前加or {}防止 None。 - numpy/scipy ABI 衝突：apt scipy 綁定舊 numpy ABI；
pip install pin-pink升級 numpy 後 scipy 壞掉。修法：pip3 install --upgrade numpy scipy先升級兩個再裝其他套件。 - Docker container 就是 venv：在容器內不需要另建 venv；用
colcon build --symlink-install管理 ROS2 packages，system pip 管理非 ROS2 依賴，source install/setup.bash統一環境。
Final Setup
FROM tiryoh/ros2-desktop-vnc:humble
RUN apt-get update && apt-get install -y android-tools-adb \
&& rm -rf /var/lib/apt/lists/*
RUN pip3 install --upgrade numpy scipy && \
pip3 install mujoco pin-pink pin quadprog robot_descriptions# 一次性
touch ~/ros_ws/src/meta_quest_teleop/README.md # colcon workaround
colcon build --symlink-install --packages-select meta_quest_teleop
# 每次執行
source /opt/ros/humble/setup.bash
source ~/ros_ws/install/setup.bash
python3 mujoco_teleop.py --ip <quest-ip> \
--xml ~/mujoco_menagerie/franka_panda/scene.xml \
--ee-frame panda_hand