mBestImage

Description:

Given a list of images and a position on the sky, determine which image covers the location "best" (i.e., the one where the position is farthest from the nearest edge).

Syntax:

mBestImage [-d level] images.tbl ra dec

Switches:

-d debug

Turn on debugging to the specified level (1 or 2)

Arguments:

images.tbl

Input table of image metadata (as generated by mImgtbl).

ra

RA of location of interest (in degrees)

dec

Declination of location of interest (in degrees)

Results:

[struct stat="OK", file="filename", edgedist=distance]
or
[struct stat="OK", file="filename", url="fileurl", edgedist=distance]

where filename is the name of the "best" image found in images.tbl and distance is measured from the point of interest to the nearest edge of the image. If the input table included a URL column, the output message will also include the image's URL.

Examples:

Given a table of image metadata describing images covering a 0.5 by 0.5 degree area around m31 (2mass_m31_j.tbl), narrow it down to the image which includes the best coverage of one particular location:

mBestImage 2mass_m31_j.tbl 10.7 41.2

[struct stat="OK", file="2mass-atlas-971024n-j0080033.fits", edgedist=0.008436]

Return Codes:

• [struct stat="OK", file="filename", url="fileurl", edgedist=distance"]
• [struct stat="OK", file="filename", edgedist=distance"]
• [struct stat="ERROR", msg="Usage: BestImage [-d level] images.tbl ra dec"]
• [struct stat="ERROR", msg="Invalid image metadata file: images.tbl"]
• [struct stat="ERROR", msg="Need columns: cntr and fname; ctype1 ctype2 nl ns crval1 crval2 crpix1 crpix2 cdelt1 cdelt2 and crota2 or cd matrix / ra dec ra1 ... dec4"] (images.tbl missing required columns)
• [struct stat="ERROR", msg="Bad WCS for image fitsfile"] (Unable to determine position information for fitsfile)
• [struct stat="ERROR", msg="No image covers this position."]