setiastrosuitepro 1.6.12__py3-none-any.whl → 1.7.1.post2__py3-none-any.whl

setiastro/saspro/remove_green.py

@@ -164,7 +164,7 @@ class RemoveGreenDialog(QDialog):
 
     def _build_ui(self):
         lay = QVBoxLayout(self)
-        lay.addWidget(QLabel(self.tr("Select the amount to remove green noise:")))
+        lay.addWidget(QLabel(self.tr("Select the amount to remove green:")))
 
         # amount
         self.slider = QSlider(Qt.Orientation.Horizontal)

setiastro/saspro/resources.py

@@ -167,6 +167,7 @@ class Icons:
     GREEN = property(lambda self: _resource_path('green.png'))
     NEUTRAL = property(lambda self: _resource_path('neutral.png'))
     WHITE_BALANCE = property(lambda self: _resource_path('whitebalance.png'))
+    TEXTURE_CLARITY = property(lambda self: _resource_path('TextureClarity.svg'))
     MORPHOLOGY = property(lambda self: _resource_path('morpho.png'))
     CLAHE = property(lambda self: _resource_path('clahe.png'))
     HDR = property(lambda self: _resource_path('hdr.png'))
@@ -244,6 +245,7 @@ class Icons:
     STACKING = property(lambda self: _resource_path('stacking.png'))
     LIVE_STACKING = property(lambda self: _resource_path('livestacking.png'))
     IMAGE_COMBINE = property(lambda self: _resource_path('imagecombine.png'))
+    PLANETARY_STACKER = property(lambda self: _resource_path('planetarystacker.png'))
     
     # Moon phase (WIMS)
     MOON_NEW            = property(lambda self: _resource_path('new_moon.png'))
@@ -301,6 +303,7 @@ class Icons:
     COLOR_WHEEL = property(lambda self: _resource_path('colorwheel.png'))
     SELECTIVE_COLOR = property(lambda self: _resource_path('selectivecolor.png'))
     NB_TO_RGB = property(lambda self: _resource_path('nbtorgb.png'))
+    NARROWBANDNORMALIZATION = property(lambda self: _resource_path('narrowbandnormalization.png'))
     
     # Stretching
     STAT_STRETCH = property(lambda self: _resource_path('statstretch.png'))
@@ -411,6 +414,7 @@ def _init_legacy_paths():
         'green_path': get_icon_path('green.png'),
         'neutral_path': get_icon_path('neutral.png'),
         'whitebalance_path': get_icon_path('whitebalance.png'),
+        'texture_clarity_path': get_icon_path('TextureClarity.svg'),
         'morpho_path': get_icon_path('morpho.png'),
         'clahe_path': get_icon_path('clahe.png'),
         'starnet_path': get_icon_path('starnet.png'),
@@ -531,6 +535,7 @@ def _init_legacy_paths():
         'collage_path': get_icon_path('collage.png'),
         'annotated_path': get_icon_path('annotated.png'),
         'colorwheel_path': get_icon_path('colorwheel.png'),
+        'narrowbandnormalization_path': get_icon_path('narrowbandnormalization.png'),
         'font_path': get_icon_path('font.png'),
         'csv_icon_path': get_icon_path('cvs.png'),
         'spinner_path': get_data_path('spinner.gif'),
@@ -540,6 +545,7 @@ def _init_legacy_paths():
         'debayer_path': get_icon_path('debayer.png'),
         'aberration_path': get_icon_path('aberration.png'),
         'functionbundles_path': get_icon_path('functionbundle.png'),
+        'planetarystacker_path': get_icon_path('planetarystacker.png'),
         'viewbundles_path': get_icon_path('viewbundle.png'),
         'selectivecolor_path': get_icon_path('selectivecolor.png'),
         'rgbalign_path': get_icon_path('rgbalign.png'),

setiastro/saspro/rgbalign.py

@@ -4,11 +4,13 @@ from __future__ import annotations
 import os
 import numpy as np
 
-from PyQt6.QtCore import Qt, QThread, pyqtSignal
+from PyQt6.QtCore import Qt, QThread, pyqtSignal, QEvent, QTimer
 from PyQt6.QtWidgets import (
     QDialog, QVBoxLayout, QHBoxLayout, QLabel, QPushButton, QApplication,
-    QComboBox, QCheckBox, QMessageBox, QProgressBar, QPlainTextEdit, QSpinBox
+    QComboBox, QCheckBox, QMessageBox, QProgressBar, QPlainTextEdit,
+    QSpinBox, QGridLayout, QWidget
 )
+from PyQt6.QtGui import QImage, QPixmap, QMouseEvent, QCursor
 
 
 import astroalign
@@ -24,6 +26,54 @@ except Exception:
     PolynomialTransform = None
 
 
+def _translate_channel(ch: np.ndarray, dx: float, dy: float) -> np.ndarray:
+    if cv2 is None:
+        return ch
+    H, W = ch.shape[:2]
+    A = np.array([[1, 0, dx],
+                [0, 1, dy]], dtype=np.float32)
+    return cv2.warpAffine(
+        ch, A, (W, H),
+        flags=cv2.INTER_LANCZOS4,
+        borderMode=cv2.BORDER_CONSTANT,
+        borderValue=0,
+    )
+
+def _planet_centroid(ch: np.ndarray):
+    """Return (cx, cy, area) of dominant planet blob, or None."""
+    if cv2 is None:
+        return None
+
+    img = ch.astype(np.float32, copy=False)
+    p1 = float(np.percentile(img, 1.0))
+    p99 = float(np.percentile(img, 99.5))
+    if p99 <= p1:
+        return None
+
+    scaled = (img - p1) * (255.0 / (p99 - p1))
+    scaled = np.clip(scaled, 0, 255).astype(np.uint8)
+    scaled = cv2.GaussianBlur(scaled, (0, 0), 1.2)
+
+    _, bw = cv2.threshold(scaled, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+
+    k = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (7, 7))
+    bw = cv2.morphologyEx(bw, cv2.MORPH_OPEN, k, iterations=1)
+    bw = cv2.morphologyEx(bw, cv2.MORPH_CLOSE, k, iterations=2)
+
+    num, labels, stats, cents = cv2.connectedComponentsWithStats(bw, connectivity=8)
+    if num <= 1:
+        return None
+
+    areas = stats[1:, cv2.CC_STAT_AREA]
+    j = int(np.argmax(areas)) + 1
+    area = float(stats[j, cv2.CC_STAT_AREA])
+    if area < 200:
+        return None
+
+    cx, cy = cents[j]
+    return (float(cx), float(cy), area)
+
+
 # ─────────────────────────────────────────────────────────────────────
 # Worker
 # ─────────────────────────────────────────────────────────────────────
@@ -160,11 +210,83 @@ class RGBAlignWorker(QThread):
         except Exception as e:
             self.failed.emit(str(e))
 
+    def _planet_centroid(self, ch: np.ndarray):
+        """
+        Return (cx, cy, area) in pixel coordinates for the dominant planet blob.
+        Robust for uint8/uint16/float images.
+        """
+        if cv2 is None:
+            return None
+
+        img = ch.astype(np.float32, copy=False)
+
+        # Normalize to 0..255 for thresholding (robust percentile scaling)
+        p1 = float(np.percentile(img, 1.0))
+        p99 = float(np.percentile(img, 99.5))
+        if p99 <= p1:
+            return None
+
+        scaled = (img - p1) * (255.0 / (p99 - p1))
+        scaled = np.clip(scaled, 0, 255).astype(np.uint8)
+
+        # Blur to suppress banding/noise
+        scaled = cv2.GaussianBlur(scaled, (0, 0), 1.2)
+
+        # Otsu threshold to separate planet from background
+        _, bw = cv2.threshold(scaled, 0, 255, cv2.THRESH_BINARY + cv2.THRESH_OTSU)
+
+        # Clean up small junk / fill holes a bit
+        k = cv2.getStructuringElement(cv2.MORPH_ELLIPSE, (7, 7))
+        bw = cv2.morphologyEx(bw, cv2.MORPH_OPEN, k, iterations=1)
+        bw = cv2.morphologyEx(bw, cv2.MORPH_CLOSE, k, iterations=2)
+
+        # Largest connected component = planet
+        num, labels, stats, cents = cv2.connectedComponentsWithStats(bw, connectivity=8)
+        if num <= 1:
+            return None
+
+        # stats: [label, x, y, w, h, area] but area is stats[:, cv2.CC_STAT_AREA]
+        areas = stats[1:, cv2.CC_STAT_AREA]
+        j = int(np.argmax(areas)) + 1
+        area = float(stats[j, cv2.CC_STAT_AREA])
+        if area < 200:  # too tiny = probably noise
+            return None
+
+        cx, cy = cents[j]
+        return (float(cx), float(cy), area)
+
+    def _estimate_translation_by_centroid(self, src: np.ndarray, ref: np.ndarray):
+        c_src = self._planet_centroid(src)
+        c_ref = self._planet_centroid(ref)
+        if c_src is None or c_ref is None:
+            return None
+
+        sx, sy, sa = c_src
+        rx, ry, ra = c_ref
+
+        dx = rx - sx
+        dy = ry - sy
+        return (dx, dy, (sx, sy, sa), (rx, ry, ra))
+
 
     # ───── helpers (basically mini versions of your big star alignment logic) ─────
     def _estimate_transform(self, src: np.ndarray, ref: np.ndarray, model: str):
         H, W = ref.shape[:2]
 
+        # ── Planet centroid ADC mode ─────────────────────────────
+        if model == "planet-centroid":
+            t = self._estimate_translation_by_centroid(src, ref)
+            if t is None:
+                # fall back to affine/astroalign if centroid fails
+                # (or you can hard-fail here if you prefer)
+                pass
+            else:
+                dx, dy, src_info, ref_info = t
+                # store "pairs" as tiny diagnostic info
+                src_xy = np.array([[src_info[0], src_info[1]]], dtype=np.float32)
+                dst_xy = np.array([[ref_info[0], ref_info[1]]], dtype=np.float32)
+                X = (float(dx), float(dy))
+                return ("translate", X, (src_xy, dst_xy))
         # ── 0) edge-only, SEP-based path ─────────────────────────────
         if model == "edge-sep":
             src_xy, dst_xy = self._pair_edge_points(src, ref, (H, W))
@@ -323,6 +445,17 @@ class RGBAlignWorker(QThread):
 
     def _warp_channel(self, ch: np.ndarray, kind: str, X, ref_shape):
         H, W = ref_shape[:2]
+
+        if kind == "translate":
+            dx, dy = X
+            A = np.array([[1, 0, dx],
+                        [0, 1, dy]], dtype=np.float32)
+            return cv2.warpAffine(
+                ch, A, (W, H),
+                flags=cv2.INTER_LANCZOS4,
+                borderMode=cv2.BORDER_CONSTANT,
+                borderValue=0
+            )
         if kind == "affine":
             # Just assume cv2 is available (standard dependency) for perf
             A = np.asarray(X, dtype=np.float32).reshape(2, 3)
@@ -368,17 +501,28 @@ class RGBAlignDialog(QDialog):
         hl.addWidget(QLabel(self.tr("Alignment model:")))
         self.model_combo = QComboBox()
         self.model_combo.addItems([
+            "Planet Centroid (ADC)",   # NEW
             "EDGE",           # ← first, new default
             "Homography",
             "Affine",
             "Poly 3",
             "Poly 4",
         ])
-        self.model_combo.setCurrentIndex(0)
-
-        # tooltips for each mode
+        self.model_combo.setCurrentIndex(1)
         self.model_combo.setItemData(
             0,
+            (
+                "Planet Centroid (Atmospheric Dispersion)\n"
+                "• Find planet disk in each channel\n"
+                "• Compute centroid (moments)\n"
+                "• Shift R and B so their centroids match G\n"
+                "• Translation only (no warp), ideal for planets"
+            ),
+            Qt.ItemDataRole.ToolTipRole,
+        )
+        # tooltips for each mode
+        self.model_combo.setItemData(
+            1,
             (
                 "EDGE (Edge-Detected Guided Estimator)\n"
                 "• Detect stars in both channels with SEP\n"
@@ -390,22 +534,22 @@ class RGBAlignDialog(QDialog):
             Qt.ItemDataRole.ToolTipRole,
         )
         self.model_combo.setItemData(
-            1,
+            2,
             "Standard homography using astroalign matches (good general-purpose choice).",
             Qt.ItemDataRole.ToolTipRole,
         )
         self.model_combo.setItemData(
-            2,
+            3,
             "Affine (shift + scale + rotate + shear). Good when channels are mostly parallel.",
             Qt.ItemDataRole.ToolTipRole,
         )
         self.model_combo.setItemData(
-            3,
+            4,
             "Polynomial (order 3). Use when you have mild field distortion.",
             Qt.ItemDataRole.ToolTipRole,
         )
         self.model_combo.setItemData(
-            4,
+            5,
             "Polynomial (order 4). Use for stronger distortion, but needs more/better matches.",
             Qt.ItemDataRole.ToolTipRole,
         )
@@ -454,8 +598,15 @@ class RGBAlignDialog(QDialog):
 
         btns = QHBoxLayout()
         self.btn_run = QPushButton(self.tr("Align"))
+
+        self.btn_manual = QPushButton(self.tr("Manual…"))
+        self.btn_manual.setToolTip("Manual planetary RGB alignment (nudge channels by 1 px with preview).")
+
+        self.btn_manual.clicked.connect(self._open_manual)
+
         self.btn_close = QPushButton(self.tr("Close"))
         btns.addWidget(self.btn_run)
+        btns.addWidget(self.btn_manual)
         btns.addWidget(self.btn_close)
         lay.addLayout(btns)
 
@@ -464,6 +615,56 @@ class RGBAlignDialog(QDialog):
 
         self.worker: RGBAlignWorker | None = None
 
+    def _open_manual(self):
+        if self.image is None or self.image.ndim != 3 or self.image.shape[2] < 3:
+            QMessageBox.warning(self, "RGB Align", "Image must be RGB (3 channels).")
+            return
+
+        dlg = RGBAlignManualDialog(self, self.image, planet_roi=("planet" in self.model_combo.currentText().lower()))
+
+        if dlg.exec() != QDialog.DialogCode.Accepted:
+            return
+
+        rdx, rdy, bdx, bdy = dlg.result_offsets()
+        self.summary_box.setPlainText(
+            "[Manual Planetary]\n"
+            f"R shift: dx={rdx}, dy={rdy}\n"
+            f"B shift: dx={bdx}, dy={bdy}\n"
+        )
+
+        # apply full-res
+        img = self.image
+        R = img[..., 0].astype(np.float32, copy=False)
+        G = img[..., 1].astype(np.float32, copy=False)
+        B = img[..., 2].astype(np.float32, copy=False)
+
+        R2 = _translate_channel(R, rdx, rdy)
+        B2 = _translate_channel(B, bdx, bdy)
+
+        out = np.stack([R2, G, B2], axis=2)
+        if out.dtype != img.dtype:
+            out = out.astype(img.dtype, copy=False)
+
+        # same create-new-doc logic you already use
+        try:
+            if self.chk_new_doc.isChecked():
+                dm = getattr(self.parent, "docman", None)
+                if dm is not None:
+                    dm.open_array(out, {"display_name": "RGB Aligned (Manual)"}, title="RGB Aligned (Manual)")
+                else:
+                    if hasattr(self.doc, "apply_edit"):
+                        self.doc.apply_edit(out, {"step_name": "RGB Align (Manual)"}, step_name="RGB Align (Manual)")
+                    else:
+                        self.doc.image = out
+            else:
+                if hasattr(self.doc, "apply_edit"):
+                    self.doc.apply_edit(out, {"step_name": "RGB Align (Manual)"}, step_name="RGB Align (Manual)")
+                else:
+                    self.doc.image = out
+        except Exception as e:
+            QMessageBox.warning(self, "RGB Align", f"Manual aligned image created, but applying failed:\n{e}")
+
+
     def _trial_sep_detect(self):
         if self.image is None:
             QMessageBox.warning(self, "RGB Align", "No image loaded.")
@@ -529,6 +730,8 @@ class RGBAlignDialog(QDialog):
 
     def _selected_model(self) -> str:
         txt = self.model_combo.currentText().lower()
+        if "planet" in txt or "centroid" in txt or "adc" in txt:
+            return "planet-centroid"
         if "edge" in txt:
             return "edge-sep"
         if "affine" in txt:
@@ -539,7 +742,7 @@ class RGBAlignDialog(QDialog):
             return "poly4"
         if "homography" in txt:
             return "homography"
-        return "edge-sep"  # super-safe fallback
+        return "edge-sep"
 
     # slots
     def _on_worker_progress(self, pct: int, msg: str):
@@ -593,7 +796,10 @@ class RGBAlignDialog(QDialog):
                 if w.r_pairs is not None and len(w.r_pairs) == 2:
                     summary_lines.append(_spread_stats(w.r_pairs[1], (h_img, w_img)))
                 summary_lines.append(f"  model: {kind}")
-                if kind == "affine":
+                if kind == "translate":
+                    dx, dy = X
+                    summary_lines.append(f"  shift: dx={dx:.3f}, dy={dy:.3f}")                
+                elif kind == "affine":
                     A = np.asarray(X, dtype=float).reshape(2, 3)
                     M = np.vstack([A, [0, 0, 1]])
                     summary_lines.append(_fmt_mat(M))
@@ -611,7 +817,10 @@ class RGBAlignDialog(QDialog):
                 if w.b_pairs is not None and len(w.b_pairs) == 2:
                     summary_lines.append(_spread_stats(w.b_pairs[1], (h_img, w_img)))
                 summary_lines.append(f"  model: {kind}")
-                if kind == "affine":
+                if kind == "translate":
+                    dx, dy = X
+                    summary_lines.append(f"  shift: dx={dx:.3f}, dy={dy:.3f}")                
+                elif kind == "affine":
                     A = np.asarray(X, dtype=float).reshape(2, 3)
                     M = np.vstack([A, [0, 0, 1]])
                     summary_lines.append(_fmt_mat(M))
@@ -725,3 +934,238 @@ def run_rgb_align_headless(main_window, document, preset: dict | None = None):
 
     if callable(sb):
         sb().showMessage("RGB Align done.", 3000)
+
+
+class RGBAlignManualDialog(QDialog):
+    """
+    Manual channel translation for ADC / dispersion.
+    Adjust R and B offsets relative to G with 1px steps and live preview.
+    """
+    def __init__(self, parent=None, image: np.ndarray | None = None, planet_roi: bool = False):
+        super().__init__(parent)
+        self.setWindowTitle("RGB Align — Manual (Planetary)")
+        self.setModal(True)
+
+        self.image = np.asarray(image) if image is not None else None
+        self._timer = None
+        self._result = None  # (r_dx, r_dy, b_dx, b_dy)
+
+        # offsets
+        self.r_dx = 0
+        self.r_dy = 0
+        self.b_dx = 0
+        self.b_dy = 0
+
+        lay = QVBoxLayout(self)
+
+        self.lbl = QLabel("Nudge Red and Blue so they line up with Green (1 px steps).")
+        lay.addWidget(self.lbl)
+
+        # preview label
+        self.preview = QLabel()
+        self.preview.setMinimumSize(420, 320)
+        self.preview.setAlignment(Qt.AlignmentFlag.AlignCenter)
+        self.preview.setStyleSheet("background:#111; border:1px solid #333;")
+        lay.addWidget(self.preview)
+
+        # controls grid
+        row = QHBoxLayout()
+        lay.addLayout(row)
+
+        # controls
+        row = QHBoxLayout()
+        lay.addLayout(row)
+
+        self.red_pad = OffsetPad("Red offset (relative to Green):")
+        self.blue_pad = OffsetPad("Blue offset (relative to Green):")
+
+        self.red_pad.changed.connect(self._on_change)
+        self.blue_pad.changed.connect(self._on_change)
+
+        row.addWidget(self.red_pad)
+        row.addWidget(self.blue_pad)
+
+
+        # buttons
+        btns = QHBoxLayout()
+        self.btn_reset = QPushButton("Reset")
+        self.btn_apply = QPushButton("Apply")
+        self.btn_close = QPushButton("Close")
+        btns.addWidget(self.btn_reset)
+        btns.addStretch(1)
+        btns.addWidget(self.btn_apply)
+        btns.addWidget(self.btn_close)
+        lay.addLayout(btns)
+
+        self.btn_reset.clicked.connect(self._reset)
+        self.btn_apply.clicked.connect(self._apply)
+        self.btn_close.clicked.connect(self.reject)
+
+        # build a reasonable ROI for preview (center crop)
+        self._roi = None
+        if self.image is not None and self.image.ndim == 3 and self.image.shape[2] >= 3:
+            H, W = self.image.shape[:2]
+
+            if planet_roi:
+                # Use green channel to find the planet (most stable)
+                c = _planet_centroid(self.image[..., 1])
+                if c is not None:
+                    cx, cy, area = c
+                    # Estimate radius from area, then choose a padded ROI
+                    r = max(32.0, np.sqrt(area / np.pi))
+                    s = int(np.clip(r * 3.2, 160, 900))  # ROI size = ~3.2x radius
+                    cx_i, cy_i = int(round(cx)), int(round(cy))
+                else:
+                    cx_i, cy_i = W // 2, H // 2
+                    s = int(np.clip(min(H, W) * 0.45, 160, 900))
+            else:
+                cx_i, cy_i = W // 2, H // 2
+                s = int(np.clip(min(H, W) * 0.45, 160, 900))
+
+            x0 = max(0, cx_i - s // 2)
+            y0 = max(0, cy_i - s // 2)
+            x1 = min(W, x0 + s)
+            y1 = min(H, y0 + s)
+            self._roi = (x0, y0, x1, y1)
+
+
+        # debounce timer
+        from PyQt6.QtCore import QTimer
+        self._timer = QTimer(self)
+        self._timer.setSingleShot(True)
+        self._timer.timeout.connect(self._render_preview)
+        if self._roi is not None:
+            x0,y0,x1,y1 = self._roi
+            self.lbl.setText(self.lbl.text() + f"\nPreview ROI: x={x0}:{x1}, y={y0}:{y1}")
+        self._render_preview()
+
+    def result_offsets(self):
+        return self._result
+
+    def _on_change(self, *_):
+        self._timer.start(60)
+
+    def _reset(self):
+        self.red_pad.reset()
+        self.blue_pad.reset()
+
+    def _apply(self):
+        rdx, rdy = self.red_pad.offsets()
+        bdx, bdy = self.blue_pad.offsets()
+        self._result = (int(rdx), int(rdy), int(bdx), int(bdy))
+        self.accept()
+
+    def _render_preview(self):
+        if self.image is None or self.image.ndim != 3 or self.image.shape[2] < 3:
+            self.preview.setText("No RGB image.")
+            return
+
+        x0, y0, x1, y1 = self._roi if self._roi is not None else (0, 0, self.image.shape[1], self.image.shape[0])
+        crop = self.image[y0:y1, x0:x1, :3]
+
+        R = crop[..., 0].astype(np.float32, copy=False)
+        G = crop[..., 1].astype(np.float32, copy=False)
+        B = crop[..., 2].astype(np.float32, copy=False)
+
+        rdx, rdy = self.red_pad.offsets()
+        bdx, bdy = self.blue_pad.offsets()
+
+        R2 = _translate_channel(R, rdx, rdy)
+        B2 = _translate_channel(B, bdx, bdy)
+
+        out = np.stack([R2, G, B2], axis=2)
+
+        # display: robust scale to uint8
+        out8 = self._to_u8_preview(out)
+        qimg = QImage(out8.data, out8.shape[1], out8.shape[0], out8.strides[0], QImage.Format.Format_RGB888)
+        pix = QPixmap.fromImage(qimg).scaled(
+            self.preview.size(),
+            Qt.AspectRatioMode.KeepAspectRatio,
+            Qt.TransformationMode.SmoothTransformation,
+        )
+        self.preview.setPixmap(pix)
+
+    @staticmethod
+    def _to_u8_preview(rgb: np.ndarray) -> np.ndarray:
+        x = rgb.astype(np.float32, copy=False)
+        # percentile stretch per-channel, simple + robust
+        out = np.empty_like(x, dtype=np.uint8)
+        for c in range(3):
+            ch = x[..., c]
+            p1 = float(np.percentile(ch, 1.0))
+            p99 = float(np.percentile(ch, 99.5))
+            if p99 <= p1:
+                out[..., c] = 0
+            else:
+                y = (ch - p1) * (255.0 / (p99 - p1))
+                out[..., c] = np.clip(y, 0, 255).astype(np.uint8)
+        return out
+
+class OffsetPad(QWidget):
+    changed = pyqtSignal(int, int)  # dx, dy
+
+    def __init__(self, title: str, parent=None):
+        super().__init__(parent)
+        self._dx = 0
+        self._dy = 0
+
+        outer = QVBoxLayout(self)
+        outer.setContentsMargins(0, 0, 0, 0)
+        outer.setSpacing(4)
+
+        hdr = QLabel(title)
+        hdr.setStyleSheet("font-weight:600;")
+        outer.addWidget(hdr)
+
+        self.lbl = QLabel("dx=0  dy=0")
+        self.lbl.setStyleSheet("color:#bbb;")
+        outer.addWidget(self.lbl)
+
+        grid = QGridLayout()
+        grid.setSpacing(2)
+
+        self.btn_up = QPushButton("↑")
+        self.btn_dn = QPushButton("↓")
+        self.btn_lt = QPushButton("←")
+        self.btn_rt = QPushButton("→")
+        self.btn_mid = QPushButton("⟲")  # reset
+
+        for b in (self.btn_up, self.btn_dn, self.btn_lt, self.btn_rt, self.btn_mid):
+            b.setFixedSize(34, 34)
+            b.setFocusPolicy(Qt.FocusPolicy.NoFocus)
+
+        grid.addWidget(self.btn_up, 0, 1)
+        grid.addWidget(self.btn_lt, 1, 0)
+        grid.addWidget(self.btn_mid, 1, 1)
+        grid.addWidget(self.btn_rt, 1, 2)
+        grid.addWidget(self.btn_dn, 2, 1)
+
+        outer.addLayout(grid)
+
+        # connections
+        self.btn_up.clicked.connect(lambda: self.nudge(0, -1))
+        self.btn_dn.clicked.connect(lambda: self.nudge(0, +1))
+        self.btn_lt.clicked.connect(lambda: self.nudge(-1, 0))
+        self.btn_rt.clicked.connect(lambda: self.nudge(+1, 0))
+        self.btn_mid.clicked.connect(self.reset)
+
+    def set_offsets(self, dx: int, dy: int):
+        self._dx = int(dx)
+        self._dy = int(dy)
+        self._update_label()
+        self.changed.emit(self._dx, self._dy)
+
+    def offsets(self):
+        return (self._dx, self._dy)
+
+    def reset(self):
+        self.set_offsets(0, 0)
+
+    def nudge(self, ddx: int, ddy: int, step: int = 1):
+        self._dx += int(ddx) * int(step)
+        self._dy += int(ddy) * int(step)
+        self._update_label()
+        self.changed.emit(self._dx, self._dy)
+
+    def _update_label(self):
+        self.lbl.setText(f"dx={self._dx:+d}  dy={self._dy:+d}")