astro-swiper 0.1.0__tar.gz

astro_swiper-0.1.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: astro-swiper
+Version: 0.1.0
+Summary: Web-based interactive FITS triplet classifier for astronomical image labelling
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: flask>=2.0
+Requires-Dist: flask-socketio>=5.0
+Requires-Dist: astropy>=5.0
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: numpy>=1.21
+Requires-Dist: pyyaml>=6.0
+
+# Astro Swiper — Usage
+
+## Installation
+
+```bash
+pip install flask flask-socketio astropy matplotlib numpy pyyaml
+```
+
+---
+
+## Running
+
+### 1. As a Python import (recommended)
+
+```python
+from astro_swiper_web import AstroSwiper
+
+AstroSwiper('config.yaml').run()
+```
+
+### 2. With a custom triplet loader
+
+If your files don't follow the default `*scicutout / *subcutout / *refcutout` naming convention, provide a `triplet_loader` function. It receives `input_dir` from the config (or `None` if omitted) and must return a list of `[sub_path, sci_path, ref_path]` triplets.
+
+```python
+from astro_swiper_web import AstroSwiper
+
+def my_loader(input_dir):
+    # build and return your triplets however you like
+    import glob, re
+    sci_files = sorted(glob.glob(f"{input_dir}/*_science.fits"))
+    triplets = []
+    for sci in sci_files:
+        base = re.sub(r'_science\.fits$', '', sci)
+        sub  = base + '_difference.fits'
+        ref  = base + '_template.fits'
+        if os.path.exists(sub) and os.path.exists(ref):
+            triplets.append([sub, sci, ref])
+    return triplets
+
+AstroSwiper('config.yaml', triplet_loader=my_loader).run()
+```
+
+`input_dir` becomes optional in config when a loader is supplied — you can omit it entirely if your loader doesn't need it.
+
+### 4. With an inline config dict (no file needed)
+
+```python
+from astro_swiper_web import AstroSwiper
+
+AstroSwiper({
+    'input_dir': '/data/cutouts/',
+    'back_button': 'up',
+    'port': 5000,
+    'resume': True,
+    'overwrite': False,
+    'storage': {'backend': 'sqlite', 'db': 'classifications.db'},
+    'keybinds': {
+        'a': 'noise',
+        'e': 'streaks',
+        'd': 'dots',
+        '1': 'small',
+        '2': 'medium',
+    },
+}).run()
+```
+
+### 5. From the command line
+
+```bash
+python astro_swiper_web.py              # uses config.yaml in current directory
+python astro_swiper_web.py my_cfg.yaml  # explicit config path
+```
+
+Then open **http://localhost:5000** in a browser.
+
+**Over SSH** (no X11 needed):
+```bash
+ssh -L 5000:localhost:5000 user@host
+# then open http://localhost:5000 locally
+```
+
+---
+
+## config.yaml reference
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `input_dir` | *(required)* | Directory containing `.fits` or `.fits.gz` cutout triplets |
+| `back_button` | `left` | Key that undoes the last classification |
+| `port` | `5000` | Port the web server listens on |
+| `resume` | `true` | Skip already-classified triplets on startup |
+| `overwrite` | `false` | Wipe all saved classifications and start fresh |
+| `storage.backend` | `sqlite` | Storage format: `sqlite`, `csv`, or `txt` |
+| `keybinds` | *(required)* | Map of key → label (or file path for `txt` backend) |
+
+---
+
+## Storage backends
+
+### SQLite (recommended)
+
+```yaml
+storage:
+  backend: sqlite
+  db: training_sets/classifications.db
+```
+
+Single file, atomic writes, safe against crashes. Query results with pandas:
+
+```python
+import sqlite3, pandas as pd
+df = pd.read_sql(
+    "SELECT * FROM classifications",
+    sqlite3.connect("training_sets/classifications.db")
+)
+counts = df['label'].value_counts()
+```
+
+### CSV
+
+```yaml
+storage:
+  backend: csv
+  file: training_sets/classifications.csv
+```
+
+One row per triplet with columns `sub_path, sci_path, ref_path, label`. Easy to open in Excel or pandas:
+
+```python
+import pandas as pd
+df = pd.read_csv("training_sets/classifications.csv")
+```
+
+### Txt (legacy)
+
+```yaml
+storage:
+  backend: txt
+  already_classified: training_sets/already_classified.txt
+```
+
+One `.txt` file per category; keybind values must be **file paths** (not labels):
+
+```yaml
+keybinds:
+  a: training_sets/noise.txt
+  c: training_sets/skips.txt
+  ...
+```
+
+Each file contains triplet paths, three lines per entry (sub, sci, ref).
+
+---
+
+## Input data format
+
+Each triplet is a set of three co-registered FITS cutout files sharing a common basename:
+
+```
+<basename>scicutout.fits[.gz]
+<basename>subcutout.fits[.gz]
+<basename>refcutout.fits[.gz]
+```
+
+All files must be in the same flat directory (`input_dir`). Both `.fits` and `.fits.gz` are supported.
+
+---
+
+## Controls
+
+| Key | Action |
+|-----|--------|
+| *(configured keybinds)* | Classify current triplet |
+| `back_button` (default `left`) | Undo last classification |
+| `Shift+↑` | Increase contrast (narrow display window) |
+| `Shift+↓` | Decrease contrast (widen display window) |
+| `Shift+→` | Increase brightness (shift window up) |
+| `Shift+←` | Decrease brightness (shift window down) |

astro_swiper-0.1.0/astro_swiper/__init__.py

@@ -0,0 +1,3 @@
+from astro_swiper.web import AstroSwiper
+
+__all__ = ["AstroSwiper"]

astro_swiper-0.1.0/astro_swiper/_cli.py

@@ -0,0 +1,15 @@
+"""CLI entry point for astro-swiper."""
+
+import argparse
+from astro_swiper.web import AstroSwiper
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description='Astro Swiper — web-based FITS triplet classifier'
+    )
+    parser.add_argument(
+        'config', nargs='?', default='config.yaml',
+        help='Path to YAML config file (default: config.yaml)',
+    )
+    AstroSwiper(parser.parse_args().config).run()

astro_swiper-0.1.0/astro_swiper/classifier.py

@@ -0,0 +1,218 @@
+"""classifier.py — TripletClassifier: FITS loading, rendering, and key handling."""
+
+import os, io, base64, gzip, shutil, tempfile, threading
+
+import numpy as np
+from astropy.io import fits
+from astropy.visualization import ZScaleInterval
+import matplotlib
+matplotlib.use('Agg')
+import matplotlib.pyplot as plt
+import matplotlib.gridspec as gridspec
+
+
+class TripletClassifier:
+    def __init__(self, keybinds, back_button, storage, socketio,
+                 resume=True, overwrite=False):
+        self.keybinds    = keybinds
+        self.back_button = back_button
+        self.resume      = resume
+        self._storage    = storage
+        self._socketio   = socketio   # injected — no module-level global needed
+
+        self.triplets = []
+        self.index    = 0
+        self._lock    = threading.Lock()
+        self._zscale  = ZScaleInterval()
+
+        self.vmin     = 0.0
+        self.vmax     = 1.0
+        self.step_pct = 0.1
+
+        self._imgs_idx = None
+        self._imgs     = None
+        self._b64      = None
+        self._b64_key  = None
+        self._pf_lock  = threading.Lock()
+        self._pf       = None
+
+        if overwrite:
+            self._storage.clear()
+        self.pre_classified = self._storage.get_classified() if resume else set()
+
+    # ── FITS I/O ──────────────────────────────────────────────────────────────
+
+    def _load_fits(self, path):
+        if path.endswith('.fits.gz'):
+            with gzip.open(path, 'rb') as f_in:
+                with tempfile.NamedTemporaryFile(suffix='.fits', delete=False) as f_out:
+                    shutil.copyfileobj(f_in, f_out)
+                    tmp = f_out.name
+            try:
+                with fits.open(tmp) as h:
+                    return np.nan_to_num(h[0].data)
+            finally:
+                os.unlink(tmp)
+        with fits.open(path) as h:
+            return np.nan_to_num(h[0].data)
+
+    def _load_triplet(self, triplet):
+        return tuple(self._zscale(self._load_fits(p)) for p in triplet)
+
+    # ── Rendering ─────────────────────────────────────────────────────────────
+
+    def _render(self, imgs):
+        fig = plt.figure(figsize=(21, 7), facecolor='black')
+        gs  = gridspec.GridSpec(1, 3, wspace=0.02)
+        for i, (title, img) in enumerate(zip(('SUB', 'SCI', 'REF'), imgs)):
+            ax = fig.add_subplot(gs[i])
+            ax.set_title(title, fontsize=16, color='white')
+            ax.axis('off')
+            ax.imshow(img, cmap='gray', origin='lower', vmin=self.vmin, vmax=self.vmax)
+        plt.tight_layout(pad=0.4)
+        buf = io.BytesIO()
+        fig.savefig(buf, format='png', bbox_inches='tight', facecolor='black', dpi=100)
+        plt.close(fig)
+        buf.seek(0)
+        return base64.b64encode(buf.read()).decode()
+
+    def _get_b64(self):
+        idx = self.index
+        if self._imgs_idx != idx:
+            with self._pf_lock:
+                if self._pf and self._pf[0] == idx:
+                    self._imgs, self._pf = self._pf[1], None
+                else:
+                    self._imgs = self._load_triplet(self.triplets[idx])
+            self._imgs_idx = idx
+            self._b64      = None
+        key = (idx, round(self.vmin, 8), round(self.vmax, 8))
+        if self._b64_key != key:
+            self._b64     = self._render(self._imgs)
+            self._b64_key = key
+        return self._b64
+
+    # ── Prefetch ──────────────────────────────────────────────────────────────
+
+    def _prefetch_next(self):
+        nxt = self.index
+        while nxt < len(self.triplets):
+            if self.resume and self.triplets[nxt][1] in self.pre_classified:
+                nxt += 1
+            else:
+                break
+        if nxt >= len(self.triplets):
+            return
+        target, triplet = nxt, self.triplets[nxt]
+        def _work():
+            imgs = self._load_triplet(triplet)
+            with self._pf_lock:
+                self._pf = (target, imgs)
+        threading.Thread(target=_work, daemon=True).start()
+
+    # ── Navigation ────────────────────────────────────────────────────────────
+
+    def _skip_classified(self):
+        while self.index < len(self.triplets):
+            if self.resume and self.triplets[self.index][1] in self.pre_classified:
+                self.index += 1
+            else:
+                break
+
+    # ── Emit ──────────────────────────────────────────────────────────────────
+
+    def _emit_current(self, to=None):
+        if self.index >= len(self.triplets):
+            self._socketio.emit('done', {'message': f'All {len(self.triplets)} triplets done!'})
+            return
+        triplet = self.triplets[self.index]
+        payload = {
+            'image':    self._get_b64(),
+            'filename': os.path.basename(triplet[1]),
+            'progress': f'{self.index + 1} / {len(self.triplets)}',
+        }
+        self._socketio.emit('update', payload, to=to) if to else \
+            self._socketio.emit('update', payload)
+
+    def send_current(self, to=None):
+        sid = to
+        def _work():
+            self._socketio.emit('loading')
+            with self._lock:
+                self._emit_current(to=sid)
+        threading.Thread(target=_work, daemon=True).start()
+
+    # ── Key handling ──────────────────────────────────────────────────────────
+
+    def handle_key(self, key):
+        def _work():
+            with self._lock:
+                if key.startswith('shift+'):
+                    self._apply_scaling(key)
+                    self._emit_current()
+                elif key == self.back_button:
+                    self._undo()
+                    self._emit_current()
+                elif key in self.keybinds:
+                    self._classify(key)
+                    self._emit_current()
+                    self._prefetch_next()
+        threading.Thread(target=_work, daemon=True).start()
+
+    def _apply_scaling(self, key):
+        rng  = self.vmax - self.vmin
+        step = rng * self.step_pct
+        if   key == 'shift+up':    self.vmax -= step
+        elif key == 'shift+down':  self.vmax += step
+        elif key == 'shift+right': self.vmin += step; self.vmax += step
+        elif key == 'shift+left':  self.vmin -= step; self.vmax -= step
+        self._b64 = None
+
+    def _classify(self, key):
+        sub, sci, ref = self.triplets[self.index]
+        label = self.keybinds[key]
+        self._storage.save(sub, sci, ref, key, label)
+        self.pre_classified.add(sci)
+        print(f"[{self.index + 1}/{len(self.triplets)}] {os.path.basename(sci)} → {label}")
+        self.index += 1
+        self._skip_classified()
+
+    def _undo(self):
+        last_sci = self._storage.undo()
+        if last_sci is None:
+            print("Nothing to undo.")
+            return
+        self.pre_classified.discard(last_sci)
+        for i, triplet in enumerate(self.triplets):
+            if triplet[1] == last_sci:
+                self.index = i
+                break
+        else:
+            self.index = max(0, self.index - 1)
+        print(f"Undid: {os.path.basename(last_sci)}")
+
+    # ── Setup ─────────────────────────────────────────────────────────────────
+
+    def load_directory(self, directory_path, triplet_loader=None):
+        if triplet_loader is not None:
+            triplets = list(triplet_loader(directory_path))
+        else:
+            all_files = [
+                os.path.join(directory_path, fn)
+                for fn in os.listdir(directory_path)
+                if os.path.isfile(os.path.join(directory_path, fn))
+            ]
+            triplets = []
+            for sci_sfx, sub_sfx, ref_sfx in [
+                ('scicutout.fits.gz', 'subcutout.fits.gz', 'refcutout.fits.gz'),
+                ('scicutout.fits',    'subcutout.fits',    'refcutout.fits'),
+            ]:
+                for f in all_files:
+                    if f.endswith(sci_sfx):
+                        base    = f[:-len(sci_sfx)]
+                        triplet = [base + sub_sfx, f, base + ref_sfx]
+                        if all(os.path.exists(p) for p in triplet):
+                            triplets.append(triplet)
+        self.triplets = sorted(triplets, key=lambda t: t[1])
+        self._skip_classified()
+        print(f"Loaded {len(self.triplets)} triplets; resuming at index {self.index}.")

astro_swiper-0.1.0/astro_swiper/storage.py

@@ -0,0 +1,149 @@
+"""storage.py — Classification storage backends for astro_swiper."""
+
+import os, sqlite3, csv
+
+
+class StorageBackend:
+    def get_classified(self) -> set:           raise NotImplementedError
+    def save(self, sub, sci, ref, key, label): raise NotImplementedError
+    def undo(self) -> 'str | None':            raise NotImplementedError
+    def clear(self):                           raise NotImplementedError
+    def close(self): pass
+
+
+class SQLiteBackend(StorageBackend):
+    def __init__(self, db_path):
+        os.makedirs(os.path.dirname(db_path) or '.', exist_ok=True)
+        self._db = sqlite3.connect(db_path, check_same_thread=False)
+        self._db.execute("""
+            CREATE TABLE IF NOT EXISTS classifications (
+                rowid    INTEGER PRIMARY KEY AUTOINCREMENT,
+                sci_path TEXT UNIQUE,
+                sub_path TEXT,
+                ref_path TEXT,
+                label    TEXT
+            )
+        """)
+        self._db.commit()
+
+    def get_classified(self):
+        return {r[0] for r in self._db.execute(
+            "SELECT sci_path FROM classifications"
+        ).fetchall()}
+
+    def save(self, sub, sci, ref, key, label):
+        self._db.execute(
+            "INSERT OR REPLACE INTO classifications "
+            "(sci_path, sub_path, ref_path, label) VALUES (?, ?, ?, ?)",
+            (sci, sub, ref, label),
+        )
+        self._db.commit()
+
+    def undo(self):
+        row = self._db.execute(
+            "SELECT sci_path FROM classifications ORDER BY rowid DESC LIMIT 1"
+        ).fetchone()
+        if row is None:
+            return None
+        self._db.execute("DELETE FROM classifications WHERE sci_path = ?", (row[0],))
+        self._db.commit()
+        return row[0]
+
+    def clear(self):
+        self._db.execute("DELETE FROM classifications")
+        self._db.commit()
+
+    def close(self):
+        self._db.close()
+
+
+class CSVBackend(StorageBackend):
+    def __init__(self, csv_path):
+        os.makedirs(os.path.dirname(csv_path) or '.', exist_ok=True)
+        self._path = csv_path
+        if not os.path.exists(csv_path):
+            with open(csv_path, 'w', newline='') as f:
+                csv.writer(f).writerow(['sub_path', 'sci_path', 'ref_path', 'label'])
+
+    def get_classified(self):
+        with open(self._path, newline='') as f:
+            return {row['sci_path'] for row in csv.DictReader(f)}
+
+    def save(self, sub, sci, ref, key, label):
+        with open(self._path, 'a', newline='') as f:
+            csv.writer(f).writerow([sub, sci, ref, label])
+
+    def undo(self):
+        with open(self._path, newline='') as f:
+            rows = list(csv.reader(f))
+        if len(rows) <= 1:
+            return None
+        last_sci = rows[-1][1]
+        with open(self._path, 'w', newline='') as f:
+            csv.writer(f).writerows(rows[:-1])
+        return last_sci
+
+    def clear(self):
+        with open(self._path, 'w', newline='') as f:
+            csv.writer(f).writerow(['sub_path', 'sci_path', 'ref_path', 'label'])
+
+
+class TxtBackend(StorageBackend):
+    """Original multi-file format. keybinds must be {key: filepath}."""
+    def __init__(self, keybinds, already_classified_path):
+        self._keybinds = keybinds
+        self._ac_path  = already_classified_path
+        os.makedirs(os.path.dirname(already_classified_path) or '.', exist_ok=True)
+        if not os.path.exists(already_classified_path):
+            open(already_classified_path, 'w').close()
+        for path in keybinds.values():
+            os.makedirs(os.path.dirname(path) or '.', exist_ok=True)
+
+    def get_classified(self):
+        with open(self._ac_path) as f:
+            lines = [l.strip() for l in f if l.strip()]
+        return set(lines[i] for i in range(0, len(lines), 2))
+
+    def save(self, sub, sci, ref, key, label):
+        with open(self._keybinds[key], 'a') as f:
+            f.write(f"{sub}\n{sci}\n{ref}\n")
+        with open(self._ac_path, 'a') as f:
+            f.write(f"{sci}\n{key}\n")
+
+    def undo(self):
+        with open(self._ac_path) as f:
+            lines = f.readlines()
+        if len(lines) < 2:
+            return None
+        last_key = lines[-1].strip()
+        last_sci = lines[-2].strip()
+        with open(self._ac_path, 'w') as f:
+            f.writelines(lines[:-2])
+        cat_path = self._keybinds[last_key]
+        with open(cat_path) as f:
+            cat_lines = f.readlines()
+        with open(cat_path, 'w') as f:
+            f.writelines(cat_lines[:-3])
+        return last_sci
+
+    def clear(self):
+        open(self._ac_path, 'w').close()
+        for path in self._keybinds.values():
+            open(path, 'w').close()
+
+
+def make_backend(cfg, keybinds) -> StorageBackend:
+    storage_cfg = cfg.get('storage', {})
+    backend     = storage_cfg.get('backend', 'sqlite').lower()
+    if backend == 'sqlite':
+        return SQLiteBackend(storage_cfg.get('db', 'classifications.db'))
+    elif backend == 'csv':
+        return CSVBackend(storage_cfg.get('file', 'classifications.csv'))
+    elif backend == 'txt':
+        return TxtBackend(
+            keybinds=keybinds,
+            already_classified_path=storage_cfg.get(
+                'already_classified', 'training_sets/already_classified.txt'
+            ),
+        )
+    raise ValueError(f"Unknown storage backend '{backend}'. Choose sqlite, csv, or txt.")

astro_swiper-0.1.0/astro_swiper/web.py

@@ -0,0 +1,201 @@
+"""web.py — AstroSwiper: web-based FITS triplet classifier.
+
+Usage as a module:
+    from astro_swiper import AstroSwiper
+    AstroSwiper('config.yaml').run()
+
+Also accepts a pre-loaded dict instead of a path:
+    AstroSwiper({'input_dir': '...', 'keybinds': {...}, ...}).run()
+"""
+
+import os
+import yaml
+from flask import Flask, render_template_string, request, send_file
+from flask_socketio import SocketIO, emit
+
+from astro_swiper.storage import make_backend
+from astro_swiper.classifier import TripletClassifier
+
+# ---------------------------------------------------------------------------
+# Browser UI
+# ---------------------------------------------------------------------------
+
+HTML = r"""<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <title>Astro Swiper</title>
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link href="https://fonts.googleapis.com/css2?family=Press+Start+2P&display=swap" rel="stylesheet">
+  <style>
+    * { box-sizing: border-box; margin: 0; padding: 0; }
+    body { background: #111 url('/background') center top / cover no-repeat fixed;
+           color: #eee; font-family: monospace;
+           display: flex; flex-direction: column; align-items: center;
+           padding: 40px 10px 10px; min-height: 100vh; }
+    #status   { font-size: 1.1em; margin-bottom: 3px; min-height: 1.4em; }
+    #progress { font-size: 0.85em; color: #888; margin-bottom: 6px; min-height: 1.2em; }
+    #triplet-img { max-width: 100%; max-height: 78vh; object-fit: contain;
+                   background: #000; display: block; }
+    #spinner  { display: none; font-size: 0.9em; color: #666; margin: 4px; }
+    #keybinds { display: flex; flex-wrap: wrap; justify-content: center;
+                gap: 5px; margin-top: 8px; font-size: 1.1em; }
+    .kb       { background: #1e1e1e; border: 1px solid #444;
+                padding: 4px 12px; border-radius: 4px; }
+    .kb b     { color: #7af; }
+    #hint     { font-size: 0.95em; color: #fff; margin-top: 8px; }
+    #photo-credit { position: fixed; bottom: 6px; right: 10px; font-size: 0.6em;
+                    color: #444; text-decoration: none; }
+    #title    { font-family: 'Press Start 2P', monospace; font-size: 64pt;
+                line-height: 1; margin-bottom: 12px; }
+  </style>
+</head>
+<body>
+  <div id="title">Astro Swiper</div>
+  <div id="status">Connecting…</div>
+  <div id="progress"></div>
+  <div id="spinner">Rendering…</div>
+  <img id="triplet-img" src="" alt="">
+  <div id="keybinds"></div>
+  <div id="hint">Shift+↑↓ contrast &nbsp;|&nbsp; Shift+←→ brightness</div>
+  <a id="photo-credit" href="https://www.pexels.com/photo/blue-and-purple-cosmic-sky-956999/" target="_blank">Photo by Felix Mittermeier</a>
+
+  <script src="https://cdn.socket.io/4.7.5/socket.io.min.js"></script>
+  <script>
+    const socket   = io();
+    const imgEl    = document.getElementById('triplet-img');
+    const statusEl = document.getElementById('status');
+    const progEl   = document.getElementById('progress');
+    const spinEl   = document.getElementById('spinner');
+    const kbEl     = document.getElementById('keybinds');
+
+    socket.on('connect',    () => { statusEl.textContent = 'Connected — loading…'; });
+    socket.on('disconnect', () => { statusEl.textContent = 'Disconnected.'; });
+    socket.on('loading',    () => { spinEl.style.display = 'block'; });
+
+    socket.on('update', d => {
+      imgEl.src = 'data:image/png;base64,' + d.image;
+      statusEl.textContent  = d.filename;
+      progEl.textContent    = d.progress;
+      spinEl.style.display  = 'none';
+    });
+
+    socket.on('done', d => {
+      statusEl.textContent = '✓ ' + d.message;
+      imgEl.src = ''; progEl.textContent = '';
+      spinEl.style.display = 'none';
+    });
+
+    const arrowGlyph = {left:'←', right:'→', up:'↑', down:'↓'};
+    const pretty = k => arrowGlyph[k] ?? k;
+
+    socket.on('keybinds', list => {
+      kbEl.innerHTML =
+        list.map(([k, n]) => `<div class="kb"><b>${pretty(k)}</b> ${n}</div>`).join('');
+    });
+
+    document.addEventListener('keydown', e => {
+      if (['ArrowLeft','ArrowRight','ArrowUp','ArrowDown',' '].includes(e.key))
+        e.preventDefault();
+      const arrows = {ArrowLeft:'left', ArrowRight:'right', ArrowUp:'up', ArrowDown:'down'};
+      let key = arrows[e.key] ?? e.key;
+      if (e.shiftKey && ['left','right','up','down'].includes(key)) key = 'shift+' + key;
+      socket.emit('keypress', {key});
+    });
+  </script>
+</body>
+</html>"""
+
+# ---------------------------------------------------------------------------
+# Public API
+# ---------------------------------------------------------------------------
+
+class AstroSwiper:
+    """
+    Web-based FITS triplet classifier.
+
+    Usage:
+        from astro_swiper import AstroSwiper
+        AstroSwiper('config.yaml').run()
+
+    Also accepts a pre-loaded dict instead of a path:
+        AstroSwiper({'input_dir': '...', 'keybinds': {...}, ...}).run()
+
+    To use a custom triplet loader instead of the built-in filename scanner,
+    pass a callable that accepts input_dir (may be None) and returns a list of
+    [sub_path, sci_path, ref_path] triplets:
+
+        def my_loader(input_dir):
+            return [[sub, sci, ref], ...]
+
+        AstroSwiper('config.yaml', triplet_loader=my_loader).run()
+
+    When a triplet_loader is provided, input_dir in config is optional and is
+    passed to the loader as-is (you may ignore it if not needed).
+    """
+
+    def __init__(self, config, triplet_loader=None):
+        if isinstance(config, str):
+            with open(config) as f:
+                cfg = yaml.safe_load(f)
+        else:
+            cfg = dict(config)
+
+        input_dir = cfg.get('input_dir')
+        if input_dir is None and triplet_loader is None:
+            raise ValueError("config must include 'input_dir' when no triplet_loader is provided")
+
+        self._port = cfg.get('port', 5000)
+        self._app  = Flask(__name__)
+        self._app.config['SECRET_KEY'] = 'astro_swiper'
+        self._sio  = SocketIO(self._app, async_mode='threading', cors_allowed_origins='*')
+
+        keybinds = {str(k): str(v) for k, v in cfg['keybinds'].items()}
+
+        self._classifier = TripletClassifier(
+            keybinds=keybinds,
+            back_button=cfg.get('back_button', 'left'),
+            storage=make_backend(cfg, keybinds),
+            socketio=self._sio,
+            resume=cfg.get('resume', True),
+            overwrite=cfg.get('overwrite', False),
+        )
+        self._classifier.load_directory(input_dir, triplet_loader=triplet_loader)
+        self._register_routes()
+
+    def _register_routes(self):
+        app = self._app
+        sio = self._sio
+        clf = self._classifier
+
+        @app.route('/')
+        def index_page():
+            return render_template_string(HTML)
+
+        @app.route('/background')
+        def background():
+            return send_file(
+                os.path.join(os.path.dirname(__file__), 'imgs', 'background.png'),
+                mimetype='image/png',
+            )
+
+        @sio.on('connect')
+        def on_connect():
+            kb_list = [
+                (k, os.path.splitext(os.path.basename(v))[0])
+                for k, v in clf.keybinds.items()
+            ]
+            kb_list.append((clf.back_button, 'back'))
+            emit('keybinds', kb_list)
+            clf.send_current(to=request.sid)
+
+        @sio.on('keypress')
+        def on_keypress(data):
+            clf.handle_key(data.get('key', ''))
+
+    def run(self):
+        print(f"Open http://localhost:{self._port} in your browser")
+        self._sio.run(
+            self._app, host='127.0.0.1', port=self._port,
+            debug=False, use_reloader=False, allow_unsafe_werkzeug=True,
+        )

astro_swiper-0.1.0/astro_swiper.egg-info/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: astro-swiper
+Version: 0.1.0
+Summary: Web-based interactive FITS triplet classifier for astronomical image labelling
+License: MIT
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: flask>=2.0
+Requires-Dist: flask-socketio>=5.0
+Requires-Dist: astropy>=5.0
+Requires-Dist: matplotlib>=3.5
+Requires-Dist: numpy>=1.21
+Requires-Dist: pyyaml>=6.0
+
+# Astro Swiper — Usage
+
+## Installation
+
+```bash
+pip install flask flask-socketio astropy matplotlib numpy pyyaml
+```
+
+---
+
+## Running
+
+### 1. As a Python import (recommended)
+
+```python
+from astro_swiper_web import AstroSwiper
+
+AstroSwiper('config.yaml').run()
+```
+
+### 2. With a custom triplet loader
+
+If your files don't follow the default `*scicutout / *subcutout / *refcutout` naming convention, provide a `triplet_loader` function. It receives `input_dir` from the config (or `None` if omitted) and must return a list of `[sub_path, sci_path, ref_path]` triplets.
+
+```python
+from astro_swiper_web import AstroSwiper
+
+def my_loader(input_dir):
+    # build and return your triplets however you like
+    import glob, re
+    sci_files = sorted(glob.glob(f"{input_dir}/*_science.fits"))
+    triplets = []
+    for sci in sci_files:
+        base = re.sub(r'_science\.fits$', '', sci)
+        sub  = base + '_difference.fits'
+        ref  = base + '_template.fits'
+        if os.path.exists(sub) and os.path.exists(ref):
+            triplets.append([sub, sci, ref])
+    return triplets
+
+AstroSwiper('config.yaml', triplet_loader=my_loader).run()
+```
+
+`input_dir` becomes optional in config when a loader is supplied — you can omit it entirely if your loader doesn't need it.
+
+### 4. With an inline config dict (no file needed)
+
+```python
+from astro_swiper_web import AstroSwiper
+
+AstroSwiper({
+    'input_dir': '/data/cutouts/',
+    'back_button': 'up',
+    'port': 5000,
+    'resume': True,
+    'overwrite': False,
+    'storage': {'backend': 'sqlite', 'db': 'classifications.db'},
+    'keybinds': {
+        'a': 'noise',
+        'e': 'streaks',
+        'd': 'dots',
+        '1': 'small',
+        '2': 'medium',
+    },
+}).run()
+```
+
+### 5. From the command line
+
+```bash
+python astro_swiper_web.py              # uses config.yaml in current directory
+python astro_swiper_web.py my_cfg.yaml  # explicit config path
+```
+
+Then open **http://localhost:5000** in a browser.
+
+**Over SSH** (no X11 needed):
+```bash
+ssh -L 5000:localhost:5000 user@host
+# then open http://localhost:5000 locally
+```
+
+---
+
+## config.yaml reference
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `input_dir` | *(required)* | Directory containing `.fits` or `.fits.gz` cutout triplets |
+| `back_button` | `left` | Key that undoes the last classification |
+| `port` | `5000` | Port the web server listens on |
+| `resume` | `true` | Skip already-classified triplets on startup |
+| `overwrite` | `false` | Wipe all saved classifications and start fresh |
+| `storage.backend` | `sqlite` | Storage format: `sqlite`, `csv`, or `txt` |
+| `keybinds` | *(required)* | Map of key → label (or file path for `txt` backend) |
+
+---
+
+## Storage backends
+
+### SQLite (recommended)
+
+```yaml
+storage:
+  backend: sqlite
+  db: training_sets/classifications.db
+```
+
+Single file, atomic writes, safe against crashes. Query results with pandas:
+
+```python
+import sqlite3, pandas as pd
+df = pd.read_sql(
+    "SELECT * FROM classifications",
+    sqlite3.connect("training_sets/classifications.db")
+)
+counts = df['label'].value_counts()
+```
+
+### CSV
+
+```yaml
+storage:
+  backend: csv
+  file: training_sets/classifications.csv
+```
+
+One row per triplet with columns `sub_path, sci_path, ref_path, label`. Easy to open in Excel or pandas:
+
+```python
+import pandas as pd
+df = pd.read_csv("training_sets/classifications.csv")
+```
+
+### Txt (legacy)
+
+```yaml
+storage:
+  backend: txt
+  already_classified: training_sets/already_classified.txt
+```
+
+One `.txt` file per category; keybind values must be **file paths** (not labels):
+
+```yaml
+keybinds:
+  a: training_sets/noise.txt
+  c: training_sets/skips.txt
+  ...
+```
+
+Each file contains triplet paths, three lines per entry (sub, sci, ref).
+
+---
+
+## Input data format
+
+Each triplet is a set of three co-registered FITS cutout files sharing a common basename:
+
+```
+<basename>scicutout.fits[.gz]
+<basename>subcutout.fits[.gz]
+<basename>refcutout.fits[.gz]
+```
+
+All files must be in the same flat directory (`input_dir`). Both `.fits` and `.fits.gz` are supported.
+
+---
+
+## Controls
+
+| Key | Action |
+|-----|--------|
+| *(configured keybinds)* | Classify current triplet |
+| `back_button` (default `left`) | Undo last classification |
+| `Shift+↑` | Increase contrast (narrow display window) |
+| `Shift+↓` | Decrease contrast (widen display window) |
+| `Shift+→` | Increase brightness (shift window up) |
+| `Shift+←` | Decrease brightness (shift window down) |

astro_swiper-0.1.0/astro_swiper.egg-info/SOURCES.txt

@@ -0,0 +1,15 @@
+pyproject.toml
+readme.md
+setup.py
+astro_swiper/__init__.py
+astro_swiper/_cli.py
+astro_swiper/classifier.py
+astro_swiper/storage.py
+astro_swiper/web.py
+astro_swiper.egg-info/PKG-INFO
+astro_swiper.egg-info/SOURCES.txt
+astro_swiper.egg-info/dependency_links.txt
+astro_swiper.egg-info/entry_points.txt
+astro_swiper.egg-info/requires.txt
+astro_swiper.egg-info/top_level.txt
+astro_swiper/imgs/background.png

astro_swiper-0.1.0/astro_swiper.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

astro_swiper-0.1.0/astro_swiper.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+asswiper = astro_swiper._cli:main

astro_swiper-0.1.0/astro_swiper.egg-info/requires.txt

@@ -0,0 +1,6 @@
+flask>=2.0
+flask-socketio>=5.0
+astropy>=5.0
+matplotlib>=3.5
+numpy>=1.21
+pyyaml>=6.0

astro_swiper-0.1.0/astro_swiper.egg-info/top_level.txt

@@ -0,0 +1 @@
+astro_swiper

astro_swiper-0.1.0/pyproject.toml

@@ -0,0 +1,29 @@
+[build-system]
+requires = ["setuptools>=61", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "astro-swiper"
+version = "0.1.0"
+description = "Web-based interactive FITS triplet classifier for astronomical image labelling"
+readme = "readme.md"
+license = { text = "MIT" }
+requires-python = ">=3.8"
+dependencies = [
+    "flask>=2.0",
+    "flask-socketio>=5.0",
+    "astropy>=5.0",
+    "matplotlib>=3.5",
+    "numpy>=1.21",
+    "pyyaml>=6.0",
+]
+
+[project.scripts]
+asswiper = "astro_swiper._cli:main"
+
+[tool.setuptools.packages.find]
+where = ["."]
+include = ["astro_swiper*"]
+
+[tool.setuptools.package-data]
+astro_swiper = ["imgs/*.png"]

astro_swiper-0.1.0/readme.md

@@ -0,0 +1,179 @@
+# Astro Swiper — Usage
+
+## Installation
+
+```bash
+pip install flask flask-socketio astropy matplotlib numpy pyyaml
+```
+
+---
+
+## Running
+
+### 1. As a Python import (recommended)
+
+```python
+from astro_swiper_web import AstroSwiper
+
+AstroSwiper('config.yaml').run()
+```
+
+### 2. With a custom triplet loader
+
+If your files don't follow the default `*scicutout / *subcutout / *refcutout` naming convention, provide a `triplet_loader` function. It receives `input_dir` from the config (or `None` if omitted) and must return a list of `[sub_path, sci_path, ref_path]` triplets.
+
+```python
+from astro_swiper_web import AstroSwiper
+
+def my_loader(input_dir):
+    # build and return your triplets however you like
+    import glob, re
+    sci_files = sorted(glob.glob(f"{input_dir}/*_science.fits"))
+    triplets = []
+    for sci in sci_files:
+        base = re.sub(r'_science\.fits$', '', sci)
+        sub  = base + '_difference.fits'
+        ref  = base + '_template.fits'
+        if os.path.exists(sub) and os.path.exists(ref):
+            triplets.append([sub, sci, ref])
+    return triplets
+
+AstroSwiper('config.yaml', triplet_loader=my_loader).run()
+```
+
+`input_dir` becomes optional in config when a loader is supplied — you can omit it entirely if your loader doesn't need it.
+
+### 4. With an inline config dict (no file needed)
+
+```python
+from astro_swiper_web import AstroSwiper
+
+AstroSwiper({
+    'input_dir': '/data/cutouts/',
+    'back_button': 'up',
+    'port': 5000,
+    'resume': True,
+    'overwrite': False,
+    'storage': {'backend': 'sqlite', 'db': 'classifications.db'},
+    'keybinds': {
+        'a': 'noise',
+        'e': 'streaks',
+        'd': 'dots',
+        '1': 'small',
+        '2': 'medium',
+    },
+}).run()
+```
+
+### 5. From the command line
+
+```bash
+python astro_swiper_web.py              # uses config.yaml in current directory
+python astro_swiper_web.py my_cfg.yaml  # explicit config path
+```
+
+Then open **http://localhost:5000** in a browser.
+
+**Over SSH** (no X11 needed):
+```bash
+ssh -L 5000:localhost:5000 user@host
+# then open http://localhost:5000 locally
+```
+
+---
+
+## config.yaml reference
+
+| Key | Default | Description |
+|-----|---------|-------------|
+| `input_dir` | *(required)* | Directory containing `.fits` or `.fits.gz` cutout triplets |
+| `back_button` | `left` | Key that undoes the last classification |
+| `port` | `5000` | Port the web server listens on |
+| `resume` | `true` | Skip already-classified triplets on startup |
+| `overwrite` | `false` | Wipe all saved classifications and start fresh |
+| `storage.backend` | `sqlite` | Storage format: `sqlite`, `csv`, or `txt` |
+| `keybinds` | *(required)* | Map of key → label (or file path for `txt` backend) |
+
+---
+
+## Storage backends
+
+### SQLite (recommended)
+
+```yaml
+storage:
+  backend: sqlite
+  db: training_sets/classifications.db
+```
+
+Single file, atomic writes, safe against crashes. Query results with pandas:
+
+```python
+import sqlite3, pandas as pd
+df = pd.read_sql(
+    "SELECT * FROM classifications",
+    sqlite3.connect("training_sets/classifications.db")
+)
+counts = df['label'].value_counts()
+```
+
+### CSV
+
+```yaml
+storage:
+  backend: csv
+  file: training_sets/classifications.csv
+```
+
+One row per triplet with columns `sub_path, sci_path, ref_path, label`. Easy to open in Excel or pandas:
+
+```python
+import pandas as pd
+df = pd.read_csv("training_sets/classifications.csv")
+```
+
+### Txt (legacy)
+
+```yaml
+storage:
+  backend: txt
+  already_classified: training_sets/already_classified.txt
+```
+
+One `.txt` file per category; keybind values must be **file paths** (not labels):
+
+```yaml
+keybinds:
+  a: training_sets/noise.txt
+  c: training_sets/skips.txt
+  ...
+```
+
+Each file contains triplet paths, three lines per entry (sub, sci, ref).
+
+---
+
+## Input data format
+
+Each triplet is a set of three co-registered FITS cutout files sharing a common basename:
+
+```
+<basename>scicutout.fits[.gz]
+<basename>subcutout.fits[.gz]
+<basename>refcutout.fits[.gz]
+```
+
+All files must be in the same flat directory (`input_dir`). Both `.fits` and `.fits.gz` are supported.
+
+---
+
+## Controls
+
+| Key | Action |
+|-----|--------|
+| *(configured keybinds)* | Classify current triplet |
+| `back_button` (default `left`) | Undo last classification |
+| `Shift+↑` | Increase contrast (narrow display window) |
+| `Shift+↓` | Decrease contrast (widen display window) |
+| `Shift+→` | Increase brightness (shift window up) |
+| `Shift+←` | Decrease brightness (shift window down) |

astro_swiper-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

astro_swiper-0.1.0/setup.py

@@ -0,0 +1,3 @@
+from setuptools import setup
+
+setup()