01 // Overview & 60-Second Quickstart

ParallaxXR End-User Documentation

ParallaxXR (universal-xr / parallax-ctl / plx) is a commercial-grade, multi-platform 3DoF & 120Hz 6DoF spatial computing, optical hand gesture, and 1000Hz IMU head-click runtime for VITURE and 21+ multi-vendor XR smart glasses across Linux, Android / Samsung DeX, macOS, and Windows.

⚡ 60-Second Quickstart

# 1. Verify USB (0x35ca), DisplayPort link, 6DoF VIO, and PipeWire audio
plx status

# 2. Activate a 14-day hardware-bound offline Pro trial (or activate your key)
plx license trial
plx license activate PLX-XXXX-XXXX-XXXX-XXXX
plx license status

# 3. Engage the 6DoF/3DoF spatial desktop (or standalone OpenGL compositor)
plx spatial on
plx compositor start

# 4. Route audio to temple speakers, start optical + IMU gestures, and enable auto-dimming
plx audio
plx gesture start
plx autodim on
plx webui open

🥽 Supported XR Glasses Hardware Matrix (21+ Models)

Manufacturer Supported Models USB VID:PID Native Mode & FOV Hardware Capabilities
VITURE Luma Ultra (Carina P6S) 35ca:1104 1920×1200 @ 120Hz (52°) 120Hz 6DoF Stereo VIO, 3DoF IMU, 4-Level Film Dimming, Onboard RGB + Stereo IR Cameras (0c45:636b), SBS 3D
VITURE Beast / Luma Pro / Luma 35ca:1161 / 1101 / 1121 1920×1200 @ 120Hz (50°–54°) 6DoF VIO (Beast), 3DoF IMU, 4-Level Film Dimming, Optical Camera (Beast/Luma Pro), SBS 3D
VITURE Pro XR / One 35ca:1019 / 101d / 1011 1920×1080 @ 120Hz / 60Hz 3DoF IMU, Electrochromic Dimming, SBS 3D (+ Host Webcam Hand Gestures)
XREAL Air, Air 2, Air 2 Pro, Air 2 Ultra, One, One Pro 3318:0424 – 0436 1920×1080 @ 120Hz (46°–57°) 3DoF IMU, 6DoF + Camera (Ultra/One Pro), Electrochromic Dimming (Pro/One), SBS 3D
Rokid / RayNeo / Lenovo / ASUS Rokid Max 2, RayNeo Air 3, Legion Glasses, AirVision M1 04d2 / 1bbb / 17ef / 0b05 1080p / 1200p @ 60–120Hz 3DoF IMU, SBS 3D, Universal Compositor & Host Webcam Gestures
02 // Installation & Hardware Setup

Installation & Cabling Topology

1. Physical Cabling Modes

  • Direct Discrete GPU Connection (Active DP + USB-A to USB-C — Recommended for Desktops): Plug DisplayPort directly into your NVIDIA/AMD GPU (DP-5 / DP-4) for zero-copy 1920×1200 @ 120Hz video, and plug the USB-A tail into a motherboard USB 3.0 port (carries 5V VBUS HPD power + USB 2.0 D+/D- data for IMU 0x35ca, audio 0x35ca:0x1102, and camera 0x0c45:0x636b).
  • Motherboard / Laptop USB-C DisplayPort Alt-Mode: Connect to a Thunderbolt 4 / USB4 / DP-Alt-Mode port (marked with ⚡ or DP). Ensure IGD + PEG multi-monitor support is enabled in BIOS on desktops.
  • Wireless Phone / Tablet Streaming (Sunshine + Moonlight): Connect glasses to an Android phone or tablet and run plx stream start viture on your Linux host.

2. Linux Host Dependencies, Udev Rules & Python Setup

# 1. Install system packages & enable /dev/uinput kernel module
sudo apt update && sudo apt install -y \
    python3 python3-venv python3-pip python3-pyqt6 python3-pyqt6.qtopengl \
    libusb-1.0-0 pulseaudio-utils pipewire-bin v4l-utils
sudo modprobe uinput
echo "uinput" | sudo tee /etc/modules-load.d/uinput.conf

# 2. Configure /etc/udev/rules.d/70-viture-xr.rules for zero-root USB & uinput access
sudo usermod -aG input,video,plugdev "$USER"
sudo udevadm control --reload-rules && sudo udevadm trigger

# 3. Install universal-xr with Linux & Vision extras
cd ~/gemini_master/projects/viture_spatial
pip install -e ".[linux,vision]"

# 4. Link CLI entrypoints (parallax-ctl / plx / viture-ctl)
ln -sf ~/gemini_master/scripts/viture-ctl.sh ~/.local/bin/plx
ln -sf ~/gemini_master/scripts/viture-ctl.sh ~/.local/bin/parallax-ctl

3. Samsung DeX Companion APK (v1.3.0)

  1. Download parallaxxr-dex-v1.3.0.apk from https://parallaxxr.com/dex.
  2. Enable Settings → Accessibility → Installed apps → ParallaxXR DeX Spatial Service (on Android 13+, tap Allow restricted settings in App Info if prompted).
  3. Grant Appear on top (Overlay) and Camera permissions, and check Always allow when the USB permission popup appears for VITURE Glasses (0x35CA) and Camera (0x0C45).
03 // Usage Guide & CLI Reference

Spatial Workspace, Gestures, HUDs & CLI (plx)

1. Spatial Workspace & Standalone 120Hz 6DoF Compositor

# KDE Plasma 6 KWin Spatial Desktop
plx spatial on                   # Start 6DoF VIO daemon, load KWin effect & position virtual screens
plx follow off                   # Recommended: Anchored 6DoF/3DoF multi-monitor workspace
plx follow on                    # Smooth-follow single-screen HUD mode
plx recenter                     # Recenter spatial head origin (or press Ctrl+Super+Space)
plx virtual add 1920 1200        # Add a virtual spatial monitor

# Universal Standalone 120Hz 6DoF OpenGL Compositor (GNOME, Hyprland, Sway, COSMIC, KDE)
plx compositor start             # Launch fullscreen 120Hz OpenGL 3D spatial workspace
plx compositor start windowed    # Launch in windowed preview mode
plx compositor curved 3.2        # Set cylindrical curvature radius (meters)
plx compositor wings             # Toggle curved side-wing monitors
plx compositor hud               # Toggle gaze-locked telemetry HUD
plx compositor stop              # Stop standalone compositor

2. Optical 3D Hand Gestures & 1000Hz IMU Head Gestures

Hold your hand naturally 25 cm – 55 cm (10–22 inches) in front of the glasses (e.g., above your keyboard):

Gesture How to Perform Action Triggered
👉 Pointing Cursor Extend index finger / hold hand in FOV Moves cursor via 1-Euro velocity-adaptive 3-point palm centroid filter.
🤏 Air-Pinch & Drag Touch thumb & index tips (Ratio ≤ 0.23 engage, ≥ 0.33 release) Tap to left-click (BTN_LEFT); hold and move to drag windows or sliders.
✌️ Peace Hold Hold Index + Middle fingers extended for 0.40s Toggles PiP Passthrough 2.0 (lower-65% desk/keyboard view).
👍 Thumbs-Up Hold Curl 4 fingers into palm + thumb up for 0.40s Toggles Sideview Floating HUD (sysinfo, terminal, notes).
🖐️ Relaxed Open Palm Open hand naturally (≥ 3 uncurled fingers for 0.45s) Disengages cursor clutch and recenters the spatial canvas.
↕️ Double Head-Nod Two gentle downward nods (≥ 4.0° pitch dip, 1000Hz IMU) Emits left mouse click (BTN_LEFT) — works in 0 Lux pitch darkness.
↔️ Head-Shake Quick left-right yaw shake (≥ 5.5° within 0.55s) Immediately recenters your spatial workspace without touching the keyboard.

3. Hardware Optics, PiP Passthrough 2.0 & Sideview HUD

# Electrochromic Film Tint & Optics
plx dim 0..3                     # 0=Clear AR, 1=Light, 2=Medium, 3=Max Dark Cinema
plx autodim on                   # EMA ambient camera luminance auto-dimming
plx brightness 0..8              # Micro-OLED display brightness (default 6)
plx volume 0..8                  # Temple speaker volume (default 6)
plx 3d on | off                  # Toggle Stereoscopic Side-by-Side (SBS) 3D mode (3840x1080)

# PiP Passthrough 2.0 & Sideview HUD (Persistent KWin placement)
plx pip on                       # Launch frameless camera passthrough HUD
plx pip zoom desk                # Crop lower 65% of camera FOV onto keyboard (desk | full | zoom2x)
plx pip align bottom-right       # Align to 9 screen anchor points
plx pip hud toggle               # Toggle 21-landmark AR hand skeleton overlay
plx sideview on                  # Launch floating Sideview HUD
plx sideview mode sysinfo        # Modes: sysinfo | terminal | notes
04 // Licensing, Offline Certificates & Seats

Zero-Nag Offline-First Ed25519 Licensing

ParallaxXR verifies entitlements locally in under 0.2 milliseconds using an Ed25519 cryptographically signed offline certificate stored at ~/.config/viture_spatial/license.cert. It never phones home during offline flights and never nags you with popups.

Privacy-Preserving Hardware Fingerprint: Your machine computes hw_hash = sha256("viture-spatial-seat-v1:" + /etc/machine-id + ":" + arch)[:32] locally before contacting Cloudflare Edge. Raw serial numbers, MAC addresses, and usernames never leave your device.
Tier Price Hardware Seats Offline Lease Included Features
Parallax Community (COMMUNITY_FREE) $0 / forever Unlimited Permanent 3DoF virtual display, Smooth Follow, Brightness/Volume/Tint CLI, Local WebUI (:8766).
14-Day Pro Trial (TRIAL_14D) Free (14 Days) 1 Seat 14 Days Full Pro suite unlocked via plx license trial (no credit card required).
ParallaxXR Pro (PRO_ANNUAL) $39 / yr ($5/mo) 3 Seats 35 Days (auto-renews) 120Hz Carina 6DoF VIO, Standalone Compositor, Air-Pinch & 3D Gestures, 1000Hz IMU Head Clicks, EMA Auto-Dim, PiP 2.0, Sideview, Samsung DeX, 21+ XR vendors.
ParallaxXR Founder (PRO_PERPETUAL) $89 one-time 5 Seats 365 Days (auto-renews) Lifetime perpetual access to all Pro features + 365-day renewable offline certificate. 
plx license status               # Verify local Ed25519 certificate (<0.2ms) & check days remaining
plx license trial                # Start an instant 14-day Pro trial
plx license activate PLX-XXXX... # Bind this hardware seat and download signed offline certificate
plx license refresh              # Refresh offline certificate lease before a trip
plx license verify               # Verify signature offline + live seat state in Cloudflare D1
plx license seats                # List all active devices bound to your license key
plx license deactivate           # Release this machine's seat so you can move to another PC/Deck
05 // Troubleshooting & Diagnostics

Troubleshooting & Common Fixes

Always start diagnostics by running plx status, which checks all 9 hardware, display, audio, and daemon subsystems automatically.

Multi-Monitor Occlusion ("Only One Screen Tracks My Head"): If turning your head causes one display to swing across and cover adjacent virtual monitors, Smooth-Follow Mode is enabled. Press Ctrl + Super + Enter or run plx follow off to return to Anchored 6DoF/3DoF Multi-Monitor Mode.
Symptom Root Cause Fix / Command
Glasses displays are black after hotplug or stuck at 640×480 USB-C retimer HPD sleep or 0-byte EDID fallback on card2-DP-1 / DP-5. Run plx video to force DisplayPort link training and restore native 1920×1200 @ 120Hz hardware EDID mode.
Video works in glasses, but no IMU head tracking (0x35ca), mic, or dimming Active DP-to-USB-C adapter's USB-A tail is unplugged or plugged into a wall charger instead of the PC. Plug the adapter's USB-A tail into a motherboard USB 3.0 port and verify with lsusb -d 35ca:.
Zero power when using a passive USB-C female-to-female coupler Single-sided CC1 configuration channel polarity mismatch inside the coupler. Rotate one USB-C plug 180° at the coupler joint.
VITURE Mobile Dock fails with usb: error -71 (EPROTO) Mobile Dock internal BMS battery is at 0% and browns out during USB descriptor read. Recharge the Mobile Dock via USB-C PD or connect directly to the host PC.
No sound in temple speakers or missing VITURE USB mic (35ca:1102) PipeWire default sink not routed to VITURE HDMI/USB or USB mic interface hung. Run plx audio (or plx audio reset to issue a hardware USBDEVFS_RESET).
SEAT_LIMIT_REACHED (HTTP 409) when activating key All 3 (Pro) or 5 (Founder) hardware seats are currently bound. Run plx license deactivate on an old machine or release a seat at parallaxxr.com/#offline-spec.