frames.md

Frames, scales and zoom

Frames

atlas borrows DS9's frame concept: each loaded image lives in its own frame, and the display mode decides how frames appear on screen.

Mode	What you see	Shortcut
single	One frame at a time	Ctrl+1
tile	Every frame in a grid	Ctrl+2

Move between frames with Ctrl+] and Ctrl+[, or click a tile. Ctrl+W closes the current frame, and Frame → Delete All Frames clears the lot.

Set the starting mode from the command line or a configuration:

atlas *.fits --mode tile
atlas *.fits --mode tile --tile-columns 1

tile_columns fixes the width of the grid. Left unset (null), atlas picks a roughly square arrangement from however many frames are open, which is usually what you want; fixing it to 1 gives a single column, which is how the detector profile stacks a signal frame above its reset frame.

(zoom)=

Zoom

View → Zoom magnifies the current frame. Like the scale, the zoom belongs to the frame rather than to the window, so in tile mode one image can be zoomed into a corner while its neighbour still shows the whole field.

Command	What it does	Shortcut
Zoom In	Doubles the magnification	Ctrl++
Zoom Out	Halves it	Ctrl+-
Zoom to Fit	The whole frame in its tile, centred	Ctrl+0
Actual Pixels	One screen pixel per data pixel	Ctrl+9

The mouse does the same thing more directly: turn the wheel over the image to zoom about the pixel under the pointer, and drag with the left button to pan a frame that no longer fits in its tile.

Frames open fitted to their tile. A configuration can start them magnified instead, which saves repeating the same keystrokes every session on a detector nobody looks at whole:

display:
  zoom: 4.0      # 1.0 fits the frame to its tile

Every bundled profile sets it explicitly, so a profile copied as a starting point already has the key to edit. It is where new frames start, not a floor: Zoom to Fit still shows the whole frame.

A zoom survives everything that does not change the frame: resizing the window, tiling and untiling, switching scale, and the next image of a live stream, so a detector corner stays under the eye exposure after exposure.

Scales

View → Scale decides how pixel values map onto the brightness of the display. It is a property of the frame, not of the window, so in tile mode one image can be shown on a log scale beside another on a linear one.

Scale	What it does	Shortcut
linear	Brightness proportional to pixel value	Ctrl+3
log	Stretches the faint end, compresses the bright end	Ctrl+4

Both scales first map the frame's own minimum and maximum onto the full display range, so changing scale never clips a pixel that was visible before; it only redistributes contrast.

:::{note} Only the rendered pixmap changes. The raw data is left alone, so switching back and forth is lossless, and everything that reports numbers (the hover readout, the statistics panel, the histogram) keeps reporting detector counts rather than display brightness. :::

When to reach for log

A log scale earns its keep when one part of the frame is far brighter than the rest: a saturated star over a faint field, or a bright column in an otherwise flat bias. On a linear scale the bright feature takes the whole display range and everything else goes black. Note that this is about looking at the frame; if you want to see how the counts are actually distributed, the histogram is the better instrument, and it has its own independent log option for the count axis.