waydeeper

Depth-effect wallpaper for Wayland — GPU-accelerated parallax driven by ML depth estimation. Move your cursor (or switch workspaces) and the wallpaper shifts in 3D.

This is a personal fork focused on Hyprland + AMD (ROCm) with an Electron configuration GUI.

How it works

1. A monocular depth model (ONNX) turns any image into a depth map.
2. A wlr-layer-shell background surface renders the image with an OpenGL ES 3.0 shader that displaces pixels by depth — either a flat UV-warp or a true 3D inpainted mesh with correct occlusion.
3. Parallax is driven by the cursor (polled from Hyprland) and, optionally, by workspace movement.

Components

Component	Stack	Location
Daemon	Rust, smithay-client-toolkit, glow/EGL, ort (ONNX Runtime)	src/
Depth inference	ONNX Runtime — ROCm + MIGraphX execution providers	src/depth_estimator.rs
3D inpainting	Python subprocess (3d-photo-inpainting)	scripts/
GUI	Electron + Vue 3 + Vuetify	gui/

One independent daemon process runs per monitor; the GUI and waydeeper set talk to it over a per-monitor Unix socket and hot-reload without flicker.

Requirements

• A wlr-layer-shell compositor — primarily tested on Hyprland.
• ONNX Runtime (libonnxruntime.so) reachable via ORT_DYLIB_PATH.
• For GPU depth on AMD: ROCm + MIGraphX. Tested on a Radeon RX 6800 (RDNA2) with HSA_OVERRIDE_GFX_VERSION=10.3.0.
• Node.js (only to build the GUI).

Build & install

# Daemon + GUI + launcher into ~/.local/bin
bash install-all.sh

Or build pieces manually:

cargo build --release          # daemon -> target/release/waydeeper
cd gui && npm install && npm run build

The launcher sets the runtime environment the daemon needs:

export ORT_DYLIB_PATH=/usr/lib/libonnxruntime.so
export HSA_OVERRIDE_GFX_VERSION=10.3.0
export LD_LIBRARY_PATH=/opt/rocm/lib:/opt/rocm/lib/migraphx/lib:$LD_LIBRARY_PATH

Depth models

Download with waydeeper download-model. Models live in ~/.local/share/waydeeper/models/.

Model	Notes
depth-anything-v3-base (default)	Balanced quality/speed
depth-anything-v3-large	Highest DAv3 quality, slow
depth-anything-v2-small	Fastest, good on anime/illustration

Roadmap: adding edge-sharper generative-distilled models (Lotus-Depth, Marigold-Lightning, Metric3D v2) that run well on ROCm/MIGraphX.

Usage

# Apply a wallpaper (all monitors)
waydeeper set /path/to/image.jpg

# Specific monitor + parallax strength
waydeeper set /path/to/image.jpg -m DP-1 --strength 0.05

# True-3D inpaint mode (cached after first run)
waydeeper set /path/to/image.jpg --inpaint

# Daemon control
waydeeper daemon            # start configured monitors
waydeeper stop              # stop all
waydeeper list-monitors

# Cache
waydeeper cache --list
waydeeper cache --clear

If a daemon is already running for a monitor, set reloads it in-place over IPC.

Most users will just open the GUI to pick wallpapers, tune sliders, and place the clock overlay.

Configuration

~/.config/waydeeper/config.json, per monitor:

Option	Default	Description
strength_x / strength_y	0.02	Parallax strength per axis
smooth_animation	true	Eased animation
animation_speed	0.05	Animation speed multiplier
fps	60	Frame rate (30 or 60)
active_delay_ms	150	Delay before animating after cursor enters
idle_timeout_ms	5000	Idle time before animation stops
invert_depth	false	Invert depth interpretation
use_inpaint	false	3D inpaint mesh mode

Caches: depth maps in ~/.cache/waydeeper/depth/, inpaint meshes in ~/.cache/waydeeper/inpaint/, GUI thumbnails in ~/.cache/waydeeper/thumbs/.

Roadmap

• Faster, edge-sharper depth models (Lotus-Depth / Marigold-Lightning / Metric3D).
• Snappier GUI thumbnail loading (parallel decode + incremental rendering).
• Workspace parallax — read Hyprland IPC and pan the wallpaper as you move between workspaces.
• Fullscreen-aware rendering — pause (and optionally release GPU resources) while an app is fullscreen, resume on exit.

Acknowledgements

Fork of EdenQwQ/waydeeper, inspired by lively wallpaper. Depth models: Depth Anything, MiDaS, Depth Pro. Mesh inpainting from 3D Photo Inpainting.