Opening your data#

pc.show takes your data in whatever form you have it: a file on the server, a file in an S3 bucket or on a web server, or an array or astropy object already in the kernel. This page goes through each, and says what is read when.

Files on the server#

Give pc.show a path. These formats open as images:

Format	Extensions	Notes
FITS	`.fits`, `.fit`, `.fts`, `.fits.gz`, `.fits.fz`	Every HDU, scaled and blank values, cubes, WCS including SIP. Tile-compressed images are decompressed as they are read.
ASDF	`.asdf`	Every array in the tree, listed by path. Uncompressed and lz4 blocks stream from disk; world coordinates come from the file’s gwcs.
HDF5	`.h5`, `.hdf5`, `.he5`	Every dataset, with its attributes.
NetCDF-4	`.nc`, `.nc4`	Every variable, groups included, listed with its dimensions; a variable over time is a cube. Packed values are shown as physical values, fill values are blank, and `units` follow the value in the readout.
MATLAB v7.3	`.mat`	Numeric and logical variables and struct fields, as MATLAB shows them (an m×n matrix is m rows by n columns). Files saved without `-v7.3` get a message saying so.
NumPy	`.npy`, `.npz`	Integer, float and bool arrays.
TIFF, PNG	`.tif`, `.tiff`, `.png`	8 and 16 bit and float, multi-page, color.
JPEG	`.jpg`, `.jpeg`	Color as red, green and blue channels, the right way up for phone and camera pictures.

import pixel_clarity as pc

pc.show("data/image.fits")
pc.show("~/reduced/stack.asdf")

A file opens at its first image. If it holds more (extensions, arrays in an ASDF tree, HDF5 datasets), the array picker in the toolbar lists them all, and the Info panel shows the header or metadata, searchable.

Large files aren’t loaded whole: the viewer reads what it needs to show, and an overview and statistics the first time. That first read is kept in a cache for as long as the kernel runs, so opening the same file again is immediate.

Several files at once#

A folder or a glob pattern shows its image files together, as a mosaic placed on the sky (see Mosaics); .mat files, which are often not images, only when you name them. So does a list:

pc.show("exposure/")                       # every image file in the folder
pc.show("frames/*.fits", kind="stack")     # one at a time, with a slider
pc.show(["a.fits", "b.fits", "c.fits"])    # a list: a mosaic, unless kind says otherwise

kind picks how several images are shown: "mosaic" (the default for several), "stack", or "rgb" for three. Frames, cubes and blinking and Color images cover the others.

Files in the cloud#

An s3:// URI or an https:// URL is read where it is, by range requests: only the parts of the file the viewer needs are fetched, so a large file shows its first view in seconds, without downloading it first.

pc.show("s3://bucket/path/image.asdf")                        # a public bucket, anonymously
pc.show("s3://my-bucket/private/image.fits", anon=False)      # signed with the kernel's AWS credentials
pc.show("https://example.org/data/image.fits")

Private buckets need boto3 (pip install 'pixel-clarity[s3]') and use the same credentials as the rest of your code. A server must answer range requests, as S3 and most file servers do; a signed URL works too.

Each image read from a URL is downloaded once. The viewer keeps a summary of it (a reduced copy and its statistics) with the kernel’s own viewer process, so showing it again, in another viewer or a mosaic, reads only the parts under the view at full resolution. The summary is used only after the URL has been read again successfully, so nothing is shown from a file you can no longer read, and it goes when the kernel stops.

Data in the kernel#

Arrays and astropy objects can be shown directly. They are written once to a temporary file on the server’s local disk (an unchanged array only once, however often you show it), and removed when the kernel stops.

A NumPy array:

pc.show(array, title="green band, from memory", height=450)

Masked arrays show their masked values as blank (NaN). A 3-dimensional array is a cube: the viewer shows it plane by plane, with a slider for the first axis.

import numpy as np
from astropy.io import fits

cube = np.stack([fits.getdata(f) for f in frames])     # 8 frames of 400 × 700
pc.show(cube, title="frames as a cube", scale="asinh", limits="99.5", height=400)

An astropy HDU, HDU list, NDData or CCDData brings its WCS with it, so sky coordinates work as they do for the file:

hdu = fits.open(red)[0]
pc.show(hdu, cmap="viridis", height=450)

ASDF files opened with asdf.open and data models work the same way.

Read in place#

Data that is already a file’s is read from that file rather than written again. That covers an array memory-mapped from a .npy file, and an HDU of a FITS file opened with fits.open, as long as you haven’t touched its data or header. This is also the way to start on a particular extension of a file:

array = np.load("big.npy", mmap_mode="r")     # read from big.npy, nothing copied
pc.show(array)

hdul = fits.open("exposure.fits")
pc.show(hdul["SCI"])                          # starts on the SCI extension, read from the file

HiPS#

A HiPS (a Hierarchical Progressive Survey: a sky image cut into a pyramid of tiles) opens however large it is, since only the tiles in view are read. Give its folder (the one holding properties) or its URL, one whose last part has no file extension:

pc.show("surveys/my_hips/")

pc.show("https://alasky.cds.unistra.fr/DSS/DSSColor")

FITS tiles are values (stretch, regions and statistics work as for any image); PNG and JPEG tiles open in color.

Tables#

Table files (.csv, .tsv, .ecsv, .parquet, VOTables, Arrow/Feather, and FITS files that hold tables and no image) and astropy, pandas or polars tables open in the table viewer instead. See Tables and catalogs.