Getting started#

This page installs Pixel Clarity, opens a first image in a notebook, and explains the few things worth knowing before you go further: what the dot under the viewer means, where your data is read, and how to get around the viewer.

Install#

Pixel Clarity is on PyPI. In a notebook:

%pip install pixel-clarity

Then restart the kernel (or start a new one) so it picks up the package. It needs JupyterLab 4 or Notebook 7 with ipywidgets 8, which most JupyterHubs already have. It also works in VS Code’s notebooks.

On a hub where packages installed into the kernel’s environment disappear when your server restarts, install into your home directory instead:

%pip install --user pixel-clarity

Pixel Clarity brings its own copy of Node.js (through the nodejs-wheel-binaries package), which runs the small process that reads your data. You don’t need to install anything else.

A first image#

Give pc.show a file. Here it is a FITS file of a star field with a galaxy (the sample image these docs use throughout):

import pixel_clarity as pc

pc.show(image)

That’s all it takes. The viewer opens at the size of the cell and fits the whole image in view. Try it on the live viewer above (click it first):

  • Drag to pan, scroll to zoom about the pointer, or use 1, 2, 4 and f (fit).

  • Hover for the pixel’s value and its RA and Dec, in the readout and the pixel table.

  • Right-drag to change the contrast and brightness; r resets them.

  • Click a scale (lin, log, asinh, …) or the limits menu (zscale, 99.5%, …) to restretch.

  • ? lists every key.

The viewer goes through the toolbar and panels in more detail.

Where the data is read#

When you call pc.show, the data isn’t sent to your browser. A process started next to the kernel reads it there and sends the browser only the tiles you are looking at, coarse ones first, then full resolution. Statistics, histograms and region measurements are worked out next to the data too.

So the size of the file hardly matters: a 4k × 4k detector, a mosaic of a dozen of them, or a cube of hundreds of planes opens as quickly as this small image, even when the server is far away. Files on S3 or a web server are read where they are, by range requests, without downloading them first. Opening your data lists everything it reads.

The dot under the viewer#

Under each viewer is a status line with a small dot. It tells you how your browser reaches the viewer’s process:

  • Green, direct. The page talks to the process through jupyter-server-proxy (installed on most hubs), or straight to it when your browser runs on the same machine. Tiles never wait for the kernel, so the viewer keeps working while a long cell runs. Open in a new tab shows the same view in a browser tab of its own.

  • Amber, through the kernel. Messages travel through the notebook’s widget channel. This works anywhere widgets do, but the viewer pauses while a cell is running.

Either way, nothing changes in how you use it. Running on a server has more on hubs and remote machines.

A few options#

Every keyword of pc.show sets how a view starts; the toolbar changes everything afterwards. The ones you’ll reach for most often are the stretch and the colormap, and the viewer’s height:

pc.show(image, scale="asinh", limits="99.5", cmap="magma", height=450)

Color and stretch covers these in detail, and Settings and defaults shows how to make your favorites the default for every new viewer.

Outside a notebook#

You don’t need a notebook at all. From a script or an IPython session, pc.popup shows the same viewer in a browser tab of its own:

import pixel_clarity as pc

pc.popup("image.fits")

See Browser tabs from any program.