Settings and defaults

Every keyword that sets how a view starts (the colormap, the stretch, the panels, how mosaics match their levels) is a setting. This page shows how to make your own choices the default, for this session or for good, and lists every setting with its values.

Settings as keywords

Each setting is a keyword of pc.show, pc.rgb, pc.mosaic, pc.stack, pc.blink, pc.table and pc.popup. It sets how the view opens; the viewer’s toolbar and panels change it afterwards.

import pixel_clarity as pc

pc.show("image.fits", cmap="viridis", scale="asinh", limits="99.5", sidebar=False)

Your editor knows them: the keywords are typed, so autocompletion offers their names and allowed values, and a type checker flags a misspelling. A wrong value raises an error that lists the right ones:

pc.show("image.fits", cmap="virdis")

ValueError: cmap='virdis': use one of 'gray', 'heat', 'cool', 'rainbow', 'a', 'b', 'bb', 'he', 'i8', 'aips0', 'red', 'green', 'blue', 'viridis', 'magma', 'inferno', 'plasma', 'cividis', 'turbo', 'cubehelix', 'gist_heat', 'gist_earth', 'coolwarm', 'RdBu_r', 'seismic', 'twilight', 'nipy_spectral', 'hsv'

Defaults for this session

pc.defaults holds settings applied to every new viewer. Change it like a dictionary:

pc.defaults["cmap"] = "magma"
pc.defaults.update(scale="asinh", limits="99.5")

pc.show("image.fits")                 # magma, asinh, 99.5%
pc.show("image.fits", cmap="gray")    # a keyword still wins

pc.defaults.clear()                   # back to the viewer's own

Defaults for good

pc.save_defaults does the same and also keeps your choices for later sessions. They are written to ~/.config/pixel-clarity/defaults.json and read whenever pixel_clarity is imported.

pc.save_defaults(scale="asinh", limits="99.5", cmap="magma", sky_format="degrees")
pc.reset_defaults()                   # forget them

PIXEL_CLARITY_DEFAULTS names another file, handy for a project or a shared account. A setting in the file that this version doesn’t know, or a value it doesn’t allow, is left out with a warning rather than an error, so an old file never stops a notebook.

What’s set now

pc.settings() lists every setting with its allowed values, the viewer’s default and yours, so you can see at a glance what a new viewer will do:

pc.settings()

Every setting

Setting	Default	What it does
cmap	"gray"	Colormap. Any of "gray", "heat", "cool", "rainbow", "a", "b", "bb", "he", "i8", "aips0", "red", "green", "blue", "viridis", "magma", "inferno", "plasma", "cividis", "turbo", "cubehelix", "gist_heat", "gist_earth", "coolwarm", "RdBu_r", "seismic", "twilight", "nipy_spectral", "hsv".
invert	False	Invert the colormap.
scale	"linear"	Scale function. Any of "linear", "log", "pow", "sqrt", "squared", "asinh", "sinh", "histeq", "mtf".
limits	"zscale"	How the display limits are found: the data’s range, zscale, or a percentile. Any of "minmax", "zscale", "99.5", "99", "98", "95", "90".
zoom	"fit"; mosaics always fit	Zoom: “fit” the whole image in the view, or 1 data pixel per screen pixel, centered. Any of "fit", 1.
smooth_pixels	False	Zoomed in past one data pixel per screen pixel, blend between pixel centers instead of drawing square pixels; values and readouts stay the original pixels.
file_display	True	Open a file that suggests how to show it (a HiPS’s cut and stretch, color HiPS tiles as they are) that way, instead of by scale and limits.
auto	False	Auto enhance the image when it opens, instead of using scale and limits.
auto_sky_brightness	0.06	Auto enhance: the sky’s brightness as a fraction of white, 0.02 to 0.35. Takes a number.
auto_saturation	1.4	Auto enhance: color saturation of RGB and color mosaics, 0 to 2.5. Takes a number.
sky_format	"sexagesimal"	Sky coordinates in the readout. Any of "sexagesimal", "degrees".
region_coords	"sky"	Where regions say they are: on statistics cards, in the Regions panel and in coordinate labels. Any of "sky", "pixel", "off".
leader_lines	False: the card takes its region’s color	A line from each statistics card to its region.
sidebar	True	Show the side panel: panner, magnifier, histogram, info.
cuts	False in a notebook	Show the row and column cut plots.
link_scales	True	RGB: the scale function and limits start linked across the three channels.
mosaic_layout	"auto"	Mosaics: the layout when none is given; “auto” picks the HEALPix plane when every image is a HiPS of one sky frame, then sky when every image has a WCS. Any of "auto", "hpx", "sky", "focal", "grid".
outlines	True	Mosaics: outline and label each image.
flux_calibrate	True	Mosaics: show detectors still in DN/s in MJy/sr, each by its own calibration factor.
match_sky	"local"	Mosaics: shift each image’s values so the sky levels agree: each measured on its own (“local”), or compared where they overlap (“match”). Any of "off", "local", "match".
feather	0: the last drawn is on top	Mosaics: blend overlaps over this many pixels from each edge, 0 to 256. Takes a number.
trim_edges	0	Mosaics: leave out this many pixels at each image’s edges, 0 to 32. Display and export only. Takes a number.
live_reload	True	Reload when the file changes on disk.
online	True	Allow the SIMBAD lookup (right-click › What is this?) and the Aladin Lite panel, from the browser.
simbad_radius	0	Search radius of What is this?, in arcseconds; 0 follows the zoom. Takes a number.
survey	"CDS/P/DSS2/color"	The sky survey the Aladin Lite panel opens with. Any of "CDS/P/DSS2/color", "CDS/P/PanSTARRS/DR1/color-z-zg-g", "CDS/P/DESI-Legacy-Surveys/DR10/color", "CDS/P/SDSS9/color", "CDS/P/2MASS/color", "CDS/P/unWISE/color-W2-W1W2-W1", "CDS/P/GALEXGR6_7/color", "CDS/P/Mellinger/color".
overview_precision	"float16"	Precision of the reduced overview tiles sent to the page. ; full-resolution tiles are exact. Any of "float16", "float32".
tile_size	512	Tile edge in pixels. Any of 256, 512, 1024.

A few keywords aren’t settings, since they belong to one call rather than to every viewer: height, title, names, kind, layout, active, color, blink, groups, levels, plot, state, connection, anon and out_dir. The API reference describes each.