specterm1d 0.1.0__py3-none-any.whl

specterm1d/cli.py

@@ -0,0 +1,155 @@
+"""Command-line entry point."""
+from __future__ import annotations
+
+import argparse
+import io
+import sys
+from pathlib import Path
+
+import specterm1d.commands
+import specterm1d.term  # noqa: F401  - registers renderer factories
+from specterm1d.io import registry
+from specterm1d.logfile import SplotLog
+from specterm1d.plot import SpectrumPlot
+from specterm1d.session import Session
+from specterm1d.term import caps as caps_mod
+
+RENDERERS = ("kitty", "iterm2", "sixel", "gui", "halfblock")
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="specterm1d",
+        description="Terminal 1D spectrum viewer with IRAF splot keybindings",
+    )
+    parser.add_argument("files", nargs="*", type=Path, help="FITS spectra to view")
+    parser.add_argument("--renderer", choices=RENDERERS,
+                        help="force a renderer instead of probing the terminal")
+    parser.add_argument("--gui", action="store_true",
+                        help="shortcut for --renderer gui (a matplotlib window)")
+    parser.add_argument("--format", help="force a loader instead of sniffing")
+    parser.add_argument("--units", help="initial dispersion units, e.g. nm, um, GHz")
+    parser.add_argument(
+        "--mouse", action=argparse.BooleanOptionalAction, default=None,
+        help="toggle mouse positioning (default: on for inline graphics)",
+    )
+    parser.add_argument("--log", default="splot.log", help="measurement log file")
+    parser.add_argument("--debug", action="store_true",
+                        help="show full tracebacks instead of one-line errors")
+    parser.add_argument("--cursor", type=Path,
+                        help="run a cursor script instead of reading the keyboard")
+    parser.add_argument("--dump", type=Path,
+                        help="render one frame to a PNG and exit (no tty needed)")
+    parser.add_argument("--dump-size", default="1200x700",
+                        help="pixel size for --dump, as WxH")
+    return parser
+
+
+def resolve_renderer_choice(args) -> str | None:
+    """--gui is a shortcut; an explicit --renderer always wins."""
+    if args.renderer:
+        return args.renderer
+    return "gui" if args.gui else None
+
+
+def attach_or_fall_back(renderer, plot, caps, out):
+    """Open the renderer's window, or warn once and use halfblock.
+
+    A viewer that refuses to start over a missing window is worse than one
+    that draws coarsely, so this is never fatal - even for an explicit
+    --renderer gui. Terminal backends have no attach() and pass straight
+    through.
+    """
+    from specterm1d.term.gui import GuiUnavailable
+    from specterm1d.term.halfblock import HalfblockRenderer
+
+    attach = getattr(renderer, "attach", None)
+    if attach is None:
+        return renderer
+    try:
+        attach(plot)
+    except GuiUnavailable as exc:
+        print(f"graphics window unavailable ({exc}); using halfblock",
+              file=sys.stderr)
+        return HalfblockRenderer(out=out, truecolor=caps.truecolor)
+    return renderer
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+
+    if not args.files:
+        build_parser().print_help()
+        return 2
+
+    try:
+        collection = registry.load(args.files[0], format=args.format)
+    except registry.LoaderError as exc:
+        print(str(exc), file=sys.stderr)
+        return 1
+
+    # Headless: --dump and --cursor must work with no tty at all, so this
+    # branches before the tty check.
+    if args.dump or args.cursor:
+        from specterm1d.cursorscript import parse_script, run_script
+        from specterm1d.term.halfblock import HalfblockRenderer
+
+        width, height = (int(v) for v in args.dump_size.lower().split("x"))
+        caps = caps_mod.TerminalCaps(
+            kitty=False, iterm2=False, sixel=False, truecolor=True,
+            rows=height // 2, cols=width, pixel_width=width,
+            pixel_height=height, is_tty=False,
+        )
+        session = Session(collection, HalfblockRenderer(out=io.StringIO()),
+                          SpectrumPlot(width, height), out=io.StringIO(),
+                          caps=caps)
+        session.debug = args.debug
+        session.log = SplotLog(args.log)
+        if args.units:
+            import astropy.units as u
+            session.view.set_axis(unit=u.Unit(args.units))
+        if args.cursor:
+            run_script(session, parse_script(args.cursor.read_text()))
+        if args.dump:
+            session.dump_png(args.dump, size=(width, height))
+        return 0
+
+    caps = caps_mod.detect(is_tty=sys.stdout.isatty())
+    if not caps.is_tty:
+        print("specterm1d needs a terminal; stdout is not a tty.", file=sys.stderr)
+        return 1
+
+    renderer = caps_mod.choose_renderer(caps, override=resolve_renderer_choice(args),
+                                        out=sys.stdout)
+    width, height = renderer.target_pixels(caps.rows - 2, caps.cols)
+    plot = SpectrumPlot(width, height)
+    renderer = attach_or_fall_back(renderer, plot, caps, out=sys.stdout)
+    session = Session(collection, renderer, plot, out=sys.stdout, caps=caps)
+    session.debug = args.debug
+
+    if args.log:
+        session.log = SplotLog(args.log)
+
+    if args.units:
+        import astropy.units as u
+        session.view.set_axis(unit=u.Unit(args.units))
+
+    mouse_enabled = args.mouse
+    if mouse_enabled is None:
+        mouse_enabled = bool(getattr(renderer, "inline_graphics", False))
+    if mouse_enabled:
+        session.set_mouse(True)
+
+    try:
+        session.run()
+    except Exception as exc:
+        session.teardown()
+        if args.debug:
+            raise
+        print(f"error: {exc}", file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

specterm1d/commands/__init__.py

@@ -0,0 +1,9 @@
+"""Importing this package registers every command handler."""
+from specterm1d.commands import (
+    colon,
+    display,
+    measure,
+    transform,
+)
+
+__all__ = ["colon", "display", "measure", "transform"]

specterm1d/commands/colon.py

@@ -0,0 +1,174 @@
+"""Colon commands.
+
+splot's set is reproduced except :dispaxis and :nsum, which are 2D-image
+concerns - this tool ingests 1D. New commands cover the toggles splot had no
+concept of: overlays, the sigma band, the mask, and the variant.
+"""
+from __future__ import annotations
+
+import astropy.units as u
+
+from specterm1d.keymap import command
+
+_TRUE = {"yes", "y", "true", "on", "1", "+"}
+_FALSE = {"no", "n", "false", "off", "0", "-"}
+
+
+def parse_colon(text: str) -> tuple[str, list[str]]:
+    stripped = text.strip()
+    if not stripped:
+        return ("", [])
+    if stripped.startswith("#"):
+        return ("#", [stripped[1:].strip()])
+    head, _, tail = stripped.partition(" ")
+    return (head, tail.split() if tail.strip() else [])
+
+
+def _boolean(args: list[str], current: bool) -> bool:
+    if not args:
+        return not current
+    value = args[0].lower()
+    if value in _TRUE:
+        return True
+    if value in _FALSE:
+        return False
+    return not current
+
+
+def _view_toggle(field: str, label: str):
+    def handler(session, args):
+        current = getattr(session.view, field)
+        new = _boolean(args, current)
+        setattr(session.view, field, new)
+        if field in ("zero_base",):
+            session.view.rescale_y()
+        session.message(f"{label} {'on' if new else 'off'}")
+    return handler
+
+
+def _overlay_toggle(name: str):
+    def handler(session, args):
+        if name in session.view.overlays:
+            session.view.overlays.discard(name)
+            session.message(f"{name} overlay off")
+        else:
+            session.view.overlays.add(name)
+            available = session.view.current_spec().overlays
+            if name not in available:
+                session.message(f"{name} overlay on (not present in this file)")
+            else:
+                session.message(f"{name} overlay on")
+    return handler
+
+
+def _cmd_log(session, args):
+    session.log.enable()
+    session.message(f"logging to {session.log.path}")
+
+
+def _cmd_nolog(session, args):
+    session.log.disable()
+    session.message("logging disabled")
+
+
+def _cmd_show(session, args):
+    session.showing_log = not session.showing_log
+    session.page_index = 0
+    if not session.showing_log:
+        session._close_text_page()
+
+
+def _cmd_units(session, args):
+    if not args:
+        session.message(f"units {session.view.axis.unit.to_string()}")
+        return
+    try:
+        unit = u.Unit(args[0])
+    except ValueError:
+        session.message(f"unknown unit: {args[0]}")
+        return
+    try:
+        session.view.set_axis(mode="wave", unit=unit)
+    except u.UnitConversionError:
+        session.message(f"cannot express the dispersion in {args[0]}")
+        return
+    session.view.rescale_y()
+    session.message(f"units {unit.to_string()}")
+
+
+def _cmd_comment(session, args):
+    session.log.comment(args[0] if args else "")
+    session.message("comment added to the log")
+
+
+def _cmd_variant(session, args):
+    keys = session.view.entry.variant_keys()
+    if not args:
+        session.message("variants: " + "  ".join(keys))
+        return
+    if args[0] not in keys:
+        session.message(f"no variant {args[0]!r}; have: {'  '.join(keys)}")
+        return
+    session.view.variant = args[0]
+    session.view.rescale_y()
+    session.message(f"variant {args[0]}")
+
+
+def _cmd_renderer(session, args):
+    session.message(f"renderer {session.renderer.name} "
+                    "(change with --renderer at startup)")
+
+
+def _cmd_mouse(session, args):
+    session.set_mouse(_boolean(args, session.mouse_enabled))
+
+
+def _cmd_not_applicable(name: str):
+    def handler(session, args):
+        session.message(f":{name} applies to 2D images; specterm1d ingests 1D")
+    return handler
+
+
+COLON_COMMANDS = {
+    "log": _cmd_log,
+    "nolog": _cmd_nolog,
+    "show": _cmd_show,
+    "units": _cmd_units,
+    "#": _cmd_comment,
+    "variant": _cmd_variant,
+    "renderer": _cmd_renderer,
+    "mouse": _cmd_mouse,
+    "zero": _view_toggle("zero_base", "zero base"),
+    "hist": _view_toggle("histogram", "histogram"),
+    "flip": _view_toggle("flip", "flipped coordinates"),
+    "wreset": _view_toggle("window_reset", "window reset"),
+    "overplot": _view_toggle("overplot_next", "overplot"),
+    "sigma": _view_toggle("show_sigma", "sigma band"),
+    "mask": _view_toggle("show_mask", "mask highlight"),
+    "sky": _overlay_toggle("sky"),
+    "telluric": _overlay_toggle("telluric"),
+    "model": _overlay_toggle("obj_model"),
+    "dispaxis": _cmd_not_applicable("dispaxis"),
+    "nsum": _cmd_not_applicable("nsum"),
+}
+# splot accepts these but they are no-ops here: we always draw our own frame.
+COLON_COMMANDS["auto"] = _view_toggle("window_reset", "autodraw")
+COLON_COMMANDS["nosysid"] = lambda s, a: s.message("nosysid has no effect here")
+
+
+@command("colon.prompt")
+def colon_prompt(session):
+    def submitted(sess, text):
+        if text is None:
+            sess.message("cancelled")
+            return
+        name, args = parse_colon(text)
+        if not name:
+            return
+        handler = COLON_COMMANDS.get(name)
+        if handler is None:
+            sess.message(f"unknown colon command: {name}")
+            return
+        handler(sess, args)
+
+    session.await_line(":", submitted)

specterm1d/commands/display.py

@@ -0,0 +1,347 @@
+"""Display and navigation commands - splot's viewing keys."""
+from __future__ import annotations
+
+import numpy as np
+
+from specterm1d.keymap import STATUS_HINTS, command
+
+SHIFT_FRACTION = 0.25
+ZOOM_FACTOR = 2.0
+
+
+def _spec_and_pixel(session, x: float):
+    spec = session.view.display_spec()
+    pixel = int(np.clip(np.searchsorted(spec.wave, x), 0, spec.npix - 1))
+    return spec, pixel
+
+
+@command("display.report")
+def report(session):
+    """<space>: cursor position and the nearest pixel's value."""
+    x = session.view.cursor_x
+    if x is None:
+        session.message("no cursor")
+        return
+    spec, pixel = _spec_and_pixel(session, x)
+    session.message(
+        f"x={x:.6g}  y={spec.flux[pixel]:.6g}  pix={pixel}  "
+        f"wave={spec.wave[pixel]:.6g}"
+    )
+
+
+@command("display.expand")
+def expand(session):
+    """a: expand between two cursors; the same point twice autoscales all."""
+    def done(sess, positions):
+        xs = [x for x, _ in positions]
+        lo, hi = min(xs), max(xs)
+        if np.isclose(lo, hi):
+            sess.view.reset_limits()
+            sess.message("autoscaled the whole spectrum")
+            return
+        sess.view.xlim = (float(lo), float(hi))
+        sess.view.rescale_y()
+        sess.message(f"expanded to {lo:.6g} - {hi:.6g}")
+
+    session.await_cursor(2, "mark two positions to expand between", done)
+
+
+@command("display.zero_base")
+def zero_base(session):
+    session.view.zero_base = not session.view.zero_base
+    session.view.rescale_y()
+    session.message(f"zero base {'on' if session.view.zero_base else 'off'}")
+
+
+@command("display.clear")
+def clear(session):
+    session.view.markers.clear()
+    session.view.fits.clear()
+    session.overlay_specs.clear()
+    session.view.reset_limits()
+    session.message("cleared windowing")
+
+
+@command("display.redraw")
+def redraw(session):
+    session.message("redrawn")
+
+
+@command("display.zoom")
+def zoom(session):
+    lo, hi = session.view.xlim
+    centre = session.view.cursor_x if session.view.cursor_x is not None \
+        else (lo + hi) / 2
+    half = (hi - lo) / (2 * ZOOM_FACTOR)
+    session.view.xlim = (float(centre - half), float(centre + half))
+    session.view.rescale_y()
+    session.message(f"zoomed to {session.view.xlim[0]:.6g} - "
+                    f"{session.view.xlim[1]:.6g}")
+
+
+def _shift(session, sign: float):
+    lo, hi = session.view.xlim
+    step = (hi - lo) * SHIFT_FRACTION * sign
+    session.view.xlim = (float(lo + step), float(hi + step))
+    session.view.rescale_y()
+
+
+@command("display.shift_left")
+def shift_left(session):
+    _shift(session, -1.0)
+    session.message("shifted left")
+
+
+@command("display.shift_right")
+def shift_right(session):
+    _shift(session, +1.0)
+    session.message("shifted right")
+
+
+def _goto(session, index: int):
+    session.view.index = index
+    session.view.variant = None
+    session.view.markers.clear()
+    session.view.fits.clear()
+    if session.view.window_reset:
+        session.view.reset_limits()
+        session.view.cursor_x = float(np.mean(session.view.xlim))
+        session.view.follow_flux()
+    session.message(f"{session.view.entry.label} "
+                    f"({index + 1}/{len(session.collection)})")
+
+
+@command("display.prev")
+def previous(session):
+    if session.view.index == 0:
+        session.message("already at the first spectrum")
+        return
+    _goto(session, session.view.index - 1)
+
+
+@command("display.next")
+def next_entry(session):
+    if session.view.index >= len(session.collection) - 1:
+        session.message("already at the last spectrum")
+        return
+    _goto(session, session.view.index + 1)
+
+
+@command("display.goto")
+def goto(session):
+    def done(sess, text):
+        if not text:
+            sess.message("cancelled")
+            return
+        key = int(text) - 1 if text.strip().lstrip("-").isdigit() else text.strip()
+        try:
+            sess_index = sess.collection.find(key)
+        except KeyError:
+            sess.message(f"no spectrum matching {text!r}")
+            return
+        _goto(sess, sess_index)
+
+    session.await_line(f"spectrum (1-{len(session.collection)} or name): ", done)
+
+
+@command("display.variant")
+def variant(session):
+    keys = session.view.entry.variant_keys()
+    if len(keys) < 2:
+        session.message(f"only one variant available: {keys[0]}")
+        return
+    current = session.view.variant or session.view.entry.default
+    nxt = keys[(keys.index(current) + 1) % len(keys)]
+    session.view.variant = nxt
+    if session.view.window_reset:
+        session.view.rescale_y()
+    session.message(f"variant {nxt}")
+
+
+@command("display.pixel_coords")
+def pixel_coords(session):
+    mode = "wave" if session.view.axis.mode == "pixel" else "pixel"
+    session.view.set_axis(mode=mode)
+    session.view.rescale_y()
+    session.message(f"{mode} coordinates")
+
+
+@command("display.velocity")
+def velocity(session):
+    if session.view.axis.mode == "velocity":
+        session.view.set_axis(mode="wave")
+        session.message("wavelength scale")
+        return
+    x = session.view.cursor_x
+    spec = session.view.current_spec()
+    origin = float(session.view.axis.to_wave(spec, np.array([x]))[0])
+    session.view.set_axis(mode="velocity", velocity_origin=origin)
+    session.message(f"velocity scale about {origin:.6g}")
+
+
+@command("display.overplot")
+def overplot(session):
+    session.view.overplot_next = True
+    session.message("the next spectrum will overplot")
+
+
+@command("display.get")
+def get_spectrum(session):
+    def done(sess, text):
+        if not text:
+            sess.message("cancelled")
+            return
+        sess.load_path(text.strip())
+
+    session.await_line("file: ", done)
+
+
+@command("display.quit")
+def quit_command(session):
+    if session.file_index + 1 < len(session.files):
+        session.file_index += 1
+        session.load_path(session.files[session.file_index])
+        return True
+    return False
+
+
+@command("display.interrupt")
+def interrupt(session):
+    return False
+
+
+@command("help.page")
+def help_page(session):
+    session.showing_help = not session.showing_help
+    session.page_index = 0
+    if not session.showing_help:
+        session._close_text_page()
+
+
+@command("help.cycle")
+def help_cycle(session):
+    session.hint_index = (session.hint_index + 1) % len(STATUS_HINTS)
+    session.message(STATUS_HINTS[session.hint_index])
+
+
+# ---- w: the gtools window submode -----------------------------------
+#
+# Transcribed from IRAF pkg/xtools/gtools/gtwindow.x and lib/scr/gtools.key,
+# so every key keeps the meaning a splot user already has in their fingers.
+# Shifts move 0.75 of the window, zooms are cursor +/- d/4 (a factor of two),
+# and 'p' pans to cursor +/- d, which doubles the window - all as gt_window1
+# does it. 'e' takes two cursors and, following gt_window2, applies each axis
+# only if the two marks differ by more than 0.001 of that axis's span.
+
+SHIFT_WINDOW = 0.75
+EXPAND_TOLERANCE = 0.001
+
+
+def _window_action(session, char):
+    view = session.view
+    x1, x2 = view.xlim
+    y1, y2 = view.ylim
+    dx, dy = x2 - x1, y2 - y1
+    cx = view.cursor_x if view.cursor_x is not None else (x1 + x2) / 2
+    cy = view.cursor_y if view.cursor_y is not None else (y1 + y2) / 2
+
+    if char == "?":
+        session.showing_help = True
+        session.message("window keys")
+    elif char == "a":
+        view.reset_limits()
+        session.message("autoscaled x and y")
+    elif char == "b":
+        view.ylim = (float(cy), float(y2))
+        session.message(f"bottom edge {cy:.6g}")
+    elif char == "c":
+        view.xlim = (float(cx - dx / 2), float(cx + dx / 2))
+        view.ylim = (float(cy - dy / 2), float(cy + dy / 2))
+        session.message("centred at cursor")
+    elif char == "d":
+        view.ylim = (float(y1 - SHIFT_WINDOW * dy), float(y2 - SHIFT_WINDOW * dy))
+        session.message("shifted down")
+    elif char == "f":
+        view.flip = not view.flip
+        session.message(f"x axis flip {'on' if view.flip else 'off'}")
+    elif char == "g":
+        view.flip_y = not view.flip_y
+        session.message(f"y axis flip {'on' if view.flip_y else 'off'}")
+    elif char == "j":
+        view.xlim = (float(cx), float(x2))
+        session.message(f"left edge {cx:.6g}")
+    elif char == "k":
+        view.xlim = (float(x1), float(cx))
+        session.message(f"right edge {cx:.6g}")
+    elif char == "l":
+        view.xlim = (float(x1 - SHIFT_WINDOW * dx), float(x2 - SHIFT_WINDOW * dx))
+        session.message("shifted left")
+    elif char == "m":
+        spec = view.display_spec()
+        good = spec.wave[spec.good]
+        if good.size:
+            view.xlim = (float(good.min()), float(good.max()))
+        session.message("autoscaled x")
+    elif char == "n":
+        view.rescale_y()
+        session.message("autoscaled y")
+    elif char == "p":
+        view.xlim = (float(cx - dx), float(cx + dx))
+        view.ylim = (float(cy - dy), float(cy + dy))
+        session.message("panned about cursor")
+    elif char == "r":
+        view.xlim = (float(x1 + SHIFT_WINDOW * dx), float(x2 + SHIFT_WINDOW * dx))
+        session.message("shifted right")
+    elif char == "t":
+        view.ylim = (float(y1), float(cy))
+        session.message(f"top edge {cy:.6g}")
+    elif char == "u":
+        view.ylim = (float(y1 + SHIFT_WINDOW * dy), float(y2 + SHIFT_WINDOW * dy))
+        session.message("shifted up")
+    elif char == "x":
+        view.xlim = (float(cx - dx / 4), float(cx + dx / 4))
+        session.message("zoomed x")
+    elif char == "y":
+        view.ylim = (float(cy - dy / 4), float(cy + dy / 4))
+        session.message("zoomed y")
+    elif char == "z":
+        view.xlim = (float(cx - dx / 4), float(cx + dx / 4))
+        view.ylim = (float(cy - dy / 4), float(cy + dy / 4))
+        session.message("zoomed x and y")
+    else:
+        session.message(f"window: {char!r} is not a window key")
+
+
+def _window_expand(session):
+    """gtools 'e': mark two corners; each axis moves only if the marks differ."""
+    x1, x2 = session.view.xlim
+    y1, y2 = session.view.ylim
+    dx, dy = x2 - x1, y2 - y1
+
+    def done(sess, positions):
+        (mx1, my1), (mx2, my2) = positions
+        moved = []
+        if abs(mx2 - mx1) > EXPAND_TOLERANCE * abs(dx):
+            sess.view.xlim = (float(min(mx1, mx2)), float(max(mx1, mx2)))
+            moved.append("x")
+        if abs(my2 - my1) > EXPAND_TOLERANCE * abs(dy):
+            sess.view.ylim = (float(min(my1, my2)), float(max(my1, my2)))
+            moved.append("y")
+        sess.message(f"expanded {' and '.join(moved)}" if moved
+                     else "marks too close; window unchanged")
+
+    session.await_cursor(2, "mark two corners of the new window", done)
+
+
+@command("display.window")
+def window(session):
+    def chosen(sess, char):
+        if char == "e":
+            _window_expand(sess)
+        elif char == "I":
+            sess.message("cancelled")
+        else:
+            _window_action(sess, char)
+
+    session.await_key(
+        "window: a b c d e f g j k l m n p r t u x y z, ? for help", chosen, {})