---

5.1.1.3 Pixel information images ¶

In Keyword inspection and manipulation options like --pixelscale were introduced for information on the pixels from the keywords. But that only provides a single value for all the pixels! This will not be sufficient in some scenarios; for example due to distortion, different regions of the image will have different pixel areas when projected onto the sky.

The options in this section provide such “meta” images: images where the pixel values are information about the pixel itself. Such images can be useful in understanding the underlying pixel grid with the same tools that you study the astronomical objects within the image (like SAO DS9). After all, nothing beats visual inspection with tools you are familiar with.

--pixelareaonwcs

Create a meta-image where each pixel’s value shows its area in the WCS units (usually degrees squared). The output is therefore the same size as the input.

This option uses the same “pixel mixing” or “area resampling” concept that is described in Resampling (as part of the Warp program). Similar to Warp, its sampling can be tuned with the --edgesampling that is described below.

One scenario where this option becomes handy is when you are debugging aligned images using the Warp program (see Warp). You may observe gradients after warping and can check if they caused by the distortion of the instrument or not. Such gradients can happen due to distortions because the detectors pixels are measuring photons from different areas on the sky (or the type of projection you’re seeing). This effect is more pronounced in images covering larger portions of the sky, for instance, the TESS images¹³².

Here is an example usage of the --pixelareaonwcs option:

# Check the area each 'input.fits' pixel takes in sky
$ astfits input.fits -h1 --pixelareaonwcs -o pixarea.fits

# Convert each pixel's area to arcsec^2
$ astarithmetic pixarea.fits 3600 3600 x x \
                --output=pixarea_arcsec2.fits

# Compare area relative to the actual reported pixel scale
$ pixarea=$(astfits input.fits --pixelscale -q \
                    | awk '{print $3}')
$ astarithmetic pixarea.fits $pixarea / -o pixarea_rel.fits

--edgesampling=INT

Extra sampling along the pixel edges for --pixelareaonwcs. The default value is 0, meaning that only the pixel vertices are used. Values greater than zero improve the accuracy in the expense of greater time and memory consumption. With that said, the default value of zero usually has a good precision unless the given image has extreme distortions that produce irregular pixel shapes. For more, see Align pixels with WCS considering distortions).

Caution: This option does not “oversample” the output image! Rather, it makes Warp use more points to calculate the input pixel area. To oversample the output image, set a reasonable --cdelt value.