Krolyxon
Commit 8b10288

Branches

Tags

Refs →

remageREADME.md

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