Browser tabs from any program#

You don’t need a notebook to use Pixel Clarity. pc.popup shows the same viewer in a browser tab of its own from any Python program: a script, an IPython session, a pipeline you are debugging. Called again, it updates the same tab, so a loop can watch an image change.

A first tab#

import pixel_clarity as pc

pc.popup("image.fits")

The tab opens in your browser and shows the image, with every tool the notebook viewer has. pc.popup takes the same data and keywords as pc.show: files, URLs, arrays, astropy objects, tables, and lists of them with kind= for mosaics, stacks and RGB.

In a notebook, pc.popup gives a link to the tab instead of opening it: handy when you want a viewer full screen beside the notebook, or one that a loop in the notebook keeps updating.

Updating a tab#

Each tab is a window, named by window ("main" by default). Calling pc.popup again with the same window shows the new data in the same tab:

  • An array of the same shape and type is read again in place, and the tab keeps its zoom, pan and colors. That’s what you want in a loop.

  • Anything else (another file, another kind of view) starts the tab afresh, with its new title.

import numpy as np
import pixel_clarity as pc

for step in range(200):
    image = simulate(step)                     # your code
    pc.popup(image, title="simulation")        # the same tab, updated in place

Different windows are different tabs:

pc.popup(residuals, window="residuals", cmap="coolwarm")
pc.popup(catalog, window="stars")

pc.popup returns the window, which has state, regions and add_regions() as a notebook viewer does, so a script can draw on it and read back what you drew:

win = pc.popup("image.fits")
win.add_regions("detections.reg")
input("Mark anything odd, then press Enter... ")
print(win.regions_ds9)

When the script ends#

Everything stays with the program: its viewer process and temporary files go when it ends. So that you can still look at the tabs, a script waits at its end until they are closed (or you press Ctrl-C). If no tab ever connected, it waits a minute at most.

  • pc.wait() waits sooner, at a point of your choosing.

  • PIXEL_CLARITY_POPUP_WAIT=0 doesn’t wait at all.

Interactive sessions (IPython, a notebook) don’t wait: the tabs stay up while the session does.

On a remote machine#

The tab’s page is served on the machine running the program, on 127.0.0.1 only. When that machine is reached over SSH, the program prints the address and the port to forward:

Pixel Clarity: open http://127.0.0.1:53211/view/…?token=… in a browser
  From your computer: ssh -L 53211:127.0.0.1:53211 <this machine>, then open it there (PIXEL_CLARITY_PORT keeps the port the same each run).

PIXEL_CLARITY_PORT keeps the port the same from run to run, so one SSH forward serves every run. Where there is a desktop (macOS, Windows, or Linux with a display), the tab opens by itself.