QuickLook 3

QuickLook 3 is a modern, high-performance Python/Qt-based application designed for viewing integral field spectroscopy data. It provides a comprehensive graphical interface to interactively visualize both 2D images and 3D data cubes. This tool is a replacement for the legacy IDL qlook2 GUI for viewing and analyzing FITS data originally built for the OSIRIS instrument at the Keck Observatory. While QuickLook 3 is optimized for OSIRIS data, it should work for most IFU instruments including JWST NIRSpec IFU and Gemini NIFS.

Features

• Rendering: Built on PySide6 and pyqtgraph. The image display is software-rendered through Qt's raster engine, which imposes no GPU requirement; OpenGL is used only by the 3D Surface and Peak Fit views, which degrade to a message when no GL context is available.
• IFU Data Cube Visualization: Interactively view FITS cubes across spatial and spectral dimensions. Extract 1D depth spectra from specific spatial pixels or regions.
• Z-Axis Collapsing: Collapse 3D spectral ranges into 2D display slices using Median, Mean, or Sum algorithms on the fly.
• Advanced Scaling & Displays: Includes interactive Linear, Logarithmic, Square Root, AsinH, and Histogram Equalization scaling. Supports instant color map inversion and position angle compass overlays.
• Astronomical Coordinates & WCS: Integrates WCS pixel-to-world (RA/Dec) coordinate translations dynamically at your mouse pointer.
• Interactive Catalog Overlay: Overlay astronomical catalogs (CSV, TXT, DAT, or FITS binary tables) using Display Pixels, FITS Pixels, or WCS RA/Dec coordinates. Features viewport label culling for fast performance, custom marker styling, search filtering, and row selection highlighting.
• ds9-Style Regions: Draw circles, boxes, arrows and text over the image from a Region menu, an optional toolbar, or a right-click. Edit colour, line width, angle, label and a per-region channel range; save and load as readable YAML or exchange with ds9 as .reg. Catalogue-sized sets are drawn as a single overlay so tens of thousands load in seconds.
• Analysis Tools: Built-in 1D profile cuts (horizontal, vertical, arbitrary lines), SNR estimates, Encircled Energy plots, 2D Peak Fitting, and 3D OpenGL Surface Rendering.
• FITS Datacube Arithmetic: Execute image and cube math (addition, subtraction, division, scalar scaling) between open datasets.
• Multiple Cubes at Once: Each window is an independent view — its own file, display settings, tool dialogs and directory watch — so two dithers, or a frame and its sky, can be compared side by side rather than reloaded in turn.
• Directory Polling: Watch a directory and load new FITS files as they are written, including files written from another host onto an NFS share. A frame is announced only after its size and modification time are unchanged across consecutive scans, and a burst of arrivals displays only the most recent frame.
• Header Editor: View and modify FITS header cards directly in the UI.

Download

Binaries of the applications are available for Linux, MacOS, and Windows. Download the latest release at https://github.com/astrodatalab/pyql3/releases/latest

Verifying your download

The bundles are not code-signed or notarized, so your operating system cannot vouch for them and you will have to bypass Gatekeeper or SmartScreen to run them. Every release therefore publishes a SHA256SUMS.txt generated during the build. Download it alongside the binary and check that the hash matches:

# macOS
shasum -a 256 -c SHA256SUMS.txt --ignore-missing

# Linux
sha256sum -c SHA256SUMS.txt --ignore-missing

# Windows PowerShell — compare against the matching line in SHA256SUMS.txt
Get-FileHash .\QuickLook3-*-Windows.zip -Algorithm SHA256

A mismatch means the file was corrupted in transit or tampered with; do not run it.

Installation

PyQL3 manages its dependencies seamlessly using uv, an extremely fast Python package and project manager. uv will automatically download the correct Python version and all required libraries (PySide6, pyqtgraph, astropy, scipy, etc.) so you don't have to worry about complex virtual environments.

1. Install uv

For macOS and Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

For Windows: Open PowerShell and run:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

2. Launch PyQL3

Clone or navigate to the pyql3 repository in your terminal/command prompt:

cd pyql3

Run the application through uv. It will automatically fetch dependencies and launch the GUI:

uv run python main.py

3. Optional: a quicklook3 command, like ds9

To open FITS files from any directory with one word, install a launcher on your PATH — from the menu bar (Help ➔ Install 'quicklook3' Command Line Tool...) or from a terminal:

uv run python main.py --install-cli     # source checkout
/Applications/QuickLook3.app/Contents/MacOS/QuickLook3 --install-cli   # installed macOS bundle
/opt/QuickLook3/QuickLook3 --install-cli                              # unpacked Linux build

quicklook3 cube.fits --collapse-range 100 200

The menu action shows exactly which file it will create, what that file will run, how to run the command afterwards, and how to remove it — and installs nothing until you click Install. The --install-cli flag treats itself as the confirmation and prints the same summary after installing.

It installs into /usr/local/bin when writable, otherwise ~/.local/bin, and gives you the export PATH=... line if that directory is not already on your PATH. To uninstall, delete the file (rm ~/.local/bin/quicklook3); nothing else is written. macOS and Linux only.

On macOS, open a freshly downloaded QuickLook3.app from Finder once (or run xattr -cr /Applications/QuickLook3.app) before using quicklook3: macOS kills a quarantined app started from a shell without printing anything. The installed launcher detects this and tells you the fix. The macOS bundle also registers as a viewer for .fits, .fit, .fts and .fz, so it appears in Finder's Open With menu and accepts files dropped on its icon.

Usage

Building a Standalone Application

macOS

You can compile PyQL3 into a standalone application that does not require users to install Python or any dependencies:

./build_app.sh

This will create QuickLook3.app in the dist/ directory, along with a .dmg package containing the executable for your architecture (Intel or Apple Silicon).

Windows

You can compile PyQL3 into a standalone .exe application bundle on Windows:

build_app.bat

This will create a QuickLook3 folder inside the dist\ directory containing the main executable.

Launching the Application

You can launch QuickLook 3 directly from the terminal with flexible command-line options:

# Basic launch
uv run python main.py

# Open a FITS image or 3D cube directly
uv run python main.py /path/to/data.fits

# Several files, each in its own window, for side-by-side comparison
uv run python main.py /path/to/dither1.fits /path/to/dither2.fits

# Open image and automatically load a target source catalog
uv run python main.py /path/to/data.fits --catalog /path/to/catalog.csv

# ... or a FITS table, optionally naming the extension to read
uv run python main.py /path/to/data.fits --catalog /path/to/catalog.fits --catalog-hdu SOURCES

# Draw a region file over it (QuickLook 3 YAML or a ds9 .reg)
uv run python main.py /path/to/data.fits --regions /path/to/targets.reg

# Auto-poll a directory for new incoming FITS files
uv run python main.py --poll-dir /path/to/raw_data/

# Start with a collapsed spectral slice range
uv run python main.py datacube.fits --collapse-range 100 200

Basic Navigation

• Open File: File -> Open...
• Header: File -> Edit FITS Header to inspect or modify header keywords, on any extension.
• Window Menu: lists every open window and groups each window's tool dialogs beneath it, so a Depth Plot can be told from the identically-titled Depth Plot belonging to another cube. Bring All to Front raises the set.

Working with Several Cubes

A window is a self-contained view of one dataset: it owns its FitsReader, its display settings (scaling, colormap, rotation, axis mapping), its tool dialogs and its directory watch. Changing the scaling in one window does not affect another, and closing a window releases its cube.

• File -> New Window opens an empty window; File -> Open in New Window... opens a file into one; File -> Close Window closes the current window without exiting the application.
• Several filenames on the command line open one window each.
• A file arriving with no window attached — a Finder double-click, or quicklook3 cube.fits while the application is already running — loads into the most recently used window, or opens a new one if all have been closed.

Directory Polling

File -> Polling... watches a directory and loads new FITS files as they appear. The behaviour is stated here because it determines what the tool will and will not detect:

• Scanning, not filesystem events. Kernel notification backends (FSEvents, inotify) report only changes made through the local kernel, so a file written by the OSIRIS DRP from another host onto an NFS share generates no event on the viewing machine. QuickLook 3 diffs directory snapshots instead, at a configurable interval (2 s by default), which sees remote writes.
• A file is announced only once it has stopped changing — its size and modification time must be unchanged across two consecutive scans. This avoids loading a FITS file that is still being written. On NFS this is necessary but not sufficient, because clients cache file attributes for seconds at a time, so a failed read is retried rather than reported as a corrupt file.
• A burst of arrivals displays only the newest frame, with the number skipped reported, rather than flashing each file in turn as a bulk copy completes.
• One window watches a given directory at a time. Auto-loaded frames go to the window that owns the watch, not to whichever window was last used, so a watch following a reduction cannot take over a window opened for comparison. Moving a watch to another window asks first.

Visual Controls

• Slices & Slabs: The bottom control panel allows you to switch between viewing a single Z-slice or a collapsed Z-range of a 3D datacube. Use the slider to navigate through cube depth.
• Scaling: Adjust scaling limits dynamically using the intensity histogram gradient on the right side of the image, or select scaling algorithms (Linear, Logarithmic, Square Root, AsinH, Negative, Histogram Equalization) via the Display -> Scaling menu or bottom left dropdown.
• Rotation & Flips: Display -> Rotate Image... lets you orient the image properly while preserving spatial coordinate accuracy.
• Data Units: Toggle between native As DN/s and Total DN (As Total DN) through the Display menu.
• Position Angle (PA): Enable Display -> Position Angle to display dynamic North/East compass rose vectors.

Analysis & Catalog Tools

Found under the Plot and Analysis menu bars:

• Catalog Plot Tool (Plot -> Plot Catalog...): Load astronomical catalog files (.csv, .txt, .dat) or FITS tables (.fits, .fit, .fts, gzipped) and overlay sources onto the FITS display.
  • Coordinates: Supports Display Pixels, FITS Pixels, or WCS RA/Dec (HMS/DMS or decimal degrees).
  • FITS Tables: Reads binary and ASCII table extensions; you are asked which extension to use when a file holds more than one. Common photutils / SExtractor column names (xcentroid, X_IMAGE, ALPHA_J2000, ...) are auto-detected, masked and undefined coordinates are skipped rather than plotted at the origin, and per-row vector columns (e.g. spectra) are omitted from the table.
  • Large Catalogs: Labels are culled to the visible area and hidden while the view is being panned, so redraw cost stays bounded by what is on screen rather than by catalog size.
  • Interactivity: Filter table rows in real time with the built-in search bar, click rows to center sources on the image with a red highlight, or right-click rows to copy coordinates.
  • CLI Auto-Load: Pass --catalog <file> on launch to auto-open the tool and load the catalog, with --catalog-hdu <index|EXTNAME> to pick a FITS table extension.
• Regions (Region menu): Draw circles, boxes, arrows and text over the image — drag them out, or right-click the image for New Region to place a default-sized one where you clicked. An optional vertical toolbar (Region -> Region Toolbar) holds the same tools.
  • Editing: Double-click a region for a properties dialog — position, size, angle, label, colour, line width, dashing, text size, tag, visibility, and a channel range that shows the region only over part of a cube. Region -> Region List... gives the same in a table.
  • File Formats: Save as readable YAML (pyql3-regions/1) or export ds9 .reg; loading detects the format from the file's contents, not its name, and reports anything a conversion could not carry. Geometry is stored in pixels with the sky position alongside, so regions survive flips, rotations and a move to another frame of the same field.
  • Large Sets: Above 500 regions the set is drawn as one overlay — 20,000 load in about two seconds — with labels culled to the view, hidden while panning, and switchable off. Region -> Send Regions to Plot Catalog... hands a large set to the catalog tool for its table and search.
  • CLI Auto-Load: Pass --regions <file> on launch, in either format.
• 1D Profile Cuts: Plot -> Horizontal Cut / Vertical Cut / Diagonal Cut to generate 1D profile cuts with adjustable boxcar averaging.
• Depth Plot: Click anywhere on a 3D dataset to extract and display 1D spectra along the Z-axis. Extraction defaults to a circular aperture with an explicit radius, totalled per channel. Background subtraction defaults to a sky annulus concentric with that aperture — inner and outer radii are set directly, and the annulus follows the aperture rather than being placed separately — which makes each channel an aperture-photometry measurement. An independently placed background region remains available for a background that must be measured somewhere specific.
• Peak Fit / Encircle / SNR: Draw a rectangular ROI over a source to calculate 2D Gaussian statistics, Encircled Energy radial profiles, or Signal-to-Noise.
• Surface Plot: Plot -> Surface renders a 3D OpenGL surface mesh of the displayed image. Requires a working OpenGL context; without one the dialog reports that rather than failing.
• FITS Arithmetic: File -> Arithmetic... performs addition, subtraction, division, and scalar scaling between open FITS datasets. The result opens in its own window.

License

QuickLook 3 is licensed under the BSD 3-Clause License. You are free to use, modify, and redistribute this software, provided that the original copyright notice and license text are retained.

Authors

Tuan Do (UCLA)

Based on QuickLook 2 (ql2) for IDL from the OSIRIS Data Reduction Pipeline. See the contributors of the OSIRIS DRP here: https://github.com/Keck-DataReductionPipelines/OsirisDRP#alphabetical-list-of-contributors