Skip to content

Command Line & Live Directory Polling Guide

QuickLook 3 can be launched directly from the terminal or integrated into automated observing scripts with flexible command-line flags.

🚀 Command Line Flags

Launch PyQL3 with command-line arguments to automatically open specific FITS files, set display scaling, apply colormaps, or start directory polling:

uv run python main.py [OPTIONS] [FILEPATH ...]

Options Reference

Flag Description Default Example
filepath ... One or more 2D or 3D FITS files to load immediately upon launch. Each opens in its own window None uv run python main.py data.fits
--collapsed Start with the collapsed (slab) view active instead of a single channel False --collapsed
--collapse-range Start collapsed over ZMIN ZMAX channels (implies --collapsed) None --collapse-range 100 200
--poll-dir Path to directory to automatically monitor for new FITS files None --poll-dir ~/data/observing_run
--catalog Catalog to load into the Plot Catalog tool (text table or FITS table) None --catalog sources.fits
--catalog-hdu Table extension of a FITS catalog, by index or EXTNAME first table --catalog-hdu SOURCES
--regions Region file to draw on startup — QuickLook 3 YAML or a ds9 .reg, detected from the contents None --regions targets.reg
--install-cli Install the quicklook3 shell launcher (see below) and exit False --install-cli

Scaling, colormap, rotation and extension are set from the Display menu and the controls under the image rather than from flags.

--catalog and --regions load into the first window; anything that cannot be read is reported on stderr rather than in a dialog, so an automated launch is never left waiting on a modal window.

Comparing several cubes

Naming more than one file opens one window per file, cascaded, with any display flags applied to all of them:

uv run python main.py s150531_a025002_Kn5_035.fits s150531_a026002_Kn5_035.fits --collapse-range 100 200

Each window is independent: its own scaling, colormap, collapse range and its own Depth Plot, Statistics and other tool windows. More windows can be opened at any time with File ➔ New Window (⌘N / Ctrl+N) or File ➔ Open in New Window..., and File ➔ Close Window (⌘W / Ctrl+W) closes one without quitting the application. The Window menu lists every open window with its tool windows grouped underneath, and Bring All to Front raises the whole set.

Opening a file from Finder, or running quicklook3 cube.fits while the application is already open, loads it into the window you used most recently — so it replaces the view you were last looking at, rather than one hidden behind it. Use Open in New Window... to keep both.

🖥️ Launching Like ds9: the quicklook3 Command

QuickLook 3 can be given a short name on your PATH, so a FITS file opens with one word from any directory:

quicklook3 s150531_a025002_Kn5_035.fits
quicklook3 cube.fits --collapse-range 100 200 --catalog sources.fits

Installing the launcher

Either way works, on macOS and on Linux:

  • From the running application — Help ➔ Install 'quicklook3' Command Line Tool.... This is the easiest route if you installed a released binary, because the app already knows where it lives. It shows you exactly what it proposes to do and writes nothing until you click Install:
Install the 'quicklook3' command line tool?

Create:      /Users/you/.local/bin/quicklook3
Which runs:  /Applications/QuickLook3.app/Contents/MacOS/QuickLook3

To run it:   quicklook3 yourfile.fits
To undo it:  rm /Users/you/.local/bin/quicklook3
  • From a terminal — run the application with --install-cli. Passing the flag is the confirmation, so this one installs directly, then prints the same summary:
# from a source checkout
uv run python main.py --install-cli

# from an installed macOS bundle
/Applications/QuickLook3.app/Contents/MacOS/QuickLook3 --install-cli

# from an unpacked Linux build
/opt/QuickLook3/QuickLook3 --install-cli

The launcher goes into /usr/local/bin when that is writable, otherwise ~/.local/bin (created if needed). Both routes name the exact file, and give you the export PATH=... line to add to your shell profile when that directory is not already on your PATH.

Uninstalling

Delete the file — nothing else is installed, and no settings are written:

rm ~/.local/bin/quicklook3      # or /usr/local/bin/quicklook3

The exact path is shown both before the install (in the dialog) and after it, so you never have to guess which of the two it went to.

What gets written is a two-line sh script that runs the application with "$@", so it forwards every flag above and resolves relative paths against your current directory. It is a script rather than a symlink or a copy because a copied PyInstaller binary cannot find its own _internal directory. A file already at that name is never overwritten unless it was generated by QuickLook 3.

macOS: open the app once before using quicklook3

A bundle downloaded through a browser carries the com.apple.quarantine attribute, and macOS kills a quarantined program launched from a shell with no error message at all — quicklook3 cube.fits simply does nothing. Clear it by opening QuickLook3.app once from Finder (right-click ➔ Open) or with xattr -cr /Applications/QuickLook3.app. The generated launcher checks for this and prints the fix instead of failing silently.

This applies again after every new download, until the app is signed and notarized.

Installing from the .dmg

Drag QuickLook3.app to /Applications (or your home folder) before installing the launcher. Installing while the app is still running from the mounted disk image is refused, because that path disappears when the image is ejected.

📂 Opening FITS Files from the Desktop

The macOS bundle registers itself as a viewer for .fits, .fit, .fts and .fz files, so QuickLook 3 appears in Finder's Open With menu, and a FITS file can be dropped onto the app or Dock icon. To make it the default for FITS, use Finder's Get Info ➔ Open with ➔ Change All...; QuickLook 3 registers as an alternate handler and will not displace another viewer on its own.

Two details worth knowing:

  • Finder does not pass a double-clicked file as a command-line argument — it sends the application an open-document event. This is handled while the app is running too, so opening a second file from Finder loads it into the existing window.
  • .fits.gz cannot be registered: macOS matches only the final extension, and claiming .gz would offer QuickLook 3 for every gzip file on the system. Open compressed cubes through File ➔ Open... or quicklook3 cube.fits.gz, both of which handle them.

On Linux, desktop integration is per-environment; the quicklook3 launcher above is the supported route.

📡 Live Directory Polling Workflow

During observing runs at the telescope, raw data cubes or reduced frames are written continuously to disk. QuickLook 3 features a background directory polling service built on watchdog.

The directory is scanned on an interval rather than watched for filesystem notifications. Kernel notification APIs (FSEvents, inotify) only report changes made on the local machine, so a DRP writing from another host onto an NFS share would go completely unnoticed. Scanning costs more but is the only approach that sees remote writes.

Three consequences worth knowing:

  • A new file is displayed a few seconds after it lands, not instantly. The poller waits for the file's size to stop changing, so a cube that is still being written is never loaded half-complete.
  • When many files arrive at once — dragging in a night's frames, or a DRP flushing a backlog — only the newest is displayed, instead of flashing each one on screen in turn. A status bar message reports how many were skipped.
  • Scan cost grows with the number of files in the directory, and is markedly higher over NFS. Raise the scan interval for a directory holding a whole run, and prefer watching a per-night directory over an accumulating archive.

The interval defaults to 2 seconds and is configurable in File ➔ Polling....

Enabling Directory Polling

Option A: Via Command Line

Start monitoring a folder immediately when launching PyQL3:

uv run python main.py --poll-dir /path/to/raw_data

Option B: Via GUI Menu

  1. Open QuickLook 3.
  2. Select File ➔ Polling... from the top menu bar.
  3. Click Browse... to pick the watch directory.
  4. Click Start Polling.

Behavior

  • When a new file ending in .fits or .fit is created or moved into the watched directory, QuickLook 3 automatically loads the new dataset in real-time.
  • Active analytical tools (Depth Plot, Profile Cuts, Statistics) automatically refresh to reflect the newly detected file.
  • New frames load into the window that started the watch, and only that window. Opening another window to look at something else will not divert the incoming frames to it.
  • A directory is watched by one window at a time. Pointing a second window at a directory another window is already watching asks first, and then moves the watch — new frames start appearing in the second window instead of the first. Two simultaneous watches would scan the directory twice and load every frame twice, which matters on a busy NFS share.