The viewer#

A tour of the viewer itself: how to get around an image, what the toolbar and the side panel hold, and the keywords that set how a view opens. Everything here works the same in a notebook, in a browser tab, and in the live examples on these pages.

Getting around#

The viewer draws the image on your own computer’s graphics card from tiles the server sends, so panning, zooming and restretching never wait on the network once a tile has arrived.

To

Do

Pan

Drag (in the pan tool; Esc returns to it)

Zoom

Scroll (about the pointer), 1, 2, 4 for 1:1, 2:1, 4:1, f to fit

Change contrast and brightness

Right-drag; r resets

Read values

Hover; c pins a crosshair, which the arrow keys move a pixel at a time

Go to a position

j, then type RA and Dec, in degrees or h:m:s ±d:m:s

Undo, redo

Ctrl+Z (⌘Z on a Mac), Ctrl+Shift+Z or Ctrl+Y: regions, stretch, colors, crop, turn, contours, smoothing, grid

Measure a star

Shift+R over it: its FWHM, shape, peak, sky and flux, with its radial profile

Hide the tools

h, for a clean look or a screenshot (h or Esc brings them back)

See every key

?

The toolbar#

From left to right, the top rows hold:

  • Scale: lin, log, pow, sqrt, sq, asinh, sinh, eq (histogram equalization) and mid (a midtone stretch), then the limits menu (zscale, min/max, percentiles) with the low and high values, which you can type, and a lock that keeps them as you change slices.

  • Auto: Auto enhance, a one-click stretch for a picture: a dark sky, faint structure lifted, bright parts kept. Its menu sets the sky brightness and, for color images, the color balance.

  • Colormap, with invert beside it.

  • Zoom, fit and 1:1, then flip, turn and crop. n turns the view north up, east left; , and . turn it a quarter turn; x frames a crop for a poster or slide, in any shape.

  • Region tools: box, circle, line, point, text and arrow (see Coordinates and regions).

  • Contours of the image, or of another file lined up with it through the sky (see Comparing and linking viewers below); smoothing, a Gaussian blur of the picture that brings out faint extended light (the values you read stay the pixels’ own); a coordinate grid and scale bar.

  • Catalogs: Gaia DR3, 2MASS, SIMBAD or any VizieR table over what the view shows (see Tables and catalogs).

  • Link, to make viewers follow one another.

  • Export (a figure for a paper or a talk, or a full-resolution PNG rendered next to the data; pc.save_png writes the PNG from code), Share as a web page, the Aladin Lite sky panel (a sky survey around the view, following it), and the panels’ toggle.

The side panel#

The panel on the right stacks several sections, each of which folds away:

  • Navigator: the whole image with the view outlined; drag the outline to move.

  • Magnifier: the pixels under the pointer, enlarged.

  • Pixel table: the values around the pointer (3×3 up to 9×9).

  • Histogram, with draggable limits and the stretch curve over it.

  • Header (or the file’s metadata), searchable, and Info: the image’s size, type, units, plate scale and rotation.

  • Regions, and for a mosaic Detectors, for an image with a data-quality array Mask (tick bits to color them over the image).

How a view opens#

These keywords set the starting point; everything can be changed in the viewer afterwards.

Keyword

Values

zoom

"fit" (default: the whole image) or 1 (one data pixel per screen pixel, centered)

sidebar

the side panel: True (default) or False

cuts

the row and column cut plots beside the image (default False in a notebook)

smooth_pixels

zoomed in past 1:1, blend between pixel centers instead of square pixels (v in the viewer); values stay the original pixels

height

the viewer’s height in pixels (default 600); the grip under it changes it too

title, names

the view’s title; a name for each image in place of its file name

Pixels at full size, without the side panel, in a shorter viewer:

import pixel_clarity as pc

pc.show(image, zoom=1, sidebar=False, height=420, scale="asinh", limits="99.5")

With the cut plots, which follow the crosshair or the pointer:

pc.show(image, cuts=True, height=650, title="with the cut plots")

Several viewers at once#

Each call gives a viewer of its own, and you can have many open. They share one viewer process per kernel. A viewer nobody has used for five minutes (ten with a direct connection) frees the memory its data took, and reads it again when you come back to it, so a long notebook with dozens of viewers stays light.

The function returns the viewer, which you can keep for later:

v = pc.show("image.fits")
v.state         # the view as you left it (stretch, colors, regions, pan, zoom)
v.regions       # what is drawn on it, as regions objects
v.close()       # free it now

Comparing and linking viewers#

Link in the toolbar ties viewers together: every viewer with Link on follows the others’ pan, zoom, turn, crosshair and plane, matched on the sky through each image’s WCS (the same patch of sky, the same way up, at the same angular scale, whatever the pixel sizes) or pixel for pixel. Its menu chooses which, and whether the stretch goes too. Viewers in the notebook and in tabs of their own link alike, as long as they belong to the same kernel. Open beside, linked… in the same menu picks images on the server and opens them in new tabs, already linked.

The contour popover’s Of → Other file… draws the contours of a second image over this one, lined up through both files’ sky coordinates (radio contours over an optical image, say), or pixel for pixel when neither has any. A file with several images or planes lets you choose.

Both ask for files with a picker that lists the folders and images on the server, starting next to the image. Double-click a file to open it, or type a path (or an https:// URL) and press Enter.

Opening a tab needs the direct connection (the green dot). Through the kernel the viewer says how to show the same thing from Python instead.