Beta

garview

Image & Document Viewer

A multi-format image and document viewer with annotation tools, PDF text search, form fields, and print/export support. View images, PDFs, comics, and eBooks with session persistence and IPC control.

View on GitHub Install

garview PDF annotation mode with drawing tools on a W-9 form

garview PDF viewer with sidebar showing table of contents

garview PDF document with sidebar navigation and table of contents

garview gallery mode with thumbnail grid of images

Features

8 annotation tools with undo/redo history
PDF with text search, selection, and form fields
Print via CUPS and export to PNG/JPEG
Comics (CBZ, CB7, CBT) and eBooks (EPUB, MOBI)
Raster images: PNG, JPEG, GIF, WebP, AVIF, TIFF
SVG/SVGZ vector graphics with resvg
Animated GIF and APNG playback
Zoom: fit, fill, 100%, custom (5-2000%)
Single, continuous, and dual page view modes
Gallery mode with thumbnail grid
Slideshow with configurable interval (1-30s)
Clickable hyperlinks (internal and external)
Session persistence (zoom, page, position)
IPC control via garviewctl

Quick Start

What is garview?

garview is a feature-rich image and document viewer for the gardesk desktop environment. It handles raster images, SVG, PDF, comics, and eBooks with annotation tools, print support, and session persistence.

Control garview remotely via garviewctl for scripting and automation.

Installation

terminal

$ curl -fsSL https://gar.musicsian.com/install.sh | bash -s -- --component=garview # Install via script

$ cd ~/.local/src/gardesk/garview && cargo build --release # Or build from source

Basic Usage

terminal

$ garview # Open with recent files panel

$ garview /path/to/image.png # Open specific image

$ garview /path/to/document.pdf # Open PDF document

$ garview /path/to/comic.cbz # Open comic archive

$ garview /path/to/directory/ # Open directory in gallery mode

Command-Line Options

terminal

$ garview --fullscreen /path/to/image # Start in fullscreen

$ garview --slideshow /path/to/directory # Start slideshow of directory

$ garview --log /tmp/garview.log /path/to/file # Log to file

$ garview --help # Show all options

Quick Reference

`Ctrl+A`	Enter annotation mode
`Ctrl+P`	Print current document
`Ctrl+E`	Export as PNG/JPEG
`F7`	Toggle sidebar
`Tab`	Toggle gallery mode
`q`	Quit

Configuration

garview is configured via TOML at ~/.config/garview/config.toml.

Full Configuration Example

~/.config/garview/config.toml

$ [general] # General settings

$ default_zoom = "fit" # fit, fill, 1:1, or 100%

$ remember_position = false # Restore scroll position

$ remember_zoom = false # Restore zoom level

$ background_color = "#1a1b26" # Window background

$ [images] # Image settings

$ auto_rotate_exif = true # Auto-rotate by EXIF

$ interpolation = "lanczos" # lanczos, nearest, linear

General Settings

Option	Default	Description
`default_zoom`	"fit"	Initial zoom mode: fit, fill, 1:1, or 100%
`remember_position`	false	Restore scroll position when reopening files
`remember_zoom`	false	Restore zoom level when reopening files
`background_color`	"#1a1b26"	Background color (hex or CSS color)

Image Settings

Option	Default	Description
`auto_rotate_exif`	true	Auto-rotate based on EXIF orientation tag
`interpolation`	"lanczos"	Scaling filter: lanczos, nearest, linear

Data Locations

paths

$ ~/.config/garview/config.toml # Configuration file

$ ~/.local/share/garview/recent.json # Recent files & session state

$ ~/.cache/garview/thumbnails/ # Thumbnail cache

$ $XDG_RUNTIME_DIR/garview.sock # IPC socket

Overview

garview is a unified viewer for images, documents, comics, and eBooks:

Image viewing - Raster images (25+ formats), SVG, and animated GIF/APNG
Document viewing - PDF with text search, selection, form fields, and TOC
Comics - CBZ, CB7, CBT archive formats
eBooks - EPUB and MOBI format support
Annotations - 8 drawing tools with sidecar persistence
Print & Export - Print via CUPS, export to PNG/JPEG

Binaries

• garview - Main viewer application
• garviewctl - IPC control client

View Modes

For multi-page documents, garview supports three layout modes:

Key	Mode	Description
`1`	Single Page	One page at a time (default)
`2`	Continuous	Vertical scroll through all pages
`3`	Dual Page	Side-by-side book-style layout

Press V to cycle through modes.

Drawing Tools

8 annotation tools available in annotation mode (Ctrl+A):

Key	Tool	Description
`b`	Brush	Freehand drawing
`l`	Line	Straight lines
`a`	Arrow	Arrows with head (default)
`r`	Rectangle	Rectangular shapes
`e`	Ellipse	Circles and ellipses
`t`	Text	Text annotations
`x`	Blur	Blur regions
`h`	Highlight	Transparent highlighting

Tool Controls

• +/- - Adjust line width (1-50px)
• f - Toggle fill mode for shapes
• Ctrl+Z/Ctrl+Y - Undo/redo
• Ctrl+Shift+C - Clear all annotations

IPC Protocol

garview exposes an IPC interface via Unix socket. Use garviewctl for command-line control.

Socket Location

socket

$ $XDG_RUNTIME_DIR/garview.sock # Default location

garviewctl Commands

terminal

$ garviewctl open /path/to/file # Open file in running instance

$ garviewctl next # Next page/image

$ garviewctl prev # Previous page/image

$ garviewctl first # First page

$ garviewctl last # Last page

$ garviewctl goto 5 # Go to page 5

$ garviewctl zoom-in # Zoom in

$ garviewctl zoom-out # Zoom out

$ garviewctl zoom-fit # Fit to window

$ garviewctl zoom-set 150 # Set zoom to 150%

$ garviewctl rotate-cw # Rotate clockwise

$ garviewctl rotate-ccw # Rotate counter-clockwise

$ garviewctl flip-h # Flip horizontal

$ garviewctl flip-v # Flip vertical

$ garviewctl fullscreen # Toggle fullscreen

$ garviewctl sidebar # Toggle sidebar

$ garviewctl slideshow-start # Start slideshow

$ garviewctl slideshow-stop # Stop slideshow

$ garviewctl slideshow-interval 5 # Set interval to 5 seconds

$ garviewctl info # Get viewer state

$ garviewctl ping # Check if running

$ garviewctl quit # Quit viewer

Info Response

The info command returns:

json

$ {

$ "pid": 12345, # Process ID

$ "file": "/path/to/current.pdf", # Current file

$ "page": 5, # Current page (1-indexed)

$ "page_count": 24, # Total pages

$ "zoom": 150.0, # Zoom percentage

$ "dimensions": [1920, 1080], # Image dimensions

$ "fullscreen": false, # Fullscreen state

$ "slideshow": false # Slideshow state

$ }

Troubleshooting

PDF rendering errors

PDF support requires poppler library.

• Install: dnf install poppler-devel or apt install libpoppler-dev
• Some corrupted PDFs may cause issues

Annotations not saving

Check file permissions for sidecar files.

• Sidecar files are saved alongside the original
• Ensure write permission to the directory
• Use Ctrl+S to manually save

Print not working

Printing requires CUPS and the lpr command.

• Install CUPS: dnf install cups
• Ensure a printer is configured
• Test with: lpstat -p

garviewctl: connection refused

garview must be running for IPC to work.

• Start garview first: garview &
• Check socket: ls $XDG_RUNTIME_DIR/garview.sock

EPUB/MOBI not rendering

eBook format support requires the epub crate to be compiled in.

• Verify the file isn't DRM-protected (garview cannot read DRM content)
• Try opening with: RUST_LOG=debug garview book.epub to see parsing errors

Image colors look wrong

EXIF auto-rotation or color profile issues.

• Disable EXIF rotation: set auto_rotate_exif = false in config
• Try different interpolation: set interpolation = "nearest" to rule out scaling artifacts

Debug logging

terminal

$ RUST_LOG=debug garview /path/to/file # Full debug

$ RUST_LOG=garview=debug garview /path/to/file # garview only

`Right` / `n`	Next page
`Left` / `p`	Previous page
`Home` / `End`	First / last page
`Ctrl+G`	Go to page dialog

`1`	Red	`6`	Blue
`2`	Orange	`7`	Magenta
`3`	Yellow	`8`	White
`4`	Green	`9`	Black
`5`	Cyan

`Ctrl+F`	Open search bar
`n` / `F3`	Next result
`N`	Previous result
`Escape`	Exit search

`q`	Quit
`F11`	Toggle fullscreen
`F7`	Toggle sidebar
`Tab` / `g`	Toggle gallery mode
`i` / `Ctrl+I`	Properties panel
`Ctrl+R`	Recent files panel
`V`	Cycle view modes (single/continuous/dual)
`r` / `R`	Rotate clockwise / counter-clockwise
`s`	Start/stop slideshow
`[` / `]`	Decrease / increase slideshow interval
`Ctrl+P`	Print
`Ctrl+E`	Export
`Ctrl+Shift+E`	Export with format selection (PNG/JPEG/PDF)

`b/l/a/r/e/t/x/h`	Select tool
`1-9`	Color presets
`+/-`	Line width
`f`	Toggle fill
`Ctrl+Z/Y`	Undo/redo
`Ctrl+S`	Save annotations
`Ctrl+E`	Export annotated
`Escape`	Exit annotation mode

`+` / `=`	Zoom in
`-`	Zoom out
`Ctrl+Scroll`	Zoom at mouse position

garview

Features

Quick Start

What is garview?

Installation

Basic Usage

Command-Line Options

Quick Reference

Configuration

Full Configuration Example

General Settings

Image Settings

Data Locations

Overview

Binaries

Navigation

Zoom

Pan

Pages

Zoom Controls

Zoom Modes

Keyboard Controls

Pan & Scroll

Page Navigation

View Modes

Format Support

Raster Images

Vector & Docs

Comics

eBooks

Raster Images

SVG/SVGZ

PDF Documents

Comics (CBZ/CB7/CBT)

eBooks (EPUB/MOBI)

Annotations

Drawing Tools

Tool Controls

Colors & Styles

Saving & Loading

Saving

Print & Export

Print (Ctrl+P)

Export (Ctrl+E)

Gallery Mode

Slideshow

PDF Features

Text Search

Text Selection

Form Fields

Table of Contents

Sidebar & UI

Thumbnails

TOC

Annotations

Status Bar

Keyboard Shortcuts

General

Annotation Mode (Ctrl+A)

IPC Protocol

Socket Location

garviewctl Commands

Info Response

Troubleshooting

PDF rendering errors

Annotations not saving

Print not working

garviewctl: connection refused

EPUB/MOBI not rendering

Image colors look wrong

Debug logging