Color and stretch#
Astronomical images span a huge range of values: a faint galaxy’s outskirts may be a few counts above the sky, its core thousands. How those values become gray levels or colors on your screen decides what you can see. This page goes through the three choices involved (the scale function, the limits, and the colormap) and Auto enhance, which picks a stretch for you.
Each choice is a keyword of pc.show (and of pc.rgb, pc.mosaic, pc.stack, pc.blink and
pc.popup). They set how a view opens; the toolbar changes them afterwards, and the examples
below are live, so try the buttons on them too.
The examples use the sample star field with a galaxy, image.
The default#
With no options, the viewer uses a linear scale between the zscale limits. zscale picks limits
close around the sky’s level, which is ideal for faint stars and the noise, but anything much
brighter than the sky comes out white, so the galaxy’s core is burnt out:
import pixel_clarity as pc
pc.show(image)
Scale functions and limits#
The limits are the values that map to black and white. The scale is the curve between
them: linear, or one that spends more of the gray levels on faint values (log, sqrt,
asinh) or on bright ones (squared, sinh).
Keyword |
Values |
|---|---|
|
|
|
|
A percentile keeps that central share of the image’s values between black and white: "99.5"
sets the faintest 0.25% to black and the brightest 0.25% to white, so a few very bright pixels
don’t wash out the rest. asinh between the 99.5
percentile limits is a good general choice: it keeps the faint stars and the galaxy’s core both
in view.
pc.show(image, scale="asinh", limits="99.5", cmap="magma")
log over the whole range of the data (minmax) shows the galaxy’s disk well, at the cost of a
noisier sky:
pc.show(image, scale="log", limits="minmax", cmap="viridis")
histeq (histogram equalization) spreads the values evenly over the gray levels, so every part
of the image gets the same share of contrast. That makes structure easy to find, though the
brightness no longer means much. invert=True turns it around, black stars on white, the way
many finding charts are printed:
pc.show(image, scale="histeq", invert=True)
The low and high limits can also be typed into the toolbar, or dragged on the histogram in the side panel. The lock beside them keeps them as they are when you change slices, or when the file is rewritten and reloads.
Auto enhance#
auto=True picks the stretch from the image itself, in place of scale and limits. It sets
black just below the sky, lifts the faint parts and keeps the bright ones: a quick way to a good
picture. auto_sky_brightness (0.02 to 0.35, by default 0.06) sets how bright the sky comes
out; lower is darker.
pc.show(image, auto=True, auto_sky_brightness=0.04)
In the viewer, it’s the Auto button (or Shift+A). Its menu sets the same things by slider, and Revert goes back to the stretch you had before.
Colormaps#
cmap names the colormap. The perceptual maps (viridis, magma, inferno, plasma,
cividis) keep brightness increasing evenly, which matters when you are reading values off
colors. Diverging maps (coolwarm, RdBu_r, seismic) suit residuals and differences, centred
on zero.
"gray" (default), "viridis", "magma", "inferno", "plasma", "cividis", "turbo",
"cubehelix", "gist_heat", "gist_earth", "coolwarm", "RdBu_r", "seismic", "twilight",
"nipy_spectral", "hsv", "heat", "cool", "rainbow", "red", "green", "blue", "a",
"b", "bb", "he", "i8", "aips0".
Describing what you did#
When an image goes into a paper or a talk, you’ll want to say how it was stretched. Color settings… (the ⓘ beside the colorbar, or right-click) gives a one-paragraph description to copy into a caption or a methods section, then each channel’s limits, stretch and curve. Copy JSON gives the same as JSON for scripts, and every exported PNG carries it too.
Your defaults#
If you find yourself typing the same options every time, pc.save_defaults keeps them for
every new viewer, in later sessions too. Keywords given to a call still win.
pc.save_defaults(scale="asinh", limits="99.5", cmap="magma")
pc.reset_defaults() # back to the viewer's own
Settings and defaults has the details. For three filters combined into one color image, see Color images.