imaegete 0.1.1

A FOSS image viewer built with PyQt6

Imaegete

A FOSS image viewer built with PyQt6.

Features

• Fast keyboard-driven navigation
• Zoom + pan
• Animated GIF support
• Slideshow with tap-tempo
• On-disk metadata cache + in-memory pixmap cache
• Folder watching (auto-refresh when files change)
• Vim-inspired command mode (:) and filename search (/)
• Category sorting (move current image into configured folders)

Install

# from PyPI
pip install imaegete

# from source (development)
git clone https://github.com/actx4gh/Imaegete.git
cd Imaegete
pip install -r requirements-dev.txt
pip install -e .

Usage

imaegete [options] [paths...]

Examples:

# scan a directory
imaegete ~/Pictures

# open a single file (also uses its parent directory as the effective root)
imaegete ~/Pictures/foo.jpg

# playlist/selection-only mode: open exactly these files (no directory scanning)
imaegete 0.jpg 1.jpg 2.jpg

Playlist mode (multi-select)

If you launch Imaegete with multiple file paths (for example via a file manager “Open With” multi-select), it runs in selection-only / playlist mode:

• the image list is exactly the argv file list (deduped, order preserved)
• folder scanning does not run
• watchers may refresh/notice deletions, but will not inject unrelated files

Common options

• --start_dirs DIR [DIR ...] scan one or more folders (default: .)
• --categories CAT [CAT ...] category folder names (enables move-to-category keys)
• --sort_dir DIR base directory to create category folders in (defaults to start_dirs)
• --cache_dir DIR cache location (default: ~/.config/Imaegete/cache)
• --cache_size MB cache size in MB
• --clear_cache clear cache and exit

For the full CLI: imaegete --help

Controls

Keyboard shortcuts

All shortcuts below are active in normal mode (i.e. when you are not typing into the : or / bars). Press Esc to leave command/search and return to normal mode.

Action	Key
Next image	Right / j
Previous image	Left / k
First image	Home / gg
Last image	End / G
Random image / toggle shuffle mode	R
Toggle slideshow	S
Slideshow/GIF/flood-zoom speed up	]
Slideshow/GIF/flood-zoom speed down	[
Zoom in	+
Zoom out	-
Reset zoom (fit-to-window)	=
Flood-zoom (auto-zoom) toggle	\\
Toggle fullscreen	F
Delete current image	Delete
Undo last delete/move	U
Move to category 1..9 (if configured)	1 … 9
Enter command mode	:
Enter filename search	/
Exit command/search bars	Esc
Quit	Q

Mouse

• Zoom: mouse wheel
• Pan: left-click + drag (only when zoomed in past “fit to window”)

Slideshow tap-tempo

While slideshow is running, manual navigation taps set the interval:

• two taps establish a tempo; additional taps refine it
• direction changes reset the tap sequence
• taps time out after inactivity

Keys that count as taps: Right/j (next), Left/k (previous), R (random).

Category moves

If you pass --categories (or set categories in config), you can move the current image into a category folder:

• press 1..9 to move to the corresponding category (first 9 only)
• or use :m <category> / :m <N> in command mode

Vim-style modes

Command mode (:)

Type : to open the command bar, then press Enter.

• :q / :quit / :exit — quit
• :n / :next — next image
• :p / :prev / :previous — previous image
• :first / :last / :rand (:random) — jump
• :del / :delete / :rm — delete current image
• :u / :undo — undo last move/delete
• :m <category> or :m <N> — move to category by name or 1-based index
• :fs (:fullscreen) — toggle fullscreen
• :ss (:slideshow) [on/off] — toggle or set slideshow
• :<N> — jump to 1-based index (e.g. :12)

Filename search (/)

Type / to open the search bar.

• start typing to live-filter the image list
• select from the popup list (mouse or keyboard) and press Enter
• Esc exits search without jumping

License

AGPLv3 (see LICENSE)