Mosaics#

A camera with many detectors writes each one to a file of its own, and a survey cuts the sky into tiles. A mosaic shows them together as one image: placed by their sky coordinates, with their levels matched so the edges don’t show. It is an ordinary view: stretch, regions, the readout and exports all work across the whole mosaic.

The examples use tiles_r, four overlapping tiles cut from the sample field, each with a WCS and a slightly different sky level, as separate exposures would have.

Placing images on the sky#

pc.mosaic takes a list of files, a folder or a glob pattern. Images with a WCS are placed on a north-up plane by their sky coordinates. Hover anywhere for the value and the position, and the readout names the tile under the pointer.

import pixel_clarity as pc

pc.mosaic(tiles_r, scale="asinh", limits="99.5")

pc.show gives a mosaic too when it’s handed a folder, a pattern or a list:

pc.mosaic("exposure/")
pc.show("exposure/*_cal.fits")

Only the detectors in view are read at full resolution, so a mosaic of many large detectors opens as quickly as one of them.

Layouts#

layout decides where the images go:

layout

Places the images

"sky"

by their WCS, on a north-up plane (the default when every image has one)

"focal"

at their places in the instrument’s focal plane, for detectors the viewer knows

"grid"

side by side, in the order given

"pixel"

on top of each other, pixel for pixel

"hpx"

on the HEALPix plane (for HiPS of one sky frame)

Side by side is handy for comparing images that don’t overlap, or have no WCS. Here, with each tile named and their outlines off:

pc.mosaic(tiles_r, layout="grid", match_sky="off", outlines=False,
          names=["tile 1", "tile 2", "tile 3", "tile 4"])

Without level matching (match_sky="off"), you can see each tile’s own sky level.

Matching levels#

Separate exposures rarely have exactly the same background, so a mosaic shown as the files are shows its seams. The viewer evens them out for display, without changing the files:

  • match_sky shifts each image’s values so the sky levels agree. "local" (the default) measures each image’s sky on its own; "match" compares the images where they overlap, which is better when the field has extended emission; "off" shows the values as they are.

  • flux_calibrate (on by default) multiplies images still in count rates by their own calibration factor from their metadata, so a source is equally bright on every detector.

  • feather blends overlaps over this many pixels from each edge (0 to 256), weighted by each image’s noise, so seams fade instead of stepping.

  • trim_edges leaves out this many pixels at each image’s edge (0 to 32), for reference pixels or ragged borders.

Values in the readout and the region statistics stay those of one image; matching is for what you see and what you export.

pc.mosaic(tiles_r, match_sky="match", feather=40, trim_edges=4, scale="asinh", limits="99.5")

The Detectors panel#

A mosaic adds a Detectors panel to the side, listing every image. From it you can show and hide images, pick one (or click it on the image), and trim one by hand. An image that differs from the rest, such as a file from another exposure, is flagged there.

Save mosaic writes a .pcmosaic file that remembers the files, the layout and the level matching. Open it again with pc.show("field.pcmosaic") or pc.mosaic("field.pcmosaic"); it’s written next to the notebook (or to the viewer’s out_dir).

Starting on one image#

active picks the image that’s selected first (by its index in the list; a folder’s files are in name order), for the array picker and the Detectors panel:

pc.mosaic("exposure/", active=3)

Filters in color#

Tiles in two or more filters can be shown as one color mosaic, each filter in its own hue. That’s on the next page: Color images.