.help astradius Jan96 astutil
.ih
NAME
astradius -- find images within a circle on the sky
.ih
USAGE
astradius images racenter deccenter epcenter radius
.ih
PARAMETERS
.ls images
List of images for which the radius to a point on the sky is to be
determined.
.le
.ls 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.
.le
.ls radius
Search radius in arc seconds about the center position.
.le
.ls 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 \fBkeywpars\fR.
.le
.ls 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 \fBastcalc\fR.
Users may copy and modify this file if desired.
.le
.ih
DESCRIPTION
\fBAstradius\fR computes the spherical distance from a specified point on
the sky for each image in a list of images (\fIimages\fR).  The point on
the sky is specified by the parameters \fIracenter\fR, \fIdeccenter\fR, and
\fIepcenter\fR 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 (\fIradius\fR) 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 \fIkeywpars\fR parameter.
If no value is given then the parameters from the \fBkeywpars\fR
parameter set task are used.  The keywords required are those
select by the \fIkeywpars.ra\fR, \fIkeywpars.dec\fR, and
\fIkeywpars.epoch\fR.  If the epoch is absent or zero then the
keywords selected by \fIkeywpars.date_obs\fR and \fIkeywpars.ut\fR
are used to compute an epoch.

\fBAstradius\fR is a simple script which calls \fBastcalc\fR.  The
command file is specified by the parameter \fIcommands\fR.  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 \fBastcalc\fR.
.ih
EXAMPLES
1.  Page the script task and the command file.

.nf
    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
.fi

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

.nf
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
.fi
.ih
REVISIONS
.ls ASTRADIUS V2.11
This task is new in this release.
.le
.ih
SEE ALSO
astcalc, hselect
.endhelp
