QuickView

A Wayland-native image viewer for Linux with Quick Look-style preview and OCR text selection.

Roadmap · Architecture · Spec Sheet · Decisions · ADRs · Contributing

---

Inspired by macOS Quick Look + Preview — open an image, select text right off it, copy to your clipboard. Built with GTK4 and libadwaita, targeting wlroots compositors (niri, Hyprland, Sway).

Status: Early development. Core scaffold is functional — image display, OCR pipeline, drag-select overlay, and quick preview mode all work. See the Phased Plan for what's done and what's next.

Features

Quick Preview — borderless overlay window, dismiss with Space or Esc

quickview --quick-preview photo.png

Full Viewer — standard app window with headerbar, arrow key navigation between images in the same directory

quickview photo.png

Zoom & Pan — Ctrl+scroll to zoom at cursor, pinch-to-zoom on touchpad, +/- keys, 0 to reset. Middle-click drag or Ctrl+left-drag to pan.

OCR Text Selection — Tesseract runs asynchronously after the image loads. Drag to select recognized words, Ctrl+C to copy. Selection stays aligned at any zoom level.

Requirements

Arch Linux (primary target, requires GTK4 >= 4.10):

sudo pacman -S --needed \
  base-devel rustup pkgconf \
  gtk4 libadwaita \
  tesseract tesseract-data-eng \
  gtk4-layer-shell

Optional:

• wl-clipboard — CLI clipboard fallback
• glycin — sandboxed image decoding (future)

gtk4-layer-shell provides true overlay behavior on wlroots compositors. On GNOME/Mutter, Quick Preview falls back to an undecorated window.

Build and Run

cargo build

# Full viewer
cargo run -- path/to/image.png

# Quick preview
cargo run -- --quick-preview path/to/image.png

# Pipe a path via stdin
echo path/to/image.png | cargo run -- --quick-preview -

# OCR in a different language
cargo run -- --lang deu path/to/image.png

Project Structure

crates/
  quickview/          CLI entrypoint
  quickview-core/     OCR parsing, geometry, selection logic (no GTK dep)
  quickview-ui/       GTK4/libadwaita windows, widgets, layer-shell
docs/                 Architecture, spec sheet, phased plan, decisions
adrs/                 Architecture Decision Records (10)
packaging/            Arch PKGBUILD, Flatpak manifest, AppImage stub
assets/               .desktop file, icons, AppStream metainfo

License

MIT