Metadata-Version: 2.4
Name: imaegete
Version: 0.1.11
Summary: A FOSS image viewer built with PyQt6
Author: Aaron Colichia
License-Expression: 0BSD
Project-URL: Homepage, https://latebrum.com/git/actx/Imaegete/
Project-URL: Repository, https://latebrum.com/git/actx/Imaegete/
Keywords: image-viewer,pyqt6,sway,lxqt
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: X11 Applications :: Qt
Classifier: Intended Audience :: End Users/Desktop
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Topic :: Multimedia :: Graphics :: Viewers
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: Pillow>=10
Requires-Dist: PyQt6>=6.7
Requires-Dist: PyYAML>=6.0
Requires-Dist: colorama>=0.4
Requires-Dist: confuse>=2.0
Requires-Dist: typing-extensions>=4.0
Requires-Dist: natsort>=8.4
Requires-Dist: packaging>=24
Requires-Dist: psutil>=6.0
Requires-Dist: watchfiles>=0.21
Requires-Dist: GlavnaQt==0.2.2
Requires-Dist: confumo==0.2.2
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == "dev"
Requires-Dist: twine>=6.0; extra == "dev"
Requires-Dist: pytest>=8.0; extra == "dev"
Requires-Dist: pytest-qt>=4.4; extra == "dev"
Requires-Dist: pyfakefs>=5.7; extra == "dev"
Dynamic: license-file

# Imaegete

A FOSS image viewer built with PyQt6.

Imaegete is currently packaged and tested as a Linux desktop application. Some Qt-backed internals are portable, but Linux is the supported release target for published wheels.

![Floodfill + rapid slideshow demo](https://latebrum.com/downloads/actx/Imaegete/latest/imaegete-demo.gif)

## 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

```bash
# from PyPI
pip install imaegete

# from source (development)
# canonical source: https://latebrum.com/git/actx/Imaegete/
# public mirror:    https://codeberg.org/aaron_colichia/Imaegete
cd Imaegete
pip install -r requirements-dev.txt
pip install -e .
```

## Usage

```bash
imaegete [options] [paths...]
```

Examples:

```bash
# 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`

### Declarative GlavnaQt layouts

Imaegete uses GlavnaQt's data-only layout layer for its default chrome. A custom YAML/TOML layout can be loaded with:

```bash
imaegete --layout-file layout.yaml
```

During development, add hot reload:

```bash
imaegete --layout-file layout.yaml --dev-layout-hot-reload
```

Layout files describe sections only. Runtime widgets, including the image canvas, remain owned by Imaegete and are reattached by section name during layout compilation/reload.

## 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.

- 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

This repository ships under 0BSD; see `LICENSE`.

## Licensing / provenance notice

This repository may include AI-generated material and minimal human-authored
material. To the extent any portion of this repository is not copyrightable, it
is made available without restriction.

No bundled third-party source files or assets were identified in the shipped
source tree during the current audit. External runtime/build dependencies are
not vendored into this repository and remain subject to their own licenses.
