termfits 0.1.0__py3-none-any.whl

termfits/__init__.py

@@ -0,0 +1,7 @@
+"""termfits - a terminal FITS image viewer with zoom and pan, tuned for radio images."""
+
+__version__ = "0.1.0"
+
+from .viewer import Viewer, main, robust_stats, CMAPS, STRETCHES  # noqa: E402,F401
+
+__all__ = ["Viewer", "main", "robust_stats", "CMAPS", "STRETCHES", "__version__"]

termfits/__main__.py

@@ -0,0 +1,4 @@
+from .viewer import main
+
+if __name__ == "__main__":
+    main()

termfits/viewer.py

@@ -0,0 +1,725 @@
+"""
+termfits - a terminal FITS image viewer with zoom and pan, tuned for radio images.
+
+Renders with Unicode upper-half blocks (two image pixels per character cell),
+so a 100 x 100 character view shows a 100 x 200 grid of near-square pixels.
+
+Radio-friendly defaults:
+  * Display limits are set from a robust noise estimate (median and 1.4826 x MAD),
+    -1 sigma to +10 sigma, rather than from percentiles.
+  * Inverted greyscale, linear stretch. Colour maps include heat (DS9-style orange),
+    inferno, magma, viridis, cubehelix, and 'diverging', which is centred on the
+    median so negative sidelobes show blue and real emission red.
+  * Status bar shows the pixel value in BUNIT and in sigma, the rms, and the
+    restoring beam (BMAJ/BMIN/BPA); the beam is drawn in the lower-left corner.
+  * When zoomed out, image pixels are combined into blocks (never skipped).
+    'b' switches between block mean (lower noise, good for faint extended
+    emission) and block max (keeps faint compact sources visible).
+
+Requires: numpy. astropy is recommended (compressed images, WCS / RA-Dec readout);
+without it a built-in reader handles plain uncompressed images.
+
+Usage:
+    termfits image.fits
+    termfits cube.fits --plane 10 --sigma-lo 2 --sigma-hi 20
+    termfits image.fits --snapshot      # print one frame and exit
+
+Keys:
+    arrows / h j k l        pan (10% of view)
+    Shift+arrows / H J K L  pan (50% of view)
+    + / =    zoom in          - / _   zoom out
+    f        fit image        1       1:1 (one image pixel per screen pixel)
+    r        reset (fit + recentre)
+    < >      lower / raise the upper display limit (in sigma)
+    ( )      lower / raise the lower display limit (in sigma)
+    c        cycle clip mode (sigma, 99.5, 99, 98, 95 percent, min/max)
+    n        re-measure the noise from the region in view   N  back to global
+    b        zoomed-out binning: block mean / block max
+    e        toggle beam ellipse
+    s        cycle stretch (linear, sqrt, log, asinh)
+    m / M    next / previous colour map (inverted, gray, heat, inferno, magma,
+             viridis, cubehelix, cool, rainbow, diverging)
+    x        toggle crosshair
+    [ ]      previous / next plane (channels / Stokes)
+    Tab      next image HDU
+    ?        help
+    q / Esc  quit
+"""
+import argparse
+import math
+import os
+import select
+import signal
+import sys
+import warnings
+
+import numpy as np
+
+try:
+    from astropy.io import fits
+except ImportError:
+    fits = None
+
+
+# ---------------------------------------------------------------------------
+# Minimal fallback FITS reader (used only if astropy is not installed).
+# Handles uncompressed primary/IMAGE HDUs; skips tables. No WCS support.
+# ---------------------------------------------------------------------------
+class _MiniHDU:
+    def __init__(self, header, data, is_image):
+        self.header, self.data, self.is_image = header, data, is_image
+
+
+class _MiniHDUList(list):
+    def close(self):
+        pass
+
+
+def _mini_open(path):
+    dtypes = {8: ">u1", 16: ">i2", 32: ">i4", 64: ">i8", -32: ">f4", -64: ">f8"}
+    raw = np.memmap(path, dtype=np.uint8, mode="r")
+    pos, hdus = 0, _MiniHDUList()
+    while pos + 2880 <= raw.size:
+        header = {}
+        done = False
+        while not done:
+            block = bytes(raw[pos:pos + 2880]).decode("ascii", "replace")
+            pos += 2880
+            for i in range(0, 2880, 80):
+                card = block[i:i + 80]
+                key = card[:8].strip()
+                if key == "END":
+                    done = True
+                    break
+                if card[8:10] != "= ":
+                    continue
+                val = card[10:]
+                if val.lstrip().startswith("'"):
+                    v = val.lstrip()[1:]
+                    header[key] = v[: v.find("'")].rstrip() if "'" in v else v.strip()
+                else:
+                    v = val.split("/")[0].strip()
+                    try:
+                        header[key] = int(v)
+                    except ValueError:
+                        try:
+                            header[key] = float(v.replace("D", "E"))
+                        except ValueError:
+                            header[key] = {"T": True, "F": False}.get(v, v)
+            if pos >= raw.size and not done:
+                return hdus
+        naxis = int(header.get("NAXIS", 0))
+        shape = [int(header.get(f"NAXIS{k}", 0)) for k in range(1, naxis + 1)]
+        bitpix = int(header.get("BITPIX", 8))
+        nelem = int(np.prod(shape)) if naxis else 0
+        nbytes = abs(bitpix) // 8 * (header.get("GCOUNT", 1) * (header.get("PCOUNT", 0) + nelem))
+        xt = str(header.get("XTENSION", "IMAGE")).strip()
+        is_image = (xt == "IMAGE" or "SIMPLE" in header) and naxis >= 2 and nelem > 0
+        data = None
+        if is_image:
+            arr = np.frombuffer(raw[pos:pos + nelem * abs(bitpix) // 8], dtype=dtypes[bitpix])
+            arr = arr.reshape(shape[::-1])
+            bs, bz = header.get("BSCALE", 1.0), header.get("BZERO", 0.0)
+            if bs != 1.0 or bz != 0.0:
+                arr = arr.astype(np.float32) * bs + bz
+            data = arr
+        hdus.append(_MiniHDU(header, data, is_image))
+        pos += -(-nbytes // 2880) * 2880
+    return hdus
+
+
+def open_fits(path):
+    if fits is not None:
+        return fits.open(path, memmap=True)
+    return _mini_open(path)
+
+UPPER = "▀"  # upper half block: fg = top pixel, bg = bottom pixel
+
+def _cubehelix(start=0.5, rot=-1.5, hue=1.2, n=9):
+    """Green (2011) cubehelix: brightness rises monotonically, so it prints well in grey too."""
+    out = []
+    for t in np.linspace(0, 1, n):
+        ang = 2 * math.pi * (start / 3 + 1 + rot * t)
+        amp = hue * t * (1 - t) / 2
+        c, s = math.cos(ang), math.sin(ang)
+        rgb = (t + amp * (-0.14861 * c + 1.78277 * s),
+               t + amp * (-0.29227 * c - 0.90649 * s),
+               t + amp * (1.97294 * c))
+        out.append(tuple(int(round(255 * min(1, max(0, v)))) for v in rgb))
+    return out
+
+
+# Sequential maps run low -> high. Maps listed in DIVERGING are centred on the
+# median (zero for a clean radio image): negatives go one way, positives the other.
+CMAPS = {
+    "inverted": [(255, 255, 255), (0, 0, 0)],
+    "gray": [(0, 0, 0), (255, 255, 255)],
+    "heat": [(0, 0, 0), (128, 0, 0), (255, 128, 0), (255, 255, 128), (255, 255, 255)],
+    "inferno": [(0, 0, 4), (31, 12, 72), (85, 15, 109), (136, 34, 106), (186, 54, 85),
+                (227, 89, 51), (249, 140, 10), (249, 201, 50), (252, 255, 164)],
+    "magma": [(0, 0, 4), (28, 16, 68), (79, 18, 123), (129, 37, 129), (181, 54, 122),
+              (229, 80, 100), (251, 135, 97), (254, 194, 135), (252, 253, 191)],
+    "viridis": [(68, 1, 84), (71, 45, 123), (59, 82, 139), (44, 114, 142), (33, 145, 140),
+                (39, 173, 129), (94, 201, 98), (170, 220, 50), (253, 231, 37)],
+    "cubehelix": _cubehelix(),
+    "cool": [(0, 0, 32), (0, 64, 160), (0, 200, 255), (255, 255, 255)],
+    "rainbow": [(48, 18, 59), (70, 107, 227), (40, 188, 235), (50, 241, 151), (164, 252, 60),
+                (237, 208, 58), (251, 128, 34), (210, 49, 5), (122, 4, 3)],   # turbo-like
+    "diverging": [(5, 48, 97), (33, 102, 172), (103, 169, 207), (209, 229, 240), (247, 247, 247),
+                  (253, 219, 199), (239, 138, 98), (178, 24, 43), (103, 0, 31)],
+}
+DIVERGING = {"diverging"}
+STRETCHES = ["linear", "sqrt", "log", "asinh"]
+CLIP_MODES = ["sigma", 99.5, 99.0, 98.0, 95.0, 100.0]   # "sigma" = median + k * robust rms
+
+OUTSIDE_RGB = (24, 24, 30)   # beyond the image edge
+NAN_RGB = (55, 40, 62)       # NaN / blanked pixels (e.g. outside the primary-beam cut)
+CROSS_RGB = (255, 60, 60)
+BEAM_RGB = (0, 170, 230)
+
+HELP_TEXT = __doc__.split("Keys:")[1].rstrip().splitlines()
+
+
+def build_lut(anchors):
+    a = np.array(anchors, float)
+    x = np.linspace(0, 1, len(a))
+    t = np.linspace(0, 1, 256)
+    return np.stack([np.interp(t, x, a[:, k]) for k in range(3)], 1).astype(np.uint8)
+
+
+LUTS = {name: build_lut(a) for name, a in CMAPS.items()}
+
+
+def apply_stretch(v, kind):
+    if kind == "sqrt":
+        return np.sqrt(v)
+    if kind == "log":
+        return np.log1p(1000 * v) / np.log1p(1000)
+    if kind == "asinh":
+        return np.arcsinh(10 * v) / np.arcsinh(10)
+    return v
+
+
+def fmt_sexa(ra, dec):
+    ra %= 360.0
+    h = ra / 15.0
+    hh = int(h); mm = int((h - hh) * 60); ss = ((h - hh) * 60 - mm) * 60
+    sign = "-" if dec < 0 else "+"
+    d = abs(dec)
+    dd = int(d); dm = int((d - dd) * 60); ds = ((d - dd) * 60 - dm) * 60
+    return f"{hh:02d}:{mm:02d}:{ss:05.2f} {sign}{dd:02d}:{dm:02d}:{ds:04.1f}"
+
+
+def robust_stats(a, max_samples=1_000_000):
+    """Median and MAD-based rms (1.4826 * MAD) of the finite values in a."""
+    flat = np.asarray(a).ravel()
+    if flat.size > 2 * max_samples:
+        flat = flat[:: flat.size // max_samples]
+    flat = flat[np.isfinite(flat)]
+    if flat.size == 0:
+        return 0.0, 1.0, flat
+    med = float(np.median(flat))
+    rms = 1.4826 * float(np.median(np.abs(flat - med)))
+    if not rms > 0:
+        rms = float(np.std(flat)) or 1.0
+    return med, rms, flat
+
+
+class Viewer:
+    STATUS_LINES = 4
+
+    def __init__(self, path, args):
+        self.path = path
+        self.hdul = open_fits(path)
+        self.hdus = [i for i, h in enumerate(self.hdul)
+                     if h.is_image and h.header.get("NAXIS", 0) >= 2]
+        if not self.hdus:
+            sys.exit(f"No 2-D (or higher) image HDUs found in {path}")
+        if args.hdu is not None:
+            if args.hdu not in self.hdus:
+                sys.exit(f"HDU {args.hdu} is not an image HDU; image HDUs: {self.hdus}")
+            self.hi = self.hdus.index(args.hdu)
+        else:
+            self.hi = 0
+        self.req_w, self.req_h = args.width, args.height
+        self.truecolor = not args.colors256
+        self.plane = args.plane
+        self.stretch_i = STRETCHES.index(args.stretch)
+        self.clip_i = CLIP_MODES.index("sigma" if args.clip == "sigma" else float(args.clip))
+        self.sig_lo, self.sig_hi = args.sigma_lo, args.sigma_hi
+        self.cmap_names = list(CMAPS)
+        self.cmap_i = self.cmap_names.index(args.cmap)
+        self.binmode = args.bin
+        self.cross = True
+        self.show_beam = True
+        self.show_help = False
+        self.message = ""
+        self.last_b = 1
+        self.update_geometry()
+        self.load_plane()
+        self.fit()
+
+    # ---------------- data ----------------
+    def load_plane(self):
+        hdu = self.hdul[self.hdus[self.hi]]
+        data = hdu.data
+        planes = data.reshape(-1, data.shape[-2], data.shape[-1])
+        self.nplanes = planes.shape[0]
+        self.plane = max(0, min(self.plane, self.nplanes - 1))
+        self.img = np.asarray(planes[self.plane], dtype=np.float32)
+        self.ny, self.nx = self.img.shape
+        self.header = hdu.header
+        self.pyramid = {}
+        self.read_header_info()
+        self.med, self.rms, self._sample = robust_stats(self.img)
+        self.noise_src = "global"
+        self.compute_limits()
+
+    def read_header_info(self):
+        h = self.header
+        self.wcs = None
+        try:
+            from astropy.wcs import WCS, FITSFixedWarning
+            with warnings.catch_warnings():
+                warnings.simplefilter("ignore", FITSFixedWarning)
+                w = WCS(h)
+            if w.has_celestial:
+                self.wcs = w.celestial
+        except Exception:
+            self.wcs = None
+        self.bunit = str(h.get("BUNIT", "")).strip()
+        pix = h.get("CDELT2", h.get("CD2_2", None))
+        self.pixscale = abs(float(pix)) if pix not in (None, 0) else None   # degrees
+        try:
+            self.beam = (float(h["BMAJ"]), float(h["BMIN"]), float(h.get("BPA", 0.0)))
+        except (KeyError, TypeError, ValueError):
+            self.beam = None
+
+    def compute_limits(self):
+        mode = CLIP_MODES[self.clip_i]
+        if mode == "sigma":
+            self.vmin = self.med - self.sig_lo * self.rms
+            self.vmax = self.med + self.sig_hi * self.rms
+        else:
+            flat = self._sample
+            if flat.size == 0:
+                self.vmin, self.vmax = 0.0, 1.0
+            else:
+                lo, hi = (100 - mode) / 2, 100 - (100 - mode) / 2
+                self.vmin, self.vmax = (float(v) for v in np.percentile(flat, [lo, hi]))
+        if not self.vmax > self.vmin:
+            self.vmax = self.vmin + (self.rms or 1.0)
+
+    def noise_from_view(self):
+        half_w, half_h = self.W / 2 / self.zoom, self.H / 2 / self.zoom
+        x0, x1 = int(max(0, self.cx - half_w)), int(min(self.nx, self.cx + half_w + 1))
+        y0, y1 = int(max(0, self.cy - half_h)), int(min(self.ny, self.cy + half_h + 1))
+        region = self.img[y0:y1, x0:x1]
+        if np.isfinite(region).sum() < 100:
+            self.message = "too few valid pixels in view to estimate noise"
+            return
+        self.med, self.rms, _ = robust_stats(region)
+        self.noise_src = "view"
+        self.compute_limits()
+
+    def binned(self, b):
+        """Downsampled copy for zoomed-out display: block mean or block max."""
+        if b == 1:
+            return self.img
+        key = (b, self.binmode)
+        if key not in self.pyramid:
+            ny2, nx2 = -(-self.ny // b) * b, -(-self.nx // b) * b
+            a = np.full((ny2, nx2), np.nan, np.float32)
+            a[: self.ny, : self.nx] = self.img
+            a = a.reshape(ny2 // b, b, nx2 // b, b)
+            with warnings.catch_warnings(), np.errstate(all="ignore"):
+                warnings.simplefilter("ignore", RuntimeWarning)
+                f = np.nanmax if self.binmode == "max" else np.nanmean
+                self.pyramid[key] = f(a, axis=(1, 3)).astype(np.float32)
+        return self.pyramid[key]
+
+    # ---------------- geometry ----------------
+    def update_geometry(self):
+        try:
+            ts = os.get_terminal_size()
+            tcols, trows = ts.columns, ts.lines
+        except OSError:
+            tcols, trows = self.req_w, self.req_h + self.STATUS_LINES
+        self.cols = max(10, min(self.req_w, tcols))
+        self.rows = max(5, min(self.req_h, trows - self.STATUS_LINES))
+        self.small = (self.cols < self.req_w) or (self.rows < self.req_h)
+        self.W, self.H = self.cols, self.rows * 2  # pixel grid (half blocks)
+
+    def fit_zoom(self):
+        return min(self.W / self.nx, self.H / self.ny)
+
+    def fit(self):
+        self.cx, self.cy = (self.nx - 1) / 2, (self.ny - 1) / 2
+        self.zoom = self.fit_zoom()
+
+    def set_zoom(self, z):
+        self.zoom = max(0.25 * self.fit_zoom(), min(64.0, z))
+
+    def pan(self, dx_screen, dy_screen):
+        self.cx += dx_screen / self.zoom
+        self.cy += dy_screen / self.zoom
+        self.cx = max(0, min(self.nx - 1, self.cx))
+        self.cy = max(0, min(self.ny - 1, self.cy))
+
+    # ---------------- rendering ----------------
+    def render_rgb(self):
+        s = self.zoom
+        # Bin by a power of two >= 1/zoom so no image pixel is ever skipped.
+        b = 1 if s >= 1 else 2 ** int(math.ceil(math.log2(1 / s) - 1e-9))
+        self.last_b = b
+        src = self.binned(b)
+        sh, sw = src.shape
+        i0, j0 = self.W // 2, self.H // 2
+        x = self.cx + (np.arange(self.W) - i0) / s
+        y = self.cy - (np.arange(self.H) - j0) / s       # FITS y increases upward
+        xb = np.floor((x + 0.5) / b).astype(np.int64)
+        yb = np.floor((y + 0.5) / b).astype(np.int64)
+        okx = (x >= -0.5) & (x < self.nx - 0.5)
+        oky = (y >= -0.5) & (y < self.ny - 0.5)
+        vals = src[np.clip(yb, 0, sh - 1)[:, None], np.clip(xb, 0, sw - 1)[None, :]]
+        outside = ~(oky[:, None] & okx[None, :])
+        nan = ~np.isfinite(vals) & ~outside
+
+        cmap = self.cmap_names[self.cmap_i]
+        with np.errstate(all="ignore"):
+            if cmap in DIVERGING:
+                # Symmetric about the median: white = median, blue = negative, red = positive.
+                span = max(self.vmax - self.med, self.med - self.vmin)
+                d = np.nan_to_num((vals - self.med) / span, nan=0.0)
+                mag = apply_stretch(np.clip(np.abs(d), 0, 1), STRETCHES[self.stretch_i])
+                v = 0.5 + 0.5 * np.sign(d) * mag
+            else:
+                v = (vals - self.vmin) / (self.vmax - self.vmin)
+                v = np.clip(np.nan_to_num(v, nan=0.0), 0, 1)
+                v = apply_stretch(v, STRETCHES[self.stretch_i])
+        rgb = LUTS[cmap][(np.clip(v, 0, 1) * 255).astype(np.uint8)]
+        rgb[outside] = OUTSIDE_RGB
+        rgb[nan] = NAN_RGB
+
+        if self.show_beam:
+            self.draw_beam(rgb)
+        if self.cross:
+            for d in (2, 3, 4):
+                for (yy, xx) in ((j0, i0 - d), (j0, i0 + d), (j0 - d, i0), (j0 + d, i0)):
+                    if 0 <= yy < self.H and 0 <= xx < self.W:
+                        rgb[yy, xx] = CROSS_RGB
+        return rgb
+
+    def beam_pixels(self):
+        if self.beam is None or self.pixscale is None:
+            return None
+        bmaj, bmin, bpa = self.beam
+        return bmaj / self.pixscale, bmin / self.pixscale, bpa
+
+    def draw_beam(self, rgb):
+        """Filled restoring-beam ellipse in the lower-left corner (north up, east left)."""
+        bp = self.beam_pixels()
+        if bp is None:
+            return
+        a = bp[0] / 2 * self.zoom
+        b = bp[1] / 2 * self.zoom
+        if a < 0.75 or a > self.H / 4:
+            return
+        th = math.radians(bp[2])
+        u = (-math.sin(th), -math.cos(th))          # major axis, screen coords (y down)
+        v = (math.cos(th), -math.sin(th))
+        r = int(math.ceil(a)) + 1
+        ex, ey = 2 + r, self.H - 3 - r
+        yy, xx = np.mgrid[ey - r: ey + r + 1, ex - r: ex + r + 1]
+        dx, dy = xx - ex, yy - ey
+        p = dx * u[0] + dy * u[1]
+        q = dx * v[0] + dy * v[1]
+        inside = (p / a) ** 2 + (q / max(b, 0.5)) ** 2 <= 1
+        ok = inside & (yy >= 0) & (yy < self.H) & (xx >= 0) & (xx < self.W)
+        rgb[yy[ok], xx[ok]] = BEAM_RGB
+
+    def color_code(self, rgb, fg):
+        if self.truecolor:
+            return f"{38 if fg else 48};2;{rgb[0]};{rgb[1]};{rgb[2]}"
+        r, g, b = (int(round(c / 255 * 5)) for c in rgb)
+        if r == g == b:
+            gray = int(round(rgb[0] / 255 * 25))       # use the finer gray ramp
+            idx = 16 if gray == 0 else (231 if gray == 25 else 231 + gray)
+        else:
+            idx = 16 + 36 * r + 6 * g + b
+        return f"{38 if fg else 48};5;{idx}"
+
+    def frame(self, home=True):
+        rgb = self.render_rgb().tolist()
+        out = ["\x1b[H" if home else ""]
+        for r in range(self.rows):
+            if home:
+                out.append(f"\x1b[{r + 1};1H")
+            top, bot = rgb[2 * r], rgb[2 * r + 1]
+            prev = None
+            for c in range(self.cols):
+                key = (tuple(top[c]), tuple(bot[c]))
+                if key != prev:
+                    out.append(f"\x1b[{self.color_code(key[0], True)};"
+                               f"{self.color_code(key[1], False)}m")
+                    prev = key
+                out.append(UPPER)
+            out.append("\x1b[0m\x1b[K" + ("" if home else "\n"))
+        out.extend(self.status(home))
+        return "".join(out)
+
+    # ---------------- status ----------------
+    def flux_fmt(self):
+        """Returns (scale, unit label) chosen so the rms reads as a sensible number."""
+        u = self.bunit
+        if "JY" in u.upper():
+            rest = u[2:] if u.upper().startswith("JY") else ""
+            rest = "/beam" if rest.upper() == "/BEAM" else rest
+            for scale, prefix in ((1, ""), (1e3, "m"), (1e6, "µ"), (1e9, "n")):
+                if abs(self.rms) * scale >= 1 or scale == 1e9:
+                    return scale, f"{prefix}Jy{rest}"
+        return 1.0, u
+
+    def pixel_value(self):
+        ix, iy = int(round(self.cx)), int(round(self.cy))
+        if 0 <= ix < self.nx and 0 <= iy < self.ny:
+            return ix, iy, float(self.img[iy, ix])
+        return ix, iy, float("nan")
+
+    def status(self, home):
+        ix, iy, val = self.pixel_value()
+        scale, unit = self.flux_fmt()
+        hdu_idx = self.hdus[self.hi]
+        name = self.header.get("EXTNAME", "PRIMARY" if hdu_idx == 0 else "")
+        plane = f"  plane {self.plane + 1}/{self.nplanes}" if self.nplanes > 1 else ""
+        binning = f" (bin {self.last_b} {self.binmode})" if self.last_b > 1 else ""
+        l1 = (f"{os.path.basename(self.path)}  HDU {hdu_idx} {name}  "
+              f"{self.nx}x{self.ny}{plane}  zoom {self.zoom:.3g}x{binning}")
+
+        if math.isfinite(val):
+            snr = (val - self.med) / self.rms
+            l2 = f"pix ({ix + 1}, {iy + 1})  {val * scale:.4g} {unit}  {snr:+.1f}σ"
+        else:
+            l2 = f"pix ({ix + 1}, {iy + 1})  blank"
+        if self.wcs is not None:
+            try:
+                ra, dec = self.wcs.pixel_to_world_values(self.cx, self.cy)
+                l2 += f"   {fmt_sexa(float(ra), float(dec))}"
+            except Exception:
+                pass
+
+        mode = CLIP_MODES[self.clip_i]
+        if mode == "sigma":
+            clip = f"{-self.sig_lo:+g}σ..{self.sig_hi:+.3g}σ"
+        else:
+            clip = "min/max" if mode == 100 else f"{mode}%"
+        l3 = f"clip {clip}  rms {self.rms * scale:.3g} {unit} ({self.noise_src})"
+        bp = self.beam_pixels()
+        if self.beam is not None:
+            l3 += (f"  beam {self.beam[0] * 3600:.3g}\"x{self.beam[1] * 3600:.3g}\" "
+                   f"{self.beam[2]:.0f}°")
+            if bp is not None:
+                l3 += f" ({bp[0]:.1f}px)"
+        l3 += f"  {STRETCHES[self.stretch_i]} {self.cmap_names[self.cmap_i]}"
+
+        l4 = self.message or ("arrows pan  +/- zoom  f fit  1 1:1  < > max  ( ) min  "
+                              "c clip  n noise  b bin  ? help  q quit")
+        if self.small:
+            l4 = f"(terminal too small for {self.req_w}x{self.req_h}; showing {self.cols}x{self.rows}) " + l4
+        out = []
+        for k, line in enumerate([l1, l2, l3, l4]):
+            line = line[: max(self.cols, 40)]
+            style = "\x1b[7m" if k == 0 else ("\x1b[2m" if k == 3 else "")
+            if home:
+                out.append(f"\x1b[{self.rows + 1 + k};1H{style}{line}\x1b[0m\x1b[K")
+            else:
+                out.append(line + "\n")
+        return out
+
+    def help_frame(self):
+        out = ["\x1b[H\x1b[2J", "\x1b[1m termfits - keys\x1b[0m\r\n\r\n"]
+        for line in HELP_TEXT:
+            out.append(line + "\r\n")
+        out.append("\r\n press any key to return")
+        return "".join(out)
+
+    # ---------------- input ----------------
+    def handle(self, key):
+        self.message = ""
+        step, big = self.W / 10, self.W / 2
+        stepy, bigy = self.H / 10, self.H / 2
+        moves = {
+            "LEFT": (-step, 0), "RIGHT": (step, 0), "UP": (0, stepy), "DOWN": (0, -stepy),
+            "h": (-step, 0), "l": (step, 0), "k": (0, stepy), "j": (0, -stepy),
+            "S-LEFT": (-big, 0), "S-RIGHT": (big, 0), "S-UP": (0, bigy), "S-DOWN": (0, -bigy),
+            "H": (-big, 0), "L": (big, 0), "K": (0, bigy), "J": (0, -bigy),
+        }
+        if key in moves:
+            self.pan(*moves[key])
+        elif key in ("+", "="):
+            self.set_zoom(self.zoom * math.sqrt(2))
+        elif key in ("-", "_"):
+            self.set_zoom(self.zoom / math.sqrt(2))
+        elif key == "f":
+            self.zoom = self.fit_zoom()
+        elif key == "1":
+            self.zoom = 1.0
+        elif key == "r":
+            self.fit()
+        elif key in ("<", ",", ">", ".", "(", ")"):
+            self.clip_i = 0                       # these keys work in sigma mode
+            if key in ("<", ","):
+                self.sig_hi = max(0.5, self.sig_hi / 1.25)
+            elif key in (">", "."):
+                self.sig_hi = min(1e5, self.sig_hi * 1.25)
+            elif key == "(":
+                self.sig_lo += 0.5
+            elif key == ")" and self.sig_hi + (self.sig_lo - 0.5) > 0.4:
+                self.sig_lo -= 0.5
+            self.compute_limits()
+        elif key == "c":
+            self.clip_i = (self.clip_i + 1) % len(CLIP_MODES)
+            self.compute_limits()
+        elif key == "n":
+            self.noise_from_view()
+        elif key == "N":
+            self.med, self.rms, _ = robust_stats(self.img)
+            self.noise_src = "global"
+            self.compute_limits()
+        elif key == "b":
+            self.binmode = "max" if self.binmode == "mean" else "mean"
+            self.message = f"zoomed-out binning: block {self.binmode}"
+        elif key == "e":
+            self.show_beam = not self.show_beam
+        elif key == "s":
+            self.stretch_i = (self.stretch_i + 1) % len(STRETCHES)
+        elif key == "m":
+            self.cmap_i = (self.cmap_i + 1) % len(self.cmap_names)
+            self.message = f"colour map: {self.cmap_names[self.cmap_i]}"
+        elif key == "M":
+            self.cmap_i = (self.cmap_i - 1) % len(self.cmap_names)
+            self.message = f"colour map: {self.cmap_names[self.cmap_i]}"
+        elif key == "x":
+            self.cross = not self.cross
+        elif key in ("[", "]"):
+            if self.nplanes > 1:
+                self.plane = (self.plane + (1 if key == "]" else -1)) % self.nplanes
+                self.load_plane()
+            else:
+                self.message = "single-plane image"
+        elif key == "TAB":
+            if len(self.hdus) > 1:
+                self.hi = (self.hi + 1) % len(self.hdus)
+                self.plane = 0
+                self.load_plane()
+                self.fit()
+            else:
+                self.message = "only one image HDU in this file"
+        elif key == "?":
+            self.show_help = True
+
+
+def read_key(fd):
+    ch = os.read(fd, 1)
+    if ch == b"\x1b":
+        r, _, _ = select.select([fd], [], [], 0.03)
+        if not r:
+            return "ESC"
+        seq = os.read(fd, 16)
+        arrows = {b"A": "UP", b"B": "DOWN", b"C": "RIGHT", b"D": "LEFT"}
+        if seq[:1] in (b"[", b"O") and seq[-1:] in arrows:
+            name = arrows[seq[-1:]]
+            return ("S-" + name) if b";2" in seq else name
+        return None
+    if ch == b"\t":
+        return "TAB"
+    try:
+        return ch.decode()
+    except UnicodeDecodeError:
+        return None
+
+
+def run(viewer):
+    try:
+        import termios
+        import tty
+    except ImportError:
+        sys.exit("termfits needs a POSIX terminal (Linux, macOS or WSL on Windows). "
+                 "--snapshot works anywhere.")
+    fd = sys.stdin.fileno()
+    if not os.isatty(fd):
+        sys.exit("stdin is not a terminal (use --snapshot for non-interactive output)")
+    old = termios.tcgetattr(fd)
+    resized = {"flag": False}
+    signal.signal(signal.SIGWINCH, lambda *_: resized.update(flag=True))
+    w = sys.stdout.write
+    try:
+        tty.setcbreak(fd)
+        w("\x1b[?1049h\x1b[?25l\x1b[2J")
+        while True:
+            if resized["flag"]:
+                resized["flag"] = False
+                viewer.update_geometry()
+                w("\x1b[2J")
+            if viewer.show_help:
+                w(viewer.help_frame())
+                sys.stdout.flush()
+                read_key(fd)
+                viewer.show_help = False
+                w("\x1b[2J")
+                continue
+            w(viewer.frame())
+            sys.stdout.flush()
+            try:
+                key = read_key(fd)
+            except InterruptedError:
+                continue
+            if key in ("q", "Q", "ESC"):
+                break
+            if key:
+                viewer.handle(key)
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, old)
+        w("\x1b[0m\x1b[?25h\x1b[?1049l")
+        sys.stdout.flush()
+        viewer.hdul.close()
+
+
+def main(argv=None):
+    from . import __version__
+    p = argparse.ArgumentParser(
+        prog="termfits",
+        description="Terminal FITS image viewer with zoom and pan, tuned for radio images.",
+        epilog="Press ? inside the viewer for the key list.")
+    p.add_argument("file", help="FITS file")
+    p.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    p.add_argument("--hdu", type=int, help="HDU index to open (default: first image HDU)")
+    p.add_argument("--plane", type=int, default=0, help="starting plane for cubes (0-based)")
+    p.add_argument("--width", type=int, default=100, help="view width in characters (default 100)")
+    p.add_argument("--height", type=int, default=100, help="view height in characters (default 100)")
+    p.add_argument("--clip", choices=["sigma", "99.5", "99", "98", "95", "100"], default="sigma",
+                   help="display limits: sigma (median + k*rms, default) or a percentile")
+    p.add_argument("--sigma-lo", type=float, default=1.0, help="lower limit in rms below median (default 1)")
+    p.add_argument("--sigma-hi", type=float, default=10.0, help="upper limit in rms above median (default 10)")
+    p.add_argument("--stretch", choices=STRETCHES, default="linear")
+    p.add_argument("--cmap", choices=list(CMAPS), default="inverted",
+                   help="starting colour map (default inverted; m / M cycle in the viewer)")
+    p.add_argument("--bin", choices=["mean", "max"], default="mean",
+                   help="how pixels are combined when zoomed out (default mean)")
+    p.add_argument("--256", dest="colors256", action="store_true",
+                   help="use 256-colour mode for terminals without truecolor")
+    p.add_argument("--snapshot", action="store_true", help="print one frame to stdout and exit")
+    args = p.parse_args(argv)
+    if not os.path.isfile(args.file):
+        p.error(f"no such file: {args.file}")
+
+    v = Viewer(args.file, args)
+    if args.snapshot:
+        sys.stdout.write(v.frame(home=False))
+        v.hdul.close()
+    else:
+        run(v)
+
+
+if __name__ == "__main__":
+    main()

termfits-0.1.0.dist-info/METADATA

@@ -0,0 +1,162 @@
+Metadata-Version: 2.4
+Name: termfits
+Version: 0.1.0
+Summary: A terminal FITS image viewer with zoom and pan, tuned for radio images
+Author-email: Ian Heywood <email.ian.heywood@gmail.com>
+License: MIT
+Project-URL: Homepage, https://github.com/ianheywood/termfits
+Project-URL: Issues, https://github.com/ianheywood/termfits/issues
+Keywords: fits,astronomy,radio astronomy,terminal,viewer,tui
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: POSIX
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Astronomy
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: numpy>=1.21
+Requires-Dist: astropy>=5.0
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# termfits
+
+A FITS image viewer that runs in your terminal, built for quick looks at radio images
+over SSH: no X forwarding, no VNC, no copying files back to your laptop.
+
+![termfits showing a radio field: default limits vs a tightened upper limit](https://raw.githubusercontent.com/ianheywood/termfits/main/docs/images/radio_sigma_limits.png)
+
+It draws the image with Unicode half-block characters in 24-bit colour. Each character
+cell holds two pixels, so a 100 x 100 character window shows a 100 x 200 grid of
+roughly square pixels. You can zoom, pan, step through cube planes and switch extensions,
+and the status bar reports the pixel value, its significance in sigma, the position
+in RA/Dec, the noise and the beam.
+
+## Install
+
+```bash
+pip install termfits
+```
+
+This installs a `termfits` command. termfits needs Python 3.9+, numpy and astropy, and
+a terminal with truecolour support: most current terminals have it, including iTerm2,
+GNOME Terminal, Konsole, kitty, WezTerm, Alacritty, Windows Terminal (via WSL) and tmux
+with `set -g default-terminal "tmux-256color"` and `set -as terminal-features ",*:RGB"`.
+It runs on Linux and macOS, or under WSL on Windows.
+
+## Use
+
+```bash
+termfits image.fits
+termfits cube.fits --plane 120 --cmap inferno
+termfits image.fits --sigma-hi 4           # tighter limits for faint emission
+termfits image.fits --width 100 --height 50  # square-ish view for a square image
+```
+
+Make your terminal at least 100 columns by 104 rows for the default view (100 x 100
+plus a 4-line status bar), or set `--width` / `--height` to fit. Terminal characters are
+about twice as tall as they are wide, so `--height` set to half of `--width` gives a
+square viewing area.
+
+Press `?` in the viewer for the key list.
+
+| Keys | Action |
+|---|---|
+| arrows or `h j k l` | pan by 10% of the view |
+| Shift+arrows or `H J K L` | pan by half the view |
+| `+` / `-` | zoom in / out |
+| `f` / `1` / `r` | fit image / 1:1 / reset |
+| `<` `>` | lower / raise the upper display limit (sigma) |
+| `(` `)` | lower / raise the lower display limit (sigma) |
+| `c` | cycle clip mode: sigma, 99.5, 99, 98, 95 %, min/max |
+| `n` / `N` | measure the noise in the current view / back to the whole image |
+| `b` | zoomed-out binning: block mean / block max |
+| `m` / `M` | next / previous colour map |
+| `s` | cycle stretch: linear, sqrt, log, asinh |
+| `e` / `x` | toggle beam ellipse / crosshair |
+| `[` `]` | previous / next plane (channel, Stokes) |
+| `Tab` | next image extension |
+| `q` or `Esc` | quit |
+
+`termfits image.fits --snapshot` prints one frame to stdout and exits, which is handy
+for logs or notebooks.
+
+## Radio defaults
+
+- **Display limits from the noise.** The rms is estimated as 1.4826 x the median
+  absolute deviation, which bright sources barely affect. The default range is -1 to
+  +10 sigma about the median. Press `n` to re-measure the noise from the region in view
+  when it varies across the field (e.g. towards the primary-beam edge).
+- **Values in sigma.** The status bar shows the pixel under the crosshair in BUNIT
+  (scaled to Jy, mJy or µJy so the rms reads sensibly) and in sigma.
+- **Beam.** BMAJ/BMIN/BPA from the header are shown in arcsec and pixels, and the beam
+  is drawn in the lower-left corner once it is large enough to see.
+- **Blanked pixels** (NaNs, e.g. outside a primary-beam cut) are drawn in a muted purple
+  so they are not mistaken for zero.
+
+## Zoomed out: what you can and can't trust
+
+When the image is larger than the view, blocks of pixels are combined into one screen
+pixel; none are skipped.
+
+![Block mean vs block max for the whole field](https://raw.githubusercontent.com/ianheywood/termfits/main/docs/images/mean_vs_max.png)
+
+- **Block mean** (default) lowers the noise, so faint *extended* emission stands out,
+  but faint *compact* sources are diluted and can vanish.
+- **Block max** (`b`) keeps every compact source visible, but it also lifts the
+  background: the maximum of many noise pixels sits around +3 sigma, so noise peaks
+  look like sources.
+
+Use either for finding candidates, then press `1` to inspect them at full resolution.
+For decisions about marginal detections, use a full-resolution viewer such as CARTA
+or DS9.
+
+## Colour maps
+
+![The ten colour maps on the same field](https://raw.githubusercontent.com/ianheywood/termfits/main/docs/images/colourmaps.png)
+
+`inverted` (default) and `gray`; `heat` (DS9-style); `inferno`, `magma`, `viridis` and
+`cubehelix`, which are perceptually uniform and the best colour choices for faint
+features; `cool`; `rainbow` (turbo-like, good for bright high-dynamic-range regions,
+but it creates false contours in noise); and `diverging`, which is centred on the
+median so negative sidelobes show blue and positive emission red.
+
+Truecolour gives the full range; `--256` is a fallback for terminals without it, and
+colour maps get coarse there (6 levels per channel).
+
+## Data support
+
+- 2-D images, and cubes of any dimension: extra axes (FREQ, STOKES, ...) are
+  flattened into planes stepped with `[` and `]`.
+- Multi-extension files: every image HDU is reachable with `Tab`.
+- RA/Dec readout from the celestial WCS via astropy.
+- Large images: one plane is loaded into memory as float32 (about 400 MB for
+  10k x 10k). The first zoom-out builds the binned copies, which takes a few seconds;
+  after that it is quick.
+- If astropy is missing, a built-in reader handles plain uncompressed images, without
+  WCS.
+
+Not yet supported: per-channel beams stored in a CASA `BEAMS` table (the header beam is
+used), and tile-compressed images without astropy.
+
+## Development
+
+```bash
+git clone https://github.com/ianheywood/termfits
+cd termfits
+pip install -e ".[test]"
+pytest
+```
+
+The screenshots in `docs/images` were rendered from termfits' own output, using
+synthetic data.
+
+## Licence
+
+MIT. See [LICENSE](LICENSE).

termfits-0.1.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+termfits/__init__.py,sha256=7GMBXFQ0nqBqVCn7iIzsyHazHIz1K89HFbqmCannTH0,280
+termfits/__main__.py,sha256=WtCt1iyekjUh0YPYLne9Fd6e3DsB83PZQYetYMvCNNY,64
+termfits/viewer.py,sha256=iE36Tw-Ld086clNmgFo6eHoYNhXFmjXMRaZlOmnDJPc,29859
+termfits-0.1.0.dist-info/licenses/LICENSE,sha256=PxHT1GItiPOQJfOrydpzSFFBHR9jghVzVpUbqPERcxw,1068
+termfits-0.1.0.dist-info/METADATA,sha256=E-W-5WuJSWr9ib8fZ2qazLWeE7vUHio8zza_0V3NP5w,6881
+termfits-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+termfits-0.1.0.dist-info/entry_points.txt,sha256=tT_mwVI3zPQqCifc2f7OfVZBgokdHTS6-yByVVAor3w,50
+termfits-0.1.0.dist-info/top_level.txt,sha256=1YYwQUYxorUf25Y_rdRN8pZZTcSAvetv9Ao0MWSb_vs,9
+termfits-0.1.0.dist-info/RECORD,,

termfits-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

termfits-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+termfits = termfits.viewer:main

termfits-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ian Heywood
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

termfits-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+termfits