diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/superpowers/plans/2026-10-30-upscale-qt.md | 793 |
1 files changed, 793 insertions, 0 deletions
diff --git a/docs/superpowers/plans/2026-10-30-upscale-qt.md b/docs/superpowers/plans/2026-10-30-upscale-qt.md new file mode 100644 index 0000000..9af7600 --- /dev/null +++ b/docs/superpowers/plans/2026-10-30-upscale-qt.md @@ -0,0 +1,793 @@ +# upscale-qt Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Single-file PyQt6 app that upscales one image with `sd-cli`, lets imajev suggest the model, compares before/after with a slider wipe, and saves as new file or overwrites the original. + +**Architecture:** One executable script `upscale-qt` (no `.py`). Module-level pure helpers (model listing, answer matching, argument building, atomic overwrite) are unit tested; `CompareView` paints both images into one transform with a clipped divider; `Main` holds a list of `Job`s (one for now), drives a single `QProcess` for both external tools, and enables actions from state. + +**Tech Stack:** Python 3, PyQt6 (QtCore, QtGui, QtWidgets), external `sd-cli` and optional `llama-mtmd-cli`. + +**Spec:** `docs/superpowers/specs/2026-10-30-upscale-qt-design.md` + +**Deviation from spec, deliberate:** jobs carry no explicit state enum. "Result present" means done, and a running process disables Open/Upscale, so no other state is observable yet. Add the enum with batch mode. + +**EXIF orientation:** stb_image (used by sd-cli) and plain `QImage(path)` ignore EXIF orientation. `load()` reads with `QImageReader.setAutoTransform(True)` and writes an oriented `input.png` into the temp dir; that PNG feeds both sd-cli and imajev, so before, after and the overwritten file all share the upright orientation. Overwrite drops EXIF metadata (Qt does not copy it). + +--- + +## File structure + +- Create `upscale-qt`: the whole app, executable, GPLv2-only header. +- Create `test_upscale_qt.py`: plain-assert tests, loads `upscale-qt` with `SourceFileLoader`, runs offscreen with a throwaway config dir. +- Modify `AGENTS.md` (Testing section), `README.md` (Usage). + +--- + +### Task 1: Pure helpers + +**Files:** +- Create: `upscale-qt` +- Create: `test_upscale_qt.py` + +- [ ] **Step 1: Write the failing tests** + +`test_upscale_qt.py`: + +```python +# upscale-qt - tests for the non-GUI helpers and a GUI smoke test +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License version 2 as +# published by the Free Software Foundation. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License along +# with this program; if not, write to the Free Software Foundation, Inc., +# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +import os +import tempfile +from importlib.machinery import SourceFileLoader +from importlib.util import module_from_spec, spec_from_loader + +TMP = tempfile.mkdtemp(prefix='upscale-qt-test-') +os.environ['QT_QPA_PLATFORM'] = 'offscreen' +os.environ['XDG_CONFIG_HOME'] = os.path.join(TMP, 'config') + +HERE = os.path.dirname(os.path.abspath(__file__)) +_loader = SourceFileLoader('upscale_qt', os.path.join(HERE, 'upscale-qt')) +uq = module_from_spec(spec_from_loader('upscale_qt', _loader)) +_loader.exec_module(uq) + +from PyQt6.QtGui import QColor, QImage, QImageReader # noqa: E402 + +NAMES = ['4x_detail.pth', 'RealESRGAN_x4plus.pth', + 'RealESRGAN_x4plus_anime_6B.pth'] + + +def test_match_model(): + m = uq.match_model + # the longer stem must win over its own prefix + assert m('RealESRGAN_x4plus_anime_6B.pth', NAMES) == 'RealESRGAN_x4plus_anime_6B.pth' + assert m(' realesrgan_x4plus\n', NAMES) == 'RealESRGAN_x4plus.pth' + assert m('I suggest 4x_detail.', NAMES) == '4x_detail.pth' + assert m('no idea', NAMES) is None + assert m('', []) is None + + +def test_list_models(): + d = os.path.join(TMP, 'models') + os.makedirs(d) + for f in ('b.safetensors', 'a.pth', 'notes.txt', 'c.GGUF'): + open(os.path.join(d, f), 'w').close() + assert uq.list_models(d) == ['a.pth', 'b.safetensors', 'c.GGUF'] + assert uq.list_models(os.path.join(TMP, 'missing')) == [] + + +def test_args(): + a = uq.sd_args('/m/x.pth', '/in.png', '/out.png') + assert a == ['-M', 'upscale', '--upscale-model', '/m/x.pth', + '-i', '/in.png', '-o', '/out.png'] + a = uq.llama_args('/m.gguf', '/mm.gguf', '/in.png', NAMES) + assert a[a.index('--image') + 1] == '/in.png' + prompt = a[a.index('-p') + 1] + assert all(n in prompt for n in NAMES) + assert 'noise' in prompt + + +def test_save_over(): + path = os.path.join(TMP, 'photo.JPG') # uppercase suffix on purpose + small = QImage(4, 4, QImage.Format.Format_RGB32) + small.fill(QColor('red')) + assert small.save(path, 'jpeg') + big = QImage(16, 16, QImage.Format.Format_RGB32) + big.fill(QColor('blue')) + assert uq.save_over(big, path) + assert QImage(path).width() == 16 + assert bytes(QImageReader.imageFormat(path)) == b'jpeg' + assert not os.path.exists(path + '.part') + + +if __name__ == '__main__': + for name, fn in list(globals().items()): + if name.startswith('test_'): + fn() + print('ok', name) +``` + +- [ ] **Step 2: Run, expect failure** + +Run: `python3 test_upscale_qt.py` +Expected: `FileNotFoundError` for `upscale-qt`. + +- [ ] **Step 3: Write the helpers** + +`upscale-qt` (then `chmod +x upscale-qt`): + +```python +#!/usr/bin/env python3 +# upscale-qt - upscale an image with sd-cli and compare before/after +# Copyright (C) 2026 Danilo M. <danix@danix.xyz> +# +# This program is free software; you can redistribute it and/or modify +# it under the terms of the GNU General Public License version 2 as +# published by the Free Software Foundation. +# +# This program is distributed in the hope that it will be useful, +# but WITHOUT ANY WARRANTY; without even the implied warranty of +# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +# GNU General Public License for more details. +# +# You should have received a copy of the GNU General Public License along +# with this program; if not, write to the Free Software Foundation, Inc., +# 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA. + +import os +import sys +from pathlib import Path + +from PyQt6.QtGui import QImage, QImageReader + +MODEL_EXTS = ('.pth', '.safetensors', '.gguf') +JPEG_QUALITY = 95 +PROMPT = ( + 'You pick an image upscaler model. Judge the subject (photo of people, ' + 'landscape, anime, illustration) and also the source quality: noise, ' + 'JPEG compression, blur. Noisy or compressed sources need a denoising ' + 'model, clean sources a detail-preserving one. Answer with exactly one ' + 'filename from this list and nothing else: {names}') + + +def list_models(folder): + try: + return sorted(f for f in os.listdir(folder) + if f.lower().endswith(MODEL_EXTS)) + except OSError: + return [] + + +def match_model(answer, names): + """Map imajev's free-text answer to one of names, or None. + + Longest stem first, so 'x4plus_anime_6B' is not taken for 'x4plus'.""" + answer = answer.lower() + for name in sorted(names, key=lambda n: len(Path(n).stem), reverse=True): + if Path(name).stem.lower() in answer: + return name + return None + + +def sd_args(model, src, out): + return ['-M', 'upscale', '--upscale-model', model, '-i', src, '-o', out] + + +def llama_args(model, mmproj, src, names): + return ['-m', model, '--mmproj', mmproj, '--image', src, + '--temp', '0', '-n', '64', + '-p', PROMPT.format(names=' '.join(names))] + + +def save_over(img, path): + """Replace path with img in the original's format, never truncating it.""" + fmt = bytes(QImageReader.imageFormat(path)).decode() or None + part = path + '.part' + if not img.save(part, fmt, JPEG_QUALITY if fmt == 'jpeg' else -1): + if os.path.exists(part): + os.remove(part) + return False + os.replace(part, path) + return True +``` + +- [ ] **Step 4: Run, expect pass** + +Run: `python3 test_upscale_qt.py` +Expected: four `ok test_...` lines. + +- [ ] **Step 5: Commit** + +```bash +git add upscale-qt test_upscale_qt.py +git commit # "Add model matching, argument and overwrite helpers" +``` + +--- + +### Task 2: CompareView + +**Files:** +- Modify: `upscale-qt` (imports, new class after helpers) +- Modify: `test_upscale_qt.py` (append test) + +- [ ] **Step 1: Write the failing test** + +Append before the `if __name__` block: + +```python +from PyQt6.QtWidgets import QApplication # noqa: E402 + +APP = QApplication.instance() or QApplication([]) + + +def test_compare_view(): + before = QImage(10, 10, QImage.Format.Format_RGB32) + before.fill(QColor('red')) + after = QImage(40, 40, QImage.Format.Format_RGB32) + after.fill(QColor('blue')) + v = uq.CompareView() + v.resize(200, 200) + v.set_images(before, after) + shot = v.grab().toImage() + # left of the divider shows before, right shows after + assert shot.pixelColor(50, 100) == QColor('red') + assert shot.pixelColor(150, 100) == QColor('blue') +``` + +- [ ] **Step 2: Run, expect failure** + +Run: `python3 test_upscale_qt.py` +Expected: `AttributeError: module 'upscale_qt' has no attribute 'CompareView'`. + +- [ ] **Step 3: Implement** + +Replace the Qt import lines at the top of `upscale-qt` with: + +```python +from PyQt6.QtCore import QPointF, QRectF, Qt +from PyQt6.QtGui import QColor, QImage, QImageReader, QPainter, QPen +from PyQt6.QtWidgets import QWidget +``` + +Add after `save_over`: + +```python +class CompareView(QWidget): + """Before left of a draggable divider, after right, one shared transform. + + Before is drawn into after's rectangle, so it is scaled on paint, never + copied at 4x size.""" + + GRAB = 8 # px around the divider that start a divider drag + + def __init__(self): + super().__init__() + self.before = self.after = None + self.split = 0.5 + self.scale = 1.0 + self.offset = QPointF() + self.drag = None + self.setMouseTracking(True) + self.setMinimumSize(400, 300) + + def set_images(self, before, after=None): + self.before, self.after = before, after + self.fit() + + def ref(self): + return self.after if self.after is not None else self.before + + def fit(self): + img = self.ref() + if img is not None: + self.scale = min(self.width() / img.width(), + self.height() / img.height()) + self.offset = QPointF((self.width() - img.width() * self.scale) / 2, + (self.height() - img.height() * self.scale) / 2) + self.update() + + def divider_x(self): + return self.split * self.width() + + def paintEvent(self, e): + p = QPainter(self) + p.fillRect(self.rect(), QColor(40, 40, 40)) + img = self.ref() + if img is None: + return + if self.scale >= 0.5: + # ponytail: smooth only near 1:1, smoothing a 160 MP image + # scaled down to screen size stalls the paint + p.setRenderHint(QPainter.RenderHint.SmoothPixmapTransform) + target = QRectF(self.offset.x(), self.offset.y(), + img.width() * self.scale, img.height() * self.scale) + if self.after is None: + p.drawImage(target, self.before) + return + x = self.divider_x() + p.setClipRect(QRectF(0, 0, x, self.height())) + p.drawImage(target, self.before) + p.setClipRect(QRectF(x, 0, self.width() - x, self.height())) + p.drawImage(target, self.after) + p.setClipping(False) + p.setPen(QPen(QColor('white'), 2)) + p.drawLine(QPointF(x, 0), QPointF(x, self.height())) + + def near_divider(self, pos): + return self.after is not None and abs(pos.x() - self.divider_x()) < self.GRAB + + def mousePressEvent(self, e): + self.drag = 'split' if self.near_divider(e.position()) else e.position() + + def mouseMoveEvent(self, e): + pos = e.position() + if self.drag == 'split': + self.split = min(max(pos.x() / self.width(), 0.0), 1.0) + elif self.drag is not None: + self.offset += pos - self.drag + self.drag = pos + self.setCursor(Qt.CursorShape.SplitHCursor if self.drag == 'split' + or self.near_divider(pos) else Qt.CursorShape.ArrowCursor) + self.update() + + def mouseReleaseEvent(self, e): + self.drag = None + + def mouseDoubleClickEvent(self, e): + self.fit() + + def wheelEvent(self, e): + f = 1.25 if e.angleDelta().y() > 0 else 0.8 + pos = e.position() + self.offset = pos - (pos - self.offset) * f # zoom around the cursor + self.scale *= f + self.update() + + def resizeEvent(self, e): + self.fit() # ponytail: resize resets zoom, keep the view center if it annoys +``` + +- [ ] **Step 4: Run, expect pass** + +Run: `python3 test_upscale_qt.py` +Expected: five `ok` lines. + +- [ ] **Step 5: Commit** + +```bash +git add upscale-qt test_upscale_qt.py +git commit # "Add slider-wipe compare view" +``` + +--- + +### Task 3: Main window + +**Files:** +- Modify: `upscale-qt` (imports, `DEFAULTS`, `Job`, `SettingsDialog`, `Main`, `main()`) +- Modify: `test_upscale_qt.py` (append smoke test) + +- [ ] **Step 1: Write the failing test** + +Append before the `if __name__` block: + +```python +def test_main_window(): + w = uq.Main() + w.cfg.setValue('imajev_model', '') # never run the real VLM in tests + w.cfg.setValue('upscalers_dir', os.path.join(TMP, 'models')) + w.reload_models() + assert not w.a_up.isEnabled() # no image yet + path = os.path.join(TMP, 'in.png') + img = QImage(8, 6, QImage.Format.Format_RGB32) + img.fill(QColor('green')) + img.save(path) + w.load(path) + assert len(w.jobs) == 1 and w.jobs[0].image.size() == img.size() + assert os.path.exists(w.jobs[0].input) + assert w.a_up.isEnabled() and not w.a_save.isEnabled() +``` + +`test_list_models` must run first: it creates the `models` folder this test points at (the runner keeps definition order). + +- [ ] **Step 2: Run, expect failure** + +Run: `python3 test_upscale_qt.py` +Expected: `AttributeError: module 'upscale_qt' has no attribute 'Main'`. + +- [ ] **Step 3: Implement** + +Replace the Qt imports with: + +```python +import shutil +from dataclasses import dataclass + +from PyQt6.QtCore import QPointF, QProcess, QRectF, QSettings, QTemporaryDir, Qt +from PyQt6.QtGui import (QAction, QColor, QImage, QImageReader, QKeySequence, + QPainter, QPen) +from PyQt6.QtWidgets import (QApplication, QComboBox, QDialog, + QDialogButtonBox, QFileDialog, QFormLayout, + QLineEdit, QMainWindow, QMessageBox, QWidget) +``` + +(keep `import os`, `import sys`, `from pathlib import Path` above them). + +Add after `JPEG_QUALITY`: + +```python +DEFAULTS = { + 'upscalers_dir': '/data/LLM-models/SD/upscalers', + 'imajev_model': '/data/LLM-models/SD/imajev/imajev-4b-Q4_K_M.gguf', + 'imajev_mmproj': '/data/LLM-models/SD/imajev/imajev-4b-mmproj-f16.gguf', +} +``` + +Add after `save_over`, before `CompareView`: + +```python +def tail(data, lines=15): + text = bytes(data).decode(errors='replace').replace('\r', '\n') + return '\n'.join([l for l in text.splitlines() if l.strip()][-lines:]) + + +@dataclass +class Job: + path: str # file the user opened, overwrite target + image: QImage # original, EXIF orientation applied + input: str # oriented PNG fed to sd-cli and imajev + model: str = '' + out: str = '' + result: QImage | None = None +``` + +Add after `CompareView`: + +```python +class SettingsDialog(QDialog): + def __init__(self, parent, cfg): + super().__init__(parent) + self.setWindowTitle('Settings') + self.cfg = cfg + self.edits = {k: QLineEdit(str(cfg.value(k, v))) for k, v in DEFAULTS.items()} + form = QFormLayout(self) + form.addRow('Upscalers folder', self.edits['upscalers_dir']) + form.addRow('imajev model (.gguf)', self.edits['imajev_model']) + form.addRow('imajev mmproj (.gguf)', self.edits['imajev_mmproj']) + bb = QDialogButtonBox(QDialogButtonBox.StandardButton.Ok + | QDialogButtonBox.StandardButton.Cancel) + bb.accepted.connect(self.accept) + bb.rejected.connect(self.reject) + form.addRow(bb) + + def accept(self): + for k, e in self.edits.items(): + self.cfg.setValue(k, e.text().strip()) + super().accept() + + +class Main(QMainWindow): + def __init__(self, path=None): + super().__init__() + self.setWindowTitle('upscale-qt') + self.resize(1200, 800) + self.cfg = QSettings('upscale-qt', 'upscale-qt') + self.tmp = QTemporaryDir() + self.jobs = [] # one job for now, batch mode adds more + self.cur = None + self.runs = 0 # unique temp file names + self.what = None # 'suggest' or 'upscale' while a process runs + self.err = b'' + + self.view = CompareView() + self.setCentralWidget(self.view) + self.models = QComboBox() + self.models.setSizeAdjustPolicy(QComboBox.SizeAdjustPolicy.AdjustToContents) + self.models.setToolTip('Upscaler model') + + tb = self.addToolBar('main') + tb.setMovable(False) + + def act(text, slot, key=None): + a = QAction(text, self) + a.triggered.connect(slot) + if key is not None: + a.setShortcut(key) + tb.addAction(a) + return a + + self.a_open = act('Open', self.open_dialog, QKeySequence.StandardKey.Open) + tb.addWidget(self.models) + self.a_up = act('Upscale', self.upscale, 'Ctrl+U') + self.a_save = act('Save As', self.save_as, QKeySequence.StandardKey.SaveAs) + self.a_over = act('Overwrite', self.overwrite) + act('Settings', self.settings) + + self.proc = QProcess(self) + self.proc.finished.connect(self.proc_done) + self.proc.errorOccurred.connect(self.proc_error) + self.proc.readyReadStandardError.connect(self.proc_stderr) + + self.reload_models() + if path: + self.load(path) + + def get(self, key): + return str(self.cfg.value(key, DEFAULTS[key])) + + def job(self): + return self.jobs[self.cur] if self.cur is not None else None + + def names(self): + return [self.models.itemText(i) for i in range(self.models.count())] + + def reload_models(self): + keep = self.models.currentText() + self.models.clear() + self.models.addItems(list_models(self.get('upscalers_dir'))) + if keep: + self.models.setCurrentText(keep) + self.refresh() + + def refresh(self): + busy = self.what is not None + job = self.job() + done = job is not None and job.result is not None + self.a_open.setEnabled(not busy) + self.models.setEnabled(not busy) + self.a_up.setEnabled(job is not None and not busy and self.models.count() > 0) + self.a_up.setToolTip('Upscale' if self.models.count() else + f'No models in {self.get("upscalers_dir")}, see Settings') + self.a_save.setEnabled(done and not busy) + self.a_over.setEnabled(done and not busy) + + def open_dialog(self): + path, _ = QFileDialog.getOpenFileName( + self, 'Open image', str(self.cfg.value('last_dir', str(Path.home()))), + 'Images (*.png *.jpg *.jpeg *.webp *.bmp *.tif *.tiff);;All files (*)') + if path: + self.load(path) + + def load(self, path): + r = QImageReader(path) + r.setAutoTransform(True) + img = r.read() + if img.isNull(): + QMessageBox.warning(self, 'upscale-qt', f'Cannot read {path}:\n{r.errorString()}') + return + self.runs += 1 + src = self.tmp.filePath(f'in{self.runs}.png') + if not img.save(src): + QMessageBox.warning(self, 'upscale-qt', f'Cannot write temp file {src}') + return + self.jobs = [Job(path, img, src)] + self.cur = 0 + self.cfg.setValue('last_dir', str(Path(path).parent)) + self.setWindowTitle(f'upscale-qt - {Path(path).name}') + self.view.set_images(img) + self.statusBar().showMessage(f'{img.width()}x{img.height()}') + self.refresh() + self.suggest() + + def run(self, what, prog, args, msg): + self.what, self.err = what, b'' + self.statusBar().showMessage(msg) + self.refresh() + self.proc.start(prog, args) + + def suggest(self): + model, mmproj = self.get('imajev_model'), self.get('imajev_mmproj') + if not (self.names() and os.path.isfile(model) and os.path.isfile(mmproj) + and shutil.which('llama-mtmd-cli')): + return # suggestion is optional, skip quietly + self.run('suggest', 'llama-mtmd-cli', + llama_args(model, mmproj, self.job().input, self.names()), + 'imajev is looking at the image...') + + def upscale(self): + job = self.job() + job.model = self.models.currentText() + self.runs += 1 + job.out = self.tmp.filePath(f'out{self.runs}.png') + self.run('upscale', 'sd-cli', + sd_args(os.path.join(self.get('upscalers_dir'), job.model), + job.input, job.out), + f'Upscaling with {job.model}...') + + def proc_stderr(self): + self.err = (self.err + bytes(self.proc.readAllStandardError()))[-8000:] + if self.what == 'upscale': + last = tail(self.err, 1) + if last: + self.statusBar().showMessage(last) + + def proc_done(self, code, status): + what, self.what = self.what, None + ok = code == 0 and status == QProcess.ExitStatus.NormalExit + job = self.job() + if what == 'suggest': + answer = bytes(self.proc.readAllStandardOutput()).decode(errors='replace') + pick = match_model(answer, self.names()) if ok else None + if pick: + self.models.setCurrentText(pick) + self.statusBar().showMessage(f'imajev suggests {pick}') + else: + self.statusBar().showMessage('imajev gave no usable suggestion') + elif what == 'upscale': + img = QImage(job.out) if ok else QImage() + if img.isNull(): + self.statusBar().showMessage('Upscale failed') + QMessageBox.warning(self, 'Upscale failed', tail(self.err) or f'exit code {code}') + else: + job.result = img + self.view.set_images(job.image, img) + self.statusBar().showMessage( + f'{job.image.width()}x{job.image.height()} -> ' + f'{img.width()}x{img.height()} with {job.model}') + self.refresh() + + def proc_error(self, err): + if err != QProcess.ProcessError.FailedToStart: + return # crashes also emit finished, handled there + what, self.what = self.what, None + prog = self.proc.program() + if what == 'upscale': + QMessageBox.warning(self, 'upscale-qt', f'Cannot start {prog}: is it installed?') + self.statusBar().showMessage(f'Cannot start {prog}') + self.refresh() + + def save_as(self): + job = self.job() + src = Path(job.path) + path, _ = QFileDialog.getSaveFileName( + self, 'Save upscaled image', str(src.with_name(f'{src.stem}_x4{src.suffix}')), + 'Images (*.png *.jpg *.jpeg *.webp *.tif *.tiff)') + if not path: + return + if job.result.save(path, None, JPEG_QUALITY): + self.statusBar().showMessage(f'Saved {path}') + else: + QMessageBox.warning(self, 'upscale-qt', f'Cannot save {path}') + + def overwrite(self): + job = self.job() + r = job.result + if QMessageBox.question( + self, 'Overwrite', + f'Replace {job.path}\nwith the {r.width()}x{r.height()} upscaled image?\n' + 'This cannot be undone.') != QMessageBox.StandardButton.Yes: + return + if save_over(r, job.path): + self.statusBar().showMessage(f'Overwrote {job.path}') + else: + QMessageBox.warning(self, 'upscale-qt', f'Cannot write {job.path}, original untouched') + + def settings(self): + if SettingsDialog(self, self.cfg).exec(): + self.reload_models() + + def closeEvent(self, e): + if self.proc.state() != QProcess.ProcessState.NotRunning: + self.proc.kill() + self.proc.waitForFinished(2000) + super().closeEvent(e) + + +def main(): + app = QApplication(sys.argv) + w = Main(sys.argv[1] if len(sys.argv) > 1 else None) + w.show() + sys.exit(app.exec()) + + +if __name__ == '__main__': + main() +``` + +- [ ] **Step 4: Run, expect pass** + +Run: `python3 test_upscale_qt.py` +Expected: six `ok` lines. + +- [ ] **Step 5: Commit** + +```bash +git add upscale-qt test_upscale_qt.py +git commit # "Add main window: open, suggest, upscale, save as, overwrite" +``` + +--- + +### Task 4: Real run, docs + +**Files:** +- Modify: `AGENTS.md` (Testing) +- Modify: `README.md` (Usage) + +- [ ] **Step 1: End-to-end headless run with the real tools** + +Script in the scratchpad (not the repo), run with +`XDG_CONFIG_HOME=<scratch>/cfg QT_QPA_PLATFORM=offscreen python3 -I <script>`: + +```python +import os, sys +from importlib.machinery import SourceFileLoader +from importlib.util import module_from_spec, spec_from_loader +from PyQt6.QtCore import QEventLoop +from PyQt6.QtGui import QImage, QColor +from PyQt6.QtWidgets import QApplication + +loader = SourceFileLoader('uq', os.path.expanduser('~/Programming/GIT/upscale-qt/upscale-qt')) +uq = module_from_spec(spec_from_loader('uq', loader)); loader.exec_module(uq) +app = QApplication([]) +w = uq.Main(); w.resize(1000, 700); w.show() + +def wait(): + loop = QEventLoop(); w.proc.finished.connect(loop.quit); loop.exec() + w.proc.finished.disconnect(loop.quit) + +src = sys.argv[1] # a ~512 px test image +w.load(src); wait() # imajev suggestion +print('suggested:', w.models.currentText(), '|', w.statusBar().currentMessage()) +w.upscale(); wait() +r = w.jobs[0].result +print('result:', r.width(), r.height(), w.statusBar().currentMessage()) +w.grab().save(sys.argv[2]) +``` + +Expected: a suggestion from the folder, result 4x the input size, screenshot shows the divider with before on the left. Check the screenshot by eye. + +- [ ] **Step 2: Manual check by the user** + +`./upscale-qt <photo>`: drag divider, wheel zoom, drag pan, double-click fit, Save As, Overwrite on a copy. + +- [ ] **Step 3: Docs** + +`AGENTS.md`, replace `No test suite yet.` with: + +```markdown + python3 test_upscale_qt.py + +Plain asserts for the helpers plus offscreen smoke tests of `CompareView` +and `Main`. The test sets `XDG_CONFIG_HOME` to a temp dir and blanks the +imajev path, so it never touches the real settings or runs the VLM. For an +end-to-end check with the real tools, load the script with +`SourceFileLoader` under `QT_QPA_PLATFORM=offscreen`, call `load()` and +`upscale()`, wait on `proc.finished`, and `grab()` a screenshot. Use a +small image: about 25 s per input megapixel. +``` + +`README.md`, replace the Usage section body with: + +```markdown + ./upscale-qt [image] + +- Open an image (Ctrl+O or as argument). If imajev is configured it looks at the image and preselects an upscaler, you can always pick another. +- Upscale (Ctrl+U) runs `sd-cli`. Expect roughly 25 seconds per megapixel of input; the result is 4x in each direction. +- The view shows before left of the divider and after right of it. Drag the divider to wipe, drag elsewhere to pan, mouse wheel to zoom, double-click to fit. +- Save As (Ctrl+Shift+S) writes a new file; Overwrite replaces the original after a confirmation, in the same format. EXIF metadata is not kept. +- Settings holds the upscalers folder and the imajev model and mmproj paths. +``` + +- [ ] **Step 4: Commit and push** + +```bash +git add AGENTS.md README.md +git commit # "Document usage and testing" +git push +``` |