astradius: Find images within a circle on the sky

Package: astutil

Usage

astradius images racenter deccenter epcenter radius

Parameters

images: List of images for which the radius to a point on the sky is to be determined.

racenter, deccenter, epcenter: Right ascension in hours, declination in degrees, and epoch of a position on the sky to use as the center of a circle.

radius: Search radius in arc seconds about the center position.

keywpars = "" (pset): Parameter set defining the image header keywords. This task requires keywords for the right ascension, declination, and epoch. If there is no epoch in the image header keywords for the date of observation and the universal time are used for the epoch. The default parameter set (specified by the empty string) is keywpars.

commands = "astutil$astradius.dat": Command file used to compute the distance from the coordinate center and print a result if the distance is less than the specified radius. The command file uses the syntax described for astcalc. Users may copy and modify this file if desired.

Description

Astradius computes the spherical distance from a specified point on the sky for each image in a list of images (images). The point on the sky is specified by the parameters racenter, deccenter, and epcenter which give a right ascension in hours, a declination in degrees, and an epoch. Each image is required to have keywords for the right ascension (hours), declination (degrees), and epoch. However, if no epoch is defined in the image header then an epoch is computed from the observation date and universal time. The spherical distance is compared to a specified radius (radius) in arc seconds. If the distance is less than the radius the image name and title are printed.

The image header keywords giving the observation coordinates are defined by the parameter set selected with the keywpars parameter. If no value is given then the parameters from the keywpars parameter set task are used. The keywords required are those select by the keywpars.ra, keywpars.dec, and keywpars.epoch. If the epoch is absent or zero then the keywords selected by keywpars.date_obs and keywpars.ut are used to compute an epoch.

Astradius is a simple script which calls astcalc. The command file is specified by the parameter commands. The default file precesses the observation coordinates to the epoch of the search center coordinates and then computes the spherical distance between the search center and the observation. Finally it tests the distance against the specified radius and prints the image name and title if the observation is within the radius. Users may copy the default command file and modify it. The command syntax is described in the help for astcalc.

Examples

1. Page the script task and the command file.

cl> page astutil$astradius.cl,astutil$astradius.dat
# ASTRADIUS -- Find images within a radius.

procedure astradius (images, racenter, deccenter, epcenter, radius)

string  images = ""             {prompt="List of images"}
string  racenter = ""           {prompt="RA center (hours)"}
string  deccenter = ""          {prompt="DEC center (degrees)"}
real    epcenter = 2000.        {prompt="Epoch of center"}
real    radius = 60.            {prompt="Radius in arc seconds"}
pset    keywpars = ""           {prompt="Keywords for RA, DEC, EPOCH\n"}

file    commands = "astutil$astradius.dat"      {prompt="ASTCALC file"}

begin
        astcalc (commands=commands, images=images, table="", verbose=no)
end

 Print images which are within a given radius in the sky.

# Get parameters.
racenter = clget ("astradius.racenter")
deccenter = clget ("astradius.deccenter")
epcenter = clget ("astradius.epcenter")
radius = clget ("astradius.radius")
ra = imget(clget("keywpars.ra"))
dec = imget(clget("keywpars.dec"))

epoch = imget(clget("keywpars.epoch"))
if (str(epoch) == "" || real(epoch) == 0.)
    date = imget(clget("keywpars.date_obs"))
    ut = imget(clget("keywpars.ut"))
    epoch = epoch (date, ut)
endif

# Precess image coordinates to center epoch and compute separation.
radec = precess (ra, dec, epoch, epcenter)
ra1 = ra_precess (ra, dec, epoch, epcenter)
dec1 = dec_precess (ra, dec, epoch, epcenter)
sep = arcsep (racenter, deccenter, ra1, dec1)

# Print result if within radius.
if (sep < real (radius))
    printf ("%-15s %s\n", $I, imget ("title"))
endif

2. Find images within an arc minute of a particular position.

cl> astradius
List of images: *.imh
RA center (hours): 13:31
DEC center (degrees): 47:00
Epoch of center (2000.):
Radius in arc seconds (60.):
obj0020.imh         m51 B 600s
obj0021.imh         m51 V 600s
obj0022.imh         m51 R 600s

Revisions

ASTRADIUS V2.11: This task is new in this release.