Krolyxon
Commit 4654f72

Branches

Tags

Refs →

remageREADME.md

218 lines · 9.8 KB · Markdown

Raw Blame History Download
1<div align="center">
2 <img src="docs/logo.svg" width="360" alt="remage">
3 <p>A keyboard-centric image viewer for Linux. Fast, quiet and vim-shaped.</p>
4
5[![CI](https://img.shields.io/github/actions/workflow/status/krolyxon/remage/ci.yml?branch=master&style=flat-square&label=CI&labelColor=000000)](https://github.com/krolyxon/remage/actions/workflows/ci.yml)
6[![Top language](https://img.shields.io/github/languages/top/krolyxon/remage?style=flat-square&logo=rust&logoColor=white&labelColor=000000&color=333333)](https://github.com/krolyxon/remage)
7[![Lines of code](https://img.shields.io/badge/lines%20of%20code-17.5k-333333?style=flat-square&labelColor=000000)](src)
8[![License](https://img.shields.io/github/license/krolyxon/remage?style=flat-square&labelColor=000000&color=333333)](LICENSE)
9[![Platform](https://img.shields.io/badge/platform-Linux%20(Wayland%20%7C%20X11)-333333?style=flat-square&labelColor=000000)](#install)
10[![Renderer](https://img.shields.io/badge/GPU-wgpu-D71921?style=flat-square&labelColor=000000)](https://wgpu.rs)
11[![nsxiv](https://img.shields.io/badge/replaces-nsxiv-333333?style=flat-square&labelColor=000000)](https://codeberg.org/nsxiv/nsxiv)
12[![Last commit](https://img.shields.io/github/last-commit/krolyxon/remage?style=flat-square&labelColor=000000&color=333333)](https://github.com/krolyxon/remage/commits)
13
14</div>
15
16remage aims for nsxiv's feature set with vim-style control and a Nothing OS look. It draws with the
17GPU, so zooming, panning and scrolling stay smooth, and it uses no CPU at all while the picture
18stands still. It can take its colours from your wallpaper through matugen or pywal, and you script
19it with plain shell commands and an IPC socket.
20
21<p align="center">
22 <img src="docs/screenshots/image.jpg" width="820" alt="remage showing a painting of a torii gate under cherry blossoms, with the filename on the left of the status bar and format, size, zoom and position on the right">
23</p>
24
25<table>
26 <tr>
27 <td width="50%"><img src="docs/screenshots/grid.jpg" alt="The thumbnail grid with three marked images and the cursor on one"></td>
28 <td width="50%"><img src="docs/screenshots/palette.jpg" alt="The command palette fuzzy-matching 'fit' over actions and their keys"></td>
29 </tr>
30 <tr>
31 <td align="center"><sub>Thumbnail grid with marks</sub></td>
32 <td align="center"><sub><code>:</code> command palette</sub></td>
33 </tr>
34</table>
35
36-----
37
38## Features
39
40- **Fast.** The first image is on screen in about 90 ms. Neighbours are decoded and uploaded ahead
41 of time, so `n` and `p` take a single frame. Rendering happens only on demand.
42- **Keyboard first.** Vim key notation, sequences (`gg`, `<Space>w`) and counts (`5n`, `12G`).
43 Every feature is an action you can bind, run from the `:` palette or send over IPC. Which-key
44 shows what a pending prefix can do, and `?` lists the live keymap.
45- **Thumbnail grid.** Shares the freedesktop thumbnail cache with your file manager, so thumbnails
46 are often there already. Visual mode marks ranges.
47- **Many formats.** JPEG, PNG/APNG, GIF, WebP, JPEG XL, AVIF, HEIC, SVG, TIFF (multi-page), camera
48 RAW, OpenEXR/HDR and more. Animations play with their own timing. ICC colour profiles and EXIF
49 orientation are applied, and images larger than the GPU's texture limit are tiled. Anything
50 else can go through an external decoder such as ImageMagick.
51- **Scripting.** User commands replace nsxiv's key-handler: placeholders, marks as targets, inline
52 confirmation and output fed back as actions. An old key-handler works unchanged.
53- **IPC.** `remage msg next`, `remage msg --query marked` and `remage msg --subscribe image` from
54 Hyprland binds or scripts.
55- **Themeable.** Three colours are enough, and the rest are derived. matugen and pywal recolour
56 open windows live when the wallpaper changes.
57- **Configurable.** One TOML file with live reload, `file:line:col` errors and "did you mean"
58 suggestions.
59
60## Install
61
62### Arch Linux
63
64A `remage-git` PKGBUILD lives in [`contrib/PKGBUILD`](contrib/PKGBUILD):
65
66```bash
67git clone https://github.com/krolyxon/remage
68cd remage/contrib
69makepkg -si
70```
71
72It installs the binary, the man page, zsh/bash/fish completions and a desktop file.
73
74### From source
75
76You need stable Rust (1.96 or newer). AVIF and HEIC use two system libraries:
77
78```bash
79sudo pacman -S dav1d libheif # Arch
80sudo apt install libdav1d-dev libheif-dev # Debian/Ubuntu (libheif ≥ 1.17)
81
82cargo install --locked --git https://github.com/krolyxon/remage
83```
84
85Without those libraries, build with the pure-Rust formats only:
86
87```bash
88cargo install --locked --git https://github.com/krolyxon/remage --no-default-features --features jxl,svg,raw
89```
90
91Shell completions and the man page are generated by the binary:
92
93```bash
94remage completions zsh > ~/.local/share/zsh/site-functions/_remage # also bash, fish, elvish
95remage man > ~/.local/share/man/man1/remage.1
96```
97
98## Usage
99
100```bash
101remage # the current directory
102remage photo.jpg # photo.jpg and the rest of its directory
103remage -rt ~/Pictures # a whole tree, starting in the grid
104remage -S=3 wallpapers/ # slideshow, 3 seconds per image
105find . -name '*.png' | remage -i -o > picked.txt # pick images, print the marked ones on exit
106remage --dump-config # the complete commented default config
107```
108
109`remage --help` lists every option, and `man remage` covers keys, actions and IPC.
110
111## Keys
112
113The defaults below can all be changed. `?` shows the live keymap inside remage.
114
115| | Keys |
116|---|---|
117| **Everywhere** | `n`/`p` next/previous · `[`/`]` ±10 · `gg`/`G`/`12G` first/last/goto · `<CR>` image ⇄ grid · `m` mark · `M` invert marks · `u` unmark all · `N`/`P` next/previous mark · `f` fullscreen · `b` status bar · `i` info · `s` slideshow · `r` reload · `D` remove from queue · `:` palette · `/` search · `?` help · `q` quit |
118| **Image** | `hjkl` pan · `HJKL` jump to edge · `+`/`-`/`=` zoom in/out/100% · `w`/`W`/`e`/`E` fit/fill/width/height · `z` centre · `<`/`>` rotate · `\|`/`_` flip · `a` pixel filter · `A` transparency background · `{`/`}` gamma · `<C-Space>` play/pause · `<C-n>`/`<C-p>` frames · wheel zooms at the cursor, drag pans |
119| **Grid** | `hjkl` move · `<C-d>`/`<C-u>` half page · `<C-f>`/`<C-b>` page · `0`/`$` row start/end · `+`/`-` thumbnail size · `v` visual mode, then `m` to mark the range · click selects, double-click opens |
120
121## Configuration
122
123remage reads `~/.config/remage/config.toml`. The file is merged over the built-in defaults, so put
124in only what you change. Edits apply as soon as you save, and `remage --check-config` validates
125the file. [`contrib/config.example.toml`](contrib/config.example.toml) is a good start.
126
127```toml
128[image]
129fit = "down" # down | fit | fill | width | height | original
130alpha_background = "dots" # dots | checker | solid
131
132[grid]
133size = 160
134
135[keys.image]
136"<C-ScrollUp>" = "next"
137"D" = "none" # remove a default binding
138```
139
140### Commands
141
142Commands run asynchronously and act on the marked files, or on the current one when nothing is
143marked. Bind them as `run <name>`; unbound ones still show up in the `:` palette.
144
145```toml
146[commands.delete]
147desc = "Delete files"
148run = ["rm", "--", "{files}"] # array: run directly, {files} becomes one arg per file
149confirm = "Delete {count} file(s)?" # asks inline in the status bar: y / n
150
151[commands.copy]
152desc = "Copy image"
153run = "wl-copy --type image/png < {file}" # string: run through sh, placeholders are quoted
154
155[commands.legacy] # an nsxiv key-handler works as it is
156run = ["~/.config/nsxiv/exec/key-handler", "w"]
157stdin = "files"
158
159[keys.global]
160"<Space>d" = "run delete"
161"<Space>c" = "run copy"
162```
163
164After a command succeeds, remage re-checks the files it touched by default. Deleted files leave
165the queue and edited ones are decoded again, so delete and rotate scripts need no extra setup.
166With `output = "actions"`, each line the command prints runs as an action.
167
168### Theming
169
170`nothing-dark` (the default) and `nothing-light` are built in. Any theme needs only `background`,
171`foreground` and `accent`; the other tokens are derived.
172
173- **matugen:** copy [`contrib/matugen/remage.toml`](contrib/matugen/remage.toml) into your matugen
174 templates (the file says how), then add `include = ["~/.cache/matugen/remage.toml"]` to your
175 config. Every wallpaper change recolours open windows.
176- **pywal:** set `[theme] pywal = "~/.cache/wal/colors.json"`.
177
178## Scripting over IPC
179
180Each instance listens on `$XDG_RUNTIME_DIR/remage/<pid>.sock` and speaks newline-delimited JSON.
181`remage msg` talks to the newest instance (or `$REMAGE_SOCKET`, or `--pid`).
182
183```bash
184remage msg next 5 # any action
185remage msg --query marked # current | marked | queue | state
186remage msg --subscribe image # one JSON line per change
187
188# Hyprland
189bind = SUPER, bracketright, exec, remage msg next
190```
191
192## Formats
193
194| Format | Through |
195|---|---|
196| JPEG, PNG/APNG, GIF, WebP, BMP, ICO, TIFF, TGA, PNM, QOI, DDS, HDR, OpenEXR | `image` |
197| JPEG XL | `jxl-oxide` |
198| AVIF | `dav1d` (system library) |
199| HEIC / HEIF | `libheif` (system library) |
200| SVG / SVGZ | `resvg`, re-rendered sharp at every zoom level |
201| Camera RAW (CR2, CR3, NEF, ARW, DNG, RAF, ORF, RW2 …) | `rawler`, embedded preview first |
202| Anything else | `[[decoders]]`, e.g. `magick "{file}[0]" png:-` for PSD and XCF |
203
204## Development
205
206```bash
207cargo run --release -- ~/Pictures
208cargo fmt --check && cargo clippy --all-targets -- -D warnings && cargo test
209RUST_LOG=remage=debug cargo run --release # startup and first-frame timings
210REMAGE_SNAPSHOT=/tmp/x.png remage … # also write each settled frame to a PNG
211```
212
213`tests/fixtures/make.sh` regenerates the decoder fixtures.
214
215## License
216
217remage is licensed under the [GNU AGPL v3](LICENSE). The embedded fonts (Space Grotesk, Space
218Mono and Doto) are under the [SIL Open Font License](assets/fonts/OFL.txt).