SurveyOverlay

2.1 Launching SurveyOverlay

Once installed, SurveyOverlay appears under the PROCESS > DeepSkyColors and PROCESS > Astrometry menus, and in the Process Explorer under the same categories. As with most processes, we open its interface, set its parameters, and apply it to a view: we drag the New Instance triangle onto the image, or click the Apply button to run it on the active view. SurveyOverlay works on one open image at a time. There is no file list and no batch mode.

The view can also be a preview. Only the area of the preview is fetched then, which is quicker, and is the natural way to look closely at one part of a large image.

The image must carry an astrometric solution, and the computer must be connected to the Internet. An image that has not been plate solved is refused with a message that says so, and nothing is downloaded.

2.2 Licensing

SurveyOverlay is free and fully functional. There is no trial period and nothing expires: every survey and every feature is available to everyone, forever.

The free version shows a small advertisement banner at the bottom of the interface, usually promoting other Deep Sky Colors tools for PixInsight. The banner is a single clickable image; it never interrupts our work and it makes no attempt to track us. If we click on the banner, SurveyOverlay opens our default browser with the direct destination link, without saving nor tracking any information about the click at all.

Registering SurveyOverlay removes the banner. To register, we click the wrench (Preferences) button on the process panel, enter the e-mail and license key from our purchase confirmation, and click Register. The banner disappears immediately and stays gone.

3.1 Choosing a survey

The Survey list holds the built-in surveys. The color surveys come first, each one marked Color:, and the single band surveys follow: optical, dust and gas, H-alpha, ultraviolet and infrared. Just below, a line of text says what the selected survey shows, how much of the sky it covers and how fine its detail is, which is usually all we need to decide whether it suits our image.

HiPS identifier is the name the survey has in the HiPS network, the system professional observatories use to publish their surveys. For a survey of the list it is there only to be read. The last entry of the list, Other, makes the field editable: we type the identifier of any other image survey, such as CDS/P/SDSS9/g, and press Enter. The full catalog, with several hundred surveys, can be browsed at aladin.cds.unistra.fr/hips/list.

The identifier is the process parameter (surveyId), so a saved process icon carries its survey with it, and a script can ask for any survey by name.

3.2 The built-in surveys

The color surveys are pictures made for the screen: already stretched, with 8 bits per channel. They come back as an RGB image that is good to look at and to compare with ours, and is not data to measure.

The single band surveys come back as a grayscale image that holds the survey's own values, which makes them the ones to use for anything beyond looking.

Coverage and resolution are those of each survey and are given as a guide. A survey that does not reach our field leaves it black, and SurveyOverlay reports how much of the image has no data.

3.3 The output options

Output says what SurveyOverlay makes:

• Pixel-matched image, the default: the survey as a new image with the size and geometry of ours, the same star on the same pixel, to compare with it or to blend.
• Context image: a wider piece of the survey, with our image itself on top of it, to see it in its surroundings. It is described in the next section.

A survey comes in its own units: megajanskys per steradian, Rayleighs, counts, magnitudes of reddening. Its values can be anything, negative ones included, while PixInsight works in the range from 0 to 1. With Rescale the survey values to the [0,1] range ticked, which is the default, the values are mapped linearly so that the lowest value in our field becomes 0 and the highest becomes 1. The two values are written to the keywords of the new image, SVOLOW and SVOHIGH, so the original units can always be recovered. A color survey is mapped from its 0 to 255 range instead, the same for the three channels, which keeps its color balance.

Unticked, the values are stored exactly as the survey gives them. This is the choice when we want to measure the survey, or to work on its real values with PixelMath.

Show the new image with an automatic screen stretch gives the new image a screen transfer function, so the survey is visible the moment it opens. Only the way it is displayed changes; its pixels stay as they are. A color survey is already stretched and gets none.

All three are process parameters as well (output, rescale and autoStretch).

3.4 The context image

The context image shows where our image sits on the sky, and what surrounds it. It is always 5000 by 5000 pixels, north up, centered on our image, and from 2 to 16 times as wide as its larger side, so it covers at least four times its area. Our image goes on top of the survey at its true place, size and rotation, placed there through its own astrometric solution.

The context is a stereographic projection, which keeps the shapes of the sky and stretches it little toward the edges, so even a very wide context looks right. It can be up to 180 degrees across, a whole hemisphere of sky.

Our image goes in as it is displayed: with its screen stretch applied, so a linear image looks the same in the context as it does on our screen. When the context has room for fewer pixels than our image has, our image is first reduced by averaging, which keeps it smooth. The context image is in color when either our image or the survey is; a grayscale one then fills the three channels.

The survey under it is always mapped to the range from 0 to 1, so Rescale does not apply to a context image. With Show the new image with an automatic screen stretch ticked, a single band survey is stretched in its pixels instead of on screen: a screen stretch of the whole context would stretch our image a second time. A color survey is used as it comes.

With Context image selected, a small button appears to the right of Output. It opens the options of the context image:

• Output: Composite, the default, makes one image with ours on top of the survey. Separate images makes two, on the same canvas and with the same astrometric solution: the survey alone, and our image alone, placed where it belongs, black around it. They are meant to be combined by hand, with LayerBlender or PixelMath; the mask separates them. Opacity and Blend do not apply to separate images.
• Width: how much sky the context covers, 2, 4, 8 or 16 times the larger side of our image. The context stays 5000 pixels across, so a wider one shows the surroundings in less detail, and our image in it gets smaller. A context that would be wider than 180 degrees is refused, with a message to choose a narrower one.
• Opacity: how much of our image shows over the survey, from 1, our image alone where it is, to 0, the survey alone.
• Blend: how our image combines with the survey under it. Normal puts it on top as it is; the other modes are the usual ones of image editors, the same as in LayerBlender, with the survey as the lower layer and our image as the upper one.
• Soft edge: a width in pixels of the context image over which our image fades in from its border. 0, the default, is a hard edge. A soft edge makes the blends look natural, and gives the mask a gentle border.
• Outline: a line just inside the border of our image, from 1 to 10 pixels of the context image wide, or none, to show exactly what our image covers. The swatch beside it sets its color. A colored outline makes the context image RGB even when the survey and our image are grayscale. With separate images, the outline goes on the image of ours.
• Create a mask of the image: also creates a mask the size of the context image, white where our image is and black on the survey, with the same soft edge. It separates the two, for instance to work on the survey or on our image alone.

OK keeps the new values and Cancel the old ones. They apply to the next context image, and stay as they are for the rest of the session. They are process parameters too (contextLayers, contextWidth, contextOpacity, contextBlend, contextFeather, contextOutline, contextOutlineColor and contextCreateMask), so a process icon carries them, and Reset brings back the defaults.

4.1 A typical session

The workflow is short:

• Open the image and make sure it is plate solved. If it is not, solve it first: with PixInsight's ImageSolver script, or with AstroResolver when we know nothing about the image but the name of an object in it.
• Open SurveyOverlay and choose a survey in the list.
• Apply it to the image, or to a preview of it.

SurveyOverlay works out which piece of the sky the image covers, downloads that piece of the survey and builds from it a new image with the size and geometry of ours. When it is done, the new image opens beside ours. It is named after both: Planck 857 GHz applied to an image called M31 gives M31_PLANCK_R2_HFI857, and M31_PLANCK_R2_HFI857_context for a context image. With separate images, our image alone is M31_PLANCK_R2_HFI857_context_image, and the mask, when we ask for one, is M31_PLANCK_R2_HFI857_context_mask.

Our own image is only read. It is not changed, and nothing is added to its processing history. We can apply one survey after another to the same image, and each gives its own new image.

4.2 While the survey arrives

A small progress window follows the work. Most of the time goes into the first step: the survey is not a file sitting on a server, and CDS has to build the image we asked for out of the tiles of the survey before it can send any of it. How long that takes grows with the number of pixels requested, which follows the size of our image.

A request larger than 1000 pixels on a side is split into tiles of up to 1000 pixels, and four of them are downloaded at the same time. Each tile is an exact piece of the image we asked for, so the tiles fit together with no seams. Four at a time makes a large request about four times quicker: a 5000-pixel color image that takes CDS three minutes in one piece arrives in under a minute as 25 tiles. The Process Console shows how the request was split.

CDS builds each tile before it sends any of it, so the tiles arrive in bursts, with pauses in between. The window has two rows. The first says how far the download is: Progress, with how many tiles have been received out of the total and the seconds gone. The second says what is happening: Waiting for CDS to build the survey tiles during a pause, Downloading the survey tiles while data come in. Until the first tile arrives, a block travels along the bar to show that the wait is alive; from then on the bar fills as the tiles arrive.

A request of up to 1000 pixels on a side is made in one piece. While CDS builds it, the first row shows the seconds gone, the second reads Waiting for CDS to build the survey image, and the block travels along the bar: nothing can tell us how far along CDS is, so the bar makes no claim about it. Such an image is usually built in a few seconds. Once it is built it is sent: the second row reads Downloading the survey image, and the first row and the bar show the megabytes received out of the total.

Tiles are downloaded with curl, the command line download tool that comes with Windows 10 and 11 and with macOS, and with nearly every Linux distribution. On a computer without it, every request is made in one piece, and a large one can take several minutes; the Process Console warns us before one starts.

The last step, the reprojection of the survey to the geometry of our image, takes a moment.

We can stop at any time with the Cancel button of the progress window, or by aborting the process from the Process Console. If the CDS server does not answer, or a tile fails, SurveyOverlay tries its mirror before it gives up.

4.3 Reading the results

SurveyOverlay reports what it does in the Process Console. Before the download we see the survey, the field it worked out from our astrometric solution (its center, its radius and the scale of our image in arcseconds per pixel) and the size and scale of the image it requests. After it, the name the survey gives itself and its copyright notice, when it has one. At the end, the name of the new image, the lowest and highest survey values found in the field, and the fraction of the image for which the survey has no data, if any.

The new image is a 32-bit floating point image of exactly the size of ours: grayscale for a single band survey, RGB for a color one. It carries:

• The astrometric solution of our image, so every astrometry-aware tool works on the survey as it does on ours. For a preview, the solution is rebuilt for the area the preview covers.
• Keywords that say where it comes from: SVOSURV holds the identifier of the survey, SVOLOW and SVOHIGH the survey values stored as 0 and 1 when the values were rescaled, and a few HISTORY lines record the image it was made for, the copyright of the survey and the acknowledgment CDS asks for.

Pixels the survey does not cover are black.

A context image is also a 32-bit floating point image, 5000 by 5000 pixels, in color when our image or the survey is. It has an astrometric solution of its own, stereographic, so astrometry-aware tools work on it as well, and it carries the same keywords, plus SVOMODE, which says what it is, SVOWIDTH, its width in times our image's, and for a composite SVOBLEND, SVOOPAC and SVOFEATH, the blend, opacity and soft edge it was made with. The console reports the size of the context, its scale at the center, these values and the outline, if any. With separate images, the image of ours has the same size, color space and astrometric solution as the survey, so the two combine directly. The mask, when we ask for one, is a grayscale image of the same size, with the same astrometric solution.

4.4 Putting the survey to work

Because the new image has exactly the geometry of ours, the two can be compared directly. The simplest way is to look at one and then the other at the same zoom. With LayerBlender we can stack the survey over our image and change its opacity or its blend mode, and PixelMath can combine the two pixel by pixel.

• Is it real? A faint cloud in our background that also shows in a dust map is galactic cirrus, and deserves to be kept. One that the survey does not have is a gradient, a flat field residue or a reflection.
• Before removing gradients. A dust or H-alpha map shows which parts of the field hold real signal and which are empty sky, which is what we need to know before we tell a background model where the background is.
• A second look at the object. The ultraviolet, the infrared or a deeper optical survey of our own field, at our own framing, often explains what our image shows.
• Where is it? A context image shows our field in its surroundings: the cloud it belongs to, the nebula just outside the frame, how a mosaic panel sits among its neighbors. A soft edge and a gentle blend make the two read as one picture.

A survey is a reference, not a second exposure of ours. Its resolution, its depth and the date it was taken differ from ours, and it has artifacts of its own: plate edges, satellite trails, ghosts around bright stars. What matters is the structure the two images share.