ack/rectify
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs: give Linux and Windows equal footing; hyphenate every shortcut label

Browse Source 
Documentation:

- The GUI is stated as the primary interface on every platform; the
  earlier claim that Linux is CLI-first is gone.
- §2.1 becomes "Installing Rectify" with macOS, Linux, and Windows
  subsections, each opening with the public clone of this repository and
  the per-session launch commands.
- §3.1's Linux section reaches the depth the Windows one already had:
  python3-venv (stock Debian/Ubuntu fails `python3 -m venv` without it),
  libxcb packages, QT_QPA_PLATFORM=xcb as the Wayland fallback, a
  PYTHONPATH wrapper for launching from any directory, and a .desktop
  entry. States plainly that Linux has no packaged deliverable.
- §2.15 lists all three settings paths; §2.3 covers the platform-specific
  Open dialog and HEIC thumbnails; Finder/Mac-only phrasing generalized.
- README gains a matching Linux section, and its "pre-built executables"
  section no longer promises Linux and Windows binaries that were never
  published.

Keyboard notation:

- Both documents print the macOS symbols throughout, with one
  substitution rule (Ctrl for ⌘, Alt for ⌥) stated in the guide's §2
  preamble and under each shortcut table.
- Every combination is joined with a hyphen on all platforms — ⌘-O,
  Ctrl-O, ⇧-⌘-Z, ⌥-⇧ — rather than Apple's tight ⌘O, whose glyphs have
  side bearings too small to separate them from the next character.
- shortcuts.py carries this in SECTIONS and _mac_translate; gui.py's
  tooltip modifier follows. Display labels only: the QKeySequence
  bindings keep Qt's "Ctrl+X" syntax and are untouched.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
This commit is contained in:
Andy Kopra
2026-08-07 17:49:35 +02:00
parent fb80764e66
commit 1a139da884
4 changed files with 348 additions and 107 deletions
Download Patch File Download Diff File Expand all files Collapse all files

248
doc/Rectify_user_guide.md
View File

@@ -31,7 +31,7 @@ This guide is divided into four parts:
- [1.4 A word about color](#14-a-word-about-color)
- [1.5 Two ways to use Rectify](#15-two-ways-to-use-rectify)
- [2. Using Rectify](#2-using-rectify)
- [2.1 Installing Rectify on macOS](#21-installing-rectify-on-macos)
- [2.1 Installing Rectify](#21-installing-rectify)
- [2.2 The main window](#22-the-main-window)
- [2.3 Opening images](#23-opening-images)
- [2.4 How detection works, and the vocabulary](#24-how-detection-works-and-the-vocabulary)
@@ -185,14 +185,18 @@ from the ground up, and the earlier sections link to it where useful.
Rectify is one program with two front ends:
- **The graphical application (GUI)** is the primary way to use it, and the
subject of [§2](#2-using-rectify). It is interactive: you see the detected
region, drag it into place, and watch the corrected result update live. On
macOS it is delivered as a ready-to-run `Rectify.dmg`.
- **The graphical application (GUI)** is the primary way to use Rectify on every
platform, and the subject of [§2](#2-using-rectify). It is interactive: you see
the detected region, drag it into place, and watch the corrected result update
live. On macOS it is delivered as a ready-to-run `Rectify.dmg`; on Linux and
Windows you run it from source and launch it with `python -m rectify --gui`
(see [§2.1](#21-installing-rectify)). The window and every feature in it are
identical on all three.
- **The command line (CLI)** drives the same engine without a window, for
scripting and batch processing. On Linux, where Rectify is run from source, the
command line is the primary way to interact with it. The CLI is documented in
[§3.3](#33-the-command-line-interface).
scripting and batch processing — correcting a whole folder of photos in a loop,
for instance, without touching the GUI at all. It is available on all three
platforms (on macOS from the source tree, not the app bundle) and is documented
in [§3.3](#33-the-command-line-interface).
## 2. Using Rectify
@@ -202,7 +206,28 @@ photography either; the later ones (aspect ratio, bow, color) assume you are
comfortable with ordinary photographic ideas, and point you to the
[primer in §4.14](#414-color-theory-primer) when a deeper concept comes up.
### 2.1 Installing Rectify on macOS
Everything here applies equally to macOS, Linux, and Windows — the window, the
controls, and the gestures are the same on all three. Only two things differ:
how you install and launch the program ([§2.1](#21-installing-rectify)), and the
names of two keys.
**How keys are written in this guide.** Shortcuts are printed throughout with the
macOS symbols, **⌘** (Command) and **⌥** (Option). **If you are on Linux or
Windows, press Ctrl wherever this guide shows ⌘, and Alt wherever it shows ⌥** —
so ⌘-O means Ctrl-O, ⌘-Click means Ctrl-Click, and Shift-⌥ means Shift-Alt. That
single substitution is the whole difference; no shortcut exists on one system and
not another. Rectify labels its own tooltips and its shortcut overlay for the
system you are actually on, so what you see on screen always matches your
keyboard.
### 2.1 Installing Rectify
Rectify is delivered in two forms: as a ready-to-run application on macOS, and as
source code you run with Python on Linux and Windows. Pick the section for your
system; from [§2.2](#22-the-main-window) onward the guide is the same for
everyone.
#### macOS — the Rectify application
You have been given a file named **`Rectify.dmg`**. To install:
@@ -223,6 +248,65 @@ confirm; you only need to do this once.
Rectify runs on both Apple-silicon (M-series) and Intel Macs. There is nothing
else to install — everything it needs is inside the app.
#### Linux — from source
There is no packaged download for Linux; you fetch the source once, install its
Python dependencies into a self-contained folder, and launch the same GUI from a
terminal. It is about five commands, and you only do it once.
Start by cloning the public repository — no account, login, or permission is
needed:
```bash
git clone https://git.andykopra.com/ack/rectify.git
cd rectify
```
You can also browse it in a web browser at
<https://git.andykopra.com/ack/rectify/>, and download it there as a ZIP if you
would rather not use `git`. From that point, the step-by-step instructions —
including the two or three things that can go wrong on a fresh machine — are in
[§3.1](#31-installation), written to be followed without any Python knowledge.
Afterwards, each session starts like this:
```bash
cd ~/rectify # wherever you put the source
source .venv/bin/activate
python -m rectify --gui # or: python -m rectify --gui photo.jpg
```
[§3.1](#31-installation) also shows how to reduce that to a single command you
can type anywhere, or to a desktop icon you click. Once the window is open,
everything from [§2.2](#22-the-main-window) onward applies unchanged.
#### Windows — from source
Windows works the same way: there is no installer, you run the program from
source. Every component ships as a ready-built Windows package, so nothing has to
be compiled and no system libraries are needed.
Start by cloning the public repository — no account, login, or permission is
needed. In PowerShell:
```powershell
git clone https://git.andykopra.com/ack/rectify.git
cd rectify
```
You can also browse it in a web browser at
<https://git.andykopra.com/ack/rectify/> and use its download button to get a ZIP
instead, which avoids installing `git` at all. From that point, full instructions
are in [§3.1](#31-installation).
Afterwards, each session starts like this, in PowerShell:
```powershell
cd ~\rectify
.\.venv\Scripts\Activate.ps1
python -m rectify --gui # or: python -m rectify --gui photo.jpg
```
### 2.2 The main window
When Rectify opens, the window has five areas, top to bottom:
@@ -270,7 +354,8 @@ displays.
There are several ways to load a photo:
- Click **Open** (or press **⌘-O**) and choose a file.
- **Drag an image file** from the Finder directly onto the Rectify window.
- **Drag an image file** from your file manager (Finder, Explorer, Files, …)
directly onto the Rectify window.
- Once an image is open, press **⌘-↓ / ⌘-↑** to step to the **next / previous**
image in the same folder (it wraps around at the ends). This is the fast way to
work through a folder of photos — each one is detected fresh as it loads.
@@ -284,6 +369,12 @@ tone are already applied — color correction works on the residual cast, not ra
sensor data (see the [primer](#414-color-theory-primer)). Saved output is always
one of the standard formats; HEIC is read-only.
The **Open** dialog itself is your system's own: Finder's panel on macOS,
Explorer's on Windows, and your desktop's file chooser on Linux. Its *thumbnails*
therefore come from the system, not from Rectify — so on an older Linux
distribution HEIC files may show a generic icon even though Rectify opens them
perfectly well. A one-time fix is in [§3.1](#31-installation).
When an image loads, Rectify immediately evaluates the detection and shows you the
best result — the green quadrilateral on the left, the straightened result on the
right. From there you refine by hand as needed.
@@ -730,15 +821,17 @@ Because each image's edits live in this per-image memory, you can prepare a whol
set in one session — adjusting corners, lines, bow, color, and aspect on each —
just by stepping between them with ⌘-↑/↓, without saving to disk between switches.
The preferences file is stored per-user, so multiple users on one Mac keep
independent settings:
The preferences file is stored per-user, so several people sharing one computer
keep independent settings:
| Platform | Location |
|---|---|
| macOS | `~/Library/Application Support/<username>/Rectify/settings.json` |
| Linux | `~/.local/share/<username>/Rectify/settings.json` |
| Windows | `%APPDATA%\<username>\Rectify\settings.json` |
(It is plain JSON and can be edited by hand if you ever need to, though normally
you never will. The Linux location is noted in [§3.1](#31-installation).)
you never will. Deleting it resets Rectify to a first-run state.)
### 2.16 Keyboard shortcuts
@@ -755,14 +848,28 @@ you never will. The Linux location is noted in [§3.1](#31-installation).)
| Space (hold) | Show the original in the right panel (before/after) |
| Arrow keys | Nudge the selected corner, edge, or whole quad |
| Mouse wheel | Zoom (or adjust the element under the cursor with Shift held) |
| Shift + wheel | Adjust the quad element under the cursor |
| ⌘ + Left-click | Snap the nearest point to the click position |
| Right-click | Reset zoom on the clicked panel |
| Shift-wheel | Adjust the quad element under the cursor |
| ⌘-Left-click | Snap the nearest point to the click position |
| ⌥-click ×2 | Draw an alternate-line annotation between two clicks |
| Right-click (or ⌃-click) | Reset zoom on the clicked panel |
| 0 | Reset zoom on both panels |
| Esc | Clear temporary marks |
| Shift+Option (hold) | Show the keyboard-shortcut overlay (release to dismiss) |
| Shift-⌥ (hold) | Show the keyboard-shortcut overlay (release to dismiss) |
Hold **Shift+Option** at any time to see this table without leaving the window.
**On Linux and Windows:** read **Ctrl** for ⌘ and **Alt** for ⌥ throughout the
table — ⌘-O is Ctrl-O, ⌘-click is Ctrl-click, Shift-⌥ is Shift-Alt. Everything
else is identical.
Hold **Shift-⌥** at any time to see this table without leaving the window, with
the key names for the system you are on. The same table is printed by
`rectify -k` from the command line.
Two macOS-only details are worth knowing. **⌘-click** snaps the nearest point,
while **⌃-click** — the *physical* Control key — is simply how a Mac delivers a
right-click on a one-button mouse or trackpad, and so resets the panel's zoom.
And where a combination includes Shift, the on-screen overlay follows Apple's
ordering and puts it first, as ⇧-⌘-Z and ⌥-⇧ — the same keys as the ⌘-Shift-Z
and Shift-⌥ written above, listed in the other order.
### 2.17 When automatic detection struggles
@@ -803,26 +910,42 @@ program is built and operated, and it links to
#### macOS (the app)
For day-to-day use on a Mac, install the supplied `Rectify.dmg` exactly as in
[§2.1](#21-installing-rectify-on-macos) — drag the app to Applications. That bundle
[§2.1](#21-installing-rectify) — drag the app to Applications. That bundle
is a self-contained build (Python, Qt, and OpenCV included) and needs nothing
else. To *develop* on macOS instead, follow the from-source steps below; they work
on macOS with Homebrew or python.org Python (Apple silicon and Intel).
#### Linux (from source)
On Linux, Rectify is run from source, and the **command line is the primary way to
interact with it** (the GUI is available too, and behaves as described in §2).
Linux is the platform Rectify is developed on, so it is the best-tested of the
three — but there is no packaged download the way macOS has its `.dmg`. You run
it from source, and the **GUI is the primary interface here as everywhere else**
(the CLI in [§3.3](#33-the-command-line-interface) is the same engine without a
window, for scripting and batch work).
**Prerequisites:** Python 3.10 or later, `pip`, and `git`.
**Prerequisites:** Python 3.10 or later, `pip`, `git`, and a graphical desktop.
Development happens on Ubuntu with GNOME; any current distribution with those
pieces works, and nothing below is Ubuntu-specific except the `apt` command
lines, which have direct equivalents in `dnf`, `pacman`, and `zypper`.
1. **Obtain the source tree.**
1. **Clone the public repository.** It is open to everyone — no account, login,
or permission is required, and it can be browsed (and downloaded as a ZIP) at
<https://git.andykopra.com/ack/rectify/>.
```bash
git clone https://git.andykopra.com/ack/rectify.git
cd rectify
```
2. **Create a virtual environment and install dependencies:**
2. **Make sure Python can create virtual environments.** Debian and Ubuntu ship
Python without this piece, and step 3 fails with `ensurepip is not available`
if it is missing:
```bash
sudo apt install python3-venv python3-pip
```
3. **Create a virtual environment and install dependencies:**
```bash
python3 -m venv .venv
@@ -832,20 +955,16 @@ interact with it** (the GUI is available too, and behaves as described in §2).
This pulls in OpenCV, NumPy, PySide6 (Qt), Pillow, and `pillow-heif` (HEIC/HEIF
reading — it bundles its own `libheif`, so no system library is required).
Everything lands inside `.venv/`; nothing is installed system-wide, and
deleting the source folder removes all of it.
3. **Qt system libraries.** If PySide6 fails to start, install the X11/XCB
4. **Qt system libraries.** If PySide6 fails to start, install the X11/XCB
libraries Qt needs. On Ubuntu/Debian:
```bash
sudo apt install libxcb-xinerama0 libxcb-cursor0
```
4. **(Optional) HEIC thumbnails in the file chooser.** Rectify reads HEIC
regardless, but the **Open** dialog's thumbnails come from your desktop, which
on older distributions can't render iPhone HDR HEICs. Run
`scripts/install_heic_thumbnailer.sh` once to enable them (it self-skips if your
system already handles HEIC).
5. **Run it:**
```bash
@@ -856,9 +975,55 @@ interact with it** (the GUI is available too, and behaves as described in §2).
python -m rectify photo.jpg -o rectified.jpg # CLI, no window
```
6. **(Optional) HEIC thumbnails in the file chooser.** Rectify reads HEIC
regardless, but the **Open** dialog's thumbnails come from your desktop, which
on older distributions can't render iPhone HDR HEICs. Run
`scripts/install_heic_thumbnailer.sh` once to enable them (it self-skips if your
system already handles HEIC).
**Launching without the two-step dance.** The virtual environment's own
interpreter can run Rectify directly, so a one-line wrapper lets you start it
from any directory, with relative filenames intact. Save this as
`~/bin/rectify` and `chmod +x` it, substituting your own path:
```bash
#!/bin/sh
exec env PYTHONPATH="$HOME/rectify" "$HOME/rectify/.venv/bin/python" \
-m rectify "$@"
```
Then `rectify --gui photo.jpg` works anywhere. For a clickable icon, point a
desktop entry at that wrapper — save the following as
`~/.local/share/applications/rectify.desktop`:
```ini
[Desktop Entry]
Type=Application
Name=Rectify
Exec=/home/YOUR_USER/bin/rectify --gui %f
Terminal=false
Categories=Graphics;Photography;
MimeType=image/jpeg;image/png;image/tiff;image/webp;image/bmp;image/heif;
```
It then appears in your application menu, and images can be opened with it from
the file manager.
**If the window misbehaves on Wayland.** Qt picks Wayland automatically in a
Wayland session. If Rectify fails to start, or the window's sizing, cursors, or
tooltip placement look wrong there, force the X11 path for one run:
```bash
QT_QPA_PLATFORM=xcb python -m rectify --gui
```
If that fixes it, put `export QT_QPA_PLATFORM=xcb` in the wrapper script above.
This is worth trying first for any display-related oddity, particularly on NVIDIA
drivers, where Wayland compositor bugs are still common.
On Linux the per-user settings file lives at
`~/.local/share/<username>/Rectify/settings.json` (the macOS path is in
[§2.15](#215-what-rectify-remembers)).
`~/.local/share/<username>/Rectify/settings.json`; all three platforms' paths are
listed in [§2.15](#215-what-rectify-remembers).
#### Windows (from source)
@@ -873,7 +1038,10 @@ the standard Explorer dialog, complete with image thumbnails.
python.exe to PATH"** ticked. `git` is optional — the repository can be
downloaded as a ZIP instead.
1. **Obtain the source tree and create a virtual environment.** In PowerShell:
1. **Clone the public repository and create a virtual environment.** The
repository is open to everyone — no account, login, or permission is required,
and it can be browsed (and downloaded as a ZIP, if you would rather not
install `git`) at <https://git.andykopra.com/ack/rectify/>. In PowerShell:
```powershell
git clone https://git.andykopra.com/ack/rectify.git
@@ -1012,7 +1180,8 @@ python -m rectify --gui photo.jpg --debug my_debug.log # custom path, GU
```
**Keyboard reference:** `rectify -k` (also `--keyboard`) prints the shortcut table
(the same one the GUI shows on Shift+Option).
(the same one the GUI shows on Shift-⌥), with the key names of whichever system
it is run on.
**Note:** color correction ([§2.12](#212-color-correction)) is interactive —
it depends on clicking a reference in the image — so it is a GUI-only feature; the
@@ -1091,11 +1260,12 @@ Connect them to detection or display methods via Qt signals, and wrap programmat
updates in `blockSignals(True/False)` to avoid cascading recomputation. See
[§4.13](#413-gui-architecture-internals).
**Diagnostic aids built into the GUI.** `Ctrl+Shift+E` toggles a Canny edge-detection
**Diagnostic aids built into the GUI.** `⇧-⌘-E` toggles a Canny edge-detection
overlay on the left panel (red edges over the source, using the grayscale
defaults) — useful for seeing what the detector sees. `Ctrl+Shift+Delete` (or
`Ctrl+Shift+Backspace`) clears the settings cache and resets all controls to
defaults. Two environment variables draw layout-debugging overlays for GUI work:
defaults) — useful for seeing what the detector sees. `⇧-⌘-Delete` (or
`⇧-⌘-Backspace`) clears the settings cache and resets all controls to
defaults. (As everywhere in this guide, read those as `Ctrl-Shift-E` and
`Ctrl-Shift-Delete` on Linux and Windows.) Two environment variables draw layout-debugging overlays for GUI work:
`RECTIFY_DEBUG_BORDERS=1` outlines every widget, and `RECTIFY_DEBUG_BASELINES=1`
draws a red line at each text widget's baseline.