From fa080de7afc95aa1c19a6e6fc0e0708ced2eadc4 Mon Sep 17 00:00:00 2001
From: Joseph Hunkeler <jhunkeler@gmail.com>
Date: Wed, 8 Jul 2015 20:46:52 -0400
Subject: Initial commit

---
 noao/astutil/doc/astradius.hlp | 138 +++++++++++++++++++++++++++++++++++++++++
 1 file changed, 138 insertions(+)
 create mode 100644 noao/astutil/doc/astradius.hlp

(limited to 'noao/astutil/doc/astradius.hlp')

diff --git a/noao/astutil/doc/astradius.hlp b/noao/astutil/doc/astradius.hlp
new file mode 100644
index 00000000..f19a47ec
--- /dev/null
+++ b/noao/astutil/doc/astradius.hlp
@@ -0,0 +1,138 @@
+.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
-- 
cgit 

