API reference#

Showing data#

pixel_clarity.show(data, *, kind=None, title=None, names=None, height=600, connection='auto', state=None, anon=True, out_dir=None, layout=None, active=None, color=False, blink=False, groups=None, levels=None, plot=False, table=None, subtract=None, divide=False, **settings)#

Show images or a table in the notebook, with the Pixel Clarity viewer.

The data stays on the server: files and URLs are read where they are, and the page receives only the tiles and values it shows.

Parameters:

data –
What to show:
- a path on the server: FITS (also .fits.fz), ASDF, HDF5, NetCDF-4 (.nc), MATLAB v7.3 (.mat), .npy/.npz, TIFF, PNG or JPEG. A folder or a glob pattern ("frames/*.fits") shows its image files (.mat files only by name); a .pcmosaic file opens a saved mosaic again. A HiPS: its folder (the one holding properties).
- an s3:// URI or an http(s):// URL, read where it is by range requests. A URL whose last part has no file extension is a HiPS’s folder, read tile by tile.
- data in the kernel: a NumPy array (an image, or a cube shown plane by plane), an astropy HDU, HDUList, NDData or CCDData (with its WCS), an ASDF file or a data model.
- a list of these: a mosaic, unless kind says otherwise.
- a table: a .csv, .tsv, .ecsv, .parquet, VOTable (.vot) or Arrow/Feather file, a FITS file of tables and no image, or an astropy, pandas or polars table. It opens in the table viewer.
kind ({"single", "mosaic", "stack", "rgb", "table"}, optional) – How to show it. "mosaic" places several images together (on the sky when they have a WCS, else side by side), "stack" shows them one at a time with a slider, "rgb" shows three as red, green and blue. By default one image is "single", several are a "mosaic" and a table is a "table".
title (str, optional) – The view’s title, also used to name its shared pages. By default made from the file names.
names (list of str, optional) – A name for each image, in the order given, shown in place of its file name (data from the kernel is otherwise called “array”, “HDU” and so on).
height (int, default 600) – The viewer’s height in pixels. The grip under the viewer changes it too.
connection ({"auto", "direct", "kernel"}, default "auto") – How the page reaches the viewer’s process. "direct" goes through jupyter-server-proxy (or to localhost), so the view keeps working while a cell runs; "kernel" relays widget messages through the kernel, which works wherever widgets do. "auto" is direct when the page can be, else through the kernel.
layout ({"sky", "focal", "grid", "pixel", "hpx"}, optional) – Mosaics: where the images go. "sky" by their WCS, "focal" at their places in the instrument’s focal plane (for detectors the viewer knows), "grid" side by side, "pixel" on top of each other on the same pixels, "hpx" on the HEALPix plane (HiPS of one sky frame). By default the first of these the images allow (the mosaic_layout setting).
active (int, optional) – Mosaics and stacks: the index of the image selected (for a stack, the frame shown) first.
color (bool, default False) – Mosaics: show two or more filters as colors, each in its own hue.
blink (bool, default False) – Mosaics: show the images one at a time instead, lined up on the sky (or pixel for pixel), to blink between them.
groups (list of str, optional) – Mosaics: each file’s filter (or folder), one per file. With color=True each group becomes one color.
levels (optional) – Mosaics: the level matching to start with, as a saved .pcmosaic file holds it.
state (dict, optional) – A view saved from another viewer’s state, to open this one the same way: an image’s stretch, colors, regions, pan and zoom; a table’s filters, sort, columns and plot.
anon (bool, default True) – s3:// URIs: read public buckets anonymously. False signs the URLs with the kernel’s AWS credentials (needs boto3: pip install 'pixel-clarity[s3]').
out_dir (str or path, optional) – Where the viewer writes full-resolution exports, shared pages and saved mosaics. By default the kernel’s working directory.
plot (bool, default False) – Tables: open with the plot pane showing.
table (int or str, optional) – Tables: which of a file’s tables to open. A FITS file’s by HDU number (the primary is 0) or EXTNAME, a VOTable’s by its place in the file (from 0). By default the first; the viewer’s toolbar switches between them.
subtract (str, int, tuple or image, optional) – Frame subtraction: show each frame of a cube or stack less a reference, made where the data is (values, statistics, plots and exports are of the difference). "first" (the first frame), "previous" (the frame before each), "ramp" (the first read of each ramp of a cube with four or more axes), an int (that frame, counting from 0), a (first, last) pair (the mean of those frames), or another image of the same size (a bias or dark: anything show takes as one image). The viewer’s Δ button changes it.
divide (bool, default False) – With subtract: divide by the reference instead (changes as a fraction).
**settings – Settings, as in the VS Code extension; your editor suggests them with their values. The usual ones: cmap ("gray", "viridis", "magma", …), scale ("linear", "log", "sqrt", "asinh", "histeq", …), limits ("zscale", "minmax", "99.5", …), invert, zoom ("fit" or 1), auto (auto enhance), sidebar, cuts. pc.settings() lists every one with its values; pc.defaults sets them for every new viewer.

Returns:

Viewer – The viewer. Its state, regions and add_regions() work from Python.

Examples

>>> pc.show("image.fits")
>>> pc.show("s3://bucket/path/image.asdf", cmap="viridis", scale="asinh", limits="99.5")
>>> pc.show(array, title="residuals", height=800)
>>> pc.show(sorted(glob("frames/*.fits")), kind="stack")
>>> pc.show("ramp.fits", subtract="first")   # each read less the first

pixel_clarity.rgb(red, green, blue, *, title=None, names=None, height=600, connection='auto', state=None, anon=True, out_dir=None, **settings)#

Show three images as red, green and blue.

Parameters:

red – Each an image as show takes one: a path, an s3:// URI, a URL, an array, an HDU or NDData, an ASDF file or a data model. Images with a WCS are aligned on the sky.
green – Each an image as show takes one: a path, an s3:// URI, a URL, an array, an HDU or NDData, an ASDF file or a data model. Images with a WCS are aligned on the sky.
blue – Each an image as show takes one: a path, an s3:// URI, a URL, an array, an HDU or NDData, an ASDF file or a data model. Images with a WCS are aligned on the sky.
title (str, optional) – The view’s title. By default made from the file names.
names (list of str, optional) – [red, green, blue] names, shown in place of the file names.
height (int, default 600) – The viewer’s height in pixels. The grip under the viewer changes it too.
connection ({"auto", "direct", "kernel"}, default "auto") – How the page reaches the viewer’s process. "direct" goes through jupyter-server-proxy (or to localhost), so the view keeps working while a cell runs; "kernel" relays widget messages through the kernel, which works wherever widgets do. "auto" is direct when the page can be, else through the kernel.
state (dict, optional) – A view saved from another viewer’s state, to open this one the same way: an image’s stretch, colors, regions, pan and zoom; a table’s filters, sort, columns and plot.
anon (bool, default True) – s3:// URIs: read public buckets anonymously. False signs the URLs with the kernel’s AWS credentials (needs boto3: pip install 'pixel-clarity[s3]').
out_dir (str or path, optional) – Where the viewer writes full-resolution exports, shared pages and saved mosaics. By default the kernel’s working directory.
**settings – Settings, as in the VS Code extension; your editor suggests them with their values. The usual ones: cmap ("gray", "viridis", "magma", …), scale ("linear", "log", "sqrt", "asinh", "histeq", …), limits ("zscale", "minmax", "99.5", …), invert, zoom ("fit" or 1), auto (auto enhance), sidebar, cuts. pc.settings() lists every one with its values; pc.defaults sets them for every new viewer. link_scales=False starts the three channels with scales of their own.

Returns:

Viewer – The viewer. Its state, regions and add_regions() work from Python.

pixel_clarity.mosaic(files, *, color=False, blink=False, layout=None, groups=None, active=None, levels=None, title=None, names=None, height=600, connection='auto', state=None, anon=True, out_dir=None, **settings)#

Show images (detectors, tiles) together: placed by their sky coordinates, else side by side.

Parameters:

files – The images: a folder or a glob pattern, a .pcmosaic file saved from a mosaic, or a list of anything show takes (paths, s3:// URIs, URLs, arrays, HDUs, data models).
color (bool, default False) – Mosaics: show two or more filters as colors, each in its own hue.
blink (bool, default False) – Mosaics: show the images one at a time instead, lined up on the sky (or pixel for pixel), to blink between them.
layout ({"sky", "focal", "grid", "pixel", "hpx"}, optional) – Mosaics: where the images go. "sky" by their WCS, "focal" at their places in the instrument’s focal plane (for detectors the viewer knows), "grid" side by side, "pixel" on top of each other on the same pixels, "hpx" on the HEALPix plane (HiPS of one sky frame). By default the first of these the images allow (the mosaic_layout setting).
groups (list of str, optional) – Mosaics: each file’s filter (or folder), one per file. With color=True each group becomes one color.
active (int, optional) – Mosaics and stacks: the index of the image selected (for a stack, the frame shown) first.
levels (optional) – Mosaics: the level matching to start with, as a saved .pcmosaic file holds it.
title (str, optional) – The view’s title, also used to name its shared pages. By default made from the file names.
names (list of str, optional) – A name for each image, in the order given, shown in place of its file name (data from the kernel is otherwise called “array”, “HDU” and so on).
height (int, default 600) – The viewer’s height in pixels. The grip under the viewer changes it too.
connection ({"auto", "direct", "kernel"}, default "auto") – How the page reaches the viewer’s process. "direct" goes through jupyter-server-proxy (or to localhost), so the view keeps working while a cell runs; "kernel" relays widget messages through the kernel, which works wherever widgets do. "auto" is direct when the page can be, else through the kernel.
state (dict, optional) – A view saved from another viewer’s state, to open this one the same way: an image’s stretch, colors, regions, pan and zoom; a table’s filters, sort, columns and plot.
anon (bool, default True) – s3:// URIs: read public buckets anonymously. False signs the URLs with the kernel’s AWS credentials (needs boto3: pip install 'pixel-clarity[s3]').
out_dir (str or path, optional) – Where the viewer writes full-resolution exports, shared pages and saved mosaics. By default the kernel’s working directory.
**settings – Settings, as in the VS Code extension; your editor suggests them with their values. The usual ones: cmap ("gray", "viridis", "magma", …), scale ("linear", "log", "sqrt", "asinh", "histeq", …), limits ("zscale", "minmax", "99.5", …), invert, zoom ("fit" or 1), auto (auto enhance), sidebar, cuts. pc.settings() lists every one with its values; pc.defaults sets them for every new viewer. Mosaics also take match_sky, flux_calibrate, feather, trim_edges and outlines.

Returns:

Viewer – The viewer. Its state, regions and add_regions() work from Python.

pixel_clarity.stack(files, *, active=None, title=None, names=None, height=600, connection='auto', state=None, anon=True, out_dir=None, subtract=None, divide=False, **settings)#

Show images as the frames of a stack, one at a time with a slider.

Parameters:

files – The frames, in order: a folder or a glob pattern, or a list of anything show takes (paths, s3:// URIs, URLs, arrays, HDUs, data models).
active (int, optional) – The index of the frame shown first (by default the first).
title (str, optional) – The view’s title, also used to name its shared pages. By default made from the file names.
names (list of str, optional) – A name for each image, in the order given, shown in place of its file name (data from the kernel is otherwise called “array”, “HDU” and so on).
height (int, default 600) – The viewer’s height in pixels. The grip under the viewer changes it too.
connection ({"auto", "direct", "kernel"}, default "auto") – How the page reaches the viewer’s process. "direct" goes through jupyter-server-proxy (or to localhost), so the view keeps working while a cell runs; "kernel" relays widget messages through the kernel, which works wherever widgets do. "auto" is direct when the page can be, else through the kernel.
state (dict, optional) – A view saved from another viewer’s state, to open this one the same way: an image’s stretch, colors, regions, pan and zoom; a table’s filters, sort, columns and plot.
anon (bool, default True) – s3:// URIs: read public buckets anonymously. False signs the URLs with the kernel’s AWS credentials (needs boto3: pip install 'pixel-clarity[s3]').
out_dir (str or path, optional) – Where the viewer writes full-resolution exports, shared pages and saved mosaics. By default the kernel’s working directory.
subtract (str, int, tuple or image, optional) – Frame subtraction: show each frame of a cube or stack less a reference, made where the data is (values, statistics, plots and exports are of the difference). "first" (the first frame), "previous" (the frame before each), "ramp" (the first read of each ramp of a cube with four or more axes), an int (that frame, counting from 0), a (first, last) pair (the mean of those frames), or another image of the same size (a bias or dark: anything show takes as one image). The viewer’s Δ button changes it.
divide (bool, default False) – With subtract: divide by the reference instead (changes as a fraction).
**settings – Settings, as in the VS Code extension; your editor suggests them with their values. The usual ones: cmap ("gray", "viridis", "magma", …), scale ("linear", "log", "sqrt", "asinh", "histeq", …), limits ("zscale", "minmax", "99.5", …), invert, zoom ("fit" or 1), auto (auto enhance), sidebar, cuts. pc.settings() lists every one with its values; pc.defaults sets them for every new viewer.

Returns:

Viewer – The viewer. Its state, regions and add_regions() work from Python.

pixel_clarity.blink(files, *, active=None, title=None, names=None, height=600, connection='auto', state=None, anon=True, out_dir=None, **settings)#

Blink between images: shown one at a time, lined up on the sky (or pixel for pixel when they have no WCS). A mosaic with blink=True.

Parameters:

files – The images, in order: a folder or a glob pattern, or a list of anything show takes (paths, s3:// URIs, URLs, arrays, HDUs, data models).
active (int, optional) – The index of the image shown first (by default the first).
title (str, optional) – The view’s title, also used to name its shared pages. By default made from the file names.
names (list of str, optional) – A name for each image, in the order given, shown in place of its file name (data from the kernel is otherwise called “array”, “HDU” and so on).
height (int, default 600) – The viewer’s height in pixels. The grip under the viewer changes it too.
connection ({"auto", "direct", "kernel"}, default "auto") – How the page reaches the viewer’s process. "direct" goes through jupyter-server-proxy (or to localhost), so the view keeps working while a cell runs; "kernel" relays widget messages through the kernel, which works wherever widgets do. "auto" is direct when the page can be, else through the kernel.
state (dict, optional) – A view saved from another viewer’s state, to open this one the same way: an image’s stretch, colors, regions, pan and zoom; a table’s filters, sort, columns and plot.
anon (bool, default True) – s3:// URIs: read public buckets anonymously. False signs the URLs with the kernel’s AWS credentials (needs boto3: pip install 'pixel-clarity[s3]').
out_dir (str or path, optional) – Where the viewer writes full-resolution exports, shared pages and saved mosaics. By default the kernel’s working directory.
**settings – Settings, as in the VS Code extension; your editor suggests them with their values. The usual ones: cmap ("gray", "viridis", "magma", …), scale ("linear", "log", "sqrt", "asinh", "histeq", …), limits ("zscale", "minmax", "99.5", …), invert, zoom ("fit" or 1), auto (auto enhance), sidebar, cuts. pc.settings() lists every one with its values; pc.defaults sets them for every new viewer.

Returns:

Viewer – The viewer. Its state, regions and add_regions() work from Python.

pixel_clarity.table(data, *, table=None, plot=False, title=None, names=None, height=600, connection='auto', state=None, anon=True, out_dir=None, **settings)#

Show a table in the table viewer.

Sorting, filtering (mag < 20 and class == 'STAR'), computed columns, statistics and plots are worked out on the server; the page receives the rows on screen. Its export dialog writes CSV, TSV, ECSV or region files to out_dir, and Overlay on image draws the rows on the image viewer used last.

Parameters:

data – A CSV, TSV, ECSV, VOTable (.vot, .xml; also gzipped), Parquet, Arrow/Feather or FITS table file: a path, an s3:// URI or a URL. Or a table in the kernel: astropy, pandas or polars, or a NumPy structured array (written to a temporary Parquet file when pyarrow is installed, else ECSV or CSV).
plot (bool, default False) – Tables: open with the plot pane showing.
table (int or str, optional) – Tables: which of a file’s tables to open. A FITS file’s by HDU number (the primary is 0) or EXTNAME, a VOTable’s by its place in the file (from 0). By default the first; the viewer’s toolbar switches between them.
title (str, optional) – The table’s title. By default the file’s name.
names (list of str, optional) – [name]: the name of a table from the kernel (by default “table”).
height (int, default 600) – The viewer’s height in pixels. The grip under the viewer changes it too.
connection ({"auto", "direct", "kernel"}, default "auto") – How the page reaches the viewer’s process. "direct" goes through jupyter-server-proxy (or to localhost), so the view keeps working while a cell runs; "kernel" relays widget messages through the kernel, which works wherever widgets do. "auto" is direct when the page can be, else through the kernel.
state (dict, optional) – A view saved from another viewer’s state, to open this one the same way: an image’s stretch, colors, regions, pan and zoom; a table’s filters, sort, columns and plot.
anon (bool, default True) – s3:// URIs: read public buckets anonymously. False signs the URLs with the kernel’s AWS credentials (needs boto3: pip install 'pixel-clarity[s3]').
out_dir (str or path, optional) – Where the viewer writes full-resolution exports, shared pages and saved mosaics. By default the kernel’s working directory.
**settings – Settings as for show (live_reload, online); the image settings don’t apply.

Returns:

Viewer – The viewer. Its state, regions and add_regions() work from Python.

pixel_clarity.popup(data, *, window='main', kind=None, title=None, names=None, layout=None, active=None, color=False, blink=False, groups=None, levels=None, anon=True, out_dir=None, plot=False, subtract=None, divide=False, **settings)#

Show images or a table in a browser tab of its own, from any Python program: a script, IPython, or a notebook (where it shows a link to the tab).

Called again with the same window, it shows the new data in the same tab: an array of the same size and type updates in place, keeping the zoom, pan and stretch, so a loop can watch it change. Anything else starts the tab afresh.

Everything stays with the program: its viewer process and files go when it ends. A script waits at its end until its windows’ tabs are closed (or Ctrl-C), so they stay up to be looked at; pc.wait() waits sooner and PIXEL_CLARITY_POPUP_WAIT=0 doesn’t wait. The page is served on this machine (127.0.0.1): over SSH, forward the port it prints.

Parameters:

data – What to show, as pc.show takes it: a path (FITS, ASDF, HDF5, NetCDF-4, MATLAB v7.3, .npy/.npz, TIFF, PNG, JPEG; a table file; a folder or glob pattern; a .pcmosaic file), an s3:// URI or a URL (read where it is), an array, astropy HDU or NDData, ASDF file or data model, a list of these (a mosaic unless kind says otherwise), or a table (a table file, or an astropy, pandas or polars table). Data in memory is written to the window’s own files, over the last.
window (str, default "main") – Which window: each name has a tab of its own. Another name opens a second tab.
kind ({"single", "mosaic", "stack", "rgb", "table"}, optional) – How to show it. "mosaic" places several images together (on the sky when they have a WCS, else side by side), "stack" shows them one at a time with a slider, "rgb" shows three as red, green and blue. By default one image is "single", several are a "mosaic" and a table is a "table".
title (str, optional) – The view’s title, also used to name its shared pages. By default made from the file names.
names (list of str, optional) – A name for each image, in the order given, shown in place of its file name (data from the kernel is otherwise called “array”, “HDU” and so on).
layout ({"sky", "focal", "grid", "pixel"}, optional) – Mosaics: where the images go. "sky" by their WCS, "focal" at their places in the instrument’s focal plane (for detectors the viewer knows), "grid" side by side, "pixel" on top of each other on the same pixels. By default the first of these the images allow (the mosaic_layout setting).
active (int, optional) – Mosaics and stacks: the index of the image selected (for a stack, the frame shown) first.
color (bool, default False) – Mosaics: show two or more filters as colors, each in its own hue.
blink (bool, default False) – Mosaics: show the images one at a time instead, lined up on the sky (or pixel for pixel), to blink between them.
groups (list of str, optional) – Mosaics: each file’s filter (or folder), one per file. With color=True each group becomes one color.
levels (optional) – Mosaics: the level matching to start with, as a saved .pcmosaic file holds it.
anon (bool, default True) – s3:// URIs: read public buckets anonymously. False signs the URLs with the kernel’s AWS credentials (needs boto3: pip install 'pixel-clarity[s3]').
out_dir (str or path, optional) – Where the viewer writes full-resolution exports, shared pages and saved mosaics. By default the working directory.
plot (bool, default False) – Tables: open with the plot pane showing.
subtract (str, int, tuple or image, optional) – Frame subtraction: each frame of a cube or stack less a reference ("first", "previous", "ramp", a frame number from 0, a (first, last) pair for their mean, or another image of the same size), as pixel_clarity.show takes it.
divide (bool, default False) – With subtract: divide by the reference instead.
**settings – Settings, as in the VS Code extension; your editor suggests them with their values. The usual ones: cmap ("gray", "viridis", "magma", …), scale ("linear", "log", "sqrt", "asinh", "histeq", …), limits ("zscale", "minmax", "99.5", …), invert, zoom ("fit" or 1), auto (auto enhance), sidebar, cuts. pc.settings() lists every one with its values; pc.defaults sets them for every new viewer and window.

Returns:

Popup – The window: show() puts something else in it, state and regions read what is on it, add_regions() draws on it.

Examples

>>> for step in range(100):
...     pc.popup(simulate(step), title="simulation")   # the same tab, updated
>>> pc.popup("image.fits", cmap="viridis", window="reference")

Saving pictures#

pixel_clarity.save_png(data, path, *, kind=None, area='all', bin=None, layout=None, color=False, blink=False, groups=None, levels=None, active=None, names=None, state=None, anon=True, subtract=None, divide=False, timeout=600, **settings)#

Save images as a PNG at full resolution, as a viewer’s Export image would, without showing them: for many files in a loop, or a script with no notebook.

To save a viewer as it’s shown, call the viewer’s own method instead: v.save_png(path).

The data is opened as show would open it (one image, a mosaic, a stack’s frame, an RGB set), with the same stretch, colors and, for a mosaic, level matching, and rendered next to the data. Regions, text and a colorbar aren’t drawn; the export dialog draws those.

Parameters:

data – What show takes: a file, a folder or glob pattern (a mosaic), an s3:// URI or URL, data in the kernel, or a list of these.
path (str or path) – Where to write the PNG, replacing what is there (.png is added if missing).
kind ({"single", "mosaic", "stack", "rgb"}, optional) – How to show it, as in show.
area ({"all", "crop"}, default "all") – The whole image (or mosaic), or the crop saved in state.
bin (int, optional) – Each output pixel is the mean of bin × bin data pixels. By default the finest of 1, 2, 3, 4, 6, 8 and 16 that keeps the PNG under 100 megapixels, as the dialog starts.
layout – Mosaics (and active for stacks), as in mosaic. A mosaic shown with blink saves the image active picks.
color – Mosaics (and active for stacks), as in mosaic. A mosaic shown with blink saves the image active picks.
blink – Mosaics (and active for stacks), as in mosaic. A mosaic shown with blink saves the image active picks.
groups – Mosaics (and active for stacks), as in mosaic. A mosaic shown with blink saves the image active picks.
levels – Mosaics (and active for stacks), as in mosaic. A mosaic shown with blink saves the image active picks.
active – Mosaics (and active for stacks), as in mosaic. A mosaic shown with blink saves the image active picks.
names (list of str, optional) – A name for each image (used to tell apart detectors left out when they can’t be read).
state (dict, optional) – A viewer’s state to save the data as: its stretch, colors, levels, turn and crop. With it, the PNG of other data of the same form looks as that viewer did.
anon (bool, default True) – s3:// URIs: read public buckets anonymously.
subtract – Frame subtraction, as in show.
divide – Frame subtraction, as in show.
timeout (float, default 600) – Seconds to wait for the PNG to be written.
**settings – Settings, as show takes them: cmap, scale, limits, invert, auto, mosaic_sky, … (pc.settings() lists them). pc.defaults applies too.

Returns:

Path – The PNG written.

Examples

>>> pc.save_png("image.fits", "image.png", cmap="magma", scale="asinh", limits="99.5")
>>> for exposure in sorted(Path("exposures").iterdir()):
...     pc.save_png(exposure, f"png/{exposure.name}.png", layout="sky", bin=4)
>>> pc.save_png(other_files, "same_look.png", state=viewer.state)   # as a viewer shows it

The viewer#

class pixel_clarity.Viewer(*args, **kwargs)#

A Pixel Clarity view of one or more images, or of a table, in a notebook.

The data stays on the server: the backend process reads the files there and the page receives only the tiles, rows and values it shows. Show it as a cell’s last expression, or with show(). pc.show(...) makes one and shows it.

Parameters:

data –
What to show:
- a path on the server: FITS (also .fits.fz), ASDF, HDF5, NetCDF-4 (.nc), MATLAB v7.3 (.mat), .npy/.npz, TIFF, PNG or JPEG. A folder or a glob pattern ("frames/*.fits") shows its image files (.mat files only by name); a .pcmosaic file opens a saved mosaic again. A HiPS: its folder (the one holding properties).
- an s3:// URI or an http(s):// URL, read where it is by range requests. A URL whose last part has no file extension is a HiPS’s folder, read tile by tile.
- data in the kernel: a NumPy array (an image, or a cube shown plane by plane), an astropy HDU, HDUList, NDData or CCDData (with its WCS), an ASDF file or a data model.
- a list of these: a mosaic, unless kind says otherwise.
- a table: a .csv, .tsv, .ecsv, .parquet, VOTable (.vot) or Arrow/Feather file, a FITS file of tables and no image, or an astropy, pandas or polars table. It opens in the table viewer.
kind ({"single", "mosaic", "stack", "rgb", "table"}, optional) – How to show it. "mosaic" places several images together (on the sky when they have a WCS, else side by side), "stack" shows them one at a time with a slider, "rgb" shows three as red, green and blue. By default one image is "single", several are a "mosaic" and a table is a "table".
title (str, optional) – The view’s title, also used to name its shared pages. By default made from the file names.
names (list of str, optional) – A name for each image, in the order given, shown in place of its file name (data from the kernel is otherwise called “array”, “HDU” and so on).
height (int, default 600) – The viewer’s height in pixels. The grip under the viewer changes it too.
connection ({"auto", "direct", "kernel"}, default "auto") – How the page reaches the viewer’s process. "direct" goes through jupyter-server-proxy (or to localhost), so the view keeps working while a cell runs; "kernel" relays widget messages through the kernel, which works wherever widgets do. "auto" is direct when the page can be, else through the kernel.
layout ({"sky", "focal", "grid", "pixel", "hpx"}, optional) – Mosaics: where the images go. "sky" by their WCS, "focal" at their places in the instrument’s focal plane (for detectors the viewer knows), "grid" side by side, "pixel" on top of each other on the same pixels, "hpx" on the HEALPix plane (HiPS of one sky frame). By default the first of these the images allow (the mosaic_layout setting).
active (int, optional) – Mosaics and stacks: the index of the image selected (for a stack, the frame shown) first.
color (bool, default False) – Mosaics: show two or more filters as colors, each in its own hue.
blink (bool, default False) – Mosaics: show the images one at a time instead, lined up on the sky (or pixel for pixel), to blink between them.
groups (list of str, optional) – Mosaics: each file’s filter (or folder), one per file. With color=True each group becomes one color.
levels (optional) – Mosaics: the level matching to start with, as a saved .pcmosaic file holds it.
state (dict, optional) – A view saved from another viewer’s state, to open this one the same way: an image’s stretch, colors, regions, pan and zoom; a table’s filters, sort, columns and plot.
anon (bool, default True) – s3:// URIs: read public buckets anonymously. False signs the URLs with the kernel’s AWS credentials (needs boto3: pip install 'pixel-clarity[s3]').
out_dir (str or path, optional) – Where the viewer writes full-resolution exports, shared pages and saved mosaics. By default the kernel’s working directory.
plot (bool, default False) – Tables: open with the plot pane showing.
table (int or str, optional) – Tables: which of a file’s tables to open. A FITS file’s by HDU number (the primary is 0) or EXTNAME, a VOTable’s by its place in the file (from 0). By default the first; the viewer’s toolbar switches between them.
subtract (str, int, tuple or image, optional) – Frame subtraction: show each frame of a cube or stack less a reference, made where the data is (values, statistics, plots and exports are of the difference). "first" (the first frame), "previous" (the frame before each), "ramp" (the first read of each ramp of a cube with four or more axes), an int (that frame, counting from 0), a (first, last) pair (the mean of those frames), or another image of the same size (a bias or dark: anything show takes as one image). The viewer’s Δ button changes it.
divide (bool, default False) – With subtract: divide by the reference instead (changes as a fraction).
**settings – Settings, as in the VS Code extension; your editor suggests them with their values. The usual ones: cmap ("gray", "viridis", "magma", …), scale ("linear", "log", "sqrt", "asinh", "histeq", …), limits ("zscale", "minmax", "99.5", …), invert, zoom ("fit" or 1), auto (auto enhance), sidebar, cuts. pc.settings() lists every one with its values; pc.defaults sets them for every new viewer.

height#: Height in pixels (the grip under the viewer changes it too).

connection#: ‘auto’ (directly when the page can reach the backend, else through the kernel), ‘direct’ or ‘kernel’.

property tab_url#: A link to this view in a browser tab of its own, through jupyter-server-proxy (as the viewer’s own link).

show()#: Display the viewer (it then isn’t displayed again as the cell’s result).

close()#: Close the view and free what the backend holds for it.

add_class(className)#

Adds a class to the top level element of the widget.

Doesn’t add the class if it already exists.

add_regions(regions, name=None, *, profile=False)#

Draw regions on the view.

A viewer still opening gets them once its image is shown. More than 2000 shapes show as a catalog overlay rather than as editable regions. A DS9 projection is a line widened into a band, whose profile collapses across it.

Parameters:

regions – What to draw: a regions object or a list of them (regions.Regions), in pixel or sky coordinates (sky ones are placed with the image’s WCS); the path of a DS9 region file; or DS9 region text.
name (str, optional) – A name for the set, used in the viewer’s message saying they were added. A catalog overlay goes by it: another with the same name replaces it. By default the region file’s name, else “regions”.
profile (bool, default False) – Plot the profile of the first line, projection or box among them in the pane under the image: the values along it, collapsed across its width.

add_traits(**traits)#: Dynamically add trait attributes to the Widget.

blur()#: Blur the widget.

classmethod class_own_trait_events(name)#

Get a dict of all event handlers defined on this class, not a parent.

Works like trait_events, except for excluding traits from parents.

classmethod class_own_traits(**metadata)#

Get a dict of all the traitlets defined on this class, not a parent.

Works like class_traits, except for excluding traits from parents.

classmethod class_trait_names(**metadata)#

Get a list of all the names of this class’ traits.

This method is just like the trait_names() method, but is unbound.

classmethod class_traits(**metadata)#

Get a dict of all the traits of this class. The dictionary is keyed on the name and the values are the TraitType objects.

This method is just like the traits() method, but is unbound.

The TraitTypes returned don’t know anything about the values that the various HasTrait’s instances are holding.

The metadata kwargs allow functions to be passed in which filter traits based on metadata values. The functions should take a single value as an argument and return a boolean. If any function returns False, then the trait is not included in the output. If a metadata key doesn’t exist, None will be passed to the function.

property cross_validation_lock#

A contextmanager for running a block with our cross validation lock set to True.

At the end of the block, the lock’s value is restored to its value prior to entering the block.

property files#: The files (paths or URLs) this viewer shows.

focus()#: Focus on the widget.

static get_manager_state(drop_defaults=False, widgets=None)#

Returns the full state for a widget manager for embedding

Parameters:

drop_defaults – when True, it will not include default value
widgets – list with widgets to include in the state (or all widgets when None)

Returns:

get_state(key=None, drop_defaults=False)#

Gets the widget state, or a piece of it.

Parameters:

key (unicode or iterable (optional)) – A single property’s name or iterable of property names to get.

Returns:

state (dict of states)
metadata (dict) – metadata for each field: {key: metadata}

static handle_comm_opened(comm, msg)#: Static method, called when a widget is constructed.

classmethod handle_control_comm_opened(comm, msg)#: Class method, called when the comm-open message on the “jupyter.widget.control” comm channel is received

has_trait(name)#: Returns True if the object has a trait with the specified name.

hold_sync()#: Hold syncing any state until the outermost context manager exits

hold_trait_notifications()#

Context manager for bundling trait change notifications and cross validation.

Use this when doing multiple trait assignments (init, config), to avoid race conditions in trait notifiers requesting other trait values. All trait notifications will fire after all values have been assigned.

keys#: The traits which are synced.

property model_id#

Gets the model id of this widget.

If a Comm doesn’t exist yet, a Comm will be created automagically.

notify_change(change)#: Called when a property has changed.

observe(handler, names=traitlets.All, type='change')#

Setup a handler to be called when a trait changes.

This is used to setup dynamic notifications of trait changes.

Parameters:

handler (callable) – A callable that is called when a trait changes. Its signature should be handler(change), where change is a dictionary. The change dictionary at least holds a ‘type’ key. * type: the type of notification. Other keys may be passed depending on the value of ‘type’. In the case where type is ‘change’, we also have the following keys: * owner : the HasTraits instance * old : the old value of the modified trait attribute * new : the new value of the modified trait attribute * name : the name of the modified trait attribute.
names (list, str, All) – If names is All, the handler will apply to all traits. If a list of str, handler will apply to all names in the list. If a str, the handler will apply just to that name.
type (str, All (default: 'change')) – The type of notification to filter by. If equal to All, then all notifications are passed to the observe handler.

on_msg(callback, remove=False)#

(Un)Register a custom msg receive callback.

Parameters:

callback (callable) –
callback will be passed three arguments when a message arrives:
```
callback(widget, content, buffers)
```
remove (bool) – True if the callback should be unregistered.

on_trait_change(handler=None, name=None, remove=False)#

DEPRECATED: Setup a handler to be called when a trait changes.

This is used to setup dynamic notifications of trait changes.

Static handlers can be created by creating methods on a HasTraits subclass with the naming convention ‘_[traitname]_changed’. Thus, to create static handler for the trait ‘a’, create the method _a_changed(self, name, old, new) (fewer arguments can be used, see below).

If remove is True and handler is not specified, all change handlers for the specified name are uninstalled.

Parameters:

handler (callable, None) – A callable that is called when a trait changes. Its signature can be handler(), handler(name), handler(name, new), handler(name, old, new), or handler(name, old, new, self).
name (list, str, None) – If None, the handler will apply to all traits. If a list of str, handler will apply to all names in the list. If a str, the handler will apply just to that name.
remove (bool) – If False (the default), then install the handler. If True then unintall it.

static on_widget_constructed(callback)#

Registers a callback to be called when a widget is constructed.

The callback must have the following signature: callback(widget)

open()#: Open a comm to the frontend if one isn’t already open.

property regions#: The regions on the view as a regions.Regions list of pixel regions (needs the regions package). r.to_sky(wcs) gives sky regions; for a mosaic they are in its own plane.

property regions_ds9#

The regions, text and arrows on the view as DS9 region text, in image coordinates.

Coordinates are the image’s pixels (a stack’s frames, an RGB set’s red image), or for a mosaic those of the mosaic’s own plane. The viewer’s Save regions writes sky coordinates.

remove_class(className)#

Removes a class from the top level element of the widget.

Doesn’t remove the class if it doesn’t exist.

save_png(path, *, area='all', bin=None, timeout=600)#

Save the view as a PNG at full resolution, as the viewer’s Export image does.

The image is as the view was last left in a viewer (stretch, colors, a mosaic’s levels, turn), or as a viewer would open it when none has shown it yet. No viewer needs to be on screen: the backend works the view out and renders it next to the data. Regions, text and a colorbar aren’t drawn on it; the export dialog draws those.

Parameters:

path (str or path) – Where to write the PNG, replacing what is there (.png is added if missing).
area ({"all", "crop"}, default "all") – The whole image (or mosaic), or the view’s crop.
bin (int, optional) – Each output pixel is the mean of bin × bin data pixels. By default the finest of 1, 2, 3, 4, 6, 8 and 16 that keeps the PNG under 100 megapixels, as the dialog starts.
timeout (float, default 600) – Seconds to wait for the PNG to be written.

Returns:

Path – The PNG written.

send(content, buffers=None)#

Sends a custom msg to the widget model in the front-end.

Parameters:

content (dict) – Content of the message to send.
buffers (list of binary buffers) – Binary buffers to send with message

send_state(key=None)#

Sends the widget state, or a piece of it, to the front-end, if it exists.

Parameters:: key (unicode, or iterable (optional)) – A single property’s name or iterable of property names to sync with the front-end.

set_state(sync_data)#: Called when a state is received from the front-end.

set_trait(name, value)#: Forcibly sets trait attribute, including read-only attributes.

setup_instance(*args, **kwargs)#: This is called before self.__init__ is called.

share(path=None, *, title=None, caption='', credit='', data='compact', preview='medium', urls='', tools=True, timeout=600)#

Write the view as a web page of its own: the viewer and the data it shows, to open in any browser with no server, as the viewer’s Share as a web page does.

The page opens as the view was last left in a viewer (stretch, colors, regions, pan and zoom), or as it opens when no viewer has shown it yet.

Parameters:

path (str or path, optional) – Where to write the page (.html), replacing what is there. By default a new name made from the title, in the viewer’s out_dir.
title (str, optional) – Shown on the page. The title defaults to the view’s.
caption (str, optional) – Shown on the page. The title defaults to the view’s.
credit (str, optional) – Shown on the page. The title defaults to the view’s.
data ({"compact", "compact_files", "embed", "link", "preview"}, default "compact") – Full resolution of the frames shown: in the page as compact data, as compact data in a folder beside the page (<name>_data/, read as needed: for a web site), the files themselves in the page, a link to the files (by urls, else by their path from the page), or none (the preview only).
preview ({"small", "medium", "large"}, default "medium") – The overview the page opens with: 1, 4 or 16 megapixels for all the frames together.
urls (str, optional) – With data="link": one base URL ending in /, or one URL per file.
tools (bool, default True) – False opens the page with every tool hidden.
timeout (float, default 600) – Seconds to wait for the page to be written.

Returns:

Path – The page written.

property state#: The view as the viewer last saved it (an image’s stretch, colors, regions, pan and zoom; a table’s filters, sort, columns and plot); pass it as state= to open another the same way.

tabbable#: Is widget tabbable?

tooltip#: A tooltip caption.

trait_defaults(*names, **metadata)#

Return a trait’s default value or a dictionary of them

Notes

Dynamically generated default values may depend on the current state of the object.

classmethod trait_events(name=None)#

Get a dict of all the event handlers of this class.

Parameters:: name (str (default: None)) – The name of a trait of this class. If name is None then all the event handlers of this class will be returned instead.
Returns:: The event handlers associated with a trait name, or all event handlers.

trait_has_value(name)#

Returns True if the specified trait has a value.

This will return false even if getattr would return a dynamically generated default value. These default values will be recognized as existing only after they have been generated.

Example

class MyClass(HasTraits):
    i = Int()


mc = MyClass()
assert not mc.trait_has_value("i")
mc.i  # generates a default value
assert mc.trait_has_value("i")

trait_metadata(traitname, key, default=None)#: Get metadata values for trait by key.

trait_names(**metadata)#: Get a list of all the names of this class’ traits.

trait_values(**metadata)#

A dict of trait names and their values.

Returns:: A dict of trait names and their values.

Notes

Trait values are retrieved via getattr, any exceptions raised by traits or the operations they may trigger will result in the absence of a trait value in the result dict.

traits(**metadata)#

Get a dict of all the traits of this class. The dictionary is keyed on the name and the values are the TraitType objects.

The TraitTypes returned don’t know anything about the values that the various HasTrait’s instances are holding.

unobserve(handler, names=traitlets.All, type='change')#

Remove a trait change handler.

This is used to unregister handlers to trait change notifications.

Parameters:

handler (callable) – The callable called when a trait attribute changes.
names (list, str, All (default: All)) – The names of the traits for which the specified handler should be uninstalled. If names is All, the specified handler is uninstalled from the list of notifiers corresponding to all changes.
type (str or All (default: 'change')) – The type of notification to filter by. If All, the specified handler is uninstalled from the list of notifiers corresponding to all types.

unobserve_all(name=traitlets.All)#: Remove trait change handlers of any type for the specified name. If name is not specified, removes all trait notifiers.

Settings#

pixel_clarity.save_defaults(**settings)#

Keep settings for every new viewer, in this session and later ones.

Adds settings to pc.defaults and writes pc.defaults to a file in your home directory (~/.config/pixel-clarity/defaults.json, or the path in PIXEL_CLARITY_DEFAULTS), which import pixel_clarity reads. Keywords given to show and the others still win.

Parameters:: **settings – Settings as show takes them, e.g. cmap="viridis", scale="asinh", limits="99.5". With none, saves pc.defaults as it is (after del pc.defaults["cmap"], say).
Returns:: Path – The file written.

Examples

>>> pc.save_defaults(cmap="magma", scale="asinh", limits="99.5", sky_format="degrees")
>>> pc.reset_defaults()     # back to the viewer's own

pixel_clarity.reset_defaults()#: Forget the saved defaults: empties pc.defaults and removes the file save_defaults wrote.

pixel_clarity.settings()#: Print the settings show, popup and the others take as keywords, with their allowed values and defaults (and yours, from pc.defaults). pc.defaults sets them for every new viewer in this session; pc.save_defaults(...) keeps them for later sessions too.

pixel_clarity.diagnostics()#

What the viewer’s process sees here, for reporting a problem (starts it if needed).

Returns:: dict – pixel_clarity (this package’s version), node and node_version (the Node.js it runs on), cpus and memory_gb (the limits it found, a container’s included), pool_workers (threads reading a mosaic or stack), backend_port, jupyterhub_prefix, temp_dir and temp_free_gb (where data from the kernel is written, and the room left there).