From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001
From: Joe Hunkeler <jhunkeler@gmail.com>
Date: Tue, 11 Aug 2015 16:51:37 -0400
Subject: Repatch (from linux) of OSX IRAF

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

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

diff --git a/noao/astutil/doc/setairmass.hlp b/noao/astutil/doc/setairmass.hlp
new file mode 100644
index 00000000..bbb1cbb8
--- /dev/null
+++ b/noao/astutil/doc/setairmass.hlp
@@ -0,0 +1,243 @@
+.help setairmass Nov00 astutil
+.ih
+NAME
+setairmass -- update image headers with the effective airmass 
+.ih
+USAGE
+setairmass images
+.ih
+PARAMETERS
+.ls images
+The list of images for which to calculate the airmass.  The image headers may
+optionally be updated with the airmass and the mid-UT of the exposure.
+.le
+.ls observatory = ")_.observatory"
+Observatory for which airmasses are to be computed if the observatory is not
+specified in the image header by the keyword OBSERVAT. The default is a
+redirection to look in the parameters for the parent package for a value. The
+observatory may be one of the observatories in the observatory database,
+"observatory" to select the observatory defined by the environment variable
+"observatory" or the parameter \fBobservatory.observatory\fR, or "obspars" to
+select the current parameters set in the \fBobservatory\fR task. See help for
+\fBobservatory\fR for additional information. If the input consists of images
+then the observatory is defined by the OBSERVAT keyword if present.
+.le
+.ls intype = "beginning"
+The time stamp of the observation as recorded at the telescope for the time
+dependent header keywords.  The choices are the "beginning", "middle" or "end"
+of the observation.
+.le
+.ls outtype = "effective"
+The output time stamp desired for the airmass. The choices are the "effective"
+airmass, or the airmass at the "beginning", "middle" or "end" of the
+observation.
+.le
+.ls ra = "ra"
+The name of the keyword that contains the right ascension. The right ascension
+is assumed to be in hours unless ra is one of the standard CRVALn keywords in
+which case it is assumed to be in degrees.
+.le
+.ls dec = "dec"
+The name of the keyword that contains the declination in degrees.
+.le
+.ls equinox = "epoch"
+The name of the keyword that contains the equinox of the right ascension and
+declination coordinates in years.
+.le
+.ls st = "st"
+The name of the keyword containing the sidereal time in hours. 
+.le
+.ls ut = "ut"
+The name of the keyword containing the ut time.  This keyword can either
+be in date plus time format or in hours.  Note that this allows setting
+both the "date-obs" and "ut".  If no time is found then
+a time of 0hrs is used.
+.le
+.ls date = "date-obs"
+The name of the keyword that contains the UT date of the observation. The
+format should be `DD/MM/YY' (old FITS format), YYYY-MM-DD (new FITS format),
+or YYYY-MM-DDTHH:MM:SS (new FITS format with time).  If there is a time
+and no time is found in the ut keyword then it is used for the ut.
+.le
+.ls exposure = "exptime"
+The name of the keyword that contains the exposure time (in seconds) of the
+image.
+.le
+.ls airmass = "airmass"
+The name of the output keyword that will receive the computed airmass.
+.le
+.ls utmiddle = "utmiddle"
+The name of the output keyword that will receive the universal time for
+the middle of the observation.  The format of the keyword will be the same
+as that specifying the universal time.
+.le
+.ls scale = 750.0
+The atmospheric scale height.
+.le
+.ls show = yes
+Print the airmasses and mid-UT's for each image?
+.le
+.ls update = yes
+Update the image headers with the airmasses and the mid-UT's?
+.le
+.ls override = yes
+If updating the image headers, override values that were previously recorded ?
+.le
+
+.ih
+DESCRIPTION
+
+SETAIRMASS will calculate the effective airmass of an astronomical image, as
+described below under "ALGORITHMS".  The task requires the instantaneous
+zenith distance at the beginning, middle and end of the exposure. These are
+calculated using the right ascension, declination, and equinox as well as the
+sidereal time, exposure time, UT date, and observatory from the image header.
+If the observatory is not available in the image header under the keyword
+OBSERVAT, the observatory is defined by the \fIobservatory\fR parameter. See
+help for \fIobservatory\fR for further information.
+
+The right ascension and declination will be precessed from the given equinox to
+the date of observation. The name of the right ascension, declination, equinox,
+sidereal time, ut time, exposure time, and date keywords can be specified as
+parameters. These keywords should express the right ascension in hours,
+the declination in degrees, the equinox in years, the sidereal time in hours,
+the universal time in hours, the exposure time in seconds, and the date in
+FITS format. If any of the required keywords are missing from the image
+headers, they can be added using the hedit or asthedit tasks.  Note that
+the universal time keyword may be in either a date plus time format or
+in hours and any output middle universal time will be in the same format.
+
+Before using this task, you will need to know the "time stamp" of the time
+varying header quantities (e.g. sidereal time).  Do the recorded values
+represent the beginning, the middle or the end of the exposure ? This should
+be set in the \fBintype\fR parameter.
+
+If for some reason the effective airmass is not desired, the value of the
+airmass at the beginning, middle or end of the exposure can be recorded in the
+header keyword specified by the \fIairmass\fR parameter. The \fBshow\fR
+parameter can be used to control the output to the terminal. The \fBupdate\fR
+and \fBoverride\fR parameters control the header keyword output.
+
+SETAIRMASS will also calculate the universal time of the middle of the exposure
+and place the value in the header keyword specified by the \fIutmiddle\fR
+parameter.  This assumes that the value for the UT is in the date keyword
+or ut keyword, with the same time stamp as the sidereal time. The
+mid-observation UT is useful for interpolating calibration arc dispersion
+solutions using REFSPECTRA, especially when the exposure time is
+long.
+
+.ih
+ALGORITHMS
+The mean airmass is calculated uses the formula described in "Some
+Factors Affecting the Accuracy of Stellar Photometry with CCDs" by P.
+Stetson, DAO preprint, September 1988.  This simple formula is:
+
+.nf
+	    AM (eff) = [AM (beginning) + 4*AM (middle) + AM (end)] / 6
+.fi
+
+and is derived by using Simpson's 1/3 rule to approximate the integral
+that represents the mean airmass.
+
+The beginning, middle and end airmasses are calculated using the
+relation between airmass and elevation (or zenith distance) in John
+Ball's book on Algorithms for the HP-45:
+
+.nf
+	    AM = sqrt (x**2 + 2*scale + 1) - x, where
+
+	     x = scale * sin(elevation) = scale * cos(ZD)
+.fi
+
+The atmospheric scaling parameter is \fIscale\fR (see "Astrophysical
+Quantities" by Allen, 1973 p.125,133).
+
+.ih
+KEYWORDS
+The input keywords are:
+.ls OBSERVAT
+Observatory at which the data was taken.  If absent the observatory is
+determined using the \fIobservatory\fR parameter.
+.le
+.ls \fIra\fR
+Right ascension in hours at the beginning, middle, or end of the observation.
+If ra is one of the CRVALn keywords it is assumed to be in degrees.
+.le
+.ls \fIdec\fR
+Declination in degrees at the beginning, middle, or end of the observation.
+.le
+.ls \fIequinox\fR
+The equinox of the coordinates.  The right ascension and declination will
+be precessed from this epoch to the date of the observation before being
+used.
+.le
+.ls \fIst\fR
+Sidereal time in hours at the beginning, middle, or end of the observation.
+.le
+.ls \fIut\fR
+Universal time in hours at the beginning, middle, or end of the observation.
+This may be in either date plus time format or just in hours.  
+.le
+.ls \fIdate\fR
+The value of the date parameter is the keyword name to be used for the date of
+the observation.  The date must be in either the old or new FITS format.
+.le
+.ls \fIexposure\fR
+The value of the exposure parameter is the keyword name to be used for the
+exposure time in seconds.
+.le
+
+The output keywords are:
+.ls \fIairmass\fR
+The value of the airmass parameter is the keyword name to be used for
+the computed airmass at either the beginning, middle, or end of the
+exposure, or for the weighted effective value over the exposure.
+.le
+.ls \fIutmiddle\fR
+The value of the utmiddle parameter is the keyword name to be used for
+the universal time at the middle of the exposure.
+.le
+
+.ih
+EXAMPLES
+
+1. Calculate the effective airmass of the IRAF test picture, dev$pix.
+
+.nf
+    cl> setairmass dev$pix exposure=itime update-
+.fi
+
+Note that the test picture does not have the correct coordinate epoch
+listed in its header, so no precession will be performed. 
+
+2. Calculate the effective airmass of the IRAF test picture dev$ypix in two
+ways.
+
+.nf
+    cl> setairmass dev$ypix exposure=itime update-
+
+    cl> setairmass dev$ypix ra=crval1 dec=crval2 equinox=equinox \
+        exposure=itime update-
+.fi
+
+Note the first way gives the same results as example 1. The second way
+uses the J2000 equatorial system rather then the ra and dec at the time
+of observation.
+
+.ih
+REVISIONS
+.ls SETAIRMASS V2.11.4
+The ut keyword now has precedence over any time in the date keyword
+and it can be either date plus time or hours.
+.le
+.ls SETAIRMASS V2.11.3
+The right ascension, declination, equinox, st, and ut keywords were made 
+parameters rather than being hard wired.
+.le
+.ls SETAIRMASS V2.11.2
+Y2K update: This task was updated to use the new FITS date format.
+.le
+.ih
+SEE ALSO
+airmass, hedit, refspectra, observatory
+.endhelp
-- 
cgit 

