Add .gitignore, update Dockerfile, and enhance README with udev rules and calibration instructions

.gitignore

@@ -0,0 +1,2 @@
+playground/
+misc/zed_installer.run

Dockerfile

@@ -1,18 +1,36 @@
 FROM stereolabs/zed:5.1-gl-devel-cuda12.8-ubuntu24.04
 
+ARG PROXYCHAIN_SOCKS5_HOST=127.0.0.1
+ARG PROXYCHAIN_SOCKS5_PORT=36000
+
 # Use USTC mirrors for faster access in China.
-RUN sed -i 's|http://archive.ubuntu.com/ubuntu/|https://mirrors.ustc.edu.cn/ubuntu/|g' /etc/apt/sources.list \
+RUN if [ -f /etc/apt/sources.list.d/ubuntu.sources ]; then \
-  && sed -i 's|http://security.ubuntu.com/ubuntu/|https://mirrors.ustc.edu.cn/ubuntu/|g' /etc/apt/sources.list \
+      sed -i 's|http://archive.ubuntu.com/ubuntu/|https://mirrors.ustc.edu.cn/ubuntu/|g' /etc/apt/sources.list.d/ubuntu.sources; \
+      sed -i 's|http://security.ubuntu.com/ubuntu/|https://mirrors.ustc.edu.cn/ubuntu/|g' /etc/apt/sources.list.d/ubuntu.sources; \
+    elif [ -f /etc/apt/sources.list ]; then \
+      sed -i 's|http://archive.ubuntu.com/ubuntu/|https://mirrors.ustc.edu.cn/ubuntu/|g' /etc/apt/sources.list; \
+      sed -i 's|http://security.ubuntu.com/ubuntu/|https://mirrors.ustc.edu.cn/ubuntu/|g' /etc/apt/sources.list; \
+    fi \
   && mkdir -p /etc/pip \
   && printf "%s\n" \
     "[global]" \
     "index-url = https://pypi.mirrors.ustc.edu.cn/simple" \
     "trusted-host = pypi.mirrors.ustc.edu.cn" \
-    > /etc/pip.conf
+    > /etc/pip.conf \
-
+  && apt-get update \
-RUN  apt-get update \
   && DEBIAN_FRONTEND=noninteractive apt-get install -y --no-install-recommends \
     build-essential \
     cmake \
     git \
+    gdb \
+    vim \
+    ninja-build \
+    python3-pip \
+    python3-setuptools \
+    python3-venv \
+    libopencv-dev \
+    proxychains-ng \
+  && if [ -f /etc/proxychains4.conf ]; then \
+       sed -i 's|^socks4[[:space:]]\\+127\\.0\\.0\\.1[[:space:]]\\+9050|socks5 '"${PROXYCHAIN_SOCKS5_HOST}"' '"${PROXYCHAIN_SOCKS5_PORT}"'|g' /etc/proxychains4.conf; \
+     fi \
   && rm -rf /var/lib/apt/lists/*

README.md

@@ -43,3 +43,45 @@ docker compose exec zed bash
 - USB devices are passed through via `/dev/bus/usb` and the container runs
   `privileged` for camera access.
 - The workspace is mounted at `/workspaces/zed-playground`.
+
+## Udev Rules (Host)
+
+Udev controls device permissions and power settings on the host. If ZED sensors
+fail to initialize inside the container, the host likely does not allow
+non-root access to the camera MCU/IMU or has USB autosuspend enabled.
+
+This repo provides two options:
+- `misc/99-slabs.rules`: a ready-to-use rule file that grants access to ZED
+  USB/HID devices and disables autosuspend for known ZED USB IDs.
+- `misc/udev_fix.sh`: downloads the official `99-slabs.rules`, installs it to
+  `/etc/udev/rules.d/`, and reloads udev.
+
+Run the script on the host (not in the container), then unplug/replug the
+camera so the new rules take effect.
+- `/usr/local/zed/samples` has ZED SDK sample applications.
+
+See [adujardin/setup_zed_udev-rules.sh](https://gist.github.com/adujardin/2d5ce8f000fc6a7bd40bee2709749ff8/) from stereolabs community.
+
+- [ZED camera does not open in docker container as a non-root user](https://community.stereolabs.com/t/zed-camera-does-not-open-in-docker-container-as-a-non-root-user/2259/4)
+- [CAMERA NOT DETECTED in WSL2 Ubuntu 22.04](https://community.stereolabs.com/t/camera-not-detected-in-wsl2-ubuntu-22-04/3477/5)
+
+## Calibration Download
+
+If automatic calibration download fails, grab it manually:
+
+```
+http://calib.stereolabs.com/?SN=<ZED_SN>
+```
+
+`<ZED_SN>` is the decimal serial number without the `SN` prefix.
+
+Place the downloaded `SN<XXXX>.conf` in the default settings path:
+- Linux: `/usr/local/zed/settings/`
+- Windows: `C:/ProgramData/stereolabs/settings`
+
+If you pass a custom settings path in your app, the SDK will try that first and
+fall back to the default path if the file is not found.
+
+## See also
+
+- [How to Install ZED SDK with Docker on Linux](https://www.stereolabs.com/docs/docker/install-guide-linux)

docker-compose.yml

@@ -22,5 +22,7 @@ services:
       - /dev/bus/usb:/dev/bus/usb
     gpus: all
     network_mode: host
+    group_add:
+      - video
     stdin_open: true
     tty: true

misc/99-slabs.rules

@@ -0,0 +1,28 @@
+# HIDAPI/libusb
+SUBSYSTEM=="usb", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f681", MODE="0666"
+SUBSYSTEM=="usb", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f781", MODE="0666"
+SUBSYSTEM=="usb", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f881", MODE="0666"
+SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE="0666"
+
+# HIDAPI/hidraw
+KERNEL=="hidraw*", ATTRS{busnum}=="1", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f681", MODE="0666"
+KERNEL=="hidraw*", ATTRS{busnum}=="1", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f781", MODE="0666"
+KERNEL=="hidraw*", ATTRS{busnum}=="1", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f881", MODE="0666"
+KERNEL=="hidraw*", ATTRS{busnum}=="1", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="df11", MODE="0666"
+
+# blacklist for usb autosuspend
+# http://kernel.org/doc/Documentation/usb/power-management.txt
+ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f780", TEST=="power/control", ATTR{power/control}="on"
+ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f781", TEST=="power/control", ATTR{power/control}="on"
+ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f881", TEST=="power/control", ATTR{power/control}="on"
+ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="0424", ATTRS{idProduct}=="2512", TEST=="power/control", ATTR{power/control}="on"
+
+ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f780", TEST=="power/autosuspend", ATTR{power/autosuspend}="-1"
+ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f781", TEST=="power/autosuspend", ATTR{power/autosuspend}="-1"
+ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f881", TEST=="power/autosuspend", ATTR{power/autosuspend}="-1"
+ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="0424", ATTRS{idProduct}=="2512", TEST=="power/autosuspend", ATTR{power/autosuspend}="-1"
+
+ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f780", TEST=="power/autosuspend_delay_ms", ATTR{power/autosuspend_delay_ms}="-1"
+ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f781", TEST=="power/autosuspend_delay_ms", ATTR{power/autosuspend_delay_ms}="-1"
+ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="2b03", ATTRS{idProduct}=="f881", TEST=="power/autosuspend_delay_ms", ATTR{power/autosuspend_delay_ms}="-1"
+ACTION=="add", SUBSYSTEM=="usb", ATTRS{idVendor}=="0424", ATTRS{idProduct}=="2512", TEST=="power/autosuspend_delay_ms", ATTR{power/autosuspend_delay_ms}="-1"

misc/udev_fix.sh

@@ -0,0 +1,14 @@
+# This script will setup USB rules to open the ZED cameras without root access
+# This can also be useful to access the cameras from a docker container without root (this script needs to be run on the host)
+# NB: Running the ZED SDK installer will already setup those
+
+# Print the commands
+set -x
+# Download the lightest installer
+wget -q https://download.stereolabs.com/zedsdk/3.5/jp44/jetsons -O zed_installer.run
+# Extracting only the file we're interested in
+bash ./zed_installer.run --tar -x './99-slabs.rules'  > /dev/null 2>&1
+sudo mv "./99-slabs.rules" "/etc/udev/rules.d/"
+sudo chmod 777 "/etc/udev/rules.d/99-slabs.rules"
+sudo udevadm control --reload-rules && sudo udevadm trigger
+