Krolyxon
Branch master

Branches

Tags

Refs →

remageREADME.md

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