You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Refract is a guided image conversion tool written in [Rust](https://www.rust-lang.org/) for x86-64 Linux systems with [GTK](https://www.gtk.org/)`v3.22.30` or later.
8
+
Refract is a cross-platform[\*](#installation) guided image conversion tool.
9
9
10
-
It takes [JPEG](https://en.wikipedia.org/wiki/JPEG) and [PNG](https://en.wikipedia.org/wiki/Portable_Network_Graphics) image sources and produces [AVIF](https://en.wikipedia.org/wiki/AV1#AV1_Image_File_Format_(AVIF)), [JPEG XL](https://en.wikipedia.org/wiki/JPEG_XL), and [WebP](https://en.wikipedia.org/wiki/WebP)clones.
10
+
It takes [JPEG](https://en.wikipedia.org/wiki/JPEG) and [PNG](https://en.wikipedia.org/wiki/Portable_Network_Graphics) image sources and produces [AVIF](https://en.wikipedia.org/wiki/AV1#AV1_Image_File_Format_(AVIF)), [JPEG XL](https://en.wikipedia.org/wiki/JPEG_XL), and [WebP](https://en.wikipedia.org/wiki/WebP)copies.
11
11
12
-
<imgsrc="https://github.com/Blobfolio/refract/raw/master/skel/gallery/screen0.png"width="30%"alt="The start screen. Nice and clean."></img> <imgsrc="https://github.com/Blobfolio/refract/raw/master/skel/gallery/screen1.png"width="30%"alt="Viewing a PNG source image."></img> <imgsrc="https://github.com/Blobfolio/refract/raw/master/skel/gallery/screen2.png"width="30%"alt="Previewing a WebP candidate to Discard or Keep."></img>
12
+
13
13
14
-
The program works like an eye doctor Refraction Test. It generates candidate images at various qualities, asking at each step how it looks, and uses the feedback (you provide) to arrive at the smallest possible "acceptable" output.
14
+
The program is named for and works something like an optometrist's refraction test, presenting a series of feedback-driven candidate images — what looks better, this… or this? This… or this? — until the subjective "best" option is found (or found to be impossible).
15
15
16
16
Hence "guided".
17
17
18
-
The beauty of this approach is that it moots the need for exhaustive testing. Refract's quality stepping works by selecting the mid-point between moving min/max boundaries. Similar to a binary search, each answer you provide halves the range of remaining possibilities, allowing the final, perfect result to be discovered in just 5-10 steps instead of 100+.
18
+
The beauty of this sort of approach is it moots the need for exhaustive testing.
19
19
20
+
Every Yay and Nay you provide halve the number of possibilities remaining to be tested. The ideal copy, whatever and wherever it might be, can be found in a handful of steps instead of a hundred.
20
21
21
22
22
-
## Why?
23
-
24
-
Every image is different. The idea of a "Magic Bullet" format is a myth.
25
-
26
-
If you want to truly maximize the quality and size of next-gen copies, you cannot rely on hardcoded constants or automated [SSIM](https://en.wikipedia.org/wiki/Structural_similarity) analysis; your images would come out over- or under-compressed.
27
23
28
-
You have to actually _use your eyes_. And you have to pay attention to the resulting file sizes. Sometimes newer formats will result in _larger_ output than the original source, defeating the purpose. Haha.
29
-
30
-
While you can do all of this manually — running multiple programs hundreds of times for each and every source you want to convert — that would be incredibly tedious and easy to screw up.
24
+
## Why?
31
25
32
-
Refract helps make that manual process _less_ tedious and _more_ foolproof.
26
+
Every image is different.
33
27
34
-
It automatically uses the strongest (slowest) possible compression settings for each format, keeps track of file sizes and qualities along the way, supports batch processing, and reduces the number of conversion tests by around 90%.
28
+
There is no such thing as a one-size-fits-all quality setting, or even a one-size-fits-all image format.
35
29
36
-
Should you use it for every image ever?
30
+
Whether you're looking for perfect copies or merely passable ones, the only way to be sure you're not producing over- or under-compressed images is to _use your eyes_.
37
31
38
-
No, probably not.
32
+
Done manually, you'd need to use a lot more — your brain, for starters — but thankfully most of the rest of the process _can_ be automated.
39
33
40
-
The next generation formats, particularly AVIF and JPEG XL, require a lot of computation to eek out their extra byte savings. All those minutes will add up quickly.
34
+
That's where refract comes in.
41
35
42
-
But if you're looking to obsessively optimize a small project or single web page, Refract is definitely the way to go!
36
+
It keeps track of the details so you don't have to.
43
37
44
38
45
39
@@ -48,47 +42,63 @@ But if you're looking to obsessively optimize a small project or single web page
48
42
| Format | Decoding (Input/Display) | Encoding (Output) |
49
43
| ------ | -------- | -------- |
50
44
| JPEG | Yes, except CMYK and 16-bit lossless. ||
51
-
| PNG | Yes*||
45
+
| PNG | Yes ||
52
46
| AVIF | Yes | Lossless, lossy, `RGB`, and `YCbCr`|
53
47
| JPEG XL | Yes*| Lossless, lossy. |
54
48
| WebP | Yes*| Lossless, lossy. |
55
49
56
-
*Refract does not support animated images. Without going too far down _that_ rabbit hole, let's just say that if GIF can't handle the job, it should be a video, not an image.
57
-
58
-
In other words, Refract takes JPEG and PNG sources — either individual files or entire directory trees — and turns them into AVIF, JPEG XL, and/or WebP outputs.
50
+
In short, Refract takes JPEG and PNG sources — either individual files or entire directory trees — and turns them into AVIF, JPEG XL, and/or WebP outputs.
59
51
60
52
Refract implements [`libavif`](https://github.com/AOMediaCodec/libavif), [`libjxl`](https://github.com/libjxl/libjxl), and [`libwebp`](https://chromium.googlesource.com/webm/libwebp/) directly. This not only ensures full standards compliance and feature/performance parity with each format's official conversion tools — `avifenc`, `cjxl`, and `cwebp` respectively — it also means you don't need any of that crap separately installed to use it.
61
53
62
54
All conversion takes place at Pixel Level and is intended for displays with an sRGB color space (e.g. web browsers). Gamma correction, color profiles, and other metadata are ignored and stripped out when saving next-gen copies.
63
55
56
+
All conversions are performed using the maximum/slowest (general) encoder settings, ensuring the smallest possible output. Refract also explicitly tracks the input and output file sizes to save you having to review counter-productive combinations.
57
+
64
58
65
59
66
60
## Usage
67
61
68
62
Refract is pretty straightforward:
69
63
70
-
1. Tweak the settings — via the `Settings` menu — as desired.
71
-
2. Load a single image or an entire directory. You can either use the links in the `File` menu, or drag-and-drop images straight onto the window from your file browser.
72
-
3. Sit back and wait for any feedback or save prompts.
64
+
0. Open the program;
65
+
1. Choose the output format(s) and tweak any other settings you want;
66
+
2. Choose one or more JPEG/PNG source files to crunch;
67
+
3. Sit back and wait for the feedback prompts;
68
+
69
+
### Feedback
70
+
71
+
Lossless conversions require no human supervision. Being lossless, all that really matters is that shit gets smaller, and refract can figure _that_ out on its own. ;)
72
+
73
+
Lossy conversions are another matter since, by their very nature, information is lost in translation.
74
+
75
+
For those, refract will present a series of "candidate" images to you, one at a time, in a simple A/B fashion for easy comparison with the original sources.
76
+
77
+
The "feedback" comes in the form of two buttons — "reject" and "accept" — which can be thought of as answers to the question: Are you happy with this copy?
73
78
74
-
For best results, be sure to optimize your input sources before re-encoding them with Refract. (The CLI tool [flaca](https://github.com/Blobfolio/flaca) is great for this, and fully automatic.)
79
+
If it looks like what you want it to, great!, accept it. If not, reject it. Refract will raise or lower the quality of the next candidate accordingly.
75
80
76
-
For keyboard aficionados, the following hot-keys may be used:
81
+
Rinse and repeat.
77
82
78
-
| Action | Key(s) |
79
-
| ------ | ------ |
80
-
| Open File |`CTRL + o`|
81
-
| Open Directory |`SHIFT + CTRL + o`|
82
-
| Toggle Dark Mode |`CTRL + n`|
83
-
| Toggle A/B View |`SPACE`|
84
-
| Discard Candidate |`d`|
85
-
| Keep Candidate |`k`|
83
+
The smallest of the accepted candidates, if any, will be saved to disk at the end of the process, the rest forgotten like a passing dream.
84
+
85
+
Then it's back around again for the next input/output pair!
86
+
87
+
### Pro Tip
88
+
89
+
JPEG and PNG are actually quite _good_ and, properly encoded, can provide _better_ compression than some — or all — of the possible next-gen alternatives.
90
+
91
+
(This is especially true for lossless conversions; a well-optimized PNG is _not_ something you'd want to meet in a dark alley!)
92
+
93
+
For best — or at least more honest — results, take some time to optimize your sources with a tool like [flaca](https://github.com/Blobfolio/flaca/)_before_ feeding them to refract.
94
+
95
+
Two things are twice as many things as one thing,<sup>\[citation needed\]</sup> but being the obsessive person you are — normal people wouldn't be doing _either_ — you'll sleep better knowing no bytes have gone unsaved.
86
96
87
97
88
98
89
99
## CLI Usage
90
100
91
-
Refract is a _graphical_ program, but when launching from the command line, you can override the default settings and/or queue up images to re-encode.
101
+
Refract is a graphical program, but the startup settings and/or queue can be configured via command line if desired.
Note: The flags only affect the initial program state. All settings can still be managed through the program's dropdown menus after launch.
117
+
|`--save-auto`| Automatically save successful conversions to their source paths — with new extensions appended — instead of popping a file dialogue for confirmation. |
109
118
110
119
| Option | Description |
111
120
| ------ | ----------- |
112
121
|`-l` / `--list`| Read (absolute) image and/or directory paths from this text file, one path per line. Set to "-" to read from STDIN. This is equivalent to specifying the same paths as trailing arguments, but can be cleaner if there are lots of them. |
113
122
114
-
When image and/or directory paths are passed as trailing arguments (`<PATH(S)>...`), and/or the `-l`/`--list` option is used, Refract will start crunching all valid sources as soon as the program launches.
115
-
116
123
117
124
118
125
## Installation
119
126
120
-
Debian and Ubuntu users can just grab the pre-built `.deb` package from the [release page](https://github.com/Blobfolio/refract/releases/latest).
127
+
Pre-built packages for x86-64 CPU architectures are available for Debian and Ubuntu users on the [release page](https://github.com/Blobfolio/refract/releases/latest), and to Arch Linux users via [AUR](https://aur.archlinux.org/packages/refract-bin).
121
128
122
-
Arch Linux users can install Refract via [AUR](https://aur.archlinux.org/packages/refract-bin) (community-maintained).
129
+
To use refract in other environments, it'll needs to be built from source.
123
130
124
-
While specifically written for use on x86-64 Linux systems, both Rust and GTK3 are cross-platform, so you may well be able to build it from source on other 64-bit Unix systems using `Cargo`:
131
+
Thankfully, [Rust](https://www.rust-lang.org/)/[Cargo](https://github.com/rust-lang/cargo) make this pretty easy:
# Build with Cargo. Feel free to add other build flags as desired.
134
-
cargo build --release
135
-
```
146
+
The extra build dependencies (required by all the damn image codecs) will vary by environment, but at a minimum you'll need up-to-date C and C++ compilers, `cmake`, `git` (obviously), `make`, `nasm`, and `ninja-build`.
136
147
137
-
Cargo _will_ handle the entire build process for you, however many of Refract's dependencies have heavy `build.rs` scripts requiring additional system libraries. (Who'd have thought image decoders and encoders were complicated?!)
148
+
Cargo should pop an error if anything's missing. If that happens, just find/install the missing dep and give `cargo install` another shot.
138
149
139
-
At a minimum, you'll need up-to-date versions of:
150
+
If you wind up needing something not on this list, please [open an issue](https://github.com/Blobfolio/refract/issues) so it can be given a mention. ;)
140
151
141
-
* Cmake
142
-
*`gcc`/`g++`
143
-
* Git
144
-
* Make
145
-
* NASM
146
-
* Ninja
147
-
* Rust/Cargo
152
+
### Runtime Dependencies
148
153
149
-
GTK3 is a whole other monster, requiring the `-dev` packages for (at least) ATK, Cairo, GDK, GLIB, GTK, Pango, and Pixbuf. Thankfully, many distributions offer meta packages to make GTK dependency resolution easier. On Debian Bullseye, for example, installing `librust-gtk-dev` and `librust-gdk-dev` should just about cover everything.
154
+
On Linux, the file dialogues require one of `xdg-desktop-portal-[gnome, gtk, kde]` or `zenity`, user's choice.
150
155
151
-
[This post](https://github.com/Blobfolio/refract/issues/3#issuecomment-1086924244) provides a good breakdown of how to set up a minimal Docker build environment for Refract.
156
+
In theory, _None of the Above_ should work too, provided you use the CLI to enqueue image paths and enable automatic saving with the `--save-auto` flag (along with any other settings tweaks you might want):
152
157
153
-
If you end up building Refract on a non-Debian system — Red Hat, MacOS, etc. — please let us know what that setup looked like so we can update the docs. Users of those systems will no doubt appreciate it. :)
0 commit comments