diff options
Diffstat (limited to 'pkg/xtools/skywcs/doc')
23 files changed, 1662 insertions, 0 deletions
diff --git a/pkg/xtools/skywcs/doc/README b/pkg/xtools/skywcs/doc/README new file mode 100644 index 00000000..b0998629 --- /dev/null +++ b/pkg/xtools/skywcs/doc/README @@ -0,0 +1,301 @@ + SKYWCS: The Sky Coordinates Package + +1. Introduction + + The skywcs package contains a simple set of routines for managing sky +coordinate information and for transforming from one sky coordinate system to +another. The sky coordinate system is defined either by a system name, e.g. +"J2000", "galactic", etc., or by an image system name, e.g. "dev$ypix" or +"dev$ypix world". + + The skywcs routine are layered on the Starlink Positional Astronomy library +SLALIB which is installed in the IRAF MATH package. Type "help slalib option= +sys" for more information about SLALIB. + + +2. The Interface Routines + +The package prefix is sk. The interface routines are listed below. + + stat = sk_decwcs (ccsystem, mw, coo, imcoo) + stat = sk_decwstr (ccsystem, coo, imcoo) + stat = sk_decim (im, wcs, mw, coo) + sk_enwcs (coo, ccsystem, maxch) + newcoo = sk_copy (coo) + sk_iiprint (label, imagesys, mw, coo) + sk_iiwrite (fd, label, imagesys, mw, coo) +[id]val = sk_stat[id] (coo, param) + sk_stats (coo, param, str, maxch) + sk_set[id] (coo, param, [id]val) + sk_sets (coo, param, str) + sk_ultran (incoo, outcoo, ilng, ilat, olng, olat, npts) + sk_lltran (incoo, outoo, ilng, ilat, ipmlng, ipmlat, px, rv, + olng, olat) + sk_equatorial (incoo, outcoo, ilng, ilat, ipmlng, ipmlat, px, + rv, olng, olat) + sk_saveim (coo, mw, im) + sk_close (coo) + + +3. Notes + + An "include <pkg/skywcs.h>" statement must appear in the calling program +to make the skywcs package parameter definitions visible to the calling +program. + + A "-lxtools -lslalib" must be included in the calling program link line +to link in the skywcs and the slalib routines. + + The sky coordinate descriptor is created with a call to one of the +sk_decwcs, sk_decwstr, or sk_imwcs routines. If the source of the sky +coordinate descriptor is an image then an IRAF MWCS descriptor will be returned +with the sky oordinate descriptor. The sky coordinate descriptor is freed with a +call to sk_close. A separate call to mw_close must be made to free the MWCS +descriptor if one was allocated. + + By default the main skywcs coordinate transformation routine sk_ultran +assumes that the input and output sky coordinates are in hours and degrees +if the input and output coordinate systems are equatorial, otherwise the +coordinates are assumed to be in degrees and degrees. The default input and +output sky coordinate units can be reset with calls to sk_seti. Two lower level +coordinate transformations for handling proper motions sk_lltran and +sk_equatorial are also available. These routines assume that the input and +output coordinates and proper motions are in radians. + + Calling programs working with both sky coordinate and MWCS descriptors +need to be aware that the MWCS routines assume that all sky coordinates +will be input and output in degrees and adjust their code accordingly. + + The skywcs routine sk_saveim can be used to update an image header. + + +3. Examples + +Example 1: Convert from B1950 coordinates to J2000 coordinates. + + include <skywcs.h> + + .... + + # Open input coordinate system. + instat = sk_decwstr ("B1950", incoo, NULL) + if (instat == ERR) { + call sk_close (incoo) + return + } + + # Open output coordinate system. + outstat = sk_decwstr ("J2000", outcoo, NULL) + if (outstat == ERR) { + call sk_close (outcoo) + return + } + + # Do the transformation assuming the input coordinates are in hours + # and degrees. The output coordinates will be in hours and degrees + # as well. + call sk_ultran (incoo, outcoo, rain, decin, raout, decout, npts) + + # Close the coordinate descriptors. + call sk_close (incoo) + call sk_close (outcoo) + + ... + + +Example 2: Repeat example 1 but convert to galactic coordinates. + + include <skywcs.h> + + .... + + # Open the input coordinate system. + instat = sk_decwstr ("B1950", incoo, NULL) + if (instat == ERR) { + call sk_close (incoo) + return + } + + # Open the output coordinate system. + outstat = sk_decwstr ("galactic", outcoo, NULL) + if (outstat == ERR) { + call sk_close (outcoo) + return + } + + # Dd the transformation assuming the input coordinates are in hours and + # degrees. The output coordinates will be in degrees and degrees. + call sk_ultran (incoo, outcoo, rain, decin, raout, decout, npts) + + # Close the coordinate descriptors. + call sk_close (incoo) + call sk_close (outcoo) + + ... + +Example 3: Convert a grid of pixel coordinates in the input image to the +equivalent pixel coordinate in the output image using the image world +coordinate systems to connect the two. + + include <skywcs.h> + + .... + + # Mwref will be defined because the input system is an image. + refstat = sk_decwcs ("refimage logical", mwref, refcoo, NULL) + if (refstat == ERR || mwref == NULL) { + if (mwref != NULL) + call mw_close (mwref) + call sk_close (refcoo) + return + } + + # Set the reference coordinate descriptor so it expects input in degrees + # and degrees. + call sk_seti (refcoo, S_NLNGUNUTS, SKY_DEGREES) + call sk_seti (refcoo, S_NLATUNUTS, SKY_DEGREES) + + # Mwout will be defined because the output system is an image. + outstat = sk_decwcs ("image logical", mwout, outcoo, NULL) + if (outstat == ERR || mwout == NULL) { + if (mwout != NULL) + call mw_close (mwout) + call sk_close (outcoo) + call mw_close (mwref) + call sk_close (refcoo) + return + } + + # Set the output coordinate descriptor so it will output coordinates + # in degrees and degrees. + call sk_seti (outcoo, S_NLNGUNUTS, SKY_DEGREES) + call sk_seti (outcoo, S_NLATUNUTS, SKY_DEGREES) + + # Compute pixel grid in refimage and store coordinate in the arrays + # xref and yref. + npts = 0 + do j = 1, IM_LEN(im,2), 100 { + do i = 1, IM_LEN(im,1), 100 { + npts = npts + 1 + xref[npts] = i + yref[npts] = j + } + } + + # Convert xref and yref to celestial coordinates raref and decref using + # mwref. The output coordinates will be in degrees and degrees. + ctref = mw_sctran (mwref, "logical", "world", 03B) + do i = 1, npts + call mw_c2trand (ctref, xref[i], yref[i], raref[i], decref[i]) + call ct_free (ctref) + + # Convert the reference celestial coordinates to the output celestial + # coordinate system using the coordinate descriptors. + call sk_ultran (refcoo, outcoo, raref, decref, raout, decout, npts) + + # Convert the output celestial coordinates to pixel coordinates in + # the other image using mwout. + ctout = mw_sctran (mwout, "world", "logical", 03B) + do i = 1, npts + call mw_c2trand (ctout, raout[i], decout[i], xout[i], yout[i]) + call ct_free (ctout) + + # Print the input and output pixel coordinates. + do i = 1, npts { + call printf ("%10.3f %10.3f %10.3f %10.3f\n") + call pargd (xref[i]) + call pargd (yref[i]) + call pargd (xout[i]) + call pargd (yout[i]) + } + + # Tidy up. + call mw_close (mwref) + call mw_close (mwout) + call sk_close (refcoo) + call sk_close (outcoo) + + +Example 4: Convert a 2D image with an J2000 tangent plane projection wcs to the +equivalent galactic wcs. The transformation requires a shift in origin and a +rotation. Assume that the ra axis is 1 and the dec axis is 2. The details of +how to compute the rotation are not shown here. See the imcctran task for +details. + + include <mwset.h> + include <skywcs.h> + + ... + + # Open image. + im = immap (image, READ_WRITE, 0) + + # Open the image coordinate system. + instat = sk_decim (im, "logical", mwin, cooin) + if (instat == ERR || mwin == NULL) { + ... + call sk_close (cooin) + ... + } + + # Get the dimensions of the mwcs descriptor. This should be 2. + ndim = mw_ndim (mwin, MW_NPHYSDIM) + + # Get the default coordinates to degrees and degreees. + call sk_seti (cooin, S_NLNGUNITS, SKY_DEGREES) + call sk_seti (cooin, S_NATGUNITS, SKY_DEGREES) + + # Open the output coordinate system. Mwout is NULL because this system + # is not an image. + outstat = sk_decwstr ("galactic", mwout, cooout, cooin) + if (outstat == ERR) { + ... + call sk_close (outstat) + ... + } + + # Make a copy of the mwcs descriptor. + mwout = mw_newcopy (mwin) + + # Allocate space for the r and w vectors and cd matrix. + call malloc (r, ndim, TY_DOUBLE) + call malloc (w, ndim, TY_DOUBLE) + call malloc (cd, ndim * ndim, TY_DOUBLE) + call malloc (newcd, ndim * ndim, TY_DOUBLE) + + # Assume for simplicty that the MWCS LTERM is the identify transform. + # so we don't have to worry about it. Get the WTERM which consists + # of r the reference point in pixels, w the reference point in degrees, + # and the cd matrix in degrees per pixel. + call mw_gwtermd (mwin, Memd[r], Memd[w], Memd[cd], ndim) + + # Convert the world coordinates zero point. The pixel zero point + # remains the same. + tilng = Memd[w] + tilat = Memd[w+1] + call sk_ultran (incoo, outcoo, tilng, tilat, tolng, tolat, 1) + Memd[w] = tolng + Memd[w+1] = tolat + + # Figure out how much to rotate the coordinate system and edit the + # compute a new CD matrix. Call it newcd. + ... + + # Enter the new CD matrix and zero point. + call mw_swterm (mwout, Memd[r], Memd[w], Memd[newcd], ndim) + + # Update the header. + call sk_saveim (cooout, mwout, im) + call mw_saveim (mwout, im) + ... + + # Tidy up. + call mfree (r, TY_DOUBLE) + call mfree (w, TY_DOUBLE) + call mfree (cd, TY_DOUBLE) + call mfree (newcd, TY_DOUBLE) + call mw_close (mwin) + call mw_close (mwout) + call sk_close (cooin) + call sk_close (cooout) + call imunmap (im) diff --git a/pkg/xtools/skywcs/doc/ccsystems.hlp b/pkg/xtools/skywcs/doc/ccsystems.hlp new file mode 100644 index 00000000..63a2fde6 --- /dev/null +++ b/pkg/xtools/skywcs/doc/ccsystems.hlp @@ -0,0 +1,134 @@ +.help ccsystems Mar00 Skywcs +.ih +NAME +ccsystems -- list and describe the supported sky coordinate systems +.ih +USAGE +help ccsystems + +.ih +SKY COORDINATE SYSTEMS + +The sky package supports the equatorial ("fk4", "fk4-noe", "fk5", "icrs"), +ecliptic, galactic, and supergalactic celestial coordinate systems. In most +cases and unless otherwise noted users can input their coordinates in +any one of these systems as long as they specify the coordinate system +correctly. + +Considerable flexibility is permitted in how the coordinate systems are +specified, e.g. J2000.0, j2000.0, 2000.0, fk5, fk5 J2000, and fk5 2000.0 +all specify the mean place post-IAU 1976 or FK5 system. Missing equinox and +epoch fields assume reasonable defaults. In most cases the +systems of most interest to users are "icrs", "j2000", and "b1950" +which stand for the ICRS J2000.0, FK5 J2000.0 and FK4 B1950.0 celestial +coordinate systems respectively. The full set of options are listed below: + +.ls equinox [epoch] +The equatorial mean place post-IAU 1976 (FK5) system if equinox is a +Julian epoch, e.g. J2000.0 or 2000.0, or the equatorial mean place +pre-IAU 1976 system (FK4) if equinox is a Besselian epoch, e.g. B1950.0 +or 1950.0. Julian equinoxes are prefixed by a J or j, Besselian equinoxes +by a B or b. Equinoxes without the J / j or B / b prefix are treated as +Besselian epochs if they are < 1984.0, Julian epochs if they are >= 1984.0. +Epoch is the epoch of the observation and may be a Julian +epoch, a Besselian epoch, or a Julian date. Julian epochs +are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to the epoch type of +equinox if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian date. If undefined epoch defaults to equinox. +.le +.ls icrs [equinox] [epoch] +The International Celestial Reference System where equinox is +a Julian or Besselian epoch e.g. J2000.0 or B1980.0. +Equinoxes without the J / j or B / b prefix are treated as Julian epochs. +The default value of equinox is J2000.0. +Epoch is a Besselian epoch, a Julian epoch, or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Julian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian date. If undefined epoch defaults to equinox. +.le +.ls fk5 [equinox] [epoch] +The equatorial mean place post-IAU 1976 (FK5) system where equinox is +a Julian or Besselian epoch e.g. J2000.0 or B1980.0. +Equinoxes without the J / j or B / b prefix are treated as Julian epochs. +The default value of equinox is J2000.0. +Epoch is a Besselian epoch, a Julian epoch, or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Julian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian date. If undefined epoch defaults to equinox. +.le +.ls fk4 [equinox] [epoch] +The equatorial mean place pre-IAU 1976 (FK4) system where equinox is a +Besselian or Julian epoch e.g. B1950.0 or J2000.0, +and epoch is the Besselian epoch, the Julian epoch, or the Julian date of the +observation. +Equinoxes without the J / j or B / b prefix are treated +as Besselian epochs. The default value of equinox is B1950.0. Epoch +is a Besselian epoch, a Julian epoch, or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Besselian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian date. If undefined epoch defaults to equinox. +.le +.ls noefk4 [equinox] [epoch] +The equatorial mean place pre-IAU 1976 (FK4) system but without the E-terms +where equinox is a Besselian or Julian epoch e.g. B1950.0 or J2000.0, +and epoch is the Besselian epoch, the Julian epoch, or the Julian date of the +observation. +Equinoxes without the J / j or B / b prefix are treated +as Besselian epochs. The default value of equinox is B1950.0. +Epoch is a Besselian epoch, a Julian epoch, or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Besselian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian day. If undefined epoch defaults to equinox. +.le +.ls apparent epoch +The equatorial geocentric apparent place post-IAU 1976 system where +epoch is the epoch of observation. +Epoch is a Besselian epoch, a Julian epoch or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Besselian +epochs if the epoch value < 1984.0, Julian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian date. +.le +.ls ecliptic epoch +The ecliptic coordinate system where epoch is the epoch of observation. +Epoch is a Besselian epoch, a Julian epoch, or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Besselian epochs +if the epoch values < 1984.0, Julian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian day. +.le +.ls galactic [epoch] +The IAU 1958 galactic coordinate system. +Epoch is a Besselian epoch, a Julian epoch or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Besselian +epochs if the epoch value < 1984.0, Julian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian date. The default value of epoch is B1950.0. +.le +.ls supergalactic [epoch] +The deVaucouleurs supergalactic coordinate system. +Epoch is a Besselian epoch, a Julian epoch or a Julian date. +Julian epochs are prefixed by a J or j, Besselian epochs by a B or b. +Epochs without the J / j or B / b prefix default to Besselian +epochs if the epoch value < 1984.0, Julian epochs +if the epoch value <= 3000.0, otherwise epoch is interpreted as +a Julian date. The default value of epoch is B1950.0. +.le + +Fields enclosed in [] are optional with the defaults as described. The epoch +field for the "icrs" , "fk5", "galactic", and "supergalactic" coordinate +systems is only used if the input coordinates are in the equatorial fk4, +noefk4, fk5, or icrs systems and proper motions are used to transform from +coordinate system to another. + +.ih +SEE ALSO +.endhelp diff --git a/pkg/xtools/skywcs/doc/skclose.hlp b/pkg/xtools/skywcs/doc/skclose.hlp new file mode 100644 index 00000000..191b08b5 --- /dev/null +++ b/pkg/xtools/skywcs/doc/skclose.hlp @@ -0,0 +1,23 @@ +.help skclose Mar00 Skywcs +.ih +NAME +skclose -- free the sky coordinate descriptor +.ih +SYNOPSIS +call sk_close (coo) + +.nf +pointer coo # the sky coordinate descriptor +.fi +.ih +ARGUMENTS +.ls coo +The sky coordinate descriptor to be freed. +.le +.ih +DESCRIPTION +Sk_close frees a previously allocated sky coordinate descriptor. +.ih +SEE ALSO +skdecwcs, skdecwstr, skdecim, skcopy +.endhelp diff --git a/pkg/xtools/skywcs/doc/skcopy.hlp b/pkg/xtools/skywcs/doc/skcopy.hlp new file mode 100644 index 00000000..68219c0d --- /dev/null +++ b/pkg/xtools/skywcs/doc/skcopy.hlp @@ -0,0 +1,24 @@ +.help skcopy Mar00 Skywcs +.ih +NAME +skcopy -- copy a sky coordinate descriptor +.ih +SYNOPSIS +newcoo = sk_copy (coo) + +.nf +pointer coo # the sky coordinate descriptor +.fi +.ih +ARGUMENTS +.ls coo +The sky coordinate descriptor to be copied. +.le +.ih +DESCRIPTION +Sk_copy is a pointer function which returns a copy of the input sky coordinate +descriptor as its function value. +.ih +SEE ALSO +skdecwcs, skdecwstr, skdecim, skclose +.endhelp diff --git a/pkg/xtools/skywcs/doc/skdecim.hlp b/pkg/xtools/skywcs/doc/skdecim.hlp new file mode 100644 index 00000000..6e570e47 --- /dev/null +++ b/pkg/xtools/skywcs/doc/skdecim.hlp @@ -0,0 +1,56 @@ +.help skdecim Mar00 Skywcs +.ih +NAME +skdecim -- open a sky coordinate descriptor using an image descriptor +.ih +SYNOPSIS +stat = sk_decim (im, mw, coo, imcoo) + +.nf +pointer im # the input image descriptor +pointer mw # the output mwcs descriptor +pointer coo # the output sky coordinate descriptor +pointer imcoo # the input image sky coordinate descriptor +.fi +.ih +ARGUMENTS +.ls im +The input image descriptor. +.le +.ls mw +The output mwcs descriptor. A NULL value for mw is returned if the image +world coordinate system cannot be read. +.le +.ls coo +The output sky coordinate descriptor. +.le +.ls imcoo +The parent image sky coordinate descriptor. Imcoo is set to NULL +except in cases where the sky coordinate descriptor for an image is +transformed and written back to the same image. +.le +.ih +DESCRIPTION +Sk_decim is an integer function which returns OK or ERR as its function +value. ERR is returned if a valid sky coordinate system cannot be opened, +OK otherwise. + +Sk_decim returns the image MWCS descriptor mw. The MWCS descriptor is used +to convert from pixel coordinates to world coordinates and vice versa. +The MWCS descriptor must be freed with a call to the MWCS routine +mw_close before task termination. + +Sk_decim returns the sky descriptor coo. The sky coordinate descriptor +is defined even if an error is detected in reading the image celestial +coordinate system, and must be freed with a call to sk_close before +task termination. + +.ih +NOTES +Type "help ccsystems" to see the list of the supported sky coordinate systems. + +Type "help mwcs$MWCS.hlp fi+" to find out more about the IRAF image world +coordinate system library MWCS. +SEE ALSO +skdecwcs, skdecwstr, skcopy, skclose +.endhelp diff --git a/pkg/xtools/skywcs/doc/skdecwcs.hlp b/pkg/xtools/skywcs/doc/skdecwcs.hlp new file mode 100644 index 00000000..2081fd50 --- /dev/null +++ b/pkg/xtools/skywcs/doc/skdecwcs.hlp @@ -0,0 +1,62 @@ +.help skdecwcs Mar00 Skywcs +.ih +NAME +skdecwcs -- open a sky coordinate descriptor using an image or system name +.ih +SYNOPSIS +stat = sk_decwcs (ccsystem, mw, coo, imcoo) + +.nf +char ccsystem # the input celestial coordinate system name +pointer mw # the output mwcs descriptor +pointer coo # the output sky coordinate descriptor +pointer imcoo # the input image sky coordinate descriptor +.fi +.ih +ARGUMENTS +.ls ccsystem. +The celestial coordinate system name. Ccsystem is a either an image system +name, e.g. "dev$ypix logical" or "dev$ypix world" or a system name, e.g. +"J2000" or "galactic". +.le +.ls mw +The output mwcs descriptor. A NULL value for mw is returned if the +image world coordinate system cannot be read or ccsystem is not an image +system name. +.le +.ls coo +The output sky coordinate descriptor. +.le +.ls imcoo +The parent image coordinate descriptor. Imcoo is set to NULL +except in cases where the sky coordinate descriptor for an image is +transformed and written back to the same image. +.le +.ih +DESCRIPTION +Sk_decwcs is an integer function which returns OK or ERR as its function +value. ERR is returned if a valid sky coordinate system cannot be opened, +OK otherwise. + +Sk_decwcs returns the image MWCS descriptor mw if ccsystem is an image +system, otherwise it returns NULL. The MWCS descriptor is used +to convert from pixel coordinates to world coordinates and vice versa. +The MWCS descriptor must be freed with a call to the MWCS routine +mw_close before task termination. + +Sk_decwcs returns the sky descriptor coo. The sky coordinate descriptor +is defined even if an error is detected in reading the image celestial +coordinate system, and must be freed with a call to sk_close before +task termination. + +.ih +NOTES +Type "help ccsystems" to see the list of the supported sky coordinate systems. + +Type "help mwcs$MWCS.hlp fi+" to find out more about the IRAF image world +coordinate system library MWCS. + + +SEE ALSO +skdecwstr, skdecim +.endhelp diff --git a/pkg/xtools/skywcs/doc/skdecwstr.hlp b/pkg/xtools/skywcs/doc/skdecwstr.hlp new file mode 100644 index 00000000..0edf7fa0 --- /dev/null +++ b/pkg/xtools/skywcs/doc/skdecwstr.hlp @@ -0,0 +1,46 @@ +.help skdecwstr Mar00 Skywcs +.ih +NAME +skdecwstr -- open a sky coordinate descriptor using a system name +.ih +SYNOPSIS +stat = sk_decwstr (csystem, coo, imcoo) + +.nf +char csystem # the input celestial coordinate system name +pointer coo # the output sky coordinate descriptor +pointer imcoo # the input image sky coordinate descriptor +.fi +.ih +ARGUMENTS +.ls csystem +The sky coordinates definition. Ccsystem is a system name, e.g. "J2000" +or "galactic". +.le +.ls coo +The output sky coordinate descriptor. +.le +.ls imcoo +The parent image coordinate descriptor. Imcoo is set to NULL +except in cases where the sky coordinate descriptor for an image is +transformed and written back to the same image. +.le +.ih +DESCRIPTION +Sk_decwstr is an integer function which returns OK or ERR as its function +value. ERR is returned if a valid sky coordinate system cannot be opened, +OK otherwise. + +Sk_decwstr returns the sky descriptor coo. The sky coordinate descriptor +is defined even if an error is detected in reading the image celestial +coordinate system, and must be freed with a call to sk_close before +task termination. + +.ih +NOTES + +Type "help ccsystems" to get a list of the supported sky coordinate systems. + +SEE ALSO +skdecwcs, skdecim, skcopy, skclose +.endhelp diff --git a/pkg/xtools/skywcs/doc/skenwcs.hlp b/pkg/xtools/skywcs/doc/skenwcs.hlp new file mode 100644 index 00000000..cc388108 --- /dev/null +++ b/pkg/xtools/skywcs/doc/skenwcs.hlp @@ -0,0 +1,32 @@ +.help skenwcs Mar00 Skywcs +.ih +NAME +skenwcs -- encode a system name using a sky coordinate descriptor +.ih +SYNOPSIS + +call sk_enwcs (coo, csystem, maxch) + +.nf +pointer coo # the input sky coordinate descriptor +char csystem # the output system name +int maxch # the maximum size of the output system name +.fi +.ih +ARGUMENTS +.ls coo +The input sky coordinate descriptor +.le +.ls csystem +The output system name, e.g. "galactic". +.le +.ls maxch +The maximum size of the output system name. +.le +.ih +DESCRIPTION +Sk_enwcs returns the sky coordinate system name. +.ih +SEE ALSO +skdecwcs, skdecwstr +.endhelp diff --git a/pkg/xtools/skywcs/doc/skequatorial.hlp b/pkg/xtools/skywcs/doc/skequatorial.hlp new file mode 100644 index 00000000..4500b881 --- /dev/null +++ b/pkg/xtools/skywcs/doc/skequatorial.hlp @@ -0,0 +1,58 @@ +.help skequatorial Mar00 Skywcs +.ih +NAME +skequatorial -- apply pm and transform between equatorial coordinate systems +.ih +SYNOPSIS +call sk_equatorial (incoo, outcoo, ilng, ilat, ipmlng, ipmlat, px, rv, + olng, olat) + +.nf +pointer incoo # the input sky coordinate descriptor +pointer outcoo # the output sky coordinate descriptor +double ilng, ilat # the input sky coordinates in radians +double ipmlng, ipmlat # the input proper motions in radians / year +double px # the input parallax in arcsec +double rv # the input radial velocity in km / sec (+ve receding) +double olng, olat # the output sky coordinates in radians +.fi +.ih +ARGUMENTS +.ls incoo +The input sky coordinate descriptor. +.le +.ls outcoo +The output sky coordinate descriptor. +.le +.ls ilng, ilat +The input sky coordinates in radians. +.le +.ls ipmlng, ipmlat +The input proper motions. If proper motions are unknown do not set ipmlng +and ipmlat to 0.0, use sk_ultran instead. Note that the ra proper motion +is in dra not cos (dec) * dra units. +.le +.ls px +The parallax in arcseconds. Use 0.0 if the proper motion is unknown unknown. +The parallax value is used only if proper motions are defined. +.le +.ls rv +The radial velocity in km / sec. Use 0.0 if the radial velocity is unknown. +The radial velocity value is used only if proper motions are defined. +.le +.ls olng, olat +The output sky coordinates in radians. +.le +.ih +DESCRIPTION +The coordinates in the input sky coordinate system are converted to +coordinates in the output sky coordinate system. +.ih +NOTES +If the proper motions are undefined use the routine sk_ultran. Zero valued +proper motions are not the same as undefined proper motions. + +.ih +SEE ALSO +sk_lltran, sk_ultran +.endhelp diff --git a/pkg/xtools/skywcs/doc/skiiprint.hlp b/pkg/xtools/skywcs/doc/skiiprint.hlp new file mode 100644 index 00000000..217819c2 --- /dev/null +++ b/pkg/xtools/skywcs/doc/skiiprint.hlp @@ -0,0 +1,39 @@ +.help skiiprint Mar00 Skywcs +.ih +NAME +skiiprint -- print the sky coordinate system summary +.ih +SYNOPSIS + +call sk_iprint (label, imagesys, mw, coo) + +.nf +char label # the input user label +char imagesys # the input image system +pointer mw # the input mwcs descriptor +pointer coo # the sky coordinate descriptor +.fi +.ih +ARGUMENTS +.ls label +The input user supplied label, e.g. "Input System", "Ref System", +"Output System" etc. +.le +.ls imagesys +The input image system, e.g. "dev$ypix logical", "dev$ypix world", etc. +.le +.ls mwcs +The input image mwcs descriptor if defined. If mwcs is defined then +information about which sky coordinate corresponds to which image +axis etc is read from the mwcs descriptor. +.le +.ls coo +The input sky coordinate descriptor. +.le +.ih +DESCRIPTION +A summary of the sky coordinate system is printed on the standard output. +.ih +SEE ALSO +skiiwrite +.endhelp diff --git a/pkg/xtools/skywcs/doc/skiiwrite.hlp b/pkg/xtools/skywcs/doc/skiiwrite.hlp new file mode 100644 index 00000000..c82472f4 --- /dev/null +++ b/pkg/xtools/skywcs/doc/skiiwrite.hlp @@ -0,0 +1,43 @@ +.help skiiwrite Mar00 Skywcs +.ih +NAME +skiiwrite -- write the sky coordinate system summary to a file +.ih +SYNOPSIS + +call sk_iiwrite (outfd, label, imagesys, mw, coo) + +.nf +int outfd # the input file descriptor +char label # the input user label +char imagesys # the input image system +pointer mw # the input mwcs descriptor +pointer coo # the sky coordinate descriptor +.fi +.ih +ARGUMENTS +.ls outfd +The input file descriptor. +.le +.ls label +The input user supplied label, e.g. "Input System", "Ref System", +"Output System" etc. +.le +.ls imagesys +The input image system, e.g. "dev$ypix logical", "dev$ypix world", etc. +.le +.ls mwcs +The input image mwcs descriptor if defined. If mwcs is defined then +information about which sky coordinate corresponds to which image +axis etc is read from the mwcs descriptor. +.le +.ls coo +The input sky coordinate descriptor. +.le +.ih +DESCRIPTION +A summary of the sky coordinate system is written to a file. +.ih +SEE ALSO +skiiprint +.endhelp diff --git a/pkg/xtools/skywcs/doc/sklltran.hlp b/pkg/xtools/skywcs/doc/sklltran.hlp new file mode 100644 index 00000000..b45f3ea4 --- /dev/null +++ b/pkg/xtools/skywcs/doc/sklltran.hlp @@ -0,0 +1,59 @@ +.help sklltran Mar00 Skywcs +.ih +NAME +sklltran -- apply pm and transform between coordinate systems +.ih +SYNOPSIS +call sk_lltran (incoo, outcoo, ilng, ilat, ipmlng, ipmlat, px, rv, olng, olat) + +.nf +pointer incoo # the input sky coordinate descriptor +pointer outcoo # the output sky coordinate descriptor +double ilng, ilat # the input sky coordinates in radians +double ipmlng, ipmlat # the input proper motions in radians / year +double px # the input parallax in arcsec +double rv # the input radial velocity in km / sec (+ve receding) +double olng, olat # the output sky coordinates in radians +.fi +.ih +ARGUMENTS +.ls incoo +The input sky coordinate descriptor. +.le +.ls outcoo +The output sky coordinate descriptor. +.le +.ls ilng, ilat +The input sky coordinates in radians. +.le +.ls ipmlng, ipmlat +The input proper motions. For these to be applied the input coordinate +system must be an equatorial coordinate system. If proper motions are +unknown do not set ipmlng and ipmlat to 0.0, use sk_ultran instead. Note that +the ra proper motion is in dra not cos (dec) * dra units. +.le +.ls px +The parallax in arcseconds. Use 0.0 if the proper motion is unknown unknown. +The parallax value is used only if proper motions are defined. +.le +.ls rv +The radial velocity in km / sec. Use 0.0 if the radial velocity is unknown. +The radial velocity value is used only if proper motions are defined. +.le +.ls olng, olat +The onput sky coordinates in radians. +.le + +.ih +DESCRIPTION +The coordinates in the input sky coordinate system are converted to +coordinates in the output sky coordinate system. +.ih +NOTES +If the proper motions are undefined use the routine sk_ultran. Zero valued +proper motions are not the same as undefined proper motions. + +.ih +SEE ALSO +sk_ultran, sk_equatorial +.endhelp diff --git a/pkg/xtools/skywcs/doc/sksaveim.hlp b/pkg/xtools/skywcs/doc/sksaveim.hlp new file mode 100644 index 00000000..82c16f3f --- /dev/null +++ b/pkg/xtools/skywcs/doc/sksaveim.hlp @@ -0,0 +1,39 @@ +.help sksaveim Mar00 Skywcs +.ih +NAME +sksaveim -- update the image header using a sky coordinate descriptor +.ih +SYNOPSIS +call sk_saveim (coo, mw, im) + +.nf +pointer coo # the input sky coordinate descriptor +pointer mw # the input mwcs descriptor +pointer im # the input image descriptor +.fi +.ih +ARGUMENTS +.ls coo +The input sky coordinate descriptor. +.le +.ls mw +The IRAF mwcs descriptor. +.le +.ls im +The input image descriptor. +.le +.ih +DESCRIPTION +The image world coordinate system is updated using information in +the sky coordinate descriptor and the mwcs descriptor. + +.ih +NOTES +Note that the sk_saveim call does not include a call to the MWCS mw_saveim +routine. This call must be made separately. + +Type "help mwcs$MWCS.hlp fi+" to find out more about the IRAF image world +coordinate system code. +SEE ALSO +skdecwcs, skdecim +.endhelp diff --git a/pkg/xtools/skywcs/doc/sksetd.hlp b/pkg/xtools/skywcs/doc/sksetd.hlp new file mode 100644 index 00000000..f518d71c --- /dev/null +++ b/pkg/xtools/skywcs/doc/sksetd.hlp @@ -0,0 +1,53 @@ +.help sksetd Mar00 Skywcs +.ih +NAME +sksetd -- set a double sky coordinate descriptor parameter +.ih +SYNOPSIS +include <skywcs.h> + +call sk_setd (coo, parameter, dval) + +.nf +pointer coo # the input sky coordinate descriptor +int parameter # the double parameter to be set +double dval # the value of the parameter to be set +.fi +.ih +ARGUMENTS +.ls coo +The sky coordinate descriptor. +.le +.ls parameter +The parameter to be set. The double parameter definitions in skywcs.h are: +.nf + S_VXOFF # the logical ra / longitude offset in pixels + S_VYOFF # the logical dec / latitude offset in pixels + S_VXSTEP # the logical ra / longitude step size in pixels + S_VYSTEP # the logical dec / latitude step size in pixels + S_EQUINOX # the equinox in years + S_EPOCH # the MJD of the observation +.fi +.le +.ls dval +The value of the parameter to be set. +.le +.ih +DESCRIPTION +Sk_setd sets the values of double sky coordinate descriptor parameters. +.ih +NOTES +The offsets and step sizes default to 0 and 1 for both axes. However +if the sky coordinate descriptor was derived from an input image section, e.g. +"dev$ypix[100:300,100:300]" these numbers may assume other values in some +circumstances. + +The equinox and epoch of observation are normally set by the calling program +when the sky coordinate descriptor is initialized, e.g. they default +to 2000.0 and 51544.50000 if the input coordinate system was "fk5". + +In most cases these parameters should not be set by the user. +.ih +SEE ALSO +skseti, sksets +.endhelp diff --git a/pkg/xtools/skywcs/doc/skseti.hlp b/pkg/xtools/skywcs/doc/skseti.hlp new file mode 100644 index 00000000..b08be476 --- /dev/null +++ b/pkg/xtools/skywcs/doc/skseti.hlp @@ -0,0 +1,93 @@ +.help skseti Mar00 Skywcs +.ih +NAME +skseti -- set an integer sky coordinate descriptor parameter +.ih +SYNOPSIS +include <skywcs.h> + +call sk_seti (coo, parameter, ival) + +.nf +pointer coo # the input sky coordinate descriptor +int parameter # the integer parameter to be set +int ival # the value of the parameter to be set +.fi +.ih +ARGUMENTS +.ls coo +The sky coordinate descriptor. +.le +.ls parameter +The parameter to be set. The double parameter definitions in skywcs.h are: +.nf + S_CTYPE # the celestial coordinate system type + S_RADECSYS # the equatorial system type + S_NLNGUNITS # the ra / longitude units + S_NLATUNITS # the dec/ latitude units + S_WTYPE # the projection type + S_PLNGAX # the physical ra / longitude axis + S_PLATAX # the physical dec / latitude axis + S_XLAX # the logical ra / longitude axis + S_YLAX # the logical dec / latitude axis + S_PIXTYPE # the IRAF pixel coordinate system type + S_NLNGAX # the length of ra / longitude axis + S_NLATAX # the length of dec / latitude axis + S_STATUS # the coordinate system status +.fi +.le +.ls ival +The value of the parameter to be set. +.le +.ih +DESCRIPTION +Sk_seti sets the values of integer sky coordinate descriptor parameters. +.ih +NOTES +Permitted values of S_CTYPE are CTYPE_EQUATORIAL, CTYPE_ECLIPTIC, +CTYPE_GALACTIC, and CTYPE_SUPERGALACTIC. The corresponding string dictionary +is CTYPE_LIST. + +Permitted types of S_RADECSYS are EQTYPE_FK4, EQTYPE_FK4NOE, +EQTYPE_FK5, EQTYPE, ICRS, and EQTYPE_GAPPT. The corresponding string +dictionary is EQTYPE_LIST. + +Permitted values of S_WTYPE are WTYPE_LIN, WTYPE_AZP, WTYPE_TAN, WTYPE_SIN, +WTYPE_STG, WTYPE_ARC, WTYPE_ZPN, WTYPE_ZEA, WTYPE_AIR, WTYPE_CYP, WTYPE_CAR, +WTYPE_MER, WTYPE_CEA, WTYPE_COP, WTYPE_COD, WTYPE_COE, WTYPE_COO, WTYPE_BON, +WTYPE_PCO, WTYPE_GLS, WTYPE_PAR, WTYPE_AIT, WTYPE_MOL, WTYPE_CSC, WTYPE_QSC, +WTYPE_TSC, WTYPE_TNX, WTYPE_ZPX. The corresponding string dictionary is +WTYPE_LIST. + +Permitted values of S_PIXTYPE are PIXTYPE_LOGICAL, PIXTYPE_TV, +PIXTYPE_PHYSICAL. and PIXTPE_WORLD. The corresponding string dictionary +is PIXTYPE_LIST. + +Permitted values of S_NLNGUNITS are SKY_HOURS, SKY_DEGREES, and SKY_RADIANS. +The corresponding string dictionary is SKY_LNG_UNITLIST. +Permitted values of S_NLATUNITS are SKY_DEGREES, and SKY_RADIANS. +The corresponding string dictionary is SKY_LAT_UNITLIST. + +The parameters S_CTYPE, S_RADECSYS, S_NLNGUNITS, and S_NLATUNITS are +important for all sky coordinate descriptors regardless of the source. +The parameters S_WTYPE, S_PLNGAX, S_PLATAX, S_XLAX, S_YLAX, S_PIXTYPE, +S_NLNGAX, and S_NLATAX are only important for sky coordinate descriptors +derived from an image sky coordinate systems. S_STATUS is OK if the sky +coordinate descriptor describes a valid celestial coordinate system, ERR +otherwise. + +In most cases these parameters should not be modified by the user. The +major exceptions are the units parameters S_NLNGUNITS and N_LATUNITS +which assumes default values fo hours and degrees for equatorial sky +coordinate systems and degrees and degrees for other sky coordinate systems. +If the user input and output units are different from the normal defaults +then the units parameters should be set appropriately. + +Parameters that occasionally need to be reset when a coordinate system +is created, edited, or saved to an image are S_WTYPE, S_PIXTYPE, S_PLNGAX, +and S_PLATAX. + +.ih +SEE ALSO +sksetd, sksets +.endhelp diff --git a/pkg/xtools/skywcs/doc/sksets.hlp b/pkg/xtools/skywcs/doc/sksets.hlp new file mode 100644 index 00000000..8e4179b4 --- /dev/null +++ b/pkg/xtools/skywcs/doc/sksets.hlp @@ -0,0 +1,36 @@ +.help sksets Mar00 Skywcs +.ih +NAME +sksets -- set a string sky coordinate descriptor parameter +.ih +SYNOPSIS +include <skywcs.h> + +call sk_sets (coo, parameter, str) + +.nf +pointer coo # the input sky coordinate descriptor +int parameter # the string parameter to be set +char str # the value of the string parameter to be set +.fi +.ih +ARGUMENTS +.ls coo +The sky coordinate descriptor. +.le +.ls parameter +The parameter to be set. The string parameter definitions in skywcs.h are: +.nf + S_COOSYSTEM # the celestial coordinate system name +.fi +.le +.ls str +The value of the parameter to be set. +.le +.ih +DESCRIPTION +Sk_sets sets the values of string sky coordinate descriptor parameters. +.ih +SEE ALSO +sksetd, skseti +.endhelp diff --git a/pkg/xtools/skywcs/doc/skstatd.hlp b/pkg/xtools/skywcs/doc/skstatd.hlp new file mode 100644 index 00000000..52dc0c70 --- /dev/null +++ b/pkg/xtools/skywcs/doc/skstatd.hlp @@ -0,0 +1,49 @@ +.help skstatd Mar00 Skywcs +.ih +NAME +skstatd -- get a double sky coordinate descriptor parameter +.ih +SYNOPSIS +include <skywcs.h> + +dval = sk_statd (coo, parameter) + +.nf +pointer coo # the input sky coordinate descriptor +int parameter # the double parameter to be returned +.fi +.ih +ARGUMENTS +.ls coo +The sky coordinate descriptor. +.le +.ls parameter +The oarameter to be returned. The double parameter definitions in skywcs.h are: +.nf + S_VXOFF # the logical ra / longitude offset in pixels + S_VYOFF # the logical dec / latitude offset in pixels + S_VXSTEP # the logical ra / longitude step size in pixels + S_VYSTEP # the logical dec / latitude step size in pixels + S_EQUINOX # the equinox in years + S_EPOCH # the MJD of the observation +.fi +.le +.ih +DESCRIPTION +Sk_statd returns the values of double sky coordinate descriptor parameters. + +.ih +NOTES +The offsets and step sizes default to 0 and 1 for both axes. However +if the sky coordinate descriptor was derived from an input image section, e.g. +"dev$ypix[100:300,100:300]" these numbers may assume other values in some +circumstances. + +The equinox and epoch of observation are normally set by the calling program +when the sky coordinate descriptor is initialized, e.g. they default +to 2000.0 and 51544.50000 if the input coordinate system was "fk5". + +.ih +SEE ALSO +skstati, skstats +.endhelp diff --git a/pkg/xtools/skywcs/doc/skstati.hlp b/pkg/xtools/skywcs/doc/skstati.hlp new file mode 100644 index 00000000..90d33eb1 --- /dev/null +++ b/pkg/xtools/skywcs/doc/skstati.hlp @@ -0,0 +1,79 @@ +.help skstati Mar00 Skywcs +.ih +NAME +skstati -- get an integer sky coordinate descriptor parameter +.ih +SYNOPSIS +include <skywcs.h> + +ival = sk_stati (coo, parameter) + +.nf +pointer coo # the input sky coordinate descriptor +int parameter # the integer parameter to be returned +.fi +.ih +ARGUMENTS +.ls coo +The sky coordinate descriptor. +.le +.ls parameter +Parameter to be returned. The integer parameter definitions in skywcs.h are: +.nf + S_CTYPE # the celestial coordinate system type + S_RADECSYS # the equatorial system type + S_NLNGUNITS # the ra / longitude units + S_NLATUNITS # the dec/ latitude units + S_WTYPE # the projection type + S_PLNGAX # the physical ra / longitude axis + S_PLATAX # the physical dec / latitude axis + S_XLAX # the logical ra / longitude axis + S_YLAX # the logical dec / latitude axis + S_PIXTYPE # the IRAF pixel coordinate system type + S_NLNGAX # the length of the ra / longitude axis + S_NLATAX # the length of the dec / latitude axis + S_STATUS # the coordinate system status +.fi +.le +.ih +DESCRIPTION +Sk_stati returns the values of integer sky coordinate descriptor parameters. + +.ih +NOTES +Permitted values of S_CTYPE are CTYPE_EQUATORIAL, CTYPE_ECLIPTIC, +CTYPE_GALACTIC, and CTYPE_SUPERGALACTIC. The corresponding string dictionary +is CTYPE_LIST. + +Permitted types of S_RADECSYS are EQTYPE_FK4, EQTYPE_FK4NOE, +EQTYPE_FK5, EQTYPE, ICRS, and EQTYPE_GAPPT. The corresponding string +dictionary is EQTYPE_LIST. + +Permitted values of S_WTYPE are WTYPE_LIN, WTYPE_AZP, WTYPE_TAN, WTYPE_SIN, +WTYPE_STG, WTYPE_ARC, WTYPE_ZPN, WTYPE_ZEA, WTYPE_AIR, WTYPE_CYP, WTYPE_CAR, +WTYPE_MER, WTYPE_CEA, WTYPE_COP, WTYPE_COD, WTYPE_COE, WTYPE_COO, WTYPE_BON, +WTYPE_PCO, WTYPE_GLS, WTYPE_PAR, WTYPE_AIT, WTYPE_MOL, WTYPE_CSC, WTYPE_QSC, +WTYPE_TSC, WTYPE_TNX, WTYPE_ZPX. The corresponding string dictionary is +WTYPE_LIST. + +Permitted values of S_PIXTYPE are PIXTYPE_LOGICAL, PIXTYPE_TV, +PIXTYPE_PHYSICAL. and PIXTPE_WORLD. The corresponding string dictionary +is PIXTYPE_LIST. + +Permitted values of S_NLNGUNITS are SKY_HOURS, SKY_DEGREES, and SKY_RADIANS. +The corresponding string dictionary is SKY_LNG_UNITLIST. +Permitted values of S_NLATUNITS are SKY_DEGREES, and SKY_RADIANS. +The corresponding string dictionary is SKY_LAT_UNITLIST. + +The parameters S_CTYPE, S_RADECSYS, S_NLNGUNITS, and S_NLATUNITS are +important for all sky coordinate descriptors regardless of the source. +The parameters S_WTYPE, S_PLNGAX, S_PLATAX, S_XLAX, S_YLAX, S_PIXTYPE, +S_NLNGAX, and S_NLATAX are only important for sky coordinate descriptors +derived from an image sky coordinate systems. S_STATUS is OK if the sky +coordinate descriptor describes a valid celestial coordinate system, ERR +otherwise. + +.ih +SEE ALSO +skstatd, skstats +.endhelp diff --git a/pkg/xtools/skywcs/doc/skstats.hlp b/pkg/xtools/skywcs/doc/skstats.hlp new file mode 100644 index 00000000..483ed3e5 --- /dev/null +++ b/pkg/xtools/skywcs/doc/skstats.hlp @@ -0,0 +1,40 @@ +.help skstats Mar00 Skywcs +.ih +NAME +skstats -- get a string sky coordinate descriptor parameter +.ih +SYNOPSIS +include <skywcs.h> + +call sk_stats (coo, parameter, str, maxch) + +.nf +pointer coo # the input sky coordinate descriptor +int parameter # the string parameter to be returned +char str # the returned string parameter value +int maxch # the maximum size of the returned string parameter +.fi +.ih +ARGUMENTS +.ls coo +The sky coordinate descriptor. +.le +.ls parameter +The parameter to be returned. The string parameter definitions in skywcs.h are: +.nf + S_COOSYSTEM # the celestial coordinate system name +.fi +.le +.ls str +The value of the returned string. +.le +.ls maxch +The maximum size of the returned string. +.le +.ih +DESCRIPTION +Sk_stats returns the values of string sky coordinate descriptor parameters. +.ih +SEE ALSO +skstati, skstatd +.endhelp diff --git a/pkg/xtools/skywcs/doc/skultran.hlp b/pkg/xtools/skywcs/doc/skultran.hlp new file mode 100644 index 00000000..ca02385e --- /dev/null +++ b/pkg/xtools/skywcs/doc/skultran.hlp @@ -0,0 +1,50 @@ +.help skultran Mar00 Skywcs +.ih +NAME +skultran -- transform between coordinate systems +.ih +SYNOPSIS +call sk_ultran (incoo, outcoo, ilng, ilat, olng, olat, npts) + +.nf +pointer incoo # the input sky coordinate descriptor +pointer outcoo # the output sky coordinate descriptor +double ilng, ilat # the input celestial coordinates in expected units +double olng, olat # the output celestial coordinates in expected units +int npts # the number of input and output coordinate pairs +.fi +.ih +ARGUMENTS +.ls incoo +The input sky coordinate descriptor. +.le +.ls outcoo +The output sky coordinate descriptor. +.le +.ls ilng, ilat +The input sky coordinates in the units defined by the integer parameters +S_NLNGUNITS and S_NLATUNITS. +.le +.ls olng, olat +The output sky coordinates in the units defined by the integer parameters +S_NLNGUNITS and S_NLATUNITS. +.le +.ls npts +The number of input and output coordinate pairs. +.le +.ih +DESCRIPTION +The coordinates in the input coordinate system are converted to +coordinates in the output coordinates system. + +If the calling program has not set the S_NLNGUNITS and S_NLATUNITS parameters +in either system the expected coordinates are hours and degrees for +equatorial sky coordinate systems and degrees and degrees for other sky +coordinate systems. The calling program must either perform the necessary +coordinate conversions or set the units parameters in the input and output +sky coordinate descriptors appropriately. + +.ih +SEE ALSO +sk_lltran, sk_equatorial +.endhelp diff --git a/pkg/xtools/skywcs/doc/skywcs.hd b/pkg/xtools/skywcs/doc/skywcs.hd new file mode 100644 index 00000000..74bac140 --- /dev/null +++ b/pkg/xtools/skywcs/doc/skywcs.hd @@ -0,0 +1,25 @@ +# Help directory for the SKYWCS library + +$doc = "./" +$source = "../" + +skdecwcs hlp=doc$skdecwcs.hlp, src=source$skdecode.x +skdecwstr hlp=doc$skdecwstr.hlp, src=source$skdecode.x +skdecim hlp=doc$skdecim.hlp, src=source$skdecode.x +skenwcs hlp=doc$skenwcs.hlp, src=source$skdecode.x +skcopy hlp=doc$skcopy.hlp, src=source$skdecode.x +skiiprint hlp=doc$skiiprint.hlp, src=source$skwrite.x +skiiwrite hlp=doc$skiiwrite.hlp, src=source$skwrite.x +skstati hlp=doc$skstati.hlp, src=source$skstat.x +skstatd hlp=doc$skstatd.hlp, src=source$skstat.x +skstats hlp=doc$skstats.hlp, src=source$skstat.x +skseti hlp=doc$skseti.hlp, src=source$skset.x +sksetd hlp=doc$sksetd.hlp, src=source$skset.x +sksets hlp=doc$sksets.hlp, src=source$skset.x +skultran hlp=doc$skultran.hlp, src=source$skytransform.x +sklltran hlp=doc$sklltran.hlp, src=source$skytransform.x +skequatorial hlp=doc$skequatorial.hlp, src=source$skytransform.x +sksaveim hlp=doc$sksaveim.hlp, src=source$sksaveim.x +skclose hlp=doc$skclose.hlp, src=source$skdecode.x + +ccsystems hlp=doc$ccsystems.hlp diff --git a/pkg/xtools/skywcs/doc/skywcs.hlp b/pkg/xtools/skywcs/doc/skywcs.hlp new file mode 100644 index 00000000..d02f4d2f --- /dev/null +++ b/pkg/xtools/skywcs/doc/skywcs.hlp @@ -0,0 +1,306 @@ +.help skywcs Oct00 xtools +.ih +NAME +skywcs -- sky coordinates package +.ih +SYNOPSIS + +.nf + stat = sk_decwcs (ccsystem, mw, coo, imcoo) + stat = sk_decwstr (ccsystem, coo, imcoo) + stat = sk_decim (im, wcs, mw, coo) + sk_enwcs (coo, ccsystem, maxch) + newcoo = sk_copy (coo) + sk_iiprint (label, imagesys, mw, coo) + sk_iiwrite (fd, label, imagesys, mw, coo) +[id]val = sk_stat[id] (coo, param) + sk_stats (coo, param, str, maxch) + sk_set[id] (coo, param, [id]val) + sk_sets (coo, param, str) + sk_ultran (incoo, outcoo, ilng, ilat, olng, olat, npts) + sk_lltran (incoo, outoo, ilng, ilat, ipmlng, ipmlat, px, rv, + olng, olat) + sk_equatorial (incoo, outcoo, ilng, ilat, ipmlng, ipmlat, px, + rv, olng, olat) + sk_saveim (coo, mw, im) + sk_close (coo) + +.fi +.ih +DESCRIPTION + +The skywcs package contains a simple set of routines for managing +sky coordinate information and for transforming from one sky coordinate +system to another. The sky coordinate system is defined either by a system +name, e.g. "J2000", "galactic", etc. or by an image system name, e.g. +"dev$ypix" or "dev$ypix world". + +The skywcs routine are layered on the Starlink Positional Astronomy library +SLALIB which is installed in the IRAF MATH package. Type "help slalib +option=sys" for more information about SLALIB. + + +.ih +NOTES + +An "include <skywcs.h>" statement must be included in the calling program +to make the skywcs package parameter definitions visible to the calling +program. + +The sky coordinate descriptor is created with a call to one of the sk_decwcs +sk_decwstr or sk_imwcs routines. If the source of sky coordinate descriptor +is an image then an IRAF MWCS descriptor will be returned with the sky +oordinate descriptor. The sky coordinate descriptor is freed with a +call to sk_close. A separate call to mw_close must be made to free the +MWCS descriptor if one was allocated. + +By default the main skywcs coordinate transformation routine sk_ultran +assumes that the input and output sky coordinates are in hours and degrees +if the input and output coordinate systems are equatorial, otherwise the +coordinates are assumed to be in degrees and degrees. The default input and +output sky coordinate units can be reset with calls to sk_seti. Two lower level +coordinate transformations for handling proper motions sk_lltran and +sk_equatorial are also available. These routines expect the input and output +coordinates and proper motions to be in radians. + +Calling programs working with both sky coordinate and MWCS descriptors +need to be aware that the MWCS routines assume that all sky coordinates +must be input in degrees and will be output in degrees and adjust their +code accordingly. + +The skywcs routine sk_saveim can be used to update an image header. + + +.ih +EXAMPLES +.nf +Example 1: Convert from B1950 coordinates to J2000 coordinates. + + include <skywcs.h> + + .... + + # Open input coordinate system. + instat = sk_decwstr ("B1950", incoo, NULL) + if (instat == ERR) { + call sk_close (incoo) + return + } + + # Open output coordinate system. + outstat = sk_decwstr ("J2000", outcoo, NULL) + if (outstat == ERR) { + call sk_close (outcoo) + return + } + + # Do the transformation assuming the input coordinates are in hours + # and degrees. The output coordinates will be in hours and degrees + # as well. + call sk_ultran (incoo, outcoo, rain, decin, raout, decout, npts) + + # Close the coordinate descriptors. + call sk_close (incoo) + call sk_close (outcoo) + + ... + + +Example 2: Repeat example 1 but convert to galactic coordinates. + + include <skywcs.h> + + .... + + # Open the input coordinate system. + instat = sk_decwstr ("B1950", incoo, NULL) + if (instat == ERR) { + call sk_close (incoo) + return + } + + # Open the output coordinate system. + outstat = sk_decwstr ("galactic", outcoo, NULL) + if (outstat == ERR) { + call sk_close (outcoo) + return + } + + # Do the transformation assuming the input coordinates are in hours and + # degrees. The output coordinates will be in degrees and degrees. + call sk_ultran (incoo, outcoo, rain, decin, raout, decout, npts) + + # Close the coordinate descriptors. + call sk_close (incoo) + call sk_close (outcoo) + + ... + +Example 3: Convert a grid of pixel coordinates in the input image to the + equivalent pixel coordinate in the output image using the + image world coordinate systems to connect the two. + + include <skywcs.h> + + .... + + # Mwref will be defined because the input system is an image. + refstat = sk_decwcs ("refimage logical", mwref, refcoo, NULL) + if (refstat == ERR || mwref == NULL) { + if (mwref != NULL) + call mw_close (mwref) + call sk_close (refcoo) + return + } + + # Set the reference coordinate descriptor so it expects input in degrees + # and degrees. + call sk_seti (refcoo, S_NLNGUNUTS, SKY_DEGREES) + call sk_seti (refcoo, S_NLATUNUTS, SKY_DEGREES) + + # Mwout will be defined because the output system is an image. + outstat = sk_decwcs ("image logical", mwout, outcoo, NULL) + if (outstat == ERR || mwout == NULL) { + if (mwout != NULL) + call mw_close (mwout) + call sk_close (outcoo) + call mw_close (mwref) + call sk_close (refcoo) + return + } + + # Set the output coordinate descriptor so it will output coordinates + # in degrees and degrees. + call sk_seti (outcoo, S_NLNGUNUTS, SKY_DEGREES) + call sk_seti (outcoo, S_NLATUNUTS, SKY_DEGREES) + + # Compute pixel grid in refimage and store coordinate in the arrays + # xref and yref. + npts = 0 + do j = 1, IM_LEN(im,2), 100 { + do i = 1, IM_LEN(im,1), 100 { + npts = npts + 1 + xref[npts] = i + yref[npts] = j + } + } + + # Convert xref and yref to celestial coordinates raref and decref using + # mwref. The output coordinates will be in degrees and degrees. + ctref = mw_sctran (mwref, "logical", "world", 03B) + do i = 1, npts + call mw_c2trand (ctref, xref[i], yref[i], raref[i], decref[i]) + call ct_free (ctref) + + # Convert the reference celestial coordinates to the output celestial + # coordinate system using the coordinate descriptors. + call sk_ultran (refcoo, outcoo, raref, decref, raout, decout, npts) + + # Convert the output celestial coordinates to pixel coordinates in + # the other image using mwout. + ctout = mw_sctran (mwout, "world", "logical", 03B) + do i = 1, npts + call mw_c2trand (ctout, raout[i], decout[i], xout[i], yout[i]) + call ct_free (ctout) + + # Print the input and output pixel coordinates. + do i = 1, npts { + call printf ("%10.3f %10.3f %10.3f %10.3f\n") + call pargd (xref[i]) + call pargd (yref[i]) + call pargd (xout[i]) + call pargd (yout[i]) + } + + # Tidy up. + call mw_close (mwref) + call mw_close (mwout) + call sk_close (refcoo) + call sk_close (outcoo) + + +Example 4: Convert a 2D image with an J2000 tangent plane projection + wcs to the equivalent galactic wcs. The transformation + requires a shift in origin and a rotation. Assume that the ra + axis is 1 and the dec axis is 2. The details of how to compute + the rotation are not shown here. See the imcctran task for details. + + include <mwset.h> + include <skywcs.h> + + ... + + # Open image. + im = immap (image, READ_WRITE, 0) + + # Open the image coordinate system. + instat = sk_decim (im, "logical", mwin, cooin) + if (instat == ERR || mwin == NULL) { + ... + call sk_close (cooin) + ... + } + + # Get the dimensions of the mwcs descriptor. This should be 2. + ndim = mw_ndim (mwin, MW_NPHYSDIM) + + # Get the default coordinates to degrees and degreees. + call sk_seti (cooin, S_NLNGUNITS, SKY_DEGREES) + call sk_seti (cooin, S_NATGUNITS, SKY_DEGREES) + + # Open the output coordinate system. Mwout is NULL because this system + # is not an image. + outstat = sk_decwstr ("galactic", mwout, cooout, cooin) + if (outstat == ERR) { + ... + call sk_close (outstat) + ... + } + + # Make a copy of the mwcs descriptor. + mwout = mw_newcopy (mwin) + + # Allocate space for the r and w vectors and cd matrix. + call malloc (r, ndim, TY_DOUBLE) + call malloc (w, ndim, TY_DOUBLE) + call malloc (cd, ndim * ndim, TY_DOUBLE) + call malloc (newcd, ndim * ndim, TY_DOUBLE) + + # Assume for simplicty that the MWCS LTERM is the identify transform. + # so we don't have to worry about it. Get the WTERM which consists + # of r the reference point in pixels, w the reference point in degrees, + # and the cd matrix in degrees per pixel. + call mw_gwtermd (mwin, Memd[r], Memd[w], Memd[cd], ndim) + + # Convert the world coordinates zero point. The pixel zero point + # remains the same. + tilng = Memd[w] + tilat = Memd[w+1] + call sk_ultran (incoo, outcoo, tilng, tilat, tolng, tolat, 1) + Memd[w] = tolng + Memd[w+1] = tolat + + # Figure out how much to rotate the coordinate system and edit the + # compute a new CD matrix. Call it newcd. + ... + + # Enter the new CD matrix and zero point. + call mw_swterm (mwout, Memd[r], Memd[w], Memd[newcd], ndim) + + # Update the header. + call sk_saveim (cooout, mwout, im) + call mw_saveim (mwout, im) + ... + + # Tidy up. + call mfree (r, TY_DOUBLE) + call mfree (w, TY_DOUBLE) + call mfree (cd, TY_DOUBLE) + call mfree (newcd, TY_DOUBLE) + call mw_close (mwin) + call mw_close (mwout) + call sk_close (cooin) + call sk_close (cooout) + call imunmap (im) +.fi +.endhelp diff --git a/pkg/xtools/skywcs/doc/skywcs.men b/pkg/xtools/skywcs/doc/skywcs.men new file mode 100644 index 00000000..7502bcd0 --- /dev/null +++ b/pkg/xtools/skywcs/doc/skywcs.men @@ -0,0 +1,15 @@ + skdecwcs - Open a sky coordinate descriptor using an image or system name + skdecwstr - Open a sky coordinate descriptor using a system name + skdecim - Open a sky coordinate descriptor using an image descriptor + skenwcs - Encode a system name using a sky coordinate descriptor + skcopy - Copy a sky coordinate descriptor + skstat[ids] - Get a sky coordinate descriptor parameter value + skset[ids] - Set a sky coordinate descriptor parameter value + skiiprint - Print a sky coordinate descriptor summary + skiiwrite - Write a sky coordinate descriptor summary + skultran - Transform between coordinate systems + sklltran - Apply pm and transform between coordinates systems +skequatorial - Apply pm and transform between equatorial coordinate systems + sksaveim - Update image header using sky coordinate descriptor + skclose - Close the sky coordinate descriptor + ccsystems - Describe the supported celestial coordinate systems |